pi-session-mcp 0.8.1 → 0.8.3

package/docs/acceptance.md

@@ -16,6 +16,16 @@ Provider-free tests exercise the real Pi SDK and real stdio child processes with
 a scripted model. They do not establish live client or model acceptance. State
 only what was run.
 
+Targeted live checks are not a level. The [Pi extension live
+check](#pi-extension-live-check) and the [multi-session skill
+acceptance](#multi-session-skill-acceptance) use a real provider and model on one
+path with one or two sessions: the first drives the server with a scripted
+client, the second with one real controller. They are not a Level 3 cycle,
+do not count towards its [gate](#gate) and do not replace it. A record of one
+of them never says that Level 3 passed. What a package version, the MCP tool
+contract and a setup report `schemaVersion` identify is defined in [tool
+contracts](tool-contracts.md#versions).
+
 ## Level 1: repository checks
 
 Run on a clean checkout of the exact source under test:
@@ -24,7 +34,7 @@ Run on a clean checkout of the exact source under test:
 npm ci
 npm run typecheck
 npm run build:cli
-npm test
+NODE_OPTIONS=--unhandled-rejections=strict npm test
 npm run build
 npm audit
 git diff --check
@@ -122,6 +132,17 @@ prefix (`npm install -g --prefix <dir> pi-session-mcp@<version>`) and runs the
 lifecycle through the installed `pi-session-mcp-setup`, which also proves the
 executables and the entry-point detection through npm's symlinks.
 
+A packed-tarball run installs the tarball of the release candidate, before it is
+published, into a fresh temporary prefix (`npm pack`, then
+`npm install -g --prefix <dir> ./pi-session-mcp-<version>.tgz`, with `<dir>`
+created by `mktemp -d` and removed afterwards) and runs the lifecycle through
+the installed `pi-session-mcp-setup`. It is the only acceptance-level
+pre-release check that resolves dependencies like a consumer install does,
+without our lockfile, before publication. The working-tree run and the CI build
+cannot prove that, because they install from the lockfile; the CI install smoke
+also resolves fresh, but it is an early warning, not acceptance. The packed
+tarball run is the pre-release counterpart of the published-package run.
+
 A published-release run uses a fresh clone of the published tag instead of an
 existing branch or local tag. It additionally records the tag object and the
 peeled commit, confirms `git describe --tags --exact-match`, passes Level 1 on
@@ -169,6 +190,35 @@ node scripts/setup-acceptance.mjs \
   --label npm-<version> --out level2-result.json
 ```
 
+Packed tarball: pack the built candidate and install the tarball into a fresh
+temporary prefix outside `/tmp`, then pass the installed executable and package
+directory as for the published package. Create the prefix with `mktemp -d`,
+never reuse a fixed one, and remove it and the tarball afterwards.
+
+```bash
+npm pack
+PREFIX="$(mktemp -d "$HOME/.cache/pi-session-mcp-pack.XXXXXX")"
+npm install -g --prefix "$PREFIX" ./pi-session-mcp-<x.y.z>.tgz
+node scripts/setup-acceptance.mjs \
+  --setup "$PREFIX/bin/pi-session-mcp-setup" \
+  --build-dir "$PREFIX/lib/node_modules/pi-session-mcp" \
+  --label packed-<x.y.z> --out level2-result.json
+rm -rf "$PREFIX" ./pi-session-mcp-<x.y.z>.tgz
+```
+
+The CI job and a nightly workflow (`.github/workflows/install-smoke.yml`) run
+`scripts/install-smoke.mjs` against a lockfile-free install: CI against the
+packed tarball of the commit, the nightly job against the published
+`pi-session-mcp@latest`. The smoke starts the installed server, checks the
+handshake, its name and version and the eight tools, and requires it to exit by
+itself with status 0 after stdin EOF. It starts no session and uses no provider.
+It reports one JSON line whose code is `smoke_passed` or one of
+`package_invalid`, `server_exited`, `initialize_invalid`, `tools_invalid`,
+`stdout_invalid`, `shutdown_timeout`, `shutdown_failed` or `timeout`. On any
+failure it kills the server's whole process group. Both are early warnings for
+a broken fresh install, not acceptance and not a replacement for the
+packed-tarball run.
+
 Tag clone: build a fresh clone of the tag (`npm ci`, `npm run build`,
 `npm run build:cli`) and use it like the working tree, with `--setup` and
 `--build-dir` pointing at the clone.
@@ -316,6 +366,11 @@ external MCP grants, and client restart or resume.
 A narrower live check can cover a single path. It must state its scope and does
 not count as a ten-task cycle.
 
+This applies to the two-session records below: the extension live check
+started two sessions and the multi-session acceptance drives two concurrent
+sessions from one controller. Both are targeted evidence, not a Level 3 cycle,
+and no number of such runs adds up to the gate.
+
 ## Pi extension live check
 
 Manual, on a machine with Pi, `pi-cursor-sdk@0.5.3` and a stored Cursor key. Run it from a working tree (`npm run build`, then `node dist/main.js`) with a temporary configuration, passed through `PI_SESSION_MCP_CONFIG`, whose profile names `"extensions": ["npm:pi-cursor-sdk@0.5.3"]` and a Cursor model from Pi's catalog.
@@ -328,6 +383,9 @@ Manual, on a machine with Pi, `pi-cursor-sdk@0.5.3` and a stored Cursor key. Run
 
 Record date, source commit, versions and outcome under Status. No secret, path or prompt content goes into the record.
 
+This check is targeted. Its two parallel sessions show that the extension path
+works for the recorded build, provider and model. They are not a Level 3 cycle.
+
 ## Multi-session skill acceptance
 
 A targeted live check for profile skill selection ([skills](skills.md)) and for
@@ -347,8 +405,12 @@ Pi Session MCP tools; the script never does.
   `dist/`; `run` refuses a changed build.
 - Configuration: `prepare --base-config <operator config> --from-profile
   <alias>` copies only provider, model and thinking level of the one explicitly
-  selected profile into a run configuration with two profiles: `accept-read` (default, `read-only`, skill `review`) and
-  `accept-code` (`coding`, skills `implementation` and `handshake`). From the
+  selected profile into a run configuration with the profiles `accept-read` (default, `read-only`, skill `review`) and
+  `accept-code` (`coding`). From the Sprint 2 harness (#68) on, `accept-code`
+  selects exactly `implementation` and is used for every task except `slug`,
+  and a second coding profile `accept-code-handshake` selects `implementation`
+  and `handshake` and is used only for the `slug` session; before, `accept-code`
+  carried both skills for every task. From the
   harness of `3f98104` on, all three are `builtin:` references: the two worker
   skills ship with the candidate, and the `handshake` skill sits in the
   override directory `skills/` next to the run configuration, so the run also
@@ -357,16 +419,18 @@ Pi Session MCP tools; the script never does.
   `mcpServers` is always rejected. A profile with `extensions` is rejected
   unless `--with-extensions` is given; with it, `prepare` also copies exactly
   that profile's extension allowlist (1 to 8 distinct exact
-  `npm:<name>@<version>` pins) into both run profiles and installs nothing.
+  `npm:<name>@<version>` pins) into every run profile and installs nothing.
   `--with-extensions` on a profile without extensions is rejected. Nothing else
   is copied: the run has its own workspaces and skills.
 - Working directory: `--work-dir` (default `~/.cache/pi-session-mcp-acceptance`)
   must not be inside a temporary directory (the system temporary directory,
   `/tmp`, `/var/tmp` or `/dev/shm`), because Codex refuses helper binaries
   there.
-- Fixtures: four small synthetic git repositories per client (`slug`, `stats`,
-  `wait`, `range`), each a separate workspace alias (`cc-*` for Claude Code,
-  `cx-*` for Codex). Both clients use the same configuration and build.
+- Fixtures: five small synthetic git repositories per client (`slug`, `stats`,
+  `wait`, `range` and, from the Sprint 3 harness (#71) on, `review`), each a
+  separate workspace alias (`cc-*` for Claude Code, `cx-*` for Codex). `review`
+  holds a finished, frozen implementation that only the read-only reviewer of
+  `trio` uses. Both clients use the same configuration and build.
 - Fixture baselines: when it creates a fixture, `prepare` stores its initial
   commit and a manifest of its files (path, type, mode, SHA-256; without
   `.git/`) under the run's private directory, never inside the worker's
@@ -381,7 +445,31 @@ Pi Session MCP tools; the script never does.
   home (`~/.claude/skills` and `~/.agents/skills`, recorded as missing when
   absent). `run` rechecks all of them before the launch and again after the
   run. A change before the launch refuses the run; a change after it fails the
-  result with `resourcesChanged`.
+  result with `resourcesChanged`. From the Sprint 2 harness (#66, #67) on it
+  also binds, under path-free names: per allowlisted extension the tree of its
+  real package root (`extension:<name>`) and the whole npm installation of
+  Pi's agent directory, with dependencies, `package.json` and lockfile
+  (`extensionNpmInstallation`, `none` without extensions); and every Codex
+  skill source besides the run's own link: `$CODEX_HOME/skills` with the
+  bundled `.system` skills (`codexHomeSkills`), all of `~/.agents/skills`
+  (`homeAgentsSkills`), `/etc/codex/skills` (`etcCodexSkills`) and the
+  `.agents/skills` of every ancestor of the Codex controller's directory
+  (`codexAncestorSkills`, up to `/`). These extension, Codex source and
+  candidate skill digests (the controller skill and both worker skills) walk a
+  tree without following links, record every link's text, and for a link
+  whose real path lies outside the bound root also bind what it leads to (the
+  file's bytes, or the same digest of the target directory, recursively); a
+  link that stays inside the root needs only its text. Each real directory is
+  digested once, so link cycles end, and at most 200,000 entries are read. A
+  value of `unreadable` or `tooLarge` means that a resource cannot be bound
+  completely. For every key, composed ones included, `prepare` then refuses and
+  names the key, and `run` refuses before the launch with `resourcesUnbound`.
+  `missing`, `none`, `notDirectory`, `unset` and a dangling top-level link are
+  determinate values and stay allowed. The other resources keep the plain tree
+  digest. `prepare` resolves Pi's
+  agent directory (`PI_CODING_AGENT_DIR`, else `~/.pi/agent`) and `CODEX_HOME`
+  (else `~/.codex`) once and records both only in the run's private data; they
+  never appear in a result or the evidence.
 - Home controller skills: Claude Code prefers a personal skill over a project
   skill of the same name. With `--setting-sources project,local`, as the
   harness starts it, Claude Code `2.1.296` listed only the project copy when a
@@ -389,8 +477,25 @@ Pi Session MCP tools; the script never does.
   without that flag the personal copy shadowed the project copy. Re-check this
   when the client version changes. Codex's precedence between its home skills
   and the run's repository skill is not established, so a Codex run is refused
-  while `~/.agents/skills/pi-session-orchestration` differs from the
-  candidate's skill.
+  while any bound Codex skill source (`$CODEX_HOME/skills`,
+  `~/.agents/skills`, `/etc/codex/skills` or an ancestor's `.agents/skills`)
+  holds a controller skill whose resolved content differs from the
+  candidate's. A controller skill is a directory named
+  `pi-session-orchestration` or one whose `SKILL.md` frontmatter declares that
+  `name:`. The frontmatter is read as a YAML block mapping whose top-level keys
+  are those at the indentation of its first content line; `name` may be a plain
+  or quoted scalar, and a ` #` comment outside quotes is ignored. Any other
+  form (a flow mapping or sequence, a bare scalar, a dedent or tab
+  indentation, a block or multi-line scalar, malformed quoting, a duplicate
+  `name`, unclosed frontmatter), and a `SKILL.md` that is not a regular file,
+  make the skill indeterminate, so its source counts as differing. Only the
+  first 16 KiB of a `SKILL.md` are read, after its type was checked. The
+  bounded search includes hidden directories such as `.system` and
+  follows links. An equal copy, also behind a link, or none is allowed; a
+  source that cannot be searched completely refuses the run. Skills that Codex
+  might load by other means, such as other file names or plugin caches, are
+  not covered. Before the Sprint 2 harness only
+  `~/.agents/skills/pi-session-orchestration` was checked.
 - Launch record and failed analysis: `run` records the launch once before the
   controller starts, so an attempt that ends without a result is never repeated
   silently. If the analysis after the controller fails, the result is recorded
@@ -410,7 +515,10 @@ Pi Session MCP tools; the script never does.
   the shipped skill. Codex installs skills only in the user's home, which the
   run must not change, so the Codex controller gets one run-scoped symbolic link
   in `.agents/skills` of its directory. Earlier runs linked both. No global
-  skill directory changes.
+  skill directory changes. From the Sprint 2 harness (#67) on, the evidence
+  records per client the kind of controller skill, `installed` for Claude Code
+  and `linked` for Codex, with its tree digest and without paths
+  (`controllerSkills`).
 - Clients: Claude Code runs as `claude -p` with `--mcp-config`,
   `--strict-mcp-config`, `--setting-sources project,local`,
   `--permission-mode dontAsk` and an `--allowedTools` list of the eight tools
@@ -418,8 +526,19 @@ Pi Session MCP tools; the script never does.
   `codex exec --ignore-user-config --sandbox read-only` with the server
   defined through `-c mcp_servers.pi-candidate.*` and the three per-tool
   approvals from [client setup](client-setup.md#run-codex-without-prompts).
-  Neither run changes a persistent registration, `HOME` or `CODEX_HOME`, and
-  both use the existing authentication.
+  The harness changes neither a persistent registration, `HOME` nor the
+  contents of `CODEX_HOME`, and both runs use the existing authentication.
+  Codex itself can install its bundled `.system` skills into
+  `$CODEX_HOME/skills` on its first start after an upgrade, or create that
+  directory in a fresh `CODEX_HOME`. Because those skills are bound, such a
+  change invalidates the prepared run for both clients; it fails safe and never
+  passes. After a Codex upgrade, start Codex once with the same `CODEX_HOME`
+  before `prepare`. From the Sprint 2
+  harness (#66, #67) on, the Codex controller runs with exactly the
+  `CODEX_HOME` that `prepare` recorded, whatever the launching environment
+  holds, and the server of both clients receives the recorded Pi agent
+  directory as `PI_CODING_AGENT_DIR`, so the bound extension directory is the
+  one the server loads from.
 - Time limit: `run --timeout-min` takes a number above 0 and at most 180
   (default 25). After the limit the harness sends `SIGTERM` to the client's
   process group and waits up to 10 seconds. It then sends `SIGKILL` to that
@@ -435,12 +554,14 @@ Pi Session MCP tools; the script never does.
 
 ### Scenarios
 
-Each client runs two invocations, one per scenario:
+Each client runs one invocation per scenario: `parallel` and `abort`, and from
+the Sprint 3 harness (#71) on also `trio`:
 
 | Scenario | What the controller does | What is checked |
 | --- | --- | --- |
-| `parallel` | Capabilities first; two sessions of `accept-code` on `slug` and `stats`; both first turns started before waiting; one follow-up in the `slug` session that adds a test and completes the handshake from the worker's skills; own verification; close both | Candidate version and configuration fingerprint seen through capabilities; `skills` of `accept-code`; first turns overlap by the server's `startedAt` and `completedAt`; follow-up completed; tests pass and only allowed files changed; handshake file holds the token although no prompt contained it |
-| `abort` | Two sessions on `wait` (a bounded `sleep 120` command) and `range` (a bounded `sleep 45`, then the change); abort `wait` about 15 seconds after both turns started, while `range` runs; verify and close both | Every abort result is `ok` (an `abort_timeout` stays on record even after a retry); the first successful abort comes before `pi_turn_get` shows the `wait` turn `aborted`, and both before its session is closed; its abort time lies inside the running interval of `range`; `range` completed and verified; at the end of the run no late file exists and no worker `sleep` remains |
+| `parallel` | Capabilities first; a session of `accept-code-handshake` on `slug` and one of `accept-code` on `stats` (before the Sprint 2 harness: `accept-code` for both); both first turns started before waiting; one follow-up in the `slug` session that adds a test and completes the handshake from the worker's skills; own verification; close both | Candidate version and configuration fingerprint seen through capabilities; `skills` of both coding profiles and the profile of each session; first turns overlap by the server's `startedAt` and `completedAt`; follow-up completed; tests pass and only allowed files changed; handshake file holds the token although no prompt contained it |
+| `abort` | Two sessions of `accept-code` on `wait` (a bounded `sleep 120` command) and `range` (a bounded `sleep 45`, then the change); abort `wait` about 15 seconds after both turns started, while `range` runs; verify and close both | Every `pi_session_abort` call of the transcript is `ok` and targets the `wait` session (an `abort_timeout`, an unknown session id or an abort on `range` stays on record and fails, also after a retry); the first successful abort comes before `pi_turn_get` shows the `wait` turn `aborted`, and both before its session is closed; its abort time lies inside the running interval of `range`; `range` completed and verified; at the end of the run no late file exists and no worker `sleep` remains |
+| `trio` | Capabilities first; three sessions whose first turns start in the order `review`, `slug`, `wait`, all before waiting for any: `accept-read` on `review` (an enumerated read-only review of the frozen `review` fixture, one finding per exported function with a line reference), `accept-code` on `slug` (a bounded `sleep 45`, then the change, only in `src/slug.js`) and on `wait` (a bounded `sleep 120`); abort `wait` about 5 seconds after its turn was accepted, while `slug` and `review` run; own verification of `slug`; confirm `review` changed nothing; close all three; no handshake | Candidate version and configuration fingerprint seen through capabilities; three sessions, each on its expected alias and profile; `accept-read` offers exactly `review` and only the `review` session used it; all three first turns overlap; every `pi_session_abort` call is `ok` and on `wait`, the first successful abort comes before `wait` is seen `aborted`, both before close; the abort lies inside the running intervals of both `slug` and `review`; `slug` and `review` completed; `slug` tests pass; the `review` fixture is byte-identical in working tree, index and `HEAD`, with no empty directory; `wait` leaves no late file; no worker `sleep` remains |
 
 ### Independent checks
 
@@ -482,6 +603,8 @@ Each client runs two invocations, one per scenario:
   - the controller exit code is 0 (`controllerExit`), neither `timedOut`,
     `spawnFailed` nor `harnessAborted` is set, and the analysis finished
     (`analysisFailed`);
+  - every bound resource was completely readable when recorded and after the
+    run (`resourcesUnbound`);
   - no bound resource changed after the run (`resourcesChanged`), and for a
     reanalysis no resource or fixture differs from the state recorded at the
     end of the run (`stateChangedSinceRun`);
@@ -489,8 +612,15 @@ Each client runs two invocations, one per scenario:
     process of the run remains (`residualProcesses`);
   - the controller called `pi_capabilities_get` first (`capabilitiesNotFirst`),
     saw the candidate version and configuration fingerprint
-    (`candidateNotConfirmed`) and saw exactly the skills `implementation` and
-    `handshake` on `accept-code` (`workerSkills`);
+    (`candidateNotConfirmed`), saw exactly the skill `implementation` on
+    `accept-code` and exactly `implementation` and `handshake` on
+    `accept-code-handshake`, and only the `slug` session used
+    `accept-code-handshake` while every other session used `accept-code`
+    (`workerSkills`; before the Sprint 2 harness: exactly `implementation` and
+    `handshake` on `accept-code`). In `trio` there is no handshake: `slug` and
+    `wait` use `accept-code`, `accept-read` offers exactly `review`, and only the
+    `review` session may use `accept-read`; in `parallel` and `abort` no session
+    uses `accept-read`;
   - the structural leak scan found nothing (`structuralLeaks`), the token
     appears nowhere it must not (`tokenExposed`), and no worker prompt or
     controller action touched a private marker (`privateAccess`);
@@ -499,13 +629,31 @@ Each client runs two invocations, one per scenario:
     overlapped (`noOverlap`) and the follow-up completed
     (`followUpNotCompleted`);
   - `abort`: the `wait` turn ended `aborted` after only successful aborts
-    (`abortFailed`), in the required order and before its session closed
+    (`abortFailed`), every abort call on the `wait` session
+    (`offTargetAbort`), in the required order and before its session closed
     (`abortOrder`), and `range` completed with the abort inside its running
     interval (`neighborNotRunningDuringAbort`);
+  - `trio`: exactly three sessions started (`sessionsNotStarted`), each on its
+    expected workspace alias and profile (`sessionAssociation`); the `slug` and
+    `review` first turns completed (`firstTurnsNotCompleted`) and all three
+    first turns overlapped (`noOverlap`); the `wait` turn ended `aborted` after
+    only successful aborts (`abortFailed`) and only on `wait`
+    (`offTargetAbort`), in the required order and before
+    close (`abortOrder`), with the abort inside the running intervals of both
+    `slug` and `review` (`neighborsNotRunningDuringAbort`); the `review` fixture
+    is unchanged in working tree, index and `HEAD`, `HEAD` is still its base
+    commit, and no empty directory appeared (`review:readOnly`); the `slug`
+    task of `trio` may change only `src/slug.js`, while `test/slug.test.js`
+    and `HANDSHAKE.txt` stay allowed in `parallel` only. The read-only check
+    compares the end state with the baseline, so a write reverted before the
+    end, a `git stash`, new refs or branches and directory-mode changes are not
+    seen; the read-only profile is the actual guard;
   - per fixture: only allowed changes (`<task>:changes`), every change written
     during a worker turn (`<task>:attribution`), fixture tests and business
-    checks passing (`<task>:tests`), for `slug` the added test and the
-    handshake (`slug:followUp`), for `wait` no late file (`wait:lateFile`),
+    checks passing (`<task>:tests`), for `slug` in `parallel` the added test
+    and the handshake (`slug:followUp`), for `review` the read-only invariance
+    (`review:readOnly`) instead of tests, for `wait` no late file
+    (`wait:lateFile`),
     and an oracle for every task of the scenario (`oracleMissing`).
 - Liveness observation: for each turn of a session, `turnLiveness` records the
   number of `pi_turn_get` polls that saw the turn `running` and whether
@@ -530,7 +678,8 @@ Each client runs two invocations, one per scenario:
 - `evidence` writes one sanitized JSON record and refuses to write a local path
   or the token. It lists the original results and the reanalyses separately,
   lists every launch with whether it left a result, and includes the extension
-  names and versions and the resource digests.
+  names and versions, the resource digests, the profiles and, from the Sprint 2
+  harness on, the controller skill kinds and digests.
   Transcripts and the configuration stay in the run's private directory and
   are never published.
 
@@ -555,6 +704,19 @@ limits, which that change removed:
   client to close without a bound. A hang would have shown as a hang, not as a
   pass.
 
+Records made with the harness before Sprint 2 (#66, #67, #68) have these
+further method limits:
+
+- Pi extensions were bound by name and version only, not by the package
+  contents the server loaded, and the run's server did not receive the agent
+  directory explicitly.
+- For Codex, only `~/.agents/skills/pi-session-orchestration` was checked;
+  `$CODEX_HOME/skills`, `/etc/codex/skills`, other home skills and ancestor
+  `.agents/skills` were neither bound nor excluded, and the controller
+  inherited `CODEX_HOME` from the launching environment.
+- The `handshake` skill was offered to every task's worker; this is how the
+  v0.8.1 Codex `abort` run's worker could apply it to an unrequested file.
+
 These limits do not show that any recorded result was wrong. The records stay
 as recorded; a new run gets a new record.
 
@@ -573,6 +735,13 @@ as recorded; a new run gets a new record.
 
 ## Status
 
+Targeted records below, the Pi extension live check and the multi-session
+skill acceptance with one or two concurrent sessions, are not Level 3 cycles
+even where they used a real controller or a real model. The wording "passed all
+three levels" refers to earlier private cycles only; the full ten-task Level 3
+cycle has not been repeated on Pi SDK `1.x`. This note adds no result and
+changes none.
+
 Release notes state which levels were run for a release and what was not
 covered. Pi Session MCP has passed all three levels in earlier private cycles. The
 live two-client acceptance has not yet been repeated on a build with Pi SDK
@@ -1204,3 +1373,361 @@ release candidate `baa6406` on Linux (`x64`), with Node.js `26.11.1`, Codex CLI
   `0c7bad3`. Its built modules have the same dist tree SHA-256
   (`7b16757f9a1a0318247914f56debe79119a3845e1a1debcf1ad371db3a958fce`) as the
   final candidate `1e904be` of the multi-session acceptance recorded above.
+
+### v0.8.1 post-release evidence carried over from the release notes
+
+The post-release results of `v0.8.1` were recorded in the [v0.8.1 release
+notes](https://github.com/plagor44-ux/pi-session-mcp/releases/tag/v0.8.1),
+published on 2026-10-12 (22:06 UTC), and were carried over into this document
+on 2026-10-13 as roadmap item R19. This is a historical record taken from
+those notes: the checks were not rerun for it, and every item below keeps the
+scope, result and limitation that the notes state. The pre-release results of
+the same release candidate are recorded above.
+
+Source and CI, as stated in the notes:
+- Release source and annotated tag target: `e462054a37505ef00e1e0c549ebab27e4db7ef55`,
+  the merge of #55 (head `440f2e4ccb4f7cebd88825abd8515218f4bbbdee`). The
+  annotated tag object is `02f0b30588115058fbb30148cb0934f18cf05aa3`.
+- #55 passed CI on Linux, macOS 15 and macOS 26. The merged-main CI run
+  `38309519719` and the tag CI run `38309738675` are named in the notes. CI is
+  neither Level 2 nor Level 3 acceptance.
+
+Provider-free (Level 1), on a fresh clone of the tag, with Node.js `26.11.1`
+and npm `12.2.0`. Every command exited with `0`:
+- Typecheck, server build and CLI build.
+- 50 test files: 1035 passed and 6 skipped.
+- `npm audit` and `npm audit --omit=dev`: 0 vulnerabilities.
+- Offline Doctor: package version `0.8.1`. With the example configuration, the
+  only finding was its placeholder workspace.
+
+Package publication, a release fact and not an acceptance level: the npm
+package `pi-session-mcp@0.8.1` was published from a fresh clone of the tag
+through staged publishing, approved by the maintainer. It has 129 files and
+215.6 kB, with shasum `b39fe48aff6ade4bf52c427960593951e150191b`. The tarball
+downloaded from the registry has the same SHA-1 and SHA-512 integrity. The
+package has no provenance attestation, because it was published from the
+maintainer's machine.
+
+Real clients without a model (Level 2), with `scripts/setup-acceptance.mjs`:
+160 of 160 checks passed in each of three variants:
+- the release candidate's working tree (`baa6406`);
+- a fresh clone of the tag;
+- the npm package installed into a temporary prefix.
+
+The clients were Codex CLI `0.162.1` (`user`) and Claude Code `2.1.296`
+(`user`, `project`, `local`), in disposable homes. The real client
+registrations were unchanged, no process remained, and the build stayed
+byte-identical. The notes do not state the platform of these variants; the
+pre-release run of the candidate above states Linux (`x64`).
+
+Real model, targeted multi-session skill acceptance (not a Level 3 cycle), on
+the final code candidate `1e904be`, whose built modules equal this release's
+(dist tree SHA-256 `7b16757f…`, abbreviated in the notes; the full value is
+recorded above). The detailed record is in the multi-session section above.
+- Controllers: Claude Code `2.1.296` and Codex CLI `0.162.1`. Workers: Cursor
+  (`pi-cursor-sdk@0.5.3`, `composer-2.5`) on Pi SDK `1.1.0`.
+- Both required Claude Code scenarios passed every check: two overlapping
+  sessions with a same-session follow-up, and a targeted abort while the
+  neighbor kept running.
+- `updatedAt` had moved past `startedAt` in every Cursor turn polled while
+  running: 31 of 31 across four runs.
+
+Limitations and failures stated in the notes:
+- No full ten-task Level 3 cycle. The multi-session check is targeted.
+- Live acceptance ran on Linux only, with Cursor (`pi-cursor-sdk@0.5.3`,
+  `composer-2.5`) workers. macOS is covered by CI.
+- Not live-proven: a Codex controller reading the skill from a copy installed
+  in `~/.agents/skills`; a third concurrent or `read-only` worker; a real crash
+  in the middle of a setup skill update (provider-free tests cover it).
+- In the final run, the supplementary Codex `abort` invocation failed its scope
+  check: the Cursor worker applied the `handshake` test skill on its own. The
+  required Claude Code invocations and Codex `parallel` passed, and Codex
+  `abort` had passed on earlier runs of the same build.
+
+### v0.8.2 pre-release acceptance
+
+Before its release, `v0.8.2` passed Level 1 and the working-tree Level 2 on its
+release candidate `bdbdf00` on Linux (`x64`), with Node.js `26.11.1`, Codex CLI
+`0.162.1` and Claude Code `2.1.296`, on 2026-10-13:
+- Level 1 on the release branch: every command exited with `0`.
+  - The test run, with `NODE_OPTIONS=--unhandled-rejections=strict`, reported
+    54 files, 1409 passed and 6 skipped, and no unhandled error.
+  - `npm audit` and `npm audit --omit=dev` reported 0 vulnerabilities.
+  - `npm pack --dry-run` listed 135 files, including the three skills, and
+    no acceptance harness, sources, tests, lockfile or implementation plan.
+  - Doctor reported `packageVersion` `0.8.2`. With the example configuration
+    its only finding was the placeholder workspace.
+- Level 2 through `scripts/setup-acceptance.mjs` on the candidate's working
+  tree: 160 of 160 checks passed. All nine steps passed on all four targets.
+  The real client registrations were unchanged, no process remained, and the
+  built files were unchanged.
+- Apart from the version and documentation, the candidate's sources equal
+  `166ffef`, current main; its runtime sources (`src/`, `skills/`) equal
+  those of `0aae639`, on which Sprint 3 ran. Its built modules have the same
+  `dist/main.js` SHA-256 (`47875d38886528ace6b242df2c6ad79d624c51e330e63c2f401576eadc449ed7`)
+  and `dist` tree as the build on which the
+  [Sprint 3 live acceptance](#sprint-3-live-acceptance-2026-10-13) ran, including
+  the accepted ten-task Level 3 cycle.
+
+### v0.8.2 post-release evidence
+
+The published-release acceptance of `v0.8.2` ran on 2026-10-15 from 15:36 UTC
+on Linux (`x64`) with Node.js `26.11.1`, npm `12.2.0`, Codex CLI `0.162.1` and
+Claude Code `2.1.299`. It **failed** for the installed npm package; the tag
+passed. The failure is recorded as it happened and is tracked as
+[#78](https://github.com/plagor44-ux/pi-session-mcp/issues/78).
+
+Tag binding: a fresh clone of the annotated tag `v0.8.2` (tag object
+`d068067539a5cf86917e0be08014c9535dce0cc2`) peels to
+`bdfb95de9a46defa64d2eb382d58d454f97fc8fb`, the merge of #76, and
+`git describe --tags --exact-match` reports `v0.8.2`.
+
+Provider-free (Level 1), on that clone. Every command exited with `0`:
+- 54 test files: 1409 passed and 6 skipped, with strict unhandled rejections
+  and no unhandled error.
+- `npm audit` and `npm audit --omit=dev`: 0 vulnerabilities.
+- `git diff --check` and `git status --short` printed nothing.
+- Offline Doctor with the example configuration: `packageVersion` `0.8.2`;
+  its only finding was the placeholder workspace (`workspace_missing`).
+
+`package.json`, `package-lock.json`, `dist/main.js` and the whole `dist` tree
+(84 files) were byte-identical before and after the client cycles.
+`dist/main.js` has the SHA-256 of the release build
+(`47875d38886528ace6b242df2c6ad79d624c51e330e63c2f401576eadc449ed7`).
+
+Real clients without a model (Level 2), with `scripts/setup-acceptance.mjs`:
+- Tag clone: 160 of 160 checks passed; all nine steps passed on all four
+  targets. The real client registrations were unchanged, no process
+  remained, and the build stayed byte-identical.
+- npm package, installed with `npm install -g --prefix` into a temporary
+  prefix: the installed version is `0.8.2`, the registry shasum is
+  `1ab640909d8c513f3dbaad3c3691f7ce1f267945` and `dist/main.js` has the same
+  SHA-256 as above. **151 of 160 checks passed.** `--verify` (steps 5 and 8)
+  reported `mcp_unsupported` instead of `mcp_verified` on all four targets;
+  every other step passed, no process remained and the package stayed
+  byte-identical. `realRegistrationsUnchanged` was `false` (see below).
+
+Cause of the verify failure (#78): the prefix resolved
+`@earendil-works/pi-codemode` `1.2.0`, while the lockfile pins `1.1.0`. The
+pinned Pi SDK `1.1.0` declares it as `^1.1.0`, and `1.2.0` no longer exports
+`MCP_TYPESCRIPT_PREAMBLE`, which the SDK imports. Started directly, the
+installed `dist/main.js` exits with `1` and a `SyntaxError` before its first
+MCP frame; the tag clone's server answers `initialize`. Verify reports a
+server that exits before `initialize` as `mcp_unsupported`. The published
+bytes are correct; a fresh install of them is not. Installations made before
+`pi-codemode` `1.2.0` was published (2026-10-12, 23:00 UTC) keep `1.1.0` and
+start.
+
+`realRegistrationsUnchanged` `false`: the cause was not determined. Another
+process wrote the real Codex configuration file during the npm run (15:39:09
+UTC). Afterwards no real registration referenced the run's directories, the
+real setup ownership records were unchanged since 2026-10-13, and the real
+Claude Code registration still targeted the installed `0.8.1`. A live client
+that changes its registrations during a run is a known source of a false
+failure (see [Tooling](#tooling)); the check is not counted as passed.
+
+A run against the published release on 2026-10-14 was reported with exit `0`,
+but neither its variant nor its check counts were saved; it is not evidence.
+
+Result: `v0.8.2` is accepted as a release source (tag clone), not as an
+installed npm package. Fresh npm installs of `0.8.2`, and probably of every
+version that pins the Pi SDK `1.1.0`, crash at startup.
+
+### v0.8.3 pre-release acceptance
+
+Before its release, `v0.8.3` passed Level 1, the working-tree Level 2 and the
+new packed-tarball Level 2 on its release candidate `35091eb` on Linux
+(`x64`), with Node.js `26.11.1`, npm `12.2.0`, Codex CLI `0.162.1` and Claude
+Code `2.1.299`, on 2026-10-15:
+- Level 1 on the release branch: every command exited with `0`.
+  - The test run, with `NODE_OPTIONS=--unhandled-rejections=strict`, reported
+    55 files, 1425 passed and 6 skipped, and no unhandled error.
+  - `npm audit` and `npm audit --omit=dev` reported 0 vulnerabilities.
+  - `npm pack --dry-run` listed 136 files, including the three
+    skills, and no acceptance harness, sources, tests, lockfile or
+    implementation plan.
+  - Doctor reported `packageVersion` `0.8.3`. With the example configuration
+    its only finding was the placeholder workspace.
+- Level 2 through `scripts/setup-acceptance.mjs` on the candidate's working
+  tree: 160 of 160 checks passed. All nine steps passed on all four targets.
+  The real client registrations were unchanged, no process remained, and the
+  built files were unchanged.
+- Packed-tarball Level 2 (#78): the candidate's tarball, installed with
+  `npm install -g --prefix` into a fresh prefix without the lockfile, resolved
+  every `@earendil-works` package to `1.2.0` with a single copy each. The install
+  smoke reported `smoke_passed`, and Level 2 against the installed package
+  passed 160 of 160 checks, with the same unchanged registrations, process
+  and build results.
+
+Targeted live multi-session acceptance on the new Pi SDK `1.2.0`, with
+`scripts/multi-session-acceptance.mjs` (harness SHA-256 prefix `bb1620ad`) on a
+clean detached checkout of `16b2374`, the candidate before the review fixes:
+`dist/main.js` SHA-256 `47875d38…`, build digest `c5e91f70…`. Between `16b2374`
+and `35091eb` no runtime source changed; the lockfile gained only the root
+entry that pins `@earendil-works/pi-telemetry` at the `1.2.0` it already
+resolved. Strictly sequential runs on 2026-10-15 from 18:19 UTC, with
+synthetic fixtures and the worker profiles copied from the operator profiles
+without their external MCP grant:
+
+| Profile source | Extension | Controller | Scenario | Result | Duration |
+| --- | --- | --- | --- | --- | --- |
+| DeepSeek `deepseek-flash`, `high` | none | Codex `0.162.1` | `abort` | passed, no failure | 101 s |
+| DeepSeek `deepseek-flash`, `high` | none | Claude Code `2.1.299` | `parallel` | passed, no failure | 66 s |
+| Cursor `grok-4.7@256k:fast`, `high` | `pi-cursor-sdk` `0.5.3` | Claude Code `2.1.299` | `abort` | passed, no failure | 156 s |
+| Cursor `grok-4.7@256k:fast`, `high` | `pi-cursor-sdk` `0.5.3` | Codex `0.162.1` | `parallel` | passed, no failure | 146 s |
+
+Every run kept its scope, closed its sessions and left no residual process.
+The Cursor runs load the allowlisted `pi-cursor-sdk` `0.5.3`, which registers
+`before_agent_start`, whose semantics changed in SDK `1.2.0`; both passed.
+
+Not established for `0.8.3`: the ten-task Level 3 cycle on SDK `1.2.0`, the
+`trio` scenario, the operator profiles' external MCP grant, macOS on real
+hardware (R10, R11), and other providers and models. The published-release
+acceptance follows after publication.
+
+## Sprint 1 correctness checks (2026-10-13)
+
+These checks belong to [#59](https://github.com/plagor44-ux/pi-session-mcp/issues/59)
+(recovery keeps unprovable trash) and
+[#56](https://github.com/plagor44-ux/pi-session-mcp/issues/56) (verify
+diagnostics). They were run on 2026-10-13 against the Sprint 1 branch
+`fix/59-56-s1-correctness`, before merge and without a release. The
+[Sprint 1 file](sprints/2026-10-13-s1-correctness.md) holds the commands,
+source binding, before-fix evidence and review findings in full.
+
+Source: base main `3e360dd`; runtime candidate
+`fa32c22b573ff0bb0b920813bd9520bb79b025f4`, the last commit that changes `src/`
+or `test/`. Native Linux (x64), Node.js `26.11.1`, npm `12.2.0`, Codex CLI
+`0.162.1`, Claude Code `2.1.296`. No provider, model or credential was used.
+
+Provider-free (Level 1), on `fa32c22`:
+
+| Check | Exit | Result |
+| --- | --- | --- |
+| `npm ci`, `npm run typecheck`, `npm run build:cli`, `npm run build` | 0 each | |
+| `NODE_OPTIONS=--unhandled-rejections=strict npm test` | 0 | 52 files passed; 1121 tests passed, 6 skipped, 0 failed; no unhandled error |
+| `npm audit`, `npm audit --omit=dev` | 0 each | 0 vulnerabilities |
+| `git diff --check`, `git status --short` | 0 each | clean |
+| #59 counterexamples for `apply`, `remove` and `rollback` (`test/setup-skills-trash-preservation.test.ts`) and the adapted SIGKILL recovery tests | 0 | All pass. On the unfixed base 24 of the 30 counterexamples failed on the defect itself (`skill_recovered` or `skill_removed` where `skill_recovery_retained` was required). |
+| #56 counterexamples (`test/setup-verify-diagnostics.test.ts`) | 0 | All 53 pass. On the unfixed base 19 failed on the defect itself (`registration_not_equivalent` for unsupported and throwing inspections, and inspection or handshake after a failed Doctor). |
+
+On the documentation head that followed, `npm pack --dry-run` listed 132 files
+without `src/`, `test/`, lockfile or implementation plans, and a relative link
+and anchor check of the changed documentation found no problem.
+
+Real clients without a model (Level 2), on the build of the same runtime
+sources (`dist/main.js` SHA-256 `47875d38886528ace6b242df2c6ad79d624c51e330e63c2f401576eadc449ed7`):
+
+- `scripts/setup-acceptance.mjs`: 160 of 160 checks passed, exit `0`, for
+  `codex:user` and `claude-code:user`, `project` and `local` in disposable
+  homes. Real registrations unchanged, no remaining process, no path leak,
+  build unchanged.
+- New #56 negative case, outside the harness: with the client CLI not on
+  `PATH`, `--verify` reported `unsupported (unsupported)` in human and JSON
+  form and `--dry-run` reported `unsupported (unsupported)`, each with exit
+  `1`, for Codex `user` and Claude Code `user`. The registration was unchanged
+  during these steps, and no output contained a path. The same steps on the
+  built base reproduced #56 (`registration_not_equivalent`).
+
+Not established by these checks: the result on macOS (only CI covers it
+there), the final pull-request head's CI matrix, a real operating-system crash
+during a skill update (the interruption tests use a checkpoint and SIGKILL,
+the counterexamples a scripted checkpoint), and any model behavior. A dry-run
+of a pending recovery can still announce a recovery that apply retains; that
+is tracked as [#60](https://github.com/plagor44-ux/pi-session-mcp/issues/60).
+Note added in Sprint 2: #60 changes this dry-run behavior; see the
+[Sprint 2 checks](#sprint-2-evidence-checks-2026-10-13). The Sprint 1 record
+above is unchanged.
+
+Open gates that Sprint 1 does not close:
+- Level 3: no full ten-task cycle on Pi SDK `1.x`, and none for the profile
+  intended for use.
+- Current macOS Level 2 on real hardware with both clients. CI covers macOS;
+  it does not replace that.
+- Live discovery of the Codex home skill that setup installs.
+- Multi-session operation beyond two sessions, including a third concurrent
+  worker and a `read-only` worker.
+
+## Sprint 2 evidence checks (2026-10-13)
+
+These checks belong to [#60](https://github.com/plagor44-ux/pi-session-mcp/issues/60),
+[#62](https://github.com/plagor44-ux/pi-session-mcp/issues/62),
+[#63](https://github.com/plagor44-ux/pi-session-mcp/issues/63) and the harness
+issues [#66](https://github.com/plagor44-ux/pi-session-mcp/issues/66),
+[#67](https://github.com/plagor44-ux/pi-session-mcp/issues/67) and
+[#68](https://github.com/plagor44-ux/pi-session-mcp/issues/68). They ran on
+2026-10-13 on branch `fix/s2-evidence`, before merge and without a release.
+The [Sprint 2 file](sprints/2026-10-13-s2-evidence.md) holds the commands,
+before-fix evidence, every gate run and the review rounds.
+
+Source: base main `b145f8c`; final runtime candidate `923a393`, the last commit
+that changes `src/`, `scripts/`, `test/`, `skills/` or CI; native Linux
+(x64), Node.js `26.11.1`, npm `12.2.0`, Codex CLI `0.162.1`, Claude Code
+`2.1.296`. No provider, model or credential was used.
+
+Provider-free (Level 1), on the documentation head `07f56b6` of that runtime:
+`npm ci`, typecheck, `build:cli`,
+`NODE_OPTIONS=--unhandled-rejections=strict npm test` (54 files; 1300 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`. On the unfixed base, the new #60 counterexamples
+failed 14 of 23 on the defect itself (`skill_recovery_planned` where
+`skill_recovery_retained` was required).
+
+Pi SDK canary: the published `1.2.0` is compatible with the candidate's
+sources (typecheck and the 12 SDK-facing test files passed); the pin stays
+`1.1.0`. This is not an SDK update.
+
+Real clients without a model (Level 2): `scripts/setup-acceptance.mjs` passed
+160 of 160 checks, exit `0`, on the build that the final head also produces
+(`dist` JS tree SHA-256 `f85bf73ee8c0ddb2270d8d6040feffbc49f018d2e6ab6253fffb828654a389df`),
+for `codex:user` and `claude-code:user`, `project` and `local`; real
+registrations unchanged, no remaining process, no path leak.
+
+The multi-session harness changes (#66, #67, #68) were verified with
+provider-free tests only: no live multi-session run used them yet. A live run
+belongs to Sprint 3.
+
+Open gates that Sprint 2 does not close: the final-head CI of the pull request,
+a live run with the new harness bindings, and every Sprint 1 open gate above.
+
+## Sprint 3 live acceptance (2026-10-13)
+
+Recorded on 2026-10-13 against main `0aae639` (package `0.8.1` plus the
+unreleased Sprint 1 and 2 changes; `dist/main.js` SHA-256 `47875d38…`), on
+native Linux x64 with Node.js `26.11.1`, Claude Code `2.1.296` and Codex CLI
+`0.162.1`. The [Sprint 3 file](sprints/2026-10-13-s3-live-usage.md) holds the
+pre-registration, every command and the review rounds. Worker profiles are
+the maintainer's intended pair, copied without its read-only external MCP
+grant: read-only OpenAI `gpt-6-luna` (`low`) and coding DeepSeek
+`deepseek-flash` (`high`).
+
+Level 3 (R05, R09): one ten-task cycle with both controllers, pre-registered,
+strictly sequential. Accepted: 10 of 10 tasks reached their intended outcome
+and every gate condition held, including the coding barrier for both clients
+(in Codex's read-only sandbox too), read-only invariance, no change outside the
+approved diff, no public leak, no session or process left after a verified
+close, and Level 1 green for the release source. Every running turn was seen
+in at most one `pi_turn_get` poll. This is the first full cycle on Pi SDK `1.x`;
+it covers this provider pair on Linux only.
+
+Targeted multi-session evidence (not Level 3), with
+`scripts/multi-session-acceptance.mjs`:
+
+- R06, Codex `abort` (DeepSeek workers): passed, including the strict scope
+  oracle that failed the v0.8.1 Codex abort run.
+- R08, `trio` (three concurrent sessions, a read-only reviewer of a frozen
+  fixture, a neighbor abort): Codex passed; Claude Code failed only
+  `neighborsNotRunningDuringAbort`, because the read-only review finished 6.7 s
+  before the abort. The failed run stays on record
+  ([#74](https://github.com/plagor44-ux/pi-session-mcp/issues/74)).
+
+Real client discovery (R07): a real Codex run in an isolated home found the
+controller skill that setup had installed as a regular copy, named that copy's
+path and quoted a line that exists only in the revision under test; no manual
+link was needed.
+
+Not established: macOS (R10, R11; runbook in the Sprint 3 file), other
+providers and models, the operator profiles' external MCP grant, larger tasks,
+more than three concurrent sessions, and the `trio` timing with Claude Code as
+controller.