Cut v0.75.5b — fix cache-hit silent same-bytes regression

ALL FOUR releases v0.74.0 -> v0.75.5 had been shipping the same image
bytes due to a Docker layer-cache hit on the bare 'npm install -g
@earendil-works/pi-coding-agent' command (when PI_VERSION=latest).
The command string is identical across builds, so the layer-hash is
identical, so registry buildcache (cache-from/cache-to) silently
reuses 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.

DISCOVERED 2026-05-23 by user trying to update pi-devbox on MBP-M1
and seeing pi 0.74.0 reported despite pulling v0.75.5.

CHANGES

.gitea/workflows/docker-publish.yml — both smoke and publish jobs
get a new 'Resolve PI_VERSION from tag' step that strips the leading
'v' and any trailing letter suffix from github.ref_name. Result is
passed as a build-arg to docker/build-push-action so the npm install
layer's hash includes the concrete version, forcing cache miss when
pi bumps.

scripts/smoke-test.sh — new run_expect helper that asserts pi
--version contains the EXPECTED_PI_VERSION env var. Smoke job sets
this from the resolve step output. Would have caught this regression
on v0.75.3.

Dockerfile — comment block above ARG PI_VERSION=latest documenting
the cache-hit footgun. The 'if latest' branch in the install RUN is
preserved for local dev convenience but never fires in CI now.

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; will manifest
when cutting a vN.N.Nb-style opencode-version-unchanged release that
only bumps pi).

CHANGELOG.md — full entry under v0.75.5b describing the recovery,
the silent-failure mechanism, and the verification steps.

NO IMAGE-CONTENT CHANGES vs v0.75.5 INTENT. This build produces the
actual pi 0.75.5 image content that v0.75.5 was supposed to ship.

NEXT FOLLOWUP (parked, not in this commit)

opencode-devbox should get the same workflow change for its
build-variant-with-pi and build-variant-omos-with-pi jobs. Currently
masked because every release also bumps OPENCODE_VERSION which
invalidates the cache, but that masking would fail on a pi-only bump
release.

.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,6 +102,16 @@ jobs:
             echo "EOF"
           } >> "$GITHUB_OUTPUT"
 
+      # 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)
         uses: docker/build-push-action@v7
         with:
@@ -88,6 +119,8 @@ jobs:
           platforms: linux/amd64,linux/arm64
           push: true
           tags: ${{ steps.tags.outputs.tags }}
+          build-args: |
+            PI_VERSION=${{ steps.resolve.outputs.pi_version }}
           cache-from: type=registry,ref=${{ env.IMAGE }}:buildcache
           cache-to: type=registry,ref=${{ env.IMAGE }}:buildcache,mode=max