pi-session-mcp 0.8.1 → 0.8.3

package/docs/reviews/2026-10-13-post-0.8.1-audit.md

@@ -0,0 +1,393 @@
+# Post-0.8.1 audit and backlog snapshot
+
+Snapshot date: 2026-10-13. Reviewed source:
+[`e462054a37505ef00e1e0c549ebab27e4db7ef55`](https://github.com/plagor44-ux/pi-session-mcp/commit/e462054a37505ef00e1e0c549ebab27e4db7ef55).
+Documentation tracking: [#57](https://github.com/plagor44-ux/pi-session-mcp/issues/57).
+
+PR #55 delivered useful stabilization and its final native CI passes. This
+review nevertheless reproduced an additional, bounded data-preservation defect
+in skill recovery and confirmed the diagnostic classification in issue #56.
+Fix these first, then complete the missing acceptance. The evidence does not
+justify a general new feature phase.
+
+This is an English preservation of the review and plan produced on 2026-10-13.
+The observations below belong to the reviewed source, not to future fixes.
+Proposed tasks are separate from verified facts. Creating this record does not
+fix either defect or complete any acceptance. The shorter execution index is
+the [roadmap](../roadmap.md).
+
+## Repository and source bindings
+
+`plagor44-ux/pi-control` is archived, with no open issues or pull requests at
+the snapshot. Its final PR is
+[#79](https://github.com/plagor44-ux/pi-control/pull/79), main `a64a5b8`.
+Its issues #31, #32 and #41 were closed as `not_planned`, not implemented.
+The [closing comment on #41](https://github.com/plagor44-ux/pi-control/issues/41#issuecomment-6037099724)
+explicitly names Pi Session MCP as the successor. Other software projects are
+outside this review.
+
+| Subject | Observed state |
+| --- | --- |
+| Main | `e462054a37505ef00e1e0c549ebab27e4db7ef55` |
+| Latest PR | [#55](https://github.com/plagor44-ux/pi-session-mcp/pull/55), merged 2026-10-12 at 21:15 UTC; final head `440f2e4ccb4f7cebd88825abd8515218f4bbbdee` |
+| Release | [v0.8.1](https://github.com/plagor44-ux/pi-session-mcp/releases/tag/v0.8.1), published 2026-10-12 at 22:06 UTC, or 2026-10-13 at 00:06 Europe/Berlin |
+| Open issues during review | One: [#56](https://github.com/plagor44-ux/pi-session-mcp/issues/56) |
+| Open PRs during review | None |
+| Final PR CI | [38309093300](https://github.com/plagor44-ux/pi-session-mcp/actions/runs/38309093300), Linux, macOS 15, macOS 26 and the aggregate check passed |
+| Main CI | [38309519719](https://github.com/plagor44-ux/pi-session-mcp/actions/runs/38309519719), passed |
+| Tag CI | [38309738675](https://github.com/plagor44-ux/pi-session-mcp/actions/runs/38309738675), passed |
+| SDK canary | [38247575455](https://github.com/plagor44-ux/pi-session-mcp/actions/runs/38247575455), passed on `de46896`, before #55 |
+| Dependencies | Package 0.8.1, Pi SDK 1.1.0, MCP client/server 2.3.1; direct dependencies exactly pinned |
+
+Open issue and PR collections, repository paths, [AGENTS.md](../../AGENTS.md),
+all seven ADRs, both implementation plans, acceptance, releasing, skills,
+setup design, threat model, CI and the changed runtime files and relevant
+tests were inspected. Main and the open issue collection were rechecked
+before delivery; main remained `e462054` and #56 remained the only open issue.
+The subsequent documentation issue #57 is not part of that earlier snapshot.
+Refresh main, issues, PRs and affected sources before implementation.
+
+## Findings
+
+### F1: recovery deletes operator changes in the transaction's trash
+
+Severity: medium correctness/data-preservation defect. Work priority: P1.
+The reproduced case needs an interrupted local skill update and subsequent
+operator changes to its intermediate directory. It does not establish remote
+reachability or general deletion of workspace files.
+
+In [src/setup-skills.ts](../../src/setup-skills.ts), `recover()` at reviewed
+lines 313–320 checks `.trash` only with `collectPlain()`: directory structure,
+regular file types, hidden entries and tree limits. An additional regular file
+passes this check; `discardTrash()` then removes it. A transaction-shaped
+directory name does not prove that its current contents remain setup's own.
+
+The isolated reproduction used the built modules from the reviewed source,
+a temporary synthetic package, home and project, and `MemoryOwnershipStore`:
+
+1. Install a synthetic v1 controller skill.
+2. Provide a synthetic v2 override.
+3. Throw at the existing `trash-renamed` checkpoint during the update. This
+   leaves the actual pending record and intermediate directory. It simulates
+   an interruption; it is not evidence of a real operating-system crash.
+4. Add a regular `operator-notes.txt` with synthetic operator content inside
+   that `.trash` directory.
+5. In separate fresh fixtures, run `apply`, `remove` and `rollback`.
+
+| Operation | Reported code | Operator file retained |
+| --- | --- | --- |
+| apply | skill_recovered | No |
+| remove | skill_removed | No |
+| rollback | skill_removed | No |
+
+The [skills guide](../skills.md) and [setup lifecycle design](../client-setup-design.md)
+also promise to retain modified or foreign intermediates. Existing recovery
+tests cover modified backups and staging trees, plus trash with links or
+hidden entries. The regular foreign-trash-file counterexample is missing.
+
+Smallest proposed correction: delete a complete trash tree only after proving
+it equals the replaced tree. Retain a partial or otherwise unprovable tree
+with `skill_recovery_retained`. Continuing a partial deletion is not a reason
+to risk operator files. If automatic partial recovery requires additional
+durable evidence, deliver the conservative behavior first and decide that
+extra scope separately. Do not introduce a broad journal abstraction as
+incidental work. Align partial-trash expectations and documentation with the
+actual preservation guarantee; do not weaken the counterexample.
+
+At the audit snapshot this finding had no GitHub implementation issue.
+Duplicate-check and create a focused issue before implementing R01.
+
+### F2: verify misclassifies client and inspection failures
+
+Severity: low diagnostic defect. Work priority: P2. Existing tracker:
+[#56](https://github.com/plagor44-ux/pi-session-mcp/issues/56).
+
+In [src/setup.ts](../../src/setup.ts), `verify()` at reviewed lines 146–149
+reduces the inspection to an `equivalent` boolean. Both `unsupported` and an
+inspection exception become `registration_not_equivalent`.
+
+An isolated synthetic-adapter reproduction confirmed:
+
+| Inspection | dry-run | verify |
+| --- | --- | --- |
+| unsupported | unsupported | registration_not_equivalent |
+| exception | inspect_failed | registration_not_equivalent |
+| absent | absent | registration_not_equivalent |
+| divergent | divergent | registration_not_equivalent |
+
+The production wrapper returns `unsupported` when client discovery fails.
+The actual missing-PATH-client reproduction is reported in #56. This review
+executed the orchestrator counterexample, not a real client installation.
+
+Smallest proposed correction: preserve existing `unsupported` and
+`inspect_failed` codes; reserve `registration_not_equivalent` for a genuinely
+absent or divergent registration. A new `client_unavailable` code is not
+necessary. Neither failure may start a mutation or MCP handshake. Preserve
+Doctor, ownership and release-binding precedence, and check human/JSON output,
+exit status, documentation and negative Level-2 cases.
+
+## Review and CI limits
+
+[CI 38307240366](https://github.com/plagor44-ux/pi-session-mcp/actions/runs/38307240366)
+failed on both macOS jobs at the earlier `183d53c` head; Linux passed.
+`f048144` made Linux-only harness checks platform-explicit and `0c7bad3`
+named the platform in lock fail-closed cases. The final head passes the full
+matrix. There is no still-failing final PR check in this observation.
+
+GitHub returned no formal review submissions and no inline review threads
+for #55. The [Codex security comment](https://github.com/plagor44-ux/pi-session-mcp/pull/55#issuecomment-6132442390)
+names `183d53c`, a P0 threshold and no merge gate. It does not approve the
+complete final head. The PR description reports independent local reviews;
+their reports were not separately available to this review. Green CI and the
+security summary do not exclude F1.
+
+## Checks actually executed by the review
+
+Unmodified checkout `e462054`; Linux container, Node.js 24.19.0. No real
+client registrations, models or providers were used. The review itself did
+not modify repository files, create commits/issues/PRs or publish a release.
+The later documentation-preservation change is separate.
+
+| Check | Result |
+| --- | --- |
+| npm ci | Exit 0 |
+| npm run typecheck | Exit 0 |
+| npm run build:cli | Exit 0 |
+| NODE_OPTIONS=--unhandled-rejections=strict npm test | Exit 1: 41 files passed, 9 failed; 983 tests passed, 52 failed, 6 skipped; 4 unhandled errors |
+| npm run build | Executed separately, exit 0 |
+| npm audit | Exit 0; no vulnerabilities at the time of the query |
+| git diff --check | Exit 0 |
+| git status --short | Empty |
+| Recovery reproduction | F1 confirmed for all three operations |
+| Verify reproduction | F2 confirmed for unsupported and inspection exception |
+| Isolated existing process-table test | createProcessTable().readable() failed in this environment |
+
+Failures concentrate on process groups, `/proc`, kernel locks, the guardian
+and dependent crash/harness tests. Direct probes gave inconsistent process
+visibility. The precise cause is unresolved. The isolated process test,
+`src/setup-platform.ts`, `src/setup-process.ts` and `test/process-fixture.ts`
+are unchanged from the PR base. This argues against attributing all 52
+failures to #55 but does not establish the cause of each failure. Do not
+claim a green local acceptance or turn all failures into new product bugs.
+A complete run on a supported native runner remains a gate.
+
+## Complete clustered remainder
+
+P1 means first or a gate for dependent usage. P2 is bounded follow-up work.
+P3 needs concrete demand. **R01–R23 are roadmap identifiers, not GitHub issue
+numbers.** Only #56 was already an open issue during the audit; other rows are
+findings, evidence gaps or proposed maintenance tasks.
+
+### A: correctness and local operation
+
+| ID | Priority | Remainder | Deliverable |
+| --- | --- | --- | --- |
+| R01 | P1 | F1 modified-trash data loss | Focused issue and conservative fix; regular foreign file, modified existing content, complete own trash and partial trash counterexamples for apply/remove/rollback |
+| R02 | P2 | F2 / #56 verify classification | Preserve existing codes; negative cases without mutation or handshake |
+| R03 | P1 gate | Local full suite failed | Reproduce on native Linux; distinguish product defects from container prerequisites without retries or weaker process proofs |
+| R04 | P2 | Non-exhaustive start-error list in the orchestration skill | Classify current public start codes as operator-needed, transient or unknown; never classify provider free text |
+
+### B: evidence and orchestration
+
+| ID | Priority | Remainder | Deliverable |
+| --- | --- | --- | --- |
+| R05 | P1 | No full ten-task Level-3 cycle on Pi SDK 1.x | One frozen build, both controllers, five tasks each, independent snapshots/oracles; preserve failed attempts |
+| R06 | P1 gate | Final supplementary Codex abort run violated scope | Offer handshake only where needed or make it unambiguously task-bound; new run with unchanged strict scope oracles, not a wider allowed-file set |
+| R07 | P2 | No live discovery of the setup-installed Codex home skill | Real discovery of a regular setup-installed copy in an isolated client home; verified revision, no required manual symlink |
+| R08 | P2 | Third concurrent worker and read-only reviewer unproven live | After two-worker acceptance, two writers in separate worktrees plus a reviewer of a frozen result; scope, association, neighbor abort and close |
+| R09 | P2 | Current multi-session live evidence covers Cursor workers only | Level 3 for the normal/local Pi profile actually intended for use; do not transfer Cursor evidence to other providers |
+| R10 | P2 | Current macOS Level-2 path not fully accepted on real hardware | 0.8.x with both clients in isolated homes; prior Claude Code evidence does not automatically cover new skill locks/recovery, and Codex was already pending |
+| R11 | P2 conditional | macOS live use beyond CI | Small real-Mac read-only smoke when needed; heavy suites and parallel inference on suitable Linux hardware |
+| R12 | P3 | Real skill-update crash, customization contention and harness-analysis signal runs absent | Add only targeted evidence when operating experience warrants it; existing provider-free tests are not renamed as live evidence |
+
+Two-session operation already has real evidence: Claude Code passed parallel
+and abort; Codex passed parallel. The final Codex abort run failed only
+`range:changes`, because a Cursor worker applied the handshake skill to an
+unrequested file. Abort, neighbor behavior and cleanup passed. This is a
+task/worker outcome, not a demonstrated session-control defect. More than two
+sessions are not documented as technically impossible; their live proof is
+missing.
+
+### C: acceptance and release evidence quality
+
+| ID | Priority | Remainder | Deliverable |
+| --- | --- | --- | --- |
+| R13 | P2 | Runs bind extension name/version, not package contents | Fingerprint effectively loaded extension trees before/after a run; changed contents invalidate acceptance; no published raw paths |
+| R14 | P2 | Additional Codex skill sources are not bound | Bind actually active CODEX_HOME/system skill sources or demonstrably exclude them; prerequisite for R07 |
+| R15 | P3 | Unreadable client start time immediately after spawn leaves no sighting | Explicit failed/unverified evidence; never infer cleanup from an absent observation |
+| R16 | P2 | Strict unhandled rejections are not explicit in CI | Align the current CI test environment with the local strict command; no broad new matrix |
+| R17 | P3 | npm audit is manual only | Keep the manual release gate; consider one small scheduled advisory check only after further demonstrated drift, in its own issue |
+| R18 | P3 | npm publication has no provenance attestation | Consider Trusted Publishing/provenance as a separate supply-chain decision if external use makes it relevant; not a blocker for bounded local dogfooding |
+
+The latest observed canary predates #55. A current-source canary can add
+maintenance evidence, but cannot replace native full-suite or live acceptance.
+It does not authorize an SDK upgrade.
+
+### D: documentation and planning
+
+| ID | Priority | Remainder | Deliverable |
+| --- | --- | --- | --- |
+| R19 | P2 | v0.8.1 post-release evidence exists only in release notes | Carry it into acceptance with the next change PR, as #55 explicitly planned; do not describe this as a forgotten release operation |
+| R20 | P2 | Historical macOS/extension plans retain unchecked steps | Mark delivered/superseded work with PR references; do not reimplement it |
+| R21 | P2 | No consolidated active roadmap in the successor | Short English docs/roadmap.md with actual remainder, sources and gates, under a focused issue |
+| R22 | P2 | ChatGPT project instructions still describe the former repository/release sequence | Update successor, SDK, macOS, extensions/skills and current ADR ordering; do not reuse v0.3.0 or old #11–#14 as active priorities |
+| R23 | P3 | Acceptance/versioning wording can be misunderstood | Distinguish targeted two-session evidence from full Level 3; clarify MCP-contract versus setup-report versioning |
+
+R21 is the documentation created alongside this snapshot. The other rows do
+not become complete merely because they are recorded here.
+
+### E: deliberately deferred decisions
+
+| Topic | State | Entry condition / smallest useful test |
+| --- | --- | --- |
+| OS/process isolation | ADR 0003; decide before real writable workspaces | Non-disposable repositories or untrusted coding content: separate architecture/threat-model issue; synthetic isolated write test |
+| pi_turn_wait | No implementation now | Routinely more than about five polls per turn with pauses, or demonstrated tool/approval cost. The reported 5–7 polls per invocation do not establish the trigger |
+| Persistence/resume | No demonstrated current need | Actual loss of useful work after restart; otherwise ephemeral sessions |
+| HTTP/remote/mobile | No approved need | Concrete case SSH/existing remote development cannot satisfy; separate ADR/security decision |
+| Finer turn_failed | Upstream-dependent | Closed public final SDK cause discriminator after retry/compaction, with positive and negative cases; no regex on raw errors |
+| Multi-user, UI, credential management | Outside product scope | Separate justified product goal and ADR |
+| Former pi-control #31/#32 | Closed as not_planned | No automatic reopening/migration; a current project-specific need requires separate scope |
+| Former release gates and #11–#14 | Historical | Do not repeat delivered historical gates; acceptance must bind the current build |
+
+## Plan and ADR reconciliation
+
+| Source | Delivered state | Actual remainder |
+| --- | --- | --- |
+| [macOS plan, 2026-10-10](../superpowers/plans/2026-10-10-macos-setup.md), tasks 1–8 | Platform, runner/guardian, ownership, tests, EOF, CI and docs delivered by #33; #32 closed | Real Codex Mac acceptance, current 0.8.x skill paths, plan checkbox status |
+| [Extension plan, 2026-10-11](../superpowers/plans/2026-10-11-pi-extensions.md), tasks 1–9 | Configuration, resolution, Doctor, stdout guard, prompt source, runtime, contracts and governance delivered by #35/#37/#44; #34 closed | Plan status and current follow-ups; no duplicate implementation |
+| Extension plan, task 10 | Cursor live path documented in acceptance and #55, including Claude Code parallel/abort | Controller/platform limits in cluster B |
+| [ADR 0001](../adr/0001-stdio-first.md) | Local stdio, one trusted peer | No transport project |
+| [ADR 0002](../adr/0002-embedded-pi-sdk.md) | Public embedded APIs, no OS isolation | Read later approved ADR 0006/0007 expansions together |
+| [ADR 0003](../adr/0003-post-mvp-maintenance.md) | Maintenance, no general feature phase | Evaluate revisit triggers using current measurements only |
+| [ADR 0004](../adr/0004-client-contract-not-version.md) | Client contract rather than exact client-version allowlist | Fix #56; do not reinstate the old allowlist |
+| [ADR 0005](../adr/0005-macos-setup-platform.md) | macOS with the same fence guarantee | Current native acceptance |
+| [ADR 0006](../adr/0006-pi-extension-allowlist.md) | Exact locally installed profile extensions | Runtime/content evidence; no automatic install |
+| [ADR 0007](../adr/0007-profile-skill-selection.md) | Operator catalog, profile-selected skills, setup-installed controller skill | F1 and actual discovery; skills neither grant rights nor guarantee task success |
+
+## Four gated sprints
+
+Dates are a proposal from 2026-10-13, not a capacity commitment. A delayed gate
+shifts dependent work; independent documentation and Mac setup checks may
+continue. Each coding task needs a focused issue first.
+
+### Sprint 1: stability and correct diagnostics
+
+Proposed window: October 13–14, one or two implementation sessions plus native
+verification. Scope: R01, R02, R03, R19 and directly affected documentation.
+
+Create the missing R01 issue after a duplicate check. Claude Code locally
+integrates. Recovery and #56 can run in separate worktrees with read-only
+review/documentation work in parallel. Run the heavy full suite only after
+integration; do not overlap full suites on a small host.
+
+- Recovery owns `src/setup-skills.ts` and dedicated recovery counterexamples.
+- #56 owns `src/setup.ts` and targeted lifecycle/verify tests.
+- The integrator owns shared docs, changelog, acceptance and version fields.
+
+Exit gate:
+- Modified regular trash contents remain intact under apply/remove/rollback.
+- Complete own intermediates are handled correctly; unprovable partial trees
+  remain with a stable report code.
+- Missing clients report unsupported and inspection exceptions inspect_failed;
+  neither runs a registration mutation or handshake.
+- Doctor, release-binding and ownership precedence remain intact.
+- Native Level 1 has no unhandled rejections; the final head passes the full
+  Linux/macOS matrix and independent code review.
+- Level 2 remains green on actually checked targets; new negative cases are
+  recorded separately.
+
+Delivery: one consolidated maintenance PR with separate issue commits.
+0.8.2 is a possible patch candidate if the MCP contract is unchanged. The
+version and pre-release evidence belong in that change PR under the current
+release procedure. Merge/tag/publish remain a separate maintainer gate, not
+an action performed by this plan. Do not approve if F1 remains or native
+Level 1 fails.
+
+### Sprint 2: make acceptance traceable
+
+Proposed window: October 15–16, one or two sessions after Sprint 1. Scope:
+R04, R13, R14, R16 and R19–R23 where narrowly justified. Include R15 only if a
+counterexample establishes a material proof gap.
+
+Bind effectively loaded extensions and active skill sources; do not silently
+ignore unknown sources. Offer the handshake only where its task needs it.
+Keep original strict scope oracles. Reconcile historical plans with delivered
+PRs, maintain a short English roadmap and preserve post-release evidence.
+Align strict CI. Check the current-source canary on a frozen candidate without
+moving the SDK pin.
+
+Harness evidence, controller-skill failure policy and documentation can run in
+separate worktrees. One owner edits the central harness; the integrator owns
+shared acceptance documentation.
+
+Exit gate: changing a bound skill/extension after preparation invalidates a
+run; installed versus linked skills are distinguishable; original failed
+attempts remain recorded; every remainder has an issue or explicit entry
+condition. No new runtime feature phase.
+
+### Sprint 3: accept real usage
+
+Proposed window: October 17–20, two or three bounded acceptance sessions, not
+a broad implementation package. Scope: R05–R11. Requires Sprint 1 and the
+Sprint-2 evidence bindings before the runs that depend on them.
+
+Start on Linux with the full Level-3 matrix for both controllers at the same
+frozen build. Select a normal/local Pi profile actually intended for use;
+record the loaded model before/after every run and never force a model switch
+on shared inference. Use synthetic coding fixtures only. Pre-register tests,
+allowed files, snapshots and oracles. A scope failure remains a failed task.
+
+Then run targeted parallel/abort scenarios for both controllers with the
+appropriate Cursor profile. A fresh Codex abort must pass scope too.
+Only afterwards try one small extension to two writers in separate alias
+worktrees and a read-only reviewer of a frozen result. Do not begin with a
+large worker matrix.
+
+In parallel, the Mac runs only current Level 2 for both clients and a short
+read-only smoke. Keep heavy suites and parallel large inference off a
+resource-constrained work Mac. If a client is unavailable, retain that gate
+and deliver independent Linux work.
+
+Exit gate: meet the existing Level-3 criteria, including at least 8/10
+intended outcomes without a server defect **and** every required scope,
+security and cleanup condition, both client lifecycles, useful follow-ups
+and verified coding. Target 10/10; the 8/10 rule never hides unauthorized
+changes. Codex abort scope passes; setup's installed Codex copy is actually
+read; read-only fixtures remain byte-identical; all sessions close with no
+residual processes or structural leaks. Usage claims cover only tested
+profiles, clients, platforms and concurrency.
+
+### Sprint 4: decide the next investment from usage
+
+Proposed window: October 21–23, one short evaluation. No feature implementation
+without a separate justified decision.
+
+Evaluate failures/causes, scope violations, polls per turn with real pauses,
+task duration, cleanup, actual restart costs and planned non-disposable coding
+workspaces. Route R12/R15/R17/R18 into one concrete follow-up or the deferred
+list according to need.
+
+If real writing is next, isolation is the first architecture question. If only
+polling is costly, examine the smallest bounded-wait proposal. If no trigger
+fired, continue maintenance. Persistence and remote access need their own
+evidence. The strongest argument against expansion is the security and
+maintenance surface it adds to a deliberately small local server.
+
+Exit gate: documented decision, at most one next investment, a focused issue
+and an appropriate ADR for scope/contract changes. No automatic roadmap to
+1.0 or general release authorization.
+
+## Dependencies
+
+```mermaid
+flowchart TD
+  S1["S1: Recovery and verify fixes"] --> G["Native QA and final review pass"]
+  G --> S2["S2: Bind harness evidence"]
+  G --> M["Current macOS Level 2"]
+  S2 --> S3["S3: Linux Level 3 and multi-session acceptance"]
+  M --> S4["S4: Usage boundary and next investment"]
+  S3 --> S4
+```
+
+The next implementation session is Sprint 1: R01 plus #56 are the smallest
+evidence-backed development step. A published tag alone is not its exit gate.

package/docs/roadmap.md

@@ -0,0 +1,140 @@
+# Maintenance roadmap
+
+Planning basis: main `e462054a37505ef00e1e0c549ebab27e4db7ef55`, 2026-10-13.
+Tracking: [#57](https://github.com/plagor44-ux/pi-session-mcp/issues/57).
+The complete [audit and clustered backlog](reviews/2026-10-13-post-0.8.1-audit.md)
+preserves source bindings, reproductions, checks and all R01–R23 items.
+
+PR #55 and v0.8.1 have green final native CI, but the review reproduced a
+skill-recovery data-preservation defect and confirmed #56's verify diagnosis.
+Both were fixed in Sprint 1; real acceptance follows. Recording tasks does not
+mean they are implemented or that their gates passed.
+
+## Current state
+
+Updated 2026-10-15. Base main `bdfb95de9a46defa64d2eb382d58d454f97fc8fb`
+(the merge of the 0.8.2 release).
+
+- R21 (this roadmap) was delivered as documentation by
+  [#58](https://github.com/plagor44-ux/pi-session-mcp/pull/58), which closed
+  [#57](https://github.com/plagor44-ux/pi-session-mcp/issues/57).
+- Sprint 1 is closed: [#61](https://github.com/plagor44-ux/pi-session-mcp/pull/61),
+  merged as `b145f8c`, closed #59 (R01) and #56 (R02). See the
+  [Sprint 1 file](sprints/2026-10-13-s1-correctness.md#closure).
+- Sprint 2 is closed: [#69](https://github.com/plagor44-ux/pi-session-mcp/pull/69)
+  was merged on 2026-10-13 as `0aae639`, after its final-head CI passed on
+  Linux, macOS 15 and macOS 26. It closed #60, #62, #63, #64, #65, #66, #67
+  and #68 as completed. See the [Sprint 2 file](sprints/2026-10-13-s2-evidence.md).
+  The main CI run on the merge commit then failed on `macos-15` in one harness
+  test that timed out on the slow runner; the tree is identical to the green
+  pull-request head. Tracked as
+  [#70](https://github.com/plagor44-ux/pi-session-mcp/issues/70) and fixed in
+  Sprint 3.
+- Sprint 3 is closed: [#75](https://github.com/plagor44-ux/pi-session-mcp/pull/75)
+  was merged on 2026-10-13 as `f636e6e` with green CI on Linux, macOS 15
+  and macOS 26, also on main; it closed #70 and #71. The first ten-task Level 3
+  cycle on Pi SDK `1.x` was accepted (10 of 10, with the maintainer's intended
+  profiles `explore-fast` and `code-deepseek`); R06 and R07 passed; R08
+  passed for Codex while Claude Code failed one timing criterion
+  ([#74](https://github.com/plagor44-ux/pi-session-mcp/issues/74)). R10 and R11
+  are blocked on the work Mac, with a runbook. See the
+  [Sprint 3 file](sprints/2026-10-13-s3-live-usage.md).
+- Release 0.8.2 was merged in [#76](https://github.com/plagor44-ux/pi-session-mcp/pull/76)
+  and published on 2026-10-14. It carries #59, #56, #60 and the #62 skill
+  change under an unchanged MCP contract. Its published-release acceptance on
+  2026-10-15 found that a fresh npm install crashes at startup
+  ([#78](https://github.com/plagor44-ux/pi-session-mcp/issues/78)); the fix
+  ships as 0.8.3.
+- Sprint 4 decision inputs for the conditional items R12, R15, R17 and R18 are recorded in the [Sprint 4 decision inputs](sprints/2026-10-13-s4-decision-inputs.md) ([#72](https://github.com/plagor44-ux/pi-session-mcp/issues/72)): R12, R15 and R17 not met, R18 not determinable as of 2026-10-13; this is input, not the Sprint 4 decision.
+- Sprint 4 is closed with its [decision](sprints/2026-10-15-s4-decision.md)
+  ([#77](https://github.com/plagor44-ux/pi-session-mcp/issues/77)), taken on
+  2026-10-15 before the macOS gate by maintainer decision. ADR 0003's isolation
+  trigger fired, because coding profiles had written on non-disposable
+  repositories. The one next investment is the isolation decision
+  ([#79](https://github.com/plagor44-ux/pi-session-mcp/issues/79), ADR 0008
+  Proposed), with interim operating rules until it is accepted. R12, R15 and
+  R17 stay deferred (not met), R18 stays deferred (not determinable), and
+  [#74](https://github.com/plagor44-ux/pi-session-mcp/issues/74) is closed as
+  not planned. R10, R11 and R22 stay open.
+
+### Sprint 3 task status
+
+| Task | Issue | Status |
+| --- | --- | --- |
+| Harness tests time out on macOS | [#70](https://github.com/plagor44-ux/pi-session-mcp/issues/70) | verified: CI green on macOS 15 and 26, also on main |
+| R08 three sessions with a read-only reviewer | [#71](https://github.com/plagor44-ux/pi-session-mcp/issues/71) | partially verified: Codex passed, Claude Code failed on timing only; follow-up [#74](https://github.com/plagor44-ux/pi-session-mcp/issues/74) closed as not planned in Sprint 4 |
+| R05 / R09 ten-task Level 3 cycle | None (acceptance) | verified: accepted, 10 of 10 tasks |
+| R06 new Codex abort run | None (acceptance) | verified |
+| R07 Codex discovery of the setup-installed skill | None (acceptance) | verified |
+| R10 / R11 current macOS Level 2 and smoke | None | blocked: work Mac not reachable; runbook in the Sprint 3 file |
+| R22 ChatGPT project instructions | None (outside this repository) | blocked on an operator action; proposal in the Sprint 2 file |
+
+Status words: planned, in progress, implemented (code exists), verified (named
+criteria met with evidence), blocked, failed (ran and missed its criteria; kept
+on record). Sprints 1 to 4 are closed; the next investment is the isolation
+decision in [#79](https://github.com/plagor44-ux/pi-session-mcp/issues/79).
+
+## Sprints and exit gates
+
+The dates are proposed windows, not commitments. Dependent work waits for its
+gate; independent Mac setup verification and documentation may run alongside.
+Later windows shift with the gate of the sprint before them.
+
+| Sprint | Proposed window | Work | Exit gate |
+| --- | --- | --- | --- |
+| S1: correctness | Oct 13–14; 1–2 sessions plus native QA | R01 recovery fix, R02/#56 diagnosis, R03 native checks, R19 evidence record | Operator data preserved; correct existing codes; native Level 1, final review/CI and relevant Level 2 pass |
+| S2: evidence | Oct 15–16; 1–2 sessions | R04, R13/R14 resource binding, handshake offering, #60, R16 strict CI, R20, R22 and R23 documentation, current-source canary; R15 not included (entry condition in the Sprint 2 file) | Changed resources invalidate acceptance; original failures retained; remainder has issues or entry conditions |
+| S3: live usage | Oct 17–20; 2–3 bounded sessions | R05–R11: same-build ten-task cycle, Codex abort scope/discovery, third/read-only worker, intended profile, current Mac acceptance | Existing Level-3 gate plus all scope/security/cleanup criteria; no claim beyond tested combinations |
+| S4: decision | Oct 21–23; 1 evaluation | Usage metrics, conditional R12/R15/R17/R18 | Maintenance or at most one justified investment, with focused issue and ADR where required |
+
+R-identifiers are planning identifiers, not GitHub issue numbers. #56 was
+the only open implementation tracker at the audit snapshot; #59 was created
+for R01 afterwards. Create a focused, duplicate-checked issue before each new
+implementation task. This roadmap delivers R21's documentation; it does not
+close the other tasks.
+
+## Parallel work
+
+- S1 recovery and #56 use separate worktrees and file ownership. The
+  integrator owns shared docs, changelog and release fields. Full-suite QA
+  runs once on the final combined source, without overlapping heavy suites.
+- S2 has one harness owner; skill policy and documentation can proceed
+  independently.
+- S3 live runs are sequential on each shared inference endpoint; independent
+  current Mac Level-2 setup checks can run in parallel. Only after two-session
+  acceptance, try two writers on separate aliases plus one read-only reviewer
+  of a frozen result.
+- Keep heavy suites and parallel large-model work off a constrained work Mac.
+
+```mermaid
+flowchart TD
+  S1["S1: Fix confirmed defects"] --> G["Native QA and review"]
+  G --> S2["S2: Bind evidence"]
+  G --> M["Current Mac setup acceptance"]
+  S2 --> S3["S3: Live usage acceptance"]
+  S3 --> S4["S4: Next-investment decision"]
+  M --> S4
+```
+
+## Product boundary and deferred work
+
+Follow [ADR 0003](adr/0003-post-mvp-maintenance.md), together with the approved
+macOS, extension and skill decisions in ADRs 0005–0007. Maintain local stdio,
+in-memory state and one trusted local peer.
+
+| Topic | Entry condition |
+| --- | --- |
+| OS isolation | Trigger fired on 2026-10-15 (coding profiles wrote on non-disposable repositories); decision in [#79](https://github.com/plagor44-ux/pi-session-mcp/issues/79) and ADR 0008, interim rules in the [Sprint 4 decision](sprints/2026-10-15-s4-decision.md#interim-operating-rules); profiles/skills are not an OS sandbox |
+| pi_turn_wait | Measured high polling cost per turn with pauses or tool/approval cost; 5–7 polls per invocation is insufficient evidence |
+| Persistence/resume | Actual loss of useful work on restart |
+| HTTP/remote/mobile | Concrete need existing SSH/remote development cannot meet; separate ADR/security decision |
+| Finer turn_failed | Closed public final SDK cause discriminator after retry/compaction, not error-text guessing |
+| Multi-user/UI/credentials | Separate justified product scope and ADR |
+| Explicit unverified code for an unreadable client start time (R15) | A run that passes while the start time was unreadable, or a demonstrated need; today the run fails with `noServerObserved`, so it cannot pass falsely |
+| Former pi-control #31/#32 | Closed as not_planned; no automatic migration/reopening |
+| Former release gates/#11–#14 | Historical; bind current acceptance to the current build |
+
+0.8.3 is a patch release only if the MCP contract remains unchanged and its
+gates pass. Apply the current [release procedure](releasing.md): version and
+pre-release acceptance travel in the change PR. Merge, tagging and
+publication remain maintainer decisions. No release is authorized by this plan.

package/docs/skills.md

@@ -290,7 +290,7 @@ status `failed` (exit 1), so it is not overlooked.
 
 | Operation | Code (status) |
 | --- | --- |
-| `--dry-run` | `skill_absent` (absent), `skill_equivalent` (unchanged), `skill_linked` (unchanged), `skill_update_planned` (planned), `skill_recovery_planned` (planned), `skill_divergent` (divergent), `skill_legacy_unverified` (divergent), `skill_source_invalid` (failed) |
+| `--dry-run` | `skill_absent` (absent), `skill_equivalent` (unchanged), `skill_linked` (unchanged), `skill_update_planned` (planned), `skill_recovery_planned` (planned), `skill_recovery_retained` (divergent), `skill_divergent` (divergent), `skill_legacy_unverified` (divergent), `skill_source_invalid` (failed) |
 | `--apply` | `skill_installed` (ok), `skill_already_equivalent` (unchanged), `skill_recovered` (ok), `skill_linked` (unchanged), `skill_updated` (ok), `skill_divergent` (divergent), `skill_legacy_unverified` (divergent), `skill_recovery_retained` (divergent), `skill_source_invalid` (failed), `skill_install_failed` (failed) |
 | `--verify` | `skill_verified` (ok), `skill_missing` (failed), `skill_not_equivalent` (failed) |
 | `--rollback`, `--remove` | `skill_removed` (ok), `skill_kept_shared` (unchanged), `skill_not_owned` (unchanged), `skill_absent` (ok), `skill_divergent` (divergent), `skill_legacy_unverified` (divergent), `skill_recovery_retained` (divergent) |
@@ -306,11 +306,12 @@ status `failed` (exit 1), so it is not overlooked.
   If the settled copy still needs the new version, `--apply` continues and
   reports `skill_installed` or `skill_updated`.
 - `skill_recovery_planned` means that the ownership record is pending for an
-  update that `--apply` would settle. The dry-run does not write or delete
-  anything and does not look at the intermediate directories, so `--apply` can
-  still find a modified or foreign intermediate, keep it and report
-  `skill_recovery_retained`. A divergent or
-  foreign copy keeps `skill_divergent`, and a 0.8.0 record keeps its own code.
+  update that `--apply` would settle, and that the read-only classification
+  found no intermediate that `--apply` would retain. The dry-run does not
+  write or delete anything. In the dry-run, `skill_recovery_retained`
+  (divergent, exit 1) means that the same classification found an
+  intermediate that `--apply` would retain. A divergent or foreign copy keeps
+  `skill_divergent`, and a 0.8.0 record keeps its own code.
 - `skill_kept_shared` means that the other Claude Code registration (`user` or
   `local`) still uses the shared directory. The last one removes the skill.
 - A copy that already equals the effective skill but was not created by `setup`
@@ -366,15 +367,42 @@ still recognizes the old copy as its own. `--apply`, `--remove` and
   moves the verified backup back, and then continues.
 - `--remove` and `--rollback` delete the verified intermediates and then remove
   the copy as usual.
-- A partial trash directory is deleted after a structural recheck (real
-  directories and regular files only, no hidden entries, within the tree
-  limits).
+- A trash directory is deleted only when its current contents are the
+  complete, unchanged copy that the update replaced: its tree fingerprint
+  equals the replaced fingerprint in the pending record. A partial trash
+  directory (for example after an interruption during the entry-by-entry
+  deletion, including an empty one), a modified or added-to one, a foreign one,
+  and any trash when the record names no usable replaced fingerprint are
+  retained, because their contents cannot be proven to be setup's own. A
+  directory name or a structural check alone never proves that. The
+  fingerprint covers the paths and contents of regular files, not empty
+  directories or file modes: an empty directory or a mode change inside an
+  otherwise complete trash is deleted with it, but no file content is lost.
 - A partially written staging directory is deleted only when every file in it
   is a prefix-consistent part of the current library tree, and that tree is the
   record's target.
 - Anything modified or foreign stays and is reported as
-  `skill_recovery_retained` (divergent). Inspect the directory and delete it
-  yourself if it is not yours.
+  `skill_recovery_retained` (divergent). This includes the trash directory.
+  A retained intermediate leaves the pending record and the skill directory
+  unchanged, and nothing is reported as settled. A retained trash directory
+  stops recovery before any other intermediate is touched; a retained backup
+  or staging directory can follow the deletion of a proven own trash
+  directory.
+
+To settle a retained trash directory:
+
+1. Inspect the `.pi-session-mcp-<skill>-<transactionId>.trash` directory next
+   to the skill directory.
+2. Move any content of your own elsewhere.
+3. Delete that directory.
+4. Run the same setup command again.
+
+For a pending version 2 transaction, `--dry-run` reports
+`skill_recovery_retained` (divergent, exit 1) when `--apply` would retain an
+intermediate, using the same read-only classification as the recovery, and
+otherwise `skill_recovery_planned`. It never writes or deletes anything.
+Setup deliberately no longer deletes a partial trash tree automatically;
+before this rule it did after a structural recheck.
 
 A failed update leaves its staging directory until the next run settles it.
 The directories of updates by 0.8.0 had random names. Setup never searches for