docs: promote CHANGELOG Unreleased -> v1.15.13c

v1.15.13b's base crept to 2506 MB (LAN-access script + updated entrypoint
+ apt drift), tripping the zero-headroom 2500 ceiling. smoke-base failed,
which cascaded into skipping build-variant-base AND promote-base-latest,
so base-latest never advanced. All functional checks passed — this is a
guardrail bump, not a real regression. base-<hash> and the omos/with-pi/
omos-with-pi/pi-only variants did publish on the fresh base in run 354.

.env.example

@@ -31,6 +31,30 @@ WORKSPACE_PATH=~/projects
 # Path to SSH keys on host
 SSH_KEY_PATH=~/.ssh
 
+# ── LAN access from the container (host-OS-agnostic) ─────────────────
+# On VM-backed hosts (macOS OrbStack / Docker Desktop, also Docker Desktop
+# on Windows) the container runs in a Linux VM and CANNOT reach the host's
+# directly-attached LAN peers by default. On native Linux Docker the LAN is
+# reachable directly and nothing is needed. The entrypoint detects this and,
+# on VM-backed hosts, generates ~/.ssh-local/config so the host can be used
+# as an SSH jump (use the `dssh` alias, or add `ProxyJump host` to targets
+# in your bind-mounted ~/.ssh/config).
+#
+# DEVBOX_LAN_ACCESS: auto (default) | jump | off
+#   auto = set up the jump only on VM-backed hosts; no-op on native Linux.
+#   jump = always set up (e.g. native Linux with extra_hosts host-gateway).
+#   off  = disable entirely.
+# DEVBOX_LAN_ACCESS=auto
+#
+# HOST_SSH_USER: your username on the host. REQUIRED for the jump to
+# authenticate. On first start the entrypoint prints the public key to
+# authorize on the host (append to the host's ~/.ssh/authorized_keys) and
+# reminds you to enable the host's SSH server (e.g. macOS Remote Login).
+# HOST_SSH_USER=
+#
+# DEVBOX_HOST_ALIAS: host hostname to reach (default host.docker.internal).
+# DEVBOX_HOST_ALIAS=host.docker.internal
+
 # ── Skillset (agent skills and instructions) ─────────────────────────
 # If you have a skillset repo, the entrypoint auto-deploys skills and
 # instructions on container start using relative symlinks (portable

.gitea/README.md

@@ -8,14 +8,14 @@ the build pipeline is shaped the way it is, you're in the right place.
 
 | File | Trigger | Role |
 |---|---|---|
-| [`workflows/docker-publish-split.yml`](workflows/docker-publish-split.yml) | `push: tags: v*` | **Production release pipeline.** Two-phase split-base build: shared `base-<hash>` published once (skipped on cache hit), then four parallel variant deltas. ~40–80 min wall clock depending on runner count and whether base needs rebuilding. |
+| [`workflows/docker-publish-split.yml`](workflows/docker-publish-split.yml) | `push: tags: v*` | **Production release pipeline.** Two-phase split-base build: shared `base-<hash>` published once (skipped on cache hit), then five parallel variant deltas. ~40–80 min wall clock depending on runner count and whether base needs rebuilding. |
-| [`workflows/validate.yml`](workflows/validate.yml) | `push: branches: main` + PR | **Lightweight gate.** amd64-only smoke test of all four variants + `DOCKER_HUB.md` sync check. ~30 min. Fires on every push to `main`. |
+| [`workflows/validate.yml`](workflows/validate.yml) | `push: branches: main` + PR | **Lightweight gate.** amd64-only smoke test of all five variants + `DOCKER_HUB.md` sync check. ~30 min. Fires on every push to `main`. |
 
 ## Why the split-base pipeline exists
 
-opencode-devbox publishes **four image variants** (`base`, `omos`, `with-pi`, `omos-with-pi`) × **two architectures** (amd64, arm64) = **eight image tags per release**. Today's runners are 2 self-hosted gitea Actions runners. arm64 builds are emulated under QEMU, which is the dominant cost (~3–5x slower than native).
+opencode-devbox builds **five image variants** (`base`, `omos`, `with-pi`, `omos-with-pi`, `pi-only`) × **two architectures** (amd64, arm64). Four opencode-bearing variants publish under this repo (**eight tags per release** + the floating `base-latest`); the `pi-only` build is pushed into the separate `joakimp/pi-devbox` repo as `base-pi-only` (so no opencode-less tag appears here). Today's runners are 2 self-hosted gitea Actions runners. arm64 builds are emulated under QEMU, which is the dominant cost (~3–5x slower than native).
 
-The four variants share ~95% of their layers (Debian + apt + Node + AWS CLI + mempalace + dev tools + entrypoints). The original `Dockerfile` was a single multi-stage build with `INSTALL_*` build-args gating variant-specific RUNs. BuildKit's per-layer cache key is content-addressed, but as soon as a build-arg-gated `RUN` produces a different layer hash for variant A vs variant B, every subsequent layer also has a different parent → identical commands re-execute per variant. Result: minimal cross-variant cache reuse on a fresh build.
+The five variants share ~95% of their layers (Debian + apt + Node + AWS CLI + mempalace + dev tools + entrypoints). The original `Dockerfile` was a single multi-stage build with `INSTALL_*` build-args gating variant-specific RUNs. BuildKit's per-layer cache key is content-addressed, but as soon as a build-arg-gated `RUN` produces a different layer hash for variant A vs variant B, every subsequent layer also has a different parent → identical commands re-execute per variant. Result: minimal cross-variant cache reuse on a fresh build.
 
 Two improvements were considered:
 
@@ -174,7 +174,7 @@ production aliases pointing at the previous good release.
 
 ### Step 5: `promote-base-latest`
 
-Once all four variants successfully publish, re-tag `base-<hash>` as
+Once all five variants successfully publish, re-tag `base-<hash>` as
 `base-latest` using `crane copy`. This is a **manifest-level re-tag, not
 a rebuild** — it touches only Docker Hub's image index, takes seconds,
 and is atomic.
@@ -252,7 +252,7 @@ on every push to `main` and on PRs. It:
 
 1. Runs `scripts/generate-dockerhub-md.py --check` to enforce
    `DOCKER_HUB.md` is in sync with `HUB_TEMPLATE`.
-2. Builds each of the four variants amd64-only (no multi-arch, no push)
+2. Builds each of the five variants amd64-only (no multi-arch, no push)
    and runs `scripts/smoke-test.sh`.
 
 This catches regressions before they reach a tag push. Wall clock ~30 min.

.gitea/workflows/docker-publish-split.yml

@@ -37,6 +37,11 @@ concurrency:
 env:
   BUILDKIT_PROGRESS: plain
   IMAGE: ${{ vars.DOCKERHUB_USERNAME }}/opencode-devbox
+  # The pi-only variant is built here (single source of truth for the pi stack)
+  # but published into the pi-devbox repo as an internal building-block tag,
+  # NOT under opencode-devbox — so opencode-devbox never shows a tag with no
+  # opencode in it. pi-devbox's own CI FROMs PI_IMAGE:base-pi-only.
+  PI_IMAGE: ${{ vars.DOCKERHUB_USERNAME }}/pi-devbox
   RELEASE_TAG: ${{ github.ref_type == 'tag' && github.ref_name || inputs.release_tag }}
   PROMOTE_LATEST: ${{ github.ref_type == 'tag' && 'true' || inputs.promote_latest }}
 
@@ -122,6 +127,8 @@ jobs:
     outputs:
       pi_version: ${{ steps.resolve.outputs.pi_version }}
       omos_version: ${{ steps.resolve.outputs.omos_version }}
+      fork_ref: ${{ steps.resolve.outputs.fork_ref }}
+      obsmem_ref: ${{ steps.resolve.outputs.obsmem_ref }}
     steps:
       - name: Resolve pi + omos versions from npm registry
         id: resolve
@@ -136,7 +143,23 @@ jobs:
           OMOS_VERSION=$(curl -sf "https://registry.npmjs.org/oh-my-opencode-slim/latest" | jq -r '.version')
           echo "pi_version=${PI_VERSION}"     >> "$GITHUB_OUTPUT"
           echo "omos_version=${OMOS_VERSION}" >> "$GITHUB_OUTPUT"
+          # Resolve the pi-fork / pi-observational-memory git refs (default
+          # branch master) to concrete commit SHAs so the build-arg string
+          # changes whenever upstream moves — defeating the same registry-
+          # buildcache cache-hit footgun that PI_VERSION/OMOS_VERSION guard
+          # against. The Accept: application/vnd.github.sha media type returns
+          # the bare SHA. Falls back to the branch name if the API is
+          # unreachable/rate-limited (still functional, just cache-stale-prone).
+          FORK_REF=$(curl -sf -H "Accept: application/vnd.github.sha" \
+            "https://api.github.com/repos/elpapi42/pi-fork/commits/master" || echo "master")
+          OBSMEM_REF=$(curl -sf -H "Accept: application/vnd.github.sha" \
+            "https://api.github.com/repos/elpapi42/pi-observational-memory/commits/master" || echo "master")
+          [ -n "$FORK_REF" ]   || FORK_REF=master
+          [ -n "$OBSMEM_REF" ] || OBSMEM_REF=master
+          echo "fork_ref=${FORK_REF}"     >> "$GITHUB_OUTPUT"
+          echo "obsmem_ref=${OBSMEM_REF}" >> "$GITHUB_OUTPUT"
           echo "Resolved PI_VERSION=${PI_VERSION}, OMOS_VERSION=${OMOS_VERSION}"
+          echo "Resolved PI_FORK_REF=${FORK_REF}, PI_OBSMEM_REF=${OBSMEM_REF}"
 
   # ── Phase 2: build & push base (multi-arch), only when needed ──────
   build-base:
@@ -359,6 +382,8 @@ jobs:
             INSTALL_OMOS=false
             INSTALL_PI=true
             PI_VERSION=${{ needs.resolve-versions.outputs.pi_version }}
+            PI_FORK_REF=${{ needs.resolve-versions.outputs.fork_ref }}
+            PI_OBSMEM_REF=${{ needs.resolve-versions.outputs.obsmem_ref }}
       - env:
           EXPECTED_PI_VERSION: ${{ needs.resolve-versions.outputs.pi_version }}
         run: bash scripts/smoke-test.sh opencode-devbox:smoke-with-pi --variant with-pi
@@ -405,11 +430,60 @@ jobs:
             INSTALL_PI=true
             PI_VERSION=${{ needs.resolve-versions.outputs.pi_version }}
             OMOS_VERSION=${{ needs.resolve-versions.outputs.omos_version }}
+            PI_FORK_REF=${{ needs.resolve-versions.outputs.fork_ref }}
+            PI_OBSMEM_REF=${{ needs.resolve-versions.outputs.obsmem_ref }}
       - env:
           EXPECTED_PI_VERSION: ${{ needs.resolve-versions.outputs.pi_version }}
           EXPECTED_OMOS_VERSION: ${{ needs.resolve-versions.outputs.omos_version }}
         run: bash scripts/smoke-test.sh opencode-devbox:smoke-omos-with-pi --variant omos-with-pi
 
+  smoke-pi-only:
+    needs: [base-decide, build-base, resolve-versions]
+    if: |
+      always() &&
+      needs.base-decide.result == 'success' &&
+      needs.resolve-versions.result == 'success' &&
+      (needs.build-base.result == 'success' || needs.build-base.result == 'skipped')
+    runs-on: ubuntu-latest
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+      - run: |
+          rm -rf /opt/hostedtoolcache /opt/microsoft /opt/az /opt/ghc \
+            /usr/local/.ghcup /usr/share/dotnet /usr/share/swift \
+            /usr/local/lib/android /usr/local/share/powershell \
+            /usr/local/share/chromium /usr/local/share/boost \
+            /usr/lib/jvm 2>/dev/null || true
+          docker system prune -af --volumes || true
+          docker builder prune -af || true
+      - uses: docker/setup-buildx-action@v4
+        with: {driver-opts: network=host}
+      - uses: docker/login-action@v3
+        with:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: Dockerfile.variant
+          platforms: linux/amd64
+          push: false
+          load: true
+          tags: opencode-devbox:smoke-pi-only
+          build-args: |
+            BASE_IMAGE=${{ env.IMAGE }}:${{ needs.base-decide.outputs.base_tag }}
+            INSTALL_OPENCODE=false
+            INSTALL_OMOS=false
+            INSTALL_PI=true
+            PI_VERSION=${{ needs.resolve-versions.outputs.pi_version }}
+            PI_FORK_REF=${{ needs.resolve-versions.outputs.fork_ref }}
+            PI_OBSMEM_REF=${{ needs.resolve-versions.outputs.obsmem_ref }}
+      - env:
+          EXPECTED_PI_VERSION: ${{ needs.resolve-versions.outputs.pi_version }}
+        run: bash scripts/smoke-test.sh opencode-devbox:smoke-pi-only --variant pi-only
+
   # ── Phase 4: multi-arch publish per variant ────────────────────────
 
   build-variant-base:
@@ -594,6 +668,8 @@ jobs:
           TAGS: ${{ steps.tags.outputs.tags }}
           BASE_IMAGE_FULL: ${{ env.IMAGE }}:${{ needs.base-decide.outputs.base_tag }}
           PI_VERSION: ${{ needs.resolve-versions.outputs.pi_version }}
+          FORK_REF: ${{ needs.resolve-versions.outputs.fork_ref }}
+          OBSMEM_REF: ${{ needs.resolve-versions.outputs.obsmem_ref }}
         run: |
           set -euo pipefail
           TAG_FLAGS=()
@@ -610,6 +686,8 @@ jobs:
                 --build-arg "INSTALL_OMOS=false" \
                 --build-arg "INSTALL_PI=true" \
                 --build-arg "PI_VERSION=${PI_VERSION}" \
+                --build-arg "PI_FORK_REF=${FORK_REF}" \
+                --build-arg "PI_OBSMEM_REF=${OBSMEM_REF}" \
                 "${TAG_FLAGS[@]}" \
                 .; then
               echo "==> Attempt ${attempt} succeeded"
@@ -666,6 +744,8 @@ jobs:
           BASE_IMAGE_FULL: ${{ env.IMAGE }}:${{ needs.base-decide.outputs.base_tag }}
           PI_VERSION: ${{ needs.resolve-versions.outputs.pi_version }}
           OMOS_VERSION: ${{ needs.resolve-versions.outputs.omos_version }}
+          FORK_REF: ${{ needs.resolve-versions.outputs.fork_ref }}
+          OBSMEM_REF: ${{ needs.resolve-versions.outputs.obsmem_ref }}
         run: |
           set -euo pipefail
           TAG_FLAGS=()
@@ -683,6 +763,86 @@ jobs:
                 --build-arg "INSTALL_PI=true" \
                 --build-arg "PI_VERSION=${PI_VERSION}" \
                 --build-arg "OMOS_VERSION=${OMOS_VERSION}" \
+                --build-arg "PI_FORK_REF=${FORK_REF}" \
+                --build-arg "PI_OBSMEM_REF=${OBSMEM_REF}" \
+                "${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
+
+  build-variant-pi-only:
+    needs: [base-decide, smoke-pi-only, resolve-versions]
+    runs-on: ubuntu-latest
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+      - run: |
+          rm -rf /opt/hostedtoolcache /opt/microsoft /opt/az /opt/ghc \
+            /usr/local/.ghcup /usr/share/dotnet /usr/share/swift \
+            /usr/local/lib/android /usr/local/share/powershell \
+            /usr/local/share/chromium /usr/local/share/boost \
+            /usr/lib/jvm 2>/dev/null || true
+          docker system prune -af --volumes || true
+          docker builder prune -af || true
+      - uses: docker/setup-qemu-action@v3
+        with: {platforms: arm64}
+      - uses: docker/setup-buildx-action@v4
+        with: {driver-opts: network=host}
+      - uses: docker/login-action@v3
+        with:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - name: Compute version-specific tags
+        id: tags
+        run: |
+          # Option B: push the pi-only build into the pi-devbox repo as an
+          # internal building-block tag (base-pi-only[-<version>]), NOT under
+          # opencode-devbox. pi-devbox's CI FROMs ${PI_IMAGE}:base-pi-only.
+          VERSION="${{ env.RELEASE_TAG }}"
+          { echo "tags<<EOF"
+            echo "${PI_IMAGE}:base-pi-only-${VERSION}"
+            if [ "${{ env.PROMOTE_LATEST }}" = "true" ]; then
+              echo "${PI_IMAGE}:base-pi-only"
+            fi
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+      - name: Build and push variant (with retry)
+        shell: bash
+        env:
+          TAGS: ${{ steps.tags.outputs.tags }}
+          BASE_IMAGE_FULL: ${{ env.IMAGE }}:${{ needs.base-decide.outputs.base_tag }}
+          PI_VERSION: ${{ needs.resolve-versions.outputs.pi_version }}
+          FORK_REF: ${{ needs.resolve-versions.outputs.fork_ref }}
+          OBSMEM_REF: ${{ needs.resolve-versions.outputs.obsmem_ref }}
+        run: |
+          set -euo pipefail
+          TAG_FLAGS=()
+          while IFS= read -r t; do [[ -n "$t" ]] && TAG_FLAGS+=( -t "$t" ); done <<< "${TAGS}"
+          # 3-attempt retry (see build-base step for rationale). Variant: pi-only.
+          for attempt in 1 2 3; do
+            echo "==> Build+push attempt ${attempt}/3"
+            if docker buildx build \
+                --platform linux/amd64,linux/arm64 \
+                --file Dockerfile.variant \
+                --push \
+                --build-arg "BASE_IMAGE=${BASE_IMAGE_FULL}" \
+                --build-arg "INSTALL_OPENCODE=false" \
+                --build-arg "INSTALL_OMOS=false" \
+                --build-arg "INSTALL_PI=true" \
+                --build-arg "PI_VERSION=${PI_VERSION}" \
+                --build-arg "PI_FORK_REF=${FORK_REF}" \
+                --build-arg "PI_OBSMEM_REF=${OBSMEM_REF}" \
                 "${TAG_FLAGS[@]}" \
                 .; then
               echo "==> Attempt ${attempt} succeeded"
@@ -705,6 +865,7 @@ jobs:
       - build-variant-omos
       - build-variant-with-pi
       - build-variant-omos-with-pi
+      - build-variant-pi-only
     # Skip on cache-hit base builds: when need_build=false, base-latest
     # already points at the same digest as base-<hash>, so the retag is
     # a tautology and any transient failure of it is purely cosmetic.
@@ -757,6 +918,7 @@ jobs:
       - build-variant-omos
       - build-variant-with-pi
       - build-variant-omos-with-pi
+      - build-variant-pi-only
     # Run when at least the base variant published — don't let a single
     # variant failure (e.g., omos-with-pi smoke threshold) prevent Hub
     # description refresh for the other variants that did publish.

.gitea/workflows/validate.yml

@@ -312,3 +312,62 @@ jobs:
       - name: Smoke test
         run: |
           bash scripts/smoke-test.sh opencode-devbox:ci-omos-with-pi --variant omos-with-pi
+
+  validate-pi-only:
+    runs-on: ubuntu-latest
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Force IPv4 for Docker Hub
+        run: |
+          echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+
+      - name: Reclaim runner disk
+        run: |
+          set -x
+          df -h / || true
+          rm -rf \
+            /opt/hostedtoolcache \
+            /opt/microsoft \
+            /opt/az \
+            /opt/ghc \
+            /usr/local/.ghcup \
+            /usr/share/dotnet \
+            /usr/share/swift \
+            /usr/local/lib/android \
+            /usr/local/share/powershell \
+            /usr/local/share/chromium \
+            /usr/local/share/boost \
+            /usr/lib/jvm 2>/dev/null || true
+          apt-get clean || true
+          rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* || true
+          docker system df || true
+          docker system prune -af --volumes || true
+          docker builder prune -af || true
+          df -h / || true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+        with:
+          driver-opts: network=host
+
+      - name: Build pi-only image (amd64, load to local daemon)
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: Dockerfile.variant
+          platforms: linux/amd64
+          push: false
+          load: true
+          build-args: |
+            BASE_IMAGE=joakimp/opencode-devbox:base-latest
+            INSTALL_OPENCODE=false
+            INSTALL_PI=true
+          tags: opencode-devbox:ci-pi-only
+
+      - name: Smoke test
+        run: |
+          bash scripts/smoke-test.sh opencode-devbox:ci-pi-only --variant pi-only

AGENTS.md

@@ -7,9 +7,10 @@ Docker image packaging [opencode](https://opencode.ai) into a production-ready d
 ## File roles
 
 - `Dockerfile.base` — variant-independent layers (apt, locales, AWS CLI, Node.js, mempalace, gitea-mcp, user setup, chromadb prewarm, ENVs, entrypoints). Published as `joakimp/opencode-devbox:base-<sha12>`. Rebuilt only when its content hash changes.
-- `Dockerfile.variant` — `FROM`s the base and adds only opencode/omos/pi installs gated by build args: `INSTALL_OPENCODE` (default true), `INSTALL_OMOS`, `INSTALL_PI`, and `INSTALL_MEMPALACE`. All GitHub-sourced binaries are pinned with version ARGs.
+- `Dockerfile.variant` — `FROM`s the base and adds only opencode/omos/pi installs gated by build args: `INSTALL_OPENCODE` (default true), `INSTALL_OMOS`, `INSTALL_PI`, and `INSTALL_MEMPALACE`. All GitHub-sourced binaries are pinned with version ARGs. When `INSTALL_PI=true` it also clones `pi-fork` + `pi-observational-memory` (from `github.com/elpapi42`, refs `PI_FORK_REF`/`PI_OBSMEM_REF`) to `/opt` and runs `npm install` there at build time so the `fork`/`recall` extensions can load (a local-path `pi install` does not npm-install). The `pi-only` variant sets `INSTALL_OPENCODE=false`, `INSTALL_PI=true` — pi without opencode, the single source of truth for the separate `pi-devbox` image. It is built and smoke-tested here, but **published into the `joakimp/pi-devbox` repo** as the internal building-block tag `base-pi-only[-vX.Y.Z]` (NOT under `opencode-devbox`), so an opencode-devbox tag never ships without opencode.
 - `entrypoint.sh` — runs as root: UID/GID adjustment, SSH permissions, volume ownership fixes (skipped via `.devbox-owner` sentinel when ownership is already correct). Then drops to developer via gosu. Volume ownership loop covers `~/.pi/` when `INSTALL_PI=true`.
-- `entrypoint-user.sh` — runs as developer: git config, opencode.jsonc generation (delegated to `generate-config.py`), pi-toolkit + pi-extensions deploy (when pi installed), pi settings.json bootstrap, mempalace pi-bridge symlink, skillset auto-deploy from mounted skillset repo, OMOS setup.
+- `entrypoint-user.sh` — runs as developer: git config, opencode.jsonc generation (delegated to `generate-config.py`), LAN-access setup (delegated to `setup-lan-access.sh`), pi-toolkit + pi-extensions deploy (when pi installed), pi settings.json bootstrap, mempalace pi-bridge symlink, runtime `pi install /opt/{pi-fork,pi-observational-memory}` registration (idempotent), skillset auto-deploy from mounted skillset repo, OMOS setup.
+- `rootfs/usr/local/lib/opencode-devbox/setup-lan-access.sh` — host-OS-agnostic LAN reachability helper. Detects VM-backed hosts (macOS OrbStack / Docker Desktop, via `host.docker.internal` resolution) and generates a writable `~/.ssh-local/config` using the host as an SSH jump; no-op on native Linux. Controlled by `DEVBOX_LAN_ACCESS` / `HOST_SSH_USER` / `DEVBOX_HOST_ALIAS`. Ships the mechanism only (generic `host` jump alias); user targets stay in their bind-mounted `~/.ssh/config`. Non-fatal. Counted in the base hash, so editing it advances `base-latest`.
 - `rootfs/usr/local/lib/opencode-devbox/generate-config.py` — generates `~/.config/opencode/opencode.jsonc` from env vars. Never overwrites an existing config (checks both `.json` and `.jsonc`). Auto-registers MCP servers for detected tools (mempalace via `mempalace-mcp`, gitea-mcp, context7 remote endpoint).
 - `scripts/smoke-test.sh` — post-build image verification. Asserts binary presence, opencode startup, entrypoint correctness, config generation idempotency, and image size thresholds. Used by both CI workflows.
 - `scripts/generate-dockerhub-md.py` — generates `DOCKER_HUB.md` from a hand-maintained `HUB_TEMPLATE` constant. `--check` fails if the committed file is out of sync (enforced by the `validate` workflow).
@@ -17,7 +18,7 @@ Docker image packaging [opencode](https://opencode.ai) into a production-ready d
 - `README.md` — authoritative source documentation for everything in this repo. Independent of `DOCKER_HUB.md`: the Hub doc is hand-maintained in the generator's `HUB_TEMPLATE` and intentionally slim, linking back to the gitea README for depth.
 - `.gitea/README.md` — **read this first** if you're touching CI. Architectural overview of the build pipeline (production vs split-base), wall-clock estimates, NPM_CONFIG_PREFIX gotcha, runner expectations, migration plan.
 - `.gitea/workflows/validate.yml` — lightweight amd64 build + smoke test on push to main and PRs. Also runs the DOCKER_HUB.md sync check.
-- `.gitea/workflows/docker-publish-split.yml` — production CI pipeline on tag push (`v*`). Two-phase split-base: computes base hash, conditionally builds base, runs 4 parallel smoke tests, then 4 parallel multi-arch variant builds, promotes `base-latest` alias, updates Docker Hub description.
+- `.gitea/workflows/docker-publish-split.yml` — production CI pipeline on tag push (`v*`). Two-phase split-base: computes base hash, conditionally builds base, runs 5 parallel smoke tests, then 5 parallel multi-arch variant builds, promotes `base-latest` alias, updates Docker Hub description.
 
 ## Versioning scheme
 
@@ -35,7 +36,7 @@ Tags follow `v{opencode_version}[letter]` — e.g. `v1.14.20` for the first buil
   
   Cautionary example: 2026-05-28 morning, `v1.15.12` was cut while opencode-ai was still at `1.15.11`. The commit message itself acknowledged "OPENCODE_VERSION stays at 1.15.11" but tagged `v1.15.12` anyway. Re-cut as `v1.15.11c` the same afternoon (see CHANGELOG). The `v1.15.12` git tag and Hub images stayed as historical artifacts; the slip cost a CI cycle and a CHANGELOG-rewrite. **Run the npm view check at the top of every release-day cut.**
 
-CI produces eight Docker Hub tags per release: `vX.Y.Z[n]`, `latest`, `vX.Y.Z[n]-omos`, `latest-omos`, `vX.Y.Z[n]-with-pi`, `latest-with-pi`, `vX.Y.Z[n]-omos-with-pi`, `latest-omos-with-pi` — one tag pair (versioned + floating alias) per build variant.
+CI produces eight Docker Hub tags **under `opencode-devbox`** per release: `vX.Y.Z[n]`, `latest`, `vX.Y.Z[n]-omos`, `latest-omos`, `vX.Y.Z[n]-with-pi`, `latest-with-pi`, `vX.Y.Z[n]-omos-with-pi`, `latest-omos-with-pi` — one tag pair (versioned + floating alias) per opencode-bearing variant (four variants). A fifth build, `pi-only`, is built+smoked here but pushed into the **`joakimp/pi-devbox`** repo as `base-pi-only-vX.Y.Z` (+ `base-pi-only` on tag builds), where it becomes the base for that image.
 
 When bumping the opencode version, bump `OPENCODE_VERSION` in `Dockerfile.variant` and update the comment in `.env.example` if it names a specific model/version for context.
 
@@ -81,7 +82,7 @@ cd /tmp && npm pack @earendil-works/pi-coding-agent@0.75.5 && tar -xzf earendil-
 - **Resolved versions are logged by the smoke test** — `scripts/smoke-test.sh` prints a "Resolved component versions" table as its first step. CI logs always capture what got baked into a given image even when ARGs default to `latest`.
 - **`PI_VERSION` and `OMOS_VERSION` MUST be passed by CI as concrete versions**, not left at the `latest` default. The npm install steps in `Dockerfile.variant` (`npm install -g @earendil-works/pi-coding-agent` / `oh-my-opencode-slim@${OMOS_VERSION}`) produce identical layer-hashes when the ARG values are byte-identical across builds; combined with the registry buildcache (`base-buildcache`) the layer gets reused even when `latest` would have resolved to a newer upstream. This is the same class of bug that bit pi-devbox v0.74.0 → v0.75.5 (silent same-bytes-across-releases regression discovered 2026-05-23, fixed in pi-devbox v0.75.5b). It is currently *masked* in opencode-devbox by `OPENCODE_VERSION` being a hard-coded ARG that bumps every release — that bump invalidates the parent-chain cache key for the downstream pi/omos layers — but the masking would fail the moment a `vN.N.Nb` opencode-version-unchanged release ships that only bumps pi or omos. Preventative fix: `.gitea/workflows/docker-publish-split.yml` has a `resolve-versions` job that runs `npm view @earendil-works/pi-coding-agent version` and `npm view oh-my-opencode-slim version`, exposing concrete values as outputs that every variant smoke + build job consumes via build-args. Smoke tests assert via `EXPECTED_PI_VERSION` / `EXPECTED_OMOS_VERSION` env vars — would catch the regression on the next release rather than four releases later. **If you change the variant build-args list, the resolve-versions job, or the smoke EXPECTED_*_VERSION wiring, audit all affected jobs in lockstep.**
 - **Registry buildkit cache-export is currently disabled** — do NOT re-add `cache-from`/`cache-to` to the `build-base` step in `.gitea/workflows/docker-publish-split.yml` without first verifying that buildkit's `mode=max` cache-export to `registry-1.docker.io` no longer returns HTTP 400 from the Hub CDN edge. The regression surfaced ~2026-05-23 and broke five consecutive opencode-devbox publish attempts (runs #332/333/334/336 + a rerun); root-caused on 2026-05-28 by a manual host-side publish that reproduced the same 400 only on `--cache-to` while image push worked fine. Failure shape is stable (`Offset:0` in the `_state` token, HTML response body = CDN-tier rejection, not registry backend), repo-specific (we're the only repo writing `:base-buildcache` mode=max), and explains why pinning `setup-buildx-action@v4.0.0` didn't help (action pin doesn't change the bundled buildkit version on the catthehacker runner image). Trade-off: dockerfile.base changes pay a full ~3 min rebuild instead of pulling cached layers; unchanged bases short-circuit at the Hub-probe step in `base-decide` and never re-build anyway. Variants don't use registry cache so they're unaffected. Re-enable condition: upstream moby/buildkit fix lands AND a low-risk test run succeeds without 400s. See CHANGELOG v1.15.12 `Unreleased` block for the full diagnostic chain. Manual escape-hatch publish procedure: `docs/manual-host-publish.md`.
-- **Push steps wrap `docker buildx build --push` in a 3-attempt retry loop** (15s, 30s backoff) for transient `registry-1.docker.io` blips — rate limits, brief 5xx, CDN flap. Implemented as inline `shell: bash` steps with `docker buildx build` raw rather than `docker/build-push-action@v7` so the loop is visible and tweakable. Affects the 1 base + 4 variant push steps in `.gitea/workflows/docker-publish-split.yml`; smoke-test builds (`load: true`, no push) are untouched. **This does NOT mask deterministic failures** — a true regression (like the cache-export 400 of 2026-05-23..28) fails all 3 attempts identically and the job still fails. Orthogonal to the cache-export disablement above: cache-export was about a deterministic protocol mismatch, retry is about absorbing genuine transients. Both are belt-and-braces with the `ci-release-watcher` skill's transient-rerun heuristic. If you change the matrix of push steps, keep the retry wrapper consistent across them — the pattern is duplicated rather than factored out because Gitea Actions doesn't support reusable composite shell steps cleanly.
+- **Push steps wrap `docker buildx build --push` in a 3-attempt retry loop** (15s, 30s backoff) for transient `registry-1.docker.io` blips — rate limits, brief 5xx, CDN flap. Implemented as inline `shell: bash` steps with `docker buildx build` raw rather than `docker/build-push-action@v7` so the loop is visible and tweakable. Affects the 1 base + 5 variant push steps in `.gitea/workflows/docker-publish-split.yml`; smoke-test builds (`load: true`, no push) are untouched. **This does NOT mask deterministic failures** — a true regression (like the cache-export 400 of 2026-05-23..28) fails all 3 attempts identically and the job still fails. Orthogonal to the cache-export disablement above: cache-export was about a deterministic protocol mismatch, retry is about absorbing genuine transients. Both are belt-and-braces with the `ci-release-watcher` skill's transient-rerun heuristic. If you change the matrix of push steps, keep the retry wrapper consistent across them — the pattern is duplicated rather than factored out because Gitea Actions doesn't support reusable composite shell steps cleanly.
 - **Shell scripts use `set -euo pipefail`** — both entrypoints are strict. Errors in volume chown or SSH permission operations are intentionally suppressed with `|| true`.
 - **MemPalace install path** — installed via `uv tool install` into `/opt/uv-tools/mempalace/`. Both the `mempalace` CLI and the `mempalace-mcp` MCP server binary are shipped as entry points by the mempalace package itself and placed on PATH by uv as shims whose shebangs point at the venv's Python. No hand-rolled wrapper is needed. Do not use `pip install --break-system-packages` — that was the previous approach and has been removed. Do not use `["python3", "-m", "mempalace.mcp_server"]` in `opencode.jsonc` — system Python can't import from the uv venv.
 - **generate-config.py idempotency** — the script MUST never overwrite an existing `opencode.jsonc` or legacy `opencode.json`. Config persists in the `devbox-opencode-config` named volume; accidentally clobbering that file would destroy hand-edits. The smoke test asserts this.
@@ -98,7 +99,7 @@ cd /tmp && npm pack @earendil-works/pi-coding-agent@0.75.5 && tar -xzf earendil-
 - `update-description` job runs only when both builds succeed (`needs: [build-base, build-omos]`).
 - Tags must be pushed to trigger the publish workflow. The validate workflow runs on push to main and PRs.
 - Smoke tests run on amd64 only (single-arch load into the local daemon). The multi-arch push happens after smoke passes.
-- **Gitea Actions runner has ~40 GB disk, often 70%+ used at job start.** All eight `load: true` jobs (`validate-base`, `validate-omos`, `validate-with-pi`, `validate-omos-with-pi`, `smoke-base`, `smoke-omos`, `smoke-with-pi`, `smoke-omos-with-pi`) include a `Reclaim runner disk` step that strips catthehacker-resident toolchains and prunes stale docker state before `setup-buildx-action`. Build jobs use a lighter version (push-by-digest doesn't need `docker system prune`). Don't remove these steps without testing on a fresh runner.
+- **Gitea Actions runner has ~40 GB disk, often 70%+ used at job start.** All ten `load: true` jobs (`validate-base`, `validate-omos`, `validate-with-pi`, `validate-omos-with-pi`, `validate-pi-only`, `smoke-base`, `smoke-omos`, `smoke-with-pi`, `smoke-omos-with-pi`, `smoke-pi-only`) include a `Reclaim runner disk` step that strips catthehacker-resident toolchains and prunes stale docker state before `setup-buildx-action`. Build jobs use a lighter version (push-by-digest doesn't need `docker system prune`). Don't remove these steps without testing on a fresh runner.
 - **`docker/build-push-action@v7` with `platforms: linux/amd64,linux/arm64` handles multi-arch push natively in a single job** — produces a proper manifest list, no matrix or merge step needed. An earlier revision split into per-arch matrix jobs with digest artifacts, but that pattern requires `actions/{upload,download}-artifact@v4+` which Gitea Actions doesn't support (see below).
 - **`actions/upload-artifact` and `actions/download-artifact` must stay at @v3 on Gitea.** v4+ uses a GitHub-Enterprise-specific Artifact API; runs fail with `GHESNotSupportedError`. If you need artifacts for a new reason (build logs, SBOMs, etc.), pin @v3 explicitly.
 - **Step scripts run under `/bin/sh` (dash), not bash.** Avoid bash-isms like `${VAR//a/b}` parameter-pattern substitution; use POSIX alternatives (`tr`, `sed`) or declare `shell: bash` on the step.

CHANGELOG.md

@@ -8,7 +8,125 @@ Tags follow `v{opencode_version}[letter]` — bare tag for the first build on a
 
 ## Unreleased
 
-_(no changes since v1.15.11c)_
+_(no changes since v1.15.13c)_
+
+## v1.15.13c — 2026-06-03
+
+Follow-up to v1.15.13b: relocates the pi-only build out of the `opencode-devbox`
+repo (Option B) and fixes the base size threshold that blocked `promote-base-latest`.
+
+### Changed: `pi-only` build now publishes to the `joakimp/pi-devbox` repo (not `opencode-devbox`)
+
+The `pi-only` variant (added in v1.15.13b) was published under `opencode-devbox`
+as `latest-pi-only` / `vX.Y.Z-pi-only` — an "opencode-devbox" tag that contains
+**no opencode**, which confused users browsing the tag list.
+
+- The `build-variant-pi-only` CI job now pushes the artifact into the
+  **`joakimp/pi-devbox`** repo as `base-pi-only-vX.Y.Z` (+ floating `base-pi-only`
+  on tag builds) instead of `opencode-devbox:*-pi-only`. New `PI_IMAGE` workflow env.
+- It is still built from the same `Dockerfile.variant` (single source of truth)
+  and still smoke-tested by `smoke-pi-only` / `validate-pi-only` before publish.
+- `opencode-devbox` now publishes **eight** tags per release (four opencode-bearing
+  variants) plus `base-latest`; the pi-only pair lives in the pi-devbox repo.
+- De-advertised the pi-only tag from the README, `DOCKER_HUB.md` (HUB_TEMPLATE),
+  and AGENTS docs.
+- The old `opencode-devbox:latest-pi-only` / `vX.Y.Z-pi-only` tags from v1.15.13b
+  are superseded and should be deleted from Docker Hub.
+
+### Fixed: base image size threshold (unblocks `promote-base-latest`)
+
+- Bumped the `base` variant smoke size threshold 2500 → 2600 MB. In the v1.15.13b
+  run the base crept to 2506 MB (LAN-access script + updated entrypoint + apt
+  drift) and tripped the deliberately zero-headroom 2500 ceiling, which failed
+  `smoke-base` and cascaded into skipping `build-variant-base` **and**
+  `promote-base-latest` — so `base-latest` never advanced. (`base-<hash>` and the
+  omos/with-pi/omos-with-pi/pi-only variants did publish on the fresh base.)
+
+## v1.15.13b — 2026-06-03
+
+Container-level rebuild on opencode `1.15.13` (unchanged) and pi `0.78.0` (unchanged) — adds host-OS-agnostic LAN access, the `fork`/`recall` pi extensions, and a new `pi-only` variant. Letter-suffix release per the `v{opencode_version}[letter]` scheme since no upstream version moved.
+
+### Added: host-OS-agnostic LAN access (base image)
+
+The container can now reach LAN peers that the **host** can reach, regardless of host OS — addressing the macOS/Docker-Desktop limitation where a container in the Linux VM cannot see the host's directly-attached LAN.
+
+- New `rootfs/usr/local/lib/opencode-devbox/setup-lan-access.sh`, invoked (non-fatally) by `entrypoint-user.sh` on every start.
+- **Detection:** on VM-backed hosts (macOS OrbStack / Docker Desktop, Windows Docker Desktop — detected via `host.docker.internal` resolution) it generates a writable `~/.ssh-local/config` that uses the host as an SSH **jump**. On native Linux Docker (LAN reachable directly) it is a **no-op**.
+- **Mechanism, not policy:** ships a generic `host` (alias `mac`) jump entry + a generated jump key in the writable `~/.ssh-local/` sidecar (necessary because `~/.ssh` is bind-mounted read-only). Your own targets stay in your bind-mounted `~/.ssh/config` (add `ProxyJump host`), pulled in via `Include ~/.ssh/config`.
+- New env knobs: `DEVBOX_LAN_ACCESS` (`auto`|`jump`|`off`, default `auto`), `HOST_SSH_USER`, `DEVBOX_HOST_ALIAS`. When `HOST_SSH_USER` is unset the entrypoint prints the public key to authorize on the host.
+- New `dssh` / `dscp` aliases in `.bash_aliases` (wrap `ssh -F ~/.ssh-local/config`), guarded so they only appear when the jump config was generated.
+- Because this touches `Dockerfile.base` inputs (`rootfs/`, `entrypoint-user.sh`), the base image rebuilds and `base-latest` advances.
+
+### Added: pi-fork (`fork`) + pi-observational-memory (`recall`) in pi variants
+
+The `with-pi` and `omos-with-pi` variants now bake in two pi extensions from `github.com/elpapi42`:
+
+- `Dockerfile.variant` clones both repos to `/opt/pi-fork` and `/opt/pi-observational-memory` and runs `npm install` there at **build** time (a local-path `pi install` does not npm-install, so deps must be present for the extension to load).
+- `entrypoint-user.sh` registers them at runtime via `pi install /opt/<pkg>` (instant, in-place, idempotent; `fork`/`recall` tools bind on the next pi start).
+- CI (`resolve-versions`) resolves the `master` HEAD of each repo to a concrete commit SHA and passes it as `PI_FORK_REF` / `PI_OBSMEM_REF` build-args — same registry-buildcache cache-hit guard used for `PI_VERSION` / `OMOS_VERSION`.
+- New build-args: `PI_FORK_REPO`, `PI_FORK_REF`, `PI_OBSMEM_REPO`, `PI_OBSMEM_REF`.
+- Smoke test asserts the `/opt` clones + baked `node_modules` exist and that both packages register in `settings.json`. Size thresholds bumped: `with-pi` 2700→2900 MB, `omos-with-pi` 3700→3900 MB (fork's `@earendil-works` peer deps add ~150 MB).
+
+### Added: `pi-only` variant (basis for `pi-devbox`)
+
+New fifth published variant built with `INSTALL_OPENCODE=false`, `INSTALL_PI=true` — pi + companions (toolkit, extensions, `fork`, `recall`) and all base tooling, but **without** opencode (~145 MB lighter than `with-pi`).
+
+- Published as `latest-pi-only` / `vX.Y.Z-pi-only` (multi-arch). New CI jobs `smoke-pi-only` and `build-variant-pi-only`; wired into `promote-base-latest` / `update-description` needs.
+- This is the **single source of truth** for the separate [`joakimp/pi-devbox`](https://gitea.jordbo.se/joakimp/pi-devbox) image, which now `FROM`s `latest-pi-only` instead of duplicating the pi-install logic. Lets pi-devbox stay lean and pi-focused while the install logic lives in one place.
+- Smoke size threshold: 2750 MB (`with-pi` minus opencode).
+
+_Versions unchanged: opencode-ai `1.15.13`, pi `0.78.0` (both still latest at time of writing)._
+
+## v1.15.13 — 2026-05-29
+
+First container build on `opencode-ai@1.15.13` upstream release (published 2026-05-29). Also picks up pi `0.77.0` → `0.78.0` (resolved from npm at build time).
+
+### Bumped: opencode-ai 1.15.12 → 1.15.13
+
+**Core**
+- Gateway Anthropic Opus 4.7+ adaptive reasoning now keeps summarized thinking instead of returning empty thinking blocks (bugfix).
+- Sessions can now store custom metadata through the API and SDK ([@shantur](https://github.com/shantur)).
+- Config now loads from the opened location upward, so directory-specific settings and provider policies apply more predictably.
+
+**TUI**
+- Wrapped inline tool rows now stay aligned, and failed inline tools can expand their error details in place (bugfix).
+
+### Bumped: pi 0.77.0 → 0.78.0 (resolved from npm at build time)
+
+See [pi-devbox v0.78.0](https://github.com/joakimp/pi-devbox/releases/tag/v0.78.0) for full pi release notes.
+
+## v1.15.12 — 2026-05-29
+
+First container build on the genuine `opencode-ai@1.15.12` upstream release (published 2026-05-28). Also bumps pi `0.76.0` → `0.77.0`.
+
+> **Note on the `v1.15.12` git tag:** an earlier `v1.15.12` git tag existed at commit `be2a168` as a historical artifact from the 2026-05-28 versioning slip (re-cut as `v1.15.11c` once the slip was caught). The corresponding Hub `v1.15.12*` images were manually deleted at the time. Now that opencode upstream has actually released 1.15.12, the tag is being re-used at HEAD per the `v{opencode_version}[letter]` scheme — the old tag was force-overwritten locally and on origin. Commit `be2a168` and the v1.15.11c CHANGELOG block (which references the slip) remain in history.
+
+### Bumped: opencode-ai 1.15.11 → 1.15.12
+
+Notable upstream changes (from the [anomalyco/opencode v1.15.12 release](https://github.com/anomalyco/opencode/releases/tag/v1.15.12)):
+
+- **Core** — ACP integrations can send prompts/slash-commands/usage updates through `acp-next`; experimental WebSocket transport for OpenAI Responses (`OPENCODE_EXPERIMENTAL_WEBSOCKETS=true`); adaptive reasoning enabled for Anthropic Opus 4.7+.
+- **Bugfixes** — colons allowed in passwords; faster warm `acp-next` model/config switches; OpenAI WebSocket response timeouts kept active with retries before fallback; `acp-next` permission prompts handled correctly; persisted session directory used for existing-session requests; remote workspace request bodies forwarded correctly; custom base URLs supported for OpenAI WebSocket Responses.
+- **TUI** — workspace management dialog; session navigation works while prompt modes are open; thinking spinner restored; subagent retry status surfaced; opening editors from non-Git project paths fixed.
+- **Desktop** — tab-layout setting; home empty state and V2 font usage improved; tab close buttons showing reliably.
+
+### Bumped: pi 0.76.0 → 0.77.0
+
+Notable upstream changes (from pi's CHANGELOG):
+
+- **Claude Opus 4.8 support** — model metadata + adaptive-thinking coverage updated.
+- **Selective tool disablement** — `--exclude-tools` / `-xt` disables specific built-in, extension, or custom tools while keeping the rest available.
+- **Headless Codex subscription login** — `/login` can use device-code auth for ChatGPT Plus/Pro Codex subscriptions.
+- **Streaming-aware extension input** — `InputEvent.streamingBehavior` lets extensions distinguish idle prompts, mid-stream steers, and queued follow-ups.
+- **Bugfixes** — startup timing output excludes `createAgentSessionRuntime`; OpenRouter DeepSeek V4 `xhigh` reasoning preserved; SIGTERM/SIGHUP run extension `session_shutdown` cleanly; keyboard protocol negotiation ignores delayed terminal responses; Windows MSYS2 ucrt64 startup crash fixed; API-key/header config resolution treats plain strings as literals with `$ENV_VAR` interpolation; session disposal aborts in-flight work; numerous provider-specific reasoning/metadata fixes (Codex Responses replay, OpenAI/OpenRouter GPT-5.5 Pro, Kimi K2.6, Xiaomi Token Plan).
+
+### Inheritance from base
+
+No base change — `base-latest` is reused unchanged from v1.15.11c (`base-decide` short-circuits at the Hub-probe step). SSH ControlMaster on a writable socket path, gitleaks, and git-crypt continue to ride along from the base.
+
+### Workflow status
+
+This is the first opencode-version-bump publish exercising the afternoon-of-2026-05-28 workflow changes (cache-export removal + 3-attempt retry wrapper) end-to-end on a real upstream release. v1.15.11c proved the publish path mechanically; v1.15.12 is the first one with both an opencode bump and a pi bump driving fresh variant layers.
 
 ## v1.15.11c — 2026-05-28
 

DOCKER_HUB.md

@@ -15,6 +15,11 @@ Designed for teams who want a reproducible coding-agent setup that runs the same
 
 All variants support `linux/amd64` and `linux/arm64`.
 
+> A fifth, pi-without-opencode build is produced from the same `Dockerfile.variant`
+> (`INSTALL_OPENCODE=false`) but is **not** published under this repo — it ships as
+> the separate [`joakimp/pi-devbox`](https://hub.docker.com/r/joakimp/pi-devbox)
+> image so an "opencode-devbox" tag never lacks opencode.
+
 ## Quick Start
 
 For a fully-configured environment with persistent state (opencode config, mempalace memory, neovim plugins, bash history) surviving container recreation, use docker-compose. **You don't need to clone the repo** — just grab two template files:

Dockerfile.variant

@@ -12,6 +12,12 @@
 #   omos               true              true          false
 #   with-pi            true              false         true
 #   omos-with-pi       true              true          true
+#   pi-only            false             false         true
+#
+# The `pi-only` variant is the single source of truth for the pi-devbox
+# image (pi + companions, no opencode). It exists so pi-devbox can FROM it
+# without inheriting opencode, while the pi install logic stays defined
+# here in one place.
 #
 # Pass `--build-arg BASE_IMAGE=<repo>:base-<hash>` to select the base.
 # The CI workflow computes the base hash from Dockerfile.base + rootfs/
@@ -36,7 +42,7 @@ ARG USER_NAME=developer
 # edit, so the cache-hit class of bug that bit pi-devbox v0.74.0..
 # v0.75.5 cannot apply here.
 ARG INSTALL_OPENCODE=true
-ARG OPENCODE_VERSION=1.15.11
+ARG OPENCODE_VERSION=1.15.13
 RUN if [ "${INSTALL_OPENCODE}" = "true" ]; then \
       NPM_CONFIG_PREFIX=/usr npm install -g opencode-ai@${OPENCODE_VERSION} && \
       opencode --version ; \
@@ -62,6 +68,17 @@ ARG INSTALL_PI=false
 ARG PI_VERSION=latest
 ARG PI_TOOLKIT_REF=main
 ARG PI_EXTENSIONS_REF=main
+# pi-fork (fork tool) + pi-observational-memory (recall tool) live on GitHub
+# under elpapi42. Refs default to the tracked branch for local dev; CI resolves
+# them to concrete commit SHAs (see resolve-versions in docker-publish-split.yml)
+# so the build-arg string changes when upstream moves — same registry-buildcache
+# cache-hit footgun the PI_VERSION/OMOS_VERSION pins guard against. The clone
+# helper for these uses `git fetch <ref>` (not `--branch`) so it accepts both
+# branch names and raw commit SHAs.
+ARG PI_FORK_REPO=https://github.com/elpapi42/pi-fork.git
+ARG PI_FORK_REF=master
+ARG PI_OBSMEM_REPO=https://github.com/elpapi42/pi-observational-memory.git
+ARG PI_OBSMEM_REF=master
 RUN if [ "${INSTALL_PI}" = "true" ]; then \
       set -e && \
       git_clone_retry() { \
@@ -74,6 +91,17 @@ RUN if [ "${INSTALL_PI}" = "true" ]; then \
         done; \
         return 1; \
       } && \
+      git_fetch_ref() { \
+        url="$1"; ref="$2"; dest="$3"; \
+        rm -rf "$dest"; mkdir -p "$dest"; \
+        git -C "$dest" init -q && git -C "$dest" remote add origin "$url" && \
+        for i in 1 2 3 4 5; do \
+          if git -C "$dest" fetch --depth 1 origin "$ref" && git -C "$dest" checkout -q FETCH_HEAD; then return 0; fi; \
+          echo "git fetch $url@$ref failed (attempt $i/5), retrying in $((i*5))s..."; \
+          sleep $((i*5)); \
+        done; \
+        return 1; \
+      } && \
       if [ "${PI_VERSION}" = "latest" ]; then \
         NPM_CONFIG_PREFIX=/usr npm install -g @earendil-works/pi-coding-agent ; \
       else \
@@ -82,8 +110,14 @@ RUN if [ "${INSTALL_PI}" = "true" ]; then \
       pi --version && \
       git_clone_retry https://gitea.jordbo.se/joakimp/pi-toolkit.git "${PI_TOOLKIT_REF}" /opt/pi-toolkit && \
       git_clone_retry https://gitea.jordbo.se/joakimp/pi-extensions.git "${PI_EXTENSIONS_REF}" /opt/pi-extensions && \
+      git_fetch_ref "${PI_FORK_REPO}"   "${PI_FORK_REF}"   /opt/pi-fork && \
+      git_fetch_ref "${PI_OBSMEM_REPO}" "${PI_OBSMEM_REF}" /opt/pi-observational-memory && \
+      (cd /opt/pi-fork && npm install --omit=dev --no-audit --no-fund) && \
+      (cd /opt/pi-observational-memory && npm install --omit=dev --no-audit --no-fund) && \
       echo "pi-toolkit at $(cd /opt/pi-toolkit && git rev-parse --short HEAD)" && \
-      echo "pi-extensions at $(cd /opt/pi-extensions && git rev-parse --short HEAD)" ; \
+      echo "pi-extensions at $(cd /opt/pi-extensions && git rev-parse --short HEAD)" && \
+      echo "pi-fork at $(cd /opt/pi-fork && git rev-parse --short HEAD)" && \
+      echo "pi-observational-memory at $(cd /opt/pi-observational-memory && git rev-parse --short HEAD)" ; \
     fi
 
 # ── Optional: Go ─────────────────────────────────────────────────────

README.md

@@ -132,6 +132,9 @@ docker compose exec -u developer devbox aws --version
 | `GIT_USER_EMAIL` | Git commit author email | — |
 | `WORKSPACE_PATH` | Host path to mount | `.` |
 | `SSH_KEY_PATH` | Host SSH key directory | `~/.ssh` |
+| `DEVBOX_LAN_ACCESS` | LAN-access mode: `auto` (jump only on VM-backed hosts), `jump` (always), `off` | `auto` |
+| `HOST_SSH_USER` | Username to SSH into the host as (required for the LAN jump) | — |
+| `DEVBOX_HOST_ALIAS` | Hostname used to reach the container host | `host.docker.internal` |
 | `USER_UID` | Override container user UID | Auto-detect from `/workspace` |
 | `USER_GID` | Override container user GID | Auto-detect from `/workspace` |
 | `LANG` | System locale | `en_US.UTF-8` |
@@ -144,6 +147,34 @@ docker compose exec -u developer devbox aws --version
 | `OMOS_RESET` | Force regenerate OMOS config on next start | `false` |
 | `SKILLSET_CONTAINER_PATH` | Path to skillset repo inside container (for auto-deploy when not at /workspace/skillset) | Auto-detect |
 
+### Reaching your LAN from the container
+
+The devbox works the same way whether the host is **native Linux Docker** or a **VM-backed** runtime (macOS OrbStack / Docker Desktop, or Docker Desktop on Windows) — but their networking differs:
+
+- **Native Linux Docker:** the host NATs container egress onto its LAN, so other devices on your LAN are reachable directly. Nothing to configure.
+- **VM-backed (macOS / Docker Desktop):** the container runs in a Linux VM behind the host's network stack. The host's *directly-attached* LAN peers are **not** bridged into the container by default — only the host itself and *routed* subnets are reachable.
+
+On every start the entrypoint detects which case applies. On VM-backed hosts it generates a writable `~/.ssh-local/config` that uses the **host as an SSH jump** to reach LAN peers; on native Linux it does nothing.
+
+**To enable it on a VM-backed host:**
+
+1. Set `HOST_SSH_USER=<your host username>` in `.env`.
+2. Start the container once. The entrypoint prints a public key — append it to your host's `~/.ssh/authorized_keys`.
+3. Ensure the host's SSH server is on (on macOS: System Settings → General → Sharing → Remote Login).
+4. Reach the host with `dssh host`, and reach LAN peers by adding `ProxyJump host` to their entries in your bind-mounted `~/.ssh/config`:
+
+```sshconfig
+# in your host ~/.ssh/config (mounted read-only into the container)
+Host my-nas
+    HostName 192.168.1.50
+    User admin
+    ProxyJump host
+```
+
+Then `dssh my-nas` routes container → host → LAN peer. (`dssh`/`dscp` wrap `ssh -F ~/.ssh-local/config`; the host config is pulled in via `Include`.)
+
+> This ships the **mechanism** only — your specific target hosts live in your own `~/.ssh/config`, never baked into the image. Set `DEVBOX_LAN_ACCESS=off` to disable, or `=jump` to force it (e.g. native Linux with `extra_hosts: ["host.docker.internal:host-gateway"]`).
+
 ### Custom opencode config
 
 Opencode configuration is persisted automatically via the named volume `devbox-opencode-config`. This volume is mounted at `/home/developer/.config/opencode` by default — no host directory setup required. All changes to `opencode.jsonc`, skills, and (on the OMOS variant) `oh-my-opencode-slim.json` survive container recreation.
@@ -432,7 +463,7 @@ All six agents should respond if your provider authentication is working.
 
 ### Setup
 
-Pre-built pi-enabled images are available on Docker Hub as `joakimp/opencode-devbox:latest-with-pi` (base + pi) and `joakimp/opencode-devbox:latest-omos-with-pi` (OMOS + pi). Pulling one of those tags is the fastest path. Alternatively, build from source:
+Pre-built pi-enabled images are available on Docker Hub as `joakimp/opencode-devbox:latest-with-pi` (base + pi) and `joakimp/opencode-devbox:latest-omos-with-pi` (OMOS + pi). Pulling one of those tags is the fastest path. If you want pi **without** opencode, use the separate, leaner [`joakimp/pi-devbox`](https://gitea.jordbo.se/joakimp/pi-devbox) image instead (it's built from the same `Dockerfile.variant` with `INSTALL_OPENCODE=false`, published in its own repo so an opencode-devbox tag never ships without opencode). Alternatively, build from source:
 
 ### Build
 

docs/manual-host-publish.md

@@ -101,8 +101,8 @@ After the constants are set, the script runs a 5-step procedure. No editing need
 1. **Preflight** — buildx present, tag exists, `HEAD == tag`, multi-arch builder created if missing.
 2. **Base build (conditional)** — probe `${IMAGE}:base-${BASE_HASH}` on the Hub; if missing, build it multi-arch and push. **No `--cache-from` / `--cache-to`.** That's the whole point of this escape. If the base push itself fails the same way CI did, stop — the regression has spread to image push and you need a different host or account, not this runbook.
 3. **Promote `base-latest`** — `docker buildx imagetools create` re-tags by manifest reference. No rebuild.
-4. **Variants × 4** — sequential (not parallel; one host's egress can't saturate four multi-arch pushes safely). Each variant is `Dockerfile.variant` `FROM ${IMAGE}:base-${BASE_HASH}` plus the appropriate `INSTALL_OMOS` / `INSTALL_PI` build-args, tagged `${RELEASE_TAG}${suffix}` and `latest${suffix}`.
+4. **Variants × 5** — sequential (not parallel; one host's egress can't saturate five multi-arch pushes safely). Each variant is `Dockerfile.variant` `FROM ${IMAGE}:base-${BASE_HASH}` plus the appropriate `INSTALL_OPENCODE` / `INSTALL_OMOS` / `INSTALL_PI` build-args, tagged `${RELEASE_TAG}${suffix}` and `latest${suffix}`.
-5. **Verify** — prints the digest of all 10 expected tags (8 variant + base-hash + base-latest). Spot-check that each `vX.Y.Z*` and its `latest*` alias share a digest.
+5. **Verify** — prints the digest of all 12 expected tags (10 variant + base-hash + base-latest). Spot-check that each `vX.Y.Z*` and its `latest*` alias share a digest.
 
 Expected wall time on a recent Mac: ~25-40 min (base ~3 min if rebuilt, each variant ~3-7 min mostly QEMU arm64 emulation).
 

docs/manual-host-publish.sh

@@ -5,11 +5,12 @@
 # Mirrors what .gitea/workflows/docker-publish-split.yml would do:
 #   1. Build & push Dockerfile.base    → joakimp/opencode-devbox:base-<hash>
 #   2. Promote                         → joakimp/opencode-devbox:base-latest
-#   3. Build & push 4 variants on top of base-<hash>:
+#   3. Build & push 5 variants on top of base-<hash>:
 #        :v1.15.12              :latest              (INSTALL_OPENCODE only)
 #        :v1.15.12-omos         :latest-omos         (+ OMOS)
 #        :v1.15.12-with-pi      :latest-with-pi      (+ pi)
 #        :v1.15.12-omos-with-pi :latest-omos-with-pi (+ both)
+#        :v1.15.12-pi-only      :latest-pi-only      (pi, no opencode)
 #
 # Usage on your host:
 #   1. Make sure Orbstack/Docker Desktop is running with multi-arch enabled
@@ -51,7 +52,7 @@ fi
 
 # -------- 1. base (if needed) --------
 if [[ "$SKIP_BASE" == "0" ]]; then
-  echo "==> [1/5] Build & push Dockerfile.base → ${IMAGE}:${BASE_TAG}"
+  echo "==> [1/7] Build & push Dockerfile.base → ${IMAGE}:${BASE_TAG}"
   docker buildx build \
     --platform "$PLATFORMS" \
     -f Dockerfile.base \
@@ -61,14 +62,15 @@ if [[ "$SKIP_BASE" == "0" ]]; then
 fi
 
 # -------- 2. promote base-latest --------
-echo "==> [2/5] Promote ${IMAGE}:${BASE_TAG} → ${IMAGE}:base-latest"
+echo "==> [2/7] Promote ${IMAGE}:${BASE_TAG} → ${IMAGE}:base-latest"
 docker buildx imagetools create -t "${IMAGE}:base-latest" "${IMAGE}:${BASE_TAG}"
 
 # -------- 3-5. variants --------
 build_variant() {
-  local suffix="$1"      # "" | "-omos" | "-with-pi" | "-omos-with-pi"
+  local suffix="$1"      # "" | "-omos" | "-with-pi" | "-omos-with-pi" | "-pi-only"
   local install_omos="$2"
   local install_pi="$3"
+  local install_opencode="${4:-true}"
   local extra_args=()
   [[ "$install_pi"   == "true" ]] && extra_args+=(--build-arg "PI_VERSION=${PI_VERSION}")
   [[ "$install_omos" == "true" ]] && extra_args+=(--build-arg "OMOS_VERSION=${OMOS_VERSION}")
@@ -81,7 +83,7 @@ build_variant() {
     --platform "$PLATFORMS" \
     -f Dockerfile.variant \
     --build-arg "BASE_IMAGE=${IMAGE}:${BASE_TAG}" \
-    --build-arg "INSTALL_OPENCODE=true" \
+    --build-arg "INSTALL_OPENCODE=${install_opencode}" \
     --build-arg "INSTALL_OMOS=${install_omos}" \
     --build-arg "INSTALL_PI=${install_pi}" \
     ${extra_args[@]+"${extra_args[@]}"} \
@@ -91,18 +93,21 @@ build_variant() {
     .
 }
 
-echo "==> [3/5] Variant: base (opencode only)"
+echo "==> [3/7] Variant: base (opencode only)"
 build_variant ""               false false
 
-echo "==> [4/5] Variant: omos"
+echo "==> [4/7] Variant: omos"
 build_variant "-omos"          true  false
 
-echo "==> [4/5] Variant: with-pi"
+echo "==> [5/7] Variant: with-pi"
 build_variant "-with-pi"       false true
 
-echo "==> [5/5] Variant: omos-with-pi"
+echo "==> [6/7] Variant: omos-with-pi"
 build_variant "-omos-with-pi"  true  true
 
+echo "==> [7/7] Variant: pi-only (pi without opencode)"
+build_variant "-pi-only"       false true  false
+
 echo
 echo "==> Done. Verifying tags on Hub:"
 for t in \
@@ -110,6 +115,7 @@ for t in \
   "${RELEASE_TAG}-omos" "latest-omos" \
   "${RELEASE_TAG}-with-pi" "latest-with-pi" \
   "${RELEASE_TAG}-omos-with-pi" "latest-omos-with-pi" \
+  "${RELEASE_TAG}-pi-only" "latest-pi-only" \
   "${BASE_TAG}" "base-latest"
 do
   d=$(docker manifest inspect "${IMAGE}:${t}" 2>/dev/null | python3 -c "import json,sys,hashlib; m=json.load(sys.stdin); print(m.get('digest','-'))" 2>/dev/null || echo "MISSING")

docs/plan-lan-access-and-pi-extensions.md

@@ -0,0 +1,235 @@
+# Plan: LAN-access mechanism + pi-fork/pi-observational-memory in the builds
+
+Status: PROPOSED (2026-06-03, decisions folded in). Author: pi (devbox session).
+Scope: opencode-devbox base + variant, pi-devbox. Two independent work items.
+
+---
+
+## Layering decision
+
+| Capability | Lives in | Why |
+|---|---|---|
+| **LAN-access (smart-detect host-jump)** | opencode-devbox **base** | Both opencode-devbox and pi-devbox inherit it; not pi-specific. |
+| **pi-fork + pi-observational-memory** | **pi layer** (variant `with-pi`/`omos-with-pi` + pi-devbox/Dockerfile) | Only meaningful when `pi` is present. Runtime deploy via the shared base `entrypoint-user.sh`, guarded by `command -v pi`. |
+
+Guiding principle for LAN access: **ship the mechanism, not the policy.**
+The image provides a generic `host` jump alias + writable SSH config + detection.
+A user's *specific* targets (e.g. pve/pve-2) come from their bind-mounted
+`~/.ssh/config` (`ProxyJump host`) or an env list — never hardcoded in the image.
+
+---
+
+## ITEM A — LAN access (opencode-devbox base)
+
+### Why it can't "just work" unattended
+- macOS (OrbStack / Docker Desktop): container is in a Linux VM behind the host's
+  stack. Directly-attached LAN peers are not bridged by default; only the host +
+  routed subnets are reachable.
+- Linux Docker: default bridge already NATs container egress onto the host's LAN,
+  so LAN peers are usually directly reachable. The jump is unnecessary.
+- The jump path needs the host running sshd + the container's pubkey authorized.
+  The average DockerHub t"kick the tires" user has neither → setup must be
+  **opt-in / non-fatal**, never block startup.
+
+### New file: `rootfs/usr/local/lib/opencode-devbox/setup-lan-access.sh`
+COPY'd automatically (base already does `COPY rootfs/usr/local/lib/opencode-devbox/`).
+
+Behavior, driven by `DEVBOX_LAN_ACCESS=auto|jump|off` (default `auto`):
+
+1. `off` → return immediately.
+2. Detect environment:
+   - VM-backed Docker (OrbStack / Docker Desktop) iff `getent hosts host.docker.internal`
+     resolves (OrbStack also exposes `host.orb.internal`). Native Linux → no resolution
+     (unless the user added `extra_hosts: host.docker.internal:host-gateway`).
+3. `auto` + native Linux → do nothing (direct LAN works); print one info line.
+4. `auto` + VM-backed, or `jump` forced →
+   - Create writable `~/.ssh-local/{,cm/}`, `chmod 700`.
+   - Generate `~/.ssh-local/devbox_jump_ed25519` if absent (preserve across restarts).
+   - Render `~/.ssh-local/config`:
+     ```
+     Host *
+         UserKnownHostsFile ~/.ssh-local/known_hosts
+         StrictHostKeyChecking accept-new
+     Host host mac                       # 'mac' kept as friendly alias
+         HostName host.docker.internal
+         User ${HOST_SSH_USER}           # REQUIRED for auth; see below
+         IdentityFile ~/.ssh-local/devbox_jump_ed25519
+         IdentitiesOnly yes
+         ControlMaster auto
+         ControlPath ~/.ssh-local/cm/%r@%h:%p
+         ControlPersist 4h
+     # Optional per-target blocks generated from DEVBOX_LAN_HOSTS (see below)
+     Include ~/.ssh/config               # user's bind-mounted targets still resolve
+     ```
+   - If `HOST_SSH_USER` unset → still render config but print a clear hint block:
+     the generated **public key** + the one-liner to authorize it on the host
+     (`echo '<pubkey>' >> ~/.ssh/authorized_keys`) + "enable Remote Login".
+   - Idempotent: re-render config each start (cheap); never regenerate the key.
+   - DECISION #5: NO `DEVBOX_LAN_HOSTS` env. Keep the image policy-free. Users add
+     `ProxyJump host` to their own target entries in the bind-mounted `~/.ssh/config`
+     (pulled in by the `Include ~/.ssh/config` line).
+
+### `entrypoint-user.sh`
+Call `setup-lan-access.sh` right after the existing `/tmp/sshcm` block
+(non-fatal: `… || true`). It's environment-gated so it self-skips on Linux.
+
+### `rootfs/home/developer/.bash_aliases`  (per your note — alias goes HERE)
+Append, guarded:
+```bash
+# dssh — ssh using the container's writable LAN-access config (host-jump).
+# Only useful when setup-lan-access.sh generated ~/.ssh-local/config.
+if [ -r "$HOME/.ssh-local/config" ]; then
+  alias dssh='ssh -F "$HOME/.ssh-local/config"'
+  alias dscp='scp -F "$HOME/.ssh-local/config"'
+fi
+```
+Migration caveat: skel `.bash_aliases` is only copied when absent, so existing
+volumes/containers won't get `dssh` until they `rm ~/.bash_aliases` and recreate,
+OR drop the alias into the host-shared `~/.config/devbox-shell/bash_aliases`
+(already sourced at the top of the skel file).
+
+### Dockerfile.base
+No structural change required (script ships via existing rootfs COPY). Optionally
+document `DEVBOX_LAN_ACCESS` / `HOST_SSH_USER` / `DEVBOX_LAN_HOSTS` in `.env.example`
+and README.
+
+---
+
+## ITEM B — pi-fork + pi-observational-memory (pi layer)
+
+Sources (pinned this week):
+- `github.com/elpapi42/pi-fork`                  (registers `fork`; ~v0.1.0)
+- `github.com/elpapi42/pi-observational-memory`  (registers `recall`; default branch **master**, v3.0.2)
+
+### B1 RESOLVED (verified live 2026-06-03 in this container)
+- `pi install <local-path>` is INSTANT (~0.5s): NO copy, NO npm install. pi registers
+  the path and loads the extension IN PLACE from that dir.
+- settings.json stores a RELATIVE path (e.g. `../../../opt/pi-fork` from ~/.pi/agent).
+  Points into the image-layer `/opt` → stable across volume recreate. Good.
+- Idempotent: a second `pi install <same path>` does NOT duplicate the entry.
+- CONSEQUENCE: because pi does NOT npm-install a local path, deps must already exist
+  at `/opt/<pkg>/node_modules`. pi-fork imports `@sinclair/typebox` + `@earendil-works/*`
+  peers; git-install produced a 148 MB node_modules. So we MUST `npm install` inside
+  each `/opt/<pkg>` AT BUILD TIME.
+- BAKE RECIPE: clone to /opt -> `npm install` there (build) -> `pi install /opt/<pkg>`
+  at runtime (instant, idempotent).
+- (Optional size win, verify-first: prune to external-only deps if pi provides the
+  `@earendil-works/*` peers from its own runtime resolution. ~148M is mostly those.)
+
+### DECISION #3: refactor to remove duplication
+`pi-devbox/Dockerfile` currently duplicates the pi-install + /opt-clone logic from
+`Dockerfile.variant`. Refactor `pi-devbox/Dockerfile` to `FROM` the `with-pi` variant
+image so pi-install logic (incl. the new fork/obsmem clones) lives in ONE place.
+
+> **Implementation update (2026-06-03):** `FROM with-pi` would have dragged opencode
+> into pi-devbox (all opencode-devbox variants set `INSTALL_OPENCODE=true`), making it
+> nearly identical to `latest-with-pi`. So a 5th variant **`pi-only`**
+> (`INSTALL_OPENCODE=false`, `INSTALL_PI=true`) was added to opencode-devbox, and
+> pi-devbox now `FROM`s `latest-pi-only`. Same single-source-of-truth win, but
+> pi-devbox stays lean (no opencode, ~145 MB lighter than with-pi).
+>
+> **Update 2 (2026-06-03, Option B):** publishing the pi-only variant as
+> `opencode-devbox:latest-pi-only` meant an "opencode-devbox" Hub tag that
+> contains no opencode — confusing. Final scheme: the pi-only build is still
+> produced by opencode-devbox CI (single source of truth) but its
+> `build-variant-pi-only` job pushes into the **`joakimp/pi-devbox`** repo as
+> the internal building-block tag `base-pi-only` (+ `base-pi-only-vX.Y.Z`), and
+> pi-devbox now `FROM`s `joakimp/pi-devbox:base-pi-only`. No opencode-less tag
+> ever appears under opencode-devbox; pi-only is de-advertised from
+> opencode-devbox's README/DOCKER_HUB. New `PI_IMAGE` workflow env.
+
+### Build time — clone to /opt + npm install (mirror pi-toolkit/extensions pattern)
+Add to the single `INSTALL_PI=true` block in `opencode-devbox/Dockerfile.variant`
+(after refactor, pi-devbox inherits it):
+```dockerfile
+ARG PI_FORK_REPO=https://github.com/elpapi42/pi-fork.git
+ARG PI_FORK_REF=<pin: tag or commit SHA>
+ARG PI_OBSMEM_REPO=https://github.com/elpapi42/pi-observational-memory.git
+ARG PI_OBSMEM_REF=master   # pin to SHA in CI to dodge cache-hit footgun
+# ... inside the INSTALL_PI / pi-install RUN, after the pi-toolkit/extensions clones:
+git_clone_retry "$PI_FORK_REPO"   "$PI_FORK_REF"   /opt/pi-fork && \
+git_clone_retry "$PI_OBSMEM_REPO" "$PI_OBSMEM_REF" /opt/pi-observational-memory && \
+(cd /opt/pi-fork && npm install --no-audit --no-fund) && \
+(cd /opt/pi-observational-memory && npm install --no-audit --no-fund) && \
+echo "pi-fork at $(cd /opt/pi-fork && git rev-parse --short HEAD)" && \
+echo "pi-obsmem at $(cd /opt/pi-observational-memory && git rev-parse --short HEAD)"
+```
+NOTE: `git_clone_retry` uses `--branch "$ref"`, which accepts tags & branches but
+NOT arbitrary commit SHAs. For SHA pinning use `git clone <url> <dest> && git -C
+<dest> checkout <sha>` for these two repos.
+
+### Why not bake the install result
+`~/.pi` is a named volume mounted at runtime — anything `pi install`'d into
+`~/.pi/agent/...` at BUILD time is hidden by the volume. Same reason
+pi-toolkit/extensions deploy at runtime via `entrypoint-user.sh`. So:
+
+### Runtime deploy — `entrypoint-user.sh` (shared base, in the `command -v pi` block)
+After the pi-extensions `install.sh` call, add an idempotent install of each /opt pkg:
+```bash
+for pkg in /opt/pi-fork /opt/pi-observational-memory; do
+  [ -d "$pkg" ] || continue
+  name=$(basename "$pkg")
+  # skip if already registered in settings.json packages
+  if ! grep -q "$name" "$HOME/.pi/agent/settings.json" 2>/dev/null; then
+    (cd "$HOME" && pi install "$pkg") || echo "WARN: pi install $name failed (continuing)"
+  fi
+done
+```
+`fork` + `recall` tools register on the NEXT pi start after deploy (exts bind at
+startup). First deploy after a volume recreate pays an `npm install` cost
+(pi-fork pulls ~133 deps) — acceptable, one-time per volume lifetime.
+
+OPEN ITEM B1 (verify before finalizing): exact `pi install <local-path>` semantics
+— does it copy/symlink, and does it npm-install at run each time? If it re-resolves
+deps every start, pre-populate `/opt/<pkg>/node_modules` at build (`npm install
+--omit=dev`) and confirm the runtime install reuses it. Quick test in this container:
+`pi install /opt/pi-fork` twice, observe settings.json + timing + tool registration.
+
+### CI — `.gitea/workflows/docker-publish-split.yml` (DECISION #2: latest-but-pinned)
+- USE LATEST CONTENT, BUT RESOLVE TO A SHA IN CI (same pattern as PI_VERSION/OMOS).
+  The existing `resolve-versions` job curls npm `latest` for pi/omos to defeat the
+  build-arg cache-hit footgun. Add an analogous resolve for the two git repos:
+  query the GitHub API for the HEAD commit SHA of the tracked branch (master) and
+  pass it as `PI_FORK_REF` / `PI_OBSMEM_REF` build-args, so the layer hash changes
+  when upstream moves AND we still get newest-at-build-time.
+- Passing a bare branch name would be byte-identical across builds -> stale cached
+  layer (the documented footgun). SHA resolution fixes both.
+- Pass the new build-args in the `with-pi` and `omos-with-pi` build steps.
+- The resolved SHAs print in build logs (and ideally as image labels) so a bad
+  upstream is diagnosable and we can pin back to a known-good SHA.
+
+### Version coupling risk (carry-over from prior session)
+pi-fork/obsmem extensions are coupled to the host pi version (AGENTS.md warns).
+pi-fork had a `fix/effort-string-enum-schema` branch from recent API churn. So:
+- Pin against the SAME `PI_VERSION` the image ships.
+- smoke-test must assert the tools actually register (below), not just that files exist.
+
+### Smoke test — `scripts/smoke-test.sh`
+Add (for `with-pi`/`omos-with-pi`/pi-devbox):
+1. `/opt/pi-fork/package.json` and `/opt/pi-observational-memory/package.json` exist.
+2. Run a container, then assert `~/.pi/agent/settings.json` "packages" includes both.
+3. Best-effort: headless `pi` tool-list contains `fork` and `recall` (if pi exposes a
+   non-interactive list; otherwise step 2 is the gate).
+
+---
+
+## Decisions — RESOLVED 2026-06-03
+1. **B1**: VERIFIED. Local-path install is instant/in-place; bake `npm install` into
+   `/opt/<pkg>` at build; runtime `pi install /opt/<pkg>` is instant + idempotent. ✓
+2. **Latest-but-pinned**: track latest (master HEAD), resolve to SHA in CI build-arg. ✓
+3. **Refactor**: pi-devbox/Dockerfile -> `FROM` the with-pi variant; pi-install in ONE place. ✓
+4. **LAN default** `DEVBOX_LAN_ACCESS=auto`: generate config + print authorize hint when
+   `HOST_SSH_USER` unset; silent no-op on native Linux. ✓
+5. **No `DEVBOX_LAN_HOSTS`**: rely on user's bind-mounted `~/.ssh/config` (`ProxyJump host`). ✓
+
+## Remaining verify-before-merge items
+- Confirm the fork/recall extensions LOAD at runtime from `/opt/<pkg>` WITH the baked
+  node_modules (smoke test asserts tool registration, not just files).
+- Optional: confirm whether pi supplies `@earendil-works/*` peers at runtime so /opt
+  node_modules can be pruned to external-only deps (size optimization, ~148M -> small).
+
+## Rollout order
+1. Verify B1 in this live container (cheap, no build).
+2. Land ITEM A in base (rootfs script + entrypoint call + alias) → rebuild base → smoke.
+3. Land ITEM B in variant + pi-devbox + CI resolve + smoke assertions.
+4. CHANGELOG + tag both repos; CI rebuild; verify fork+recall+dssh survive a volume recreate.

entrypoint-user.sh

@@ -12,6 +12,16 @@ set -euo pipefail
 mkdir -p /tmp/sshcm
 chmod 700 /tmp/sshcm
 
+# ── LAN access: generic host-OS-agnostic reachability helper ────────
+# On VM-backed hosts (macOS OrbStack / Docker Desktop) the container can't
+# reach the host's directly-attached LAN peers by default; this generates a
+# writable ~/.ssh-local/config that uses the host as an SSH jump. On native
+# Linux (LAN reachable directly) it is a no-op. Controlled by DEVBOX_LAN_ACCESS
+# (auto|jump|off) + HOST_SSH_USER. Always non-fatal. See the script header.
+if [ -r /usr/local/lib/opencode-devbox/setup-lan-access.sh ]; then
+  bash /usr/local/lib/opencode-devbox/setup-lan-access.sh || true
+fi
+
 # ── Shell defaults: copy baked files from /etc/skel-devbox/ if absent
 # Respects host bind-mounts and user customizations — existing files
 # are never overwritten. To restore defaults: rm ~/.bash_aliases (or
@@ -96,6 +106,24 @@ if command -v pi &>/dev/null; then
     ln -sf /opt/mempalace-toolkit/extensions/pi/mempalace.ts \
            "$HOME/.pi/agent/extensions/mempalace.ts"
   fi
+
+  # pi-fork (fork tool) + pi-observational-memory (recall tool).
+  # These are pi packages (not symlink-style extensions): they're cloned to
+  # /opt with node_modules baked at BUILD time, then registered here via
+  # `pi install <local-path>`. Verified 2026-06-03: a local-path install is
+  # instant + in-place (pi loads the extension directly from /opt) + idempotent
+  # (no duplicate package entry on re-run), and stores a relative path that
+  # resolves into the image-layer /opt so it survives volume recreate. The
+  # fork/recall tools register on the NEXT pi start (extensions bind at
+  # startup). Guard on settings.json so we only install once per volume.
+  for _pkg in /opt/pi-fork /opt/pi-observational-memory; do
+    [ -d "$_pkg" ] || continue
+    _name=$(basename "$_pkg")
+    if ! grep -q "$_name" "$HOME/.pi/agent/settings.json" 2>/dev/null; then
+      pi install "$_pkg" >/dev/null 2>&1 || \
+        echo "WARN: pi install $_name failed (continuing)"
+    fi
+  done
 fi
 
 # ── Skillset: deploy skills/instructions from mounted skillset repo ──

rootfs/home/developer/.bash_aliases

@@ -54,6 +54,17 @@ alias gs='git status'
 alias gd='git diff'
 alias gl='git log --oneline --graph --decorate -20'
 
+# ── LAN access via the host (dssh) ───────────────────────────────────
+# When running on a VM-backed host (macOS OrbStack / Docker Desktop), the
+# entrypoint's setup-lan-access.sh generates ~/.ssh-local/config so the host
+# can be used as an SSH jump to reach LAN peers. These aliases wrap `ssh -F`
+# / `scp -F` against that config. Guarded so they only appear when the config
+# was actually generated (no-op / absent on native Linux hosts).
+if [ -r "$HOME/.ssh-local/config" ]; then
+  alias dssh='ssh -F "$HOME/.ssh-local/config"'
+  alias dscp='scp -F "$HOME/.ssh-local/config"'
+fi
+
 # Safety: confirm before destructive ops
 alias rm='rm -i'
 alias mv='mv -i'

rootfs/usr/local/lib/opencode-devbox/setup-lan-access.sh

@@ -0,0 +1,133 @@
+#!/usr/bin/env bash
+# setup-lan-access.sh — generic, host-OS-agnostic LAN reachability helper.
+#
+# THE PROBLEM
+#   On macOS (OrbStack / Docker Desktop) and Docker Desktop on Windows, the
+#   container runs inside a Linux VM behind the host's network stack. The
+#   host's *directly-attached* LAN peers (e.g. other boxes on 192.168.1.0/24)
+#   are NOT bridged into the container by default — only the host itself and
+#   *routed* subnets are reachable. On native Linux Docker the default bridge
+#   already NATs container egress onto the host's LAN, so LAN peers are usually
+#   reachable directly and no workaround is needed.
+#
+# THE APPROACH ("detect, and on a VM-backed host use the host as a jump")
+#   The one thing reachable from a container on every OS is the host itself
+#   (host.docker.internal). So on VM-backed hosts we generate a writable SSH
+#   config that reaches the host and lets the user ProxyJump onward to LAN
+#   peers the host can reach. On native Linux we do nothing.
+#
+#   We ship the MECHANISM (a generic `host` jump alias + writable config),
+#   never the POLICY: the user's specific target hosts live in their own
+#   bind-mounted ~/.ssh/config (add `ProxyJump host` to those entries) — which
+#   is pulled in via the `Include ~/.ssh/config` line below.
+#
+# WHY A WRITABLE SIDECAR (~/.ssh-local)
+#   The devbox typically bind-mounts the host's ~/.ssh READ-ONLY (so agents
+#   can read keys for git but can't tamper with config/known_hosts/authorized_
+#   keys). That means we cannot edit ~/.ssh/config or write ~/.ssh/known_hosts.
+#   So everything generated here lives under the writable ~/.ssh-local, used
+#   via `ssh -F ~/.ssh-local/config` (the `dssh`/`dscp` aliases wrap that).
+#
+# CONTROLS (env)
+#   DEVBOX_LAN_ACCESS = auto (default) | jump | off
+#       auto  → set up the jump config only on VM-backed hosts; no-op on Linux.
+#       jump  → always set up (e.g. native Linux with extra_hosts host-gateway).
+#       off   → do nothing.
+#   HOST_SSH_USER  — the username to SSH into the host as. REQUIRED for the
+#       jump to authenticate. If unset we still generate the config but print
+#       a hint with the public key to authorize on the host.
+#   DEVBOX_HOST_ALIAS — host hostname to reach (default host.docker.internal).
+#
+# Idempotent: re-renders the config every run (cheap); never regenerates the
+# key. Always non-fatal — never blocks container startup.
+
+set -uo pipefail
+
+MODE="${DEVBOX_LAN_ACCESS:-auto}"
+[ "$MODE" = "off" ] && exit 0
+
+HOST_ALIAS_HOSTNAME="${DEVBOX_HOST_ALIAS:-host.docker.internal}"
+SSH_LOCAL="${HOME}/.ssh-local"
+CONFIG="${SSH_LOCAL}/config"
+KEY="${SSH_LOCAL}/devbox_jump_ed25519"
+
+# ── Detection: is this a VM-backed host (macOS / Docker Desktop)? ──────
+# host.docker.internal resolves on OrbStack and Docker Desktop (mac/win) but
+# NOT on native Linux Docker (unless the user added extra_hosts: host-gateway,
+# in which case the jump is still harmless / usable, and they can force it
+# with DEVBOX_LAN_ACCESS=jump).
+is_vm_backed() {
+  getent hosts "$HOST_ALIAS_HOSTNAME" >/dev/null 2>&1
+}
+
+if [ "$MODE" = "auto" ] && ! is_vm_backed; then
+  # Native Linux host: LAN peers are reachable directly. Nothing to do.
+  exit 0
+fi
+
+# From here: MODE=jump, or MODE=auto on a VM-backed host.
+
+command -v ssh-keygen >/dev/null 2>&1 || exit 0
+
+mkdir -p "${SSH_LOCAL}/cm" 2>/dev/null || true
+chmod 700 "${SSH_LOCAL}" "${SSH_LOCAL}/cm" 2>/dev/null || true
+
+# ── Jump key (generated once; preserved across restarts) ──────────────
+if [ ! -f "$KEY" ]; then
+  ssh-keygen -t ed25519 -N '' -C "devbox-jump@${HOSTNAME:-container}" -f "$KEY" >/dev/null 2>&1 || exit 0
+  chmod 600 "$KEY" 2>/dev/null || true
+fi
+
+# ── Render the writable config ────────────────────────────────────────
+USER_LINE=""
+if [ -n "${HOST_SSH_USER:-}" ]; then
+  USER_LINE="    User ${HOST_SSH_USER}"
+fi
+
+INCLUDE_LINE=""
+if [ -r "${HOME}/.ssh/config" ]; then
+  INCLUDE_LINE="Include ~/.ssh/config"
+fi
+
+cat > "$CONFIG" <<EOF
+# AUTO-GENERATED by setup-lan-access.sh on every container start. Do not edit
+# by hand — edits are overwritten. Used via: ssh -F ~/.ssh-local/config <host>
+# (or the dssh / dscp aliases). See the script header for the full rationale.
+
+# ~/.ssh is typically mounted read-only, so keep our own known_hosts here.
+Host *
+    UserKnownHostsFile ~/.ssh-local/known_hosts
+    StrictHostKeyChecking accept-new
+
+# The container host (OrbStack / Docker Desktop). 'host' and 'mac' are aliases.
+Host host mac
+    HostName ${HOST_ALIAS_HOSTNAME}
+${USER_LINE}
+    IdentityFile ~/.ssh-local/devbox_jump_ed25519
+    IdentitiesOnly yes
+    ControlMaster auto
+    ControlPath ~/.ssh-local/cm/%r@%h:%p
+    ControlPersist 4h
+    ServerAliveInterval 30
+
+# Your own target hosts: add 'ProxyJump host' to their entries in your
+# bind-mounted ~/.ssh/config, pulled in below.
+${INCLUDE_LINE}
+EOF
+chmod 600 "$CONFIG" 2>/dev/null || true
+
+# ── One-time hint when we can't authenticate yet ──────────────────────
+if [ -z "${HOST_SSH_USER:-}" ]; then
+  cat <<EOF
+[devbox] LAN-access jump config generated at ~/.ssh-local/config, but
+         HOST_SSH_USER is unset so it can't authenticate to the host yet.
+         To enable container -> host -> LAN-peer access:
+           1. Set HOST_SSH_USER=<your host username> in the container env.
+           2. Authorize this key on the host (append to ~/.ssh/authorized_keys):
+                $(cat "${KEY}.pub" 2>/dev/null)
+           3. Ensure the host's SSH server (Remote Login) is enabled.
+         Then: dssh host   (or add 'ProxyJump host' to targets in ~/.ssh/config)
+EOF
+fi
+
+exit 0

scripts/generate-dockerhub-md.py

@@ -69,6 +69,11 @@ Designed for teams who want a reproducible coding-agent setup that runs the same
 
 All variants support `linux/amd64` and `linux/arm64`.
 
+> A fifth, pi-without-opencode build is produced from the same `Dockerfile.variant`
+> (`INSTALL_OPENCODE=false`) but is **not** published under this repo — it ships as
+> the separate [`joakimp/pi-devbox`](https://hub.docker.com/r/joakimp/pi-devbox)
+> image so an "opencode-devbox" tag never lacks opencode.
+
 ## Quick Start
 
 For a fully-configured environment with persistent state (opencode config, mempalace memory, neovim plugins, bash history) surviving container recreation, use docker-compose. **You don't need to clone the repo** — just grab two template files:

scripts/smoke-test.sh

@@ -8,7 +8,7 @@
 #   - Generated opencode.json has the expected shape
 #   - MCP wrapper works (when mempalace is installed)
 #
-# Usage: ./scripts/smoke-test.sh <image> [--variant base|omos|with-pi|omos-with-pi]
+# Usage: ./scripts/smoke-test.sh <image> [--variant base|omos|with-pi|omos-with-pi|pi-only]
 #
 # Exit codes:
 #   0  all checks passed
@@ -23,7 +23,7 @@ if [ "${2:-}" = "--variant" ]; then
 fi
 
 if [ -z "$IMAGE" ]; then
-  echo "usage: $0 <image> [--variant base|omos|with-pi|omos-with-pi]" >&2
+  echo "usage: $0 <image> [--variant base|omos|with-pi|omos-with-pi|pi-only]" >&2
   exit 2
 fi
 
@@ -171,6 +171,13 @@ if docker run --rm --entrypoint="" "$IMAGE" sh -c "command -v pi" >/dev/null 2>&
   fi
   run "pi-toolkit clone"         "test -d /opt/pi-toolkit && git -C /opt/pi-toolkit rev-parse --short HEAD"
   run "pi-extensions clone"      "test -d /opt/pi-extensions && git -C /opt/pi-extensions rev-parse --short HEAD"
+  # pi-fork (fork tool) + pi-observational-memory (recall tool): cloned to
+  # /opt with node_modules baked at build time (a local-path `pi install` does
+  # NOT npm-install, so deps MUST already be present for the extension to load).
+  run "pi-fork clone + node_modules" \
+      "test -f /opt/pi-fork/package.json && test -d /opt/pi-fork/node_modules && echo ok"
+  run "pi-observational-memory clone + node_modules" \
+      "test -f /opt/pi-observational-memory/package.json && test -d /opt/pi-observational-memory/node_modules && echo ok"
 
   # Run the full entrypoint as developer to verify install.sh deployment.
   # Spin up a long-running container so we can `docker exec` into it from
@@ -208,6 +215,21 @@ if docker run --rm --entrypoint="" "$IMAGE" sh -c "command -v pi" >/dev/null 2>&
   exec_test "~/.pi/agent/settings.json (template bootstrap)" \
             'test -f $HOME/.pi/agent/settings.json && echo ok'
 
+  # pi-fork + pi-observational-memory are registered by entrypoint-user.sh via
+  # `pi install /opt/<pkg>` (records a relative path into settings.json
+  # packages). That runs slightly after the keybindings marker, so wait for it.
+  for _ in $(seq 1 15); do
+    if docker exec "$CID" grep -q pi-observational-memory \
+         /home/developer/.pi/agent/settings.json 2>/dev/null; then
+      break
+    fi
+    sleep 1
+  done
+  exec_test "pi-fork registered in settings.json (fork tool)" \
+            'grep -q pi-fork $HOME/.pi/agent/settings.json && echo ok'
+  exec_test "pi-observational-memory registered in settings.json (recall tool)" \
+            'grep -q pi-observational-memory $HOME/.pi/agent/settings.json && echo ok'
+
   docker rm -f "$CID" >/dev/null 2>&1 || true
   trap - EXIT
 else
@@ -336,12 +358,21 @@ echo "  Uncompressed size: ${SIZE_MB} MB"
 # omos-with-pi bumped 3500→3700 on v1.15.4b — omos+pi compounded as both
 # upstream packages grew (opencode 1.15.0→1.15.4, pi 0.74.0→0.75.3) and
 # the variant landed just over 3500 in v1.15.4's smoke.
+# with-pi 2700→2900 and omos-with-pi 3700→3900: baking pi-fork +
+# pi-observational-memory node_modules into /opt (fork pulls its
+# @earendil-works peer deps, ~150 MB) adds to both pi-bearing variants.
+# base 2500→2600 on v1.15.13c — base crept to 2506 MB (LAN-access script +
+# updated entrypoint + routine apt-get upgrade drift), tripping the
+# deliberately zero-headroom 2500 ceiling and skipping promote-base-latest.
 # omos variant to ~3.1 GB. Functional smoke checks all pass; this is a
 # guardrail, not a performance limit.
-THRESHOLD=2500
+THRESHOLD=2600
 [ "$VARIANT" = "omos" ] && THRESHOLD=3300
-[ "$VARIANT" = "with-pi" ] && THRESHOLD=2700
+[ "$VARIANT" = "with-pi" ] && THRESHOLD=2900
-[ "$VARIANT" = "omos-with-pi" ] && THRESHOLD=3700
+[ "$VARIANT" = "omos-with-pi" ] && THRESHOLD=3900
+# pi-only = with-pi minus opencode (its platform binary is ~145 MB), so it
+# lands a bit under base. Threshold 2750 leaves the same headroom pattern.
+[ "$VARIANT" = "pi-only" ] && THRESHOLD=2750
 if [ "$SIZE_MB" -gt "$THRESHOLD" ]; then
   fail "image size ${SIZE_MB} MB exceeds threshold ${THRESHOLD} MB for variant=$VARIANT"
 else