pi-session-mcp 0.8.0 → 0.8.2

package/docs/sprints/2026-10-13-s3-live-usage.md

@@ -0,0 +1,267 @@
+# Sprint 3: live usage acceptance
+
+Base: main `0aae6390c539e1d70138f1efaf297e6193a2b497` (the merge of Sprint 2,
+[#69](https://github.com/plagor44-ux/pi-session-mcp/pull/69)). Date: 2026-10-13.
+Planning sources: the [roadmap](../roadmap.md) and the
+[post-0.8.1 audit](../reviews/2026-10-13-post-0.8.1-audit.md) (R05–R11 and the
+Sprint 3 exit gate).
+
+This file tracks Sprint 3. A status of `implemented` or `verified` is set only
+together with evidence below.
+
+## Scope and maintainer decisions
+
+Decided by the maintainer on 2026-10-13:
+
+- The Pi profiles actually intended for use (R09) are `explore-fast`
+  (read-only; OpenAI `gpt-6-luna`, thinking `low`) and `code-deepseek`
+  (coding; DeepSeek `deepseek-flash`, thinking `high`). Results cover this
+  pair only.
+- All Linux items run now, each once: R05 (ten-task Level 3 cycle, both
+  controllers), R06 (a new Codex abort run), R07 (Codex home-skill discovery)
+  and R08 (three concurrent sessions with a read-only reviewer). Failures stay
+  on record.
+- A 0.8.2 patch release follows the live runs in its own pull request. Merge,
+  tag and publication remain maintainer decisions.
+- R10 and R11 need the work Mac, which is not reachable from the Linux
+  workstation; they are blocked, and the [runbook](#appendix-macos-runbook-r10-r11)
+  below describes the light check to run there.
+
+Out of scope: new runtime features, dependency or Pi SDK updates, MCP contract
+changes, Sprint 4 decisions.
+
+The live runs use a separate detached, built checkout of the release under
+test at the base commit: `dist/main.js` SHA-256
+`47875d38886528ace6b242df2c6ad79d624c51e330e63c2f401576eadc449ed7`, `dist`
+JavaScript tree SHA-256
+`f85bf73ee8c0ddb2270d8d6040feffbc49f018d2e6ab6253fffb828654a389df`. Live runs
+are strictly sequential: one controller invocation at a time.
+
+## Status legend
+
+planned, in_progress, implemented (code or tooling exists), verified (the named
+criteria are met with evidence), blocked (a named blocker), failed (the run
+happened and did not meet its criteria; it stays on record).
+
+## Tasks
+
+| Task | Issue | How | Status |
+| --- | --- | --- | --- |
+| Harness tests time out on macOS (main CI after #69) | [#70](https://github.com/plagor44-ux/pi-session-mcp/issues/70) | One fixture build per case | implemented; the pull request CI on macOS decides |
+| R08 three sessions with a read-only reviewer | [#71](https://github.com/plagor44-ux/pi-session-mcp/issues/71) | `trio` scenario of the multi-session harness, then one live run per controller | partially verified: Codex passed; Claude Code failed on timing only ([#74](https://github.com/plagor44-ux/pi-session-mcp/issues/74)) |
+| R05 / R09 ten-task Level 3 cycle | None (acceptance) | Private per-cycle driver, as [acceptance](../acceptance.md#level-3-live-two-client-acceptance) prescribes; pre-registered | verified (10/10, all gate conditions) |
+| R06 new Codex abort run | None (acceptance) | Multi-session harness at the base commit, `abort` scenario, Codex | verified |
+| R07 Codex discovery of the setup-installed skill | None (acceptance) | One real Codex run in an isolated home | verified |
+| R10 / R11 current macOS Level 2 and smoke | None | Runbook below | blocked (work Mac not reachable) |
+
+## Main CI on the Sprint 2 merge
+
+The main CI run [38442206975](https://github.com/plagor44-ux/pi-session-mcp/actions/runs/38442206975)
+on `0aae639` failed on `macos-15` only: one harness test timed out after
+5684 ms against the default 5000 ms. The merge tree equals the pull-request
+head `fb40f99`, whose CI passed on all platforms, and the test needs under
+0.6 s on Linux. The cause is a test design defect (four fixture builds inside
+one test), tracked as #70 and fixed in this sprint without raising a timeout.
+The failed run stays on record; no manual re-run was started.
+
+## Evidence
+
+### R07: Codex home-skill discovery
+
+Private check script, pre-registered by its SHA-256
+`018fddbd28f699998cba23ec902f98d68951851052aa62209236fea5d5a9e7d2` before the
+run. Codex CLI `0.162.1`, Linux.
+
+- The candidate's `pi-session-mcp-setup --apply --target codex:user:pi-session-mcp`
+  ran with a disposable `HOME` and `CODEX_HOME`: exit 0, `skill_installed`; the
+  installed copy is a regular directory, equal to the candidate's skill; no
+  link exists in the project.
+- One real `codex exec` (`--ignore-user-config`, `--sandbox read-only`, the
+  disposable `HOME`, the operator's `CODEX_HOME` only for authentication) in a
+  project that is its own git root reported the skill as available, named the
+  installed copy's `SKILL.md` as its path, and quoted verbatim a line that
+  exists only in the revision under test (#62), not in the 0.8.1 copy.
+- The operator's own `~/.agents/skills` was unchanged; the disposable
+  directory was removed.
+
+Limit: the path is the model's report. It matches the installed copy, and the
+quoted line proves that the current revision was read; it is no proof of
+Codex's internal precedence between several skill sources.
+
+### Level 3 pre-registration
+
+Recorded before the first Level 3 task. Both prepared runs (Claude Code with the
+operator home, Codex with a disposable home on a non-temporary disk outside the
+operator home) share one pre-registration content digest over the prompts,
+tasks, tools, oracles, allowed files, the coding barrier, the profiles
+(permission, provider, model, thinking) and the fixture digests:
+`8645f3a4d4f700180473bbe9b4280c565bebf4e49e185685e2c0f712dd856cf5`. The private
+per-cycle driver has SHA-256 `c160a9e54885dc6d706b7e922b2d117fb98fc3ae2fe1a81ae56f68f87adccdaf`.
+
+The worker profiles copy provider, model, thinking level and permission of the
+intended `explore-fast` and `code-deepseek`. Both operator profiles also grant a
+read-only external MCP tool (`codegraph_explore`); the acceptance tooling never
+copies MCP servers, and Level 3 does not cover external MCP grants, so the runs
+use the profiles without it. The disposable Codex home is a conservative
+isolation choice: the operator home holds no `pi-session-orchestration` copy in
+`~/.agents/skills`.
+
+### R06: new Codex abort run
+
+`scripts/multi-session-acceptance.mjs` at the base commit (harness SHA-256
+prefix `7c43cc8a`), `prepare --from-profile code-deepseek` (DeepSeek
+`deepseek-flash`, thinking `high`), then one `run --client codex --scenario
+abort`, with a disposable home and the operator's `CODEX_HOME` and Pi agent
+directory passed explicitly. Codex CLI `0.162.1`, Node.js `26.11.1`, Linux
+x64. Started 2026-10-13 19:30 UTC, 100 s.
+
+- `acceptance.passed: true`, no failure code. The `wait` turn ended `aborted`,
+  the `range` turn `completed` with its tests passing, and both fixtures
+  changed only allowed files: the strict scope oracle (`range:changes`) that
+  failed the v0.8.1 Codex abort run passed unchanged.
+- Both sessions closed, no residual process, no bound resource changed or
+  unbound, no structural leak, the handshake token appeared nowhere.
+- The sanitized evidence record contains no path.
+
+### R05 / R09: ten-task Level 3 cycle
+
+Private per-cycle driver (SHA-256 prefix `c160a9e5`), pre-registered as
+recorded above. Candidate: detached checkout of `0aae639`, clean, package
+`0.8.1`, `dist/main.js` SHA-256 `47875d38…`. Clients Claude Code `2.1.296`
+and Codex CLI `0.162.1`; Node.js `26.11.1`; Linux x64. Worker profiles
+`l3-read` (OpenAI `gpt-6-luna`, `low`, read-only) and `l3-code` (DeepSeek
+`deepseek-flash`, `high`, coding). Claude Code ran with the operator home,
+Codex with a disposable home; both runs share the pre-registration digest
+`8645f3a4…`.
+
+- Preflight: both profiles answered PONG through the candidate server and
+  closed; the server exited with empty stderr.
+- Six invocations, strictly sequential, 19:33–19:40 UTC (56–94 s each):
+
+  | Client | Read-only analysis | Read-only follow-up | Coding change | Coding follow-up | Abort and recovery |
+  | --- | --- | --- | --- | --- | --- |
+  | Claude Code | intended | intended | intended | intended | intended |
+  | Codex | intended | intended | intended | intended | intended |
+
+- Verdict: accepted, 10 of 10 tasks, and all 16 gate conditions true: both
+  clients complete discovery, start, prompt, result and close; a useful
+  second turn; a bounded, independently verified coding workflow (barrier
+  snapshots taken after each coding turn and before the next prompt, fixture
+  tests and hidden business checks on the snapshots, only the allowed files
+  changed); no change outside the approved diff; no public leak; no session or
+  process left after a verified close; stable, sanitized lifecycle errors;
+  bound resources unchanged and complete; Level 1 green for the release source
+  (native Linux on `0aae639`: typecheck, strict `npm test` with 54 files, 1300
+  passed and 6 skipped, `npm audit` 0).
+- The coding barrier worked for both clients, including inside Codex's
+  read-only sandbox.
+- Liveness and polling: every turn was seen `running` in at most one
+  `pi_turn_get` poll, and whenever it was, `updatedAt` had advanced past
+  `startedAt`. Both clients waited between polls with `sleep`. This is no
+  evidence for the bounded-wait revisit trigger of ADR 0003.
+
+Limits: one cycle, one provider pair, Linux only. The worker profiles do not
+include the operator profiles' read-only `codegraph_explore` MCP grant. The
+ten tasks are deliberately small and qualify the control path, not model
+capability on larger work. No live run failed with `noServerObserved`, so this
+sprint adds no input for R15.
+
+### R08: three concurrent sessions with a read-only reviewer
+
+`scripts/multi-session-acceptance.mjs` of this sprint's branch at `63d5ff7`
+(harness SHA-256 prefix `bb1620ad`), reviewed before the runs (see
+[Independent review](#independent-review)); candidate `0aae639`; `prepare
+--from-profile code-deepseek` (DeepSeek `deepseek-flash`, `high`, for both
+`accept-code` and `accept-read`); one `trio` run per controller, Claude Code
+with the operator home, Codex with a disposable home. 2026-10-13, 20:13–20:17
+UTC.
+
+| Controller | Result | Duration | Notes |
+| --- | --- | --- | --- |
+| Codex `0.162.1` | passed, no failure code | 102 s | Three sessions on their expected aliases and profiles; all first turns overlapped; `wait` aborted by one successful, on-target abort while `slug` and `review` were running; `slug` tests passed within `src/slug.js`; the `review` fixture unchanged in working tree, index and `HEAD`; all closed; no residual process, leak or resource change |
+| Claude Code `2.1.296` | failed: `neighborsNotRunningDuringAbort` only | 118 s | Every other criterion passed as for Codex. The `review` turn completed after 10.7 s, 6.7 s before the abort of `wait`, which came about 10 s after the `wait` turn started instead of the requested about 5 s; `slug` was still running |
+
+The failure is a timing outcome of the scenario design, not a session-control
+defect; it stays on record and was not repeated, as decided for this sprint.
+Follow-up: [#74](https://github.com/plagor44-ux/pi-session-mcp/issues/74).
+Three concurrent sessions, a read-only reviewer of a frozen result and a
+neighbor abort are therefore accepted for Codex; for Claude Code everything
+except the reviewer still running at the abort is shown.
+
+### Native gate
+
+On `0e90589` (this branch before this record), native Linux: `npm ci`,
+typecheck, `build:cli`, `NODE_OPTIONS=--unhandled-rejections=strict npm test`
+(54 files; 1409 passed, 6 skipped, 0 failed; no unhandled error), build,
+`npm audit` and `npm audit --omit=dev` (0 vulnerabilities), `git diff --check`
+and a clean status all exited with `0`; `npm pack --dry-run` listed 134 files
+without sources, tests, lockfile, plans or the harness. The test count adds the
+109 new harness cases to the 1306 of Sprint 2. The built `dist` tree equals the
+one of the base commit, so the package runtime is unchanged and the live
+evidence above binds to this branch. No client session in a test root and no
+client process appeared during the run.
+
+## Independent review
+
+The harness changes for #70 and #71 were reviewed before the R08 runs by two
+read-only reviewers who did not write them:
+
+| Reviewer | Round | Verdict | Outcome |
+| --- | --- | --- | --- |
+| Claude family | 1 | approve with nits | An abort on a neighbor with `abort_timeout` was not judged; the reviewer started last and could finish before the abort; a looser `slug` scope in `trio`; an end-state-only read-only oracle; missing `analyze`-to-verdict tests; one test with two fixture builds. All addressed: `c80383f` to `63d5ff7`; the end-state limit is documented. |
+| OpenAI family (Pi `review` profile) | 1 | changes requested | A failed abort with an unknown session id disappeared from the verdict (concrete false pass), also in the existing `abort` scenario; lost aggregate coverage in the #70 split. Fixed: every `pi_session_abort` call is judged in `abort` and `trio` (new code `offTargetAbort`); an aggregate test. |
+| OpenAI family | 2 | approve | No new finding. |
+
+The stricter abort rule also applies to `abort`. The recorded R06 run was
+checked by hand against it: its transcript holds one abort call, on its own
+started session, with an ok result.
+
+## Open gates
+
+- This sprint's pull request CI (Linux, macOS 15, macOS 26), which also shows
+  whether #70 removed the `macos-15` timeout, and the maintainer's merge.
+- [#74](https://github.com/plagor44-ux/pi-session-mcp/issues/74): the `trio`
+  timing with Claude Code as controller (entry condition in the issue).
+- R10 and R11 on the work Mac ([runbook](#appendix-macos-runbook-r10-r11)).
+- R22 (external ChatGPT project instructions) stays blocked on an operator
+  action.
+
+## Next step
+
+After the merge, the 0.8.2 release pull request follows, as the maintainer
+decided: version, changelog heading and pre-release acceptance on the release
+candidate. It carries #59, #56 and #60, which the published 0.8.1 does not
+have (0.8.1 still deletes a partial trash), and the #62 skill change; the MCP
+contract is unchanged. Merge, tag and publication stay maintainer decisions.
+Then Sprint 4 decides from the evidence of Sprints 1–3 and the
+[Sprint 4 decision inputs](https://github.com/plagor44-ux/pi-session-mcp/pull/73)
+prepared in parallel.
+
+## Closure
+
+Sprint 3 closed on 2026-10-13. Pull request
+[#75](https://github.com/plagor44-ux/pi-session-mcp/pull/75) was merged as
+`f636e6e` after its final-head CI passed on Linux, macOS 15 and macOS 26 (run
+`38462141219`); the CI run on main (`38465781209`) passed on the same
+matrix, so #70 holds on main too. The merge closed #70 and #71 as completed.
+The Sprint 4 decision inputs
+([#73](https://github.com/plagor44-ux/pi-session-mcp/pull/73), #72) followed
+as `166ffef`, also with green CI on main. Open from this sprint: #74, R10 and
+R11 on the work Mac, and R22. The 0.8.2 release is prepared in its own pull
+request.
+
+## Appendix: macOS runbook (R10, R11)
+
+Light checks only; no full test suite and no parallel model work on the work
+Mac. Run them from a checkout of the release under test.
+
+1. `npm ci`, `npm run build`, `npm run build:cli`.
+2. Level 2 with both clients in disposable homes:
+   `node scripts/setup-acceptance.mjs --setup "node <checkout>/dist/setup-main.js" --build-dir <checkout> --work-dir ~/.cache/pi-session-mcp-acceptance --label "macOS <version> <commit>" --out <private file>`.
+   Record the exit status, the check count, the client versions and the
+   result's `realRegistrationsUnchanged`, `processCheck` and `buildUnchanged`.
+3. Read-only smoke (R11): one `pi_session_start` with a read-only profile, one
+   short prompt, `pi_turn_get` until completed, `pi_session_close`, through the
+   installed client registration.
+4. Record date, macOS version, commit, `dist/main.js` SHA-256 and the outcomes
+   in [acceptance](../acceptance.md), without paths or prompt content.

package/docs/sprints/2026-10-13-s4-decision-inputs.md

@@ -0,0 +1,241 @@
+# Sprint 4 decision inputs: R12, R15, R17 and R18
+
+Date: 2026-10-13. Base: main `0aae6390c539e1d70138f1efaf297e6193a2b497` (the
+merge of Sprint 2). Tracking:
+[#72](https://github.com/plagor44-ux/pi-session-mcp/issues/72).
+Planning sources: the [roadmap](../roadmap.md) and the
+[post-0.8.1 audit](../reviews/2026-10-13-post-0.8.1-audit.md), whose
+[Sprint 4 section](../reviews/2026-10-13-post-0.8.1-audit.md#sprint-4-decide-the-next-investment-from-usage)
+routes R12, R15, R17 and R18 "into one concrete follow-up or the deferred list
+according to need".
+
+This record is decision input, not the Sprint 4 decision. It checks the entry
+condition of each of these four conditional items against facts gathered on
+2026-10-13, while Sprint 3 (live usage acceptance) is still running. It
+implements nothing: no workflow, `package.json`, release tooling or runtime
+change. The usage evaluation that Sprint 4 needs from Sprint 3 (failures and
+their causes, scope violations, polls per turn, task duration, cleanup,
+restart cost and planned non-disposable workspaces) is outside this record.
+Sprint 3 results can change the assessments of R12 and R15 below; Sprint 4
+re-checks them.
+
+R-identifiers are planning identifiers from the audit, not GitHub issue
+numbers.
+
+## Summary
+
+| Item | Entry condition | Assessment on 2026-10-13 | Re-check in Sprint 4 |
+| --- | --- | --- | --- |
+| R17 scheduled advisory check | Further demonstrated `npm audit` drift | Not met | Any advisory found between releases or at a release gate; any Dependabot alert |
+| R18 npm provenance / Trusted Publishing | External use makes it relevant | Not determinable; no evidence of external consumers | Distinguishable external use, or a maintainer decision to harden publication anyway |
+| R12 real crash, contention and signal runs | Operating experience warrants targeted evidence | Not met | Sprint 3 records and operator reports of interrupted updates, customization conflicts or signal-ended analyses |
+| R15 explicit unverified evidence for an unreadable start time | A run passes while the start time was unreadable, or a demonstrated need | Not met | Sprint 3 `noServerObserved` failures whose investigated cause is an unreadable start time |
+
+Assessment values: **met** (the facts satisfy the entry condition), **not
+met** (the facts were checked and do not satisfy it), **not determinable**
+(the available facts cannot decide it).
+
+## R17: scheduled advisory check
+
+Definition
+([audit, cluster C](../reviews/2026-10-13-post-0.8.1-audit.md#c-acceptance-and-release-evidence-quality)):
+`npm audit` is manual only. Deliverable: keep the manual release gate;
+consider one small scheduled advisory check only after further demonstrated
+drift, in its own issue.
+
+Facts:
+- `npm audit` and `npm audit --omit=dev` against the lockfile of `0aae639`
+  reported 0 vulnerabilities each (331 dependencies), exit 0.
+- The release notes of v0.6.4, v0.7.0, v0.7.1, v0.8.0 and v0.8.1 each record
+  `npm audit` and `npm audit --omit=dev` with 0 vulnerabilities. The native
+  gates of [Sprint 1](2026-10-13-s1-correctness.md) and
+  [Sprint 2](2026-10-13-s2-evidence.md) recorded 0 vulnerabilities on every
+  run.
+- No changelog entry and no commit after the initial public release patches
+  an audit advisory. The 0.6.2 changelog records that the earlier lockfile
+  patches for `proxy-addr`, `shell-quote` and `concurrently`, present since
+  the initial public release (2026-10-06), left the tree with the Inspector
+  update `5015143` of 2026-10-09, before v0.6.2 was tagged the same day.
+  [Releasing](../releasing.md#patch-audit-advisories) describes the
+  `concurrently` case.
+- GitHub vulnerability alerts (Dependabot alerts) are enabled for the
+  repository and list no alerts. There is no `.github/dependabot.yml`, so no
+  version-update pull requests are configured. Dependabot alerts already give
+  a passive advisory signal for the default branch between releases.
+- `npm audit signatures` on the installed tree of the workstation checkout
+  (consistent with the lockfile: `npm ls --all` exit 0) reported 251 packages
+  with verified registry signatures and 79 with verified attestations, exit 0.
+  CI does not run it.
+- A scheduled-workflow precedent exists:
+  [`pi-sdk-canary.yml`](../../.github/workflows/pi-sdk-canary.yml) runs nightly
+  and reports an incompatible SDK into one labeled tracker issue.
+
+Assessment: **not met**. No drift is demonstrated after the initial release.
+
+If the condition is met later, the smallest follow-up is its own issue for a
+nightly job that runs both audit commands against the lockfile and reports
+into one labeled tracker issue, following the canary's pattern. The manual
+release gate stays. Whether Dependabot alerts already cover the need is part
+of that decision.
+
+## R18: npm provenance and Trusted Publishing
+
+Definition
+([audit, cluster C](../reviews/2026-10-13-post-0.8.1-audit.md#c-acceptance-and-release-evidence-quality)):
+npm publication has no provenance attestation. Deliverable: consider Trusted
+Publishing or provenance as a separate supply-chain decision if external use
+makes it relevant; not a blocker for bounded local dogfooding.
+[#3](https://github.com/plagor44-ux/pi-session-mcp/issues/3) deferred
+"provenance and trusted publishing from GitHub Actions" when the package was
+first published.
+
+Facts about publication:
+- The registry lists 0.6.1, 0.6.2, 0.6.3, 0.6.4, 0.7.0, 0.7.1, 0.8.0 and 0.8.1,
+  published between 2026-10-06 and 2026-10-12 (UTC), plus the staging placeholder
+  `0.0.0-stage`. None of them carries a provenance attestation in its registry
+  metadata.
+- [Releasing](../releasing.md#publish-a-release) publishes from a fresh local
+  clone of the tag with `npm stage publish`; the maintainer approves the staged
+  version with the account's second factor and compares the shasum.
+
+Facts about use:
+- The npm download API, whose data ended on 2026-10-11 at the time of the
+  query, reports 915 downloads from 2026-10-07 to 2026-10-11 (59, 15, 150, 349
+  and 342 per day) and none earlier in the 30-day window, all within days of
+  the six publications from 0.6.1 to 0.7.1; 0.8.0 and 0.8.1 fall after the
+  data. The counts do not distinguish
+  people from registry mirrors and automated fetchers, nor external users from
+  the maintainer's own installations.
+- GitHub reports one star, no forks and no watchers. Its 14-day traffic shows
+  770 clones (229 unique) and 45 views (3 unique); every CI run checks the
+  repository out, so clones do not indicate external users either.
+- All 26 pull requests are from the maintainer account. Before #72, 43 of 45
+  issues were from the maintainer account and two (#28, #29) from one other
+  account. #28 reports use from a clone of a release tag, not from the npm
+  package. No issue or pull request identifies an external consumer of the
+  npm package.
+
+Facts about the mechanism (npm documentation, read on 2026-10-13:
+[Trusted publishing for npm packages](https://docs.npmjs.com/trusted-publishers),
+[Staged publishing for npm packages](https://docs.npmjs.com/staged-publishing),
+[Generating provenance statements](https://docs.npmjs.com/generating-provenance-statements)):
+- Trusted publishing authenticates a CI workflow through OIDC instead of a
+  long-lived token. It needs npm CLI 11.5.1 or later and Node.js 22.14.0 or
+  later, a GitHub Actions workflow with `id-token: write`, and a trusted
+  publisher configured on npmjs.com for the owner, repository and workflow
+  file name.
+- A trusted publisher always allows `npm stage publish`; a direct
+  `npm publish` and dist-tag management are separate options. A staged
+  version still needs a maintainer's approval with the second factor, so the
+  current approval step can stay. Staging needs npm 11.15 or later (see
+  [Releasing](../releasing.md#publish-a-release)), above the trusted-publishing
+  minimum.
+- Trusted publishing from GitHub Actions generates provenance attestations
+  automatically when the repository and the package are public. Both are
+  public. A local publish, as today, cannot produce provenance.
+
+Assessment: **not determinable**. The available counts cannot separate
+external consumers from mirrors, automation and the maintainer's own
+installations, and no external consumer has made itself known.
+
+If the condition is met later, or the maintainer decides to harden
+publication without it, the smallest follow-up is its own issue and a release
+procedure decision:
+- a tag-triggered workflow with `id-token: write` that runs `npm ci`, builds
+  and stages the package with `npm stage publish`;
+- a trusted publisher on npmjs.com limited to staging, so every version still
+  needs the second-factor approval;
+- [Releasing](../releasing.md) updated, including a check of the attestation
+  after approval;
+- the published-release Level 2 acceptance unchanged.
+
+Trade-offs to weigh: the release bytes are built on a GitHub-hosted runner
+instead of a fresh local clone; the repository gains a workflow with an
+OIDC token permission and depends on the actions it uses; the first release
+under the new procedure needs the same pre-release acceptance as any other.
+The change touches release tooling; if a 0.8.2 patch release happens, keeping
+this change out of it would keep that patch's scope unchanged.
+
+## R12: real crash, contention and signal runs
+
+Definition
+([audit, cluster B](../reviews/2026-10-13-post-0.8.1-audit.md#b-evidence-and-orchestration)):
+a real skill-update crash, a real customization contention and a
+harness-analysis signal run are absent from live evidence. Deliverable: add
+only targeted evidence when operating experience warrants it; existing
+provider-free tests are not renamed as live evidence.
+
+Facts:
+- The [acceptance status](../acceptance.md#status) states that its records do
+  not cover a real crash in the middle of a setup skill update, a real
+  contention of two customization processes outside the tests, or an
+  operating-system signal to the harness during a live analysis, and that the
+  provider-free tests cover these.
+- Those provider-free tests exist: SIGKILL recovery at six of the seven update
+  checkpoints in [`setup-skills-recovery.test.ts`](../../test/setup-skills-recovery.test.ts),
+  concurrent customization in
+  [`skill-customize-concurrency.test.ts`](../../test/skill-customize-concurrency.test.ts)
+  and signal handling of the harness in
+  [`multi-session-acceptance.test.ts`](../../test/multi-session-acceptance.test.ts).
+- No issue and no acceptance record reports an interrupted real skill update,
+  a customization conflict between two processes, or a live analysis ended by
+  a signal.
+- On `main` since Sprints 1 and 2, not yet in a published release, recovery
+  retains an unprovable intermediate
+  ([#59](https://github.com/plagor44-ux/pi-session-mcp/issues/59)) and the
+  dry-run predicts it ([#60](https://github.com/plagor44-ux/pi-session-mcp/issues/60)).
+  A real interruption that leaves an unprovable intermediate on a build that
+  contains these changes would surface as `skill_recovery_retained`; the
+  published 0.8.1 still deletes a partial trash.
+
+Assessment: **not met**.
+
+If the condition is met later, the smallest follow-up records that occurrence
+as evidence, with its sanitized setup report, and adds a targeted test only
+when the occurrence shows behavior the provider-free tests miss.
+
+## R15: explicit unverified evidence for an unreadable start time
+
+Definition
+([audit, cluster C](../reviews/2026-10-13-post-0.8.1-audit.md#c-acceptance-and-release-evidence-quality)):
+a client start time that is unreadable immediately after spawn leaves no
+sighting. Deliverable: explicit failed or unverified evidence; never infer
+cleanup from an absent observation. [Sprint 2](2026-10-13-s2-evidence.md#tasks)
+did not include it and set the entry condition: a run that passes while the
+start time was unreadable, or a demonstrated need for an explicit unverified
+code.
+
+Facts:
+- The [multi-session harness](../../scripts/multi-session-acceptance.mjs)
+  records a process only together with its start time; without the client's
+  start time nothing is recorded. Its pass criteria include at least one
+  observed server (`noServerObserved`) and no residual process.
+- The acceptance records contain one run with `noServerObserved` failures:
+  run 2 on `06471b5`, where three invocations failed only with
+  `noServerObserved`. Their cause was a harness defect that replaced earlier
+  sightings; `cb6e949` fixed it. The code was misleading there, but the runs
+  failed. The cause was not an unreadable start time.
+- No record shows a run that passed while a start time was unreadable.
+
+Assessment: **not met**.
+
+If the condition is met later, the smallest follow-up is its own issue for an
+explicit failure code when the client's start time cannot be read, so the
+result names the cause instead of `noServerObserved`; such a run still fails.
+
+## Sources and checks
+
+All checks ran on 2026-10-13 on the Linux workstation, read-only, without a
+client, Pi session, provider or model:
+- `npm audit` and `npm audit --omit=dev` against the lockfile of `0aae639`;
+  `npm audit signatures` on the installed tree of the workstation checkout.
+- npm registry metadata of `pi-session-mcp` (publication times, attestations)
+  and the npm download API (point and daily range).
+- GitHub API: repository statistics, 14-day traffic, Dependabot alerts and
+  the vulnerability-alert setting, issue and pull request authors.
+- Release notes of v0.6.4 to v0.8.1, `CHANGELOG.md`, the Git history,
+  [Releasing](../releasing.md), [Acceptance](../acceptance.md), the Sprint 1
+  and Sprint 2 files, the audit and
+  [#3](https://github.com/plagor44-ux/pi-session-mcp/issues/3).
+- npm documentation on trusted publishing, staged publishing and provenance,
+  read through a documentation index on 2026-10-13.

package/docs/threat-model.md

@@ -29,10 +29,10 @@ Pi Session MCP trusts the local process that launches and speaks MCP over inheri
 - **Skill installation into clients:** `setup --apply` writes the controller skill `pi-session-orchestration` into the clients' skill directories, in the home directory (`~/.agents/skills`, `~/.claude/skills`) and, for Claude Code `project`, in the project that setup runs in (`<project>/.claude/skills`). What is written there becomes instructions for the controlling agent, so the copy is as trusted as the package or the override it comes from. Mitigations:
   - Copies come only from the package's `skills/` directory or from the operator's override directory next to the configuration file. No tool argument, client prompt or workspace names a source.
   - The override directory and its `.pi-session-mcp-bases.json` are operator-trusted configuration next to the configuration file, never a workspace. Keep them out of every workspace and writable only by the operator; a `coding` session that can write there could change what setup installs next.
-  - Setup reads a bounded tree of regular files (at most 32 files and 1 MiB, no links or special files) and installs it as a real copy, never as a link. The copy is staged and renamed into place; only the exact old tree that setup itself moved is deleted afterwards.
-  - Setup never replaces or deletes a modified installed copy, hidden operator entries inside it, a foreign skill of the same name or a linked or non-directory entry; it reports `skill_divergent`. A link to exactly the effective skill is accepted as the operator's own (`skill_linked`) and never written through or deleted. Ownership records hold a content fingerprint (and, during an update, the replaced fingerprint), no path; a project record carries an unsalted, truncated SHA-256 of the project's real path as an opaque identity, which someone who can read the state file could test against guessed paths.
+  - Setup reads a bounded tree of regular files (at most 32 files and 1 MiB, no links or special files) and installs it as a real copy, never as a link. The copy is staged and renamed into place. An update renames the old tree to a backup named after the pending record's transaction id and deletes it only after verifying that it is the exact old tree; leftover intermediates are deleted only by their exact names and only after verification (a leftover trash directory only while it still is the complete, unchanged replaced copy), and anything modified, foreign, partial or otherwise unprovable stays (`skill_recovery_retained`).
+  - Setup never replaces or deletes a modified installed copy, hidden operator entries inside it, a foreign skill of the same name or a linked or non-directory entry; it reports `skill_divergent`. A link to exactly the effective skill is accepted as the operator's own (`skill_linked`) and never written through or deleted. Ownership records hold a version 2 content fingerprint (and, during an update, the replaced fingerprint), no path. A bare version 1 value from 0.8.0 names a copy only when a trusted reference (a released 0.8.0 shipped tree or the current library tree) has that value and the copy's exact bytes; otherwise setup reports `skill_legacy_unverified` and changes nothing; a project record carries an unsalted, truncated SHA-256 of the project's real path as an opaque identity, which someone who can read the state file could test against guessed paths.
   - A project may be untrusted. Inside a project setup never follows a link: any link below the project root makes the slot divergent, so a repository cannot redirect the write outside itself. In the home directory the client's skills directory may be the operator's own link (for example into a dotfiles checkout) and is followed; the skill entry itself is never followed.
-  - `--customize-skill` writes only below the override directory, never overwrites an existing override and never edits an operator's file. It moves the recorded base only on an explicit `--apply`, which acknowledges a reviewed change to the shipped skill.
+  - `--customize-skill` writes only below the override directory, never overwrites an existing override and never edits an operator's file. It moves the recorded base only on an explicit `--apply`, which acknowledges a reviewed change to the shipped skill. `--apply` runs under an exclusive kernel lock on `<override dir>/.pi-session-mcp-bases.lock` and replaces the bases file atomically, so concurrent runs cannot lose a base; the dry-run takes no lock and writes nothing.
   - Worker skills are not installed into clients. Reports name the skill and a stable code, never a path or content.
 - **False verification:** Verify combines Doctor and exact registration
   equality with a bounded direct MCP initialize, `tools/list`, and

package/docs/tool-contracts.md

@@ -15,6 +15,24 @@ Every response includes text JSON for broad client compatibility and the same ob
 
 There are exactly eight tools. No `pi_turn_wait` tool or live provider/model inventory exists.
 
+## Versions
+
+Three different versions exist. They identify different things and change for
+different reasons; none of them stands in for another.
+
+| Version | What it identifies | Where it appears | When it changes |
+| --- | --- | --- | --- |
+| Package version | One build and release of Pi Session MCP: the npm package, the GitHub release and the server. | `package.json`; `server.version` of `pi_capabilities_get`; `packageVersion` of the Doctor result | With every release. A release that keeps the MCP tool contract is a patch release. |
+| MCP tool contract | The eight tools of this document: their inputs, response fields, states and error codes. | Only this document. It carries no version number of its own and no tool, field or code names one. | A change to a tool, field, state or error code needs a new minor release and its own decision, so within a `0.x` minor line the contract is stable. A client identifies its compatibility by the package version, as `pi_capabilities_get` reports it, and by this document at that release. |
+| Setup report `schemaVersion` | The shape of the result of `pi-session-mcp-setup`, currently `1`; the human output derives from the same result. | The `schemaVersion` field of the `--json` report | Independent of the package version and no part of the MCP tool contract; a release does not change it by itself. It has been `1` since the first public release, and no document defines a further rule for changing it. |
+
+The setup report is not an MCP response. The Doctor result has its own
+`schemaVersion` (currently `1`), and the skill customization bases file has a
+`schemaVersion` (currently `2`) that is separate again; neither is the setup
+report's. Release rules are in [Releasing](releasing.md#versioning); acceptance
+records name the package version and the build they ran on, see
+[Acceptance](acceptance.md#evidence-rules).
+
 ## Capability discovery
 
 `pi_capabilities_get` accepts only `{}`. Unknown fields fail MCP schema validation. Success has this strict shape:
@@ -22,7 +40,7 @@ There are exactly eight tools. No `pi_turn_wait` tool or live provider/model inv
 ```json
 {
   "ok": true,
-  "server": { "name": "pi-session-mcp", "version": "0.8.0" },
+  "server": { "name": "pi-session-mcp", "version": "0.8.2" },
   "configuration": {
     "fingerprint": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
     "reloadPolicy": "restart-required"
@@ -90,7 +108,7 @@ Invalid execution-profile configuration prevents startup, so it cannot be an MCP
 
 `pi_session_prompt` returns `{session,turn}` only after successful Pi preflight. Preflight is bounded at 5,000 ms; a missing callback, hanging prompt acceptance, or timeout returns `prompt_timeout` / `Pi prompt preflight timed out` and creates no public turn. Late settlement may only release the unpublished operation's quarantine; it cannot publish a turn. `pi_session_abort` waits at most 5,000 ms per caller for one shared SDK abort attempt and returns `abort_timeout` / `Pi abort timed out` without claiming the turn was aborted. Rejection/failure remain `prompt_rejected`/`abort_failed`. Close allows at most 5,000 ms for abort cleanup, then performs best-effort disposal and removes the public registry entry; it remains idempotent through the retained tombstone. Registry shutdown rejects new starts, allows 12,000 ms, and disposes a handle from a late-resolving start instead of admitting it. Process shutdown, started by `SIGINT`, `SIGTERM`, or stdin EOF, allows 15,000 ms, attempts transport cleanup even after registry failure/timeout, then explicitly exits the process. These boundaries do not guarantee graceful cancellation of a provider request. `pi_turn_get` returns a `TurnView` with `turnId`, `sessionId`, state, timestamps, and `completedAt` for terminal turns. Completed views add normalized final `assistantText` and `truncated`; failed views contain only `{code:"turn_failed",message:"Pi turn failed"}`. Final assistant text is capped at 64 KiB UTF-8 bytes, each active session retains at most 20 turns, and close removes its turn data.
 
-While a turn runs, `updatedAt` is the controller's last-activity stamp: it advances after each completed tool execution and each completed assistant message, then freezes at the terminal transition. It is a liveness lower bound only. A stamp that has not moved can still be a working turn (a long model response, thinking, or a first token), so it never justifies a claim that a turn is hung; it is a wall-clock ISO-8601 millisecond stamp for ordering, not a progress count, duration, or step total, and activity within one millisecond simply reuses the stamp. It is never derived from event payloads.
+While a turn runs, `updatedAt` is the time of the last observed public SDK activity of that turn: assistant message start, streaming updates and end, and tool execution start, update and end. It freezes at the terminal transition. The `updatedAt` of the session does not follow this activity: it moves when a turn starts and at its terminal transition. It is a liveness lower bound only. Streaming is activity, not evidence of finished or useful work. Work without a public event, such as the internal steps of an extension's own agent loop or a long tool call without updates, stays invisible, so a stamp that has not moved can still be a working turn (a long model response, thinking, a first token, or a long tool call) and never justifies a claim that a turn is hung. The stamp is a wall-clock ISO-8601 millisecond value for ordering, not a progress count, duration, or step total, and activity within one millisecond simply reuses the stamp. Only the type of an event and the role of its message are inspected: no delta, thinking block, tool argument, or partial result is stored or projected, and the answer still comes only from the final assistant message.
 
 Context usage stays out of the boundary: no token, usage, context-window, or cost figure is projected for a running or terminal turn, so approaching context exhaustion remains invisible in the turn view and in `pi_session_get`. This change adds no progress counters, tool names, arguments, results, or transcripts; see *Failure causes* below for failure-cause classification, which is not part of the turn view and is decided in *Failure causes* below.
 

package/package.json

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

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

@@ -11,7 +11,7 @@ You control Pi worker sessions through the pi-session-mcp tools. You choose only
 
 - Call `pi_capabilities_get` before anything else in a run. Use only the workspace and profile aliases it lists. Never invent an alias or pass a path.
 - Each profile lists `permissionProfile` (`read-only` or `coding`), `extensions` and `skills`. `skills` names the configured skill aliases. That is configuration intent only. It does not prove that a session loaded the skill or that the model will read it.
-- Capabilities do not prove that a provider or model is reachable. The first `pi_session_start` is the real check.
+- Capabilities do not prove that a provider or model is reachable. A successful `pi_session_start` shows that the session was created with the selected provider, model and thinking level, and that local authentication, the extensions, external MCP servers and selected skills passed their start checks. It does not prove that the provider accepts requests: credentials, quota and network show only when a turn runs.
 
 ## 2. Scope each task
 
@@ -56,7 +56,7 @@ Keep an internal ledger with one row per task: task, workspace alias, profile al
 
 ## 7. Interpret progress and results
 
-- `updatedAt` on a running turn is a last-activity stamp. A stamp that has not moved is not proof of a hang: the model may be thinking or writing a long answer. Judge by your time budget, not by `updatedAt` alone.
+- `updatedAt` on a running turn is the time of the last observed public SDK activity: assistant message start, streaming updates and end, and tool execution start, update and end. Streaming is activity, not evidence of finished or useful work. Work without a public event stays invisible, for example inside an extension's own agent loop or in a long tool call without updates. A stamp that has not moved is therefore no proof of a hang. Judge by your time budget and by the workspace.
 - `completed` is a technical state: the turn ended and returned text. It does not mean the task succeeded. Read `assistantText` and check `truncated`.
 - Never accept a worker report as proof. A worker saying the tests pass is a claim, not evidence.
 
@@ -77,8 +77,12 @@ You integrate. Workers never integrate each other's changes. Resolve conflicts b
 - `failed` means `turn_failed`. The error carries no cause. Check the result in the workspace, then retry once in a fresh session with a narrower prompt, or take the task over yourself.
 - `aborted` means the turn stopped. Look at what the workspace contains before reusing it.
 - `pi_session_abort` returns `abort_failed` if the abort was rejected. The turn may still be running. Poll it.
-- `abort_timeout` is not a successful abort. The turn may still be running or may finish normally. Poll `pi_turn_get` until it is terminal. If it stays `running`, close the session with `pi_session_close` and treat the workspace as unverified until you inspect it.
-- On `pi_session_start` errors such as `unknown_execution_profile`, `skill_load_failed` or the `extension_*` and `external_mcp_*` codes, do not retry blindly. The cause is configuration. Report it to the operator.
+- `abort_timeout` is not a successful abort. The turn may still be running or may finish normally. Decide an observation and cleanup budget before you abort, for example a fixed number of polling rounds within a few minutes. Poll `pi_turn_get` until the turn is terminal or the budget is spent, then close the session with `pi_session_close`. If the close fails or does not finish, stop using that workspace, treat it as unverified and report it. Never wait without a bound.
+- Classify every `pi_session_start` error by its `code` alone. Never decide by the message, provider text or any other free text, and never infer a cause. Each code below is in exactly one class:
+  - Operator needed (do not retry and do not switch to another profile; report the code and stop that task): `unknown_execution_profile`, `unknown_workspace`, `unknown_provider`, `unknown_model`, `model_unavailable`, `thinking_level_unavailable`, `local_authentication_missing`, `execution_selection_mismatch`, `skill_load_failed`, `extension_not_installed`, `extension_version_mismatch`, `extension_tool_conflict`, `external_mcp_no_tools`, `external_mcp_grant_tool_missing`, `external_mcp_activation_mismatch`, `server_stopping`. The last code means the server is shutting down: a new server process is needed, not a retry.
+  - Transient (retry at most once after a pause, then report): `external_mcp_unavailable` (an external MCP server that cannot connect, times out or breaks the protocol), `extension_load_failed` (an invalid package, but also a start timeout), `local_authentication_unavailable` (local authentication could not be resolved within its deadline).
+  - Unknown (report the code; at most one retry in a fresh session): `pi_session_creation_failed`. Any code not listed above is also unknown.
+- If the pi-session-mcp tools are missing entirely, the server did not start. Its stderr names a `startup_failed` diagnostic (`invalid_execution_profile_config` or `invalid_thinking_level`). No MCP server is available; the operator must fix the configuration.
 
 ## 10. Close every session