fix(ssh): survive read-only ~/.ssh ControlPath; render sidecar on all host OSes

Coordinated with the pi-extensions ssh-controlmaster fix (picked up at build via
PI_EXTENSIONS_REF=main), this makes `pi --ssh <host>` and `dssh`/`dscp` robust
to a user ~/.ssh/config whose per-host ControlPath points under the read-only
~/.ssh bind-mount (e.g. `ControlPath ~/.ssh/cm/%r@%h:%p`). A system default can
never override a user's per-host value, so the fix lives in two layers.

- setup-lan-access.sh: always render the writable ~/.ssh-local/config sidecar
  (Host * ControlPath redirect into ~/.ssh-local/cm + Include ~/.ssh/config) on
  EVERY host OS. Previously the script exited early (no-op) on native Linux,
  leaving dssh/dscp broken when ~/.ssh was read-only there too. The host-jump
  block, its key generation, and the authorize hints stay gated on VM-backed
  detection / DEVBOX_LAN_ACCESS=jump (new NEED_JUMP flag).
- Dockerfile.base: document that the /etc/ssh drop-in default cannot override a
  user per-host ControlPath; cross-ref the two handling layers.
- entrypoint-user.sh: correct the now-stale "no-op on native Linux" comment.
- README.md / DOCKER_HUB.md: document read-only-~/.ssh ControlPath handling.

CHANGELOG: v1.1.5 (Fixed + Changed + pi 0.79.6 -> 0.79.7 auto-resolved bump).

AGENTS.md

@@ -45,6 +45,8 @@ re-brand of opencode-devbox's `pi-only` variant.
 
 1. Confirm `pi --version` resolves from npm to the expected version
    (`curl -sf 'https://registry.npmjs.org/@earendil-works%2Fpi-coding-agent/latest' | jq -r .version`).
+   Check release notes at https://github.com/earendil-works/pi/releases for
+   the upstream changelog to include in `CHANGELOG.md`.
 2. Update `CHANGELOG.md` Unreleased → vX.Y.Z section.
 3. Verify `docker compose up` works locally with the current `latest` image
    if you're upgrading users from a previous version. Then run the

CHANGELOG.md

@@ -13,14 +13,132 @@ Pre-v1.0.0 tags followed the pi npm version (`v{pi_version}[letter]`).
 
 ## Unreleased
 
+## v1.1.5 — 2026-06-18
+
+Patch release: SSH ControlMaster read-only-socket fix + pi `0.79.6` → `0.79.7`
+(auto-resolved at build). The `pi-extensions` ref is auto-resolved to `main`
+HEAD at build, so the `ssh-controlmaster` fix below lands automatically.
+
+### Fixed
+
+- **`pi --ssh <host>` no longer fails with "Read-only file system" when the
+  user's `~/.ssh/config` sets a per-host `ControlPath` under the read-only
+  `~/.ssh` mount** (e.g. the common CGNAT idiom `ControlPath ~/.ssh/cm/%r@%h:%p`).
+  Root cause: SSH precedence means a user's per-host `ControlPath` always wins
+  over the baked `/etc/ssh/ssh_config.d` default, so the master socket tried to
+  bind under the RO `~/.ssh` and `ssh … pwd` exited 255 ("Could not resolve
+  remote pwd"). The `ssh-controlmaster` extension (pulled from `pi-extensions`
+  `main` via `PI_EXTENSIONS_REF`) now (a) resolves the remote pwd with a direct
+  connection (`-o ControlPath=none -o ControlMaster=no`), and (b) tests whether
+  the system `ControlPath` dir is actually writable — falling back to its own
+  `/tmp` master (whose command-line `-o ControlPath` overrides the user's path)
+  when it is not. OS-agnostic and independent of whether the user uses
+  ControlMaster, so the majority of configs (no ControlMaster at all) are
+  unaffected.
+
+### Changed
+
+- **`setup-lan-access.sh` now renders the writable SSH sidecar
+  (`~/.ssh-local/config`) on every host OS, not just VM-backed ones.**
+  Previously the whole script no-oped on native Linux, so a Linux host that
+  also bind-mounts `~/.ssh` read-only got no `ControlPath` redirect. The
+  `ControlPath` redirect + `Include ~/.ssh/config` (and `dssh`/`dscp` usability)
+  now work on Linux too; only the host-jump block (`Host host mac`), its key
+  generation, and the authorize hints remain gated on VM-backed detection
+  (`DEVBOX_LAN_ACCESS=auto`) or `=jump`.
+
+### Bumped: pi 0.79.6 → 0.79.7
+
+Notable upstream changes (from [pi releases](https://github.com/earendil-works/pi/releases/tag/v0.79.7)):
+
+- **Automatic theme mode** — `/settings` can choose separate light and dark
+  themes and follow terminal color-scheme changes (`/` is now reserved in
+  theme names for this).
+- **Self-only `pi update` by default** — bare `pi update` updates pi only;
+  `pi update --all` updates pi and packages together.
+- **Extension API helpers** — `CONFIG_DIR_NAME` exported so extensions resolve
+  project config paths without hardcoding `.pi`; edit-diff helpers
+  (`generateDiffString`, `generateUnifiedPatch`, `EditDiffResult`) exported.
+- **Warp inline images** via Kitty graphics capability detection.
+- Fixes: RPC unknown-command errors now include the request id (clients no
+  longer hang); `/model` autocomplete matches provider/model regardless of
+  token order; tree navigator horizontally pans deep entries.
+
+## v1.1.4 — 2026-06-17
+
+Patch release: config and shell-quality fixes on a preserved volume. No pi
+version bump (still `0.79.6`, latest). The `pi-toolkit` ref is auto-resolved
+to `main` HEAD at build, so the AGENTS.md change below lands automatically.
+
+### Added
+
+- **Global `AGENTS.md` auto-loads the pi-extensions skill.** `pi-toolkit` now
+  ships `pi-global-AGENTS.md` and symlinks it to `~/.pi/agent/AGENTS.md` (pi's
+  global-instructions file, loaded at every start). It directs the agent to
+  read the `pi-extensions` skill at session start and carries a core
+  fork/recall cheat-sheet, since on-demand skill description-matching was
+  leaving `pi-fork` / `pi-observational-memory` under-utilised. **Heads-up:**
+  on a preserved volume any pre-existing real `~/.pi/agent/AGENTS.md` is backed
+  up to `*.bak.<timestamp>` and replaced by the symlink (same behavior as
+  `keybindings.json`).
+- **`settings.json` merge-on-recreate.** The bootstrap only ever copied the
+  template when `settings.json` was *absent*, so a file on a preserved volume
+  never picked up config added in a later image (e.g. the
+  `observational-memory` / `pi-fork` blocks, a newly-enabled model). The
+  entrypoint now deep-merges the template into an existing `settings.json` on
+  start with `jq -s '.[0] * .[1]'` (template first, live second): the user's
+  values always win and only *missing* keys are filled in. Arrays are treated
+  as leaves (a model the user removed is not re-added); the file is only
+  rewritten when the merge changes something, the original is backed up first,
+  and invalid JSON on either side is skipped rather than clobbered. Opt out
+  with `PI_SETTINGS_MERGE=0`.
+
+### Fixed
+
+- **bash history loss in nested / tmux shells.** The `DEVBOX_HIST_SET` guard
+  that installs the per-prompt `history -a` flush was `export`ed, so it leaked
+  into child processes. Any nested shell — crucially each tmux pane, which
+  inherits the tmux server's env — saw the guard already set and skipped
+  installing `history -a`, persisting history only on a clean exit. Abrupt
+  termination (`docker stop`, `tmux kill-server`, SIGKILL) then silently lost
+  that shell's in-memory history. The guard is now shell-local (no `export`),
+  so every new interactive shell re-installs its own flush. `zoxide` was less
+  affected (its hook is unguarded and writes immediately). History and zoxide
+  storage were never the issue — `~/.cache/bash` (`devbox-shell-history`) and
+  `~/.local/share/zoxide` (`devbox-zoxide`) are persistent named volumes.
+  **Note:** existing shells/panes keep the old behavior until restarted
+  (`tmux kill-server` or open fresh shells).
+
+### Maintainer
+
+- `scripts/recreate-sanity-check.sh` gained assertions for the new wiring: the
+  `~/.pi/agent/AGENTS.md` symlink, a nested login shell installing
+  `history -a`, and `settings.json` carrying the `observational-memory` +
+  `pi-fork` blocks after recreate.
+
+---
+
 ## v1.1.3 — 2026-06-16
 
 Patch release: pi `0.79.4` → `0.79.5` (auto-resolved at build).
 
-### Changed
+### Bumped: pi 0.79.4 → 0.79.5
 
-- **pi bumped to `0.79.5`** (published upstream 2026-06-16). No image-side
-  changes beyond the pi npm version.
+Notable upstream changes (from [pi releases](https://github.com/earendil-works/pi/releases/tag/v0.79.5)):
+
+- **Provider-scoped API key environments** — `auth.json` API key entries can
+  now include `env` overrides for provider-specific Cloudflare, Azure OpenAI,
+  Google Vertex, Amazon Bedrock, cache retention, and proxy settings without
+  changing the project shell.
+- **Global HTTP proxy setting** — configure `httpProxy` once in global settings
+  to apply `HTTP_PROXY` / `HTTPS_PROXY` to Pi-managed HTTP clients.
+- **Vercel AI Gateway attribution** — requests now include Pi attribution
+  headers by default.
+- **Fixes:** inherited OpenAI Responses streaming tolerates null message content
+  before tool calls; DeepSeek V4 thinking no longer sends both `thinking` and
+  `reasoning_effort`; device-code login no longer auto-opens the browser;
+  various Google/Vertex Gemini model metadata corrections; session selector
+  empty-state fix; Cursor Up history navigation fix.
 
 ---
 

DOCKER_HUB.md

@@ -97,7 +97,7 @@ The entrypoint deploys/registers all of these on first container start. Re-runni
 
 ### SSH and networking
 
-- OpenSSH client with **ControlMaster auto** preconfigured on a writable socket path (`/tmp/sshcm/`). Mitigates ssh banner-exchange failures behind CGNAT-restricted residential ISPs (~4-flow caps).
+- OpenSSH client with **ControlMaster auto** preconfigured on a writable socket path (`/tmp/sshcm/`). Mitigates ssh banner-exchange failures behind CGNAT-restricted residential ISPs (~4-flow caps). A read-only `~/.ssh` carrying a per-host `ControlPath` (common CGNAT configs) is handled too — redirected to a writable socket dir for both `pi --ssh` and `dssh`/`dscp`.
 - A **LAN-access helper** that auto-configures ssh jump-via-host on VM-backed hosts (OrbStack / Docker Desktop on macOS) so the container can reach the host's directly-attached LAN peers (`dssh <peer>` alias; `DEVBOX_LAN_ACCESS` / `HOST_SSH_USER`).
 
 ## Versioning

Dockerfile.base

@@ -130,6 +130,15 @@ RUN printf '%s\n' \
 # `Include /etc/ssh/ssh_config.d/*.conf` *before* the `Host *` block,
 # so user config can override these defaults if desired.
 #
+# CAVEAT (and why it is handled elsewhere): a user per-host override that
+# points ControlPath BACK under the read-only ~/.ssh (e.g. the common CGNAT
+# idiom `ControlPath ~/.ssh/cm/%r@%h:%p`) re-introduces the unwritable-socket
+# failure — a system drop-in here can never override a user's per-host value.
+# For `pi --ssh`, the ssh-controlmaster extension handles this by detecting an
+# unwritable system ControlPath and falling back to its own /tmp master; for
+# `ssh -F ~/.ssh-local/config` (dssh/dscp), setup-lan-access.sh redirects
+# ControlPath into the writable ~/.ssh-local. See CHANGELOG "Unreleased".
+#
 # ControlPersist=10m means the master socket sticks around 10 min after
 # the last session closes, so consecutive ssh calls in a workflow reuse
 # the same TCP flow. Companion entrypoint-user.sh creates /tmp/sshcm

README.md

@@ -82,6 +82,9 @@ For Python REPLs and notebooks beyond the system interpreter, see the
 - A LAN-access helper that auto-configures ssh jump-via-host on
   VM-backed hosts (OrbStack / Docker Desktop on macOS) so the container
   can reach the host's directly-attached LAN peers.
+- Read-only `~/.ssh` is handled transparently: a per-host `ControlPath`
+  under it (common CGNAT configs like `~/.ssh/cm/...`) is redirected to a
+  writable socket dir for both `pi --ssh` and `dssh`/`dscp`.
 
 ## Quickstart
 
@@ -461,6 +464,23 @@ User-level overrides in `~/.ssh/config` win because Debian's
 `/etc/ssh/ssh_config` includes `/etc/ssh/ssh_config.d/*.conf` before
 the `Host *` block.
 
+### Per-host `ControlPath` on a read-only `~/.ssh`
+
+`~/.ssh` is usually bind-mounted read-only, so a user `~/.ssh/config` that
+points `ControlPath` back under it (e.g. the CGNAT idiom
+`ControlPath ~/.ssh/cm/%r@%h:%p`) can't bind its master socket here — and a
+system default can never override a user's per-host value. Two layers handle
+this without editing the read-only config:
+
+- **`pi --ssh <host>`** — the `ssh-controlmaster` extension detects an
+  unwritable system `ControlPath` and falls back to its own writable
+  `/tmp/pi-cm-<pid>.sock` master (its command-line `-o ControlPath` overrides
+  the user's path); the remote-`pwd` probe uses `-o ControlPath=none` so it
+  cannot fail on the read-only socket dir.
+- **`ssh -F ~/.ssh-local/config` / `dssh` / `dscp`** — `setup-lan-access.sh`
+  redirects `ControlPath` into the writable `~/.ssh-local/cm` for every host
+  (the sidecar is rendered on all host OSes).
+
 ## tmux and 0-indexed sessions
 
 The image installs `/etc/tmux.conf` with:

entrypoint-user.sh

@@ -12,12 +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.
+# ── LAN access + writable SSH sidecar: host-OS-agnostic helper ──────
+# Generates the writable ~/.ssh-local/config on EVERY host OS: a `Host *`
+# ControlPath redirect into ~/.ssh-local/cm (so `ssh -F` / dssh / dscp work
+# even when ~/.ssh is bind-mounted read-only) plus `Include ~/.ssh/config`. On
+# VM-backed hosts (macOS OrbStack / Docker Desktop) it ALSO adds an
+# SSH-jump-via-host block so the container can reach the host's
+# directly-attached LAN peers; on native Linux (LAN reachable directly) the
+# jump block is omitted but the sidecar is still rendered. Controlled by
+# DEVBOX_LAN_ACCESS (auto|jump|off) + HOST_SSH_USER. Always non-fatal. See the
+# script header.
 if [ -r /usr/local/lib/pi-devbox/setup-lan-access.sh ]; then
   bash /usr/local/lib/pi-devbox/setup-lan-access.sh || true
 fi
@@ -86,9 +90,35 @@ if command -v pi &>/dev/null; then
 
   # Bootstrap settings.json from template if absent (pi rewrites this
   # file at runtime — lastChangelogVersion, etc — so we can't symlink it).
-  if [ ! -f "$HOME/.pi/agent/settings.json" ] && \
-     [ -f /opt/pi-toolkit/settings.example.json ]; then
-    cp /opt/pi-toolkit/settings.example.json "$HOME/.pi/agent/settings.json"
+  _pi_settings="$HOME/.pi/agent/settings.json"
+  _pi_template=/opt/pi-toolkit/settings.example.json
+  if [ ! -f "$_pi_settings" ] && [ -f "$_pi_template" ]; then
+    cp "$_pi_template" "$_pi_settings"
+    echo "pi settings.json bootstrapped from template"
+  elif [ -f "$_pi_settings" ] && [ -f "$_pi_template" ] && \
+       [ "${PI_SETTINGS_MERGE:-1}" != "0" ] && command -v jq >/dev/null 2>&1; then
+    # Non-destructive merge: a settings.json on a PRESERVED volume never
+    # otherwise sees new template keys (the bootstrap above only fires when
+    # the file is absent), so config added in an image upgrade — e.g. the
+    # observational-memory / pi-fork blocks or a newly-enabled model — never
+    # reaches existing users. Deep-merge with the template FIRST and the
+    # live file SECOND ('.[0] * .[1]') so the user's values always win and
+    # only keys MISSING from the live file are filled in from the template.
+    # Arrays are treated as leaves (the user's array is kept verbatim, so a
+    # model they deliberately removed is not re-added). Only rewrite when the
+    # merge actually changes something, and back up the original first.
+    # Set PI_SETTINGS_MERGE=0 to disable. Invalid JSON on either side → skip,
+    # never clobber.
+    if _pi_merged=$(jq -s '.[0] * .[1]' "$_pi_template" "$_pi_settings" 2>/dev/null); then
+      if [ -n "$_pi_merged" ] && \
+         ! printf '%s' "$_pi_merged" | jq -e --slurpfile cur "$_pi_settings" '. == $cur[0]' >/dev/null 2>&1; then
+        cp "$_pi_settings" "${_pi_settings}.bak.$(date +%Y%m%d-%H%M%S)"
+        printf '%s\n' "$_pi_merged" > "$_pi_settings"
+        echo "pi settings.json: merged new template keys from settings.example.json (backup saved)"
+      fi
+    else
+      echo "WARN: pi settings.json merge skipped (jq could not parse template or live file; left untouched)"
+    fi
   fi
 
   # pi↔mempalace MCP bridge — single extension symlink.

rootfs/home/developer/.bash_aliases

@@ -89,9 +89,16 @@ fi
 # we append with a newline separator to avoid the ';;' parse error
 # described at the top of this file. Guarded so repeated sourcing
 # (e.g. `exec bash`) doesn't stack duplicates.
+#
+# The guard MUST stay shell-local (NOT exported): if it leaks into child
+# processes, every nested shell -- crucially each tmux pane, which inherits
+# the tmux server's env -- skips installing `history -a` and only persists
+# history on a clean exit. Abrupt termination (docker stop, tmux kill-server,
+# SIGKILL) then loses that shell's in-memory history. Keeping it unexported
+# means each new interactive shell re-installs its own per-prompt flush.
 if [ -z "${DEVBOX_HIST_SET:-}" ]; then
   PROMPT_COMMAND="${PROMPT_COMMAND:+$PROMPT_COMMAND$'\n'}history -a"
-  export DEVBOX_HIST_SET=1
+  DEVBOX_HIST_SET=1
 fi
 
 # ── Prompt: show [opencode-devbox] tag so it's obvious you're in the container

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

@@ -14,7 +14,9 @@
 #   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.
+#   peers the host can reach. On native Linux we render the same writable
+#   config (for the ControlPath redirect + Include ~/.ssh/config) but emit no
+#   jump block, since LAN peers are reachable directly there.
 #
 #   We ship the MECHANISM (a generic `host` jump alias + writable config),
 #   never the POLICY: the user's specific target hosts live in their own
@@ -30,7 +32,9 @@
 #
 # CONTROLS (env)
 #   DEVBOX_LAN_ACCESS = auto (default) | jump | off
-#       auto  → set up the jump config only on VM-backed hosts; no-op on Linux.
+#       auto  → set up the host jump only on VM-backed hosts. The writable
+#               sidecar config (ControlPath redirect + Include) is always
+#               rendered, on every OS.
 #       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
@@ -84,42 +88,72 @@ 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
-
+# ── Writable socket dir + sidecar (ALWAYS, every host OS) ─────────────
+# The ControlPath redirect in the generated config needs a writable directory
+# regardless of host OS or jump mode. ~/.ssh is typically read-only, so the
+# master socket lives under the writable ~/.ssh-local. We create it and render
+# the config UNCONDITIONALLY so the redirect (and `Include ~/.ssh/config`) works
+# even on native Linux — where we set up no host jump but a read-only ~/.ssh
+# would otherwise still break ControlMaster sockets.
 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) ──────────────
+# ── Decide whether to set up the host jump ────────────────────────────
+# Jump = reach the container host (host.docker.internal) as an SSH ProxyJump
+# onward to the host's LAN peers. Needed on VM-backed hosts (macOS / Docker
+# Desktop) or when forced with DEVBOX_LAN_ACCESS=jump. On native Linux LAN
+# peers are reachable directly, so NEED_JUMP=0 and we emit no jump block — but
+# we still render the config for the ControlPath redirect + Include.
+NEED_JUMP=0
+if [ "$MODE" = "jump" ] || { [ "$MODE" = "auto" ] && is_vm_backed; }; then
+  NEED_JUMP=1
+fi
+
+# ── Jump key (only when a jump is needed; generated once, preserved) ──
 # 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
+if [ "$NEED_JUMP" = "1" ] && command -v ssh-keygen >/dev/null 2>&1 && [ ! -f "$KEY" ]; then
+  if ssh-keygen -t ed25519 -N '' -C "devbox-jump@${HOSTNAME:-container}" -f "$KEY" >/dev/null 2>&1; then
+    chmod 600 "$KEY" 2>/dev/null || true
+    KEY_JUST_GENERATED=1
+  fi
 fi
 
 # ── Render the writable config ────────────────────────────────────────
-USER_LINE=""
-if [ -n "${HOST_SSH_USER:-}" ]; then
-  USER_LINE="    User ${HOST_SSH_USER}"
-fi
-
-# Optional host-owned named-peer jump overrides (portable: lives on the host,
-# not in the image). Included BEFORE ~/.ssh/config so its ProxyJump wins.
-SSH_LAN_CONF="${HOME}/.config/devbox-shell/ssh-lan.conf"
+# Jump-specific blocks (the host alias, host-owned peer overrides, and the
+# optional RFC1918 catch-all) only make sense when a jump is set up; on native
+# Linux they are all empty and only the ControlPath redirect + Include remain.
+JUMP_BLOCK=""
 LAN_CONF_BLOCK=""
-if [ -r "$SSH_LAN_CONF" ]; then
-  LAN_CONF_BLOCK=$(cat <<'EOF'
+AUTOJUMP_BLOCK=""
+if [ "$NEED_JUMP" = "1" ]; then
+  USER_LINE=""
+  if [ -n "${HOST_SSH_USER:-}" ]; then
+    USER_LINE="    User ${HOST_SSH_USER}"
+  fi
+  JUMP_BLOCK=$(cat <<EOF
+
+# 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
+EOF
+)
+
+  # Optional host-owned named-peer jump overrides (portable: lives on the host,
+  # not in the image). Included BEFORE ~/.ssh/config so its ProxyJump wins.
+  SSH_LAN_CONF="${HOME}/.config/devbox-shell/ssh-lan.conf"
+  if [ -r "$SSH_LAN_CONF" ]; then
+    LAN_CONF_BLOCK=$(cat <<'EOF'
 
 # Host-owned named-peer jump overrides (bind-mounted; edit on the host).
 # Scope reset to match-all so the Include applies to every target host.
@@ -127,14 +161,13 @@ Host *
 Include ~/.config/devbox-shell/ssh-lan.conf
 EOF
 )
-fi
+  fi
 
-# Optional opt-in RFC1918 catch-all: ProxyJump every private IP through the
-# host. Matches the typed address, never the resolved HostName, so named hosts
-# with their own ProxyJump are unaffected. Network-agnostic → roaming-safe.
-AUTOJUMP_BLOCK=""
-if [ "${DEVBOX_LAN_AUTOJUMP_PRIVATE:-0}" = "1" ]; then
-  AUTOJUMP_BLOCK=$(cat <<'EOF'
+  # Optional opt-in RFC1918 catch-all: ProxyJump every private IP through the
+  # host. Matches the typed address, never the resolved HostName, so named hosts
+  # with their own ProxyJump are unaffected. Network-agnostic → roaming-safe.
+  if [ "${DEVBOX_LAN_AUTOJUMP_PRIVATE:-0}" = "1" ]; then
+    AUTOJUMP_BLOCK=$(cat <<'EOF'
 
 # RFC1918 auto-jump (DEVBOX_LAN_AUTOJUMP_PRIVATE=1): reach any private IP on
 # the host's CURRENT LAN via bare `dssh user@<ip>`. Public IPs are unmatched
@@ -146,6 +179,7 @@ Host 10.* 192.168.* 172.16.* 172.17.* 172.18.* 172.19.* 172.20.* 172.21.* 172.22
     ProxyJump host
 EOF
 )
+  fi
 fi
 
 INCLUDE_BLOCK=""
@@ -176,17 +210,7 @@ Host *
     UserKnownHostsFile ~/.ssh-local/known_hosts
     StrictHostKeyChecking accept-new
     ControlPath ~/.ssh-local/cm/%r@%h:%p
-
-# 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
+${JUMP_BLOCK}
 ${LAN_CONF_BLOCK}
 ${AUTOJUMP_BLOCK}
 ${INCLUDE_BLOCK}
@@ -199,6 +223,7 @@ chmod 600 "$CONFIG" 2>/dev/null || true
 # 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.
+if [ "$NEED_JUMP" = "1" ]; then
 PUBKEY_TEXT="$(cat "${KEY}.pub" 2>/dev/null)"
 if [ -z "${HOST_SSH_USER:-}" ]; then
   cat <<EOF
@@ -221,5 +246,6 @@ elif [ "$KEY_JUST_GENERATED" = "1" ]; then
          repeat this on container updates — only if that volume is reset.
 EOF
 fi
+fi
 
 exit 0

scripts/recreate-sanity-check.sh

@@ -6,8 +6,8 @@
 #     version is supplied — see the version note below)
 #   - Persisted named volumes survived (~/.pi config, shell history, zoxide,
 #     nvim data, uv cache, ssh-local)
-#   - pi runtime wiring is intact: keybindings symlink, ≥4 extensions, the
-#     mempalace.ts bridge, settings.json, and the pi-fork /
+#   - pi runtime wiring is intact: keybindings symlink, AGENTS.md symlink,
+#     ≥4 extensions, the mempalace.ts bridge, settings.json, and the pi-fork /
 #     pi-observational-memory / (studio variant) pi-studio package registrations
 #   - Shell defaults re-seeded from /etc/skel-devbox
 #   - /tmp/sshcm exists with mode 700 (ssh ControlMaster dir)
@@ -157,6 +157,14 @@ else
   fail "~/.pi/agent/keybindings.json missing or not a symlink"
 fi
 
+# global AGENTS.md symlink (pi-toolkit) — global instructions loaded by pi at
+# every start (directs the agent to read the pi-extensions skill at session start)
+if [ -L "$HOME/.pi/agent/AGENTS.md" ]; then
+  pass "~/.pi/agent/AGENTS.md symlink (pi-toolkit)"
+else
+  fail "~/.pi/agent/AGENTS.md missing or not a symlink"
+fi
+
 # extensions deployed (pi-extensions) — expect ≥4 *.ts
 EXT_COUNT=$(ls -1 "$HOME"/.pi/agent/extensions/*.ts 2>/dev/null | wc -l | tr -d ' ')
 if [ "$EXT_COUNT" -ge 4 ]; then
@@ -179,6 +187,18 @@ else
   fail "~/.pi/agent/settings.json missing"
 fi
 
+# settings.json merge: the entrypoint deep-merges new template keys into a
+# preserved settings.json on every start, so config added in an image upgrade
+# (e.g. the observational-memory / pi-fork blocks) reaches existing volumes.
+# Assert those blocks are present and that the file is still valid JSON.
+if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.pi/agent/settings.json" ]; then
+  if jq -e 'has("observational-memory") and has("pi-fork")' "$HOME/.pi/agent/settings.json" >/dev/null 2>&1; then
+    pass "settings.json has observational-memory + pi-fork blocks (template merge)"
+  else
+    fail "settings.json missing observational-memory and/or pi-fork blocks (template merge did not land)"
+  fi
+fi
+
 # pi package registrations (pi install <local-path> → recorded in settings.json)
 if [ -f "$HOME/.pi/agent/settings.json" ]; then
   for pkg in pi-fork pi-observational-memory; do
@@ -214,6 +234,16 @@ else
   fail "~/.bash_aliases missing"
 fi
 
+# History flush must survive shell nesting. The DEVBOX_HIST_SET guard must NOT
+# be exported: if it leaks into child processes, nested shells (esp. tmux
+# panes) skip installing `history -a` and lose in-memory history on abrupt
+# termination. Assert a child login shell still wires up the per-prompt flush.
+if bash -lic 'bash -lic "case \"\$PROMPT_COMMAND\" in *\"history -a\"*) exit 0;; *) exit 1;; esac"' </dev/null >/dev/null 2>&1; then
+  pass "nested shell installs 'history -a' (DEVBOX_HIST_SET not exported)"
+else
+  fail "nested shell missing 'history -a' — DEVBOX_HIST_SET leaking to children?"
+fi
+
 if [ -f "$HOME/.inputrc" ]; then
   pass "~/.inputrc exists"
 else