smoke: gate fork/recall registration checks behind STRICT_REGISTRATION (#12)

validate.yml builds variants FROM the published base-latest, which lags
the entrypoint in the current commit until a release tag rebuilds the
base. The fork/recall registration smoke checks depend on the base
entrypoint running 'pi install /opt/<pkg>', so a stale base-latest reded
push-to-main runs with a false negative even when the variant layer was
correct.

smoke-test.sh now gates the two registration assertions behind
STRICT_REGISTRATION (warn-only when unset). validate.yml leaves it unset;
docker-publish-split.yml, which builds the base fresh in the same run,
sets STRICT_REGISTRATION=1 on the pi-bearing smoke jobs. Build-time /opt
+ node_modules checks stay hard in both paths.

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

@@ -386,6 +386,7 @@ jobs:
             PI_OBSMEM_REF=${{ needs.resolve-versions.outputs.obsmem_ref }}
       - env:
           EXPECTED_PI_VERSION: ${{ needs.resolve-versions.outputs.pi_version }}
+          STRICT_REGISTRATION: "1"
         run: bash scripts/smoke-test.sh opencode-devbox:smoke-with-pi --variant with-pi
 
   smoke-omos-with-pi:
@@ -435,6 +436,7 @@ jobs:
       - env:
           EXPECTED_PI_VERSION: ${{ needs.resolve-versions.outputs.pi_version }}
           EXPECTED_OMOS_VERSION: ${{ needs.resolve-versions.outputs.omos_version }}
+          STRICT_REGISTRATION: "1"
         run: bash scripts/smoke-test.sh opencode-devbox:smoke-omos-with-pi --variant omos-with-pi
 
   smoke-pi-only:
@@ -482,6 +484,7 @@ jobs:
             PI_OBSMEM_REF=${{ needs.resolve-versions.outputs.obsmem_ref }}
       - env:
           EXPECTED_PI_VERSION: ${{ needs.resolve-versions.outputs.pi_version }}
+          STRICT_REGISTRATION: "1"
         run: bash scripts/smoke-test.sh opencode-devbox:smoke-pi-only --variant pi-only
 
   # ── Phase 4: multi-arch publish per variant ────────────────────────

.gitea/workflows/validate.yml

@@ -20,6 +20,14 @@ name: Validate
 # release tags are the gate that fully validates base-image changes.
 # The base-change-warning job below surfaces a runtime warning when this
 # blind-spot applies.
+#
+# Because of this, the fork/recall *registration* smoke checks (which depend on
+# the base entrypoint running `pi install /opt/<pkg>`) are warn-only here:
+# smoke-test.sh leaves STRICT_REGISTRATION unset on this path, so a base-latest
+# that lags the entrypoint in the current commit can't red the run with a false
+# negative. The release smoke jobs build the base fresh and set
+# STRICT_REGISTRATION=1 to enforce those checks. The build-time /opt +
+# node_modules checks stay hard in both paths.
 
 on:
   push:

CHANGELOG.md

@@ -8,7 +8,47 @@ Tags follow `v{opencode_version}[letter]` — bare tag for the first build on a
 
 ## Unreleased
 
-_(no changes since v1.15.13d)_
+### Fixed: validate.yml false-negative on fork/recall registration checks
+
+The push-to-main `validate.yml` builds variants FROM the published `base-latest`
+image, which lags the entrypoint in the current commit until a release tag
+rebuilds the base. The fork/recall *registration* smoke checks depend on the
+base entrypoint running `pi install /opt/<pkg>`, so a stale `base-latest` reded
+those runs with a false negative even when the variant layer was correct.
+`smoke-test.sh` now gates the two registration assertions behind
+`STRICT_REGISTRATION` (warn-only when unset). `validate.yml` leaves it unset;
+the release pipeline (`docker-publish-split.yml`), which builds the base fresh
+in the same run, sets `STRICT_REGISTRATION=1` on the pi-bearing smoke jobs to
+enforce them. The build-time `/opt` + `node_modules` checks stay hard in both
+paths.
+
+### Added: persist the LAN-jump key + one-line authorize hint (authorize once per machine)
+
+The jump keypair (`~/.ssh-local/devbox_jump_ed25519`) was stored on the
+container's ephemeral overlay, so `docker compose up --force-recreate` (every
+image update) regenerated it — forcing you to re-authorize the new key on the
+host each time. The compose files now persist `~/.ssh-local` via a named volume
+(`devbox-ssh-local`), matching the pattern already used for `.pi`, shell
+history, etc. The key is generated **once** and reused across updates, so you
+authorize it on the host **once per machine**.
+
+`setup-lan-access.sh` now also prints a ready-to-paste authorize line whenever
+it generates a **new** key (not just when `HOST_SSH_USER` is unset), e.g.
+`echo 'ssh-ed25519 …' >> ~/.ssh/authorized_keys` — no helper file to locate, no
+workspace path to guess. It stays silent once the key is persisted.
+
+### Fixed: chown the `devbox-ssh-local` volume so the jump key can be generated
+
+The previous change persisted `~/.ssh-local` via a named volume, but the
+entrypoint's volume-ownership loop was never updated to include it. Docker
+creates named volumes as `root:root`, so on a fresh volume `~/.ssh-local`
+stayed root-owned while `setup-lan-access.sh` runs as `developer` — both its
+`mkdir cm` and `ssh-keygen` failed silently (`|| true` / `|| exit 0`), leaving
+**no jump key and no config**, breaking LAN access on the first recreate after
+the persistence change. `entrypoint.sh` now chowns `~/.ssh-local` to the
+developer user alongside the other named-volume mount points.
+
+_(no other changes since v1.15.13d)_
 
 ## v1.15.13d — 2026-06-04
 

README.md

@@ -155,15 +155,20 @@ The devbox works the same way whether the host is **native Linux Docker** or a *
 - **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.
+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. The jump keypair lives in `~/.ssh-local`, which is persisted by the `devbox-ssh-local` named volume — so it's generated **once** and reused across container updates.
 
-**To enable it on a VM-backed host:**
+**To enable it on a VM-backed host (one-time setup per machine):**
 
 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`.
+2. Start the container once. When it generates the jump key it prints a ready-to-paste line — run it **on the host** to authorize the key:
+   ```bash
+   echo 'ssh-ed25519 AAAA…devbox-jump@…' >> ~/.ssh/authorized_keys
+   ```
 3. Ensure the host's SSH server is on (on macOS: System Settings → General → Sharing → Remote Login).
 4. Reach the host itself with `dssh host`. (`dssh`/`dscp` wrap `ssh -F ~/.ssh-local/config`.)
 
+Because the key is persisted, you do this **once per machine** — not after every `docker compose up --force-recreate`. You'll only see the authorize line again if you reset the `devbox-ssh-local` volume.
+
 That alone gets you `container → host`. To reach **named LAN peers** by name, give them a `ProxyJump host` override. Don't add it to the shared `~/.ssh/config` entries — the host itself reaches those peers *directly*, and a jump-through-`host` would break the host's own access (and that file is mounted read-only anyway). Instead, drop the overrides in a **host-owned** file that the container Includes ahead of your `~/.ssh/config`:
 
 ```sshconfig

docker-compose.yml

@@ -59,6 +59,11 @@ services:
       # allowing both native and containerized opencode on the same machine.
       - devbox-opencode-config:/home/developer/.config/opencode
       - devbox-pi-config:/home/developer/.pi
+      # Persist the generated LAN-jump keypair (~/.ssh-local) across recreates.
+      # setup-lan-access.sh generates this key once and reuses it; persisting
+      # it means you authorize it on the host ONCE rather than re-authorizing
+      # after every `docker compose up --force-recreate`.
+      - devbox-ssh-local:/home/developer/.ssh-local
 
       # NOTE: Do NOT bind-mount ~/.agents/skills/ from the host. The
       # container manages its own skills directory independently — the
@@ -95,6 +100,14 @@ services:
       # - ~/.bash_aliases:/home/developer/.bash_aliases:ro
        # - ~/.inputrc:/home/developer/.inputrc:ro
 
+      # Optional: host-owned shell config + LAN jump overrides (recommended
+      # over the single-file ~/.bash_aliases mount above — it's a directory,
+      # so it survives editors' atomic-save). The image's ~/.bash_aliases
+      # sources ~/.config/devbox-shell/bash_aliases if present, and
+      # setup-lan-access.sh reads ~/.config/devbox-shell/ssh-lan.conf for
+      # named-peer `ProxyJump host` overrides (see ssh-lan.conf.example).
+      # - ~/.config/devbox-shell:/home/developer/.config/devbox-shell:ro
+
       # Optional: persist uv data (Python installs, tool installs)
       # Without this, 'uv python install' must be re-run after container removal.
       - devbox-uv:/home/developer/.local/share/uv
@@ -126,6 +139,7 @@ services:
 volumes:
   devbox-opencode-config:
   devbox-pi-config:
+  devbox-ssh-local:
   devbox-data:
   devbox-state:
   devbox-shell-history:

entrypoint.sh

@@ -88,6 +88,7 @@ for dir in \
   /home/"$USER_NAME"/.config/opencode \
   /home/"$USER_NAME"/.config/nvim \
   /home/"$USER_NAME"/.pi \
+  /home/"$USER_NAME"/.ssh-local \
   /home/"$USER_NAME"/.agents/skills; do
   [ -d "$dir" ] || continue
 

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

@@ -97,9 +97,15 @@ 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) ──────────────
+# Persisted via a named volume on ~/.ssh-local (see compose), so a fresh key
+# is generated only on the very first start (or if the volume is wiped). When
+# we DO generate one it must be (re-)authorized on the host, so we flag it and
+# print a copy-paste authorize line below.
+KEY_JUST_GENERATED=0
 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
+  KEY_JUST_GENERATED=1
 fi
 
 # ── Render the writable config ────────────────────────────────────────
@@ -187,18 +193,33 @@ ${INCLUDE_BLOCK}
 EOF
 chmod 600 "$CONFIG" 2>/dev/null || true
 
-# ── One-time hint when we can't authenticate yet ──────────────────────
+# ── Authorize hints ───────────────────────────────────────────────────
+# Print the copy-paste authorize line whenever we either (a) can't yet
+# authenticate (HOST_SSH_USER unset) or (b) just generated a NEW key that the
+# host won't recognize. With ~/.ssh-local persisted via a named volume, case
+# (b) fires only on first-ever start (or after the volume is reset) — so this
+# is normally a one-time, one-line step per machine, with no file to locate.
+PUBKEY_TEXT="$(cat "${KEY}.pub" 2>/dev/null)"
 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)
+           2. Authorize this key on the host (run ON THE HOST, once):
+                echo '${PUBKEY_TEXT}' >> ~/.ssh/authorized_keys
            3. Ensure the host's SSH server (Remote Login) is enabled.
          Then: dssh host   (or add 'ProxyJump host' to targets in ~/.ssh/config)
 EOF
+elif [ "$KEY_JUST_GENERATED" = "1" ]; then
+  cat <<EOF
+[devbox] Generated a NEW LAN-jump key. Authorize it on the host (${HOST_SSH_USER}@host),
+         then 'dssh host' and your LAN peers will work. Run this ONCE, ON THE HOST:
+           echo '${PUBKEY_TEXT}' >> ~/.ssh/authorized_keys
+         (Ensure the host's SSH server / Remote Login is enabled.)
+         This key is persisted in the ~/.ssh-local volume, so you won't need to
+         repeat this on container updates — only if that volume is reset.
+EOF
 fi
 
 exit 0

scripts/smoke-test.sh

@@ -30,6 +30,19 @@ fi
 FAILED=0
 pass() { echo "  ✓ $1"; }
 fail() { echo "  ✗ $1" >&2; FAILED=$((FAILED + 1)); }
+warn() { echo "  ⚠ $1" >&2; }
+
+# Registration assertions (fork/recall installed by the BASE image's
+# entrypoint-user.sh via `pi install /opt/<pkg>`) depend on the base, not the
+# variant layer built here. validate.yml builds variants FROM the published
+# base-latest, which can lag the entrypoint in the current commit (the base
+# only rebuilds on a release tag), so a stale base-latest would red the
+# push-to-main run with a false negative. These checks are therefore warn-only
+# by default; the release pipeline (docker-publish-split.yml) builds the base
+# fresh in the same run and sets STRICT_REGISTRATION=1 to enforce them hard.
+# The build-time /opt + node_modules checks below stay hard in every path —
+# those are produced by the variant layer and must always be correct.
+STRICT_REGISTRATION="${STRICT_REGISTRATION:-0}"
 
 run() {
   # Run a command inside the image and capture its output.
@@ -206,6 +219,19 @@ if docker run --rm --entrypoint="" "$IMAGE" sh -c "command -v pi" >/dev/null 2>&
     fi
   }
 
+  # Like exec_test but warn-only unless STRICT_REGISTRATION=1 (see note at top).
+  exec_test_reg() {
+    local label="$1"; shift
+    local out
+    if out=$(docker exec -u developer "$CID" sh -c "$*" 2>&1); then
+      pass "$label ($(echo "$out" | head -1))"
+    elif [ "$STRICT_REGISTRATION" = "1" ]; then
+      fail "$label: $out"
+    else
+      warn "$label (warn-only — stale base-latest? set STRICT_REGISTRATION=1 to enforce): $out"
+    fi
+  }
+
   exec_test "~/.pi/agent/keybindings.json (pi-toolkit)" \
             'test -L $HOME/.pi/agent/keybindings.json && echo ok'
   exec_test "~/.pi/agent/extensions/*.ts ≥ 4 (pi-extensions)" \
@@ -225,9 +251,9 @@ if docker run --rm --entrypoint="" "$IMAGE" sh -c "command -v pi" >/dev/null 2>&
     fi
     sleep 1
   done
-  exec_test "pi-fork registered in settings.json (fork tool)" \
+  exec_test_reg "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)" \
+  exec_test_reg "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