pi-session-mcp 0.14.0 → 0.14.2

package/docs/acceptance.md

@@ -2598,6 +2598,320 @@ image) reported `writer_accepted` from 09:48 to 09:51 UTC. Client-target
 all 14 writers. Doctor reported no error, only `workspace_mode_unset` for one
 workspace without a mode.
 
+### v0.14.2 pre-release acceptance
+
+`v0.14.2` was accepted on 2026-10-30 from 15:41 to 15:47 UTC on its release
+candidate `e911a6d`, on Linux (`x64`) with Node.js `26.12.1`, npm `12.2.1`,
+Codex CLI `0.166.0` and Claude Code `2.1.314`. Level 2 passed in the working
+tree and for the packed tarball, each with delivery off and with delivery on.
+Level 1 passed except `npm audit`. Later commits on the release pull request
+change only this record.
+
+The patch release ships #198 and #199 (PR #201), #200 (PR #203) and #202
+(PR #204) from `main` at `5acbebb`; the candidate adds only the version, the
+changelog heading and the roadmap lines. The MCP tool contract, result codes
+and configuration schema are unchanged. The #200 source changes were accepted
+on their branch before the merge, see
+[Issue #200 candidate acceptance](#issue-200-candidate-acceptance-2026-10-30);
+#198, #199 and #202 were checked in their pull requests by the full test suite
+and, for #202, the native Podman tests.
+
+- Level 1 in the checkout of the candidate after `npm ci`: every command exited
+  with `0`, except `npm audit`; `git status --short` printed nothing.
+  - The test run, with `NODE_OPTIONS=--unhandled-rejections=strict`, reported
+    144 files, 4097 passed and 14 skipped, and no unhandled error.
+  - `npm audit` and `npm audit --omit=dev` exited with `1` and name only the
+    known `undici` 8.10.2 finding through `@earendil-works/pi-coding-agent`
+    1.4.0, the latest SDK release, with eight advisories
+    ([#120](https://github.com/plagor44-ux/pi-session-mcp/issues/120)).
+  - `npm pack` listed 940 files (tarball shasum
+    `775e6de2a6e810839ceb4d8518b8e7c93eae38f3`, identical in three packs). A
+    scan of the unpacked files for private names, hosts and the maintainer's
+    home path found none; the only matches were the public repository owner in
+    links and the already redacted paths of disposable evaluation homes.
+  - Doctor reported `packageVersion` `0.14.2`. It exited with `2` because no
+    configuration was set (`config_missing`).
+- Level 2 in the working tree: 160 of 160 checks passed with delivery off and
+  228 of 228 with `--events spool`.
+- Packed-tarball Level 2 from a fresh prefix: 160 of 160 with delivery off and
+  228 of 228 with `--events spool`. The install smoke from another fresh prefix
+  reported `smoke_passed` with version `0.14.2`.
+- In every Level 2 run the real client registrations were unchanged and the
+  disposable prefixes were removed.
+- Podman-gated writer tests on the candidate (Podman `6.1.4`): 10 of 10 passed
+  (9 lifecycle tests, including the detached-`HEAD` export of #193, the
+  index-only export of #200 and the stash export of #202, and 1 boundary test).
+- Bubblewrap-gated sandbox tests (`test/sandbox-shell.bwrap.test.ts`, bubblewrap
+  `0.13.1`): 12 of 12 passed, none skipped.
+
+Not established for `0.14.2`: a Level 3 cycle on the release candidate, and the
+published-release Level 2 and upgrades, which follow after publishing.
+
+### Issue #200 candidate acceptance (2026-10-30)
+
+Recorded on 2026-10-30 for the unreleased branch `fix/writer-index-only-work`
+([Sprint 13](sprints/2026-10-30-s13-index-only-work.md)), on its source commit
+`1e1e694`, in a fresh clone on Linux (`x64`) with Node.js `26.12.1`, npm
+`12.2.1`, Podman `6.1.4`, Codex CLI `0.166.0` and Claude Code `2.1.314`. Later
+commits on the branch change only documentation.
+
+- Level 1 after `npm ci`: typecheck, `build:cli`, the test run with
+  `NODE_OPTIONS=--unhandled-rejections=strict` (141 files, 4062 passed, 14
+  skipped, no unhandled error), `build` and `git diff --check` exited with `0`,
+  and the status stayed clean. `npm audit --omit=dev` still exits with `1` for
+  the known `undici` finding (#120).
+- Podman-gated writer tests, none skipped: 8 of 8 lifecycle tests, including
+  the new index-only case, and 1 of 1 boundary test. The index-only case fails
+  against the source of `7752d3f` (`baseline: true`).
+- Level 2 in the working tree: 160 of 160 with delivery off and 228 of 228 with
+  `--events spool`.
+- Packed-tarball Level 2 from a fresh prefix: 160 of 160 with delivery off and
+  228 of 228 with `--events spool`. The install smoke reported `smoke_passed`
+  with version `0.14.1`.
+- In every Level 2 run the built files and the real client registrations were
+  unchanged, no process remained, the leak check passed and the disposable
+  directories were removed.
+
+Not established: a Level 3 cycle, macOS, and a productive writer upgrade with
+this change.
+
+### v0.14.1 post-release evidence
+
+Recorded on 2026-10-30 for the published release `0.14.1`.
+
+Tag binding: a fresh clone of the annotated tag `v0.14.1` (tag object
+`bd1ba81739742e1692d65425e94d5a091731a402`) peels to the merge commit
+`7752d3f1555d19fed06f43c0e046da07017a3320` of #197, and
+`git describe --tags --exact-match` reports `v0.14.1`. CI on the merge commit
+(run 41013930671) and on the tag (run 41017350738) passed on the first attempt.
+The npm package records `gitHead` `0753fad`, the head of #197, whose tree
+(`36654c3`) is identical to the merge commit's.
+
+- Level 1 on the tag clone after `npm ci`, from 08:27 to 08:29 UTC with
+  Node.js `26.12.1` and npm `12.2.1`: typecheck, `build:cli`, the test run
+  (141 files, 4044 passed, 14 skipped, with
+  `NODE_OPTIONS=--unhandled-rejections=strict`), `build` and
+  `git diff --check` exited with `0`, and the status stayed clean. Doctor
+  reported `packageVersion` `0.14.1` and exited with `2` because no
+  configuration was set (`config_missing`).
+- `pi-session-mcp@0.14.1` on npm: 933 files, shasum
+  `886a20688a44a967d1f917e9dad5461e83fbb5e5`; `npm pack` of the tag clone gives
+  the same shasum and file count. It differs from the candidate's
+  `47cf66a3856530112c11095d07cb05b7ab9892f4` below because `0753fad` adds the
+  pre-release record to the packaged `docs/acceptance.md`; no other file
+  changed.
+- Published release, Level 2 on the tag clone, 08:29 to 08:31 UTC: 160 of 160
+  with delivery off and 228 of 228 with `--events spool`. The manifests and
+  the 152 built runtime files were byte-identical before and after the client
+  cycles.
+- Published npm package, Level 2 from a fresh prefix, 08:31 to 08:33 UTC:
+  160 of 160 with delivery off and 228 of 228 with `--events spool`. The
+  install smoke on the published package reported `smoke_passed` with version
+  `0.14.1`.
+- In every Level 2 run the real client registrations were unchanged, no process
+  remained and the leak check passed. Clients: Codex CLI `0.166.0` and Claude
+  Code `2.1.314`.
+- The GitHub release `v0.14.1` was published the same day.
+
+Installations: the workstation and the second machine (Linux) run `0.14.1`,
+upgraded by the maintainer with the steps of
+[Installation](installation.md#container-writers); both client targets passed
+`--verify`, and Doctor reported no error. On the workstation all 18 writers
+were provisioned again with `0.14.1` on 2026-10-30 for a profile change and
+reported `writer_accepted` and `--writer <name> --verify` ok. Those writers
+were removed before re-provisioning on the strength of the `0.14.1`
+inspection, which #200 shows to ignore work that exists only in the index;
+whether any of them held such work cannot be established afterwards.
+
+### v0.14.1 pre-release acceptance
+
+`v0.14.1` was accepted on 2026-10-30 from 06:04 to 06:15 UTC on its release
+candidate `a239610`, on Linux (`x64`) with Node.js `26.12.1`, npm `12.2.1`,
+Codex CLI `0.162.1` and Claude Code `2.1.314`. Level 2 passed in the working
+tree and for the packed tarball, each with delivery off and with delivery on.
+Level 1 passed except `npm audit`. Later commits on the release pull request
+change only this record.
+
+The patch release ships Sprint 12 (#192, #193, #194) from `main` at `d9a47f5`;
+the candidate adds only the version, the changelog heading and the roadmap
+line. The MCP tool contract, result codes and configuration schema are
+unchanged. The source changes were accepted on the branch before the merge, see
+[Sprint 12 candidate acceptance](#sprint-12-candidate-acceptance-2026-10-30),
+including Level 3.
+
+- Level 1 in the checkout of the candidate after `npm ci`: every command exited
+  with `0`, except `npm audit`; `git status --short` printed nothing.
+  - The test run, with `NODE_OPTIONS=--unhandled-rejections=strict`, reported
+    141 files, 4044 passed and 14 skipped, and no unhandled error.
+  - `npm audit` and `npm audit --omit=dev` exited with `1` and name only the
+    known `undici` 8.10.2 finding through `@earendil-works/pi-coding-agent`
+    1.4.0, the latest SDK release, with eight advisories
+    ([#120](https://github.com/plagor44-ux/pi-session-mcp/issues/120)).
+  - `npm pack` listed 933 files (tarball shasum
+    `47cf66a3856530112c11095d07cb05b7ab9892f4`, identical in three packs). A
+    scan of the unpacked files for private names, hosts and the maintainer's
+    home path found none.
+  - Doctor reported `packageVersion` `0.14.1`. It exited with `2` because no
+    configuration was set (`config_missing`).
+- Level 2 in the working tree: 160 of 160 checks passed with delivery off and
+  228 of 228 with `--events spool`.
+- Packed-tarball Level 2 from a fresh prefix: 160 of 160 with delivery off and
+  228 of 228 with `--events spool`. The install smoke from another fresh prefix
+  reported `smoke_passed` with version `0.14.1`.
+- In every Level 2 run the real client registrations were unchanged, no process
+  remained, the leak check passed and the disposable directories were removed.
+- Podman-gated writer tests on the candidate (Podman `6.1.4`): 8 of 8 passed
+  (7 lifecycle tests, including the detached-`HEAD` export of #193, and 1
+  boundary test).
+- Bubblewrap-gated sandbox tests (`test/sandbox-shell.bwrap.test.ts`, bubblewrap
+  `0.13.1`): 12 of 12 passed, none skipped.
+
+Not established for `0.14.1` beyond the Sprint 12 record: a Level 3 cycle on
+the release candidate itself, and the published-release Level 2 and upgrades,
+which follow after publishing.
+
+### Sprint 12 candidate acceptance (2026-10-30)
+
+Recorded on 2026-10-29 and 2026-10-30 for the unreleased branch
+`fix/s12-audit-findings` ([Sprint 12](sprints/2026-10-29-s12-audit-fixes.md),
+#192, #193, #194). No release, tag or npm publish.
+
+- Level 1 on the final source `9426682` in a separate detached worktree with
+  Node.js `26.12.1`: `npm ci`, typecheck, `build:cli`, the test run (530 files,
+  4044 passed, 14 skipped, 0 failed, no unhandled error, with
+  `NODE_OPTIONS=--unhandled-rejections=strict`), `build` and
+  `git diff --check 9d9cf8c..HEAD` exited with `0`. The same on the earlier
+  candidate `896e29d`: 4043 passed, 0 failed.
+- Real rootless Podman with the pinned Node image (git `2.39.5`):
+  `test/writer-lifecycle.podman.test.ts` 7 of 7, including the new clean
+  detached-HEAD case, which fails against the source of `9d9cf8c`. In the image,
+  `core.useReplaceRefs=false` makes a graft-hidden detached commit visible
+  again.
+- Level 2 on `npm pack` of `896e29d`, installed into a fresh prefix below the
+  home directory: 160 of 160 with delivery off and 228 of 228 with
+  `--events spool`; real registrations and built files unchanged, no process
+  left, path-leak scan 0 hits. Clients: Codex CLI `0.162.1` and Claude Code
+  `2.1.312`. The two later commits change the guard's Git arguments and a
+  regular-expression spelling; Level 2 was not repeated for them.
+- Live profile change (item D), on an expendable test configuration: a
+  candidate with the new read-only profile `review-sonnet`
+  (`anthropic/claude-sonnet-5-5`), Doctor without error, probe dry run, one
+  probe turn (`probe_passed`), timestamped backup and atomic replacement,
+  Doctor, then real use by a fresh server for the R1 and final reviews; rolled
+  back to the backup afterwards, Doctor without error. No production
+  configuration or writer was touched.
+- Live container writer (items B and C), with the packed candidate, an
+  expendable configuration and a synthetic repository: profile `s12-code`
+  (`deepseek/deepseek-flash`, coding, skill `pi-session-implementation`),
+  one probe turn (`probe_passed`); `--repo s12-probe --mode container
+  --profiles s12-code --writers 1 --apply` reported `writer_provisioned` and
+  `writer_accepted`, `--writer s12-probe-w1 --verify` `mcp_verified`. A real
+  relayed coding session completed its task; `--collect --apply` imported
+  `refs/remotes/writer-s12-probe-w1/s12-live-c`, whose commit passed the
+  oracle (4 of 4 tests), and `--finish --apply` reported `writer_reset`. With
+  the host profile's skills then changed, a start failed with
+  `writer_unavailable`, reason `none_admitted`, counts
+  `settingsChanged: 1`, and collection afterwards found `nothing_to_collect`.
+  After `--writer s12-probe-w1 --remove` and the provisioning request again,
+  the writer was accepted and verified and a start succeeded. Rolled back:
+  writer removed, configuration, repository and prefix deleted.
+- Level 3, ten-task cycle, on the final source `9426682` (`dist/main.js`
+  SHA-256 `ab93e3a932b1d5147dcbb48bbb85d9442c2214e486101f8d427360b99672cfdb`)
+  from a separate detached checkout, with a temporary credential-free
+  configuration (`l3-read` read-only and `l3-code` coding, both
+  `deepseek/deepseek-flash`), synthetic fixtures, events off, one probe turn
+  per profile as preflight. Claude Code `2.1.312` ran as `claude -p` with a
+  per-invocation `--mcp-config`, `--strict-mcp-config` and
+  `--model claude-sonnet-5-5`; Codex CLI `0.162.1` as `codex exec
+  --ignore-user-config` with `-c mcp_servers.*` overrides. Both clients could
+  wait with `sleep` between polls.
+  - Cycle 1 was not accepted: 5 of 10. The worker ignored a requested
+    ordering in both follow-ups (T2), refused the abort task's essay prompt
+    within about 1.5 seconds so that nothing was left to abort (T5), and the
+    Codex coding snapshot could not be written from the Codex sandbox (T3). A
+    path hit came from the worker's `assistantText`, not from server
+    metadata. No Pi Session MCP defect was found; the cycle is kept unchanged
+    with its own pre-registration.
+  - Cycle 2, with a new pre-registration before its first task (order-free
+    LOW oracle, a long deterministic listing as the abort prompt, snapshots
+    inside the controller directory, the leak scan separating server metadata
+    from `assistantText`): 10 of 10. Read-only fixture digests unchanged; both
+    coding snapshots pass their oracle and the fixture tests and show only the
+    allowed files; both abort tasks show running, abort, `aborted`, close, an
+    empty `pi_session_list` and a fresh `idle` session. Zero leak hits, also in
+    `assistantText`; no server or client process before or 10 seconds after any
+    invocation. Polls per turn: Claude Code 1 to 2, Codex 2 to 4. Deviation:
+    the Codex sandbox refused to spawn `git`, so the Codex snapshots' status
+    lists were derived from the barrier snapshot trees against `HEAD`.
+  The cycle-2 gate holds.
+
+Not established: a release of these fixes, the operator rollout on either
+machine, macOS, and #120.
+
+### v0.14.0 post-release evidence
+
+Recorded on 2026-10-29 for the published release `0.14.0`.
+
+Tag binding: a fresh clone of the annotated tag `v0.14.0` (tag object
+`f3a8b088a85fd5825c3256f4a7950ba051cbf388`) peels to the merge commit
+`fd4fdeacf9d02c04b6fd89314f7ec819b5506ed9` of #190, and
+`git describe --tags --exact-match` reports `v0.14.0`. CI on the merge commit
+(run 40928709705) and on the tag (run 40929602738) passed on the first attempt.
+The tag was created after the npm package had been published; the package
+records `gitHead` `d904fed`, the head of #190, whose tree (`3ae966b`) is
+identical to the merge commit's.
+
+- Level 1 on the tag clone after `npm ci`, from 18:18 to 18:20 UTC with
+  Node.js `26.12.1` and npm `12.2.1`: typecheck, `build:cli`, the test run
+  (139 files, 4005 passed, 14 skipped, with
+  `NODE_OPTIONS=--unhandled-rejections=strict`), `build` and
+  `git diff --check` exited with `0`, and the status stayed clean. Doctor
+  reported `packageVersion` `0.14.0` and exited with `2` because no
+  configuration was set (`config_missing`).
+- `pi-session-mcp@0.14.0` on npm: 932 files, shasum
+  `579cc111a7aa62987b5f35e79b34b69853c8a0e3`. It was published by the
+  maintainer; `npm pack` of the tag clone gives the same shasum and file count.
+- Published npm package, Level 2 from a fresh prefix, 18:19 to 18:21 UTC:
+  160 of 160 with delivery off and 228 of 228 with `--events spool`; real
+  registrations and built files unchanged, no process left, leak check passed.
+  Clients: Codex CLI `0.162.1` and Claude Code `2.1.312`. The install smoke on
+  the published package reported `smoke_passed` with version `0.14.0`.
+- The GitHub release `v0.14.0` was published the same day.
+
+Operator upgrade of the workstation from `0.13.1` to `0.14.0` on 2026-10-29
+from 18:33 UTC, following
+[Installation](installation.md#container-writers): no Pi session of this
+controller was open; other controller sessions without a coding session stayed
+open and need a reconnect. Both client targets were removed with `0.13.1`, then
+`npm install -g pi-session-mcp@0.14.0`. Doctor reported only
+`writer_not_ready` for the 18 writers. A dry run of the first provisioning
+command with unchanged settings reported `mode_unchanged` and
+`writer_planned`; with `--apply`, five container repositories with 18 writers
+(2 with `--tags reachable`, 4, 4 with `--cache go`, 4 with base `dev`, 4 with
+`--cache uv`, three of them with operator images) reported `writer_accepted`
+from 18:34 to 18:37 UTC. Client-target `--apply` and `--verify` passed for
+`claude-code:user` and `codex:user` (`mcp_verified`, `skill_verified` for both
+controller skills, and `hook_verified` for the wake hook); `--writer <name>
+--verify` passed for all 18 writers. Doctor reported no error, only the known
+`workspace_gitfile` and `workspace_mode_unset` warnings of the worktree
+aliases.
+
+Operator upgrade of the second machine (Linux) from `0.13.1` to `0.14.0` on
+2026-10-29 from 18:38 UTC, with Node.js `24.22.0` and the same steps; one
+controller session's server process stayed open and needs a reconnect. Both
+client targets were removed with `0.13.1`, then
+`npm install -g pi-session-mcp@0.14.0`; Doctor reported only
+`writer_not_ready` for the 14 writers. With `--apply`, four container
+repositories with 14 writers (4, 2, 4 with an operator image and `--cache go`,
+4 with an operator image) reported `writer_accepted` from 18:39 to 18:42 UTC.
+Client-target `--apply` and `--verify` passed for `claude-code:user` and
+`codex:user` (`mcp_verified`, `skill_verified` for both controller skills), and
+`--writer <name> --verify` passed for all 14 writers. Doctor reported no
+error, only `workspace_mode_unset` for one workspace without a mode.
+
+Not established for `0.14.0` after the upgrade: a coding session through a
+re-accepted writer, an agent-driven profile change end to end, and Level 3.
+
 ### v0.14.0 pre-release acceptance
 
 `v0.14.0` was accepted on 2026-10-29 from 17:56 to 18:01 UTC on its release

package/docs/adr/0012-leased-writer-pool.md

@@ -161,12 +161,16 @@ base.
   In both cases the host server closes that launcher and tries the next
   candidate. The inner writer guard stays the authority for baseline admission
   inside the boundary.
-- Before the inner start the relay compares the requested profile's entry in
-  the writer's validated `pi_capabilities_get` (permission profile, provider,
-  model, thinking level) with the host's configured profile and moves on with
-  `writer_settings_changed` on any difference, so a writer never runs an
-  outdated version of a host profile. The launcher cannot do this check: it
-  starts before the profile is known.
+- Before the inner start the relay compares every public capability field of
+  the requested profile's entry in the writer's validated `pi_capabilities_get`
+  with the host's configured profile: `permissionProfile`, `provider`, `model`,
+  `thinkingLevel` and `shell` exactly, and `skills`, `extensions` and
+  `grantedExtensionTools` as sets. A mismatch or a missing entry counts as
+  `settingsChanged`, starts no inner session and moves on to the next
+  candidate, so a writer never runs an outdated version of a host profile. The
+  launcher cannot do this check: it starts before the profile is known.
+  (Amended 2026-10-29, #194: the comparison covers every public capability
+  field, not only permission profile, provider, model and thinking level.)
 - If no candidate is admitted, the start fails with `writer_unavailable`, a
   content-free reason and content-free counts. `none_ready`: no writer of the
   workspace is ready, migrated and has a recorded acceptance (whether that

package/docs/adr/0013-hardened-read-only-profiles.md

@@ -145,6 +145,36 @@ directly after `grantedExtensionTools`. This is configured intent only.
   MCP tools and the granted extension tools. A profile with granted extension
   tools cannot have a sandboxed shell.
 
+### Amendment 2026-10-29: context files
+
+Issue #192. Previously every resource loader kept the SDK behaviour: Pi
+context files (`AGENTS.override.md`, `AGENTS.md`, `AGENTS.MD`, `CLAUDE.md`,
+`CLAUDE.MD`) were loaded from the session directory and every ancestor
+directory, and a context file reached through a symlink was followed to its
+target, so a read-only session also loaded context from outside the workspace.
+
+New rule: for **read-only profiles** every resource loader keeps only context
+files whose real path lies inside the workspace's real path, on every reload
+and before the first provider request. A symlinked context file that resolves
+outside the workspace, a dangling one, and the context files of ancestor
+directories above the workspace (including a main repository above a linked
+worktree) are not loaded for read-only profiles; the linked worktree's own file
+inside the workspace is. Coding profiles keep the SDK behaviour (the working
+directory and its ancestors).
+
+The filter runs on the SDK's result, after the SDK has picked the first
+existing name per directory. If that file is dropped, the directory contributes
+no context file: an `AGENTS.override.md` that resolves outside the workspace
+also hides an `AGENTS.md` beside it. This fails closed. A kept file's content
+is read again from its verified real path, so a link swapped after the SDK
+read cannot bring in outside content.
+
+Why: the read roots of this ADR. Section 1 confines the read tools of
+read-only profiles to the workspace and the skill directories; context files
+are model input rather than tool reads, and before this amendment they were the
+one channel through which content from outside those roots still reached a
+read-only session.
+
 ## Contract change and versioning
 
 The capabilities field `shell`, the start error `sandbox_unavailable` and the

package/docs/adr/0014-profile-probe-and-model-catalog.md

@@ -1,6 +1,6 @@
 # ADR 0014: Profile probe and offline model catalog
 
-**Status:** Accepted (2026-10-29); unreleased. Issue #139.
+**Status:** Accepted (2026-10-29); released in 0.14.0. Issue #139.
 
 ## Context
 

package/docs/doctor-design.md

@@ -44,7 +44,7 @@ and owners are:
 | `writer_not_migrated` | Warning. The writer state still records the legacy launch, so the writer is not in the relay pool | validated writer name |
 | `writer_off_default_base` | Warning. One or more ready writers of a container workspace have a base other than the workspace default base; the remediation states only their count | validated workspace alias |
 | `writer_git_identity_missing` | Clone Git config lacks a readable user name and email (warning); set both in the operator checkout, then reset the writer | validated writer name |
-| `writer_dirty` | HEAD is not the base branch, its commit differs, another branch exists, or Git metadata cannot safely be inspected (warning) | validated writer name |
+| `writer_dirty` | HEAD is not the base branch, its commit differs, another branch exists, or Git metadata cannot safely be inspected (warning). It reads only `HEAD` and refs, never the index or worktree, so an `ok` result is no proof of a clean clone and never authorizes cleanup; the boundary inspection does (#200) | validated writer name |
 | `writer_uncollected_bundle` | Bundles directory is unsafe/unreadable or contains entries other than base.bundle (warning; an absent directory alone does not warn) | validated writer name |
 | `extension_missing` | Pi has no user install of a package that a profile's `extensions` names | `<profile>:<package>` |
 | `extension_version_mismatch` | The installed manifest's version differs from the pinned version, or the manifest or its `pi.extensions` entries are invalid | `<profile>:<package>` |

package/docs/execution-modes.md

@@ -119,6 +119,11 @@ not selected by tool prefix. Their private state lives under
 `$HOME/.local/state/pi-session-mcp/writers/<name>/`: `clone`, `agent`, `config`,
 `bundles`, optional `go`, `wrapper.sh` and `state.json`. This lifecycle metadata
 is distinct from in-memory MCP sessions; it does not implement session resume.
+The writer's `agent` directory also receives a byte copy of the host's persisted
+Pi model catalog (`models-store.json`, catalog data and no credentials) at
+provisioning, reset, recreate and each launch, so that a writer resolves the same
+models as the host. A missing, linked or oversized host file is skipped and the
+writer keeps the SDK's shipped model list.
 Each clone is made via a bundle, with no hardlinks to the operator's repository.
 The workspace records a short default `base` in its container entry, selected
 by `--base` or origin's symbolic HEAD, falling back to local main. Repeating a
@@ -182,11 +187,54 @@ pi-session-mcp-setup --writer my-project-w1 --finish --apply
 
 Collection exports changed branches via a bundle into the operator's checkout as
 `refs/remotes/writer-<name>/<branch>`. Uncommitted/untracked work is captured as a
-synthetic `<branch>-wip` commit. These refs are **untrusted until reviewed**;
+synthetic `<branch>-wip` commit. A staged index whose tree differs from both
+HEAD's tree and the worktree (for example a staged change that the worktree
+reverted) is exported as an extra synthetic `<branch>-index` commit, so work
+that exists only in the index is recovered too; the same name rules apply. An
+index that cannot be evaluated, such as an unmerged conflict, makes inspection
+and collection fail closed and every non-`--discard` cleanup refuse. Such a
+writer is not at its baseline, so it is not admitted to a new session either;
+its work stays in the clone until the operator decides on `--discard`. Have the
+worker resolve or abort a merge before its session ends. A clean detached HEAD whose commit no branch in
+the clone reaches is exported as `<base>-detached` (for example `main-detached`,
+imported as `refs/remotes/writer-<name>/main-detached`); a dirty detached HEAD
+keeps the `<base>-wip` export. A `<base>-detached`, `<branch>-wip` or `<branch>-index` name that
+an exported branch already takes, or that conflicts with an exported branch's
+path (such as a branch `main-detached/topic`), is refused and makes collection
+incomplete (`writer_collect_incomplete`); the other branches are still
+exported. Clone-side Git ignores replace refs. These refs are **untrusted until reviewed**;
 setup does not merge or cherry-pick them. Collection does not change the clone.
-Only a complete export records a digest authorizing later destructive cleanup;
-new work invalidates that authorization. Stashes are not exported as branches:
-resolve any needed stash inside the boundary before collection.
+Only a complete export records a digest authorizing later destructive cleanup,
+and the digest is recorded only when the clone's HEAD commit and every branch
+commit exist in the operator checkout; otherwise collection is incomplete
+(`writer_collect_incomplete`) and no digest is recorded. This includes the base
+commit: if the operator checkout no longer has it (for example after a deleted
+base branch and garbage collection), collect and finish fail this way even on a
+pristine writer, without refused names; fetch the base again or resolve with
+`--reset --discard --apply`. The digest also covers the index tree, and the
+index and worktree tree objects must exist in the operator checkout. New work,
+including a change to the index alone, invalidates that authorization. A digest
+recorded by 0.14.1 or earlier never matches the versioned digest, so collect
+such a writer again before a destructive operation.
+
+Every stash entry is exported as `<base>-stash-<n>`, numbered like
+`stash@{n}` (newest first; for example `main-stash-0`), with its index and
+untracked parts as the commit's parents; `git stash apply` accepts the imported
+ref. The same name rules apply, and every stash commit must exist in the
+operator checkout before a digest is recorded. Tags, notes, replace refs,
+remote-tracking refs and refs in any other namespace are not exported, whatever
+their names. Each must name an object the operator checkout already has,
+otherwise the writer is not at its baseline and collection is incomplete
+(`writer_collect_incomplete`, without a refused name) and no digest is
+recorded. Provisioned tags and remote-tracking refs, and a lightweight tag on
+an exported commit, pass while the operator checkout still has their objects:
+only such a ref's name is lost at cleanup. An annotated tag, a note, a replace
+ref or a moved remote-tracking ref that the worker created blocks cleanup until
+a later session on that writer removes it or the operator decides on
+`--discard`; the server guard admits such a writer as long as its branches,
+stash and worktree are at the baseline. If the operator deletes a provisioned
+annotated tag and its object is garbage-collected, the writer's copy blocks
+cleanup the same way.
 
 `--finish` collects, then resets a persistent writer or recreates an ephemeral
 writer, on the workspace default base. A collect refusing any branch name is incomplete (`writer_collect_incomplete`,
@@ -201,7 +249,7 @@ unexported work. Do not blindly retry or bypass a refusal by changing profiles.
 | `--reset --apply [--base <ref>]` | Reset to current source base branch, delete extra branches/stash and clean untracked files, and ignored files with `--clean all`; falls back to recreation if post-reset verification fails |
 | `--recreate --apply` | Rebuild clone and agent copy from the workspace default base, retaining image/settings |
 | `--finish --apply` | Collect, then reset persistent / recreate ephemeral on the workspace default base |
-| `--remove` | Explicit mutation: unregister owned registrations before removing writer state |
+| `--remove` | Explicit mutation: unregister owned registrations before removing writer state; read-only directories inside the writer root (such as Go's module cache) are made removable first, and `state.json` is removed last |
 | `--verify` | Doctor and bounded relay-path MCP handshake/tools/list/capabilities; verify the host registration with client-target verify too; no session or provider request |
 
 Other than explicit `--remove` and `--verify`, omitting apply only plans.
@@ -234,6 +282,14 @@ reset updates admission without a server restart. A missing/unusable runtime or
 stale/unready writer launches a refusal MCP server: all eight tools return the
 sanitized refusal, with no host fallback. See [Tool contracts](tool-contracts.md).
 
+Before the relay starts an inner session it compares every public capability
+field of the writer's profile with the host profile: `permissionProfile`,
+`provider`, `model`, `thinkingLevel` and `shell` exactly, and `skills`,
+`extensions` and `grantedExtensionTools` as sets. A mismatch or a missing
+entry counts as `settingsChanged`, starts no inner session and moves on to the
+next writer; if no writer is admitted, the start fails with
+`writer_unavailable` and reason `none_admitted`.
+
 ## Reports and finding codes
 
 Reports use sanitized targets `modes/workspace/<alias>` or `writer/<alias>/<name>`
@@ -283,12 +339,12 @@ listed below; dynamic planned and MCP verification outcomes are listed explicitl
 | `clone_verification_failed` | Clone layout/hook/config redirects unsafe |
 | `writer_state_invalid` | Missing/malformed/mismatched writer state |
 | `writer_state_unreadable` | Writer state cannot safely be read |
-| `writer_inspect_failed` | Contained work inspection failed |
+| `writer_inspect_failed` | Contained work inspection failed, including an index that cannot be evaluated such as an unmerged conflict |
 | `writer_uncollected` | Changed work lacks a matching complete collection digest; destructive operation refused |
-| `writer_collect_failed` | Bundle generation/verification/import failed |
-| `writer_collect_incomplete` | One or more branch names refused; no cleanup authorization |
-| `ref_name_refused` | Unsafe export name or WIP name collision |
-| `nothing_to_collect` | No changed branch or WIP to export |
+| `writer_collect_failed` | Bundle generation/verification/import failed, including an unmerged index |
+| `writer_collect_incomplete` | One or more branch names refused, a collected commit or tree is missing from the operator checkout, or a tag, note or other unexported ref names an object only the clone has; no cleanup authorization |
+| `ref_name_refused` | Unsafe export name, or a `-wip`, `-index`, `-detached` or `-stash-<n>` name collision |
+| `nothing_to_collect` | No changed branch, WIP, index, detached commit or stash entry to export |
 | `writer_collected` | Complete export recorded |
 | `writer_reset_failed` | Reset command or validation failed |
 | `writer_reset` | Persistent clone reset and verified |

package/docs/installation.md

@@ -105,6 +105,15 @@ Providers registered only by Pi extensions are not listed; the report includes
 that note. Invalid catalog ids are omitted and counted in `omittedIds`.
 Catalog creation failures report `catalog_unavailable`.
 
+The list includes the models in the catalog overlay that Pi persisted earlier
+(`models-store.json` in Pi's agent directory, written when Pi refreshes its
+model catalogs), restored offline. Pi Session MCP makes no request to refresh
+it: run Pi once so that it refreshes its catalogs, and a model that only the
+refreshed catalog offers becomes available to `--list-models`,
+`--probe-profile` and sessions alike. Without that file only the models
+shipped with the Pi SDK are listed. (ADR 0014 describes the original design
+with a catalog that is created without this restore.)
+
 With `PI_SESSION_MCP_CONFIG` already set to the configuration to check:
 
 ```bash

package/docs/isolation-setup.md

@@ -225,12 +225,22 @@ Git metadata can redirect reads to worker-controlled configuration. Setup checks
 clone layout and runs clone-side Git only in throwaway no-network containers.
 Collect with `--writer <name> --collect --apply`, then review
 `refs/remotes/writer-<name>/<branch>` in your own checkout, with dirty work at
-`<branch>-wip`. Imported refs are untrusted until reviewed.
+`<branch>-wip`, staged work that differs from both HEAD and the worktree at
+`<branch>-index`, a clean detached HEAD at `<base>-detached` (for example
+`main-detached`), and every stash entry at `<base>-stash-<n>`. Tags, notes and
+other refs are not exported; one that names an object only the clone has makes
+collection incomplete. Imported refs are untrusted until reviewed.
 
 After taking over the result and closing its coding session, run
 `pi-session-mcp-setup --writer <name> --finish --apply` before another task.
 It collects then resets (persistent) or recreates (ephemeral). If any branch name
-was refused, collection is incomplete and finish stops. Rename inside the writer
+was refused, collection is incomplete and finish stops; a `<base>-detached`,
+`<branch>-wip`, `<branch>-index` or `<base>-stash-<n>` name that an exported branch takes or whose path it conflicts
+with is refused the same way. The release digest is
+recorded only when the clone's HEAD commit, every branch commit and every stash
+commit exist in the operator checkout and every other ref names an object the
+operator checkout has, otherwise collection is `writer_collect_incomplete` and
+no digest is recorded. Rename inside the writer
 or have the operator explicitly resolve loss with `--reset --discard --apply`.
 Finish returns persistent and ephemeral writers to the workspace default base.
 No reconnect is needed after finish, reset or recreate: each session starts a

package/docs/roadmap.md

@@ -41,6 +41,27 @@ mean they are implemented or that their gates passed.
   profile), and the shipped controller skill `pi-session-profiles`, with which a
   controlling agent creates, changes or retires profiles without a guided
   dialog. Recorded in [ADR 0014](adr/0014-profile-probe-and-model-catalog.md).
+- 2026-10-30: [Sprint 12](sprints/2026-10-29-s12-audit-fixes.md) fixes three
+  audit findings on `9d9cf8c` in one pull request, released in patch release
+  0.14.1: read-only context files confined to the workspace
+  ([#192](https://github.com/plagor44-ux/pi-session-mcp/issues/192)), detached
+  `HEAD` collection and the release-digest gate
+  ([#193](https://github.com/plagor44-ux/pi-session-mcp/issues/193)) and the
+  full writer profile comparison in the relay
+  ([#194](https://github.com/plagor44-ux/pi-session-mcp/issues/194)). Levels 1
+  to 3 passed for the candidate. #120 still waits for a Pi SDK release.
+- 2026-10-30: [Sprint 13](sprints/2026-10-30-s13-index-only-work.md) fixes the
+  loss of work that exists only in a writer's Git index
+  ([#200](https://github.com/plagor44-ux/pi-session-mcp/issues/200)) in one
+  pull request, released in patch release 0.14.2: inspection evaluates the
+  original index tree, the versioned collection digest covers it, and
+  collection exports staged-only work as `<branch>-index`. The published-release Level 2 of 0.14.1 passed. The
+  same loss for work that exists only in a stash entry is the follow-up
+  [#202](https://github.com/plagor44-ux/pi-session-mcp/issues/202).
+- 2026-10-30: #202 is fixed in one pull request, released in patch release
+  0.14.2: collection exports every stash entry as `<base>-stash-<n>`, and tags,
+  notes and other unexported refs must name objects the operator checkout
+  already has before a writer counts as baseline or a digest is recorded.
 
 The explicit 2026-10-17 user request adds a bounded development-only
 [token-footprint measurement](sprints/2026-10-17-token-footprint.md), following

package/docs/sprints/2026-10-24-s8-writer-migration.md

@@ -4,9 +4,11 @@ Planning basis: main `47b8d26` (Sprint 7 merged), installed release 0.11.2.
 Tracking: [#79](https://github.com/plagor44-ux/pi-session-mcp/issues/79),
 prerequisite [#121](https://github.com/plagor44-ux/pi-session-mcp/issues/121).
 
-Status: **planned**. The maintainer made the choices on 2026-10-25; see
-[Decisions](#decisions-2026-10-25). Nothing below has been changed on any
-machine yet.
+Status: **in progress** — steps 1–4 are done (pilot `pi-session-mcp`,
+`node-app`, the operator images, go-app) and steps 5–7 are open; see
+[Progress (2026-10-27)](#progress-2026-10-27) and the v0.11.6 and v0.11.8
+post-release evidence in [Acceptance](../acceptance.md). The maintainer made
+the choices on 2026-10-25; see [Decisions](#decisions-2026-10-25).
 
 ## Mandate