release(v1.11.0): pi 1.1.0, pi-obsmem 022da5e, pi-atelier v0.15.0, all floating refs at newest

- ARG PI_VERSION 1.0.0 -> 1.1.0. Audited against the npm tarballs: the only breaking change in 1.0.1..1.1.0 is 1.0.3's azure-openai-responses -> azure rename, which nothing here uses. pi-agent-core's finishTurn handling is byte-identical between 1.0.0 and 1.1.0. - ARG PI_OBSMEM_REF 731c3d4 -> 022da5e (= master): #81 compaction keeps unobserved context, #93 prebuilt dist/index.ts. src/agents/ unchanged. - ARG PI_ATELIER_REF/VERSION v0.13.0 -> v0.15.0. Sidebar Auto/Manual modes, Manual by default. README's sidebar section updated. - SKILLSET_SNAPSHOT_REF e9e45f7 -> 96b840e via vendor-mempalace-skill.sh. The vendored bytes are unchanged. - Dockerfile.base BASE_REBUILD_DATE marker refreshed, at no cost, because the base rebuilds anyway (rootfs + entrypoint-user.sh changed in 11e512e). - CHANGELOG: Unreleased -> v1.11.0 with the audit. The CI bypass of the obsmem pin is recorded under Still open. Exercised before tagging, with pi 1.1.0 from a temp prefix in a real pty against -ne controls: - obsmem turn cap: 11 turns uncapped, exactly 3 capped. - atelier v0.15.0 paints in both renderers (controls 0/3, render-proofed). - obsmem 022da5e registers /om:status and /om:view. - All 11 pi-extensions a88fa99 extensions load. Local gates: check-doc-drift (rc 0, check 9 names every moved component), lint-shell, check-workflow-shell, test-link-pi-models (13/13), check-dockerfile-directives, check-skill-floor, check-base-hash.
changelog(unreleased): pi-task fallback covers the task children the AWS SSO keeper leaves alone
2026-10-12 16:54:55 +02:00 · 2026-10-12 16:34:41 +02:00 · 2026-10-12 16:28:28 +02:00 · 2026-10-12 16:28:28 +02:00 · 2026-10-12 09:20:48 +02:00 · 2026-10-11 23:00:17 +02:00
18 changed files with 2880 additions and 76 deletions
@@ -169,6 +169,30 @@ GIT_USER_EMAIL=
 # AWS_ACCESS_KEY_ID=
 # AWS_SECRET_ACCESS_KEY=

+# ── AWS SSO keeper (pi-extensions aws-sso.ts; all optional) ──────────
+# Renews the AWS SSO session for Bedrock when it ends (aws sso login); you or
+# your signed-in browser still approve each login. Off until `/aws-sso on`.
+# Guide: pi-extensions docs/aws-sso.md. Recreate the container after editing.
+# PI_AWS_SSO_REFRESH=1                # force the keeper on (0 = force off)
+# PI_AWS_SSO_MODE=local               # local (default): browser on the Docker host
+#                                     # remote: device code + push (headless/ssh+tmux)
+#                                     # (a mode set with /aws-sso local|remote wins)
+# PI_AWS_SSO_NTFY=                    # push target: https://ntfy.sh/<long-random-topic>
+#                                     # anyone knowing the topic can read the pushes
+# PI_AWS_SSO_NTFY_TOKEN=              # token for a protected topic (own ntfy server)
+# PI_AWS_SSO_SSH_HOST=host            # local: SSH alias of the Docker host
+# PI_AWS_SSO_LOCAL_CMD=               # local: command run on the host; {session} =
+#                                     # sso-session name. Default (POSIX host):
+#                                     # exec "${SHELL:-/bin/sh}" -lc 'aws sso login --sso-session {session}'
+#                                     # (Compose expands ${...} in .env: write $$ for a literal $)
+
+# ── Shared custom model providers (pi models.json) ────────────────────
+# If /opt/fleet-pi/models.json exists (mount a host DIRECTORY there, read-only),
+# the entrypoint links ~/.pi/agent/models.json to it on every start. A real file
+# or a link of your own is never replaced. README: "Custom model providers".
+# Put API keys in this .env and reference them as "$NAME" in models.json.
+# PI_MODELS_JSON=/opt/fleet-pi/models.json   # another path; off = disable
+
 # ── Skillset (agent skills and instructions) ─────────────────────────
 # If you have a skillset repo, the entrypoint auto-deploys skills and
 # instructions on container start using relative symlinks.
@@ -108,7 +108,14 @@ jobs:
        id: compute
        run: |
          # Hash inputs that determine the base image's contents.
-          # Order is fixed via `find -print0 | sort -z` for reproducibility.
+          # Order is fixed via `find -print0 | LC_ALL=C sort -z`. The LC_ALL=C is
+          # load-bearing: sort collates per locale, and a dictionary locale
+          # (sv_SE/en_US.UTF-8) orders rootfs differently from byte order, giving
+          # a different hash for identical content (measured 2026-09-22:
+          # base-f40c4b7b103d under C/C.UTF-8 vs base-d8df62216a81 under
+          # sv_SE.UTF-8). The runner ships LANG=C.UTF-8 today, so this pin
+          # changes nothing now; it stops the hash depending on that accident.
+          # Predicting base_tag locally MUST use the same prefix on this sort.
          # Junk filters: __pycache__/*.pyc and macOS metadata are gitignored
          # locally but still picked up by `find rootfs -type f` on a clean CI
          # checkout. Exclude them defensively.
@@ -120,7 +127,7 @@ jobs:
                ! -name '*.pyc' \
                ! -name '.DS_Store' \
                ! -name '._*' \
-                -print0 2>/dev/null | sort -z | xargs -0 cat 2>/dev/null
+                -print0 2>/dev/null | LC_ALL=C sort -z | xargs -0 cat 2>/dev/null
              cat entrypoint.sh entrypoint-user.sh
              # mempalace-toolkit is cloned in Dockerfile.base at a ref CI
              # resolves to a SHA; fold it in so base_tag changes when the
@@ -174,6 +181,29 @@ jobs:
  #
  # ~40 s, ahead of everything expensive, and it runs scripts/lint-shell.sh --
  # the same file lint.yml calls, not a second copy that drifts.
+  #
+  # scripts/check-doc-drift.sh is here for the same reason and closes the same
+  # gap -- and for it the gap is strictly worse. Shellcheck judges the TREE:
+  # green on main is still green at the tag, because the bytes did not move.
+  # Check 9 judges the tree against UPSTREAM NOW, and the floating refs it
+  # watches (PI_OBSMEM_REF=master and friends, which resolve-versions below turns
+  # into SHAs) move with no commit in this repo at all -- so a green reading on
+  # main carries no information about tag time, and that window is exactly where
+  # releases live. Worked example: pi-observational-memory moved cba0334 ->
+  # e7d77dc the day AFTER v1.9.3 was tagged. Nothing went red; it surfaced only
+  # because someone ran the gate by hand. Without this step a tag can publish a
+  # component that no CHANGELOG entry names, and the floating ref means no other
+  # file in the repo would record it either.
+  #
+  # Adds ~8 s. No token and no built image: it takes the last published vX.Y.Z
+  # from the Hub tags API, that release's baked labels from the anonymous
+  # registry API, and `git ls-remote`s each upstream -- so a plain checkout is
+  # enough, with no tags or history to fetch. Offline it SKIPs loudly and
+  # counted rather than passing, so an outage degrades it to a visible skip
+  # instead of a false green. Residual, accepted: it resolves the refs seconds
+  # before resolve-versions resolves them again, so an upstream push landing
+  # inside that window still slips through -- and check 9 on the NEXT release
+  # would then name it.
  lint-gate:
    runs-on: ubuntu-latest
    container:
@@ -189,6 +219,16 @@ jobs:
      - name: "Shellcheck + syntax-check repository scripts (severity: error)"
        run: bash scripts/lint-shell.sh

+      - name: Components the next build would bake differently are named in the CHANGELOG
+        run: bash scripts/check-doc-drift.sh
+
+      # Runs HERE as well as in lint.yml deliberately. A guard that gates only
+      # `push` lets a tag regress — the adoption slip that let doc-drift land
+      # 27 h after the v1.9.3 tag. This one protects the tag build from the
+      # zero-failing-step failure mode that killed v1.10.0 and v1.10.1.
+      - name: Dockerfile.variant still opens with its BuildKit check directive
+        run: bash scripts/check-dockerfile-directives.sh Dockerfile.variant
+
  resolve-versions:
    # Gated: a defective tree must not reach a 46-minute base build.
    needs: [lint-gate]
@@ -90,6 +90,18 @@ jobs:
        # actionlint so the more precise diagnostic surfaces first.
        run: bash scripts/check-workflow-shell.sh .gitea/workflows

+      - name: link-pi-models.sh contract (two-sided, no docker needed)
+        # The entrypoint links ~/.pi/agent/models.json to a mounted shared file
+        # and must never replace a real file or a user's own link. Tested here
+        # on every push, because the smoke test only runs at release time.
+        run: bash scripts/test-link-pi-models.sh
+
+      - name: Dockerfile.variant still opens with its BuildKit check directive
+        # See scripts/check-dockerfile-directives.sh: without that first line the
+        # smoke jobs fail with `invalid format delimiter 'ghadelimiter_...'` and
+        # NO failing step. Also wired into docker-publish.yml's lint-gate.
+        run: bash scripts/check-dockerfile-directives.sh Dockerfile.variant
+
      - name: Install actionlint (pinned)
        env:
          ACTIONLINT_VERSION: 1.7.12
@@ -197,10 +209,17 @@ jobs:
    # someone remembering. It is also read from the TAG, so a fix pushed to main
    # after tagging never reaches the published page.
    #
-    # Cheap and hermetic on purpose: every check compares a doc string against a
-    # value that exists in this repo, so no network, no token, no built image,
-    # and no sibling clone. Claims that genuinely need a running container (image
-    # sizes, the "N mempalace_* tools" count) are deliberately left out — a gate
+    # Two classes of check. 1-7 are hermetic: each compares a doc string against
+    # a value that exists in this repo — no network, no token, no built image.
+    # 8-9 compare against what is PUBLISHED, because those claims have no
+    # in-repo anchor and rotted for exactly that reason: 8 reads Docker Hub's
+    # measured sizes; 9 reads the ref labels baked into the last released image
+    # (anonymous registry API, no docker/crane) and `git ls-remote`s each
+    # floating upstream, then requires every component the next build would
+    # bake differently to be NAMED in the CHANGELOG above that release's
+    # heading. Both SKIP loudly and counted when offline — a skip is neither OK
+    # nor a failure. Claims that genuinely need a running container (the "N
+    # mempalace_* tools" count, uncompressed sizes) are still left out — a gate
    # that cannot evaluate a claim honestly would have to guess, and a guessing
    # gate is worse than none. Assert those in scripts/smoke-test.sh instead.
    #
@@ -103,7 +103,19 @@ re-brand of opencode-devbox's `pi-only` variant.
   It compares README.md's version-pin table against the ARGs it names, and
   DOCKER_HUB.md's Node claim against `ARG NODE_VERSION`, plus Hub's
   25 000-char limit, unsubstituted `{{PLACEHOLDERS}}`, and stale `Unreleased`
-   pointers in user-facing docs.
+   pointers in user-facing docs. With network it also checks DOCKER_HUB.md's
+   size claims against Hub's measured sizes (check 8) and — check 9 — that
+   **every component the next build would bake differently from the last
+   published release is named in the CHANGELOG** above that release's heading:
+   it reads the `se.jordbo.pi-devbox.*-ref` labels off the published image and
+   `git ls-remote`s each floating `*_REF`. A red check 9 means an upstream
+   (pi-toolkit, pi-extensions, mempalace-toolkit, pi-fork,
+   pi-observational-memory, pi-studio) moved and no entry names the new SHA;
+   the failure prints the compare URL; a `PI_VERSION` or `MEMPALACE_VERSION`
+   bump is caught the same way via the `pi-version` / `mempalace-version`
+   labels. Name the 7-char SHA (or version) where you describe
+   the change — that is what the old "Dependency audit" tables recorded by
+   hand, now required.

   **Why before and not after:** `docker-publish.yml` runs `actions/checkout@v4`
   with no `ref:`, so every job reads `github.ref` — the **tag**. A doc fix
@@ -8,12 +8,12 @@ A self-contained Docker container for the [pi coding-agent](https://github.com/e

 | Tag | Architectures | Size (compressed) | What you get |
 |---|---|---|---|
-| `joakimp/pi-devbox:latest` | amd64, arm64 | ~1.1 GB | Self-contained: base + pi `{{PI_VERSION}}` + companions |
+| `joakimp/pi-devbox:latest` | amd64, arm64 | ~1.23 GB | Self-contained: base + pi `{{PI_VERSION}}` + companions |
 | `joakimp/pi-devbox:vX.Y.Z` | amd64, arm64 | same | Pinned semver release |
-| `joakimp/pi-devbox:latest-studio` | amd64, arm64 | ~1.15 GB | `latest` + [pi-studio](https://github.com/omaclaren/pi-studio): browser prompt editor, KaTeX/Mermaid preview, tmux-backed literate REPLs |
+| `joakimp/pi-devbox:latest-studio` | amd64, arm64 | ~1.25 GB | `latest` + [pi-studio](https://github.com/omaclaren/pi-studio): browser prompt editor, KaTeX/Mermaid preview, tmux-backed literate REPLs |
 | `joakimp/pi-devbox:vX.Y.Z-studio` | amd64, arm64 | same | Pinned semver studio release |
-| `joakimp/pi-devbox:base-latest` | amd64, arm64 | ~1.0 GB | Base layer alias (internal building block; pull `:latest` instead) |
-| `joakimp/pi-devbox:base-<hash>` | amd64, arm64 | ~1.0 GB | Content-addressed base; immutable. Stable parent for variant rebuilds. |
+| `joakimp/pi-devbox:base-latest` | amd64, arm64 | ~1.17 GB | Base layer alias (internal building block; pull `:latest` instead) |
+| `joakimp/pi-devbox:base-<hash>` | amd64, arm64 | ~1.17 GB | Content-addressed base; immutable. Stable parent for variant rebuilds. |

 > **pi-studio (`-studio` tags):** launch with `/studio --no-browser --port 8765` inside a pi session. The server binds `127.0.0.1` **inside the container**, so reach it via host networking or a loopback bridge (and `ssh -L` for a remote host; mosh needs a parallel `ssh -L`). Full recipe: [README → Using pi-studio](https://gitea.jordbo.se/joakimp/pi-devbox#using-pi-studio--studio-variant).

@@ -56,6 +56,8 @@ Full setup guide — authentication for each provider (Anthropic, OpenAI, Gemini

 The entrypoint deploys/registers all of these on first container start. Re-running is idempotent and preserves user edits.

+**Terminal UI mode — fullscreen by default.** pi 1.0.0 made the TUI fullscreen, and this image adopts upstream's default. Fullscreen uses the terminal's alternate screen, so the transcript no longer lands in your terminal's (or tmux's) native scrollback. To get the previous behaviour back, set `"tuiMode": "regular"` in `~/.pi/agent/settings.json`, or pass `pi --tui-mode regular` for a single session. The bundled pi-atelier sidebar works in both modes. See the README for the related `fullscreenExitOutput` / `fullscreenScrollbar` / `fullscreenCopyOnSelect` / `fullscreenWheelScrollLines` settings — the last one behaves differently over SSH, which is how this container is usually driven.
+
 ### MemPalace (persistent agent memory)

 - **MemPalace** + MCP server — semantic search over conversation history, knowledge graph, diary; queryable via 29 `mempalace_*` tools inside pi
@@ -80,7 +82,7 @@ The entrypoint deploys/registers all of these on first container start. Re-runni
 - **Editor**: neovim (system-wide `termguicolors` default; bring your own config/plugins), tmux (configured for 0-indexed sessions)
 - **Search/nav**: ripgrep, fd, fzf, zoxide
 - **Display**: bat, eza, htop, tree
- **Data**: jq, yq
+- **Data**: jq, yq, sqlite3, bc/dc, column
 - **Help**: tldr (tealdeer — Rust port; run `tldr --update` once to populate cache)
 - **Git**: git-lfs, git-crypt, gitleaks (for pre-commit secret scanning)
 - **Build**: gcc, g++, make, patch
@@ -14,7 +14,7 @@
 # content-addressed over this file, so any byte change invalidates the
 # cache. Recommended cadence: once per release for security updates.
 #
-# BASE_REBUILD_DATE: 2026-07-13 (Unreleased — agent-browser CLI + Playwright Chromium for headless browser automation; prior: typst PDF engine + xz-utils + pandoc typst-template default-font patch)
+# BASE_REBUILD_DATE: 2026-10-12 (v1.11.0 — rootfs gains link-pi-models.sh, entrypoint-user.sh links models.json; base tools re-resolve `latest` (upstream on 2026-10-12: uv 0.13.0, nvim 0.12.6, fzf 0.74.5); previous marker 2026-09-22 / v1.9.4)
 #
 # ── Lineage note ─────────────────────────────────────────────────────
 # Adapted from opencode-devbox/Dockerfile.base (commit before v1.16.2).
@@ -162,6 +162,42 @@ ENV DEBIAN_FRONTEND=noninteractive
 #                  /dev/tcp does reachability checks with zero packages
 #                  (verified against gitea.egl.lan:3000). Recorded here so the
 #                  omission reads as a decision rather than an oversight.
+#   sqlite3      — the `sqlite3` CLI. Added 2026-09-28 at ALC's request. 587 KB.
+#                  This is the one that was genuinely missing rather than merely
+#                  absent: MemPalace keeps BOTH the palace and the logstream as
+#                  SQLite files (palace/chroma.sqlite3, logstream.sqlite3),
+#                  mempalace_status reports a sqlite_integrity block, and every
+#                  integrity or forensics check on this fleet has so far been
+#                  done through a python3 -c one-liner because the CLI did not
+#                  exist in the image.
+#   bc, dc       — arbitrary-precision calculators. 236 KB + 149 KB. SEPARATE
+#                  binary packages on Debian (dc split out of bc before
+#                  bookworm), so both must be named — verified with apt-cache on
+#                  a trixie host, not assumed. Added 2026-09-28. HONEST
+#                  RATIONALE: low value on their own, because awk, python3 and
+#                  perl are all already baked and each is strictly more capable.
+#                  They are here because copy-pasted shell snippets assume bc
+#                  exists. Note what actually went wrong on 2026-09-28, since it
+#                  was NOT bc's absence: `printf '%6.2f'` was handed the empty
+#                  output of the missing bc and rendered it as a confident
+#                  "0.00 days" for a figure that was really 4.81 days. A missing
+#                  tool that formats as a plausible number is worse than one
+#                  that fails loudly, and no package fixes that — only not
+#                  taking a formatted value on trust does.
+#   bsdextrautils— ships /usr/bin/column. 339 KB. Added 2026-09-28. Confirmed
+#                  with `dpkg -S /usr/bin/column` on trixie rather than inferred
+#                  from the pre-bullseye bsdmainutils name, which is where column
+#                  used to live and is the obvious way to get this wrong.
+#                  MEASURED COST OF ALL FOUR: 1311 KB total and ZERO transitive
+#                  packages — libsqlite3-0, libreadline8t64, zlib1g,
+#                  libsmartcols1 and libtinfo6 are each already present in the
+#                  image (checked with dpkg-query, all five report
+#                  "install ok installed"), so under --no-install-recommends
+#                  nothing new is pulled.
+#                  NOT added — datamash, xsv/csvkit: considered 2026-09-28 and
+#                  declined. Python's stdlib csv module handled a real 7-file
+#                  Excel-export concatenation that day (BOM, CRLF, embedded
+#                  newlines inside quoted fields) correctly and without them.
 #   python3-yaml — PyYAML. Added 2026-09-10 for precisely the same reason as
 #                  shellcheck above: a gate this repo ALREADY OWNS could not be
 #                  run locally by anyone. scripts/check-workflow-shell.sh — the
@@ -220,6 +256,10 @@ RUN apt-get update && \
    ldap-utils \
    xxd \
    python3-yaml \
+    sqlite3 \
+    bc \
+    dc \
+    bsdextrautils \
    && ln -s /usr/bin/fdfind /usr/local/bin/fd \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*
@@ -452,7 +492,10 @@ RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "aarch64"
 # uninterruptibly. A stall-kill is no longer a permanent latch either: the
 # next tool call respawns the server with capped exponential backoff (the
 # budget resets on any successful response). Tunables:
-# MEMPALACE_MCP_TIMEOUT_MS (default 60000), MEMPALACE_MCP_INIT_TIMEOUT_MS
+# MEMPALACE_MCP_TIMEOUT_MS (default 60000; the feed's `mempalace_mine` carries
+# its own longer MEMPALACE_FEED_MINE_TIMEOUT_MS, default 300000, since toolkit
+# 817b3a8 — before that the 60 s deadline cut every honest mine off),
+# MEMPALACE_MCP_INIT_TIMEOUT_MS
 # (default 300000 — generous so a genuine first cold-open isn't killed),
 # MEMPALACE_MCP_MAX_RESPAWNS (default 2; 0 disables self-heal),
 # MEMPALACE_MCP_RESPAWN_BACKOFF_MS (default 1000); timeouts of 0 disable.
@@ -529,14 +572,22 @@ ARG INSTALL_MEMPALACE=true
 # the part that should stay manual.
 #
 # Deployment sequencing note for whoever ships this bump: synlig (the shared
-# central palace host) serves mempalace 3.8.0 SERVER-SIDE via
-# docker-compose.mempalace.yml, which reuses this same devbox image. (Measured
-# 2026-09-06 over ssh: synlig's UV_TOOL_DIR mempalace entry last changed
-# 2026-08-25 15:33 — this comment previously said 3.7.1, which was stale.)
-# Bumping this ARG changes only the CLIENT version baked into pi-devbox
-# images: it introduces client/server skew until synlig's compose stack is
-# separately rebuilt/redeployed with the new pin. Not something to code around
-# here — just sequence the redeploy.
+# central palace host) serves mempalace SERVER-SIDE as a `uv tool` install run
+# by the systemd unit `mempalace-serve.service` (`python -m mempalace.mcp_server
+# --transport http`), NOT via docker-compose.mempalace.yml — that compose file
+# exists in this repo but is not what runs there. (Measured 2026-09-22 over
+# ssh: `uv tool list` -> mempalace v3.9.0, python 3.12.13, chromadb 1.5.9;
+# `docker ps` matched no palace container. This comment previously said the
+# compose stack served 3.8.0, which was stale on both counts.) Bumping this ARG
+# changes only the CLIENT version baked into pi-devbox images: it introduces
+# client/server skew until synlig's tool is upgraded (`uv tool upgrade
+# mempalace` + restart the unit). Not something to code around here — just
+# sequence the upgrade. And note which side OWNS what: MCP tool semantics
+# (event_list ordering, kg_timeline pagination, search result fields) come
+# from the SERVER the extension talks to over MEMPALACE_REMOTE_URL, so they
+# change when synlig upgrades; only the local CLI (`mempalace init` at first
+# run, the mempalace-pi-session feeder) and the on-disk layout under
+# ~/.mempalace change when THIS pin does.
 #
 # v1.8.13: 3.8.0 -> 3.9.0. Audited: no Breaking/Removed changelog headings.
 # Adopted mainly for #2281 (`mempalace_mine` accepts a single conversation
@@ -548,7 +599,61 @@ ARG INSTALL_MEMPALACE=true
 # (release awareness, `task create`/`task launch` MCP tools) are SERVER-side,
 # so they stay dark until synlig is redeployed — a client bump alone cannot
 # light them up.
-ARG MEMPALACE_VERSION=3.9.0
+#
+# v1.9.4: 3.9.0 -> 3.10.0 (PyPI 2026-09-15). Deferred at v1.9.3 for two
+# "Upgrade notes" items; both re-measured against the 3.10.0 wheel, one needed
+# an adaptation:
+#   - "New installs keep config and palace under ~/.config/mempalace". The
+#     resolution order is $MEMPALACE_CONFIG_DIR, then ~/.mempalace IF it holds
+#     config.json / people_map.json / palace/chroma.sqlite3, then XDG. An
+#     EMPTY ~/.mempalace does not count — and an empty ~/.mempalace is exactly
+#     what a freshly mounted devbox-palace volume (or entrypoint.sh's mkdir on
+#     a volume-less container) looks like at first boot. Measured with a fresh
+#     $HOME: `mempalace init` wrote to ~/.config/mempalace, outside the
+#     persisted path, and entrypoint-user.sh's first-run test
+#     `[ ! -d ~/.mempalace/palace ]` would stay true on every start. With
+#     MEMPALACE_CONFIG_DIR set, everything landed in ~/.mempalace. Hence the
+#     ENV MEMPALACE_CONFIG_DIR below (in the non-root-user section, where
+#     ${USER_NAME} is in scope): first in the resolution order, so the
+#     heuristic never runs and the image's layout contract no longer depends
+#     on it. Existing volumes were safe either way (config.json is a legacy
+#     marker); the ENV is for first boots. palace_path still defaults to
+#     <config_dir>/palace and MEMPALACE_PALACE_PATH is still honoured (config.py
+#     :927), so scripts/smoke-test.sh's stage-path test keeps its meaning.
+#   - "MCP event listing returns the newest events first when no cursor is
+#     given". SERVER-side (see above), so it lands when synlig upgrades, not
+#     here. mempalace-toolkit 2167a1b made every cursor-less event_list call
+#     in the pi extension say `order: "desc"` explicitly, so the mailbox reads
+#     the same window against either server version.
+# Also in the notes, neither reaching this image: `mempalace rules` dropped
+# `--agent` (no caller in pi-devbox, mempalace-toolkit, skillset or myconfigs);
+# `get_collection()` refuses unknown collection names (library callers only).
+# MCP tool-schema review, as always: no tool removed or renamed; additive
+# fields on search results (filed_at / content_date provenance), `limit` /
+# `offset` on kg_timeline, `last_modified` on drawers. Skew while synlig stays
+# on 3.9.0 is narrower than it looks: the pi extension speaks HTTP to the hub
+# (no local mempalace-mcp is spawned), and the feeder in remote mode stages
+# locally in python, rsyncs, and calls the hub's own `mempalace_mine` tool.
+# Measured 2026-09-22 with a PATH shim in front of `mempalace`: a 47-session
+# `mempalace-pi-session --dry-run` made ZERO local CLI calls (the shim's
+# positive control logged one). So 3.10.0's new CLI write-routing policy never
+# runs against the hub from this image; the client pin touches first-run
+# `mempalace init` and the on-disk layout, nothing else in remote mode.
+ARG MEMPALACE_VERSION=3.10.0
+# Recorded as a label HERE, not in Dockerfile.variant, for three reasons: the
+# value lives next to the ARG that defines it (a second copy in the variant
+# would be one more pin able to drift, which is the class check-doc-drift.sh
+# exists to catch); labels are inherited by every image built FROM this one, so
+# both variants carry it with no build-arg to plumb through four call sites;
+# and inheritance means the label states the pin of the base the variant
+# ACTUALLY built on — which is the question when base-decide cache-hits an
+# older base. Like every se.jordbo.pi-devbox.* label this records INTENT; the
+# ground truth is /etc/pi-devbox/build-manifest.json's mempalace_version, read
+# from the installed binary, and scripts/smoke-test.sh asserts the two agree.
+# check-doc-drift.sh check 9 reads this off the last published image so that a
+# pin bump must be named in the CHANGELOG — until this label ships, that
+# component reports SKIP (label absent on the published release), not OK.
+LABEL se.jordbo.pi-devbox.mempalace-version="${MEMPALACE_VERSION}"
 ENV UV_TOOL_DIR=/opt/uv-tools
 ENV UV_TOOL_BIN_DIR=/usr/local/bin
 RUN if [ "${INSTALL_MEMPALACE}" = "true" ]; then \
@@ -815,6 +920,18 @@ print('chromadb embedding model warmed: all-MiniLM-L6-v2')" && \
 ENV NPM_CONFIG_PREFIX=/home/${USER_NAME}/.pi/npm-global
 ENV PATH="/home/${USER_NAME}/.pi/npm-global/bin:${PATH}"

+# ── MemPalace config/palace root: pin it, do not let a heuristic pick it ──
+# mempalace >= 3.10.0 resolves its config dir as $MEMPALACE_CONFIG_DIR, then
+# ~/.mempalace ONLY if it already holds a config/palace, else ~/.config/mempalace
+# (XDG). An empty ~/.mempalace — a fresh devbox-palace volume, or entrypoint.sh's
+# mkdir on a volume-less container — fails that test, so a first boot would put
+# the palace outside the persisted path and re-run first-run init forever. This
+# ENV is first in the order, so the layout is what entrypoint.sh (mkdir),
+# entrypoint-user.sh (first-run test), the feeder's <palace-root>/pi-stage and
+# scripts/recreate-sanity-check.sh all already assume. Rationale and the
+# measurement live with ARG MEMPALACE_VERSION above; keep the two in step.
+ENV MEMPALACE_CONFIG_DIR=/home/${USER_NAME}/.mempalace
+
 # ── Shell defaults (bash history, aliases, readline) ─────────────────
 RUN mkdir -p /etc/skel-devbox
 COPY rootfs/home/developer/.bash_aliases     /etc/skel-devbox/.bash_aliases
@@ -1,3 +1,37 @@
+# check=skip=InvalidDefaultArgInFrom
+#
+# ^ MUST stay the FIRST line of this file, and it is load-bearing for CI, not
+# style. BuildKit parses `# check=` only before any other line, so moving it
+# below the title comment silently disables it.
+#
+# Why it exists: `ARG BASE_IMAGE` (below) deliberately has NO default — this
+# file is only ever built by the two-phase CI with --build-arg BASE_IMAGE=
+# <image>:base-<hash>. BuildKit's InvalidDefaultArgInFrom check flags that as
+# "default value for global ARG results in an empty or invalid base image
+# name". There is no honest default to give it: `scratch` would satisfy the
+# linter while being a lie (nothing here can build FROM scratch), and it would
+# convert today's instant "invalid reference format" into a failure deep in the
+# build. So the check is skipped by name, with the reason written down.
+#
+# What the warning actually COST, which is why this is not cosmetic: buildx
+# attaches the warning's source context to the build metadata as
+# buildx.build.warnings[].sourceInfo.data — the ENTIRE Dockerfile, base64, on
+# ONE line. docker/build-push-action writes that metadata to $GITHUB_OUTPUT as
+# a `name<<ghadelimiter_<uuid>` heredoc, and Gitea's act_runner truncates any
+# single line at exactly 65536 chars. Once base64(this file) crossed 64 KiB the
+# closing delimiter was cut off, and the runner failed the job with
+#   invalid format delimiter 'ghadelimiter_...' not found before end of file
+# and NO failing step: every step green, smoke suite "0 failed", job red.
+# Measured: 42251 B at v1.9.4 -> base64 56355 (fine); 50034 B at v1.10.1 ->
+# base64 66712, truncated to exactly 65536. The cap corresponds to a 49152 B
+# Dockerfile, so this release's comment growth crossed it by 882 B. It killed
+# v1.10.0 (run 704, where a stale clipboard assertion hid it) and v1.10.1
+# (run 707). With zero warnings there is no sourceInfo, so the longest metadata
+# line drops from 65536 to ~1936 chars and the Dockerfile's SIZE stops being
+# coupled to CI passing at all.
+#
+# If this ever recurs — job red, zero failing steps, suite reporting 0 failed —
+# grep the job log for `ghadelimiter` first.
 # pi-devbox — variant image
 #
 # FROMs a base-<hash> image produced by Dockerfile.base and adds only
@@ -113,7 +147,118 @@ ARG USER_NAME=developer
 # signature is ~5s of sustained CPU. Two-sided check: the atelier sidebar
 # painted ACTIVITY+WORKSPACE identically to the 0.84.4 control, so the test
 # could distinguish "loaded" from "silently absent".
-ARG PI_VERSION=0.85.1
+#
+# v1.9.4: HELD at 0.85.1 while 0.86.1 and 0.87.0 exist upstream. 0.87.0's
+# changelog: "Removed the inherited `shouldStopAfterTurn` agent option. Use
+# `finishTurn` and return `{ action: "end" }` instead" (no issue number on
+# that line); 0.86.0 moved provider stream inputs to `TranscriptContext`, with
+# system prompts read from `context.messages`. pi-observational-memory 3.1.4
+# (the `master` ref baked below) still uses both the old option and
+# `AgentContext.systemPrompt` in its observer, reflector and dropper workers —
+# measured 2026-09-22 in src/agents/*/agent.ts, both the baked 3.1.3 tree and
+# upstream master 3.1.4: `shouldStopAfterTurn` 1 per worker (3), `finishTurn`
+# 0, `systemPrompt` 1 per worker. Its peerDependencies are `*`,
+# so nothing at install time would refuse; it would break at runtime (turn
+# caps ignored, workers losing their specialised prompts). Upstream tracks it
+# as pi-observational-memory #82 with fix PR #83 (opened 2026-09-21, mergeable,
+# not merged at this writing). Bump pi and pi-obsmem TOGETHER once #83 has
+# shipped in a release. The other extensions were checked against the 0.86.0
+# and 0.87.0 breaking lists and are clean: ssh-controlmaster's `user_bash`
+# handler already returns `undefined | { operations }` (0.86.0 fail-closed
+# contract) and its registerTool calls spread the built-in tools so they
+# carry parameter schemas (#9300). 0.86.1 as an intermediate is untested and
+# not worth the pty matrix for a stop that #83 will make moot.
+#
+# v1.9.5: 0.85.1 -> 0.87.1, and pi-obsmem moves off `master` to a pinned SHA in
+# the SAME commit, because neither is safe alone. 0.87.0 REMOVED
+# `shouldStopAfterTurn`, which 3.1.4 still used; the pinned tip uses
+# `finishTurn`, which does not exist before 0.87.0. So 3.1.4 + 0.87.1 silently
+# ignores turn caps, and the new tip + 0.85.1 breaks the workers outright — the
+# pair only works together, exactly as the v1.9.4 note predicted.
+# MEASURED 2026-10-01 across src/agents/{observer,reflector,dropper}/agent.ts,
+# deliberately the same counting method as the v1.9.4 audit above so the two
+# numbers are comparable:
+#   3.1.4   (e7d77dc): shouldStopAfterTurn 3, finishTurn 0, systemPrompt 3
+#   731c3d4 (pinned) : shouldStopAfterTurn 0, finishTurn 3, systemPrompt 0
+# i.e. all three workers migrated, and the 0.86.0 `AgentContext.systemPrompt`
+# reads are gone too. #82/#83 merged 2026-09-23.
+# WHY A SHA AND NOT A TAG, departing from the v1.9.4 instruction to wait for a
+# release: #83 is merged, but the newest obsmem tag is STILL 3.1.4, cut
+# 2026-09-20 — before the merge. Upstream tags slowly while moving master often
+# (e7d77dc -> 1529e14 -> 731c3d4 in the nine days to 2026-10-01), so waiting for
+# a tag means holding pi indefinitely. A full SHA keeps the one property
+# `master` does not have: rebuilding this tag later produces the SAME image.
+# v1.9.5 SKIPPED 0.99.x and 1.0.0 for lack of evidence. v1.10.2 went and got the
+# evidence instead of waiting for obsmem to mention a version, because "no issue
+# names 1.0" is an absence of a statement, not a measurement.
+#
+# v1.10.2: 0.87.1 -> 1.0.0. MEASURED 2026-10-02 against the published npm
+# tarballs for 0.87.1 and 1.0.0, unpacked side by side:
+#   1. NO `### Breaking Changes` SECTION IN 1.0.0 AT ALL. The changelog's
+#      breaking sections belong to 0.87.0, 0.86.0, 0.84.3, 0.84.0, 0.83.0,
+#      0.80.8, 0.80.7 and 0.75.0 — none to 0.88+..1.0.0. The major is a
+#      milestone (fullscreen default, leaner codemode), not an API break. The
+#      last break that touched us was 0.87.0's `shouldStopAfterTurn` removal,
+#      which v1.9.5 already absorbed.
+#   2. `finishTurn` IS STILL IN 1.0.0's dist, so the obsmem SHA pinned below
+#      keeps the API it migrated to. (`shouldStopAfterTurn`: absent from both
+#      0.87.1 and 1.0.0, as expected after its 0.87.0 removal.)
+#   3. EVERY pi.* API our extensions call exists in 1.0.0's dist — all 8 of
+#      registerTool, registerCommand, registerFlag, getFlag, on, exec,
+#      sendMessage, sendUserMessage, extracted from mempalace.ts, the
+#      pi-extensions tree and obsmem's src/.
+#   4. engines.node is `>=22.19.0` on both; the image ships 24.x.
+# THE 0.99.2 CHANGE THAT LOOKED FATAL AND IS NOT: from 0.99.2 the DEFAULT MCP
+# `exposure` is `codemode`, i.e. such tools are "neither declared to the model
+# nor listed" and must be found with `searchTools()`. That would gut the
+# MemPalace protocol if MemPalace were a builtin-MCP server. It is not: both
+# mempalace.ts and mcp-loader.ts run their OWN MCP client and surface tools via
+# `pi.registerTool()`, which is why they are named `mempalace_search` and not
+# `mcp__mempalace__search`. Confirmed on a second route — settings.json has
+# neither an `mcpServers` block (builtin, exposure-governed) nor an `mcp` block.
+# Extension-registered tools are declared like built-ins, so `exposure` cannot
+# reach them.
+# WHAT IS NOT PROVEN, stated so acceptance does not mistake this for cleared:
+# grepping dist shows the SYMBOLS survive, not that their SIGNATURES are
+# unchanged — necessary, not sufficient. 1.0.0 is also four days of upstream old
+# (published 2026-10-01T19:15Z) and neither obsmem nor atelier has a commit
+# naming it. Acceptance must prove the obsmem workers CAP TURNS (peerDeps are
+# `*`, so a mismatch is silent) and that the atelier sidebar PAINTS.
+# USER-VISIBLE BEHAVIOUR CHANGE, decided rather than inherited: 1.0.0 makes the
+# TUI fullscreen by default, which replaces the terminal's normal scrollback.
+# Upstream's default is ADOPTED on purpose and no `tuiMode` is baked here, so
+# the image follows pi instead of pinning the fleet to either mode. The revert
+# is documented (README -> "Terminal UI mode"): `"tuiMode": "regular"` in
+# ~/.pi/agent/settings.json, `pi --tui-mode regular` for one session, or the
+# same key in a project's .pi/settings.json.
+#
+# v1.11.0: 1.0.0 -> 1.1.0. MEASURED 2026-10-12 against the published npm
+# tarballs for 1.0.0 and 1.1.0, unpacked side by side, by the same method as
+# the v1.10.2 audit above:
+#   1. ONE `### Breaking Changes` section in 1.0.1..1.1.0: 1.0.3 renamed the
+#      provider `azure-openai-responses` -> `azure`. 0 uses here: grepped
+#      rootfs/, ~/.pi/agent/settings.json, pi-toolkit's settings.example.json
+#      and the fleet's shared models.json. Everything else is additive or a fix
+#      (OSC 7501 program status, `+name`/`-name` in --tools, `durationMs` and
+#      `outputPad` in the tool render context, `aborted` on agent_settled).
+#      Two user-visible changes: Home/End always move the editor cursor
+#      (fullscreen transcript top/bottom moved to Ctrl+Home/Ctrl+End, 1.0.3),
+#      and OSC 7501 status reporting (PI_PROGRAM_STATUS=0 turns it off, 1.1.0).
+#   2. pi-agent-core 1.0.0 -> 1.1.0: the finishTurn context in dist is
+#      BYTE-IDENTICAL; the only agent-loop diff adds `durationMs`. The obsmem
+#      turn-cap probe drove the real 1.1.0 agentLoop: uncapped ran its chosen
+#      11 turns, maxTurns=3 stopped at exactly 3 + agent_end.
+#   3. The 6 named pi.* APIs (registerTool, registerCommand, registerFlag,
+#      getFlag, sendMessage, sendUserMessage) appear in the same number of dist
+#      files in 1.0.0 and 1.1.0. atelier's internals TuiMainScreen and
+#      renderLayoutFrame are both still in 1.1.0's dist.
+#   4. engines.node is still `>=22.19.0`; the image ships 24.x.
+# Exercised before tagging, from a temp prefix with pi 1.1.0 and a throwaway
+# PI_CODING_AGENT_DIR, in a real pty, with -ne controls: atelier v0.15.0 paints
+# ACTIVITY/READY/TOOLS in BOTH renderers (controls 0/3, every arm render-proofed);
+# obsmem 022da5e registers /om:status and /om:view (control: none); and all 11
+# pi-extensions a88fa99 extensions load with no error (control: no /aws-sso).
+ARG PI_VERSION=1.1.0
 ARG PI_TOOLKIT_REF=main
 ARG PI_EXTENSIONS_REF=main
 # Repo URLs default to the canonical gitea origin but are overridable so a
@@ -128,7 +273,25 @@ ARG PI_EXTENSIONS_REPO=https://gitea.jordbo.se/joakimp/pi-extensions.git
 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
+# PINNED to a full 40-char SHA as of v1.9.5, not `master` — see the PI_VERSION
+# note above for the measurement and the reasoning. Moves together with
+# PI_VERSION by necessity, not by convention. The width matters: 731c3d4 is the
+# same commit, but check-doc-drift.sh recognises a literal SHA only via a
+# 40-char match (SHA40), so a short pin would fall through to its
+# branch-or-tag lookup, fail, and downgrade that component's drift check to a
+# silent SKIP — a pin that reads fine and is no longer verified.
+# v1.11.0: 731c3d4 -> 022da5e (master, 2026-10-05; still no newer tag than
+# 3.1.4). Two commits: #81 never drops unobserved context at compaction
+# (new settings compactionMaxRetainedTokens, consolidateWhenIdle,
+# piAutoCompactionEnabled, all defaulted), and #93 makes pi load a prebuilt
+# dist/index.ts instead of 32 TS sources. The bundle is committed, so
+# `npm install --omit=dev` below needs no build step. src/agents/ is
+# UNCHANGED between the two SHAs, so the finishTurn migration is intact.
+# KNOWN GAP, not fixed here: docker-publish.yml's resolve-versions still
+# resolves obsmem from `master` and passes it as --build-arg, which overrides
+# this default (verified two-sided on buildx 2026-10-12). CI builds therefore
+# get the pin only while master == pin, as it is at this release.
+ARG PI_OBSMEM_REF=022da5e5554d04dfdc876ed7dac4a42c6b83dfd4
 # pi-atelier (TUI sidebar: ordered panels, split-pane, themes) is PINNED TO A
 # TAG, which CI resolves to that tag's commit SHA — same treatment as
 # pi-studio, for reproducibility plus cache-busting.
@@ -170,9 +333,55 @@ ARG PI_ATELIER_REPO=https://github.com/michaelmjhhhh/pi-atelier.git
 # old and new pin. Included because it was already exercised: the pty matrix
 # for PI_VERSION above ran atelier v0.10.1 against pi 0.85.1 and painted the
 # sidebar identically to v0.10.0.
-ARG PI_ATELIER_REF=v0.10.1
+#
+# v1.9.4: v0.10.1 -> v0.10.3 (both v0.10.2 and v0.10.3 released 2026-09-22).
+# Fixes only per the release notes: sidebar text/borders preserved beside
+# inline images (#53), transcript images hidden while capturing overlays are
+# open, Workspace Pulse skips redundant HEAD/diff when nothing tracked changed
+# (#61), sidebar height from row counts (#59), git/usage scans suspended while
+# disabled, Display Revert + Undo ordering. Checked before bumping: package.json
+# at v0.10.3 still declares zero runtime dependencies and no build script (so
+# the no-`npm install` reasoning above holds) and peerDependencies are still
+# pi >=0.84.0, so it still spans the pinned 0.85.1. 13 commits v0.10.1..v0.10.3,
+# all under src/ tests/ docs/ scripts/ plus metadata; no entry-point move.
+#
+# v1.10.2: v0.10.3 -> v0.13.0, closing the two-minor gap v1.9.5 flagged as the
+# residual risk of the pi bump. peerDependencies are UNCHANGED at pi >=0.84.0
+# across v0.10.3, v0.12.1 and v0.13.0 — still a FLOOR, so still not evidence of
+# anything; the floor is satisfied by 1.0.0 either way. What was actually
+# checked, 2026-10-02:
+#   - v0.13.0 CARRIES ITS OWN BREAKING CHANGE, unrelated to pi: "The package
+#     entry point now exports only the sidebar contribution protocol
+#     (`registerSidebarPanel`, guards, size limits, event types). The internal
+#     registry and layout helpers are no longer exported." Harmless HERE only
+#     because nothing of ours imports them: a grep for `pi-atelier` and
+#     `registerSidebarPanel` across mempalace-toolkit, pi-devbox,
+#     pi-extensions, pi-fork, pi-observational-memory and pi-studio returns
+#     ZERO matches in all six. atelier is a leaf here — it registers its own
+#     sidebar and no one consumes its API.
+#   - Settings churn in the gap, checked against our own tree: v0.12.0 REMOVED
+#     the `showSessionActions` setting (0 references here) and migrated the
+#     Control Center shortcut Alt+A -> F6 (0 references here, so no doc goes
+#     stale). `showSidebarAgent` / `showSidebarTodos`, the only atelier keys
+#     README names, are both still documented in v0.13.0's README.
+#   - The TUI internals atelier patches (`TuiMainScreen`, `renderLayoutFrame`)
+#     are both still present in pi 1.0.0's dist, and atelier's changelog shows
+#     it has handled fullscreen vs regular renderers explicitly since 0.84.
+#   - Residual: v0.13.0 is SAME-DAY upstream (2026-10-02). Acceptance proves
+#     the sidebar PAINTS with the two-sided check from 0.84.4/0.85.1 that can
+#     tell "loaded" from "silently absent" — "no crash" is not the test.
+#
+# v1.11.0: v0.13.0 -> v0.15.0 (v0.14.0 and v0.15.0 both 2026-10-03). The
+# peerDependencies floor is unchanged (pi >=0.84.0), atelier still has zero
+# runtime dependencies, and it still imports only the public package exports.
+# Behaviour changes: v0.14.0 auto-collapses the Sidebar when the terminal is
+# narrow (Auto/Manual modes). v0.15.0 starts in Manual mode, recolours the
+# panels and simplifies the Activity rows. The startup preference is still
+# `showSidebarOnStartup` (default true, src/config.ts:38). Painted in both
+# renderers on pi 1.1.0 before tagging (see the PI_VERSION note).
+ARG PI_ATELIER_REF=v0.15.0
 # Human-readable tag PI_ATELIER_REF was resolved from; recorded as a label.
-ARG PI_ATELIER_VERSION=v0.10.1
+ARG PI_ATELIER_VERSION=v0.15.0

 RUN set -e && \
    # git_fetch_ref: clone-equivalent helper that accepts EITHER a branch name
@@ -282,6 +491,22 @@ RUN set -e && \
    echo "pi-observational-memory at $(cd /opt/pi-observational-memory && git rev-parse --short HEAD)" && \
    echo "pi-atelier at $(cd /opt/pi-atelier && git rev-parse --short HEAD) (${PI_ATELIER_VERSION})"

+# ── git: let the unprivileged user read the root-owned /opt clones ──────────
+# The clones above (and /opt/mempalace-toolkit from the base, /opt/pi-studio in
+# the studio variant) are root-owned; the container runs as `developer`. Since
+# git 2.35.2 (CVE-2022-24765) any git command in a repo owned by another user
+# fails with "dubious ownership" — so `git -C /opt/pi-extensions rev-parse`
+# returns nothing, `install.sh` used to abort on it, and acceptance checks that
+# read a baked ref via git silently measured "" (v1.9.4 first-boot run: one
+# false FAIL from exactly this). Listing the paths (not `*`) keeps the check
+# meaningful for everything else, e.g. the virtiofs-mounted /workspace.
+# Entries for paths absent in a variant (pi-studio) are inert.
+RUN for d in pi-toolkit pi-extensions pi-fork pi-observational-memory pi-atelier \
+             mempalace-toolkit pi-studio; do \
+      git config --system --add safe.directory "/opt/${d}"; \
+    done && \
+    git config --system --get-all safe.directory
+
 # ── Image-baked skill refresh: pi-extensions (Option 1 over Option 2) ──
 # rootfs ships a VENDORED snapshot of the pi-extensions skill at
 # /usr/local/share/pi-devbox/skills/pi-extensions/ (the "floor" — guarantees the
@@ -481,7 +706,7 @@ ARG MEMPALACE_TOOLKIT_REF=main
 # no ~67-minute base rebuild. (scripts/check-base-hash.sh scans only
 # Dockerfile.base, so no folding into the base hash is required — nor would
 # it be correct, since this ARG changes nothing about the base's contents.)
-ARG SKILLSET_SNAPSHOT_REF=e9e45f7acdde490c3b5d24ce5f508bff8785c2c7
+ARG SKILLSET_SNAPSHOT_REF=96b840ee43beca65a190772021a8ef370145cde1

 # Dockerfile.base sets description="pi-devbox — base image (variant-independent)"
 # and every variant INHERITS it, so both published images used to advertise
@@ -358,6 +358,61 @@ DOT syntax errors instead of crashing. Then in Studio: open the PNG (or a
 `.md` that embeds it) and hit **refresh-from-disk** after each edit.
 Note: SVG is **not** in Studio's local-image-link allowlist — use PNG.

+## Terminal UI mode: fullscreen is the default (since v1.10.2)
+
+pi **1.0.0** changed the default terminal UI mode to **fullscreen**, and this
+image adopts upstream's default rather than overriding it. Fullscreen draws into
+the terminal's alternate screen, so pi's transcript no longer accumulates in your
+terminal's native scrollback — you scroll inside pi instead, and on exit pi
+prints the transcript (`fullscreenExitOutput`).
+
+That is a real behaviour change if you were used to the old mode, so here is the
+way back. Nothing in the image is pinned, so all three routes below work:
+
+| Scope | How |
+|---|---|
+| **Permanently, for every session** | add `"tuiMode": "regular"` to `~/.pi/agent/settings.json` |
+| **One session** | `pi --tui-mode regular` |
+| **One project only** | add `"tuiMode": "regular"` to that project's `.pi/settings.json` — project settings override the agent directory |
+
+The settings file is plain JSON and `tuiMode` is top-level, so the minimal
+permanent change is:
+
+```bash
+# merge the key without disturbing the rest of the file (python3 is always present)
+python3 - <<'PY'
+import json, pathlib
+p = pathlib.Path.home() / ".pi/agent/settings.json"
+d = json.loads(p.read_text()) if p.exists() else {}
+d["tuiMode"] = "regular"        # "fullscreen" is pi's default
+p.write_text(json.dumps(d, indent=2) + "\n")
+PY
+```
+
+If you stay on fullscreen, four related settings are worth knowing — all
+documented in pi's own `docs/settings.md` under *Terminal and display*:
+
+- `fullscreenExitOutput` — `"transcript"` (default) or `"resume-hint"`: what pi
+  leaves behind in the terminal when fullscreen exits.
+- `fullscreenScrollbar` — `"auto"` (default), `"always"`, `"hidden"`.
+- `fullscreenCopyOnSelect` — `true` by default; selecting text copies it.
+- `fullscreenWheelScrollLines` — `"auto"` by default. Relevant **here** in
+  particular: this container is normally driven over SSH, and over SSH `"auto"`
+  accelerates fast wheel spins to at most 6 lines per event (local macOS
+  terminals accelerate on their own, so there it moves one line). `Alt`+wheel
+  moves five times as far.
+
+Two notes specific to this image:
+
+- **tmux.** Fullscreen uses the alternate screen, so `tmux` copy-mode scrollback
+  shows the pane's history *around* pi, not pi's transcript. Scroll within pi,
+  or use `"tuiMode": "regular"` if you rely on tmux copy-mode to search the
+  conversation.
+- **pi-atelier.** The bundled sidebar works in both modes — upstream has handled
+  regular and fullscreen renderers separately since pi 0.84, including
+  fullscreen divider dragging and keeping sidebar text out of fullscreen
+  selection — so switching back to `regular` does not cost you the sidebar.
+
 ## Using pi-atelier (TUI sidebar)

 `pi-atelier` is bundled in **both** variants (vendored at `/opt/pi-atelier`,
@@ -409,7 +464,10 @@ pin the order yourself.

 The sidebar auto-hides below 92 terminal columns and keeps the main pane at
 least 64 columns wide, so a narrow terminal degrades to the plain TUI rather
-than a squeezed one.
+than a squeezed one. That is **Manual** mode, the default since atelier v0.15.0.
+`/atelier sidebar auto` switches to **Auto** mode, which collapses the sidebar
+when space is tight (below 124 columns at the default width) and reopens it at
+132. Manual width adjustment is disabled in Auto mode.

 ## docker-compose.yml — basic shape

@@ -572,7 +630,13 @@ ChromaDB ONNX embedding model so first-time semantic search is
 instant.

 The palace data lives at `~/.mempalace/palace` on the host
-(bind-mounted into the container). This means:
+(bind-mounted into the container). The image pins that layout with
+`ENV MEMPALACE_CONFIG_DIR=/home/developer/.mempalace` (`Dockerfile.base`):
+mempalace ≥ 3.10.0 would otherwise treat an *empty* `~/.mempalace` — a freshly
+mounted volume at first boot — as "no install here" and put a new palace under
+`~/.config/mempalace`, outside anything the compose files persist. With the
+variable set, first in mempalace's resolution order, the location is a contract
+rather than a heuristic. This means:

 - A pi running on the host and a pi running inside this container see
  the same palace.
@@ -818,6 +882,40 @@ If you use Bedrock as pi's LLM provider:
 The pi-toolkit AWS env loader (in `~/.pi/agent/`) prepares Bedrock
 inference-profile model IDs (with `eu.` / `us.` prefixes) automatically.

+## Custom model providers (`models.json`)
+
+pi reads extra providers from `~/.pi/agent/models.json`. That can be any
+OpenAI-, Anthropic- or Google-compatible endpoint: a company gateway, vLLM,
+Ollama, LM Studio and so on (pi's
+[models.md](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/models.md)).
+`~/.pi` is the `devbox-pi-config` volume. A file you put there by hand survives
+recreates, but every new volume starts without one: another device, or after
+`down -v`.
+
+To share one file across devices, keep it in a host directory and mount that
+**directory** read-only at `/opt/fleet-pi`. At every start the entrypoint links
+`~/.pi/agent/models.json` to `/opt/fleet-pi/models.json`:
+
+```yaml
+    volumes:
+      - ./pi-shared:/opt/fleet-pi:ro     # a directory containing models.json
+```
+
+- **Mount the directory, not the file.** `git pull` and most editors replace a
+  file by rename. A single-file bind mount then keeps showing the old one, or
+  "No such file", until the next recreate. A directory mount shows the new file
+  at once. pi reads `models.json` when it starts, so a pulled change reaches the
+  next pi session without a recreate.
+- **Keep keys out of the file.** Write `"apiKey": "$MY_GATEWAY_KEY"` in
+  `models.json` and put the value in `.env`, which `env_file:` already passes
+  in. The file then holds no secret and can live in git.
+- **Nothing of yours is replaced.** A real `~/.pi/agent/models.json`, or a link
+  of your own, is left alone; `docker logs` shows one `NOTE` line saying so. With
+  nothing mounted, nothing happens.
+- `PI_MODELS_JSON` points at another path, and `PI_MODELS_JSON=off` disables the
+  link. Check with `pi --list-models <provider>`. `recreate-sanity-check.sh`
+  verifies the link whenever a shared file is mounted.
+
 ## Build pipeline

 pi-devbox is built from this repo's CI in two phases:
@@ -901,8 +999,10 @@ docker inspect --format '{{json .Config.Labels}}' joakimp/pi-devbox:latest | jq
 ```

 `org.opencontainers.image.{version,revision,created}` plus
-`se.jordbo.pi-devbox.*-ref` record the intended pi version and companion
-refs. The on-disk `/etc/pi-devbox/build-manifest.json` records **ground
+`se.jordbo.pi-devbox.*-ref` and `se.jordbo.pi-devbox.*-version` record the
+intended pi and mempalace versions and companion refs (`mempalace-version` is
+set in `Dockerfile.base` and inherited, so it names the pin of the base the
+image actually built on). The on-disk `/etc/pi-devbox/build-manifest.json` records **ground
 truth** — the actual checked-out commit of each `/opt` clone, the live
 `pi --version`, and (from v1.8.6) the live `mempalace --version` of the
 installed palace core — so a tag is reconstructable after CI logs rotate:
@@ -1098,7 +1198,7 @@ persisted volumes survived, and pi runtime wiring is intact:
 ```bash
 ./scripts/recreate-sanity-check.sh                              # auto-detects variant
 ./scripts/recreate-sanity-check.sh --expected-image-version 1.8.9  # assert the pi-devbox release tag
-./scripts/recreate-sanity-check.sh --expected-version 0.85.1        # assert the pi coding agent version
+./scripts/recreate-sanity-check.sh --expected-version 1.1.0          # assert the pi coding agent version
 ```

 Those are **two different versions**, and the flags are not interchangeable:
@@ -1137,9 +1237,10 @@ resolved to `latest` at build time:

 | Component | Pin | Where |
 |---|---|---|
-| pi | `0.85.1` | `ARG PI_VERSION` — `Dockerfile.variant` |
-| pi-atelier | `v0.10.1` | `ARG PI_ATELIER_REF` — `Dockerfile.variant` |
-| mempalace | `3.9.0` | `ARG MEMPALACE_VERSION` — `Dockerfile.base` |
+| pi | `1.1.0` | `ARG PI_VERSION` — `Dockerfile.variant` |
+| pi-obsmem | `022da5e5554d04dfdc876ed7dac4a42c6b83dfd4` | `ARG PI_OBSMEM_REF` — `Dockerfile.variant` |
+| pi-atelier | `v0.15.0` | `ARG PI_ATELIER_REF` — `Dockerfile.variant` |
+| mempalace | `3.10.0` | `ARG MEMPALACE_VERSION` — `Dockerfile.base` |

 The objective is **not** to freeze versions. Bumping is routine — usually one
 line plus a changelog note. The objective is that adopting a new upstream
@@ -100,8 +100,21 @@ fi
 # existing data. `--yes` auto-accepts detected entities so the init is
 # non-interactive.
 if command -v mempalace &>/dev/null && [ -d /workspace ]; then
-  PALACE_DIR="${HOME}/.mempalace"
-  if [ ! -d "$PALACE_DIR/palace" ]; then
+  # Read the root from the same variable mempalace itself reads (set as an
+  # image ENV in Dockerfile.base since mempalace 3.10.0 started resolving
+  # ~/.config/mempalace for an EMPTY ~/.mempalace). The fallback keeps the
+  # historical location for anyone running this script with the ENV unset;
+  # the point of naming the variable here is that this test and mempalace's
+  # own resolution can no longer disagree about where the palace lives — a
+  # disagreement that would make this branch fire on every start.
+  PALACE_DIR="${MEMPALACE_CONFIG_DIR:-${HOME}/.mempalace}"
+  # Sentinel = config.json, because that is what `mempalace init` writes.
+  # It does NOT create palace/ — mining does — so the earlier test on palace/
+  # re-fired on every start of a container that had never mined locally
+  # (v1.9.4 acceptance: 1 "Initializing" line after one boot, 2 after a
+  # restart). Harmless (init is idempotent) but the log lied. Populated
+  # volumes (config.json present) skip either way.
+  if [ ! -f "$PALACE_DIR/config.json" ]; then
    echo "Initializing MemPalace for workspace (non-interactive)..."
    # </dev/null: mempalace init has an interactive "Mine this directory
    # now? [Y/n]" prompt that --yes does not auto-answer in all paths.
@@ -306,6 +319,35 @@ fi
 if [ -f "$HOME/.gitignore_global" ] && ! git config --global core.excludesFile &>/dev/null; then
  git config --global core.excludesFile "$HOME/.gitignore_global"
 fi
+# Route git-over-ssh through the WRITABLE ssh sidecar. ~/.ssh is commonly
+# bind-mounted read-only from the host, and a per-host
+#   ControlPath ~/.ssh/cm/%r@%h:%p
+# inherited from that config (the standard CGNAT multiplexing recipe) kills every
+# push with
+#   unix_listener: cannot bind to path ~/.ssh/cm/...: Read-only file system
+# hidden behind git's misleading "Please make sure you have the correct access
+# rights", which sends the reader hunting for a key problem that does not exist.
+# setup-lan-access.sh (run near the top of this script) already wrote
+# ~/.ssh-local/config, whose leading `Host *` block overrides ControlPath into
+# the writable ~/.ssh-local/cm and only THEN `Include`s the user's own config —
+# so -F repairs the socket path while keeping every per-host User/Port/
+# IdentityFile. Wiring it here means no caller has to know any of that.
+#
+# WHY THIS IS NOT LEFT TO DOCUMENTATION: measured 2026-09-22 on tor-ms22, an
+# agent with the remedy in its system prompt, in a loaded skill, in 24 palace
+# drawers, AND printed verbatim by recreate-sanity-check.sh two hours earlier
+# still hit this and reinvented a /tmp/sshcm workaround. The knowledge was
+# available four times over, so a fifth copy is not the fix — removing the need
+# to know is.
+#
+# The [ -r ] guard is load-bearing, not decoration: setup-lan-access.sh only
+# writes the sidecar on VM-backed hosts (OrbStack / Docker Desktop). On native
+# Linux Docker there is none, and pointing -F at a missing file would break EVERY
+# git-over-ssh operation instead of fixing one. Respect a value the user already
+# set — same first-wins convention as the three settings above.
+if [ -r "$HOME/.ssh-local/config" ] && ! git config --global core.sshCommand &>/dev/null; then
+  git config --global core.sshCommand "ssh -F $HOME/.ssh-local/config"
+fi

 # ── pi: deploy toolkit + extensions + mempalace bridge ─────────────
 # pi is always installed in pi-devbox; no INSTALL_PI guard needed.
@@ -329,6 +371,16 @@ if command -v pi &>/dev/null; then
      echo "WARN: pi-extensions install.sh failed (continuing)"
  fi

+  # Shared custom providers: link ~/.pi/agent/models.json to a models.json in a
+  # read-only mounted DIRECTORY (default /opt/fleet-pi/models.json; PI_MODELS_JSON
+  # overrides, =off disables). Only ever creates a link where nothing exists —
+  # a real file or a link of the user's own is left alone. Without this, every
+  # fresh devbox-pi-config volume needed a manual `ln -s` (2026-10-12: one per
+  # device for the same file). Rationale and cases: the script's header.
+  if [ -r /usr/local/lib/pi-devbox/link-pi-models.sh ]; then
+    bash /usr/local/lib/pi-devbox/link-pi-models.sh || true
+  fi
+
  # Bootstrap settings.json from template if absent (pi rewrites this
  # file at runtime — lastChangelogVersion, etc — so we can't symlink it).
  _pi_settings="$HOME/.pi/agent/settings.json"
@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# link-pi-models.sh — point ~/.pi/agent/models.json at a shared, mounted file.
+#
+# pi reads custom providers (any OpenAI-, Anthropic- or Google-compatible
+# endpoint: a company gateway, vLLM, Ollama, LM Studio …) from
+# ~/.pi/agent/models.json. In pi-devbox that directory is the devbox-pi-config
+# named volume, which makes both obvious ways of providing the file wrong:
+#   - baked into the image, it would only seed a FRESH volume, once;
+#   - copied by hand into each volume, it is one more per-device step, and the
+#     copies drift the first time a price or model id changes.
+# Instead, keep ONE models.json in a host directory, mount that directory
+# read-only, and let this script link it in at every container start:
+#
+#   volumes:
+#     - ./pi-shared:/opt/fleet-pi:ro        # a directory containing models.json
+#
+# Mount the DIRECTORY, not the file. `git pull` (and most editors) replace a
+# file by rename, and a single-file bind mount keeps the old inode and shows
+# "No such file" until the next recreate (measured on Docker Desktop,
+# 2026-10-12). A directory mount shows the new file at once, and pi re-reads
+# models.json when it starts, so a pulled change reaches the next pi session.
+#
+# PI_MODELS_JSON overrides the path (default /opt/fleet-pi/models.json).
+# PI_MODELS_JSON=off (or empty) disables this script.
+#
+# Never destructive. It only ever creates a link where nothing exists:
+#   - no file at the path              → nothing (the case for most users)
+#   - models.json is already our link  → nothing
+#   - models.json is a real file       → left alone; one NOTE line says why
+#   - models.json links somewhere else → left alone; a deliberate choice
+# A link this script made whose target later disappears (mount removed) is
+# harmless: pi treats a dangling models.json exactly like a missing one —
+# no error, no custom models (measured with pi 1.0.0, 2026-10-12).
+#
+# Called by entrypoint-user.sh. Safe to run by hand at any time.
+set -u
+
+src="${PI_MODELS_JSON-/opt/fleet-pi/models.json}"
+case "$src" in
+  "" | off | OFF | Off) exit 0 ;;
+esac
+[ -f "$src" ] && [ -r "$src" ] || exit 0
+
+agent_dir="${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}"
+dest="$agent_dir/models.json"
+
+if [ -L "$dest" ]; then
+  # Ours already, or someone else's deliberate link: either way, nothing to do.
+  [ "$(readlink "$dest")" = "$src" ] || \
+    echo "NOTE: $dest links to $(readlink "$dest"), not $src; left alone"
+  exit 0
+fi
+if [ -e "$dest" ]; then
+  echo "NOTE: $dest is a real file; not linking $src (move it away to use the shared one)"
+  exit 0
+fi
+
+mkdir -p "$agent_dir" 2>/dev/null || true
+if ln -s "$src" "$dest" 2>/dev/null; then
+  echo "pi models.json: linked to $src"
+else
+  echo "WARN: could not link $dest -> $src (continuing)"
+fi
+exit 0
@@ -1,17 +1,17 @@
 ---
 name: pi-extensions
 description: >-
-  Use the pi extensions (pi-fork, pi-observational-memory, ssh-controlmaster) effectively in the pi coding agent harness. Load this skill only when running inside pi (detection - `fork` and `recall` are present in your tool list, or `pi --ssh` was used to start the session). pi-fork dispatches focused subtasks to forked agents at fast/balanced/deep effort tiers; pi-observational-memory compacts long sessions into recallable observations + reflections; ssh-controlmaster rewires pi's read/write/edit/bash tools to execute on a remote host over a multiplexed SSH connection. Also covers the context ladder L0-L4 and when to reach for the separate `pi-task` CLI instead of `fork` - isolated child, immutable spec, machine-checked envelope, write-boundary diff. This skill covers tier selection, task design, boundary discipline, when to use recall, and remote-pi mechanics.
+  Use the pi extensions (pi-fork, pi-observational-memory, ssh-controlmaster) effectively in the pi coding agent harness. Load this skill only when running inside pi (detection - `fork` and `recall` are present in your tool list, or `pi --ssh` was used to start the session). pi-fork dispatches focused subtasks to forked agents at fast/balanced/deep effort tiers; pi-observational-memory compacts long sessions into recallable observations + reflections; ssh-controlmaster rewires pi's read/write/edit/bash tools to execute on a remote host over a multiplexed SSH connection. Also covers the context ladder L0-L4 and the `task` tool (pi-task: isolated child, immutable spec, machine-checked envelope, write-boundary diff) that is the DEFAULT for delegated work, with `fork` reserved for read-only exploration and parallel opinions, plus the `fork-gate` hook that enforces the split. This skill covers rung and tier selection, task design, boundary discipline, when to use recall, and remote-pi mechanics.
 ---

-# Pi Extensions: pi-fork, pi-observational-memory, ssh-controlmaster
+# Pi Extensions: pi-fork + task/fork-gate, pi-observational-memory, ssh-controlmaster

 ## When to Load This Skill

 Load only when **both** of these are true:

 1. You are running inside the **pi coding agent harness** (not Claude Code, not opencode, not any other harness).
-2. The `fork` and/or `recall` tools appear in your available tool list, **or** the session was started with `pi --ssh ...`.
+2. The `fork`, `task` and/or `recall` tools appear in your available tool list, **or** the session was started with `pi --ssh ...`.

 If you do not see those tools, this skill does not apply — skip it. Other harnesses do not have these extensions and the patterns below will not work there.

@@ -71,7 +71,78 @@ ssh-controlmaster is orthogonal but composes cleanly: when pi is operating remot

 ---

-## Part 1: pi-fork
+## Part 1: delegating work — `task` and `fork`
+
+### Decide the rung BEFORE the brief (read this first)
+
+Two tools run a child agent. They differ in one thing, and it decides the
+quality of what comes back: **what the child sees.**
+
+| tool | child sees | rung | gives you | use for |
+|---|---|---|---|---|
+| **`task`** (pi-extensions `task.ts`, wraps `pi-task`) | **only your spec** — goal, named files, curated facts | L0–L2 | immutable spec, PASS/FAIL envelope, per-root boundary diff, audit dir, budgets | **any delegated work that changes files or must obey a rule** — the default |
+| **`fork`** (pi-fork) | **your entire branch**, brief appended last | L4 | prose report, effort tiers, parallel dispatch from one message | read-only exploration that needs this conversation; N independent opinions |
+
+**Pre-flight before any `fork(...)` — one *yes* makes it a `task`:**
+1. Does the brief say *do not / only / never / must not*?
+2. Will the child write, edit, commit or push anything?
+3. Do I want a PASS/FAIL I can check, rather than prose?
+
+Why the text alone did not work (and why this is now enforced): the rule above
+lived in this skill and in the global AGENTS.md for months and was still
+violated by agents that had just read it — five fork briefs in one session on
+2026-09-17, all carrying "do not", one of which returned confident verbatim
+quotes that did not exist. `fork` is a *tool*: its self-recommending
+description ("implementation, testing, review…") is in the tool list every turn
+and survives compaction; this skill is gone after the first compaction, and
+`pi-task` was a CLI to be remembered. Two structural fixes shipped 2026-09-19:
+
+- **`task` is a tool** (`extensions/task.ts`), so both rungs sit in the tool
+  list with the decision rule in their descriptions, and `promptGuidelines`
+  puts the rule in the system prompt where compaction cannot remove it. It
+  rejects, before spending a model run, the two spec errors that make a
+  violation certain (see "roots" below) and serialises overlapping tasks.
+- **`fork-gate`** (`extensions/fork-gate.ts`) is a `tool_call` hook that BLOCKS
+  a fork whose brief contains a prohibition, a write boundary or a clause-initial
+  file-changing imperative, and returns the `task(...)` call to make instead.
+  It matches wording, not intent: a genuinely read-only exploration brief that
+  trips it is rephrased, and one that cannot be rephrased without its
+  prohibition needed `task` all along. `PI_FORK_GATE=off` logs instead of
+  blocking; `/ext` disables it entirely.
+
+Minimal call:
+
+```
+task(id="slug", goal="…verbatim; the child has NO other context…",
+     deliverable="…exact shape wanted…", effort="fast|balanced|deep",
+     read_only=false,
+     roots=["/abs/repo/docs", "/abs/repo/src"],   # WATCHED, each diffed alone
+     write_allowed=["/abs/repo/docs"],            # exact subset of roots
+     facts=["verified fact"], files=["/abs/path/to/read"])
+```
+
+**Roots — the two errors the tool refuses up front.** Every root is diffed on
+its own and a delta is allowed only if that *exact root string* is in
+`write_allowed`. So (a) `write_allowed` must be a subset of `roots`, not a
+subdirectory of one, and (b) a writable root must not lie inside a watched-only
+root — the parent's porcelain would change and register a violation every time.
+List the writable part as its own root and leave the enclosing repo out. This is
+the shape the 2026-09-17 migration tasks used (sibling roots, `write_allowed`
+naming four of them) and it passed cleanly.
+
+**Overlap.** Sibling `task` calls whose roots overlap would see each other's
+writes as violations; the tool runs them one after another automatically. Do
+not rely on that for ordering *semantics* — if B needs A's output, call B after
+A returns.
+
+**What isolation does not fix.** L0 removes the *narrative* failures (parent
+voice, invented continuity, ignored prohibitions). It does not remove
+confabulation: an under-specified spec still gets a confident deliverable. The
+report prints the evidence pointers under a "SPOT-CHECK THESE" heading for a
+reason.
+
+Everything below about tiers, brief design and boundary discipline applies to
+**both** tools — a `task` spec is a brief too.

 ### Effort tier mapping

@@ -85,15 +156,15 @@ Configured in `~/.pi/agent/settings.json` under `pi-fork.effortProfiles`. The co

 **Rule of thumb:** start at `balanced` unless you have a specific reason to go up or down. Going too cheap on a deep task wastes a fork; going too expensive on a mechanical task is just slow.

-### When to fork vs. do it yourself
+### When to delegate vs. do it yourself

-Fork when **any** of:
+Having chosen the rung above, delegate (either tool) when **any** of:
 - The task requires reading many files whose contents you don't need to keep in your main context afterwards (the fork returns a dense summary; raw file contents stay in the fork's context and are discarded).
 - You want to run multiple analyses in **parallel** (especially: comparing N options, where independent reasoning is itself a signal — see "parallel forks" below).
 - The task is well-scoped enough to specify completely up front and well-bounded enough that returning a dense report is more useful than continuing the dialogue.
 - You are about to do something that would burn a lot of tokens on tool calls (long file reads, many bash invocations) whose output you will mostly discard.

-Don't fork when:
+Don't delegate when:
 - The work fits in your current context budget without crowding out what comes next.
 - The task is exploratory and you'll need to iterate based on what you find (forking turns iteration into round-trips with full task-spec rewrites).
 - You need to make decisions during the work that depend on context only the main thread has.
@@ -175,11 +246,12 @@ sits at one extreme of it. Five rungs:
 | **L3** | a **truncated tail** of the parent branch | *nothing implements this* — would need a new spec key plus `--session <trimmed snapshot>` | **no** |
 | **L4** | the **entire** parent branch | `fork(task=…)` — `getHeader()+getBranch()`, no offset or limit anywhere in the call chain | yes |

-**`pi-task` is a CLI, not an extension — it will never appear in your tool list.**
-Invoke it with `bash`: `/opt/pi-toolkit/bin/pi-task run <spec.json>` (source at
-`/workspace/pi-toolkit/bin/pi-task`, `schema` subcommand prints the spec fields).
-It reads an immutable JSON spec, and "inherit the session" is not expressible in
-that schema — the isolation is structural, not a request.
+**`pi-task` is a CLI (`/opt/pi-toolkit/bin/pi-task`, `schema` prints the spec
+fields); the `task` tool from pi-extensions wraps it** so it appears in your tool
+list next to `fork`. If the tool is absent, invoke the CLI with `bash`:
+`/opt/pi-toolkit/bin/pi-task run <spec.json>`. Either way it reads an immutable
+JSON spec, and "inherit the session" is not expressible in that schema — the
+isolation is structural, not a request.

 **Choose the lowest rung that can do the job:**

@@ -292,7 +364,17 @@ When entries conflict, **the most recent observation reflects the latest known s
 ## Quick Reference

 ```
+task(id, goal, deliverable, effort, read_only, roots, write_allowed, facts, files, commands, wall_s, usd)
+  - L0-L2: isolated child sees ONLY the spec — DEFAULT for work that writes or has rules
+  - roots[] = WATCHED (each diffed alone); write_allowed[] = exact subset of roots,
+    never nested inside a watched-only root (the tool rejects both errors up front)
+  - envelope must parse or the run FAILED; spot-check evidence pointers
+  - overlapping-root tasks are serialised; audit: ~/.pi/agent/pi-task/<stamp>-<id>/result.json
+  - CLI fallback: bash /opt/pi-toolkit/bin/pi-task run <spec.json>   (schema | selftest | run --dry-run)
+
 fork(task=..., effort=fast|balanced|deep)      # L4: child inherits your WHOLE branch
+  - ONLY for read-only exploration needing this conversation, or N parallel opinions
+  - fork-gate BLOCKS briefs with do-not/only/never, write boundaries, or "edit/commit/fix …"
  - state decision authority explicitly
  - pass verified context up front
  - specify deliverable shape
@@ -302,13 +384,6 @@ fork(task=..., effort=fast|balanced|deep)      # L4: child inherits your WHOLE b
  - write-capable? demand "What I did NOT do", then verify from git/fs, not the report
  - prohibition in the brief => not a `fast` task

-bash: /opt/pi-toolkit/bin/pi-task run <spec>   # L0-L2: isolated child, NOT a tool
-  - schema | selftest | run [--dry-run]
-  - context.facts (pasted) / .files (names only) / .commands
-  - roots[] = WATCHED, write_allowed[] = CHANGEABLE subset
-  - envelope must parse or the run FAILED
-  - audit + cost: ~/.pi/agent/pi-task/<stamp>-<id>/result.json
-
 recall(id=<12-char-hex>)
  - only when stakes justify the cost
  - id must already be visible in your context
@@ -317,8 +392,9 @@ recall(id=<12-char-hex>)

 ```
 ~/.pi/agent/settings.json
-  pi-fork.effortProfiles    — model + thinking-depth per tier
+  pi-fork.effortProfiles    — model + thinking-depth per tier (used by BOTH fork and task)
  pi-fork.defaultEffort     — usually "balanced"
+  env PI_FORK_GATE=off      — fork-gate logs instead of blocking (default: block)
  observational-memory.*    — token thresholds, model, agentMaxTurns
  observational-memory.debugLog: true  — opt-in NDJSON telemetry at
    ~/.pi/agent/observational-memory/debug/<session>.ndjson (off by default)
@@ -29,14 +29,18 @@
 # same failure mode check-skill-floor.sh was written for, and the same fix:
 # convert "someone remembers" into "CI refuses".
 #
-# WHY THESE FIVE CHECKS AND NOT MORE. Every check here compares a doc string to
-# a value that EXISTS IN THIS REPO, so it can never be wrong about the world and
-# needs no network, no token, and no built image. Claims that require a running
-# container to verify (image sizes, the "N mempalace_* tools" count) are
-# deliberately NOT gated: a check that cannot be evaluated honestly at lint time
-# would either be skipped or guessed, and a guessing gate is worse than none.
-# If you want those, assert them in scripts/smoke-test.sh where a real image is
-# available.
+# TWO CLASSES OF CHECK, DELIBERATELY. Checks 1-7 compare a doc string to a
+# value that EXISTS IN THIS REPO, so they can never be wrong about the world and
+# need no network, no token, and no built image. Checks 8-9 compare against what
+# is PUBLISHED (Docker Hub's measured sizes; the ref labels baked into the last
+# released image), because those claims have no in-repo anchor at all and had
+# rotted for exactly that reason. They need the network and therefore SKIP,
+# loudly and counted, when it is absent -- a skip is neither OK nor a failure,
+# because printing an unverified claim as OK is the habit this file exists to
+# break, while failing on a third party's uptime would make every release
+# hostage to it. Claims that need a RUNNING CONTAINER (the "N mempalace_* tools"
+# count, uncompressed on-disk sizes) are still not gated here; assert them in
+# scripts/smoke-test.sh where a real image is available.
 #
 # DELIBERATELY NOT GATED: Dockerfile.base's `# BASE_REBUILD_DATE:` comment, which
 # is also stale (2026-07-13, three base rebuilds ago). base_tag is a hash of
@@ -69,6 +73,22 @@ HUB_MAX_CHARS=25000

 WARN_ONLY=0
 FAILURES=0
+SKIPS=0
+
+# Tolerance for the published size claims (check 8), as a percentage OF THE
+# MEASURED SIZE. The denominator matters: against the claim instead, the same
+# drift reads as a different number, and an early draft of this gate took 20%
+# from the claim-relative figure and would therefore have MISSED its own
+# motivating case. Both bounds are measured, not guessed:
+#   - the rot that motivated this check: claimed 1.1 GB vs measured 1.37 GB
+#     = 19.7% off, so the threshold must sit BELOW that or the gate is theatre.
+#   - the largest legitimate skew, i.e. a claim describing the currently-published
+#     release while the next tag changes the size: v1.9.1's 1.37 GB against
+#     v1.9.2's measured 1.23 GB = 11.4% off, so the threshold must sit ABOVE that
+#     or every size-changing release trips it.
+# 15% sits in that 11.4%-19.7% window. Widen it only with a measured reason, and
+# re-derive both bounds if you do.
+SIZE_TOLERANCE_PCT="${SIZE_TOLERANCE_PCT:-15}"

 usage() {
  cat <<'EOF'
@@ -79,6 +99,11 @@ files they describe (Dockerfile.base, Dockerfile.variant).

  --warn-only   Report drift but exit 0 (advisory use, e.g. a local pre-push hook).

+Environment:
+  SKIP_SIZE_CHECK=1   skip check 8 (published size claims vs Docker Hub)
+  SKIP_REF_CHECK=1    skip check 9 (refs moved since the last release are named)
+  SIZE_TOLERANCE_PCT  check 8 tolerance, default 15 (see comment for its bounds)
+
 Exit: 0 = in sync, 1 = drift, 2 = cannot run.
 EOF
 }
@@ -124,6 +149,13 @@ fail() {

 ok() { printf '  OK    %s\n' "$1"; }

+# A check that could not be EVALUATED, as distinct from one that passed.
+# Deliberately neither ok() nor fail(): printing it as OK would launder an
+# unmeasured claim into a passing one (the exact habit this file exists to
+# break), while failing on a third party's uptime would make every release
+# hostage to Docker Hub's API. Loud, counted, and surfaced in the summary.
+skip() { SKIPS=$((SKIPS + 1)); printf '  SKIP  %s\n' "$1"; }
+
 echo "Checking hand-maintained doc claims against the build files they describe."
 echo

@@ -149,8 +181,14 @@ check_pin() {
 PI_ACTUAL="$(read_arg "$DF_VARIANT" PI_VERSION)"
 ATELIER_ACTUAL="$(read_arg "$DF_VARIANT" PI_ATELIER_REF)"
 MEMPALACE_ACTUAL="$(read_arg "$DF_BASE" MEMPALACE_VERSION)"
+# pi-obsmem became a PIN in v1.9.5 (was the floating `master`), so it joins the
+# reviewable table. It is also covered by the ref-move check below, but that one
+# can only ever report "unchanged" for a pinned SHA -- it answers "did upstream
+# move?", never "does the table still say what we bake?", which is this check.
+OBSMEM_PIN_ACTUAL="$(read_arg "$DF_VARIANT" PI_OBSMEM_REF)"

 check_pin pi              "$(read_pin_row pi)"          "$PI_ACTUAL"        "ARG PI_VERSION in $DF_VARIANT"
+check_pin pi-obsmem       "$(read_pin_row pi-obsmem)"   "$OBSMEM_PIN_ACTUAL" "ARG PI_OBSMEM_REF in $DF_VARIANT"
 check_pin pi-atelier      "$(read_pin_row pi-atelier)"  "$ATELIER_ACTUAL"   "ARG PI_ATELIER_REF in $DF_VARIANT"
 check_pin mempalace       "$(read_pin_row mempalace)"   "$MEMPALACE_ACTUAL" "ARG MEMPALACE_VERSION in $DF_BASE"

@@ -227,9 +265,429 @@ else
  ok "no stale 'Unreleased' pointers in $README or $HUB"
 fi

+# ---------------------------------------------------------------------------
+# 8. Published size claims vs Docker Hub's MEASURED full_size.
+#
+#    Why this exists: every other claim in these docs is checked against a file
+#    in this repo, so it cannot rot without someone editing the thing it
+#    describes. The size claims had no such anchor -- nothing in the repo states
+#    the image size -- so they quietly went 24% wrong across eight releases
+#    (DOCKER_HUB.md said ~1.1 GB; :latest measured 1.37 GB on 2026-09-14).
+#    DOCKER_HUB.md is POSTed to Docker Hub by update-description, so that number
+#    is the first thing a stranger reads about this image.
+#
+#    Hub's `full_size` tracks the FIRST manifest entry (amd64 here), NOT the sum
+#    across architectures -- measured: v1.9.2 full_size=1.228 GB, amd64=1.228,
+#    arm64=1.211, sum=2.439. That matches the table's per-arch "Size
+#    (compressed)" column, which is why full_size is the right field.
+#
+#    NOT COVERED, deliberately: README.md's ~3.2 GB figures are UNCOMPRESSED
+#    on-disk sizes, and the registry API exposes compressed sizes only (layer
+#    sizes in a manifest are compressed; the config blob carries no uncompressed
+#    totals). Measuring them needs a real pull, so they are out of scope here --
+#    do not read a green check 8 as covering them.
+# ---------------------------------------------------------------------------
+# Shared by checks 8 and 9: which Hub repo, and its tag list (one request).
+# Derive the repo from the doc's own rows rather than hardcoding it, so a
+# rename cannot leave these checks silently probing a repo nobody publishes to.
+# shellcheck disable=SC2016  # single quotes are deliberate: this is a sed
+# script, and its \( \) groups and \1 backreference must reach sed unexpanded.
+HUB_REPO_PATH="$(sed -n 's/^| `\([^:`]*\):[^`]*`.*/\1/p' "$HUB" | head -1)"
+HUB_TAGS_JSON=""
+HAVE_NET_TOOLS=0
+if command -v curl >/dev/null 2>&1 && command -v python3 >/dev/null 2>&1; then
+  HAVE_NET_TOOLS=1
+  if [ -n "$HUB_REPO_PATH" ] && \
+     { [ "${SKIP_SIZE_CHECK:-0}" != "1" ] || [ "${SKIP_REF_CHECK:-0}" != "1" ]; }; then
+    HUB_TAGS_JSON="$(curl -sS -m 20 \
+      "https://hub.docker.com/v2/repositories/${HUB_REPO_PATH}/tags/?page_size=100" \
+      2>/dev/null || true)"
+  fi
+fi
+
+if [ "${SKIP_SIZE_CHECK:-0}" = "1" ]; then
+  skip "size claims -- SKIP_SIZE_CHECK=1 was set"
+elif [ "$HAVE_NET_TOOLS" = 0 ]; then
+  skip "size claims -- need both curl and python3 to measure them"
+else
+  if [ -z "$HUB_REPO_PATH" ]; then
+    skip "size claims -- found no \`repo:tag\` image rows in $HUB to check"
+  else
+    if [ -z "$HUB_TAGS_JSON" ]; then
+      skip "size claims -- Docker Hub API unreachable (offline?); NOT verified"
+    else
+      SIZE_RC=0
+      # NO `|| true` on the python invocation: an early draft had one, and it
+      # swallowed the exit code so a printed DRIFT line still exited 0 -- a gate
+      # that reports the defect and passes anyway. The outer `|| SIZE_RC=$?` is
+      # what keeps `set -e` happy while preserving the code.
+      SIZE_OUT="$(HUB_MD="$HUB" HUB_JSON="$HUB_TAGS_JSON" TOL="$SIZE_TOLERANCE_PCT" \
+        python3 <<'PYEOF'
+import json, os, re, sys
+
+try:
+    data = json.loads(os.environ["HUB_JSON"])
+except (ValueError, KeyError) as exc:
+    print("  SKIP  size claims -- Hub API returned unparseable JSON (%s)" % exc)
+    sys.exit(3)
+
+# full_size == first manifest entry (amd64), which is the per-arch number the
+# table's "Size (compressed)" column claims. Verified against .images[] sizes.
+sizes = {
+    r["name"]: r["full_size"] / 1e9
+    for r in data.get("results", [])
+    if isinstance(r.get("full_size"), int) and r.get("name")
+}
+if not sizes:
+    print("  SKIP  size claims -- Hub API returned no usable tags")
+    sys.exit(3)
+
+tol = float(os.environ["TOL"])
+row = re.compile(r"^\|\s*`([^`:]+):([^`]+)`\s*\|[^|]*\|\s*~?([0-9]+(?:\.[0-9]+)?)\s*GB\s*\|")
+checked = drift = 0
+
+with open(os.environ["HUB_MD"], encoding="utf-8") as fh:
+    for line in fh:
+        m = row.match(line)
+        if not m:
+            continue  # rows saying "same", and every non-image row
+        _repo, tag, claimed = m.group(1), m.group(2), float(m.group(3))
+        if "X.Y.Z" in tag:
+            continue  # placeholder row; the concrete tag is checked instead
+        # base-<hash> is content-addressed and immutable, so its size is
+        # base-latest's by construction -- probe the alias that always exists.
+        probe = "base-latest" if tag.startswith("base-") else tag
+        actual = sizes.get(probe)
+        if actual is None:
+            print("  SKIP  size %s -- tag '%s' not present on Hub" % (tag, probe))
+            continue
+        checked += 1
+        off = abs(claimed - actual) / actual * 100
+        if off <= tol:
+            print("  OK    size %s claims ~%.2f GB, Hub measures %.2f GB (%.0f%% off)"
+                  % (tag, claimed, actual, off))
+        else:
+            drift += 1
+            print("  DRIFT size %s claims ~%.2f GB but Hub measures %.2f GB"
+                  " (%.0f%% off, tolerance %.0f%%)" % (tag, claimed, actual, off, tol))
+
+if checked == 0:
+    print("  SKIP  size claims -- no checkable rows resolved to a published tag")
+    sys.exit(3)
+sys.exit(1 if drift else 0)
+PYEOF
+)" || SIZE_RC=$?
+      printf '%s\n' "$SIZE_OUT"
+      case "$SIZE_RC" in
+        0) : ;;
+        3) SKIPS=$((SKIPS + 1)) ;;
+        *)
+          fail "a published size claim in $HUB has drifted from what Docker Hub
+      actually serves (see DRIFT above). This page is POSTed to Docker Hub by
+      update-description, so it is the first size a stranger sees. Re-measure and
+      update the table:
+        curl -sS 'https://hub.docker.com/v2/repositories/${HUB_REPO_PATH}/tags/?page_size=100' |
+          jq -r '.results[] | \"\\(.name) \\(.full_size/1e9)\"'"
+          ;;
+      esac
+    fi
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# 9. Everything the NEXT build would bake differently from the LAST PUBLISHED
+#    release must be named in the CHANGELOG text above that release's heading.
+#
+#    Why this exists, measured 2026-09-19: pi-extensions 25c1265 (a new `task`
+#    tool and a hook that blocks certain `fork` calls -- a change to how every
+#    agent in the container delegates work) and mempalace-toolkit 817b3a8 (the
+#    feed's mine deadline had never reached the transport) both reached this
+#    image through floating `*_REF=main` ARGs. Neither produced a diff in this
+#    repo, so nothing here asked for a CHANGELOG entry, and neither had one
+#    until a reader asked. This is the same shape as check 8: a fact with no
+#    in-repo anchor rots. The hand practice that existed for it -- the
+#    "Dependency audit" table in each release's notes ("Baked in vN | Upstream
+#    now") -- is precisely a "someone remembers" mechanism, and it had lapsed.
+#
+#    How it measures, with no docker/crane/token: the last published `vX.Y.Z`
+#    is the highest such tag in Hub's tag list (shared with check 8); its
+#    amd64 config blob is read through the anonymous registry API (token ->
+#    manifest index -> per-arch manifest -> config) and carries one
+#    `se.jordbo.pi-devbox.<name>-ref` label per component, each holding the
+#    SHA that build-args actually baked (resolve-versions in docker-publish.yml
+#    turns every ref into a SHA before `docker build`). "What the next build
+#    would bake" is resolved the way that job does it: a 40-hex ARG is itself,
+#    a tag or branch is `git ls-remote`d (peeled `^{}` first -- an annotated
+#    tag's un-dereferenced SHA is the tag object, a false alarm this repo has
+#    already fallen for once), pi-studio is the highest semver tag, and
+#    `PI_VERSION` / `MEMPALACE_VERSION` are compared as literals against the
+#    `pi-version` / `mempalace-version` labels (the latter set in Dockerfile.base
+#    and inherited; absent on releases before it shipped, which reports SKIP).
+#
+#    The rule: baked == would-bake is OK with no mention required. If they
+#    differ, the text ABOVE the last published version's `## ` heading -- i.e.
+#    `## Unreleased` plus any not-yet-published `## vX.Y.Z` section, which is
+#    what the release commit turns Unreleased into -- must contain the
+#    would-bake value's 7-char SHA prefix (or, for pi-studio, the tag name; for
+#    pi, the version string). Naming the SHA, not just the repo, is the point:
+#    it is what the audit table always recorded, and it makes the failure
+#    message's compare URL a copy-paste away from knowing what moved.
+#
+#    Every upstream commit therefore re-reds this gate until the CHANGELOG
+#    names the new head. That is the intended cost: the thing that gets baked
+#    is the thing that gets named, and a typo-fix upstream costs one edited
+#    SHA here. Read from the TAG like everything else in these docs -- the
+#    release commit renames Unreleased, so the pending text still covers it.
+#
+#    SKIPs, each counted: SKIP_REF_CHECK=1; no curl/python3; Hub unreachable;
+#    the release's labels unreadable; one component's upstream unreachable
+#    (that component only). A published tag whose heading is MISSING from the
+#    CHANGELOG is a failure, not a skip: that is drift in its own right.
+# ---------------------------------------------------------------------------
+if [ "${SKIP_REF_CHECK:-0}" = "1" ]; then
+  skip "ref moves -- SKIP_REF_CHECK=1 was set"
+elif [ "$HAVE_NET_TOOLS" = 0 ]; then
+  skip "ref moves -- need both curl and python3 to read the published labels"
+elif ! command -v git >/dev/null 2>&1; then
+  skip "ref moves -- need git (ls-remote) to resolve what the next build would bake"
+elif [ -z "$HUB_REPO_PATH" ]; then
+  skip "ref moves -- found no \`repo:tag\` image rows in $HUB to locate the published image"
+elif [ -z "$HUB_TAGS_JSON" ]; then
+  skip "ref moves -- Docker Hub API unreachable (offline?); NOT verified"
+else
+  # One plain top-level assignment per ARG, on purpose: read_arg exits 2 on a
+  # missing ARG, and under `set -e` that only propagates from a bare
+  # `VAR="$(...)"`. Nested inside a heredoc's $(...) the exit would be swallowed
+  # by `cat`, and a renamed ARG would leave this check comparing a label against
+  # an empty string and reporting the component "unchanged".
+  TOOLKIT_REPO="$(read_arg "$DF_VARIANT" PI_TOOLKIT_REPO)";     TOOLKIT_REF="$(read_arg "$DF_VARIANT" PI_TOOLKIT_REF)"
+  EXTENSIONS_REPO="$(read_arg "$DF_VARIANT" PI_EXTENSIONS_REPO)"; EXTENSIONS_REF="$(read_arg "$DF_VARIANT" PI_EXTENSIONS_REF)"
+  FORK_REPO="$(read_arg "$DF_VARIANT" PI_FORK_REPO)";           FORK_REF="$(read_arg "$DF_VARIANT" PI_FORK_REF)"
+  OBSMEM_REPO="$(read_arg "$DF_VARIANT" PI_OBSMEM_REPO)";       OBSMEM_REF="$(read_arg "$DF_VARIANT" PI_OBSMEM_REF)"
+  ATELIER_REPO="$(read_arg "$DF_VARIANT" PI_ATELIER_REPO)"
+  MPTK_REPO="$(read_arg "$DF_BASE" MEMPALACE_TOOLKIT_REPO)";    MPTK_REF="$(read_arg "$DF_BASE" MEMPALACE_TOOLKIT_REF)"
+  STUDIO_REPO="$(read_arg "$DF_VARIANT" PI_STUDIO_REPO)"
+  SKILLSET_SNAPSHOT="$(read_arg "$DF_VARIANT" SKILLSET_SNAPSHOT_REF)"
+  # name|kind|repo|ref -- one line per label the variant image carries.
+  # kinds: ref = branch/tag/SHA resolved like resolve-versions does;
+  #        studio = highest semver tag of the repo (label lives on <tag>-studio);
+  #        literal = the ARG value IS the baked value (a SHA pin, a version).
+  REF_COMPONENTS="pi-toolkit|ref|$TOOLKIT_REPO|$TOOLKIT_REF
+pi-extensions|ref|$EXTENSIONS_REPO|$EXTENSIONS_REF
+pi-fork|ref|$FORK_REPO|$FORK_REF
+pi-obsmem|ref|$OBSMEM_REPO|$OBSMEM_REF
+pi-atelier|ref|$ATELIER_REPO|$ATELIER_ACTUAL
+mempalace-toolkit|ref|$MPTK_REPO|$MPTK_REF
+pi-studio|studio|$STUDIO_REPO|
+skillset-snapshot|literal||$SKILLSET_SNAPSHOT
+pi-version|literal||$PI_ACTUAL
+mempalace-version|literal||$MEMPALACE_ACTUAL"
+  REF_RC=0
+  # Same discipline as check 8: no `|| true` on the python, or a printed DRIFT
+  # exits 0. Per-component SKIP lines are counted afterwards by grep, so a run
+  # that evaluated eight components and could not reach the ninth reports one
+  # skip, not a green tick over the ninth.
+  REF_OUT="$(HUB_REPO="$HUB_REPO_PATH" HUB_JSON="$HUB_TAGS_JSON" CHANGELOG="CHANGELOG.md" \
+    COMPONENTS="$REF_COMPONENTS" python3 <<'PYEOF'
+import json, os, re, subprocess, sys, urllib.request, urllib.parse
+
+SHA40 = re.compile(r"^[0-9a-f]{40}$")
+SEMVER = re.compile(r"^v?[0-9]+\.[0-9]+\.[0-9]+$")
+LABEL = "se.jordbo.pi-devbox."
+
+
+def ver_key(tag):
+    return tuple(int(x) for x in tag.lstrip("v").split("."))
+
+
+def http_json(url, headers=None, timeout=30):
+    req = urllib.request.Request(url, headers=headers or {})
+    with urllib.request.urlopen(req, timeout=timeout) as resp:
+        return json.loads(resp.read().decode("utf-8"))
+
+
+def labels_of(repo, tag):
+    """Config labels of <repo>:<tag>'s amd64 image via the anonymous registry API."""
+    tok = http_json(
+        "https://auth.docker.io/token?service=registry.docker.io&scope="
+        + urllib.parse.quote(f"repository:{repo}:pull", safe=":")
+    )["token"]
+    hdr = {
+        "Authorization": f"Bearer {tok}",
+        "Accept": ", ".join([
+            "application/vnd.oci.image.index.v1+json",
+            "application/vnd.docker.distribution.manifest.list.v2+json",
+            "application/vnd.oci.image.manifest.v1+json",
+            "application/vnd.docker.distribution.manifest.v2+json",
+        ]),
+    }
+    base = f"https://registry-1.docker.io/v2/{repo}"
+    man = http_json(f"{base}/manifests/{tag}", hdr)
+    if "manifests" in man:  # multi-arch index: pick linux/amd64, as check 8 does
+        cands = [m for m in man["manifests"]
+                 if m.get("platform", {}).get("architecture") == "amd64"
+                 and m.get("platform", {}).get("os") == "linux"]
+        if not cands:
+            raise RuntimeError("no linux/amd64 entry in the manifest index")
+        man = http_json(f"{base}/manifests/{cands[0]['digest']}", hdr)
+    cfg = http_json(f"{base}/blobs/{man['config']['digest']}", hdr)
+    return cfg.get("config", {}).get("Labels") or {}
+
+
+def ls_remote(repo, *patterns):
+    # GIT_TERMINAL_PROMPT=0: a repo flipped private must fail fast as a SKIP,
+    # not sit waiting for a username on a CI runner until the job times out.
+    env = dict(os.environ, GIT_TERMINAL_PROMPT="0")
+    out = subprocess.run(["git", "ls-remote", repo, *patterns], env=env,
+                         capture_output=True, text=True, timeout=60, check=True).stdout
+    return {line.split("\t")[1]: line.split("\t")[0] for line in out.splitlines() if "\t" in line}
+
+
+def resolve_ref(repo, ref):
+    """What docker-publish.yml's resolve-versions would pass as the build-arg."""
+    if SHA40.match(ref):
+        return ref, ref
+    refs = ls_remote(repo, f"refs/heads/{ref}", f"refs/tags/{ref}", f"refs/tags/{ref}^{{}}")
+    for key in (f"refs/tags/{ref}^{{}}", f"refs/heads/{ref}", f"refs/tags/{ref}"):
+        if key in refs:
+            return refs[key], ref
+    raise RuntimeError(f"'{ref}' is neither a branch nor a tag of {repo}")
+
+
+def resolve_studio(repo):
+    refs = ls_remote(repo, "refs/tags/*")
+    tags = {k[len("refs/tags/"):]: v for k, v in refs.items()}
+    names = sorted((t for t in tags if SEMVER.match(t)), key=ver_key)
+    if not names:
+        raise RuntimeError(f"no semver tag at {repo}")
+    tag = names[-1]
+    return tags.get(tag + "^{}", tags[tag]), tag
+
+
+def compare_url(repo, a, b):
+    root = repo[:-4] if repo.endswith(".git") else repo
+    return f"{root}/compare/{a}...{b}"
+
+
+try:
+    hub = json.loads(os.environ["HUB_JSON"])
+except (ValueError, KeyError) as exc:
+    print("  SKIP  ref moves -- Hub API returned unparseable JSON (%s)" % exc)
+    sys.exit(3)
+released = sorted((r["name"] for r in hub.get("results", [])
+                   if isinstance(r.get("name"), str) and re.fullmatch(r"v[0-9]+\.[0-9]+\.[0-9]+", r["name"])),
+                  key=ver_key)
+if not released:
+    print("  SKIP  ref moves -- Hub lists no published vX.Y.Z tag to compare against")
+    sys.exit(3)
+last = released[-1]
+repo = os.environ["HUB_REPO"]
+
+# The text every not-yet-published change lives in: everything above the last
+# published version's heading. Its absence is drift, not a skip.
+text = open(os.environ["CHANGELOG"], encoding="utf-8").read()
+# (\s|$) rather than \b: a word boundary would accept "## v1.9.2-rc1" or
+# "## v1.9.2-typo" as v1.9.2's heading. Caught by the sabotage test, not review.
+m = re.search(r"^## v?%s(\s|$)" % re.escape(last.lstrip("v")), text, re.M)
+if not m:
+    print("  DRIFT ref moves -- %s is the last PUBLISHED tag on Hub but %s has no '## %s' heading"
+          % (last, os.environ["CHANGELOG"], last))
+    sys.exit(1)
+pending = text[:m.start()].lower()
+
+try:
+    labels = labels_of(repo, last)
+except Exception as exc:  # network, auth, shape -- all "could not measure"
+    print("  SKIP  ref moves -- could not read %s:%s's labels from the registry (%s); NOT verified"
+          % (repo, last, exc))
+    sys.exit(3)
+studio_labels = None
+
+checked = drift = 0
+problems = []
+for line in os.environ["COMPONENTS"].splitlines():
+    if not line.strip():
+        continue
+    name, kind, url, ref = line.split("|", 3)
+    # <name>-ref labels hold SHAs; names that already end in -version are the
+    # label (pi-version, mempalace-version) -- a version string, compared literally.
+    key = LABEL + name if name.endswith("-version") else LABEL + name + "-ref"
+    try:
+        if kind == "studio":
+            if studio_labels is None:
+                studio_labels = labels_of(repo, last + "-studio")
+            baked = studio_labels.get(key)
+        else:
+            baked = labels.get(key)
+    except Exception as exc:
+        print("  SKIP  %-18s -- could not read %s:%s-studio's labels (%s)" % (name, repo, last, exc))
+        continue
+    if not baked:
+        print("  SKIP  %-18s -- %s carries no %s label" % (name, last, key))
+        continue
+    try:
+        if kind == "ref":
+            now, shown = resolve_ref(url, ref)
+        elif kind == "studio":
+            now, shown = resolve_studio(url)
+        else:
+            now, shown = ref, ref
+    except Exception as exc:
+        print("  SKIP  %-18s -- could not resolve what the next build would bake (%s)" % (name, exc))
+        continue
+    checked += 1
+    is_sha = bool(SHA40.match(now))
+    short = (lambda s: s[:7] if SHA40.match(s) else s)
+    if baked == now:
+        print("  OK    %-18s unchanged since %s (%s)" % (name, last, short(now)))
+        continue
+    names = [now[:7].lower()] if is_sha else [now.lower()]
+    if kind == "studio":
+        names.append(shown.lower())
+    if any(n in pending for n in names):
+        print("  OK    %-18s %s -> %s since %s, named above the %s heading"
+              % (name, short(baked), short(now), last, last))
+        continue
+    drift += 1
+    hint = compare_url(url, baked, now) if (url and is_sha and SHA40.match(baked)) else ""
+    problems.append("      %-18s %s -> %s%s" % (name, short(baked), short(now), ("   " + hint) if hint else ""))
+    print("  DRIFT %-18s %s -> %s since %s, NOT named above the %s heading"
+          % (name, short(baked), short(now), last, last))
+
+if problems:
+    print("      Name each new value (7-char SHA prefix, or the tag/version) in CHANGELOG.md above '## %s':" % last)
+    print("\n".join(problems))
+if checked == 0 and drift == 0:
+    print("  SKIP  ref moves -- no component could be evaluated")
+    sys.exit(3)
+sys.exit(1 if drift else 0)
+PYEOF
+)" || REF_RC=$?
+  printf '%s\n' "$REF_OUT"
+  REF_SKIPS="$(printf '%s\n' "$REF_OUT" | grep -c '^  SKIP  ' || true)"
+  case "$REF_RC" in
+    0) SKIPS=$((SKIPS + REF_SKIPS)) ;;
+    3) SKIPS=$((SKIPS + 1)) ;;
+    *)
+      SKIPS=$((SKIPS + REF_SKIPS))
+      fail "a component the next build would bake differently from the last published
+      release is not named in CHANGELOG.md (see DRIFT above). These reach the image
+      through floating refs, so nothing else in this repo records that they moved;
+      the CHANGELOG entry is the only place a reader of the next tag can learn it.
+      Name the new SHA (7 chars is enough) where you describe the change -- the
+      compare URL above shows what moved."
+      ;;
+  esac
+fi
+
 echo
 if [ "$FAILURES" -eq 0 ]; then
-  echo "OK: every checked doc claim matches the build files."
+  if [ "$SKIPS" -gt 0 ]; then
+    echo "OK: every checked doc claim matches the build files" \
+         "($SKIPS check(s) SKIPPED and therefore NOT verified -- see SKIP above)."
+  else
+    echo "OK: every checked doc claim matches the build files."
+  fi
  exit 0
 fi

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# Guard: Dockerfile.variant must OPEN with its BuildKit `# check=` directive.
+#
+# Why this is a gate and not a comment. BuildKit parses `# check=` ONLY before
+# any other line in the file, so moving it below the title comment — or dropping
+# it during an unrelated header edit — silently re-enables the
+# InvalidDefaultArgInFrom warning on `ARG BASE_IMAGE` / `FROM ${BASE_IMAGE}`.
+#
+# A re-enabled warning is not cosmetic. buildx attaches the warning's source
+# context to the build metadata as buildx.build.warnings[].sourceInfo.data: the
+# entire Dockerfile, base64, on ONE line. docker/build-push-action writes that
+# metadata to $GITHUB_OUTPUT as a `name<<ghadelimiter_<uuid>` heredoc, and
+# Gitea's act_runner truncates any single line at exactly 65536 chars. Since
+# base64(Dockerfile.variant) passed 64 KiB (50034 B source -> 66712 chars, cut
+# to 65536), the closing delimiter is lost and act_runner fails the job with
+#   invalid format delimiter 'ghadelimiter_...' not found before end of file
+# while attributing it to NO step: every step reports Success, the smoke suite
+# prints "0 failed", and the job is red regardless. That cost two tags —
+# v1.10.0 (run 704, where a stale clipboard assertion masked it) and v1.10.1
+# (run 707) — and most of a session to localise.
+#
+# So: one deterministic grep, run both on push AND in the publish workflow's
+# lint-gate. A check that gates only `push` lets a tag regress — the same
+# adoption slip that let doc-drift land 27 h after the v1.9.3 tag.
+#
+# Exit codes: 0 OK, 1 violation, 2 cannot-run (missing file) — matching
+# lint-shell.sh / check-skill-floor.sh / check-doc-drift.sh, because a gate that
+# cannot run must not pass.
+set -euo pipefail
+
+DF="${1:-Dockerfile.variant}"
+EXPECTED='# check=skip=InvalidDefaultArgInFrom'
+
+if [ ! -f "$DF" ]; then
+  echo "::error::check-dockerfile-directives: '$DF' not found (cannot-run)" >&2
+  exit 2
+fi
+
+first="$(head -n 1 "$DF")"
+if [ "$first" != "$EXPECTED" ]; then
+  {
+    echo "::error::$DF line 1 must be exactly: $EXPECTED"
+    echo "::error::found instead: ${first:-<empty>}"
+    echo "::error::"
+    echo "::error::BuildKit only honours '# check=' before any other line. Without it the"
+    echo "::error::InvalidDefaultArgInFrom warning returns, buildx embeds this whole file as"
+    echo "::error::base64 in buildx.build.warnings[].sourceInfo.data, that single line exceeds"
+    echo "::error::act_runner's 65536-char cap, and the smoke jobs fail with"
+    echo "::error::  invalid format delimiter 'ghadelimiter_...' not found before end of file"
+    echo "::error::and NO failing step. See the header of $DF for the full measurement."
+  } >&2
+  exit 1
+fi
+
+# Second, independent assertion: the condition the directive exists FOR. If a
+# later edit gives ARG BASE_IMAGE a default, the directive becomes dead weight
+# and should be removed deliberately rather than left to rot — and if the ARG is
+# renamed, this guard would otherwise keep passing while guarding nothing.
+if ! grep -qE '^ARG BASE_IMAGE$' "$DF"; then
+  {
+    echo "::error::$DF no longer contains a bare 'ARG BASE_IMAGE' (no default)."
+    echo "::error::That is the only thing '$EXPECTED' suppresses. Either restore the bare ARG"
+    echo "::error::or drop the directive and this guard together — do not leave a skip"
+    echo "::error::directive pointing at a check that can no longer fire."
+  } >&2
+  exit 1
+fi
+
+echo "Dockerfile directive guard OK — $DF opens with the check-skip directive and still declares a bare ARG BASE_IMAGE."
@@ -32,10 +32,16 @@
 #
 # SEVERITY CHOICE
 #   -S error is 0 findings across this repo when clean, so it is free to add.
-#   -S warning is NOT free here (19x SC2088 tilde-in-quotes in
+#   -S warning is NOT free here (20x SC2088 tilde-in-quotes in
 #   recreate-sanity-check.sh, plus assorted SC2016 — both intentional), and a
 #   noisy gate trains people to ignore it. Error-only, matching the
 #   SHELLCHECK_OPTS philosophy in lint.yml.
+#   Reproduce the count before editing it (the `$ ` prefix is load-bearing: a
+#   comment whose first word is "shellcheck" is parsed as a DIRECTIVE, and a
+#   malformed one is SC1072/SC1073 at severity error — this gate caught exactly
+#   that when the line was first written without it):
+#     $ shellcheck -S warning -f gcc scripts/*.sh rootfs/usr/local/bin/* \
+#         entrypoint*.sh hooks/* | grep -c SC2088
 #
 # Usage:  bash scripts/lint-shell.sh [root]     (default root: repo top level)
 set -uo pipefail
@@ -11,7 +11,8 @@
 #     pi-observational-memory / (studio variant) pi-studio package
 #     registrations in settings.json packages[]
 #   - Shell defaults re-seeded from /etc/skel-devbox
-#   - /tmp/sshcm exists with mode 700 (ssh ControlMaster dir)
+#   - ssh ControlMaster works: /tmp/sshcm exists 700 AND the ControlPath that
+#     ssh actually resolves (ssh -G) is a writable directory
 #   - /opt toolkits intact
 #   - Known expected-absences don't regress
 #
@@ -276,6 +277,24 @@ else
  fail "~/.pi/agent/AGENTS.md missing or not a symlink"
 fi

+# shared models.json (link-pi-models.sh) — checked only when a shared file is
+# actually mounted, so a device without one is not judged by it.
+_mj_src="${PI_MODELS_JSON-/opt/fleet-pi/models.json}"
+case "$_mj_src" in "" | off | OFF | Off) _mj_src="" ;; esac
+if [ -n "$_mj_src" ] && [ -f "$_mj_src" ]; then
+  _mj="$HOME/.pi/agent/models.json"
+  if [ -L "$_mj" ] && [ "$(readlink "$_mj")" = "$_mj_src" ]; then
+    pass "~/.pi/agent/models.json -> $_mj_src (shared custom providers)"
+  elif [ -L "$_mj" ]; then
+    warn "~/.pi/agent/models.json links to $(readlink "$_mj"), not the mounted $_mj_src"
+  elif [ -e "$_mj" ]; then
+    warn "~/.pi/agent/models.json is a real file, so the mounted $_mj_src is NOT in use"
+  else
+    fail "$_mj_src is mounted but ~/.pi/agent/models.json is missing (image without link-pi-models.sh? run: ln -s $_mj_src ~/.pi/agent/models.json)"
+  fi
+fi
+unset _mj _mj_src
+
 # 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
@@ -425,13 +444,175 @@ if [ -d /opt/pi-atelier ] && command -v jq >/dev/null 2>&1; then
 fi

 echo
-echo "-- ssh ControlMaster dir --"
+echo "-- ssh ControlMaster: socket dir + EFFECTIVE ControlPath --"
+# TWO LAYERS, and the second is the one that has actually broken in the field.
+#
+# LAYER 1 (original check): /tmp/sshcm, the directory entrypoint-user.sh creates
+# for the base image's system drop-in
+# (/etc/ssh/ssh_config.d/00-devbox-controlmaster.conf).
+#
+# LAYER 2 (added 2026-09-15): the directory a config NAMES — which is not the
+# same question, and asserting layer 1 is structurally blind to it. On
+# emb-7kj4vr4g a durable ~/.pi/ssh/config pointed ControlPath at /tmp/ssh-cm
+# (with a hyphen), a directory nothing in the image creates. EVERY ssh died
+#   unix_listener: cannot bind to path /tmp/ssh-cm/<hash>: No such file or directory
+# rc=255 with the remote command never running — while this script printed a
+# green tick for layer 1, truthfully, about the wrong object.
+#
+# The same rc=255 has a second, independent cause already documented in prose in
+# Dockerfile.base ("SSH client defaults" CAVEAT) and never verified anywhere: a
+# per-host `ControlPath ~/.ssh/cm/%r@%h:%p` inherited from a bind-mounted
+# READ-ONLY ~/.ssh. Measured to be the identical failure class:
+#   unix_listener: cannot bind to path ~/.ssh/cm/...: Read-only file system
+# So do not guess which config wins — ask ssh. `ssh -G` applies real config
+# precedence (first-obtained-value-wins, system drop-in, Include, -F override)
+# and prints the fully expanded ControlPath. Require its parent to exist and be
+# writable. Cost measured at 0.116 s for 48 hosts; -G never opens a connection.
 if [ -d /tmp/sshcm ] && [ "$(stat -c %a /tmp/sshcm 2>/dev/null)" = "700" ]; then
  pass "/tmp/sshcm exists with mode 700"
 else
  fail "/tmp/sshcm missing or not mode 700"
 fi

+# Probe one route. $1 = label, $2 = config to force with -F ("" = ssh's own
+# default precedence), $3 = severity when a ControlPath dir is unusable.
+#
+# SEVERITY SPLIT IS DELIBERATE. The default route legitimately resolves into the
+# read-only ~/.ssh on any host whose own config pins ControlPath there, and the
+# supported workaround (`ssh -F ~/.ssh-local/config`) already exists — so that
+# is a warn, not a fail. Failing it would paint this script red on every run of
+# every device, and a check that fires benignly every time is one you learn to
+# ignore. The sidecar route is the PRESCRIBED one, so there it is a hard fail.
+_ssh_cm_probe() {
+  local label="$1" cfg="${2:-}" sev="${3:-fail}"
+  local h out cm cp dir n=0 shown
+  local bad=()
+  while IFS= read -r h; do
+    [ -n "$h" ] || continue
+    if [ -n "$cfg" ]; then
+      out=$(ssh -F "$cfg" -G "$h" 2>/dev/null) || continue
+    else
+      out=$(ssh -G "$h" 2>/dev/null) || continue
+    fi
+    cm=$(printf '%s\n' "$out" | awk '/^controlmaster /{print $2; exit}')
+    case "$cm" in '' | no | none | false) continue ;; esac
+    cp=$(printf '%s\n' "$out" | awk '/^controlpath /{print $2; exit}')
+    case "$cp" in '' | none) continue ;; esac
+    n=$((n + 1))
+    dir=$(dirname "$cp")
+    if [ ! -d "$dir" ] || [ ! -w "$dir" ]; then
+      bad+=("$h")
+    fi
+  done <<< "$SSH_CM_HOSTS"
+
+  # Cap the host list. A 50-name line is the noisy gate this repo already warns
+  # about in lint-shell.sh: unreadable output is ignored output. Six names plus
+  # a count is enough to identify the class and act.
+  if [ "${#bad[@]}" -gt 0 ]; then
+    shown="${bad[*]:0:6}"
+    if [ "${#bad[@]}" -gt 6 ]; then
+      shown="$shown (+$(( ${#bad[@]} - 6 )) more)"
+    fi
+  fi
+
+  if [ "$n" -eq 0 ]; then
+    warn "$label: no host resolves to ControlMaster on — effective ControlPath not exercised"
+  elif [ "${#bad[@]}" -eq 0 ]; then
+    pass "$label: $n ControlMaster host(s), every ControlPath dir exists and is writable"
+  elif [ "$sev" = "warn" ]; then
+    warn "$label: ${#bad[@]}/$n host(s) resolve ControlPath to a missing or unwritable dir [$shown] — STRUCTURAL and permanent while ~/.ssh/config pins ControlPath inside the read-only ~/.ssh, so this line can never reach zero and is not a to-do; $_git_ssh_note (see Dockerfile.base CAVEAT)"
+  else
+    fail "$label: ${#bad[@]}/$n host(s) resolve ControlPath to a missing or unwritable dir [$shown] — ssh dies rc=255 'unix_listener: cannot bind to path' and the remote command never runs"
+  fi
+}
+
+if command -v ssh >/dev/null 2>&1; then
+  # Whether git-over-ssh already routes through the sidecar decides how much the
+  # permanent default-route warning below actually matters, so state it IN that
+  # message rather than leaving each reader to work it out. Asserted properly as
+  # its own pass/fail in the next section.
+  #
+  # THREE states, not two, and the [ -r ] test is why: core.sshCommand NAMING the
+  # sidecar does not mean the sidecar EXISTS. Without that test, the arm where the
+  # path is wired but the file is gone printed "git IS wired ... unaffected" about
+  # a state in which every single git-over-ssh call fails. Found by exercising all
+  # five arms of this check rather than only the healthy one.
+  if [ ! -r "$HOME/.ssh-local/config" ]; then
+    _git_ssh_note="there is no ssh sidecar on this host, so nothing for -F to point at and these hosts cannot multiplex at all — see the git-over-ssh check below"
+  elif command -v git >/dev/null 2>&1 &&
+       git config --global --get core.sshCommand 2>/dev/null |
+         grep -qF -- "-F $HOME/.ssh-local/config"; then
+    _git_ssh_note="git IS wired to the sidecar (core.sshCommand), so git push/fetch is unaffected; bare 'ssh' to these hosts still needs 'ssh -F ~/.ssh-local/config'"
+  else
+    _git_ssh_note="git is NOT wired to the sidecar (see the git-over-ssh check below), so both git and bare 'ssh' need 'ssh -F ~/.ssh-local/config'"
+  fi
+
+  # Concrete Host aliases only: patterns (*, ?) and negations (!) are not
+  # connectable targets, so `ssh -G` on them proves nothing.
+  _cm_cfgs=()
+  if [ -r "$HOME/.ssh/config" ]; then _cm_cfgs+=("$HOME/.ssh/config"); fi
+  if [ -r "$HOME/.ssh-local/config" ]; then _cm_cfgs+=("$HOME/.ssh-local/config"); fi
+  if [ "${#_cm_cfgs[@]}" -gt 0 ]; then
+    SSH_CM_HOSTS=$(awk 'tolower($1)=="host"{for(i=2;i<=NF;i++) if ($i !~ /[*?!]/) print $i}' \
+      "${_cm_cfgs[@]}" 2>/dev/null | sort -u)
+  else
+    SSH_CM_HOSTS=""
+  fi
+
+  if [ -z "$SSH_CM_HOSTS" ]; then
+    warn "no concrete Host aliases in ~/.ssh/config or ~/.ssh-local/config — effective ControlPath not verified"
+  else
+    _ssh_cm_probe "default ssh precedence" "" warn
+    if [ -r "$HOME/.ssh-local/config" ]; then
+      _ssh_cm_probe "ssh -F ~/.ssh-local/config" "$HOME/.ssh-local/config" fail
+    else
+      warn "~/.ssh-local/config absent — setup-lan-access.sh did not run; the prescribed multiplex route is unverified"
+    fi
+  fi
+else
+  warn "ssh not on PATH — effective ControlPath not verified"
+fi
+
+echo
+echo "-- git-over-ssh routed through the writable ssh sidecar --"
+# The one question in this area that is BINARY, FIXABLE, and therefore worth a
+# check that can reach zero and stay there.
+#
+# The ControlPath warning above cannot: while a bind-mounted ~/.ssh/config pins
+# ControlPath inside the read-only ~/.ssh, the default route will ALWAYS resolve
+# to an unwritable dir, so that line fires benignly on every run of every device
+# forever — and the script's own comment above says why that is dangerous: it is
+# a warning you learn to skip. MEASURED 2026-09-22, exactly that: an agent ran
+# this script, recorded "two by-design warnings", then two hours later hit
+# `unix_listener: cannot bind ... Read-only file system` on `git push`, failed to
+# connect it to the warning it had already read, and reinvented a /tmp/sshcm
+# workaround — while the remedy string sat inside the dismissed warning.
+# entrypoint-user.sh now wires core.sshCommand to the sidecar so nobody has to
+# know; this section asserts the wiring actually happened, which is the part a
+# reader can act on.
+if ! command -v git >/dev/null 2>&1; then
+  warn "git not on PATH — sidecar wiring not verified"
+elif [ ! -r "$HOME/.ssh-local/config" ]; then
+  # No sidecar (native Linux Docker, where setup-lan-access.sh writes none). The
+  # correct state is UNSET: -F pointing at a missing file breaks every
+  # git-over-ssh call, which is worse than the problem being solved.
+  if [ -z "$(git config --global --get core.sshCommand 2>/dev/null || true)" ]; then
+    pass "no ssh sidecar on this host and core.sshCommand correctly unset (guard holds)"
+  else
+    fail "core.sshCommand is set but ~/.ssh-local/config does not exist — every git-over-ssh call dies on a missing -F file; entrypoint-user.sh's [ -r ] guard did not hold"
+  fi
+else
+  _git_ssh_cmd=$(git config --global --get core.sshCommand 2>/dev/null || true)
+  case "$_git_ssh_cmd" in
+    *"-F $HOME/.ssh-local/config"*)
+      pass "git core.sshCommand routes through the sidecar ($_git_ssh_cmd)" ;;
+    '')
+      fail "a sidecar exists but git core.sshCommand is unset — 'git push' to any host whose config pins ControlPath inside the read-only ~/.ssh dies rc=255 behind git's misleading 'correct access rights'. entrypoint-user.sh should set it; expected on images built before that wiring landed, where the fix is: git config --global core.sshCommand \"ssh -F \$HOME/.ssh-local/config\"" ;;
+    *)
+      warn "git core.sshCommand set to something else and left alone (first-wins, deliberate): $_git_ssh_cmd" ;;
+  esac
+fi
+
 echo
 echo "-- Shell defaults re-seeded from /etc/skel-devbox --"
 if [ -f "$HOME/.bash_aliases" ]; then
@@ -30,7 +30,7 @@
 #     client bundle present + registered via `pi install`
 #   - no foreign npm-11 platform packages (@esbuild, clipboard) beyond the host
 #   - no build-time npm cache (/root/.npm) shipped in the image
-#   - esbuild compiles + clipboard native loads at every install site
+#   - esbuild compiles everywhere; clipboard present iff pi declares it
 #   - image size within threshold

 set -euo pipefail
@@ -250,6 +250,22 @@ run_expect "remote-palace-without-inbox skip is announced, not silent" \
    "MemPalace catch-up skipped"
 run "...and the skip notice names the variable that fixes it" \
    "grep -A6 'MemPalace catch-up skipped' /usr/local/bin/entrypoint-user.sh | grep -q 'MEMPALACE_PI_SSH_TARGET'"
+# git-over-ssh must be wired to the writable ssh sidecar, because ~/.ssh is
+# commonly bind-mounted READ-ONLY and a per-host `ControlPath ~/.ssh/cm/...`
+# inherited from it kills every push with `unix_listener: cannot bind ...:
+# Read-only file system` behind git's misleading "correct access rights".
+#
+# STATIC assertion, deliberately. `run` executes `docker run --entrypoint=""`, so
+# entrypoint-user.sh never runs here and `git config --global core.sshCommand` is
+# necessarily unset — asserting the VALUE in this harness would repeat the v1.8.0
+# mistake (an assertion that cannot pass, unvalidated until the next tag). What
+# IS checkable at build time is that the wiring code shipped in the image. The
+# runtime value is asserted below in the Runtime deployment section, where the
+# real entrypoint chain has run.
+run "entrypoint wires git core.sshCommand to the ssh sidecar" \
+    "grep -q 'core.sshCommand \"ssh -F' /usr/local/bin/entrypoint-user.sh"
+run "...and guards it on the sidecar existing (native Linux has none)" \
+    "grep -B2 'core.sshCommand \"ssh -F' /usr/local/bin/entrypoint-user.sh | grep -q '\\[ -r \"\$HOME/.ssh-local/config\" \\]'"
 # A remote mine that FAILS must not report success. MCP answers a hard tool
 # failure with HTTP 200 and the tool's own JSON escaped inside
 # result.content[].text, so the feeder's old `'\"error\"' in body` check could
@@ -597,6 +613,19 @@ if [ -n "$LBL" ] && [ "$LBL" != "<no value>" ]; then
 else
  printf "  ❌  OCI label se.jordbo.pi-devbox.pi-extensions-ref missing or empty\n"; FAIL=$((FAIL+1))
 fi
+# mempalace-version is set in Dockerfile.base and INHERITED by the variant, so
+# it states the pin of the base this image actually built on. It must equal the
+# installed binary: the one way they diverge is a base built with
+# INSTALL_MEMPALACE=false (label says 3.x, nothing installed) or an install that
+# resolved to something other than the pin — both invisible to a label-only
+# check. Same ground-truth rule as the manifest assertion above.
+MP_LBL=$(docker inspect --format '{{ index .Config.Labels "se.jordbo.pi-devbox.mempalace-version" }}' "$IMAGE" 2>/dev/null || true)
+MP_BIN=$(docker run --rm --entrypoint= "$IMAGE" sh -c 'mempalace --version 2>/dev/null | head -n1 | tr -d "\r"' 2>/dev/null || true); MP_BIN=${MP_BIN##* }
+if [ -n "$MP_LBL" ] && [ "$MP_LBL" != "<no value>" ] && [ "$MP_LBL" = "$MP_BIN" ]; then
+  printf "  ✅  OCI label se.jordbo.pi-devbox.mempalace-version=%s equals the installed core\n" "$MP_LBL"; PASS=$((PASS+1))
+else
+  printf "  ❌  OCI label se.jordbo.pi-devbox.mempalace-version=[%s] vs installed mempalace=[%s]\n" "$MP_LBL" "$MP_BIN"; FAIL=$((FAIL+1))
+fi

 # ── Runtime deployment (needs entrypoint to run) ──────────────────────
 echo ""
@@ -643,9 +672,28 @@ exec_test "keybindings.json (pi-toolkit)"         'test -L $HOME/.pi/agent/keybi
 exec_test "extensions ≥ 4 (pi-extensions)"        'count=$(ls -1 $HOME/.pi/agent/extensions/*.ts 2>/dev/null | wc -l); [ $count -ge 4 ] && echo "$count extensions"'
 exec_test "mempalace.ts bridge"                    'test -L $HOME/.pi/agent/extensions/mempalace.ts && echo ok'
 exec_test "settings.json bootstrapped"             'test -f $HOME/.pi/agent/settings.json && echo ok'
+exec_test "no shared models.json mounted → none linked" 'test ! -e $HOME/.pi/agent/models.json && test ! -L $HOME/.pi/agent/models.json'
+exec_test "link-pi-models.sh links a mounted models.json" 'mkdir -p /tmp/lpm && echo "{}" > /tmp/lpm/models.json && PI_MODELS_JSON=/tmp/lpm/models.json PI_CODING_AGENT_DIR=/tmp/lpm/agent bash /usr/local/lib/pi-devbox/link-pi-models.sh >/dev/null && test "$(readlink /tmp/lpm/agent/models.json)" = /tmp/lpm/models.json && rm -rf /tmp/lpm'
 exec_test "pi-devbox-environment skill linked"     'test -L $HOME/.agents/skills/pi-devbox-environment && test -f $HOME/.agents/skills/pi-devbox-environment/SKILL.md && echo ok'
 exec_test "pi-extensions skill linked (fallback)"  'test -L $HOME/.agents/skills/pi-extensions && test -f $HOME/.agents/skills/pi-extensions/SKILL.md && echo ok'
 exec_test "mempalace skill linked (fallback)"      'test -L $HOME/.agents/skills/mempalace && test -f $HOME/.agents/skills/mempalace/SKILL.md && echo ok'
+# git-over-ssh sidecar wiring, asserted as a BICONDITIONAL rather than "is set".
+# setup-lan-access.sh writes ~/.ssh-local/config only on VM-backed hosts, and a
+# CI runner is native Linux Docker — so "core.sshCommand is set" would fail here
+# for a correct image, which is precisely the v1.8.0 trap (an assertion whose
+# environment was never checked, unvalidated until the next tag). Both arms are
+# real: sidecar present => must route through it; sidecar absent => must be UNSET,
+# because -F pointing at a missing file breaks every git-over-ssh call and is
+# worse than the problem being fixed. This arm is the one CI actually exercises,
+# so CI validates the guard; the other is covered by the static greps above and
+# by scripts/recreate-sanity-check.sh on a real device.
+exec_test "git core.sshCommand matches sidecar presence" '
+  cmd=$(git config --global --get core.sshCommand 2>/dev/null || true)
+  if [ -r "$HOME/.ssh-local/config" ]; then
+    case "$cmd" in *"-F $HOME/.ssh-local/config"*) echo "wired: $cmd" ;; *) exit 1 ;; esac
+  else
+    [ -z "$cmd" ] || exit 1; echo "no sidecar, correctly unset"
+  fi'
 # The vendored mempalace snapshot is refreshed MANUALLY per release (see
 # rootfs/usr/local/share/pi-devbox/skills/VENDORED.md). Through v1.8.4 it also
 # silently SHADOWED the live skillset copy, so staleness was invisible — and the
@@ -940,11 +988,27 @@ run "no build-time npm cache shipped (/root/.npm)" \
 run "esbuild works at every install site (prune removed weight, not function)" \
  'sites=$(find /usr/lib/node_modules /opt -type d -path "*/node_modules/esbuild" -prune 2>/dev/null); if [ -z "$sites" ]; then echo "no esbuild install found at all" >&2; exit 1; fi; for d in $sites; do node -e "require(\"$d\").transformSync(\"const x:number=1\",{loader:\"ts\"})" || { echo "esbuild broken at $d" >&2; exit 1; }; done; echo ok'

-# Clipboard is the family pruned second, and its napi-rs loader picks its native
-# binding at require() time — so a successful load IS the proof that the kept
-# platform package is the one this image needs.
-run "clipboard native loads at every install site" \
-  'sites=$(find /usr/lib/node_modules /opt -type d -path "*/node_modules/@mariozechner/clipboard" -prune 2>/dev/null); if [ -z "$sites" ]; then echo "no @mariozechner/clipboard install found at all" >&2; exit 1; fi; for d in $sites; do node -e "var c=require(\"$d\"); if (typeof c.setText !== \"function\") { throw new Error(\"native binding missing\"); }" || { echo "clipboard native broken at $d" >&2; exit 1; }; done; echo ok'
+# Clipboard is the family pruned second. Upstream pi 0.86.0 (#9163) REPLACED the
+# external `@mariozechner/clipboard` dependency with bundled macOS/Windows/X11
+# helpers plus the OSC 52 fallback, so from 0.86.0 on there is nothing external to
+# prune and nothing to require(). pi 0.85.1 declared it; 0.87.1 and 1.0.0 do not.
+# This assertion therefore derives its expectation from what the image's pi
+# actually DECLARES rather than hardcoding either state: it re-arms by itself if a
+# future pi re-adds the dependency, and it still fails if an install lingers that
+# nothing depends on. Hardcoding "must exist" is what failed the v1.10.0 tag build
+# (100 passed, 1 failed, nothing published) against a perfectly correct image.
+run "clipboard native: present iff pi declares it (prune removed weight, not function)" \
+  'PKG=/usr/lib/node_modules/@earendil-works/pi-coding-agent/package.json;
+   if grep -q "\"@mariozechner/clipboard\"" "$PKG" 2>/dev/null; then declared=yes; else declared=no; fi;
+   sites=$(find /usr/lib/node_modules /opt -type d -path "*/node_modules/@mariozechner/clipboard" -prune 2>/dev/null);
+   if [ "$declared" = yes ]; then
+     [ -n "$sites" ] || { echo "pi declares @mariozechner/clipboard but NO install found - prune removed function" >&2; exit 1; };
+     for d in $sites; do node -e "var c=require(\"$d\"); if (typeof c.setText !== \"function\") { throw new Error(\"native binding missing\"); }" || { echo "clipboard native broken at $d" >&2; exit 1; }; done;
+     echo "ok: pi declares it and the native binding loads at every site";
+   else
+     [ -z "$sites" ] || { echo "pi no longer declares @mariozechner/clipboard yet installs remain: $sites" >&2; exit 1; };
+     echo "ok: pi bundles clipboard since upstream 0.86.0 (#9163); no external install expected";
+   fi'

 # ── Image size ────────────────────────────────────────────────────────
 echo ""
@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# test-link-pi-models.sh — two-sided tests for rootfs/usr/local/lib/pi-devbox/link-pi-models.sh.
+#
+# Runs the real script against a throwaway HOME / PI_CODING_AGENT_DIR, so it never
+# touches a live ~/.pi/agent. Every "must link" case has a "must NOT touch" twin:
+# the script's whole contract is that it only ever creates a link where nothing
+# exists, so the negative cases are the important half.
+#
+#   bash scripts/test-link-pi-models.sh            # CI (lint.yml) and locally
+#   LINK_PI_MODELS=/path/to/variant.sh bash scripts/test-link-pi-models.sh
+set -u
+here="$(cd "$(dirname "$0")/.." && pwd)"
+SCRIPT="${LINK_PI_MODELS:-$here/rootfs/usr/local/lib/pi-devbox/link-pi-models.sh}"
+T="$(mktemp -d)"; trap 'rm -rf "$T"' EXIT
+PASS=0; FAIL=0
+ok()  { printf '  ✅  %s\n' "$1"; PASS=$((PASS+1)); }
+bad() { printf '  ❌  %s — %s\n' "$1" "$2"; FAIL=$((FAIL+1)); }
+
+# One fresh world per case: shared dir with models.json, empty HOME, agent dir unset.
+world() {
+  rm -rf "$T/w"; mkdir -p "$T/w/shared" "$T/w/home"
+  printf '{"providers":{}}\n' > "$T/w/shared/models.json"
+  SRC="$T/w/shared/models.json"; AG="$T/w/home/.pi/agent"; DEST="$AG/models.json"
+}
+# run [env assignments...] — run the script with HOME and PI_CODING_AGENT_DIR pointed into the world.
+# "$@" goes FIRST so an option like `-u PI_MODELS_JSON` is still parsed as one by env.
+run() { OUT="$(env "$@" HOME="$T/w/home" PI_CODING_AGENT_DIR="$AG" bash "$SCRIPT" 2>&1)"; RC=$?; }
+
+echo "── link-pi-models.sh ($SCRIPT)"
+
+world; run PI_MODELS_JSON="$SRC"
+if [ "$RC" = 0 ] && [ -L "$DEST" ] && [ "$(readlink "$DEST")" = "$SRC" ] && [[ "$OUT" == *linked* ]]; then
+  ok "links models.json when the shared file exists and nothing is there (creates the agent dir)"
+else bad "link when absent" "rc=$RC link=$(readlink "$DEST" 2>&1) out=[$OUT]"; fi
+
+run PI_MODELS_JSON="$SRC"
+if [ "$RC" = 0 ] && [ -z "$OUT" ] && [ "$(readlink "$DEST")" = "$SRC" ]; then
+  ok "second run is a silent no-op (every container start runs it)"
+else bad "idempotent" "rc=$RC out=[$OUT]"; fi
+
+world; mkdir -p "$AG"; printf 'my own\n' > "$DEST"; before="$(sha256sum "$DEST")"; run PI_MODELS_JSON="$SRC"
+if [ "$RC" = 0 ] && [ ! -L "$DEST" ] && [ "$(sha256sum "$DEST")" = "$before" ] && [[ "$OUT" == NOTE*"real file"* ]]; then
+  ok "never replaces a real models.json (content unchanged, one NOTE line)"
+else bad "real file kept" "rc=$RC islink=$([ -L "$DEST" ] && echo y) out=[$OUT]"; fi
+
+world; mkdir -p "$AG"; ln -s /somewhere/else.json "$DEST"; run PI_MODELS_JSON="$SRC"
+if [ "$RC" = 0 ] && [ "$(readlink "$DEST")" = /somewhere/else.json ] && [[ "$OUT" == NOTE*"left alone"* ]]; then
+  ok "never re-points a link the user made to another file"
+else bad "foreign link kept" "rc=$RC link=$(readlink "$DEST") out=[$OUT]"; fi
+
+world; rm -f "$SRC"; run PI_MODELS_JSON="$SRC"
+if [ "$RC" = 0 ] && [ ! -e "$DEST" ] && [ ! -L "$DEST" ] && [ -z "$OUT" ]; then
+  ok "no shared file → creates nothing and says nothing (the default for most users)"
+else bad "absent source" "rc=$RC out=[$OUT]"; fi
+
+world; rm -f "$SRC"; mkdir -p "$SRC"; run PI_MODELS_JSON="$SRC"
+if [ "$RC" = 0 ] && [ ! -e "$DEST" ] && [ ! -L "$DEST" ]; then
+  ok "a directory at the path is not a models.json → nothing"
+else bad "directory source" "rc=$RC out=[$OUT]"; fi
+
+for v in off OFF ""; do
+  world; run PI_MODELS_JSON="$v"
+  if [ "$RC" = 0 ] && [ ! -e "$DEST" ] && [ ! -L "$DEST" ] && [ -z "$OUT" ]; then
+    ok "PI_MODELS_JSON='$v' disables it"
+  else bad "disable '$v'" "rc=$RC out=[$OUT]"; fi
+done
+
+world; run PI_MODELS_JSON="$SRC"; rm -f "$SRC"; run PI_MODELS_JSON="$SRC"
+if [ "$RC" = 0 ] && [ -L "$DEST" ] && [ "$(readlink "$DEST")" = "$SRC" ] && [ -z "$OUT" ]; then
+  ok "our link whose target vanished (mount removed) is left as is, silently (pi treats it as no file)"
+else bad "dangling own link" "rc=$RC out=[$OUT]"; fi
+
+# pi honours PI_CODING_AGENT_DIR, so the link must land THERE, not in $HOME/.pi/agent.
+world; AG="$T/w/elsewhere/agent"; DEST="$AG/models.json"; run PI_MODELS_JSON="$SRC"
+if [ "$RC" = 0 ] && [ "$(readlink "$DEST" 2>/dev/null)" = "$SRC" ] && [ ! -e "$T/w/home/.pi/agent/models.json" ]; then
+  ok "links into PI_CODING_AGENT_DIR when set (and leaves \$HOME/.pi/agent alone)"
+else bad "PI_CODING_AGENT_DIR" "rc=$RC link=$(readlink "$DEST" 2>&1) out=[$OUT]"; fi
+
+# 'off' must be a switch, not merely a path that happens not to exist: with a file
+# literally named "off" in the working directory it must still disable.
+world; printf '{}\n' > "$T/w/off"; OUT="$(cd "$T/w" && env PI_MODELS_JSON=off HOME="$T/w/home" PI_CODING_AGENT_DIR="$AG" bash "$SCRIPT" 2>&1)"; RC=$?
+if [ "$RC" = 0 ] && [ ! -e "$DEST" ] && [ ! -L "$DEST" ]; then
+  ok "PI_MODELS_JSON=off disables it even when a file named 'off' exists in the cwd"
+else bad "off is a switch" "rc=$RC link=$(readlink "$DEST" 2>&1) out=[$OUT]"; fi
+
+# The default path is /opt/fleet-pi/models.json. Whether it exists depends on where
+# this runs (a fleet devbox: yes; CI: no), so derive the expectation, don't assume it.
+world; run -u PI_MODELS_JSON
+if [ -f /opt/fleet-pi/models.json ]; then
+  if [ "$RC" = 0 ] && [ "$(readlink "$DEST" 2>/dev/null)" = /opt/fleet-pi/models.json ]; then
+    ok "PI_MODELS_JSON unset → default /opt/fleet-pi/models.json (present here) is linked"
+  else bad "default path (present)" "rc=$RC link=$(readlink "$DEST" 2>&1) out=[$OUT]"; fi
+else
+  if [ "$RC" = 0 ] && [ ! -e "$DEST" ] && [ ! -L "$DEST" ] && [ -z "$OUT" ]; then
+    ok "PI_MODELS_JSON unset → default /opt/fleet-pi/models.json (absent here) → nothing"
+  else bad "default path (absent)" "rc=$RC out=[$OUT]"; fi
+fi
+
+echo "── $PASS passed, $FAIL failed"
+[ "$FAIL" = 0 ]