smoke: fix the snapshot canary that blocked v1.8.7, and make it bidirectional

Run 589 built the base cleanly and then failed both smoke jobs 81-passed/1-failed on 'mempalace skill snapshot is current'. That canary greps a phrase from the vendored mempalace skill to detect a stale snapshot, and the phrase it pinned was 'Attribute what you file yourself' — the heading of the hand-stamping instruction that THIS release withdraws. So it fired correctly: the snapshot changed and the expectation did not. Every publish job was skipped, so nothing reached the registry and v1.8.7 was never consumed. Rather than bump the string: * the assertion is now BIDIRECTIONAL — the new phrase must be present AND the withdrawn one absent. A one-way canary only catches half the drift: it cannot notice a re-vendored stale snapshot that happens to contain the pinned phrase. Verified against v1.8.6's snapshot, which now correctly fails. * the comment records the structural limit rather than just the fix: a phrase canary can only ever detect 'older than what I remembered to pin', never 'older than skillset main'. Only a diff against the skillset repo can do that, which is now a Still-open item — it needs a CI clone credential for a private repo, i.e. a policy decision, not a code change. Changelog consolidated: the SSH sidecar multiplexing default moves from Unreleased into v1.8.7, since the retag will sit on a commit that contains it, and the v1.8.7 summary now records the failed first attempt rather than quietly presenting the second one as the whole story.
ssh sidecar: default to multiplexing, as a default and not an override
2026-08-26 08:09:09 +02:00 · 2026-08-25 23:09:46 +02:00 · 2026-08-25 22:47:53 +02:00 · 2026-08-25 22:27:04 +02:00 · 2026-08-25 21:11:55 +02:00 · 2026-08-25 20:33:19 +02:00
20 changed files with 2114 additions and 58 deletions
@@ -18,6 +18,19 @@ SSH_KEY_PATH=~/.ssh
 # the staged files and the palace dedup keys pointing at them cannot be
 # separated.
 #
 # That palace root is resolved with mempalace's own precedence
 # ($MEMPALACE_PALACE_PATH -> $MEMPAL_PALACE_PATH -> ~/.mempalace/config.json ->
 # ~/.mempalace/palace), and the feeders derive their stage FROM it
 # (<palace-root>/pi-stage). Neither the image nor the entrypoint exports it, by
 # design: pinning the palace without carrying the stage along re-creates the
 # very split that a shared root removed. Override it only to move the palace off
 # the default -- e.g. onto a different mount -- and only to a path with the SAME
 # persistence as the palace itself. A stage that outlives its palace (or dies
 # first) makes a scoped `mempalace sync` prune conversation drawers, because
 # their dedup key is the staged path. Setting it to the default buys nothing.
 # Unlike WORKSPACE_PATH/SSH_KEY_PATH above, this is a path INSIDE the container.
 # MEMPALACE_PALACE_PATH=/home/developer/.mempalace/palace
 #
 # To instead share ONE MemPalace across containers/harnesses (pi + opencode
 # + native), set the URL below. When set, the extension connects over HTTP
 # and NO local mempalace-mcp is spawned; the devbox-palace volume is then
@@ -57,9 +70,18 @@ SSH_KEY_PATH=~/.ssh
 # the server to mine its own local copy. Without MEMPALACE_PI_SSH_TARGET the
 # feeder is skipped (a remote palace with no inbox has nothing to mine).
 #   MEMPALACE_PI_SSH_TARGET  where to rsync to, as user@host:path
-#   MEMPALACE_PI_REMOTE_PATH what that inbox is called ON THE SERVER — must be
+#   MEMPALACE_PI_REMOTE_PATH what that inbox is called ON THE SERVER — i.e. the
-#                            the container path if the server runs in Docker
+#                            path the SERVER PROCESS can open. If the palace
-#                            (see docker-compose.mempalace.yml)
+#                            server runs in Docker, that is the container path
 #                            (see docker-compose.mempalace.yml). If it runs
 #                            NATIVELY (systemd unit / uv tool / plain
 #                            `mempalace serve`), it sees host paths, so this
 #                            must equal the path half of
 #                            MEMPALACE_PI_SSH_TARGET. Getting this wrong is
 #                            quiet: rsync still succeeds and only the mine
 #                            fails with "source directory not found", so
 #                            transcripts ship and are filed nowhere. The feeder
 #                            warns in preflight when the two paths disagree.
 #   MEMPALACE_PI_DEVICE      inbox subdirectory for this machine (default: hostname)
 # MEMPALACE_PI_SSH_TARGET=user@palace-host:/srv/mempalace-feed
 # MEMPALACE_PI_REMOTE_PATH=/data/feed
@@ -18,6 +18,14 @@ name: Publish Docker Image
 #   5. build-variant    multi-arch push of latest + vX.Y.Z tags.
 #   6. promote-base-latest  re-tag base-<hash> → base-latest with `crane copy`.
 #   7. update-description   patch Docker Hub description.
 #
 # Note the trigger: `push: tags: v*` (plus workflow_dispatch). Nothing here runs
 # on a push to main, so a smoke assertion added outside a release is UNVALIDATED
 # until the next tag — which is exactly how v1.8.0 shipped a broken assertion
 # written three days earlier (it asserted a literal /home/developer stage path,
 # while `run` executes `docker run --entrypoint=""` as root with HOME=/root).
 # The `smoke_only` dispatch input exists to close that gap: it runs steps 1-4
 # against HEAD and stops before anything is published.
 on:
  push:
@@ -33,6 +41,10 @@ on:
        description: 'Update latest aliases (default true for tag-push, false for manual test runs)'
        required: false
        default: 'false'
      smoke_only:
        description: 'Build base + run both smoke jobs against HEAD, then stop. Publishes nothing. Use to validate smoke assertions without cutting a tag.'
        required: false
        default: 'false'
 concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
@@ -130,6 +142,7 @@ jobs:
      image: catthehacker/ubuntu:act-latest
    outputs:
      pi_version: ${{ steps.resolve.outputs.pi_version }}
      mempalace_version: ${{ steps.resolve.outputs.mempalace_version }}
      fork_ref: ${{ steps.resolve.outputs.fork_ref }}
      obsmem_ref: ${{ steps.resolve.outputs.obsmem_ref }}
      toolkit_ref: ${{ steps.resolve.outputs.toolkit_ref }}
@@ -165,6 +178,40 @@ jobs:
            fi
          }
          # Read a commit SHA from Gitea, surviving a bad build token.
          #
          # These repos are public (see the note at the call sites), so auth is
          # a convenience, not a requirement — but Gitea REJECTS an invalid
          # token (401) rather than ignoring it, so a revoked or malformed
          # GITEA_BUILD_TOKEN could fail an entire release on reads that work
          # fine anonymously. An ABSENT secret was always safe (Gitea ignores an
          # empty `token ` value and serves the request, 200); a STALE one was
          # not. So: try authed, and on 401/403 retry anonymously.
          #
          # A non-200 after that emits nothing and returns 0 deliberately, so
          # require_sha raises the loud explicit abort rather than this helper
          # inventing a fallback ref.
          #
          # Messages go to STDERR, not as ::warning:: annotations: this
          # function's stdout IS the SHA, so anything written there would be
          # captured into the ref by the command substitution.
          gitea_sha() { # $1=repo
            local repo="$1" url resp code
            url="https://gitea.jordbo.se/api/v1/repos/joakimp/${repo}/commits?limit=1&sha=main"
            resp=$(curl -s -w '\n%{http_code}' -H "$AUTH_HEADER" "$url" || printf '\n000')
            code=${resp##*$'\n'}
            if [ "$code" = "401" ] || [ "$code" = "403" ]; then
              printf 'WARNING: Gitea rejected the build token for %s (HTTP %s); retrying anonymously. The read should succeed (public repo), but GITEA_BUILD_TOKEN is stale or malformed and should be rotated.\n' "$repo" "$code" >&2
              resp=$(curl -s -w '\n%{http_code}' "$url" || printf '\n000')
              code=${resp##*$'\n'}
            fi
            if [ "$code" != "200" ]; then
              printf 'WARNING: Gitea commit lookup for %s returned HTTP %s\n' "$repo" "$code" >&2
              return 0
            fi
            printf '%s' "${resp%$'\n'*}" | jq -r '.[0].sha // empty' 2>/dev/null || true
          }
          # ── pi version: from the PIN, not from npm `latest` ───────────
          # Until v1.7.0 this followed npm `latest`, which meant every release
          # silently adopted whatever pi had shipped that morning — unaudited —
@@ -196,6 +243,54 @@ jobs:
          fi
          echo "pi_version=${PI_VERSION}" >> "$GITHUB_OUTPUT"
          # ── mempalace core: same audit as pi, from Dockerfile.base ────
          # Until now this pin had NO CI-side audit at all — a literal string
          # in Dockerfile.base with zero references in this workflow, while
          # PI_VERSION got a concreteness gate, a published-on-registry check
          # and a drift warning. It is the same class of risk: the palace's MCP
          # tool schema is the agent-facing contract, and a client/server skew
          # against the shared central palace is a fleet-wide, not local,
          # problem. Read from Dockerfile.base (not duplicated here) so a local
          # `docker build` and CI install the same version by construction.
          MEMPALACE_VERSION=$(sed -n 's/^ARG MEMPALACE_VERSION=\([^[:space:]]*\).*/\1/p' Dockerfile.base | head -n1)
          if ! printf '%s' "${MEMPALACE_VERSION:-}" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
            echo "::error::ARG MEMPALACE_VERSION in Dockerfile.base is not a concrete version (got '${MEMPALACE_VERSION:-<empty>}'). CI refuses to build from a floating palace version — see the pin policy comment above that ARG."
            exit 1
          fi
          # One fetch, two gates. `curl -sf` exits non-zero and prints nothing
          # on 404 (PyPI's answer for an unpublished version), so an empty body
          # lands in the "not published" branch with its own message.
          MEMPALACE_PYPI=$(curl -sf "https://pypi.org/pypi/mempalace/${MEMPALACE_VERSION}/json" || true)
          MEMPALACE_PUBLISHED=$(printf '%s' "$MEMPALACE_PYPI" | jq -r '.info.version // empty' 2>/dev/null || true)
          if [ "${MEMPALACE_PUBLISHED:-}" != "${MEMPALACE_VERSION}" ]; then
            echo "::error::Pinned mempalace version ${MEMPALACE_VERSION} is not published on PyPI (registry returned '${MEMPALACE_PUBLISHED:-<empty>}'). Fix ARG MEMPALACE_VERSION in Dockerfile.base."
            exit 1
          fi
          # A yanked release still installs when pinned exactly (PEP 592), so
          # `uv tool install mempalace==X` would succeed silently and ship a
          # version upstream has withdrawn to the whole fleet. The escape hatch
          # is the same one-line bump that got us here.
          MEMPALACE_YANKED=$(printf '%s' "$MEMPALACE_PYPI" | jq -r '.info.yanked // false' 2>/dev/null || true)
          if [ "${MEMPALACE_YANKED:-false}" = "true" ]; then
            # Reason hoisted into its own variable rather than inlined as a
            # $(...) inside the message: a jq program nested in a substitution
            # inside a double-quoted string needs escaping that silently breaks
            # the FILTER (jq compile error) while the surrounding `exit 1` still
            # fires, so the gate looks correct and reports garbage. Caught by
            # the mutation test, not by review.
            MEMPALACE_YANK_REASON=$(printf '%s' "$MEMPALACE_PYPI" | jq -r '.info.yanked_reason // "no reason given"' 2>/dev/null || true)
            echo "::error::Pinned mempalace version ${MEMPALACE_VERSION} is YANKED on PyPI (${MEMPALACE_YANK_REASON:-no reason given}). An exact pin installs a yanked release without complaint — bump ARG MEMPALACE_VERSION in Dockerfile.base."
            exit 1
          fi
          # Informational only, exactly like pi's npm drift warning: a newer
          # palace must never be adopted implicitly. `|| true` so a transient
          # PyPI failure cannot fail a release whose pin is already verified.
          MEMPALACE_PYPI_LATEST=$(curl -sf "https://pypi.org/pypi/mempalace/json" | jq -r '.info.version // empty' 2>/dev/null || true)
          if [ -n "${MEMPALACE_PYPI_LATEST:-}" ] && [ "${MEMPALACE_PYPI_LATEST}" != "${MEMPALACE_VERSION}" ]; then
            echo "::warning::mempalace ${MEMPALACE_PYPI_LATEST} is published; this build ships the audited pin ${MEMPALACE_VERSION}. To adopt it: read the upstream CHANGELOG for MCP tool-schema changes (the agent-facing contract) and for sync/delete semantics, check the skew it introduces against the central palace host's server version, then bump ARG MEMPALACE_VERSION in Dockerfile.base and note the audit in CHANGELOG.md."
          fi
          echo "mempalace_version=${MEMPALACE_VERSION}" >> "$GITHUB_OUTPUT"
          # pi-fork / pi-observational-memory (GitHub) → commit SHAs.
          FORK_REF=$(curl -sf -H "Accept: application/vnd.github.sha" \
            "https://api.github.com/repos/elpapi42/pi-fork/commits/master" || true)
@@ -226,15 +321,27 @@ jobs:
          echo "atelier_ref=${ATELIER_REF}" >> "$GITHUB_OUTPUT"
          echo "atelier_tag=${ATELIER_TAG}" >> "$GITHUB_OUTPUT"
-          # pi-toolkit / pi-extensions (Gitea) → commit SHAs. Gitea API
+          # pi-toolkit / pi-extensions (Gitea) → commit SHAs. All three Gitea
-          # requires auth even for public-repo commit listing.
+          # repos read in this step are PUBLIC: an unauthenticated GET of these
-          TOOLKIT_REF=$(curl -sf -H "$AUTH_HEADER" \
+          # commit endpoints returns 200 with the IDENTICAL sha (verified
-            "https://gitea.jordbo.se/api/v1/repos/joakimp/pi-toolkit/commits?limit=1&sha=main" \
+          # 2026-08-15 for pi-toolkit, pi-extensions and mempalace-toolkit).
-            | jq -r '.[0].sha // empty' 2>/dev/null || true)
+          # The comment that used to sit here claimed the Gitea API "requires
          # auth even for public-repo commit listing" — it does not. Only
          # /api/v1/repos/*/actions/* refuses anonymous reads (401), which is
          # what that claim was almost certainly generalised from.
          #
          # The header is still passed on purpose: it keeps working if a repo is
          # ever flipped private, and an ABSENT secret degrades cleanly, because
          # Gitea ignores an empty `token ` value and serves the request
          # anonymously (200). The real hazard is the opposite one — a REVOKED or
          # malformed token returns 401 where anonymous would have returned 200,
          # so a stale GITEA_BUILD_TOKEN turns a healthy public read into a
          # require_sha failure that reads like an API or network fault. If this
          # step ever fails on a repo you can browse anonymously, suspect the
          # token before you suspect Gitea.
          TOOLKIT_REF=$(gitea_sha pi-toolkit)
          require_sha PI_TOOLKIT_REF "$TOOLKIT_REF"
-          EXTENSIONS_REF=$(curl -sf -H "$AUTH_HEADER" \
+          EXTENSIONS_REF=$(gitea_sha pi-extensions)
            "https://gitea.jordbo.se/api/v1/repos/joakimp/pi-extensions/commits?limit=1&sha=main" \
            | jq -r '.[0].sha // empty' 2>/dev/null || true)
          require_sha PI_EXTENSIONS_REF "$EXTENSIONS_REF"
          echo "toolkit_ref=${TOOLKIT_REF}"        >> "$GITHUB_OUTPUT"
          echo "extensions_ref=${EXTENSIONS_REF}"  >> "$GITHUB_OUTPUT"
@@ -244,9 +351,7 @@ jobs:
          # into the base-decide hash (see that job) to force a base rebuild
          # when the toolkit moves — otherwise a toolkit-only fix silently
          # fails to land unless Dockerfile.base itself changes.
-          MEMPALACE_TOOLKIT_REF=$(curl -sf -H "$AUTH_HEADER" \
+          MEMPALACE_TOOLKIT_REF=$(gitea_sha mempalace-toolkit)
            "https://gitea.jordbo.se/api/v1/repos/joakimp/mempalace-toolkit/commits?limit=1&sha=main" \
            | jq -r '.[0].sha // empty' 2>/dev/null || true)
          require_sha MEMPALACE_TOOLKIT_REF "$MEMPALACE_TOOLKIT_REF"
          echo "mempalace_toolkit_ref=${MEMPALACE_TOOLKIT_REF}" >> "$GITHUB_OUTPUT"
@@ -281,6 +386,7 @@ jobs:
          echo "studio_tag=${STUDIO_TAG}" >> "$GITHUB_OUTPUT"
          echo "Resolved PI_VERSION=${PI_VERSION} (pinned in Dockerfile.variant; npm latest is ${PI_NPM_LATEST:-unknown})"
          echo "Resolved MEMPALACE_VERSION=${MEMPALACE_VERSION} (pinned in Dockerfile.base; PyPI latest is ${MEMPALACE_PYPI_LATEST:-unknown})"
          echo "Resolved PI_ATELIER_REF=${ATELIER_REF} (pi-atelier ${ATELIER_TAG}, pinned)"
          echo "Resolved PI_FORK_REF=${FORK_REF}, PI_OBSMEM_REF=${OBSMEM_REF}"
          echo "Resolved PI_TOOLKIT_REF=${TOOLKIT_REF}, PI_EXTENSIONS_REF=${EXTENSIONS_REF}"
@@ -415,6 +521,7 @@ jobs:
      - name: Smoke test (amd64)
        env:
          EXPECTED_PI_VERSION: ${{ needs.resolve-versions.outputs.pi_version }}
          EXPECTED_MEMPALACE_VERSION: ${{ needs.resolve-versions.outputs.mempalace_version }}
        run: bash scripts/smoke-test.sh pi-devbox:smoke
  # ── Phase 3b: amd64 smoke for the studio variant ────────────────────
@@ -477,11 +584,20 @@ jobs:
      - name: Smoke test studio (amd64)
        env:
          EXPECTED_PI_VERSION: ${{ needs.resolve-versions.outputs.pi_version }}
          EXPECTED_MEMPALACE_VERSION: ${{ needs.resolve-versions.outputs.mempalace_version }}
        run: bash scripts/smoke-test.sh pi-devbox:smoke-studio
  # ── Phase 4: multi-arch publish ─────────────────────────────────────
  build-variant:
    needs: [base-decide, smoke, resolve-versions]
    # A `smoke_only` dispatch stops the pipeline here: base is probed/built and
    # both smoke jobs run, but nothing is published. Deliberately NOT wrapped in
    # always() — specifying `if:` keeps the implicit "all needs succeeded" gate,
    # so a failing smoke still blocks the release. On a tag push `inputs` is
    # unset, and `null != 'true'` is true, so releases are unaffected.
    # promote-base-latest and update-description need build-variant to have
    # succeeded, so they skip on their own — no extra guard required.
    if: inputs.smoke_only != 'true'
    runs-on: ubuntu-latest
    container:
      image: catthehacker/ubuntu:act-latest
@@ -574,6 +690,7 @@ jobs:
  # or fail independently of the core release.
  build-variant-studio:
    needs: [base-decide, smoke-studio, resolve-versions]
    if: inputs.smoke_only != 'true'
    runs-on: ubuntu-latest
    container:
      image: catthehacker/ubuntu:act-latest
@@ -52,6 +52,55 @@ jobs:
          apt-get update
          apt-get install -y --no-install-recommends shellcheck python3-yaml
      - name: "Shellcheck + syntax-check repository scripts (severity: error)"
        # Gap being closed: everything else in this job shellchecks workflow
        # `run:` steps ONLY, via actionlint. The repo's own shell scripts —
        # entrypoint.sh, scripts/*.sh, and the extensionless tools under
        # rootfs/usr/local/bin/ — have never been shellchecked. That exact gap
        # (a sibling repo with no shell-script lint at all) is how a defect
        # shipped invisibly for two months: `echo "$json" | python3 <<'EOF'
        # ... json.load(sys.stdin)` cannot work — with no script argument
        # python reads its SCRIPT from stdin, so the heredoc IS stdin and the
        # json.load call hits EOF. shellcheck flags exactly this at severity
        # ERROR (SC2259, "This redirection overrides piped input"); nothing
        # ever ran it. Measured before adding this gate: `-S error` is 0
        # findings across every shell file in THIS repo today, so it is free
        # to add. `-S warning` is NOT free here (19x SC2088 tilde-in-quotes in
        # scripts/recreate-sanity-check.sh, plus assorted SC2016 — both
        # intentional), so warning-level would train people to ignore the job;
        # hence error-only, matching the SHELLCHECK_OPTS philosophy below.
        #
        # Discovery is *.sh UNION a shebang scan, because rootfs/usr/local/
        # bin/{pi-devbox-version,devbox-skill-reconcile,dot-watch,studio-expose}
        # are shell scripts with no extension. -print0/mapfile -d '' so a path
        # with a space cannot silently split, and the file count is asserted
        # non-zero — a green tick over an empty file set is not a check.
        run: |
          # Union of two signals, because either alone misses a real case:
          # a shebang scan misses a sourced fragment with no shebang, and a
          # *.sh glob misses the extensionless tools in rootfs/usr/local/bin/.
          # Silent skipping is precisely the failure mode this gate exists to
          # prevent, so err toward over-collecting.
          mapfile -d '' -t all_files < <(find . -not -path './.git/*' -type f -print0)
          sh_files=()
          for f in "${all_files[@]}"; do
            case "$f" in *.sh) sh_files+=("$f"); continue;; esac
            if head -n1 "$f" 2>/dev/null | grep -qE '^#!.*\b(bash|sh)\b'; then
              sh_files+=("$f")
            fi
          done
          echo "Checking ${#sh_files[@]} shell file(s)"
          if [ "${#sh_files[@]}" -eq 0 ]; then
            echo "::error::no shell files found — the shebang scan or the checkout is wrong"
            exit 1
          fi
          shellcheck -S error -f gcc "${sh_files[@]}"
          rc=0
          for f in "${sh_files[@]}"; do
            bash -n "$f" || { echo "::error file=$f::bash -n failed"; rc=1; }
          done
          exit "$rc"
      - name: Gitea shell guard (catches the actionlint blind spot)
        # actionlint models GitHub Actions, where the default run shell is
        # bash, so it does NOT flag bash syntax in a step that merely OMITS
@@ -76,10 +76,15 @@ re-brand of opencode-devbox's `pi-only` variant.
 4. Push tag: `git tag vX.Y.Z && git push origin vX.Y.Z`.
 5. Watch CI: smoke job builds amd64 only and asserts size + extensions +
   pi version + new-base-tooling presence. Variant build is multi-arch
-   (amd64 + arm64) only after smoke passes. **A tag push produces two runs, not
+   (amd64 + arm64) only after smoke passes. A tag push fires **only**
-   one** — `lint.yml` fires on every push (including tag refs) and
+   `docker-publish.yml` — `lint.yml` is scoped to `branches: ['**']`, which
-   `docker-publish.yml` fires on `v*` tags. Watch the **publish** run; see
+   excludes tag refs on purpose (the tagged tree was already linted when the
-   *Gitea API access* below for how to find it without picking lint by mistake.
+   commit hit `main`, and a fast lint run sorting above the slow publish run
   made releases look finished before anything shipped). Verified on v1.8.4:
   `refs/tags/v1.8.4` produced run 571 (publish) and nothing else. Still filter
   discovery on `head_sha` **and** the workflow `path` — see *Gitea API access*
   below — because that guard costs nothing and a future workflow added on `v*`
   would silently reintroduce the ambiguity.
 6. Verify the Hub tags appear (latest + vX.Y.Z, the `-studio` pair, plus
   base-latest if the base was rebuilt this run).
 7. **Revoke any short-lived Gitea PAT** used during the release at
@@ -87,6 +92,34 @@ re-brand of opencode-devbox's `pi-only` variant.
   `GITEA_ACCESS_TOKEN` env var instead (see *Gitea API access* below) —
   its lifecycle is managed host-side, nothing to revoke.
 ## Verifying this repo's reality from inside a container
 Most work on this repo happens **inside** a pi-devbox container, inspecting a
 host or a peer over SSH. That setup manufactures convincing false negatives, so
 when you are about to report that something is **absent, unreachable, or not
 running**, suspect your own command first. Recurring instances:
 - **`docker` is not on the host's non-interactive SSH `PATH`.** `ssh mac 'docker
  ps'` says *command not found* on a host that plainly runs Docker; use
  `/usr/local/bin/docker` (or `command -v docker` first). Every step in the
  *Release-day checklist* that inspects a running container hits this.
 - **Don't `| head -N` a search whose answer you don't already know.** The host's
  `~/.ssh/config` is ~500 lines; a `head -20` "proved" a peer absent that was
  defined at line 454.
 - **The deployment compose file is not this repo's.** `docker-compose.yml` here
  is a template pinning `:latest`; a real host runs its own per-machine file
  (find it with `docker inspect <container> --format '{{ index .Config.Labels
  "com.docker.compose.project.config_files" }}'`). Recreating from the repo copy
  can silently move a host off `:latest-studio` onto `:latest`.
 - **A live SSH ControlMaster hides remote auth changes** — after editing a
  peer's `authorized_keys`, prove access with `-o ControlPath=none -o
  ControlMaster=no`, or the breakage surfaces in a later session instead.
 Depth and further mechanisms: the repo-authored `pi-devbox-environment` skill
 (`rootfs/usr/local/share/pi-devbox/skills/pi-devbox-environment/SKILL.md`) §2
 and §3 — that file is the one an agent actually loads mid-session, whereas this
 `AGENTS.md` is only auto-read when the cwd *is* this repo.
 ## Gitea API access (env token)
 `GITEA_ACCESS_TOKEN` + `GITEA_HOST` are passed into the container from the
@@ -65,12 +65,19 @@ The entrypoint deploys/registers all of these on first container start. Re-runni
 ### Document and image tooling
 - **pandoc** — universal Markdown↔HTML/Org/RST/etc. conversion. Useful well beyond pi: agent-driven doc exports, format conversion, etc.
 - **Typst** — markup-based typesetting, used as pandoc's `--pdf-engine`
 - **graphviz** (`dot`) — diagram rendering pipelines
 - **imagemagick** (`magick`) — image conversion / resizing
 ### Browser automation
 - **agent-browser** — CLI for driving a real browser (open pages, click/fill/`eval`, snapshot the DOM, screenshots) so agents can verify front-end work instead of guessing
 - **Playwright** + a headless **Chromium** are pre-installed and pinned together; `AGENT_BROWSER_EXECUTABLE_PATH` is preset to the baked browser, so `agent-browser open <url>` works out of the box with no setup
 - **socat** — TCP bridge used to expose the pi-studio server outside the container's loopback
 ### Modern CLI tooling
- **Editor**: neovim (LazyVim defaults), tmux (configured for 0-indexed sessions)
+- **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
@@ -384,7 +384,60 @@ ARG INSTALL_MEMPALACE=true
 # mempalace_checkpoint (#2023/#2034).
 #
 # Keep in lockstep with opencode-devbox when bumping.
-ARG MEMPALACE_VERSION=3.6.0
+#
 # 3.7.1 (from 3.6.0) is safe for anyone with an EXISTING LOCAL palace: verified
 # against the 3.7.1 source, not the changelog. Legacy drawers lack the new
 # `chunk_total` marker and both decision sites trust them ("trust the match as
 # before"), NORMALIZE_VERSION is 2 in both, chromadb stays <2 (no index-format
 # migration), there is no auto-migration ("We do NOT auto-migrate"), and the one
 # new palace file (logstream.sqlite3) is created lazily on first logstream use.
 # Two behaviour changes to know: MEMPALACE_MCP_ALLOW_PEER_WRITER no longer works
 # on local/chroma palaces, and writer-lock setup failures now fail CLOSED
 # (refuse the write) rather than fail open. Neither affects the container's
 # normal MCP-server-plus-CLI-feeder pattern, which already serialised on the
 # same lock under 3.6.0.
 #
 # 3.8.0 (2026-08-23, PyPI, released hours after this project's own v1.8.5 tag
 # the same day) is additive/reliability only — reviewed for MCP tool-schema
 # changes before bumping, as always: there are NONE. Two PRs matter:
 #   - PR #2320/#2322: `sync --apply` no longer deletes a drawer solely because
 #     its source_file was unreachable AT THAT MOMENT — it now asks for
 #     corroboration first. This fixes losing a whole mined project to one
 #     `sync --apply` while its volume happened to be unmounted.
 #     IMPORTANT — do not over-read this fix: it addresses TRANSIENT
 #     unreachability, not the standing landmine (documented in the operator's
 #     global AGENTS.md) against running `mempalace_sync` / `mempalace_delete_by_source`
 #     beyond dry-run on the SHARED central palace. On that palace most
 #     source_file paths are PERMANENTLY absent from whichever host runs the
 #     sync — a different machine's paths simply do not exist here, ever, not
 #     merely "right now". That is a different failure shape than #2320/#2322
 #     fixes. The landmine still stands; this bump does not relax it.
 #   - PR #2307: long-running Chroma servers no longer invalidate their own
 #     HNSW cache on their own writes (server-side perf fix). This does NOT
 #     make `mempalace_reconnect` unnecessary — that tool exists for EXTERNAL
 #     writes bypassing the in-process client (e.g. direct sqlite backfills,
 #     CLI commands against a running server), a different scenario #2307
 #     does not touch.
 #
 # CI-side audit (added after v1.8.6, closing that release's "Still open" item):
 # resolve-versions now treats this pin exactly as it treats PI_VERSION — it
 # reads the ARG from THIS file, refuses a non-concrete value, verifies the
 # version is published on PyPI, refuses a YANKED release (an exact pin installs
 # one silently under PEP 592), and WARNS — never silently adopts — when PyPI has
 # a newer release. smoke-test.sh then asserts the installed core equals that
 # audited pin, which catches a stale cached base layer that no manifest-internal
 # check can see. So a bump here is now gated end to end; what remains manual is
 # the JUDGEMENT above (MCP schema review, server/client sequencing), which is
 # the part that should stay manual.
 #
 # Deployment sequencing note for whoever ships this bump: synlig (the shared
 # central palace host) currently serves mempalace 3.7.1 SERVER-SIDE via
 # docker-compose.mempalace.yml, which reuses this same devbox image. 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.
 ARG MEMPALACE_VERSION=3.8.0
 ENV UV_TOOL_DIR=/opt/uv-tools
 ENV UV_TOOL_BIN_DIR=/usr/local/bin
 RUN if [ "${INSTALL_MEMPALACE}" = "true" ]; then \
@@ -425,11 +478,14 @@ RUN if [ "${INSTALL_MEMPALACE}" = "true" ] && [ "${INSTALL_MEMPALACE_TOOLKIT}" =
      ln -sf /opt/mempalace-toolkit/bin/mempalace-session /usr/local/bin/mempalace-session && \
      ln -sf /opt/mempalace-toolkit/bin/mempalace-docs    /usr/local/bin/mempalace-docs && \
      ln -sf /opt/mempalace-toolkit/bin/mempalace-pi-session /usr/local/bin/mempalace-pi-session && \
      ln -sf /opt/mempalace-toolkit/bin/mempalace-census  /usr/local/bin/mempalace-census && \
      chmod +x /opt/mempalace-toolkit/bin/mempalace-session /opt/mempalace-toolkit/bin/mempalace-docs \
-               /opt/mempalace-toolkit/bin/mempalace-pi-session && \
+               /opt/mempalace-toolkit/bin/mempalace-pi-session \
               /opt/mempalace-toolkit/bin/mempalace-census && \
      mempalace-session --help >/dev/null && \
      mempalace-docs    --help >/dev/null && \
      mempalace-pi-session --help >/dev/null && \
      mempalace-census  --help >/dev/null && \
      echo "mempalace-toolkit installed at $(cd /opt/mempalace-toolkit && git rev-parse --short HEAD)" ; \
    fi
@@ -671,12 +727,14 @@ COPY rootfs/usr/local/share/pi-devbox/ /usr/local/share/pi-devbox/
 COPY rootfs/usr/local/bin/studio-expose /usr/local/bin/studio-expose
 COPY rootfs/usr/local/bin/dot-watch /usr/local/bin/dot-watch
 COPY rootfs/usr/local/bin/pi-devbox-version /usr/local/bin/pi-devbox-version
 COPY rootfs/usr/local/bin/devbox-skill-reconcile /usr/local/bin/devbox-skill-reconcile
 COPY entrypoint.sh /usr/local/bin/entrypoint.sh
 COPY entrypoint-user.sh /usr/local/bin/entrypoint-user.sh
 RUN chmod +x /usr/local/bin/entrypoint.sh /usr/local/bin/entrypoint-user.sh \
    /usr/local/bin/studio-expose \
    /usr/local/bin/dot-watch \
    /usr/local/bin/pi-devbox-version \
    /usr/local/bin/devbox-skill-reconcile \
    /usr/local/lib/pi-devbox/*.sh 2>/dev/null || true
 # Start as root — entrypoint adjusts UID/GID then drops to developer
@@ -56,7 +56,22 @@ ARG USER_NAME=developer
 # current when it was first populated (shipped the same bytes for pi-devbox
 # v0.74.0..v0.75.5; discovered + fixed in v0.75.5b, 2026-05-23). The `latest`
 # branch below is kept only for a deliberate local `docker build` override.
-ARG PI_VERSION=0.84.2
+#
 # AUDITED AT 0.84.3 (2026-08-25, was 0.84.2): upstream's notes carry a
 # "Breaking Changes" heading — `GoogleThinkingLevel` renamed to
 # `GoogleApiThinkingLevel`. INERT FOR THIS IMAGE: all four vendored companions
 # (/opt/pi-fork, /opt/pi-observational-memory, /opt/pi-atelier, /opt/pi-studio)
 # were grepped for that symbol and reference it ZERO times, so nothing here
 # couples to the renamed type. Recorded because the heading will look alarming
 # to the next reader doing step 1 above — the audit is done, don't redo it.
 # Adopted for two fixes that land squarely on this repo's own vendored-skill
 # wiring (see devbox-skill-reconcile, v1.8.5): nested Markdown skills inside
 # `.agents/skills/<group>/` directories were not discovered, and root Markdown
 # files such as README.md / AGENTS.md inside a skill dir were reported as
 # broken skills unless they declared valid skill frontmatter.
 # pi-atelier needs no companion bump: v0.8.2 clears the >=0.7.1 floor that
 # pi >= 0.84 requires (see PI_ATELIER_REF below).
 ARG PI_VERSION=0.84.3
 ARG PI_TOOLKIT_REF=main
 ARG PI_EXTENSIONS_REF=main
 # Repo URLs default to the canonical gitea origin but are overridable so a
@@ -92,9 +107,9 @@ ARG PI_OBSMEM_REF=master
 # the /opt checkout. Adding an install here would be a no-op that only costs
 # build time.
 ARG PI_ATELIER_REPO=https://github.com/michaelmjhhhh/pi-atelier.git
-ARG PI_ATELIER_REF=v0.8.1
+ARG PI_ATELIER_REF=v0.8.2
 # Human-readable tag PI_ATELIER_REF was resolved from; recorded as a label.
-ARG PI_ATELIER_VERSION=v0.8.1
+ARG PI_ATELIER_VERSION=v0.8.2
 RUN set -e && \
    # git_fetch_ref: clone-equivalent helper that accepts EITHER a branch name
@@ -297,6 +312,19 @@ RUN set -e; \
    mkdir -p /etc/pi-devbox; \
    rev() { git -C "$1" rev-parse HEAD 2>/dev/null || echo "unknown"; }; \
    PI_V="$(pi --version 2>/dev/null | head -n1 | tr -d '\r\n')"; \
    # mempalace CORE (the PyPI package behind the MCP tools) is installed in
    # Dockerfile.base via `uv tool install`, so no /opt clone reveals it and
    # until v1.8.6 the manifest could not answer "which palace shipped here?" —
    # a palace bug could not be correlated to an image, which is precisely the
    # correlation this file exists to provide. Read from the INSTALLED BINARY,
    # not from ARG MEMPALACE_VERSION, per the ground-truth rule above: that is
    # what catches an install which resolved to something other than the pin.
    # `mempalace --version` prints "MemPalace 3.7.1" — NAME-PREFIXED, unlike
    # pi's bare "0.84.2" — hence the $NF pick rather than a straight read. The
    # leading-digit test then rejects usage/error text (a renamed flag prints a
    # usage block) and degrades to JSON null, so this can never fail the build.
    MP_V="$(mempalace --version 2>/dev/null | head -n1 | tr -d '\r' | awk '{print $NF}')"; \
    case "$MP_V" in [0-9]*) MP_CORE="\"${MP_V}\"" ;; *) MP_CORE='null' ;; esac; \
    STUDIO_REV='null'; \
    if [ -d /opt/pi-studio/.git ]; then STUDIO_REV="\"$(rev /opt/pi-studio)\""; fi; \
    { \
@@ -305,6 +333,10 @@ RUN set -e; \
      echo "  \"build_date\": \"${BUILD_DATE}\","; \
      echo "  \"source_revision\": \"${SOURCE_REVISION}\","; \
      echo "  \"pi_version\": \"${PI_V}\","; \
      # Sibling of pi_version, NOT a member of components{}: that map holds git
      # SHAs and `pi-devbox-version` renders it with .value[0:12], which would
      # silently truncate a longer version string.
      echo "  \"mempalace_version\": ${MP_CORE},"; \
      echo "  \"components\": {"; \
      echo "    \"pi-toolkit\": \"$(rev /opt/pi-toolkit)\","; \
      echo "    \"pi-extensions\": \"$(rev /opt/pi-extensions)\","; \
@@ -70,9 +70,27 @@ so `TERM=xterm-kitty` is understood. Override either in your own
 ### Document and image tooling
 - `pandoc` — universal Markdown↔HTML/Org/RST/etc. converter
 - `typst` — markup-based typesetting, wired up as pandoc's `--pdf-engine` (see
  [Generating a PDF with pandoc + typst](#generating-a-pdf-with-pandoc--typst))
 - `graphviz` — `dot` rendering for diagram pipelines
 - `imagemagick` — image conversion / resizing (invoked as `magick`)
 ### Browser automation
 - `agent-browser` — CLI for driving a real headless browser: open pages,
  click/fill/`eval`, snapshot the DOM, take screenshots. Useful whenever a task
  involves a web UI or verifying how a page actually renders (live DOM, WebGL,
  layout, popup positioning) instead of guessing from source.
 - `playwright` + a pre-installed headless **Chromium** back it.
  `AGENT_BROWSER_EXECUTABLE_PATH` is preset to the baked browser via a stable
  `/usr/local/bin/agent-chrome` symlink (insulated from Playwright's
  per-version/arch install directory), so `agent-browser open <url>` works
  out of the box with no setup. Run `agent-browser skills get core --full`
  for the command set and workflow patterns.
 - `socat` — TCP bridge used by `studio-expose` to reach pi-studio's
  loopback-bound server from outside the container (see
  [Using pi-studio](#using-pi-studio--studio-variant))
 ### Language toolchains
 - `python3` + `python3-venv` + `python3-pip` (system Python)
@@ -547,7 +565,8 @@ directory, and they compose:
  `~/.agents/skills/` by `entrypoint-user.sh` on every start. They need no
  external mount, survive volume recreate (the source is an image path, not a
  home dir a named volume would shadow), and are created only when absent so a
-  same-named skillset skill or user override is never clobbered. The bundled
+  user override is never clobbered. Precedence against a mounted `skillset` repo
  is per-skill, not blanket — see *Skillset repo* below. The bundled
  **`pi-devbox-environment`** skill is delivered this way — it teaches agents
  the container's persistence model, host/LAN SSH reachability, split-DNS
  mechanisms, the interactive-vs-tool-shell alias gotcha (`dssh`/`dscp`),
@@ -558,8 +577,11 @@ directory, and they compose:
  pi session to read `~/.agents/skills/pi-extensions/SKILL.md` at start (to fix
  fork/recall under-utilisation). That pointer would dangle in a container
  started *without* the private `skillset` repo, so the image also bakes
-  fallback copies of **`pi-extensions`** and **`mempalace`**. They are
+  fallback copies of **`pi-extensions`** and **`mempalace`**. Whether a mounted
-  symlinked only when absent, so a mounted skillset always overrides them. The
+  skillset overrides them depends on who *owns* the skill (see *Skillset repo*):
  `mempalace` is skillset-owned, so the live clone wins; `pi-extensions` is
  owned by its package repo, so the baked copy keeps winning — the skillset's
  copy of it is a downstream duplicate that can lag. The
  `pi-extensions` skill is *layered*: a committed snapshot in `rootfs/` is the
  floor, and `Dockerfile.variant` copies the canonical, package-owned copy from
  the pinned `pi-extensions` clone (`/opt/pi-extensions/skill/`) over it at
@@ -573,7 +595,16 @@ directory, and they compose:
 - **Skillset repo (optional).** If a `skillset` repo is mounted (at
  `$HOME/skillset` or `/workspace/skillset`, or via `SKILLSET_CONTAINER_PATH`),
  `deploy-skills.sh` symlinks its skills in too. Image-baked skills are
-  classified as foreign-links by its `--prune-stale` pass and left untouched.
+  classified as foreign-links by its `--prune-stale` pass and left untouched —
  which through v1.8.4 meant the baked copy *always* won, so an edit pushed to a
  skillset-owned skill was invisible until the next image build. Since v1.8.5
  `devbox-skill-reconcile` runs right after the deploy and repoints the links for
  skills the skillset owns, listed in
  `/usr/local/share/pi-devbox/skills/skillset-owned.txt` (today: `mempalace`).
  Effective precedence, highest first: **user override** (a real directory, or a
  symlink pointing outside the baked tree) → **live skillset clone** (owned names
  only) → **baked snapshot** (everything else, and every skill when no skillset
  is mounted). Check with `readlink -f ~/.agents/skills/<skill>`.
 To make agents *proactively* load a baked skill at session start (rather than
 only on description match), the image appends a short, gated pointer to the
@@ -774,8 +805,9 @@ 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
-truth** — the actual checked-out commit of each `/opt` clone and the live
+truth** — the actual checked-out commit of each `/opt` clone, the live
-`pi --version` — so a tag is reconstructable after CI logs rotate:
+`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:
 ```bash
 docker run --rm --entrypoint= joakimp/pi-devbox:latest cat /etc/pi-devbox/build-manifest.json
@@ -990,8 +1022,8 @@ resolved to `latest` at build time:
 | Component | Pin | Where |
 |---|---|---|
 | pi | `0.84.2` | `ARG PI_VERSION` — `Dockerfile.variant` |
-| pi-atelier | `v0.8.1` | `ARG PI_ATELIER_REF` — `Dockerfile.variant` |
+| pi-atelier | `v0.8.2` | `ARG PI_ATELIER_REF` — `Dockerfile.variant` |
-| mempalace | `3.6.0` | `ARG MEMPALACE_VERSION` — `Dockerfile.base` |
+| mempalace | `3.7.1` | `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
@@ -18,8 +18,23 @@ for OS packages, the per-package copyright files inside the image at
 | pi-fork | github.com/elpapi42/pi-fork | MIT |
 | pi-observational-memory | github.com/elpapi42/pi-observational-memory | MIT |
 | pi-studio *(`-studio` variant only)* | github.com/omaclaren/pi-studio | MIT |
 | pi-atelier | github.com/michaelmjhhhh/pi-atelier | MIT |
 | pi-toolkit, pi-extensions, mempalace-toolkit | authored by the maintainer (Joakim Persson) | MIT |
 ## MemPalace (AI memory)
 | Component | Upstream | License |
 | --- | --- | --- |
 | mempalace (core, MCP server) | github.com/MemPalace/mempalace (PyPI: `mempalace`) | MIT — the GitHub repo declares MIT; the PyPI package's own metadata omits a license classifier, so if you need clearance from the package artifact alone, verify against the repo's `LICENSE` file rather than the sdist/wheel metadata |
 ## Browser automation
 | Component | Upstream | License |
 | --- | --- | --- |
 | agent-browser | github.com/vercel-labs/agent-browser (npm: `agent-browser`) | Apache-2.0 |
 | Playwright | github.com/microsoft/playwright (npm: `playwright`) | Apache-2.0 |
 | Chromium | chromium.googlesource.com/chromium/src | BSD-3-Clause for Chromium's own code, plus a large set of bundled third-party components each under their own license (see Chromium's own `LICENSE`/`about:credits`). The binary in this image is **not compiled here** — it is the build Playwright downloads for its pinned version ("Chrome for Testing"), installed via `playwright install --with-deps chromium` at `/usr/local/share/ms-playwright/`. Treat Playwright's own distribution terms for that build as authoritative over any summary here. |
 ## Tooling baked into the base image
 | Component | Upstream | License (best effort) |
@@ -58,10 +58,17 @@ fi
 # the runtime skill-link assertion. Pointing at the image path (/usr/local/...)
 # keeps the skill fresh from the image and surviving volume recreate (unlike
 # anything baked under a home dir, which a named volume would shadow). Created
-# only when absent, so a same-named skillset skill (deployed later, at the end
+# only when absent, so a user override is never clobbered.
-# of this script) or a user override is never clobbered; the skillset deploy
+#
-# classifies these as foreign-links and its --prune-stale pass leaves them
+# NB: "created only when absent" does NOT hand a same-named skillset skill
-# alone (only dangling symlinks are pruned).
+# priority — the opposite. The skillset deploy runs at the end of this script
 # and classifies these links as foreign, so through v1.8.4 the BAKED copy
 # always won and an edit pushed to a skillset-owned skill was invisible until
 # the next image build. The links below are therefore the FALLBACK only;
 # devbox-skill-reconcile (invoked right after the skillset deploy) hands the
 # skillset-OWNED skills back to the live clone. Ownership is per-skill, listed
 # in skills/skillset-owned.txt — see VENDORED.md for why pi-extensions must
 # keep losing to the baked copy.
 DEVBOX_SKILLS_SRC=/usr/local/share/pi-devbox/skills
 if [ -d "$DEVBOX_SKILLS_SRC" ]; then
  mkdir -p "$HOME/.agents/skills"
@@ -69,7 +76,16 @@ if [ -d "$DEVBOX_SKILLS_SRC" ]; then
    [ -d "$_sk" ] || continue
    _skname=$(basename "$_sk")
    if [ ! -e "$HOME/.agents/skills/$_skname" ]; then
-      ln -s "${_sk%/}" "$HOME/.agents/skills/$_skname"
+      # -sfn, not -s: `[ ! -e ]` is TRUE for a DANGLING symlink (-e follows the
      # link), and since v1.8.5 these links can point into /workspace/skillset
      # (see devbox-skill-reconcile, invoked after the skillset deploy). If that
      # mount vanishes while the writable layer survives — a `docker restart` or
      # a host reboot under restart: unless-stopped, as opposed to a recreate —
      # plain `ln -s` fails with "File exists" and, under `set -e`, aborts
      # container start before `exec "$@"`. With -f the broken link heals back to
      # the baked fallback, and the reconciler re-points it in the same boot if
      # the clone is back.
      ln -sfn "${_sk%/}" "$HOME/.agents/skills/$_skname"
    fi
  done
 fi
@@ -385,6 +401,13 @@ elif [ -x /workspace/skillset/deploy-skills.sh ]; then
 fi
 if [ -n "$SKILLSET_DEPLOY" ]; then
  "$SKILLSET_DEPLOY" --bootstrap --prune-stale >/dev/null 2>&1 || true
  # The deploy leaves the early baked links (above) in place as foreign links,
  # which silently shadows the live clone for skills the skillset OWNS. Repoint
  # just those; baked stays the fallback, user overrides still win. `|| true`:
  # a skill-link refinement must never break container start.
  if command -v devbox-skill-reconcile >/dev/null 2>&1; then
    devbox-skill-reconcile "$(dirname "$SKILLSET_DEPLOY")" || true
  fi
 fi
 # ── Execute command ──────────────────────────────────────────────────
@@ -0,0 +1,91 @@
 #!/bin/sh
 # devbox-skill-reconcile — hand skillset-OWNED skills back to the live clone.
 #
 # WHY THIS EXISTS
 # ---------------
 # entrypoint-user.sh links the image-baked skills into ~/.agents/skills/ EARLY
 # (before pi-deploy), because the smoke readiness probe gates on markers that
 # only land later, and a link created after that gate produced a flaky
 # assertion. Those links are created with a `[ ! -e ]` guard — "only when
 # absent" — and the skillset deploy runs LAST, treating already-present links
 # as foreign and leaving them alone. Net effect through v1.8.4: the baked copy
 # always won, so an edit pushed to a skillset-owned skill was invisible in
 # every container until the next image build (measured on two hosts: live
 # skillset md5 129bcc4752 vs baked 5236024fef, the new section absent).
 #
 # The fix is NOT "the skillset always wins". Ownership is per-skill (see
 # rootfs/usr/local/share/pi-devbox/skills/VENDORED.md):
 #
 #   pi-devbox-environment  authored in pi-devbox   → baked IS canonical
 #   pi-extensions          owned by the package repo, copied over the snapshot
 #                          at build time; skillset carries a DOWNSTREAM copy
 #                          that can lag → baked must keep winning
 #   mempalace              owned by the skillset repo; baked is a snapshot
 #                          fallback for containers with no skillset mounted
 #                          → the live clone must win when it is present
 #
 # So only skills listed in skills/skillset-owned.txt are handed over. Baked
 # links stay as the fallback (the early-link race fix is untouched), and a user
 # override always beats both: a real directory is never replaced, and neither is
 # a symlink that already points somewhere other than the baked tree.
 #
 # Usage: devbox-skill-reconcile <skillset-root> [skills-dir] [baked-src]
 #   skillset-root  the mounted skillset repo (contains skills/<name>/)
 #   skills-dir     default $HOME/.agents/skills
 #   baked-src      default /usr/local/share/pi-devbox/skills
 #
 # Idempotent, and silent unless it changes something. Exits 0 when there is
 # nothing to do (no skillset, no list) so the entrypoint never fails on it.
 set -eu
 SKILLSET_ROOT="${1:-}"
 SKILLS_DIR="${2:-$HOME/.agents/skills}"
 BAKED_SRC="${3:-/usr/local/share/pi-devbox/skills}"
 BAKED_SRC="${BAKED_SRC%/}"          # a trailing slash would make the prefix
                                   # match below ("$BAKED_SRC"/*) match nothing
 [ -n "$SKILLSET_ROOT" ] || exit 0
 [ -d "$SKILLSET_ROOT/skills" ] || exit 0
 [ -d "$SKILLS_DIR" ] || exit 0
 # Absolutise BOTH roots before they are used, because each has its own way of
 # failing silently when relative: a relative symlink TARGET is resolved against
 # the link's directory (~/.agents/skills), not $PWD, so it would dangle on
 # creation; and a relative BAKED_SRC would never prefix-match the absolute
 # target that `readlink` reports, so every skill would be skipped and the fix
 # would look like it had simply done nothing.
 SKILLSET_ROOT=$(CDPATH= cd -- "$SKILLSET_ROOT" 2>/dev/null && pwd) || exit 0
 BAKED_SRC=$(CDPATH= cd -- "$BAKED_SRC" 2>/dev/null && pwd) || exit 0
 OWNED_LIST="$BAKED_SRC/skillset-owned.txt"
 [ -f "$OWNED_LIST" ] || exit 0
 while IFS= read -r _line || [ -n "$_line" ]; do
    # strip comments and surrounding whitespace; skip blanks
    _name=$(printf '%s\n' "$_line" | sed -e 's/#.*$//' -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
    [ -n "$_name" ] || continue
    # defensive: a list entry must be a plain skill name, never a path
    case "$_name" in */*|.*) continue ;; esac
    _live="$SKILLSET_ROOT/skills/$_name"
    _link="$SKILLS_DIR/$_name"
    # the skillset does not ship it → the baked fallback is all there is
    [ -d "$_live" ] || continue
    # a real directory is a user override → never touch
    [ -L "$_link" ] || continue
    # only ever replace OUR OWN link. readlink is deliberate: `readlink -f`
    # would resolve a link that already points into the skillset clone and,
    # since both trees hold a same-named skill, could not tell them apart.
    _target=$(readlink "$_link" 2>/dev/null || true)
    case "$_target" in
        "$BAKED_SRC"/*|"$BAKED_SRC") ;;   # baked link → ours to replace
        *) continue ;;                     # user/foreign target → leave alone
    esac
    # -n so an existing symlink-to-directory is replaced rather than followed
    # (without it, ln would create $_link/$_name inside the baked tree).
    if ln -sfn "$_live" "$_link" 2>/dev/null; then
        printf 'skill %s: baked snapshot -> live skillset (%s)\n' "$_name" "$_live"
    fi
 done < "$OWNED_LIST"
@@ -55,6 +55,10 @@ release_tag=$(jq -r '.release_tag' "$MANIFEST")
 build_date=$(jq -r '.build_date' "$MANIFEST")
 source_rev=$(jq -r '.source_revision' "$MANIFEST")
 pi_version_baked=$(jq -r '.pi_version' "$MANIFEST")
 # `// empty` matters: images built before v1.8.6 have no such field, and
 # `jq -r` renders a JSON null as the 4-char string "null" — which would
 # print as a bogus version rather than being treated as absent.
 mp_version_baked=$(jq -r '.mempalace_version // empty' "$MANIFEST")
 if [ "$MODE" = "quiet" ]; then
  printf '%s (%s)\n' "$release_tag" "${source_rev:0:7}"
@@ -71,6 +75,16 @@ if command -v pi >/dev/null 2>&1; then
  pi_version_live=$(pi --version 2>/dev/null | head -n1 | tr -d '\r\n')
 fi
 # Same check for the palace, which matters more than it looks: mempalace is
 # the one component that is BOTH client (here) and server (synlig runs this
 # same image), so a skew between the two is a real failure mode rather than
 # cosmetic. `mempalace --version` prints "MemPalace 3.8.0" — name-prefixed,
 # unlike pi's bare "0.84.3" — hence $NF rather than reading the whole line.
 mp_version_live=""
 if command -v mempalace >/dev/null 2>&1; then
  mp_version_live=$(mempalace --version 2>/dev/null | head -n1 | awk '{print $NF}' | tr -d '\r\n')
 fi
 printf 'pi-devbox %s\n' "$release_tag"
 printf '  built:  %s  (source %s)\n' "$build_date" "${source_rev:0:12}"
 if [ -n "$pi_version_live" ] && [ "$pi_version_live" != "$pi_version_baked" ]; then
@@ -79,5 +93,15 @@ else
  printf '  pi:     %s\n' "${pi_version_live:-$pi_version_baked}"
 fi
 # Printed only when known, so this degrades quietly on pre-v1.8.6 images
 # instead of showing an empty or "null" palace line.
 if [ -n "$mp_version_live" ] || [ -n "$mp_version_baked" ]; then
  if [ -n "$mp_version_live" ] && [ -n "$mp_version_baked" ] && [ "$mp_version_live" != "$mp_version_baked" ]; then
    printf '  palace: %s  \033[33m(baked as %s — drift detected)\033[0m\n' "$mp_version_live" "$mp_version_baked"
  else
    printf '  palace: %s\n' "${mp_version_live:-$mp_version_baked}"
  fi
 fi
 printf '  components:\n'
 jq -r '.components | to_entries[] | select(.value != null) | "    \(.key): \(.value[0:12])"' "$MANIFEST"
@@ -197,6 +197,45 @@ EOF
 )
 fi
 # ── Multiplexing default, deliberately LAST ───────────────────────────
 # Why this block exists: ControlPath above is forced, but ControlMaster is not
 # set anywhere for targets that come from the user's own ~/.ssh/config. A target
 # whose entry omits ControlMaster therefore opens a NEW TCP connection per ssh
 # call, and an agent doing a dozen calls in a few minutes can trip fail2ban or a
 # CGNAT flow-table cap on the far end — observed 2026-08-25: ~12 connections in
 # 15 min and port 22 stopped answering while HTTPS to the same estate stayed fine.
 #
 # WHY IT IS AT THE BOTTOM, and ControlPath is at the top. ssh_config is
 # first-value-wins, so position encodes intent:
 #   * BEFORE the Include = an OVERRIDE. Correct for ControlPath, whose value in
 #     the user's config points at read-only ~/.ssh and simply cannot work here.
 #   * AFTER  the Include = a DEFAULT. Correct for ControlMaster, because an
 #     explicit per-host 'ControlMaster no' (or 'auto', or any value) in the
 #     user's own config must keep winning. We are supplying an opinion only
 #     where the user expressed none.
 # That asymmetry is the whole design: force what is broken, default what is
 # merely absent. It also means this needs no audit of anyone's ~/.ssh/config —
 # which matters because that file is per-machine, differs across the fleet, and
 # future machines' versions do not exist yet to be audited.
 #
 # Caveat worth knowing (and documented in the pi-devbox-environment skill): a
 # stale master socket — file present, daemon gone, e.g. after the host suspends
 # or changes network — makes every later ssh to that host hang. Recovery is
 # 'ssh -F ~/.ssh-local/config -O exit <host>'. ControlPersist is deliberately
 # short (10m idle, and each new session resets the idle timer) so an abandoned
 # socket ages out on its own rather than lingering for hours.
 MULTIPLEX_DEFAULT_BLOCK=$(cat <<'EOF'
 # Multiplexing DEFAULT — intentionally after the Include above, so any explicit
 # per-host ControlMaster in your own ~/.ssh/config still wins (first-value-wins).
 # Applies only to targets that never mentioned ControlMaster at all.
 # Stale socket after a suspend/network change? ssh -O exit <host>.
 Host *
    ControlMaster auto
    ControlPersist 10m
 EOF
 )
 cat > "$CONFIG" <<EOF
 # AUTO-GENERATED by setup-lan-access.sh on every container start. Do not edit
 # by hand — edits are overwritten. Used via: ssh -F ~/.ssh-local/config <host>
@@ -216,6 +255,7 @@ ${JUMP_BLOCK}
 ${LAN_CONF_BLOCK}
 ${AUTOJUMP_BLOCK}
 ${INCLUDE_BLOCK}
 ${MULTIPLEX_DEFAULT_BLOCK}
 EOF
 chmod 600 "$CONFIG" 2>/dev/null || true
@@ -41,3 +41,32 @@ especially load-bearing here — a pi-devbox container is frequently recreated,
 the palace is your only memory across recreates. Without the habit it is just
 storage, not memory. (The skill is the consumer side; feeding the palace is the
 separate `opencode-mempalace-bridge` skill, if present.)
 ### If the palace is central, it is shared — three rules
 If `MEMPALACE_REMOTE_URL` is set, the MCP tools write to a **central palace
 shared with other machines**, not to a local one. Your drawers are not the only
 ones in there, and most drawers' `source_file` paths do not exist on this host.
 The skill covers the orientation side (provenance, chronology, whose diary is
 whose); these three are here instead because getting them wrong does *damage*
 rather than merely confusing you:
 - **Never run `mempalace sync` / `mempalace_sync` against a shared palace.** It
  prunes drawers whose source files look gitignored, deleted, or moved — and on
  a shared palace that describes most of the content, including every other
  machine's. Compounding it (RFC-001 §7.2): feeders now stage *inside* the
  palace root, so a scoped sync can delete the very drawers it just filed.
  `mempalace_delete_by_source` is exact-match rather than existence-based, but
  its blast radius is now the whole fleet's palace — leave it on its default
  `dry_run=true` and confirm the match count before committing.
 - **A timeout is not a failure.** The palace is single-writer, and one large
  mine can block every client for minutes, so a write or mine that exceeds the
  client's deadline has usually *completed* server-side. Verify with
  `mempalace_get_drawer` or `mempalace_search` before retrying — a blind retry
  files a duplicate. `[mempalace ext] feed (tick) failed: mine timed out after
  30000ms` is the common benign instance: the transcript is already in the
  server's inbox and the mine is idempotent, so nothing is lost either way.
 - **The `mempalace` CLI is not remote-aware.** It always opens a palace on
  local disk, so `mempalace search` can return older and different results than
  the MCP tools while both look correct. Use the MCP tools for the central
  palace; the CLI only for a local one.
@@ -1,9 +1,10 @@
 # Vendored fallback skills
 Most directories here are **image-baked skills** that `entrypoint-user.sh`
-symlinks into `~/.agents/skills/` on container start (only when a skill of the
+symlinks into `~/.agents/skills/` on container start. They are the **fallback**
-same name is not already present, so a mounted `skillset` repo or a user
+layer: see *Runtime precedence* below for which copy actually wins when a
-override always wins).
+`skillset` repo is mounted (through v1.8.4 the answer was "always the baked
 one", which was a bug).
 | skill | owner | how it gets here |
 |-------|-------|------------------|
@@ -38,6 +39,35 @@ its skill file needed baking.
  *different* skill, `opencode-mempalace-bridge`), so there is no public
  package source to copy from. This snapshot is refreshed manually per release.
 ## Runtime precedence (v1.8.5+)
 The baked links are created **early** in `entrypoint-user.sh` (before pi-deploy,
 to close a smoke readiness race) with a create-only-when-absent guard, and the
 skillset deploy runs **last** and treats them as foreign links. Through v1.8.4
 that combination meant the baked snapshot always won: an edit pushed to
 `skillset/skills/mempalace/SKILL.md` was invisible in every container until the
 next image build (measured on two hosts — live `md5 129bcc4752` vs baked
 `5236024fef`, new section absent). Editing those skills *appeared* to work.
 `devbox-skill-reconcile` now runs immediately after the skillset deploy and
 repoints the links for skills the **skillset owns**, listed one per line in
 `skillset-owned.txt`. Precedence, highest first:
 1. **user override** — a real directory, or a symlink pointing outside the baked
   tree; never touched by anything
 2. **live skillset clone** — but only for names in `skillset-owned.txt`
 3. **baked snapshot** — everything else, and every skill when no skillset is
   mounted
 Ownership is per-skill on purpose: `pi-extensions`' authoritative source is the
 package repo (copied over the snapshot at build), and `skillset` carries a
 downstream copy that can lag, so handing it to the clone would *regress* the
 skill. Only `mempalace` is skillset-owned today.
 Verify with `readlink -f ~/.agents/skills/<skill>` — not by reading the
 entrypoint. Smoke covers both directions (baked resolution with no skillset
 mounted, plus a fabricated-skillset run of the reconciler).
 ## Refreshing the snapshots
    cp <pi-extensions-pkg>/skill/SKILL.md                    pi-extensions/SKILL.md
@@ -50,4 +80,9 @@ also carries a copy, but it is a downstream duplicate and can lag), and
 `mempalace` from `skillset`. Copying `pi-extensions` from `skillset` would
 regress the snapshot to whatever that repo last mirrored.
-Snapshot provenance at last refresh: skillset `63f3bf5`, pi-extensions pkg `e73cb9f`.
+Snapshot provenance at last refresh: skillset `670f7f1`, pi-extensions pkg `e73cb9f`.
 When you refresh the `mempalace` snapshot, also update the phrase asserted by
 the "mempalace skill snapshot is current" smoke test — it deliberately pins the
 **newest** section, because the previous canary grepped a phrase that survived
 the very edit that made the snapshot stale, and so passed on stale content.
@@ -79,6 +79,79 @@ mempalace_search(query="<keywords>", wing="<project>")
 **Never guess about facts that might be in the palace.** Wrong is worse than slow. Say "let me check" and query.
 #### Search Before You *Probe*
 The rule above covers **questions**. This one covers **actions** — and it is the one
 that actually gets skipped, because mid-task the impulse is to go and *look* rather
 than to remember. The palace is a **fleet** record: another machine's agent has
 usually already paid the cost of discovering how this environment is wired, and its
 notes include the corrections that came afterwards, which a fresh probe cannot show
 you.
 **Before you SSH somewhere to find out how it is set up, enumerate infrastructure,
 or derive a deployment — search.** Concrete triggers, all meaning *search first*:
 - about to run `ssh <host> …`, `docker ps`, `systemctl list-units`, `ip addr` to
  discover how something is deployed or connected
 - about to establish topology: which hosts/runners/services exist, where they live,
  which of them can reach which
 - about to conclude "this isn't documented anywhere" or "there's no way to know"
 - about to assert an environment fact you learned **earlier in this same session**
 **That last trigger is the sharp edge.** A compacted session summary is lossy by
 design, and a belief you formed 40 turns ago may already be *retracted* in the
 palace by another machine. Trusting your own context over the shared record is how a
 withdrawn claim gets re-published as fact.
 Search broadly before narrowing — fleet knowledge often sits in another machine's
 wing, or inside a mined conversation, not where you would file it yourself:
 ```
 mempalace_search(query="<topic> <host> <mechanism>")     # no wing filter first
 mempalace_search(query="…", wing="<likely-wing>")        # then narrow
 ```
 Two or three searches cost seconds. Re-deriving infrastructure costs minutes **and
 can be wrong**: a probe shows one host's present state, while the palace records
 intent, history, and what was already disproved.
 > **Worked example (real, 2026-08-25).** An agent evaluating whether to add an ARM
 > CI runner probed hosts directly instead of searching. It concluded "the runner
 > lives on synlig" — there are **four** — and that "synlig is on the home LAN" —
 > it is an OpenStack VM with a public floating IP that cannot reach the home LAN at
 > all. Both facts were already in the palace, the second one as an **explicit
 > retraction of the very same mistake** made weeks earlier. The palace also held
 > the runner labels and the deliberate `capacity: 1` setting, which the probe never
 > revealed. Cost: a wrong recommendation written into the palace twice, then
 > corrected twice.
 **A search that comes back empty is not an answer — least of all about recent work.**
 Semantic search is weakest exactly where the fleet record is freshest: a drawer filed
 minutes ago is unranked against a keyword-shaped query, and the drawer you most need
 is *by construction* the newest one, because the other machine files its release,
 handoff and correction drawers at the **end** of its session. So a single miss proves
 nothing. **If the work is 0-2 days old and the first search looks stale or empty,
 enumerate before concluding:**
 ```
 mempalace_list_drawers(wing="<wing>", since="<today>")   # or room=, or no filter
 mempalace_diary_read(agent_name="<you>", wing="<wing>")  # the other machine's handoff
 ```
 Enumeration is exact where embeddings are probabilistic. Treat "I searched and found
 nothing" as a hypothesis you have not yet tested, and never as licence to go probing.
 > **Worked example (real, 2026-08-25, same fleet as above).** An agent asked to
 > orient on an in-flight release *did* search first — `"v1.8.6 release run 579
 > Docker Hub verification"` — and got back only v1.6.4 / v0.78.0 era hits, because
 > the release drawer it needed was **58 seconds old**. It accepted the miss and went
 > off to probe Docker Hub and the Gitea API. The user had to prompt "maybe there is a
 > note in mempalace"; `list_drawers(wing="pi-devbox", since=<today>)` then returned
 > the drawer immediately, along with the diary entry naming the exact open item. The
 > rule above was present and correct in this very file at the time — the failure was
 > not knowing to *retry differently* after a bad first hit.
 #### Mine New Projects
 When working on a new codebase for the first time:
@@ -275,18 +348,31 @@ Wings are top-level categories, typically one per project or domain:
 - Named after the project directory (e.g., `cli_utils`, `opencode_devbox`)
 - Agent diaries live in `wing_<agent_name>` (e.g., `wing_orchestrator`, `wing_pi`)
-#### Multi-harness palace
+#### Shared palace: multiple harnesses, and possibly multiple machines
-A single palace can be fed by multiple coding-agent harnesses. On this machine the palace is shared between **opencode** and **pi** (Mario Zechner's pi-coding-agent). Implications:
+A single palace can be fed by multiple coding-agent harnesses, and — when
 `MEMPALACE_REMOTE_URL` points at a central palace — by multiple *machines*. On
 this machine the palace is shared between **opencode** and **pi** (Mario
 Zechner's pi-coding-agent). Implications:
 - **`wing_conversations` mixes sources.** Both harnesses' session feeders write into the same wing. To tell them apart, look at the `source_file` metadata on each drawer:
  - `pi_<uuid>.jsonl` → pi session
  - `<slug>_ses_<id>.jsonl` → opencode session
  - The first chunk of each session also carries a `| source: opencode` or `| source: pi` marker in the synthetic header line.
 - **Other wings may belong to other harnesses.** For example `wing_pi` is pi's diary, not opencode's. Don't assume every diary entry was written by you — check `agent_name` on the entry.
- **Session feeders run on different schedules.** Pi sessions are fed Tue 03:00, opencode sessions Mon 03:00. Recent sessions from either harness can lag the palace by up to a week, so absence-of-evidence in `wing_conversations` is not evidence-of-absence for recent work.
+- **Session feeders run on different schedules.** Pi sessions are fed Tue 03:00, opencode sessions Mon 03:00 (launchd `Weekday`: `0`/`7`=Sunday, `1`=Monday, `2`=Tuesday — misreading this by one day is easy). Recent sessions from either harness can lag the palace by up to a week, so absence-of-evidence in `wing_conversations` is not evidence-of-absence for recent work.
 - **Reading another harness's diary is useful.** When orienting after a gap, `mempalace_diary_read agent_name=pi` (or whichever sibling agent has been active) often gives a fresher picture than waiting for the conversations feeder to catch up.
 When the palace is **central** (shared across machines), these further things apply:
 - **Check which machine a conversation came from.** Transcripts are fed per device, so `source_path` reads `…/mempalace-feed/<device>/pi_<uuid>.jsonl` while the displayed `source_file` is only the basename. One search can legitimately return hits from several machines at once — look at the device segment before attributing a decision to *this* project.
 - **Provenance is stamped for you — leave it alone.** Drawers carry `device` and `agent_kind` metadata (plus `device_source`/`agent_kind_source` recording *how* each was determined, so an inference is never mistaken for a fact). You do **not** set these, and you no longer set `added_by` either: the pi bridge defaults the writer field to `<harness>@<device>` on `add_drawer`/`checkpoint`/`mine`/`event_append`/`artifact_put`, and prefixes diary entries with `HOST:<device>|`, from host-supplied `$MEMPALACE_PI_DEVICE`. RFC 001 §7.3.2 ranks "agent stamps it via a skill instruction" as the *worst possible* place for exactly the reason you would expect — it is per-call boilerplate that gets forgotten, and it did: the agent who wrote the previous version of this bullet then filed its own provenance drawer as `added_by=checkpoint`. Two things remain yours: pass `source_drawer_id` on `kg_add` (triples have no provenance field, so that pointer is the only path back to a device), and pass an explicit `added_by` **only** when deliberately filing on behalf of another device. Never invent values for `device`/`agent_kind`/`origin_device` — a fabricated value is worse than a blank, because it silently corrupts a future merge.
 - **Metadata is invisible to search — so check the text, not the fields.** `search` results are built from a fixed key list and `diary_read` returns content, so neither ever shows `device`/`added_by`. Only `mempalace_get_drawer` reveals them. This is why diary entries carry an in-text `HOST:<device>` marker: it is the only attribution a reader actually sees. **A diary entry with no `HOST:` marker predates the convention and may be from any machine — do not assume it is this one's history.**
 - **Mined drawers carry the MINE date, not the session date.** When history is imported, or re-mined on the palace host, `filed_at`/`created_at` is the *import* time — so sorting by them does not give chronological order. Real session time is recoverable from the UUIDv7 in `pi_<uuid>.jsonl`: the first 12 hex digits are milliseconds since the epoch (and UUIDv7 sorts lexicographically in time order, so a plain filename sort is already chronological). Agent-authored drawers and diaries have no such backdoor — for those `filed_at` is the only chronology, which is why it must never be restamped.
 - **Beware the timezone mismatch when you combine those.** Palace `filed_at`/`created_at` are naive timestamps in the palace host's local time, while a UUIDv7 decodes to UTC. Comparing them directly introduces a silent offset (2 h for a CEST host). Normalise before drawing conclusions about ordering.
 - **`agent_name` is not device-scoped.** `mempalace_diary_read(agent_name="pi")` returns *every* machine's `pi` diary, interleaved. Read the entry before assuming it is your own history — and note that a container cannot tell you which machine it is on (`hostname` is a docker hash, `$DEVBOX_HOST_ALIAS` is generic). `$MEMPALACE_PI_DEVICE` is the cheap answer; `ssh -F ~/.ssh-local/config host hostname` is the independent one.
 - **One writer, no queue.** A concurrent mine returns a structured `already-running` error rather than waiting its turn, and one large mine can make the palace unresponsive to every client for minutes. After another client's mine, call `mempalace_reconnect` to see the new drawers. A client-side timeout is not evidence of failure — verify before retrying, or you file a duplicate.
 ### Rooms
 Rooms are aspects within a wing:
@@ -318,9 +404,13 @@ Entity-relationship triples with temporal validity. Query with `mempalace_kg_que
 ## Anti-Patterns
 - **Don't guess when you can search.** If a question touches past work, search first.
 - **Don't probe what the fleet already knows.** Before SSH-ing into a host, enumerating infrastructure, or deriving how something is deployed, search the palace. A probe reveals one host's present state; the palace holds intent, history and prior corrections — including the ones that contradict what you are about to conclude.
 - **Don't trust this session's context over the palace.** A compacted summary is lossy, and another machine may have corrected the fact since. Verify load-bearing environment claims against the shared record before acting on them.
 - **Don't take one empty search as proof the palace is silent.** Fresh drawers rank worst, and the drawer that matters is usually the newest one. For anything 0-2 days old, enumerate with `mempalace_list_drawers(since=…)` and read the other machine's diary before you go and probe.
 - **Don't infer elapsed time from session or container boundaries.** A restart isn't a new day. Compare the actual timestamp (`timestamp` / `created_at`) against the current date/time before saying "yesterday", "last week", etc.
 - **Don't skip the diary.** A session without a diary entry is a session forgotten.
 - **Don't summarize drawer content.** File verbatim — the embedding model needs the original words.
 - **Don't mine .git directories or node_modules.** The CLI miner respects .gitignore by default.
 - **Don't create duplicate drawers.** Use `mempalace_check_duplicate` before adding manually.
 - **Don't treat the palace as a task list.** It's for knowledge and context, not todos.
 - **Don't invent provenance metadata, and don't hand-stamp it either.** An earlier version of this list told you to set `added_by="<harness>@<device>"` by hand; that instruction has been withdrawn, because RFC 001 §7.3.2 places provenance at the client/server boundary and the pi bridge now does it uniformly (see *Provenance is stamped for you* above). DO NOT invent values for the palace's own metadata fields (`device`, `agent_kind`, `origin_device`): those are stamped by infrastructure that also records *how* each was determined, and a fabricated value is worse than none because it silently corrupts a future merge. DO pass `source_drawer_id` on `kg_add`. And never put a machine name in a diary's `agent_name` — it becomes the wing name and hides your entries from `diary_read`.
@@ -130,6 +130,36 @@ are "command not found" there — you must spell out the underlying command.
 If a command "works in my terminal but not when the agent runs it," this alias
 gap is the first thing to suspect.
 ### A negative result is usually your own filter
 **When you are about to report that something is absent, unreachable, or not
 running, the filter you wrote is the prime suspect — not the thing.** This
 environment produces false negatives cheaply, and they are convincing because
 the command "succeeded". Three real instances from one session, all wrong, all
 mine:
 | Claim I made | Why it was false |
 |---|---|
 | "`tor-ms22` is not in the SSH config" | `grep … \| head -20` — the entry was at **line 454**. `~/.ssh/config` here is ~500 lines. |
 | "the Docker host has no `docker`" | non-interactive SSH `PATH` lacks `/usr/local/bin` (§2, §3). It was at `/usr/local/bin/docker`. |
 | "no ControlMaster is running" | pattern `ssh ` (trailing space) cannot match a master: those processes **rename themselves** to `ssh: <controlpath> [mux]`. |
 Habits that would have caught all three:
 ```sh
 # don't cap the output of a search whose answer you don't already know
 grep -n -i -A6 'tor-ms22' ~/.ssh/config          # not | head -20
 # on the host, resolve the binary instead of trusting PATH
 ssh -F "$HOME/.ssh-local/config" mac 'command -v docker || ls /usr/local/bin/docker'
 # match a process's ACTUAL argv, not the name you imagine
 ps -eo pid,etime,args | grep -Ei 'mux|mosh|ssh'
 ```
 A positive result needs no such scepticism — it carries its own evidence. Only
 absence has to be *earned*, so spend the extra command there.
 **`dscp`/`scp` with accented filenames on a macOS host.** macOS stores filenames
 in Unicode **NFD** (decomposed — e.g. `ä` is `a` + combining U+0308), while the
 string you type or paste is usually **NFC** (precomposed `ä`, U+00E4). The bytes
@@ -155,6 +185,16 @@ entrypoint's `setup-lan-access.sh` writes a **writable SSH sidecar** at
 - A `Host *` block redirecting `ControlPath` into the writable `~/.ssh-local/cm`
  (because `~/.ssh` is typically bind-mounted **read-only**, so a master socket
  can't be created under it), plus `Include ~/.ssh/config`.
 - A **trailing** `Host *` block supplying `ControlMaster auto` + `ControlPersist
  10m` as a *default*. Position is the design: `ControlPath` sits **before** the
  `Include` (an override — the value in your own config points at read-only
  `~/.ssh` and cannot work here), while `ControlMaster` sits **after** it (a
  default — an explicit per-host `ControlMaster no`/`auto` in your own config
  still wins, because ssh_config is first-value-wins). **Force what is broken,
  default what is merely absent.** Without this, a target whose entry never
  mentioned `ControlMaster` opens a fresh TCP connection per `ssh` call, and an
  agent making a dozen calls in a few minutes can trip fail2ban or a CGNAT
  flow-table cap on the far end.
 - Aliases **`host` / `mac`** → `host.docker.internal` (user comes from
  `HOST_SSH_USER`) — i.e. SSH back into the Docker host.
 - On VM-backed hosts only: an **SSH-jump-via-host** block so the container can
@@ -169,12 +209,48 @@ ssh -F "$HOME/.ssh-local/config" mac 'hostname; whoami'      # reach the host
 ssh -F "$HOME/.ssh-local/config" <lan-peer> '…'             # reach a LAN peer (if configured)
 ```
 **Always go through the sidecar, never `-F ~/.ssh/config`.** This is the single
 easiest way to break SSH from inside the container, and the failure actively
 misleads: the read-only path makes the master socket uncreatable, so
 multiplexing appears *impossible* rather than misconfigured. What follows is a
 burst of fresh connections and, on a rate-limiting peer, a block that looks like
 an outage. The tell that it is rate-limiting and not an outage: HTTPS to the same
 estate keeps working while port 22 stops answering. (Recorded 2026-08-25 — an
 agent hit exactly this, concluded "ControlMaster is impossible here", disabled
 multiplexing, and filed that as a lesson. The sidecar had solved it since v1.4.)
 If every `ssh` to one host suddenly hangs, suspect a **stale master** — socket
 file present, daemon gone, typically after the host suspended or changed
 network. Check and clear it:
 ```sh
 ssh -F "$HOME/.ssh-local/config" -O check <host>   # "Master running (pid=…)" or no master
 ssh -F "$HOME/.ssh-local/config" -O exit  <host>   # tear down a stale one
 ```
 Two related mechanisms (don't reinvent them):
 - **ControlMaster multiplexing** is preconfigured (`/tmp/sshcm/`) to survive
  CGNAT per-destination flow caps on residential ISPs. If `~/.ssh/config` pins
  a `ControlPath` under the read-only `~/.ssh`, override with
  `-o ControlPath=none` (or use the sidecar, which already redirects it).
 - **A live master socket MASKS auth and config changes on the far end.** Once
  `~/.ssh-local/cm/<user>@<host>:22` exists, later commands ride it and
  authenticate **not at all** — so after editing remote `authorized_keys`,
  `sshd_config`, host keys, or firewall rules, "it still works" proves nothing.
  A corrupted `authorized_keys` then bites on the next *cold* connect, likely in
  a future session with no memory of the edit. Prove it immediately instead:
  ```sh
  ssh -F "$HOME/.ssh-local/config" -O check <host>        # 'Master running (pid=N)'
  ssh -F "$HOME/.ssh-local/config" -o ControlPath=none -o ControlMaster=no \
      -o BatchMode=yes <host> 'echo COLD AUTH OK'
  ```
  To attribute a socket rather than guess whose it is: `ps -p <pid> -o
  pid,ppid,lstart,etime,args`. A `mosh` the *user* started on the host
  bootstraps with the **host's** `~/.ssh/cm/` and is invisible from in here;
  only a mosh started *inside* the container shares `~/.ssh-local/cm/`.
 - **`pi --ssh <host>`** rewires pi's own read/write/edit/bash tools to run on a
  remote host; it has its own writable-socket fallback. See the `pi-extensions`
  skill for that path.
@@ -257,6 +333,10 @@ hardcode. Details are in the `mempalace` skill.
 - [ ] Writing durable output? → `/workspace`, not the ephemeral layer.
 - [ ] Using `dssh`/`dscp`/`ll` in the bash tool? → spell out the real command.
 - [ ] Assuming a hostname / domain / nameserver / host OS? → stop, detect it.
 - [ ] About to report something **absent / unreachable / not running**? → re-run
      without your own `head`/pattern/`PATH` assumptions first (§2).
 - [ ] Changed remote `authorized_keys` / `sshd_config`? → prove it with a **cold**
      connect; a live master socket hides breakage (§3).
 - [ ] "Resolves but won't connect"? → check route *and* DNS (§3 + §4).
 - [ ] `apt`/toolchain install? → tell the user it's ephemeral unless imaged.
 - [ ] Editing a skill? → `readlink -f ~/.agents/skills/<name>` first (§1).
@@ -0,0 +1,16 @@
 # Skills in this directory whose OWNER is the skillset repo.
 #
 # Read by devbox-skill-reconcile, which runs after the skillset deploy in
 # entrypoint-user.sh: for each name below, if the mounted skillset ships a
 # skill of that name, the baked link in ~/.agents/skills/ is repointed at the
 # live clone. The baked copy remains the fallback for containers started
 # WITHOUT a skillset mount, and a user override always wins over both.
 #
 # Add a name here ONLY if the skillset repo is the authoritative source (see
 # the ownership table in VENDORED.md). Do NOT add:
 #   pi-devbox-environment — authored in this repo; baked IS canonical
 #   pi-extensions         — owned by the pi-extensions package repo and copied
 #                           over the snapshot at build time; the skillset copy
 #                           is a downstream duplicate that can lag, so letting
 #                           it win would regress the skill.
 mempalace
@@ -5,6 +5,7 @@
 #
 # Verifies:
 #   - pi binary present and (if EXPECTED_PI_VERSION set) matches CI's resolved version
 #   - mempalace core matches the audited pin (if EXPECTED_MEMPALACE_VERSION set)
 #   - new v1.0.0 base additions (pandoc, graphviz, imagemagick, yq, tealdeer)
 #   - typst PDF engine for pandoc (Unreleased) — `pandoc --pdf-engine=typst`
 #   - non-modal editors nano + micro (alongside nvim)
@@ -43,12 +44,23 @@ PASS=0; FAIL=0
 # catching an unexpected +GB regression.
 SIZE_THRESHOLD_MB=3800
 # On failure, surface the last few lines the command produced. This used to
 # discard output entirely (`>/dev/null 2>&1`), which made a red ❌ carry zero
 # diagnostic weight: explaining the single v1.8.0 stage-default failure took a
 # full CI-log dig plus a registry-config inspection, when the container had
 # already printed the answer and thrown it away. Assertions that want a
 # diagnostic just echo it to stderr — it stays hidden while they pass.
 run() {
  local label="$1"; local cmd="$2"
-  if docker run --rm --entrypoint="" "$IMAGE" sh -c "$cmd" >/dev/null 2>&1; then
+  local out
  if out=$(docker run --rm --entrypoint="" "$IMAGE" sh -c "$cmd" 2>&1); then
    printf "  ✅  %s\n" "$label"; PASS=$((PASS+1))
  else
    printf "  ❌  %s\n" "$label"; FAIL=$((FAIL+1))
    # `if`, not `&&` — a trailing false under `set -e` would abort the script.
    if [ -n "$out" ]; then
      printf "        └─ %s\n" "$(printf '%s' "$out" | tail -3 | tr '\n' ' ' | cut -c1-300)"
    fi
  fi
 }
@@ -102,8 +114,37 @@ run "mempalace-pi-session on PATH" "mempalace-pi-session --help"
 # default-staged run at a populated dir would export whatever transcripts it
 # finds into the real stage, which is how a synthetic test session ends up
 # staged for mining as if it were a real conversation.
 #
 # Asserted $HOME-RELATIVE, not against a literal /home/developer. `run` invokes
 # `docker run --entrypoint=""`, and neither Dockerfile sets USER or ENV HOME
 # (HOME is set by entrypoint-user.sh, which --entrypoint="" deliberately skips),
 # so these assertions execute as root with HOME=/root. The original literal
 # /home/developer form could therefore never match and failed the v1.8.0
 # release — a test bug, not a product one: the stage resolution was correct all
 # along, it just follows $HOME. The invariant under test ("the stage sits beside
 # the palace, sharing its lifetime") is user-independent, so pinning the user
 # was never part of it. A cache-dir default still fails the pattern below, which
 # is the regression this guards.
 #
 # It went unnoticed for three days because this workflow only triggers on
 # `push: tags: v*` — the assertion was added on a main push, so v1.8.0 was its
 # first execution ever. Use the `smoke_only` workflow_dispatch input to run
 # smoke against HEAD without cutting a tag.
 run "pi stage defaults next to the palace (not a cache dir)" '
  out=$(mempalace-pi-session --dry-run --reason smoke --sessions-dir "$(mktemp -d)" 2>&1) || true
  stage=$(echo "$out" | grep -oE "stage=[^ ]+" | head -1)
  echo "resolved ${stage:-<no stage= line>} with HOME=$HOME" >&2
  case "$stage" in
    "stage=$HOME/.mempalace/pi-stage/"*) exit 0 ;;
    *) exit 1 ;;
  esac
 '
 # Companion to the above: the deployment-specific case the literal assertion was
 # reaching for, done properly by supplying the HOME the container actually runs
 # with instead of assuming it.
 run "pi stage is palace-adjacent for the developer user" '
  out=$(HOME=/home/developer mempalace-pi-session --dry-run --reason smoke --sessions-dir "$(mktemp -d)" 2>&1) || true
  echo "$out" | grep -oE "stage=[^ ]+" | head -1 >&2
  echo "$out" | grep -q "stage=/home/developer/.mempalace/pi-stage/"
 '
 run "pi stage follows MEMPALACE_PALACE_PATH" '
@@ -111,6 +152,33 @@ run "pi stage follows MEMPALACE_PALACE_PATH" '
        mempalace-pi-session --dry-run --reason smoke --sessions-dir "$(mktemp -d)" 2>&1) || true
  echo "$out" | grep -q "stage=/tmp/alt/.mempalace/pi-stage/"
 '
 # The feeder's --agent default is WHO a drawer is attributed to. mempalace core
 # records neither the machine nor the harness on a write, and one shared bearer
 # token means the server cannot tell clients apart, so toolkit c64ffa1 changed
 # this default from $USER to pi@$MEMPALACE_PI_DEVICE — the one string that makes
 # a write attributable to both. Nothing ever PRINTED the resolved value (the
 # banner shows mode= and stage= only), so an image built from a pre-c64ffa1
 # toolkit ref would ship unattributed writes with every check still green.
 #
 # `--help` assigns AGENT (script top) before it parses args, then exits 0 with
 # no side effects — so `bash -x` observes the REAL resolution, env interpolation
 # and fallback included, rather than grepping the source for a literal line that
 # any reformat would break. Two-sided on purpose: device set => pi@<device>;
 # device UNSET => must not be pi@anything. The second half is what fails against
 # the old unconditional $USER default, which ignored the device entirely.
 #
 # Probes the PATH entry (a symlink into the /opt clone) rather than that clone
 # path directly: this is the invocation the systemd/launchd timers and
 # entrypoint-user.sh actually use, so it is the default that reaches the palace.
 run "feeder resolves --agent to pi@<device> (drawer attribution)" '
  f=$(command -v mempalace-pi-session) || { echo "feeder not on PATH" >&2; exit 1; }
  with=$(MEMPALACE_PI_DEVICE=smoke-device bash -x $f --help 2>&1 | sed -n "s/^+* *AGENT=//p" | tail -n1)
  without=$(env -u MEMPALACE_PI_DEVICE bash -x $f --help 2>&1 | sed -n "s/^+* *AGENT=//p" | tail -n1)
  echo "resolved with-device=[$with] without-device=[$without]" >&2
  [ "$with" = "pi@smoke-device" ] || exit 1
  case "$without" in pi@*) exit 1 ;; esac
  echo ok
 '
 # Regression guard for the pi transcript exporter. If pi ever changes its
 # session JSONL shape, the exporter stops recognising sessions and the palace
 # silently gets nothing (or, worse, raw JSON chunked as prose). Feed it a
@@ -155,6 +223,16 @@ 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'"
 # 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
 # never see it: on 2026-08-15 a mine that died with "source directory not found:
 # '/data/feed/...'" logged "Done. Wing updated." and exited 0, and this
 # container's transcripts were filed nowhere for a whole session. The feeder
 # carries fixtures for that exact body; run them against the baked toolkit so a
 # stale/reverted toolkit ref can't reintroduce a silent feed.
 run "baked feeder detects a failed remote mine (no silent false success)" \
    "mempalace-pi-session --self-test"
 # v1.0.0 base additions — verify presence and basic functionality.
 run "pandoc"          "pandoc --version"
 run "typst"           "typst --version"
@@ -185,6 +263,16 @@ run "image-baked mempalace fallback skill" \
 # baked copy must be the fresh package copy (Option 1), not the stale snapshot.
 run "pi-extensions skill refreshed from package when present" \
    "if [ -f /opt/pi-extensions/skill/SKILL.md ]; then cmp -s /opt/pi-extensions/skill/SKILL.md /usr/local/share/pi-devbox/skills/pi-extensions/SKILL.md; else true; fi"
 # Runtime ownership handover (v1.8.5): the baked links are a FALLBACK, and
 # skillset-OWNED skills must be repointed at the live clone when one is mounted.
 # The list is data, so assert its content, not just its presence: mempalace in,
 # pi-extensions deliberately out (its skillset copy is a lagging duplicate).
 run "devbox-skill-reconcile helper present + executable" \
    "test -x /usr/local/bin/devbox-skill-reconcile"
 run "skillset-owned list ships and names mempalace" \
    "grep -qx 'mempalace' /usr/local/share/pi-devbox/skills/skillset-owned.txt"
 run "skillset-owned list excludes pi-extensions (ownership)" \
    "! grep -qx 'pi-extensions' /usr/local/share/pi-devbox/skills/skillset-owned.txt"
 # ── tmux 0-indexing (required for pi-studio variants) ─────────────────
 echo ""
@@ -203,6 +291,26 @@ run "pi-fork clone + node_modules" \
    "test -f /opt/pi-fork/package.json && test -d /opt/pi-fork/node_modules"
 run "pi-observational-memory clone + node_modules" \
    "test -f /opt/pi-observational-memory/package.json && test -d /opt/pi-observational-memory/node_modules"
 # ...and that the clone carries the AUTH FIX, not merely that it exists. om's
 # pre-flight hasUsableAuth() check silently disabled `recall` for ~8 weeks once
 # pi moved to request-time SigV4 signing and stopped exposing a static Bedrock
 # key; upstream fixed it in ce9fc98, adopted in v1.8.4. PI_OBSMEM_REF tracks
 # master, so an upstream revert or force-push would ship a dead `recall` with
 # the clone assertion above still green — the exact gap flagged as open in the
 # v1.8.5 changelog.
 #
 # Pin the markers to src/runtime.ts, the fix SITE, rather than grepping the
 # repo: two of these three strings also appear under tests/, so a repo-wide
 # grep stays green with runtime.ts itself reverted. That is a false green of the
 # same family as the old skill-snapshot canary.
 run "pi-observational-memory carries the ce9fc98 auth fix (recall stays alive)" '
  f=/opt/pi-observational-memory/src/runtime.ts
  test -f "$f" || { echo "fix site missing: $f" >&2; exit 1; }
  for m in availability_recheck providerCredentialConfigured hasConfiguredAuth; do
    grep -q "$m" "$f" || { echo "marker absent from runtime.ts: $m" >&2; exit 1; }
  done
  echo ok
 '
 # pi-atelier: deliberately NO node_modules assertion, unlike its siblings —
 # it declares zero runtime dependencies (only peerDeps, satisfied by the baked
 # pi) and has no build step, so Dockerfile.variant skips `npm install` for it.
@@ -241,24 +349,118 @@ echo ""
 echo "── Build provenance ──"
 run "/etc/pi-devbox/build-manifest.json present" \
    "test -f /etc/pi-devbox/build-manifest.json"
-run_expect "manifest records pi-extensions component" \
+# These next checks replace three that grepped the manifest for the FIELD NAME
-    "cat /etc/pi-devbox/build-manifest.json" '"pi-extensions"'
+# and never looked at the value:
-run_expect "manifest records pi-atelier" \
+#
-    "cat /etc/pi-devbox/build-manifest.json" '"pi-atelier"'
+#     run_expect "manifest records pi_version" "cat …manifest.json" '"pi_version"'
-run_expect "manifest records pi_version" \
+#
-    "cat /etc/pi-devbox/build-manifest.json" '"pi_version"'
+# which passes on {"pi_version": ""} and on {"pi_version": null}. The tell was
 # visible in its own passing output — `✅ manifest records pi_version (got
 # "pi_version")` echoes the key back as the thing it claims to have found.
 # Two failure modes were therefore invisible: a key that survives with an empty
 # or garbage value, and a key that vanishes from the manifest while every
 # remaining value still looks fine.
 #
 # Those two need SEPARATE assertions, and the reason is a trap worth keeping in
 # writing: an "every component value is a valid SHA" loop passes VACUOUSLY on
 # components:{} — jq's all() over an empty list is true — so the value check
 # alone would go green on a manifest that lost every component. Mutation-tested
 # 2026-08-25 across nine fabricated manifests (empty map, deleted key, "",
 # null, "unknown", 12-hex truncation, 40 non-hex chars, legit null pi-studio).
 run "manifest declares every required component key" '
  req="pi-toolkit pi-extensions pi-fork pi-observational-memory pi-atelier mempalace-toolkit pi-studio"
  for k in $req; do
    jq -e --arg k "$k" "(.components|has(\$k))" /etc/pi-devbox/build-manifest.json >/dev/null \
      || { echo "manifest lost component key: $k" >&2; exit 1; }
  done
 '
 # Subsumes the old `! grep -q \"unknown\"` check ("unknown" is not 40-hex), and
 # also catches "", null and truncated SHAs, which that grep let through. null is
 # legitimate for pi-studio alone: the non-studio variant has no such clone.
 run "manifest component values are resolved 40-hex commits" '
  jq -e "
    .components
    | to_entries
    | all(if .key == \"pi-studio\" and .value == null then true
           else (.value|type) == \"string\" and (.value|test(\"^[0-9a-f]{40}\$\")) end)
  " /etc/pi-devbox/build-manifest.json >/dev/null
 '
 # pi_version against ground truth, same shape as the mempalace check below.
 # Chains with the "pi version matches build arg" assertion earlier in this file:
 # together they tie build arg -> installed binary -> recorded manifest, so a
 # manifest written from a stale variable cannot pass by agreeing with itself.
 run "manifest pi_version matches the installed pi" '
  m=$(jq -r ".pi_version // empty" /etc/pi-devbox/build-manifest.json)
  b=$(pi --version 2>/dev/null | head -n1 | tr -d "\r")
  echo "manifest=[$m] installed=[$b]" >&2
  [ -n "$m" ] && [ "$m" = "$b" ]
 '
 # Top-level provenance fields: assert the SHAPE of each value, and only when the
 # field is populated. source_revision and build_date legitimately default to
 # empty (Dockerfile.variant ARGs) on a plain local `docker build`, so demanding
 # them would fail honest local smoke runs; a populated-but-malformed value is
 # the actual defect. release_tag defaults to "dev", so empty means a broken write.
 run "manifest top-level fields are well-formed, not merely present" '
  j=/etc/pi-devbox/build-manifest.json
  t=$(jq -r ".release_tag // empty" $j)
  r=$(jq -r ".source_revision // empty" $j)
  d=$(jq -r ".build_date // empty" $j)
  echo "release_tag=[$t] source_revision=[$r] build_date=[$d]" >&2
  [ -n "$t" ] || { echo "release_tag empty (ARG default is dev)" >&2; exit 1; }
  if [ -n "$r" ]; then
    printf "%s" "$r" | grep -qxE "[0-9a-f]{40}" || { echo "source_revision not a 40-hex commit" >&2; exit 1; }
  fi
  if [ -n "$d" ]; then
    printf "%s" "$d" | grep -qE "^[0-9]{4}-[0-9]{2}-[0-9]{2}T" || { echo "build_date not ISO-8601" >&2; exit 1; }
  fi
 '
 # mempalace CORE was absent from the manifest through v1.8.5: the toolkit SHA
 # was recorded but the palace version behind the MCP tools was not, so a palace
 # bug could not be correlated to an image version. Assert the field exists AND
 # equals the installed binary — recording it from ARG MEMPALACE_VERSION instead
 # would look identical here yet drift silently the first time an install
 # resolved to something other than the pin, which is the whole reason this file
 # is built from ground truth. `// empty` matters: jq -r prints the 4-char
 # string "null" for a JSON null, which would satisfy a naive -n test.
 run "manifest mempalace_version matches the installed core" '
  m=$(jq -r ".mempalace_version // empty" /etc/pi-devbox/build-manifest.json)
  b=$(mempalace --version 2>/dev/null | head -n1 | tr -d "\r"); b=${b##* }
  echo "manifest=[$m] installed=[$b]" >&2
  [ -n "$m" ] && [ "$m" = "$b" ]
 '
 # ... and, when CI supplies it, that the installed core is the version CI
 # actually AUDITED (published + not yanked on PyPI, in resolve-versions). This
 # does NOT duplicate the check above, which compares two properties of one
 # image and so cannot notice that BOTH are the wrong version. The live failure
 # mode it covers: the variant builds `FROM` a base tag chosen by base-decide's
 # content hash, so a bug in that hashing (the reason scripts/check-base-hash.sh
 # exists) could reuse a cached base built from an OLDER MEMPALACE_VERSION pin —
 # internally consistent, silently stale, invisible to every other assertion.
 if [ -n "${EXPECTED_MEMPALACE_VERSION:-}" ]; then
  run "installed mempalace matches CI's audited pin (${EXPECTED_MEMPALACE_VERSION})" "
    b=\$(mempalace --version 2>/dev/null | head -n1 | tr -d '\r'); b=\${b##* }
    echo \"installed=[\$b] audited_pin=[${EXPECTED_MEMPALACE_VERSION}]\" >&2
    [ \"\$b\" = \"${EXPECTED_MEMPALACE_VERSION}\" ]
  "
 fi
 # Every component must be a resolved commit (or null for pi-studio in the
-# non-studio variant) — 'unknown' means a clone silently failed to resolve.
+# non-studio variant) — now enforced by the 40-hex value check above, which
-run "manifest has no unresolved ('unknown') components" \
+# strictly subsumes the old whole-file grep for '"unknown"'. Only rev() ever
-    "! grep -q '\"unknown\"' /etc/pi-devbox/build-manifest.json"
+# emits "unknown" and rev() feeds components only, so nothing is lost.
-# pi-devbox-version wraps the manifest into a human-first command (this
+# pi-devbox-version wraps the manifest into a human-first command; verify the
-# PR); verify the binary is present, executable, and both output modes work.
+# binary is present, executable, and that all three output modes work.
 run "pi-devbox-version binary present + executable" \
    "test -x /usr/local/bin/pi-devbox-version"
 run_expect "pi-devbox-version human output shows release tag" \
    "pi-devbox-version" "pi-devbox "
-run_expect "pi-devbox-version --json round-trips the manifest" \
+# --json is a verbatim `cat` of the manifest, so "round-trips" is assertable
-    "pi-devbox-version --json" '"release_tag"'
+# literally. The old form grepped the output for the string "release_tag" — the
 # key name again — which would pass on a truncated or re-serialised dump.
 run "pi-devbox-version --json round-trips the manifest byte-for-byte" '
  a=$(cat /etc/pi-devbox/build-manifest.json)
  b=$(pi-devbox-version --json)
  [ "$a" = "$b" ] || { echo "--json output differs from the manifest on disk" >&2; exit 1; }
 '
 run_expect "pi-devbox-version --quiet is a compact one-liner" \
    "pi-devbox-version --quiet | wc -l" "1"
 # OCI labels live in the image config, not the container fs — inspect them
@@ -318,6 +520,68 @@ exec_test "settings.json bootstrapped"             'test -f $HOME/.pi/agent/sett
 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'
 # 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
 # canary that was supposed to catch it could not: it grepped "Shared palace:
 # multiple harnesses", a phrase present in BOTH the stale and the fresh copy.
 # A snapshot canary must pin the NEWEST section, so update this string whenever
 # the snapshot is refreshed — that is the point of it.
 #
 # v1.8.7: this fired for real, and on the release that changed the snapshot. The
 # pinned phrase was "Attribute what you file yourself", the heading of the
 # instruction telling agents to hand-stamp added_by — which that same release
 # WITHDREW (RFC 001 §7.3.2 ranks agent-side stamping worst-possible; the bridge
 # now does it). So the canary correctly reported "snapshot changed, expectation
 # did not", and blocked publication of an otherwise-green build (81 passed, 1
 # failed, twice). Two lessons kept in the assertion itself:
 #   * it is now BIDIRECTIONAL — the new phrase must be present AND the withdrawn
 #     one absent, so a re-vendored stale snapshot fails just as loudly as a
 #     forgotten bump. A one-way canary only catches half the drift.
 #   * a phrase canary can only ever detect "older than what I remembered to pin",
 #     never "older than skillset main". The real fix is a CI job diffing this
 #     file against the skillset repo — see the Unreleased changelog note.
 exec_test "mempalace skill snapshot is current"    'f=$HOME/.agents/skills/mempalace/SKILL.md; grep -q "Provenance is stamped for you" "$f" && ! grep -q "Attribute what you file yourself" "$f" && echo ok'
 # Link TARGETS, not just link existence: with no skillset mounted (as here) the
 # baked tree must be what resolves, for all three vendored skills.
 exec_test "vendored skills resolve to the baked tree (no skillset mounted)" \
    'for s in mempalace pi-extensions pi-devbox-environment; do
       case "$(readlink -f $HOME/.agents/skills/$s)" in
         /usr/local/share/pi-devbox/skills/$s) ;;
         *) echo "$s resolves to $(readlink -f $HOME/.agents/skills/$s)" >&2; exit 1 ;;
       esac
     done; echo ok'
 # The handover path itself. CI never mounts a skillset, so without this the
 # v1.8.5 fix would ship untested: fabricate a skillset + a skills dir holding
 # baked-style links, run the reconciler, and assert all three outcomes —
 # owned skill repointed, unowned skill left baked, user override untouched.
 exec_test "reconciler: owned skill handed to live clone, others untouched" \
    'set -e; t=$(mktemp -d); mkdir -p $t/ss/skills/mempalace $t/ss/skills/pi-extensions $t/skills
     echo LIVE > $t/ss/skills/mempalace/SKILL.md; echo LIVE > $t/ss/skills/pi-extensions/SKILL.md
     ln -s /usr/local/share/pi-devbox/skills/mempalace     $t/skills/mempalace
     ln -s /usr/local/share/pi-devbox/skills/pi-extensions $t/skills/pi-extensions
     mkdir -p $t/skills/mine; echo MINE > $t/skills/mine/SKILL.md
     devbox-skill-reconcile $t/ss $t/skills >/dev/null
     devbox-skill-reconcile $t/ss $t/skills >/dev/null   # idempotent
     [ "$(readlink $t/skills/mempalace)" = "$t/ss/skills/mempalace" ] || { echo "owned skill NOT repointed" >&2; exit 1; }
     [ "$(readlink $t/skills/pi-extensions)" = /usr/local/share/pi-devbox/skills/pi-extensions ] || { echo "unowned skill was repointed" >&2; exit 1; }
     [ "$(cat $t/skills/mine/SKILL.md)" = MINE ] || { echo "user override clobbered" >&2; exit 1; }
     rm -rf $t; echo ok'
 # The case above cannot fail if the reconciler stops checking WHERE a link
 # points — a mutation test showed all three of its assertions still passing with
 # that guard deleted, which is the same false-green shape as the old snapshot
 # canary. This one discriminates: an OWNED name (so it is considered) whose link
 # is a user override pointing outside the baked tree (so it must be left alone).
 exec_test "reconciler: user override on an owned name is left alone" \
    'set -e; t=$(mktemp -d); mkdir -p $t/ss/skills/mempalace $t/skills $t/mine-skill
     echo LIVE > $t/ss/skills/mempalace/SKILL.md; echo USERLINK > $t/mine-skill/SKILL.md
     ln -sfn $t/mine-skill $t/skills/mempalace
     devbox-skill-reconcile $t/ss $t/skills >/dev/null
     [ "$(cat $t/skills/mempalace/SKILL.md)" = USERLINK ] || { echo "user symlink override clobbered" >&2; exit 1; }
     rm -rf $t; echo ok'
 # mempalace-census gained a /usr/local/bin symlink in v1.8.3; its three siblings
 # had one since they were added, so this asserts the set stays complete.
 exec_test "mempalace-census on PATH"               'command -v mempalace-census >/dev/null && mempalace-census --help >/dev/null && echo ok'
 # pi-fork + pi-observational-memory are registered by entrypoint-user.sh via
 # `pi install /opt/<pkg>`, which runs slightly after the keybindings marker.