Cut v0.77.0 — pi 0.76.0→0.77.0

First container build on pi 0.77 line (published upstream 2026-05-28).
Built against unchanged joakimp/opencode-devbox:base-latest (same as
v0.76.0 — SSH-CM, gitleaks, git-crypt all carry forward).

Notable pi 0.77.0 upstream:
- Claude Opus 4.8 support
- --exclude-tools / -xt for selective tool disablement
- Headless Codex subscription login (device-code auth)
- Streaming-aware extension input (InputEvent.streamingBehavior)
- Long bugfix list (startup timing, signal handling, terminal
  protocol detection, Windows MSYS2 fixes, provider metadata
  cleanups, session disposal abort, etc).

Also folds the previously-Unreleased CI retry-wrapper change
(2d39766) into this release block. Second publish exercising the
cache-export-disabled workflow; first to exercise the 3-attempt
retry wrapper through the publish path.

See CHANGELOG v0.77.0 for full notes.

.gitea/workflows/docker-publish.yml

@@ -33,6 +33,23 @@ jobs:
       - uses: docker/setup-buildx-action@v4
         with: {driver-opts: network=host}
 
+      # Derive PI_VERSION from the tag (e.g. v0.75.5 -> 0.75.5; v0.75.5b -> 0.75.5).
+      # MUST be passed as a build-arg so Docker's layer cache invalidates when pi
+      # is bumped. Without this, the bare `npm install -g <pkg>` in the Dockerfile
+      # produces an identical layer-hash across builds and the registry buildcache
+      # silently reuses the layer from whatever pi version was current when the
+      # cache was first populated. Discovered 2026-05-23 — every pi-devbox release
+      # since v0.74.0 had been shipping the same image bytes (manifest digests
+      # identical across v0.74.0..v0.75.5 on both arches).
+      - name: Resolve PI_VERSION from tag
+        id: resolve
+        run: |
+          TAG="${{ github.ref_name }}"
+          PI_VERSION="${TAG#v}"
+          PI_VERSION=$(echo "$PI_VERSION" | sed 's/[a-z]*$//')
+          echo "pi_version=${PI_VERSION}" >> "$GITHUB_OUTPUT"
+          echo "Resolved PI_VERSION=${PI_VERSION} from tag ${TAG}"
+
       - name: Build (amd64, load to local daemon)
         uses: docker/build-push-action@v7
         with:
@@ -41,8 +58,12 @@ jobs:
           push: false
           load: true
           tags: pi-devbox:smoke
+          build-args: |
+            PI_VERSION=${{ steps.resolve.outputs.pi_version }}
 
       - name: Smoke test
+        env:
+          EXPECTED_PI_VERSION: ${{ steps.resolve.outputs.pi_version }}
         run: bash scripts/smoke-test.sh pi-devbox:smoke
 
   publish:
@@ -81,15 +102,60 @@ jobs:
             echo "EOF"
           } >> "$GITHUB_OUTPUT"
 
-      - name: Build and push (amd64 + arm64)
-        uses: docker/build-push-action@v7
-        with:
-          context: .
-          platforms: linux/amd64,linux/arm64
-          push: true
-          tags: ${{ steps.tags.outputs.tags }}
-          cache-from: type=registry,ref=${{ env.IMAGE }}:buildcache
-          cache-to: type=registry,ref=${{ env.IMAGE }}:buildcache,mode=max
+      # See the smoke job for why this is required (cache-hit silent regression).
+      - name: Resolve PI_VERSION from tag
+        id: resolve
+        run: |
+          TAG="${{ github.ref_name }}"
+          PI_VERSION="${TAG#v}"
+          PI_VERSION=$(echo "$PI_VERSION" | sed 's/[a-z]*$//')
+          echo "pi_version=${PI_VERSION}" >> "$GITHUB_OUTPUT"
+          echo "Resolved PI_VERSION=${PI_VERSION} from tag ${TAG}"
+
+      - name: Build and push (amd64 + arm64) — with retry
+        shell: bash
+        env:
+          PI_VERSION: ${{ steps.resolve.outputs.pi_version }}
+          TAGS: ${{ steps.tags.outputs.tags }}
+        run: |
+          set -euo pipefail
+          # Convert newline-delimited TAGS env var (build-push-action's native
+          # format from the `Compute tags` step) into a bash array of -t flags.
+          TAG_FLAGS=()
+          while IFS= read -r t; do [[ -n "$t" ]] && TAG_FLAGS+=( -t "$t" ); done <<< "${TAGS}"
+          # 3-attempt retry around `docker buildx build --push` for transient
+          # registry-1.docker.io blips (rate limits, CDN flap, brief 5xx).
+          # Does NOT mask deterministic failures: a true regression (e.g. the
+          # cache-export 400 hit 2026-05-23..28) will fail all 3 attempts
+          # identically and the job still fails — by design.
+          # Registry cache disabled: buildkit's mode=max cache-export to
+          # registry-1.docker.io reproducibly returns HTTP 400 on resumable-
+          # upload PUT (Hub-CDN protocol mismatch with buildx 0.34.x, surfaced
+          # ~2026-05-23). Diagnosed during opencode-devbox v1.15.12 manual
+          # publish: image push works fine, only --cache-to fails. See
+          # opencode-devbox CHANGELOG v1.15.12 Unreleased section for full
+          # root-cause analysis. Re-enable when buildkit upstream resolves.
+          # Single-stage Dockerfile + tiny diff (npm install pi only) means
+          # build is fast even without cache (~30-60s).
+          for attempt in 1 2 3; do
+            echo "==> Build+push attempt ${attempt}/3"
+            if docker buildx build \
+                --platform linux/amd64,linux/arm64 \
+                --push \
+                --build-arg "PI_VERSION=${PI_VERSION}" \
+                "${TAG_FLAGS[@]}" \
+                .; then
+              echo "==> Attempt ${attempt} succeeded"
+              exit 0
+            fi
+            if [[ "${attempt}" -lt 3 ]]; then
+              backoff=$(( attempt * 15 ))
+              echo "==> Attempt ${attempt} failed, sleeping ${backoff}s before retry"
+              sleep "${backoff}"
+            fi
+          done
+          echo "==> All 3 build+push attempts failed"
+          exit 1
 
   update-description:
     needs: publish

AGENTS.md

@@ -23,6 +23,19 @@ Container image that adds pi coding-agent on top of the opencode-devbox base ima
 3. Add fresh `## Unreleased` section
 4. Commit, tag `vX.Y.Z`, push tag → CI fires automatically
 
+When drafting CHANGELOG entries, pull pi's release notes from the
+`CHANGELOG.md` shipped inside the npm tarball:
+
+```bash
+cd /tmp && npm pack @earendil-works/pi-coding-agent@<version>
+tar -xzf earendil-works-pi-coding-agent-<version>.tgz package/CHANGELOG.md
+head -40 package/CHANGELOG.md
+```
+
+Pi's CHANGELOG has rich New Features / Added / Changed / Fixed sections
+per version. Don't try to derive notes from the npm registry metadata
+(`npm view`) — it doesn't include the changelog body.
+
 ## Key facts
 
 - **Base image**: `joakimp/opencode-devbox:base-latest` — rebuilt whenever opencode-devbox cuts a new base
@@ -35,3 +48,17 @@ Container image that adds pi coding-agent on top of the opencode-devbox base ima
 - Do NOT call `mempalace-toolkit/install.sh` in the Dockerfile — the base entrypoint handles it
 - `NPM_CONFIG_PREFIX=/usr` must be set per-RUN for any build-time `npm install -g` to keep baked binaries off the volume-shadowed path
 - The smoke test threshold is 2200 MB — update if the image legitimately grows past it
+- **PI_VERSION must be passed explicitly by CI as a concrete version** (derived from the git tag), not left as the `latest` default. The Dockerfile's bare `npm install -g @earendil-works/pi-coding-agent` (without `@${PI_VERSION}`) produces an identical layer-hash across builds; combined with registry buildcache (`cache-from`/`cache-to`) the layer gets reused even when `latest` would have resolved to a newer pi version. **All releases v0.74.0 → v0.75.5 silently shipped the same image bytes** because of this (verified via `docker manifest inspect` — identical digests across both arches and all four tags). Fixed in v0.75.5b: workflow now derives `PI_VERSION` from `${{ github.ref_name }}` and passes it as a build-arg; smoke-test asserts the resulting `pi --version` matches via `EXPECTED_PI_VERSION` env var. Same latent bug exists in opencode-devbox's `with-pi` variants but is masked there because `OPENCODE_VERSION` bumps invalidate downstream layers — will only manifest when cutting a `vN.N.Nb`-style opencode-version-unchanged release that only bumps pi.
+
+## Documentation drift sweep
+
+Before committing any non-trivial change, check that prose still matches code. Drift hotspots in this repo:
+
+- `README.md` — quick-start examples, env-var table, base-image reference (must match `FROM` in `Dockerfile`).
+- `AGENTS.md` (this file) — `Key facts` block (pi binary path, `NPM_CONFIG_PREFIX`, base-image tag), smoke-test threshold number.
+- `CHANGELOG.md` — promote `Unreleased` only on tag, but record post-release fixes in a fresh `Unreleased` block.
+- `DOCKER_HUB.md` — hand-maintained slim Hub description; sync anything user-facing that changes (env vars, run command, base image).
+- `.env.example` — hand-updated, must match Dockerfile/entrypoint env vars.
+- `Dockerfile` `PI_VERSION` ARG default — if you intend to pin (rather than `latest`), bump it on release.
+
+Quick triage: `git diff --name-only HEAD | xargs -I{} grep -l 'thing-you-changed' README.md AGENTS.md DOCKER_HUB.md CHANGELOG.md .env.example`.

CHANGELOG.md

@@ -8,6 +8,105 @@ Tags follow the pi npm version: `v{pi_version}[letter]` — bare tag for the fir
 
 ## Unreleased
 
+_(no changes since v0.77.0)_
+
+## v0.77.0 — 2026-05-29
+
+pi `0.76.0` → `0.77.0` bump (first container build on the pi 0.77 line, published upstream 2026-05-28). Built against `joakimp/opencode-devbox:base-latest` (unchanged from the v0.76.0 build — same SSH-CM, gitleaks, git-crypt baked in).
+
+### Bumped: pi 0.76.0 → 0.77.0
+
+Notable upstream changes (from pi's CHANGELOG):
+
+- **Claude Opus 4.8 support** — Anthropic Opus 4.8 model metadata + adaptive-thinking coverage updated.
+- **Selective tool disablement** — `--exclude-tools` / `-xt` disables specific built-in, extension, or custom tools while leaving the rest available.
+- **Headless Codex subscription login** — `/login` can use device-code auth for ChatGPT Plus/Pro Codex subscriptions; browser login remains the default.
+- **Streaming-aware extension input** — `InputEvent.streamingBehavior` lets extensions distinguish idle prompts from mid-stream steers and queued follow-ups.
+- **Bugfixes** — startup timing output excludes `createAgentSessionRuntime` work; OpenRouter DeepSeek V4 `xhigh` reasoning preserves OpenRouter's native effort; SIGTERM/SIGHUP exits run extension `session_shutdown` cleanup; keyboard protocol negotiation ignores delayed terminal responses (no false Kitty detection); Windows MSYS2 ucrt64 startup crash fixed via napi-rs 3.x clipboard addon; API-key/header config resolution treats plain strings as literals with `$ENV_VAR` / `${ENV_VAR}` interpolation and `$!` escaping; session disposal aborts in-flight agent/compaction/branch-summary/retry/bash work; `pi.getAllTools()` exposes per-tool `promptGuidelines`; OpenAI Codex Responses replay after switching from Anthropic extended-thinking sessions; Anthropic-compatible replay supports `allowEmptySignature` for providers returning empty thinking signatures; OpenAI/OpenRouter GPT-5.5 Pro thinking levels limited to supported efforts; OpenCode Go Kimi K2.6 thinking-off requests; Xiaomi Token Plan model metadata cleaned of unsupported variants; follow-up messages queued by `agent_end` extension handlers drain before idle; system prompt tool-selection guidance avoids unavailable file-exploration tools; fenced `diff` highlighting restored.
+
+Workflow continues to derive `PI_VERSION` from the git tag (`v0.77.0` → `0.77.0`) and pass it as a build-arg per the v0.75.5b cache-hit fix; smoke test asserts `pi --version` matches.
+
+### Inheritance from base
+
+No base change in `joakimp/opencode-devbox:base-latest` since v0.76.0 — the v1.15.12 opencode-devbox release also reused the unchanged base. SSH ControlMaster on a writable socket path, gitleaks, and git-crypt continue to ride along from the base.
+
+### CI
+
+This is the second pi-devbox release exercising the cache-export-disabled workflow (after v0.76.0's clean publish on run #340) and the first to also exercise the 3-attempt retry wrapper added in 2d39766 along the publish path.
+
+## v0.76.0 — 2026-05-28
+
+pi `0.75.5` → `0.76.0` bump (first minor-version release on pi 0.76 line, published upstream 2026-05-27 20:03 UTC). Built against a fresh `joakimp/opencode-devbox:base-latest` which now bakes in SSH ControlMaster on a writable socket path, plus gitleaks and git-crypt — see the inherited-from-base notes below for details on each.
+
+### Bumped: pi 0.75.5 → 0.76.0
+
+Notable upstream changes (from pi's CHANGELOG):
+
+- **Explicit session IDs for automation** — `--session-id <id>` lets scripts create or resume an exact project-local session.
+- **RPC bash output can stay out of model context** — RPC clients can pass `excludeFromContext` to `bash` for commands whose output should not be sent with the next prompt.
+- **More predictable provider retries and timeouts** — Codex WebSocket/SSE waits are bounded; `retry.provider.maxRetries` controls provider retries instead of hidden SDK defaults; SDK retries default to 0; quota/billing 429s are no longer retried behind Pi's retry handling.
+- **Better terminal editing across environments** — Apple Terminal Shift+Enter detection on macOS, Windows Terminal OSC 8 hyperlink support, JetBrains truecolor with disabled OSC 8, Unicode-aware word navigation and deletion.
+- **Bugfixes** — `pi update` bypasses npm/pnpm/Bun minimum-release-age gates; user-authored ordered-list markers preserved in transcripts; image attachment token estimates aligned with tool-result images; Codex Responses cache-affinity header fixed (`session-id` not `session_id`); OpenRouter/Poolside context-overflow detection; managed npm extension updates avoid peer-dependency conflicts; RpcClient handles unexpected child exits cleanly.
+
+Workflow continues to derive `PI_VERSION` from the git tag (`v0.76.0` → `0.76.0`) and pass it as a build-arg, per the v0.75.5b cache-hit fix; smoke test asserts `pi --version` matches.
+
+### Workflow change: registry cache-export disabled
+
+- **`.gitea/workflows/docker-publish.yml`** — `cache-from`/`cache-to` removed from the `publish` step. buildkit's `mode=max` cache-export to `registry-1.docker.io` reproducibly returns HTTP 400 on the resumable-upload PUT, surfacing ~2026-05-23. Diagnosed during opencode-devbox v1.15.12's manual host-side publish: image push works fine, only `--cache-to` fails. See opencode-devbox CHANGELOG v1.15.12 `Unreleased` for the full root-cause analysis. The pi-devbox Dockerfile is single-stage with a tiny diff (npm install pi only) on top of `base-latest`, so builds are fast even without cache (~30-60s expected).
+
+### Inherited from opencode-devbox base: SSH ControlMaster on a writable socket path
+
+No Dockerfile change here — just a note that this release picks up the system-wide SSH ControlMaster default (`/etc/ssh/ssh_config.d/00-devbox-controlmaster.conf` → `ControlPath /tmp/sshcm/%r@%h:%p`, `ControlMaster auto`, `ControlPersist 10m`). This unblocks `ssh` and `pi --ssh user@host` from inside the container when `~/.ssh` is bind-mounted read-only from the host (the standard pi-devbox compose layout) — previously, OpenSSH's default `ControlPath` under `~/.ssh/cm/` was unwritable, so multiplexing failed with `unix_listener: cannot bind ... Read-only file system` and ssh fell back to fresh TCP connections, which on residential CGNAT manifested as banner-exchange timeouts. The fix is purely additive (per-container `/tmp/sshcm` dir, mode 700, created by entrypoint) and user `~/.ssh/config` per-host overrides still win because Debian's stock `ssh_config` sources `ssh_config.d/*.conf` before its own `Host *` block. See opencode-devbox CHANGELOG `v1.15.12` for the base-side details.
+
+### Inherited from opencode-devbox base: gitleaks + git-crypt
+
+No Dockerfile change here — just a note that this release includes `gitleaks` (newly added to the base) and `git-crypt` (was always installed via apt; just wasn't called out). Both are useful inside the container for repos that use a gitleaks pre-commit hook or git-crypt-encrypted canonical config and don't want host-side dependencies. See opencode-devbox CHANGELOG `v1.15.12` for the base-side details.
+
+## v0.75.5b — 2026-05-23
+
+Recovery release fixing a **silent cache-hit regression** discovered in the v0.75.5 image. All four releases v0.74.0 through v0.75.5 had been shipping the same image bytes because the Dockerfile's `npm install -g @earendil-works/pi-coding-agent` (bare, when `PI_VERSION=latest`) produces an identical layer-hash across builds. Combined with the registry buildcache, Docker reused the layer from whatever pi version was current when the cache was first populated.
+
+Verification: `docker manifest inspect joakimp/pi-devbox:vX.Y.Z` showed identical SHA256 digests on both `linux/amd64` and `linux/arm64` for v0.74.0, v0.75.3, v0.75.4, v0.75.5. Users on `:latest` were getting whatever pi version was baked into the v0.74.0 build (probably 0.74.0 itself).
+
+- **Workflow fix:** Both `smoke` and `publish` jobs now derive `PI_VERSION` from `github.ref_name` (e.g. `v0.75.5b` → `0.75.5`) and pass it as a build-arg. The Dockerfile's existing `if PI_VERSION=latest` branch never fires in CI now — always takes the `@${PI_VERSION}` branch — so the layer-hash includes the version and cache invalidates correctly.
+- **Smoke test:** New `run_expect` helper asserts `pi --version` output contains `EXPECTED_PI_VERSION` (passed from the resolve step). Would have caught this regression on v0.75.3 if it had existed.
+- **Dockerfile:** Comment added above `ARG PI_VERSION=latest` documenting the cache-hit footgun and pointing at the workflow's resolve step + AGENTS.md gotcha.
+- **AGENTS.md:** New convention bullet explaining the cache-hit class of bug and noting the latent same-bug in opencode-devbox's `with-pi` variants (currently masked by OPENCODE_VERSION bumps).
+
+No image-side changes vs v0.75.5 *intent* — this build will produce the actual pi 0.75.5 image content that v0.75.5 was supposed to ship.
+
+## v0.75.5 — 2026-05-23
+
+pi `0.75.4` → `0.75.5` bump (one upstream patch release, two days after v0.75.4).
+
+Notable upstream changes (from pi's CHANGELOG):
+
+- Cleaner read tool output (collapsed cards show only the read line; Ctrl+O expands).
+- Faster file tools on Windows (async fs ops during streaming, image resize off the main TUI thread).
+- More reliable package updates (`pi update` reconciles git-pinned refs without losing settings).
+- Custom Anthropic-compatible adaptive thinking via `compat.forceAdaptiveThinking`.
+- Several bash/read tool card display fixes; macOS Bun clipboard sidecar resolution; per-session OpenCode-Zen routing headers; Amazon Bedrock token cap fix.
+
+Plus a new pi 0.74.2 rescue release advising Node 20 users to upgrade Node before going to newer Pi versions — the devbox base image runs newer Node so this doesn't affect us, but worth noting for users running pi outside the devbox.
+
+- **Bump:** pi `@earendil-works/pi-coding-agent@0.75.5` baked at `/usr/bin/pi` (via `PI_VERSION=latest` resolving to 0.75.5 at build time — no Dockerfile change needed).
+- No image-side changes from v0.75.4 beyond the pi npm version. Built on `joakimp/opencode-devbox:base-latest` which itself is unchanged (cache-hit on `base-35ee5fe7861a` since v1.14.50b).
+
+## v0.75.4 — 2026-05-21
+
+pi `0.75.3` → `0.75.4` bump (one upstream patch release). Plus the AGENTS.md documentation-drift sweep clause that landed on `main` between v0.75.3 and now.
+
+- **Bump:** pi `@earendil-works/pi-coding-agent@0.75.4` baked at `/usr/bin/pi` (via `PI_VERSION=latest` resolving to 0.75.4 at build time — no Dockerfile change needed).
+- **AGENTS.md:** documentation drift sweep as explicit pre-commit workflow step (commit `ae6253a`). Companion clause added across the wider repo set the same day.
+- No image-side changes beyond the pi npm version. Built on `joakimp/opencode-devbox:base-latest` which itself is unchanged (cache-hit on `base-35ee5fe7861a` since v1.14.50b).
+
+## v0.75.3 — 2026-05-18
+
+pi `0.74.0` → `0.75.3` bump (one upstream minor + three patch releases since the initial pi-devbox release on 2026-05-14).
+
+- **Bump:** pi `@earendil-works/pi-coding-agent@0.75.3` baked at `/usr/bin/pi` (via `PI_VERSION=latest` resolving to 0.75.3 at build time).
+- No image-side changes from the v0.74.0 baseline beyond the pi npm version. The pi-toolkit + pi-extensions clones, mempalace bridge symlink, and `NPM_CONFIG_PREFIX` named-volume setup all unchanged.
+
 ## v0.74.0 — 2026-05-14
 
 Initial release.

DOCKER_HUB.md

@@ -1 +1,99 @@
-pi coding-agent container — built on opencode-devbox base. Includes pi, pi-toolkit, pi-extensions, mempalace, AWS CLI, neovim, and full dev toolchain. See https://gitea.jordbo.se/joakimp/pi-devbox for full docs.
+# pi-devbox
+
+A Docker container with [pi coding-agent](https://github.com/earendil-works/pi) pre-installed, built on top of [opencode-devbox](https://hub.docker.com/r/joakimp/opencode-devbox)'s base image. Pi gets a fully-loaded development environment in one `docker run`.
+
+## Image variants
+
+| Tag | Size (compressed) | What you get |
+|---|---|---|
+| `joakimp/pi-devbox:latest` | ~700 MB | Pi + companion repos, on top of the opencode-devbox base |
+| `joakimp/pi-devbox:vX.Y.Z` | same | Pinned pi version (tracks the [pi npm package version](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)) |
+
+Multi-arch: `linux/amd64`, `linux/arm64`.
+
+## Quick start
+
+One-shot, no persistence:
+
+```bash
+docker run -it --rm \
+  -v "$PWD":/workspace \
+  -v "$HOME/.ssh":/home/developer/.ssh:ro \
+  -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
+  joakimp/pi-devbox:latest pi
+```
+
+For a fully-configured environment with persistent settings, MemPalace memory, neovim plugins, and shell history surviving container recreation, use docker-compose. **You don't need to clone the repo** — just grab two template files:
+
+```bash
+mkdir -p ~/pi-devbox && cd ~/pi-devbox
+curl -O https://gitea.jordbo.se/joakimp/pi-devbox/raw/branch/main/docker-compose.yml
+curl -fsSL https://gitea.jordbo.se/joakimp/pi-devbox/raw/branch/main/.env.example -o .env
+# Edit .env — set WORKSPACE_PATH, an LLM API key (ANTHROPIC_API_KEY,
+# OPENAI_API_KEY, GEMINI_API_KEY, or AWS_*), and your git identity.
+docker compose run --rm devbox pi
+```
+
+Full setup guide — authentication for each provider (Anthropic, OpenAI, Gemini, AWS Bedrock SSO + static), persistence model, configuration reference, build args, troubleshooting: **<https://gitea.jordbo.se/joakimp/pi-devbox#readme>**
+
+## What's inside
+
+Inherited from [opencode-devbox base](https://hub.docker.com/r/joakimp/opencode-devbox):
+
+- **Debian trixie** (latest stable)
+- **Node.js** (LTS), **uv** (Python tooling), **rustup** (Rust on-demand)
+- **AWS CLI v2** + AWS Bedrock-ready config
+- **MemPalace** + MCP server — persistent agent memory across sessions, queryable via `mempalace_*` tools inside pi
+- **Gitea MCP** server
+- **Dev tools**: neovim (LazyVim defaults), tmux, bat, eza, fzf, zoxide, ripgrep, git-lfs, make
+- **Shell**: bash with history tuning, prefix-search bindings, fzf/zoxide integration
+
+Added by pi-devbox:
+
+- **pi** ([`@earendil-works/pi-coding-agent`](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)) — baked at `/usr/bin/pi`, version pinned at build time via the `PI_VERSION` build-arg
+- **[pi-toolkit](https://gitea.jordbo.se/joakimp/pi-toolkit)** — keybindings (mosh/tmux-friendly Shift+Enter, Ctrl+J, Alt+J newline bindings), AWS env loader, settings template
+- **[pi-extensions](https://gitea.jordbo.se/joakimp/pi-extensions)** — 7 user-facing extensions: `ext-toggle` (manage extensions interactively), `mcp-loader` (load MCP servers via settings.json), `todo`, `ssh-controlmaster`, `notify`, `git-checkpoint`, `confirm-destructive`
+- **mempalace bridge** — MCP extension auto-symlinked from `/opt/mempalace-toolkit` so pi can read/write the same palace as opencode
+
+The entrypoint deploys all of these on first container start. Re-running is idempotent and preserves user edits.
+
+## Versioning
+
+Tags follow the pi npm version: `v0.74.0`, `v0.75.0`, etc. `latest` always points at the most recent release. When pi cuts a new upstream version, this image is rebuilt and re-tagged to match.
+
+For container-level rebuilds on the same pi version (security updates, base bumps, fixes) the tag gets a letter suffix: `v0.74.0b`, `v0.74.0c`, …
+
+## Persistent state
+
+User edits and pi-installed packages survive container recreation when you mount these named volumes. Use the included `docker-compose.yml` and they're set up automatically.
+
+| Volume | Mount point | What it holds |
+|---|---|---|
+| `devbox-pi-config` | `/home/developer/.pi/` | pi settings, extension toggles, sessions, user-installed pi packages (`npm install -g`, `pi install npm:…`) |
+| `devbox-shell-history` | `/home/developer/.cache/bash` | bash history |
+| `devbox-zoxide` | `/home/developer/.local/share/zoxide` | zoxide directory jump database |
+| `devbox-nvim-data` | `/home/developer/.local/share/nvim` | neovim plugin & Mason package state |
+| `devbox-uv` | `/home/developer/.local/share/uv` | uv Python installs and tool cache |
+
+Optional volumes for MemPalace (commented out by default — uncomment in `docker-compose.yml` to persist conversation memory across restarts):
+
+| Volume | Mount point | What it holds |
+|---|---|---|
+| `devbox-palace` | `/home/developer/.mempalace` | palace data (drawers, knowledge graph, embeddings) |
+| `devbox-chroma-cache` | `/home/developer/.cache/chroma` | ChromaDB embedding model cache (~80 MB, can be rebuilt) |
+
+## User-installed pi packages
+
+`NPM_CONFIG_PREFIX` is set inside the container to `/home/developer/.pi/npm-global`. Anything you `pi install npm:<pkg>` or `npm install -g` lands on the `devbox-pi-config` named volume — survives container recreation **and** image rebuilds. A user-installed `pi` wins over the baked one via `PATH` order, so you can pin a different pi version without rebuilding the image.
+
+## Source
+
+- **This image**: https://gitea.jordbo.se/joakimp/pi-devbox
+- **Base image**: https://gitea.jordbo.se/joakimp/opencode-devbox (Hub: `joakimp/opencode-devbox`)
+- **pi**: https://github.com/earendil-works/pi
+- **pi-toolkit**: https://gitea.jordbo.se/joakimp/pi-toolkit
+- **pi-extensions**: https://gitea.jordbo.se/joakimp/pi-extensions
+
+## License
+
+MIT (the image; pi and the bundled tools each carry their own licenses).

Dockerfile

@@ -2,7 +2,8 @@
 #
 # Builds on top of the opencode-devbox base image, which provides:
 #   Debian trixie, Node.js, AWS CLI, mempalace + MCP server, gitea-mcp,
-#   dev tools (neovim, tmux, bat, eza, fzf, zoxide, ripgrep, uv, rustup),
+#   dev tools (neovim, tmux, bat, eza, fzf, zoxide, ripgrep, uv, rustup,
+#   git-crypt, gitleaks),
 #   user setup (developer/gosu), entrypoints, chromadb prewarm.
 #
 # This image adds only pi itself and its companion repos.
@@ -16,6 +17,13 @@
 ARG BASE_IMAGE=joakimp/opencode-devbox:base-latest
 FROM ${BASE_IMAGE}
 
+# PI_VERSION should be passed explicitly by CI as a concrete version
+# (e.g. PI_VERSION=0.75.5, derived from the git tag). The default `latest`
+# is for local dev convenience only — it has a known cache-hit footgun
+# when used in registry-cached CI builds. See .gitea/workflows/docker-
+# publish.yml § "Resolve PI_VERSION from tag" and AGENTS.md gotcha for
+# the full story (silent same-bytes-across-releases regression discovered
+# 2026-05-23 affecting all builds v0.74.0..v0.75.5).
 ARG PI_VERSION=latest
 ARG PI_TOOLKIT_REF=main
 ARG PI_EXTENSIONS_REF=main

README.md

@@ -1,58 +1,259 @@
 # pi-devbox
 
-A Docker container image with [pi coding-agent](https://github.com/earendil-works/pi) pre-installed, built on the [opencode-devbox](https://gitea.jordbo.se/joakimp/opencode-devbox) base image.
+A Docker container with [pi coding-agent](https://github.com/earendil-works/pi) pre-installed, built on the [opencode-devbox](https://gitea.jordbo.se/joakimp/opencode-devbox) base image. Persistent state, full dev toolchain, MemPalace memory, and provider-agnostic LLM auth — in one `docker compose run`.
+
+> **Hub:** [`joakimp/pi-devbox`](https://hub.docker.com/r/joakimp/pi-devbox) · multi-arch (amd64 + arm64)
+> **Source:** [gitea.jordbo.se/joakimp/pi-devbox](https://gitea.jordbo.se/joakimp/pi-devbox)
+
+---
 
 ## What's inside
 
-Built on `opencode-devbox:base-latest`, which provides:
+Inherited from `opencode-devbox:base-latest`:
 
-- **Debian trixie** (stable base)
+- **Debian trixie** (current stable)
 - **Node.js** (LTS), **uv** (Python), **rustup** (Rust on-demand)
-- **AWS CLI** v2
-- **MemPalace** + MCP server (persistent agent memory across sessions)
+- **AWS CLI v2** (with Bedrock support)
+- **MemPalace** + MCP server — persistent agent memory across sessions; queryable via `mempalace_*` tools inside pi
 - **Gitea MCP** server
-- **Dev tools**: neovim (LazyVim), tmux, bat, eza, fzf, zoxide, ripgrep, git-lfs, make
+- **Dev tools**: neovim (LazyVim), tmux, bat, eza, fzf, zoxide, ripgrep, jq, git-lfs, make
 - **Shell**: bash with history tuning, prefix-search, fzf/zoxide integration
 
-This image adds:
+Added by pi-devbox:
 
-- **pi** (`@earendil-works/pi-coding-agent`) — baked at `/usr/bin/pi`
-- **pi-toolkit** — keybindings, env loader, settings template (cloned to `/opt/pi-toolkit`)
-- **pi-extensions** — ext-toggle, todo, ssh-controlmaster, notify, git-checkpoint, mcp-loader, confirm-destructive (cloned to `/opt/pi-extensions`)
-- **mempalace bridge** — `mempalace.ts` extension symlinked from `/opt/mempalace-toolkit`
+- **pi** ([`@earendil-works/pi-coding-agent`](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)) — baked at `/usr/bin/pi`, version pinned at build time
+- **[pi-toolkit](https://gitea.jordbo.se/joakimp/pi-toolkit)** — mosh/tmux-friendly keybindings (Shift+Enter, Ctrl+J, Alt+J newline), AWS env loader, settings template
+- **[pi-extensions](https://gitea.jordbo.se/joakimp/pi-extensions)** — 7 extensions: `ext-toggle`, `mcp-loader`, `todo`, `ssh-controlmaster`, `notify`, `git-checkpoint`, `confirm-destructive`
+- **mempalace bridge** — auto-symlinked MCP extension so pi reads/writes the same palace as opencode
 
-## Quick start
+The entrypoint deploys all of these on first container start. Idempotent and preserves user edits.
+
+---
+
+## Quick start (no git clone)
+
+If you just want to run pi-devbox and don't plan to modify the source, grab the two template files and go:
 
 ```bash
-cp .env.example .env
-# edit .env — set WORKSPACE_PATH, GIT_USER_NAME, GIT_USER_EMAIL
-docker compose run --rm devbox
-# inside the container:
-pi
+mkdir -p ~/pi-devbox && cd ~/pi-devbox
+
+# Pull the docker-compose.yml and .env template
+curl -O https://gitea.jordbo.se/joakimp/pi-devbox/raw/branch/main/docker-compose.yml
+curl -fsSL https://gitea.jordbo.se/joakimp/pi-devbox/raw/branch/main/.env.example -o .env
+
+# Edit .env — at minimum set WORKSPACE_PATH, an LLM API key, and your git identity
+$EDITOR .env
+
+# Pull and run pi
+docker compose run --rm devbox pi
 ```
 
+`docker compose run --rm devbox` (no command) drops you into bash; you can then run `pi`, `aws sso login`, etc. manually.
+
+To attach a second terminal to the same container (e.g. shell while pi is running):
+
+```bash
+docker compose exec -u developer devbox bash
+```
+
+---
+
+## Quick start (with git clone)
+
+If you want to follow upstream changes, run a customized fork, or rebuild the image yourself:
+
+```bash
+git clone https://gitea.jordbo.se/joakimp/pi-devbox
+cd pi-devbox
+cp .env.example .env
+$EDITOR .env
+docker compose run --rm devbox pi
+```
+
+---
+
+## Authentication
+
+pi reads provider credentials from environment variables, which the container picks up from `.env` automatically.
+
+### Anthropic (Claude)
+
+```ini
+ANTHROPIC_API_KEY=sk-ant-...
+```
+
+Generate a key at <https://console.anthropic.com/settings/keys>.
+
+### OpenAI
+
+```ini
+OPENAI_API_KEY=sk-...
+```
+
+### Google Gemini
+
+```ini
+GEMINI_API_KEY=...
+```
+
+### AWS Bedrock (e.g. Claude on Bedrock)
+
+Two paths — pick one:
+
+**A) Static credentials** (simplest, lower-trust environments only):
+
+```ini
+AWS_REGION=eu-west-1
+AWS_ACCESS_KEY_ID=AKIA...
+AWS_SECRET_ACCESS_KEY=...
+```
+
+**B) AWS SSO** (recommended for corporate AWS, requires mounting `~/.aws`):
+
+```ini
+AWS_REGION=eu-west-1
+AWS_PROFILE=your-profile
+```
+
+Then in your `docker-compose.yml`, uncomment the `~/.aws` bind-mount:
+
+```yaml
+volumes:
+  - ~/.aws:/home/developer/.aws
+```
+
+Inside the container, run `aws sso login` once per session. The token cache lives on the bind-mount, so subsequent `pi` invocations pick it up automatically. The pi-toolkit's `pi-env.zsh` (deployed to `~/.config/pi/`) auto-sources `AWS_PROFILE`/`AWS_REGION` whenever a shell starts.
+
+### First-run pi configuration
+
+On first start, pi reads `~/.pi/agent/settings.json` (auto-bootstrapped from the pi-toolkit template). Edit it inside the container to pick a default provider/model:
+
+```bash
+docker compose exec -u developer devbox bash
+$EDITOR ~/.pi/agent/settings.json
+```
+
+The file is rewritten by pi at runtime (e.g. `lastChangelogVersion`), so it lives on the `devbox-pi-config` named volume — your edits persist across container recreation.
+
+For pi's full configuration model (provider list, model overrides, MCP integration, themes, extensions): <https://github.com/earendil-works/pi#configuration>.
+
+---
+
+## Persistent state
+
+Persistent state is what makes the difference between "use this once" and "make it my long-term coding environment". Everything important survives `docker compose down` and image upgrades; only `docker compose down -v` wipes the volumes.
+
+| Volume | Mount point | What survives | Notes |
+|---|---|---|---|
+| `devbox-pi-config` | `/home/developer/.pi/` | pi settings.json, extension toggles, sessions, user-installed pi packages | `NPM_CONFIG_PREFIX` set inside the container so `pi install npm:…` and `npm install -g` lands here automatically |
+| `devbox-shell-history` | `/home/developer/.cache/bash` | bash history | Across container recreate |
+| `devbox-zoxide` | `/home/developer/.local/share/zoxide` | zoxide directory jump history | The `z`/`zi` shortcuts remember where you've been |
+| `devbox-nvim-data` | `/home/developer/.local/share/nvim` | neovim plugin & Mason package state | LazyVim plugins persist |
+| `devbox-uv` | `/home/developer/.local/share/uv` | uv-managed Python installs and tool cache | `uv tool install` results live here |
+
+### Optional persistent volumes
+
+These are commented out in `docker-compose.yml` by default. Uncomment them if you want the corresponding state to persist:
+
+| Volume | Mount point | What survives |
+|---|---|---|
+| `devbox-palace` | `/home/developer/.mempalace` | MemPalace data — drawers, knowledge graph, embeddings. Treat as primary storage if you rely on agent memory. |
+| `devbox-chroma-cache` | `/home/developer/.cache/chroma` | ChromaDB embedding model cache (~80 MB; disposable, re-downloads in seconds) |
+
+### Workspace bind mount
+
+`/workspace` is bind-mounted from `WORKSPACE_PATH` on the host (default `~/projects`). Source code never lives inside the container — your editor on the host and pi inside the container see the same files.
+
+### SSH keys (read-only)
+
+`~/.ssh` is mounted read-only at `/home/developer/.ssh` for git push/pull. The container does **not** write to it.
+
+---
+
+## Configuration reference
+
+All config flows through `.env`. The full list (with annotations) is in [`.env.example`](https://gitea.jordbo.se/joakimp/pi-devbox/src/branch/main/.env.example). Here's the most relevant subset:
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `WORKSPACE_PATH` | `~/projects` | Host path mounted as `/workspace` |
+| `SSH_KEY_PATH` | `~/.ssh` | Host path for SSH keys (read-only) |
+| `GIT_USER_NAME` | (empty) | Sets `git config --global user.name` inside container |
+| `GIT_USER_EMAIL` | (empty) | Sets `git config --global user.email` inside container |
+| `ANTHROPIC_API_KEY` | (unset) | Anthropic provider auth |
+| `OPENAI_API_KEY` | (unset) | OpenAI provider auth |
+| `GEMINI_API_KEY` | (unset) | Google Gemini auth |
+| `AWS_PROFILE` / `AWS_REGION` | (unset) | AWS Bedrock SSO flow |
+| `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` | (unset) | AWS Bedrock static creds |
+| `GITEA_ACCESS_TOKEN` / `GITEA_HOST` | (unset) | Gitea MCP server (optional) |
+| `GITHUB_PERSONAL_ACCESS_TOKEN` | (unset) | GitHub MCP server / git ops over HTTPS |
+| `LANG` / `LANGUAGE` / `LC_ALL` | `en_US.UTF-8` | Locale override |
+
+---
+
 ## Versioning
 
-Tags follow the pi npm version: `v0.74.0`, `v0.75.0`, etc.
-`latest` always points at the most recent release.
+Tags follow the pi npm package version: `v0.74.0`, `v0.75.0`, … `latest` always points at the most recent successful release.
 
-## Persistence
+Container-level rebuilds on the same pi version (security updates, base bumps, fixes) get a letter suffix: `v0.74.0b`, `v0.74.0c`, …
 
-| Volume | What it holds |
-|--------|---------------|
-| `devbox-pi-config` | pi settings, extensions toggle state, sessions (`~/.pi/`) |
-| `devbox-shell-history` | bash history |
-| `devbox-zoxide` | zoxide directory jump history |
-| `devbox-nvim-data` | neovim plugins, Mason packages |
-| `devbox-uv` | uv Python installs and tool cache |
+When the upstream [pi npm package](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) cuts a new version, this image is rebuilt and re-tagged to match.
 
-## User-installed pi packages
+---
 
-`NPM_CONFIG_PREFIX` is set to `/home/developer/.pi/npm-global`, so any `pi install npm:...` or `npm install -g` as the `developer` user lands on the `devbox-pi-config` volume and survives container recreation and image rebuilds. A user-installed pi wins over the baked binary via `PATH` order.
+## Building from source
 
-## Source
+If you want to pin a specific pi version, change the base image, or hack on the Dockerfile:
 
-- [pi-devbox](https://gitea.jordbo.se/joakimp/pi-devbox) — this repo
-- [opencode-devbox](https://gitea.jordbo.se/joakimp/opencode-devbox) — base image source
-- [pi-toolkit](https://gitea.jordbo.se/joakimp/pi-toolkit)
-- [pi-extensions](https://gitea.jordbo.se/joakimp/pi-extensions)
+```bash
+git clone https://gitea.jordbo.se/joakimp/pi-devbox
+cd pi-devbox
+
+# Edit Dockerfile or override via build args:
+docker compose build \
+  --build-arg PI_VERSION=0.73.0 \
+  --build-arg BASE_IMAGE=joakimp/opencode-devbox:base-latest
+
+docker compose up -d
+```
+
+Build args supported:
+
+| Arg | Default | Effect |
+|---|---|---|
+| `BASE_IMAGE` | `joakimp/opencode-devbox:base-latest` | Parent image — set to `joakimp/opencode-devbox:base-<sha>` for reproducible builds |
+| `PI_VERSION` | `latest` | npm version of `@earendil-works/pi-coding-agent` |
+| `PI_TOOLKIT_REF` | `main` | Git ref for [pi-toolkit](https://gitea.jordbo.se/joakimp/pi-toolkit) |
+| `PI_EXTENSIONS_REF` | `main` | Git ref for [pi-extensions](https://gitea.jordbo.se/joakimp/pi-extensions) |
+
+---
+
+## Troubleshooting
+
+**`pi --version` works but `pi` exits immediately.** First-run config probably hasn't been done. `docker compose exec -u developer devbox bash`, edit `~/.pi/agent/settings.json`, ensure a provider is set and the matching API key is exported.
+
+**AWS SSO token expired.** `aws sso login` from inside the container. The token cache is on the `~/.aws` bind-mount, so it persists; expiration is the issue.
+
+**Anthropic 401 / OpenAI 401.** Check the `.env` value made it in: `docker compose exec devbox env | grep ANTHROPIC` (etc).
+
+**`pi` prompts for an extension/MCP server you don't recognize.** Either toggle it off via `/ext` inside pi, or rename the file: `mv ~/.pi/agent/extensions/<name>.ts{,.off}`.
+
+**Container won't start, error about `/workspace`.** `WORKSPACE_PATH` in `.env` doesn't exist on the host. Create the directory or fix the path.
+
+**Pi-toolkit symlinks lost after `docker compose down -v`.** That's expected — `-v` wipes named volumes. Don't do it unless you mean it. Container recreation without `-v` (the default) preserves all state.
+
+---
+
+## Related
+
+- **[opencode-devbox](https://gitea.jordbo.se/joakimp/opencode-devbox)** — the base image. Use this if you want both opencode and pi (it has a `latest-with-pi` variant) or just opencode.
+- **[pi-toolkit](https://gitea.jordbo.se/joakimp/pi-toolkit)** — keybindings, env loader, settings template. Cloned into `/opt/pi-toolkit` at image build time and `install.sh` runs on container start.
+- **[pi-extensions](https://gitea.jordbo.se/joakimp/pi-extensions)** — extension source. Same install pattern.
+- **[mempalace-toolkit](https://gitea.jordbo.se/joakimp/mempalace-toolkit)** — MemPalace bring-up. The `mempalace.ts` extension symlinked into `~/.pi/agent/extensions/` comes from here.
+- **[pi (upstream)](https://github.com/earendil-works/pi)** — the coding-agent itself.
+
+---
+
+## License
+
+MIT (this image and its source). Pi and the bundled tools each carry their own licenses.

scripts/smoke-test.sh

@@ -28,12 +28,33 @@ run() {
   fi
 }
 
+# Stricter version of `run` that also asserts an expected substring in stdout.
+# Used for catching the "image bytes silently identical to previous release"
+# class of regression (Docker layer cache hit on `npm install -g <pkg>` because
+# the bare command string is identical across builds, even when `latest` would
+# resolve differently). Discovered 2026-05-23 — every pi-devbox release v0.74.0
+# through v0.75.5 had been shipping the same image bytes.
+run_expect() {
+  local label="$1"; local cmd="$2"; local expect="$3"
+  local out
+  out=$(docker run --rm --entrypoint="" "$IMAGE" sh -c "$cmd" 2>&1) || true
+  if echo "$out" | grep -Fq "$expect"; then
+    printf "  ✅  %s (got %s)\n" "$label" "$expect"; PASS=$((PASS+1))
+  else
+    printf "  ❌  %s — expected substring %q, got: %s\n" "$label" "$expect" "$out"; FAIL=$((FAIL+1))
+  fi
+}
+
 echo "=== pi-devbox smoke test: $IMAGE ==="
 echo ""
 
 # ── Basic binary checks ───────────────────────────────────────────────
 echo "── Binaries ──"
-run "pi"              "pi --version"
+if [ -n "${EXPECTED_PI_VERSION:-}" ]; then
+  run_expect "pi version matches build arg" "pi --version" "$EXPECTED_PI_VERSION"
+else
+  run "pi"              "pi --version"
+fi
 run "node"            "node --version"
 run "git"             "git --version"
 run "aws"             "aws --version"