pi-session-mcp 0.14.0 → 0.14.2

package/docs/sprints/2026-10-29-s12-audit-fixes.md

@@ -0,0 +1,174 @@
+# Sprint 12: audit findings F1–F3
+
+Planning basis: main `9d9cf8ca49e6e34dc16be6846b9324ad26ad92b9` (merge of PR
+#191), published 0.14.0, 2026-10-29. Entry: an external audit of that commit
+reported three defects with reproductions. This file plans the work and records
+it as it lands; it claims nothing that its progress log does not state with
+evidence.
+
+Branch: `fix/s12-audit-findings`, one pull request, no release.
+
+## Preflight (2026-10-29)
+
+- main and `origin/main` at `9d9cf8c`; open issues #79, #120, #144; no open
+  pull requests; clean operator checkout; no other worktree in use.
+- Doctor: no errors; only the known `workspace_gitfile` and
+  `workspace_mode_unset` warnings of the host worktree aliases.
+- Level 1 on `9d9cf8c` in a clean detached worktree on the workstation:
+  `npm ci`, `npm run typecheck`, `npm run build:cli`,
+  `NODE_OPTIONS=--unhandled-rejections=strict npm test` (527 files, 4005
+  passed, 14 skipped, 0 failed, no unhandled error) and `npm run build` all exit
+  0. The audit's cloud run of the same commit reported 70 failed tests and four
+  unhandled errors; they do not reproduce here, so they are not attributed to
+  the product. The audit environment is not available to separate them further.
+- Both `pi-session-mcp` writers were at `baseline` on an older main and were
+  reset without `--discard` to `9d9cf8c` (`writer_reset`).
+
+## Findings, re-checked on `9d9cf8c`
+
+| Id | Issue | Reproduction by the controller | Result |
+| --- | --- | --- | --- |
+| F1 | [#192](https://github.com/plagor44-ux/pi-session-mcp/issues/192) | Synthetic workspace whose `AGENTS.md` links to an outside marker file; `PI_CODING_AGENT_DIR` isolated; faux provider | Confined `read` refuses; `getAgentsFiles()` contains the marker; the real `SdkPiSessionAdapter` sends it as `project_instructions` to the faux provider. Confirmed. |
+| F2 | [#193](https://github.com/plagor44-ux/pi-session-mcp/issues/193) | Real Git; boundary scripts run by an injected runner | Detached `HEAD` commit, clean tree: remove before collect `writer_uncollected`; collect `nothing_to_collect`, 0 refs, digest stored; commit absent from the operator checkout; finish `writer_reset`; remove `writer_removed`. Feature-branch counterproof exports the commit. Confirmed; not yet a Podman result. |
+| F3 | [#194](https://github.com/plagor44-ux/pi-session-mcp/issues/194) | Real relay over stdio, fake writer server fixture | Identical profiles admitted; model drift refused with `settingsChanged`; host `skills: ["pi-session-implementation"]` against inner `skills: []` admitted. Confirmed. |
+
+## Decisions taken at planning
+
+- F1: for read-only profiles every resource loader keeps only context files
+  whose real path lies inside the workspace's real path. Context files of
+  ancestor directories above the workspace, including a main repository above a
+  linked worktree, are no longer loaded for read-only profiles: they are outside
+  the read roots of ADR 0013. Coding profiles keep the SDK's behaviour.
+- F2: smallest fix inside the existing collection contract; the export name for
+  a detached `HEAD` is a documented behaviour addition, no new public code.
+- F3: the relay compares every public capability field a writer reports, with
+  set semantics for skills, extensions and granted extension tools.
+- #120: still waiting for an SDK release (see below); no override, no
+  `npm audit fix --force`.
+- No release on this branch.
+
+## Roles and routing
+
+`pi_capabilities_get` and `--list-models` on 2026-10-29 settle which requested
+models exist as authenticated profiles:
+
+| Requested | Profile used | Status |
+| --- | --- | --- |
+| GPT 6.1 Sol | `code` (openai `gpt-6.1-sol`) | available |
+| GPT 6.1 Terra | none | unavailable: the catalog lists no `gpt-6.1-terra`; not substituted with another version |
+| DeepSeek | `code-deepseek` (`deepseek-flash`) | available |
+| GLM 5.3 | `review-glm`, `code-glm` (`zai-glm-5-3`) | available |
+| Mistral Large 4 | `code-mistral` (`mistral-large-4`) | available |
+| Sonnet 5.5 | no profile; provider `anthropic` authenticated | added only in an expendable test configuration (acceptance item D) |
+| Grok 4.7 | `review-grok` (xai `grok-4.7`) | available: the R2 turn completed |
+
+agy (Antigravity CLI, Gemini) plans the work packages, dependencies and review
+routing; Pi workers implement and review; the controller integrates, verifies
+and is the only editor of this file, the roadmap, `docs/acceptance.md` and the
+CHANGELOG.
+
+## Tasks
+
+| Id | Task | Route | Change area |
+| --- | --- | --- | --- |
+| P1 | Work packages, dependencies, review routing | agy | none |
+| P2 | Independent regression test plan | `review-glm` | none |
+| T1 | F1, #192 | `pi-session-mcp` writer, `code` | `src/sdk-pi-adapter.ts`, `src/confined-tools.ts`, tests |
+| T2 | F2, #193 | `pi-session-mcp` writer, `code-mistral` (agy's fallback for the unavailable Terra) | `src/writer-lifecycle.ts`, tests |
+| T3 | F3, #194 | `pi-session-mcp` writer, `code-deepseek` | `src/writer-relay.ts`, `src/capabilities.ts`, tests, relay fixture |
+| R1 | Security review of T1 and T3 | Sonnet 5.5, read-only | none |
+| R2 | Adversarial review of T2 and the Git lifecycle checks | `review-grok` | none |
+| D1 | Documentation and issue reconciliation (#120, ADR 0014 status, Sprint 8 status, #79, #144) | `pi-session-mcp` writer, `code-mistral`; controller as editor | `docs/`, `skills/pi-session-orchestration/SKILL.md` |
+| A | Live acceptance A–E | controller | evaluation record |
+
+## Progress log
+
+Recorded as work lands on the branch.
+
+- 2026-10-29: issues #192, #193 and #194 filed; this plan written before any
+  implementation.
+- P1: agy (`gemini-3.8-flash-high`, plan mode) proposed the packages,
+  `code-mistral` as the F2 author in place of Terra, Sonnet for R1 and Grok
+  with a fallback for R2, and at most three review rounds. Adopted.
+- P2: `review-glm` wrote the regression test plan; its edge cases (absent
+  against empty set fields, real-Git collection, a Podman case) went into the
+  task prompts.
+- T3 (`code-deepseek`, writer w2): collected as
+  `writer-pi-session-mcp-w2/fix/f3-relay-profile-drift`; the controller ran the
+  new tests against the old source (7 fail) and the fix (all pass); integrated
+  as `230e60e`, writer finished (`writer_reset`).
+- T1 (`code`, writer w1): collected as
+  `writer-pi-session-mcp-w1/fix/f1-context-files`; new tests against the old
+  source 9 of 12 fail, with the fix 148 of 148 pass; integrated as `a0a7d87`,
+  writer finished. The container-writer suite showed only the eight known
+  lock and hook timeouts (`override-lock`, `skill-customize-concurrency`,
+  `wake-hook`).
+- R1 (Sonnet 5.5, read-only, through the test configuration of item D):
+  `NON_BLOCKING_ONLY`. Fixed by the controller: kept context files are read
+  again from their verified real path (`79e8a7a`), the set comparison is
+  symmetric with a duplicated-entry test (`3e14279`); the shadowing case is
+  covered by a test and documented. Not changed: synchronous `realpathSync` in
+  the loader override (the SDK hook is synchronous) and the trust in the
+  writer's own capability report, which is the boundary the relay already
+  assumes.
+- T2 (`code-mistral`, writer w2): collected as
+  `writer-pi-session-mcp-w2/fix/f2-detached-collect`; the new real-Git tests
+  against the old source 3 of 8 fail, with the fix 8 of 8 pass, and the F2
+  reproduction now gets `writer_collected`; integrated as `236ca28`, writer
+  finished. The controller added the Podman case (`6ee7add`): with real
+  rootless Podman and the pinned Node image it passes, against the old source
+  it fails.
+- D1 (`code-mistral`, writer w1): collected as
+  `writer-pi-session-mcp-w1/docs/s12-reconcile`; split by issue into
+  `f5a9712`, `58e0e7b`, `17845ff` and `ebe3c52`. Controller edits: the
+  shadowing and re-read rule in the ADR 0013 amendment, and the relay wording
+  (a mismatch counts as `settingsChanged`; `writer_unavailable` with
+  `none_admitted` only when no writer is admitted). Writer finished.
+- R2 (`review-grok`, Grok 4.7, read-only): `NON_BLOCKING_ONLY`. Verified by
+  the controller and fixed in `1dfe4da`: a derived `-wip` or `-detached` name
+  that conflicts with an exported branch path aborted the export under
+  `set -eu` (reproduced with a branch `main-detached/topic`); a worker-made
+  `git replace --graft` made an unexported detached commit look reachable
+  (Grok's variant with a plain replacement did not reproduce, the graft did);
+  the reachability gate now also runs on `nothing_to_collect`. Recorded as
+  limits, not changed: an index-only staged change that the worktree reverted
+  (pre-existing; fixed later in
+  [#200](https://github.com/plagor44-ux/pi-session-mcp/issues/200), see
+  [Sprint 13](2026-10-30-s13-index-only-work.md)), a base name of 192 to 200 characters (fails closed), and a
+  runner that reports a fetch it did not do (outside the threat model).
+- Final integration review (Sonnet 5.5, read-only, on `896e29d`):
+  `NON_BLOCKING_ONLY`. Fixed: the in-boundary guard probe now ignores replace
+  refs too (`9426682`, with a test that fails without it), the BOM pattern is an
+  escape (`5d9f15b`), and execution modes names the pruned-base case of the
+  digest gate. Not changed: `inspectWork.head` stays optional because required
+  would break type-checked mocks outside this change.
+- Acceptance: see
+  [Sprint 12 candidate acceptance](../acceptance.md#sprint-12-candidate-acceptance-2026-10-30).
+  Level 1 green on `9426682`; Level 2 green on the packed `896e29d`; live items
+  B, C and D passed on expendable configurations and were rolled back; the
+  Level 3 ten-task cycle 2 passed (10 of 10) after cycle 1 failed on fixture and
+  harness design (5 of 10, kept unchanged).
+
+## Results
+
+| Finding | Status | Commits | Evidence |
+| --- | --- | --- | --- |
+| F1 #192 | fixed | `a0a7d87`, `79e8a7a`, `5d9f15b`; docs `f5a9712` | `test/read-only-context-files.test.ts` (fails on `9d9cf8c`), faux-provider context check, R1 and final review |
+| F2 #193 | fixed | `236ca28`, `6ee7add`, `1dfe4da`, `9426682`; docs `58e0e7b`, `896e29d` | real-Git collect tests, Podman test, guard test (each fails on the source before), R2 and final review |
+| F3 #194 | fixed | `230e60e`, `3e14279`; docs `17845ff` | `test/writer-relay.test.ts` drift tests (fail on `9d9cf8c`), live refusal with `settingsChanged`, R1 and final review |
+
+Remaining risk: #120 is unchanged. `npm audit --omit=dev` on 2026-10-29 still
+reports `undici` 8.10.2 (high) through `@earendil-works/pi-coding-agent` 1.4.0
+(moderate), eight advisories fixed in `undici` >= 8.12.2; the only offered fix
+is a semver-major downgrade. No override and no `npm audit fix --force`.
+
+Kept open: #79 (Sprint 8 steps 5 to 7 are not done), #120 and #144 (no macOS
+claim). The sandbox resource limits of ADR 0013 are the follow-up issue
+[#195](https://github.com/plagor44-ux/pi-session-mcp/issues/195), not part of
+this sprint.
+
+Cleanup: all controller Pi sessions closed; both `pi-session-mcp` writers
+finished (`writer_reset`); the test writer `s12-probe-w1` removed; expendable
+configurations, the synthetic repository, the pack prefix and the
+controller's worktrees removed.
+

package/docs/sprints/2026-10-30-s13-index-only-work.md

@@ -0,0 +1,199 @@
+# Sprint 13: work that exists only in the writer index
+
+Planning basis: main `7752d3f1555d19fed06f43c0e046da07017a3320` (merge of PR
+#197), published 0.14.1, 2026-10-30. Entry: issue
+[#200](https://github.com/plagor44-ux/pi-session-mcp/issues/200), recorded as
+an unchanged limit in [Sprint 12](2026-10-29-s12-audit-fixes.md), and the
+published-release Level 2 of 0.14.1 that was still open. This file records the
+work as it landed; it claims nothing that its progress log does not state with
+evidence.
+
+Branch: `fix/writer-index-only-work`, one pull request, no release. Merge,
+tag, npm publication and the productive rollout are maintainer decisions.
+
+## Preflight (2026-10-30)
+
+- main and `origin/main` at `7752d3f`; open issues #79, #120, #144, #195,
+  #198, #199, #200; open pull request #201 (#198, #199).
+- Both machines run `0.14.1`; on the workstation both client targets verified
+  and all 18 writers accepted earlier the same day.
+- Reproduced on `7752d3f` with the real-Git harness: for a clone whose HEAD and
+  worktree hold `base` and whose index holds a staged blob (`git status` `MM`),
+  `inspectWork` reported `baseline: true, dirty: false`, collect reported
+  `nothing_to_collect`, and remove and finish without `--discard` destroyed
+  the staged blob.
+
+## Decisions
+
+- Inspection computes the original index tree with `write-tree` on a second
+  temporary copy of the index, before `git add -A` builds the worktree tree.
+  The clone stays read-only and its index is never written.
+- `baseline` additionally requires the index tree to equal the base tree;
+  `dirty` is set when the index tree or the worktree tree differs from HEAD's.
+- The collection digest is computed over a version tag and the inspection
+  output, which now includes the index tree. A digest recorded by 0.14.1 or
+  earlier can never match, so it never authorizes cleanup.
+- Collection exports a staged tree that differs from both HEAD's tree and the
+  worktree tree as an extra `<branch>-index` commit, with the name rules of the
+  existing `-wip` export, rather than refusing: a refused writer could not be
+  admitted to a session or collected, so its work would only be recoverable by
+  `--discard`. The `-wip` and `-detached` exports are unchanged (#193).
+- A digest is recorded only when the index and worktree tree objects exist in
+  the operator checkout, in addition to the #193 commit gate.
+- An index that cannot be evaluated, such as an unmerged conflict, makes
+  inspection and collection fail closed (`writer_inspect_failed`,
+  `writer_collect_failed`); no cleanup without `--discard` proceeds.
+- Pool admission needs no change: the in-boundary guard probe runs
+  `git status --porcelain=v1 -uall`, which reports staged changes. Doctor's
+  `writer_dirty` stays an offline ref-only hint and never authorizes cleanup;
+  its documentation now says so.
+- #120: still waiting for an SDK release; no override, no
+  `npm audit fix --force`.
+
+## Roles and routing
+
+`pi_capabilities_get` on 2026-10-30 settles which requested models were
+available as profiles:
+
+| Requested | Profile used | Status |
+| --- | --- | --- |
+| GPT 6.1 Terra (implementation) | `code` (openai `gpt-6.1-sol`) | Terra has no profile: the installed 0.14.1 catalog does not see Pi's persisted model overlay (#199, fixed in #201, unreleased); the requested fallback Sol was used |
+| Sol (call-path analysis) | done by the controller | the call paths were short (one function and its five callers) |
+| DeepSeek (real-Git fixtures) | `code-deepseek` (`deepseek-flash`) | available |
+| GLM 5.3 (test plan, counter-checks) | `review-glm` (`zai-glm-5-3`) | available |
+| Grok 4.7 (adversarial review) | `review-glm` | not used: xAI requests fail with HTTP 402 since 2026-10-25 |
+| Mistral Large 4 (release evidence, docs) | controller with a Claude runner subagent | the evidence needed only local commands; the controller is the only docs editor |
+| Sonnet 5.5 (final integration review) | a read-only Claude Code subagent on `claude-sonnet-5-5` | used instead of `review-sonnet`, because a read-only Pi worker reads only the workspace on `main`, not the branch worktree |
+
+agy (Antigravity CLI, Gemini) was not used: the controller's planning call was
+declined in this session, so the controller planned the packages and the
+review route. At most two coding workers ran at once; `src/writer-lifecycle.ts`
+had one implementer, and `test/writer-collect-real-git.test.ts` one author.
+
+## Tasks
+
+| Id | Task | Route | Change area |
+| --- | --- | --- | --- |
+| P1 | Design counter-check and regression test plan | `review-glm` | none |
+| T1 | Fix in inspection, collection and the digest | `pi-session-mcp` writer, `code` | `src/writer-lifecycle.ts`, unit tests and fakes |
+| T2 | Real-Git regression matrix | `pi-session-mcp` writer, `code-deepseek` | `test/writer-collect-real-git.test.ts` |
+| R1 | Adversarial review of the integrated diff | `review-glm` | none |
+| R2 | Final integration review | Sonnet 5.5 subagent, read-only | none |
+| A | Published-release Level 2 of 0.14.1, candidate Level 1 and 2, native Podman | controller, runner subagent | records |
+
+## Progress log
+
+- P1 (`review-glm`, 1m32s): `NON_BLOCKING_ONLY`. Its main finding, that
+  `write-tree` fails on intent-to-add entries, did not reproduce: Git 2.56
+  skips such entries, so the case shows as dirty through the worktree tree. It
+  is now pinned by a test. Skip-worktree and assume-unchanged entries stay
+  invisible, as for Git itself (recorded as a limit).
+- T1 (`code`, writer w1, 4m56s): `DONE_WITH_CONCERNS`; the concerns were the
+  ten known lock, hook and live-token timeouts of the container suite
+  (`override-lock`, `skill-customize-concurrency`, `token-live`,
+  `wake-hook`). Collected as `writer-pi-session-mcp-w1/fix/200-index-only-work`
+  and integrated as `9b5c72c`; writer finished (`writer_reset`).
+- T2 (`code-deepseek`, writer w2, 5m00s): `DONE`, 7 of its 10 new tests fail on
+  the base for the bug, 3 are guards. Collected as
+  `writer-pi-session-mcp-w2/test/200-index-only-real-git` and integrated as
+  `4acb4bf`; writer finished (`writer_reset`).
+- Controller: against the source of `7752d3f` the real-Git file reports 7
+  failed and 13 passed; with the fix, 21 of 21 pass. Added the intent-to-add
+  test (`1aff988`) and a native Podman case of the exact `MM` state
+  (`1e1e694`), which fails on the base source (`baseline: true`) and passes
+  with the fix in the real container.
+- R1 (`review-glm`, 4m59s, on the integrated diff): `NON_BLOCKING_ONLY`, no
+  finding in the new lines.
+  - Confirmed and filed as
+    [#202](https://github.com/plagor44-ux/pi-session-mcp/issues/202): a stash
+    entry is not exported, yet collection records a digest and remove without
+    `--discard` then deletes it; reproduced by the controller with the real-Git
+    harness (`nothing_to_collect`, `writer_removed`, blob absent). Pre-existing.
+  - Not reproduced: an alias that shadows a builtin Git command; Git ignores
+    such aliases. A clean filter configured by the worker runs only inside the
+    throwaway boundary container, and the worker can already destroy its own
+    clone, so it adds no loss beyond the threat model.
+  - Fail closed, recorded as limits: a clone configured for a split index makes
+    `add -A` fail on the read-only clone; a worker branch named
+    `<branch>-index` makes the export refuse with `ref_name_refused`.
+- R2 (Sonnet 5.5, read-only, on the whole branch at `4670264`):
+  `NON_BLOCKING_ONLY`, no code defect. Fixed by the controller:
+  - The test for an index-only change after a collection also changed the
+    worktree, so it did not pin that the digest covers the index tree. It now
+    stages a second blob with `update-index --cacheinfo` and leaves the
+    worktree unchanged; with a digest that omits the index line it fails, with
+    the fix it passes.
+  - A test for a taken and a path-conflicting `<branch>-index` name.
+  - The code table in execution modes, the `pi-session-profiles` skill (Doctor
+    and the `--collect` dry run do not prove a clone clean; `--remove` without
+    `--discard` does), the unmerged-index consequence, the merge note and a
+    wrong direction in the acceptance record.
+  - Not changed: the verbatim issue reproduction stays as written although the
+    stricter collect, finish and remove test covers more; Doctor's
+    `writer_dirty` stays a documented offline ref-only hint (a maintainer
+    call against the issue's criterion 3).
+
+## Checks
+
+- Full suite on `1aff988` (the integrated fix and the intent-to-add test),
+  with `NODE_OPTIONS=--unhandled-rejections=strict`: 141 files, 4061 passed,
+  14 skipped, exit 0.
+- Native Podman tests: `test/writer-lifecycle.podman.test.ts` 8 of 8 and
+  `test/writer-boundary.podman.test.ts` 1 of 1, none skipped, on `1e1e694`.
+- Candidate Level 1, working-tree and packed-tarball Level 2 on `1e1e694`: see
+  [Issue #200 candidate acceptance](../acceptance.md#issue-200-candidate-acceptance-2026-10-30).
+- Published-release Level 2 of 0.14.1: see
+  [v0.14.1 post-release evidence](../acceptance.md#v0141-post-release-evidence).
+
+## Remaining risk and limits
+
+- Work held only in a stash entry or in refs outside `refs/heads` is still lost
+  after a collection (#202).
+- Skip-worktree and assume-unchanged entries hide worktree changes from Git and
+  therefore from inspection.
+- The digest version means that a writer collected under 0.14.1 but not yet
+  reset must be collected once more before finish, reset or remove. Writers at
+  their baseline need no digest and are unaffected.
+- The 18 workstation writers removed on 2026-10-30 for a profile change were
+  judged by the 0.14.1 inspection; whether any of them held index-only work
+  cannot be established afterwards.
+- #120 is unchanged: Pi SDK 1.4.0 is still the newest release and pins `undici`
+  8.10.2.
+
+## Rollout plan (maintainer decision)
+
+After the maintainer has merged and published a release with this change:
+
+1. Close the coding sessions on all writers. For every writer that is not at
+   its baseline, run `pi-session-mcp-setup --writer <name> --collect` as a dry
+   run and resolve uncollected work before anything else.
+2. Upgrade each machine as [Installation](../installation.md#container-writers)
+   describes: client targets `--remove`, `npm install -g pi-session-mcp@<new>`,
+   then for every container repository the provisioning command with its full
+   settings and `--apply`, then client targets `--apply` and `--verify`,
+   `--writer <name> --verify` for every writer, and Doctor.
+3. Collect every writer that holds collected but not yet reset work once more,
+   because its 0.14.1 digest no longer authorizes cleanup.
+4. Second machine: the Anthropic profiles still need the maintainer's login
+   there. Until #198 (in #201) is released, removing a writer with
+   `--cache go` needs the documented `chmod -R u+w` workaround.
+
+Rollback: a productive installation is not downgraded without the maintainer.
+If the maintainer decides to return to `0.14.1`, the same steps install it; a
+digest recorded by the new version does not match `0.14.1` either, so such a
+writer has to be collected again, which fails safe. The source change itself is
+reverted by reverting its commits.
+
+Merge order with #201: both change `src/writer-lifecycle.ts` (#201 replaces the
+recursive removal in `removeWriter`), `CHANGELOG.md` (`Unreleased`) and
+`docs/execution-modes.md`, and #201's `test/writer-models-store.test.ts` fakes
+the old three-tree inspection output. #201 merged first; the merge of `main`
+into this branch keeps both `Unreleased` entries and adds the index tree line
+to that fake.
+
+Unmerged index: a writer whose index holds a merge conflict can no longer be
+collected, and pool admission refuses it because it is not at its baseline; its
+work stays in the clone until the operator explicitly decides on `--discard`.
+Before this change `git add -A` collected such a state as `-wip` with conflict
+markers. Exporting the worktree in that case without recording a digest would
+keep it recoverable; that is a possible follow-up, not part of this change.

package/docs/threat-model.md

@@ -16,7 +16,16 @@ Pi Session MCP trusts the local process that launches and speaks MCP over inheri
   (arguments the SDK would rewrite, such as a leading `@` or `~`, a `file:`
   URL, Unicode spaces or NUL, are refused so both resolve the same path), and
   the `*Operations` hooks of `read`, `grep` and `ls` check the absolute path
-  again. `rg` and `fd` do not follow symlinks during traversal. A profile with
+  again. `rg` and `fd` do not follow symlinks during traversal. For read-only
+  profiles the resource loader likewise keeps only Pi context files
+  (`AGENTS.override.md`, `AGENTS.md`, `AGENTS.MD`, `CLAUDE.md`, `CLAUDE.MD`)
+  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, while the linked worktree's own file inside the
+  workspace is. Coding profiles keep the SDK behaviour (the working directory
+  and its ancestors). A profile with
   `shell: "sandboxed"` also gets `bash`, run as `/usr/bin/bwrap` (fixed path,
   root-owned and not group- or world-writable, no `PATH` lookup) with
   `--unshare-all`, `--disable-userns`, a cleared environment, no network, `/usr`

package/docs/tool-contracts.md

@@ -40,7 +40,7 @@ records name the package version and the build they ran on, see
 ```json
 {
   "ok": true,
-  "server": { "name": "pi-session-mcp", "version": "0.14.0" },
+  "server": { "name": "pi-session-mcp", "version": "0.14.2" },
   "configuration": {
     "fingerprint": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
     "reloadPolicy": "restart-required"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-session-mcp",
-  "version": "0.14.0",
+  "version": "0.14.2",
   "description": "Local stdio MCP server for controlled Pi coding-agent sessions",
   "license": "MIT",
   "keywords": [

package/skills/pi-session-orchestration/SKILL.md

@@ -122,7 +122,7 @@ You integrate. Workers never integrate each other's changes. Resolve conflicts b
 
 After taking over the result and closing its coding session, before the next task:
 
-1. Run `pi-session-mcp-setup --writer <name> --collect --apply` from the operator environment. Review the collected refs in the operator's checkout: `refs/remotes/writer-<name>/<branch>`, with uncommitted work as `<branch>-wip`. They are untrusted until reviewed. Integrate only verified work yourself.
+1. Run `pi-session-mcp-setup --writer <name> --collect --apply` from the operator environment. Review the collected refs in the operator's checkout: `refs/remotes/writer-<name>/<branch>`, with uncommitted work as `<branch>-wip`, staged work that differs from both HEAD and the worktree as `<branch>-index`, a clean detached HEAD as `<base>-detached`, and each stash entry as `<base>-stash-<n>`. They are untrusted until reviewed. Integrate only verified work yourself.
 2. Run `pi-session-mcp-setup --writer <name> --finish --apply`. It collects again, then resets a persistent writer or recreates an ephemeral writer. Do not reuse it until this succeeds. A refused branch name makes collection incomplete and finish stops: ask the operator to resolve it by renaming inside the boundary or explicitly discarding with `--reset --discard --apply`. Finish returns it to the workspace default base. No reconnect is needed after reset, finish or recreate. A setup operation on a writer held by a session fails with `writer_busy` after a short wait; close the session and allow launcher cleanup to finish.
 3. A coding start needs the writer's clone at its baseline, even after a complete collection; otherwise it fails with the controller-action code for uncollected work in [references/start-errors.md](references/start-errors.md). To let a fresh session continue from collected work, for example after a failed turn or for a review fix round, create a local branch at the collected ref and run `pi-session-mcp-setup --writer <name> --reset --base <branch> --apply`, then call `pi_session_start` on `pi-session-mcp` with the coding profile and `base: "<branch>"`. Read `writer` from that result for collection. Default starts cannot use a writer moved to the fix branch.
 4. Never run Git inside the writer's clone as the host user, including direct fetch from that clone. Use setup's bundle collection and inspect the imported refs in your own checkout. Never discard unreviewed work just to admit the next task.

package/skills/pi-session-profiles/SKILL.md

@@ -84,8 +84,12 @@ For each container repository whose selected profiles or settings change,
 determine every writer's state using the documented read-only checks:
 Doctor's `writer_dirty` and `writer_uncollected_bundle`, and
 `pi-session-mcp-setup --writer <name> --collect` (dry run).
+Neither proves a clone clean: Doctor reads only `HEAD` and refs, and the dry
+run inspects nothing. The authoritative check is `--remove` without
+`--discard`, which inspects the clone, including its index, and refuses with
+`writer_uncollected` when it holds work.
 If a writer to remove or re-provision has uncollected work or a dirty clone,
-stop and ask before anything goes live. Never run `--collect --apply` in this
+or `--remove` refuses, stop and ask before anything goes live. Never run `--collect --apply` in this
 workflow, and never discard work to get past a refusal.
 
 Stop and report `writer_busy`, `podman_unavailable`, `registration_divergent`