pi-session-mcp 0.7.1 → 0.8.1

package/docs/acceptance.md

@@ -97,7 +97,12 @@ env -i HOME="$DISPOSABLE_HOME" PATH="$PATH" PI_SESSION_MCP_CONFIG="$ACCEPTANCE_C
 ### Pass criteria
 
 - All nine operations report the expected overall status, finding and exit
-  status.
+  status. From the change that tracks #46 on, every operation also reports the
+  controller skill finding (`skill_absent` twice, `skill_installed`,
+  `skill_already_equivalent`, `skill_verified`, `skill_removed`,
+  `skill_installed`, `skill_verified`, `skill_removed`); the skill file exists
+  after steps 3 and 7 and is gone after steps 6 and 9; a foreign skill placed
+  in the same skill directory stays unchanged throughout.
 - Steps 1 and 2 leave the client state unchanged.
 - After step 9 the `pi-session-mcp` registration is absent, the sentinel is still
   present, and the ownership record set is empty. The ownership directory has
@@ -323,6 +328,236 @@ 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.
 
+## Multi-session skill acceptance
+
+A targeted live check for profile skill selection ([skills](skills.md)) and for
+several Pi sessions that one real controller drives at the same time. It is not
+the ten-task Level 3 cycle and does not replace it.
+
+The maintainer script `scripts/multi-session-acceptance.mjs` prepares the run,
+starts the controller and checks the outcome. The controller itself calls the
+Pi Session MCP tools; the script never does.
+
+### Preparation
+
+- Candidate: a separate detached checkout of the commit under test, built with
+  `npm ci`, `npm run build` and `npm run build:cli`. `prepare` records the
+  commit, whether the checkout is clean, the SHA-256 of `dist/main.js` and,
+  from the harness of `cc810c9` on, a SHA-256 over every built module in
+  `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
+  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
+  exercises library resolution. The `handshake` skill is generated per run and
+  holds a random token that no controller prompt contains. A profile with
+  `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.
+  `--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.
+- 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
+  workspace. `run` refuses a fixture that differs from its baseline before the
+  launch.
+- Bound resources: `prepare` records a digest of the candidate build, the
+  installed Claude Code controller skill copy, the candidate skill that the
+  Codex controller's link points to, the worker skills (`implementation`,
+  `review`), the `handshake` skill, the override directory, the run
+  configuration, the Claude MCP configuration, the fixture baselines, the
+  harness itself, and the `pi-session-orchestration` copies in the operator's
+  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`.
+- 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
+  different personal copy existed (observed on 2026-10-12 with a marker skill);
+  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.
+- 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
+  as `analysisFailed` and never passes, and the run's own processes are still
+  terminated. A `SIGINT` or `SIGTERM` that the harness handles during the
+  analysis records the result at once as `harnessAborted` and `analysisFailed`,
+  keeps the supervision's flags (`timedOut`, `spawnFailed`, `unterminated`),
+  terminates the run's recorded processes and exits with 1. A harness that ends
+  without handling a signal (for example `SIGKILL`, `SIGHUP` or out of memory)
+  writes no result; `evidence` lists its launch as one without a result.
+- Controller skill: from the harness of `3f98104` on, `prepare` installs the
+  Claude Code controller skill the way an operator does, with the candidate's
+  `pi-session-mcp-setup --apply --target claude-code:project:pi-session-mcp` in
+  the controller's directory. The setup step runs with a disposable `HOME`, so
+  setup state and client files of that step never touch the real home; it must
+  report `applied` and `skill_installed` and leave a regular copy identical to
+  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.
+- 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
+  plus read-only file tools, `sleep`, `node --test` and `git -C`. Codex runs as
+  `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.
+- 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
+  group and to the recorded processes of the run whose PID and start time still
+  match, never by name. A process that is only found by its working directory
+  inside the run is reported, not killed. The run is complete when the client
+  exits and a bounded drain of its output has finished; a client that the
+  escalation cannot reap still ends the wait and is marked `unterminated`. The
+  result classifies `timedOut`, `spawnFailed`, `harnessAborted` (`SIGINT` or
+  `SIGTERM` to the harness) and `analysisFailed`; the CLI exits 1 for each of
+  them. The original result of a client
+  and scenario is written once; a second `run` for the same pair is refused.
+
+### Scenarios
+
+Each client runs two invocations, one per scenario:
+
+| 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 |
+
+### Independent checks
+
+- The script watches `/proc` during the run and records every process of the
+  controller tree, every server of this run (entry point and configuration
+  path) and every process whose working directory lies inside the run, by PID
+  and start time. A later sighting of a process never lowers its role or drops
+  its fixture: an exiting server, or a zombie its client has not reaped yet,
+  has no command line, environment or working directory left to read, and a
+  descendant that outlives the client keeps the ownership that makes it the
+  run's own to terminate. After the controller exits and the server's
+  15-second shutdown bound has passed, none of them may remain.
+- From the controller transcript it extracts only tool names, aliases, states,
+  timestamps and counts. It scans every Pi Session MCP result, with
+  `assistantText` removed, for local paths, the token and credential markers,
+  and counts mentions in `assistantText` separately.
+- Scope: after the controller exits, each fixture is compared with its
+  baseline in three independent ways: the working tree against the manifest
+  (including untracked, ignored, deleted, renamed and mode-changed files), the
+  index against the base commit, and `HEAD` against the base commit. A change
+  that a worker committed therefore counts. The union of changed paths must lie
+  inside the files allowed for that task. A missing or unreadable baseline,
+  `.git` or base commit fails the check; it is never read as clean. Git runs
+  pinned to the fixture with hooks and `fsmonitor` switched off.
+- Business checks: besides the fixture's own `node --test`, the harness runs
+  its own cases per fixture (`slug`, `stats`, `range`) against the worker's
+  module in a separate `node` process, because a worker could have edited the
+  tests it is judged by. For `stats` one case passes a frozen input array, so
+  an implementation that sorts its input in place fails. The fixture's tests
+  and the business checks must both pass.
+- Every changed file must have been last written during a worker turn of its
+  task's session, and `HANDSHAKE.txt` during the follow-up turn, by the
+  server's turn timestamps. This catches a write outside the worker turns, not
+  one during them.
+- Acceptance verdict: each result carries `acceptance` with `passed` and a
+  list of `failures`, computed mechanically from the checks. `passed` is true
+  only when the list is empty. A failure code is listed when any of these
+  does not hold:
+  - the controller exit code is 0 (`controllerExit`), neither `timedOut`,
+    `spawnFailed` nor `harnessAborted` is set, and the analysis finished
+    (`analysisFailed`);
+  - 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`);
+  - at least one server of the run was observed (`noServerObserved`) and no
+    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`);
+  - 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`);
+  - at least two sessions started and all were closed (`sessionsNotClosed`);
+  - `parallel`: both first turns completed (`firstTurnsNotCompleted`), they
+    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
+    (`abortOrder`), and `range` completed with the abort inside its running
+    interval (`neighborNotRunningDuringAbort`);
+  - 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`),
+    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
+  `updatedAt` exceeded `startedAt` while it was running. This is an
+  observation, not a pass criterion.
+- Controller writes are limited by the client restrictions: the Codex
+  controller runs in a read-only sandbox, and the Claude Code controller has no
+  write or edit tool, although its allowed `git -C` could still change a
+  fixture.
+- The handshake token must appear neither in a worker prompt nor anywhere in
+  the controller transcript, and no worker prompt may name a private path or a
+  skill file. The controller's own reads and commands must not name the run's
+  private directory or its files; this is a marker check, not a sandbox.
+- The harness records its own SHA-256 at `prepare` and refuses to run or
+  re-evaluate a run with another version.
+- `reanalyze` recomputes the transcript analysis and the checks of a finished
+  run and never overwrites the original result: it writes a numbered
+  reanalysis file. At the end of each run the harness records the state of
+  the fixtures (working tree, `HEAD`, index) and of the bound resources. If a
+  fixture or a bound resource differs from that state, the reanalysis fails
+  with `stateChangedSinceRun`.
+- `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.
+  Transcripts and the configuration stay in the run's private directory and
+  are never published.
+
+A controller that reports success does not count; only the checks above and
+the `acceptance` verdict derived from them do.
+If a client or its authentication is not available, record that client's part
+as blocked.
+
+### Method limits of earlier records
+
+Records made with the harness before it was hardened in #53 have these method
+limits, which that change removed:
+
+- The scope check used `git status`, which does not show a change that a worker
+  had already committed.
+- The business checks ran the fixture tests inside the worker's workspace,
+  which a worker could have modified.
+- Only the build, the harness and the bytes of the configuration file (through
+  its fingerprint) were bound to the run. The installed controller skill, the
+  contents of the selected worker skills and the fixture baselines were not.
+- After the time limit the harness sent `SIGTERM` and then waited for the
+  client to close without a bound. A hang would have shown as a hang, not as a
+  pass.
+
+These limits do not show that any recorded result was wrong. The records stay
+as recorded; a new run gets a new record.
+
 ## Evidence rules
 
 - Record only sanitized evidence: statuses, booleans, counts, durations,
@@ -612,3 +847,360 @@ Pi extension live check with the operator's configuration on 2026-10-11:
   prompt.
 - Two Cursor sessions completed in parallel.
 - No process remained, and no foreign line reached the MCP stdout.
+
+Profile skill selection (#46) passed a multi-session skill acceptance with Claude
+Code and Codex on 2026-10-12, on Linux (`x64`) with Node.js `26.11.1`, Claude
+Code `2.1.296`, Codex CLI `0.162.1` and Pi SDK `1.1.0`:
+- Candidate: detached checkouts of `bcef6ba` (runs 1 to 3), `a086339` (run 4)
+  and `b6cf624` (run 5), each clean and built with `npm ci`, `npm run build`
+  and `npm run build:cli`. `dist/main.js` has the same SHA-256 in all five
+  runs, `47875d38886528ace6b242df2c6ad79d624c51e330e63c2f401576eadc449ed7`:
+  the commits after `bcef6ba` change only the orchestration skill text, the
+  acceptance harness and documentation.
+- Level 1 on `bcef6ba`, from the command output of the maintainer's gate run:
+  every command exited with `0`. The test run reported
+  40 files, 761 passed and 5 skipped; `npm audit` reported 0 vulnerabilities;
+  `npm pack --dry-run` listed the three skills and no harness. The test suite
+  passed again on `a086339` with the same counts.
+- Configuration: the same bytes in every run, fingerprint
+  `sha256:b754f0f5e4702d81d99183817abb379eeed2fb5733f93373852eb827ec16d687`,
+  with the profiles `accept-read` and `accept-code` derived from an OpenAI
+  `gpt-6-luna` profile with thinking level `low`, and the fixture aliases
+  `cc-slug`, `cc-stats`, `cc-wait`, `cc-range`, `cx-slug`, `cx-stats`, `cx-wait`
+  and `cx-range`. Offline Doctor reported no finding for it.
+- Every invocation confirmed the candidate's version and this fingerprint
+  through `pi_capabilities_get` as its first call, and saw the skills
+  `implementation` and `handshake` on `accept-code`. Exactly one server of the
+  run was observed per invocation, and no process of the controller tree, the
+  server or the fixtures remained afterwards. No Pi Session MCP result
+  contained a local path, the token or a credential marker, and no
+  `assistantText` mentioned one.
+
+Run 5, on `b6cf624` with the harness of that commit (SHA-256
+`ca851130bbade9f0b2700a43059b7ac3ce349dad40ad2b647133f950a408c719`), passed
+every check of all four invocations:
+
+| Client | Scenario | Result |
+| --- | --- | --- |
+| Claude Code | `parallel` | First turns overlapped by 25.1 s; follow-up in the same session completed; both fixtures pass their tests with only the allowed files changed, each last written during a worker turn; `HANDSHAKE.txt` holds the token and was written during the follow-up turn, although no worker prompt contained the token and the token never appeared in the controller transcript; no controller action named the private run directory; both sessions closed |
+| Claude Code | `abort` | First turns overlapped by 23.7 s; one abort, result `ok`; `aborted` seen through `pi_turn_get` before close; the abort fell inside the running interval of the neighbor, which then completed and passes its tests; the worker's `sleep 120` was observed running, and at the end of the run it was gone and had written no file; both sessions closed |
+| Codex | `parallel` | As for Claude Code, with an overlap of 24.8 s |
+| Codex | `abort` | As for Claude Code, with an overlap of 22.4 s |
+
+The controllers made 1 to 6 `pi_turn_get` calls per session and waited between
+polls with `sleep`. Each invocation took 93 to 156 seconds. The run's
+transcripts were also checked afterwards against the criteria the harness
+gained after run 5: in both `abort` invocations the first successful abort came
+before the first `aborted` observation, and no worker prompt named a private
+path or a skill file. Run 5 used the harness of `b6cf624`; the head's harness
+adds these two checks and the run-time checksum check, and changes nothing
+else.
+
+Earlier attempts on the same build, kept on record:
+- Run 1 (Claude Code only, with the harness of `bcef6ba`, which did not record
+  its checksum yet): `parallel` passed
+  every check. In `abort` the abort itself passed (result `ok`, `aborted` seen
+  before close, the worker's `sleep` ended, no late file), but the neighbor
+  turn had completed about three seconds before the abort, so the run shows no
+  neighbor that keeps running. The neighbor task now starts with a bounded
+  `sleep 45` and the abort comes after about 15 seconds.
+- Run 2: three invocations passed every check. In Codex `parallel` every
+  functional check passed, including the handshake written during the
+  follow-up turn with a token that no prompt contained, but the controller
+  then read the run's private handshake skill to confirm the token. The
+  controller prompt now confines reads and commands to the fixtures.
+- Run 3: three invocations passed every check. In Codex `abort` the abort, the
+  running neighbor and cleanup passed, but the controller told both workers to
+  "follow configured handshake instructions" because capabilities listed a
+  `handshake` skill, so both fixtures got an extra `HANDSHAKE.txt`. The
+  orchestration skill now says that a listed skill is not a task.
+- Run 4 (`a086339`): three invocations passed every check. The Codex
+  `parallel` controller read the fixtures-only rule as excluding its own skill
+  directory, worked from `./fixtures`, and stopped after
+  `pi_capabilities_get` without starting a session. The rule now allows the
+  controller's own skill directory.
+
+No run showed a Pi Session MCP defect. The deviations were controller
+behavior and harness wording.
+
+This is a targeted check of skill selection and of two concurrent sessions
+per client. It is not the ten-task Level 3 cycle. It covers neither the
+extension profile path live (the automated SDK contract tests cover it), nor
+`read-only` workers, nor more than two concurrent sessions, nor macOS.
+
+After the owner asked on 2026-10-12 that skills install without manual linking
+and can be adjusted and extended, the same change gained the skill library,
+`builtin:` references, `--customize-skill` and the controller-skill
+installation through `setup`. Its final candidate `0ebbaa0` passed on
+2026-10-12, on Linux (`x64`) with Node.js `26.11.1`, Claude Code `2.1.296`,
+Codex CLI `0.162.1` and Pi SDK `1.1.0`:
+- Level 1 on a clean detached checkout: every command exited with `0`. The
+  test run reported 43 files, 884 passed and 5 skipped; `npm audit` reported 0
+  vulnerabilities; `npm pack --dry-run` listed 125 files with the three skills
+  and no acceptance harness. `git diff --check` from `0cb3c60` reported nothing.
+- Level 2 through `scripts/setup-acceptance.mjs` with the setup of that
+  checkout: 160 of 160 checks passed. All nine steps passed on all four
+  targets, including the controller skill finding of every step, the skill file
+  after steps 3 and 7 and its absence after steps 6 and 9, and a foreign skill
+  that stayed unchanged. The real client registrations were unchanged, no
+  process remained, no report leaked a path, and the build was unchanged.
+  Earlier candidates `24ab13d` and `37034dd` of the same change had passed
+  Level 2 with 160 of 160 as well, before the review fixes that followed them.
+- Multi-session skill acceptance, run 7, with the harness of that checkout
+  (SHA-256 `42d46f86ae617c229568437e6d96c93f965c27778c3e2fde51e1c449ef35fb12`)
+  and the dist tree SHA-256
+  `957dfac67bf0c3c179bff6584b3bda49bedad2fe1642790537f6790b31f5ef37`:
+  - `prepare` installed the Claude Code controller skill with the candidate's
+    `setup --apply` for the controller's project scope: `applied` and
+    `skill_installed`, a regular copy identical to the shipped skill.
+  - The configuration (fingerprint
+    `sha256:b8a341c9ff48ecd7c02f8959b8e4e696f305431945b659ea35d2d98485e948c3`)
+    referenced all three skills with `builtin:`: the two shipped worker skills
+    and the `handshake` skill from the override directory next to it.
+  - All four invocations passed every check: Claude Code `parallel` (first
+    turns overlapped by 21.5 s) and `abort` (22.1 s), Codex `parallel` (22.9 s)
+    and `abort` (18.9 s). In both `parallel` invocations the worker wrote the
+    handshake token, which existed only in the override-directory skill,
+    during the follow-up turn. In both `abort` invocations the one abort
+    returned `ok`, came before the `aborted` observation and fell inside the
+    running neighbor, which completed and passed its tests. No process
+    remained, and no result leaked a path, the token or a credential marker.
+- Run 6 on `cc810c9`, before the last review fixes, had passed every check of
+  all four invocations with the same configuration fingerprint and the
+  setup-installed Claude Code skill.
+
+These runs do not cover macOS, Codex skill discovery from the user's home
+(setup installs it there, and Level 2 checks the file, but no live Codex
+controller read it from there), the extension profile path live, or more than
+two concurrent sessions.
+
+The multi-session runs above were made with the earlier harness. Its
+[method limits](#method-limits-of-earlier-records) apply to them. They do not
+show that any of these results was wrong.
+
+Before its release, `v0.8.0` passed Level 1 and the working-tree Level 2 on
+its release candidate `6d197a0` on Linux (`x64`), with Node.js `26.11.1`, Codex
+CLI `0.162.1` and Claude Code `2.1.296`, on 2026-10-12:
+- Level 1: every command exited with `0`.
+  - The test run reported 43 files, 884 passed and 5 skipped.
+  - `npm audit` and `npm audit --omit=dev` reported 0 vulnerabilities.
+  - `npm pack --dry-run` listed 125 files, including the three skills.
+  - Doctor reported `packageVersion` `0.8.0`. With the example
+    configuration its only finding was the missing placeholder workspace.
+- Level 2 ran through `scripts/setup-acceptance.mjs` on the candidate's
+  working tree: 160 of 160 checks passed. All nine steps passed on all four
+  targets, including the controller skill finding of every step. The real
+  client registrations were unchanged, no process remained, and the built
+  files were unchanged.
+- Apart from the version, the candidate's sources equal the merge of #48,
+  whose final candidate `0ebbaa0` passed the multi-session skill acceptance
+  recorded above.
+
+After its release, `v0.8.0` passed Level 1 on a fresh clone of its tag and
+Level 2 in three variants. The release was published on 2026-10-12. The release
+notes do not date the individual checks, and they name no operating system for
+the local runs.
+- Source and tag: the release source and the annotated tag target is
+  `de46896a6cc3aebc61234917c6d8c472003da36b`, the merge of #49 (head
+  `805162ed3c3bcd73113dccabf62656414e3dd9be`). The annotated tag object is
+  `a198292fab7f4ef9bdbd18a0ba40324e45e71e21`. The feature pull request #48
+  (head `a2dc018a22ffa8dd8ff6af5d358f4f57cf7db845`) was merged as
+  `f9e4b6711e9ca0419b2325bec8d6c350ebead5f5`.
+- CI: #48 and #49 passed on Linux, macOS 15 and macOS 26. The
+  [merged-main run](https://github.com/plagor44-ux/pi-session-mcp/actions/runs/38226706157)
+  and the
+  [tag run](https://github.com/plagor44-ux/pi-session-mcp/actions/runs/38226900880)
+  are on record.
+- 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.
+  - The test run reported 43 files, 884 passed and 5 skipped (macOS-only).
+  - `npm audit` and `npm audit --omit=dev` reported 0 vulnerabilities.
+  - Offline Doctor reported `packageVersion` `0.8.0`. With the example
+    configuration its only finding was the placeholder workspace.
+- npm package `pi-session-mcp@0.8.0`, published from a fresh clone of the tag
+  through staged publishing and approved by the maintainer: 125 files, 189.3 kB
+  and the shasum `37f76ab9c3807213b7e6178156992c76f0ff8378`. The tarball
+  downloaded from the registry had the same SHA-1 and SHA-512 integrity.
+- Level 2 ran through `scripts/setup-acceptance.mjs` in three variants: the
+  working tree of the release candidate, a fresh clone of the tag, and the npm
+  package installed into a temporary prefix. Each passed 160 of 160 checks.
+  - The clients were Codex CLI `0.162.1` (`user`) and Claude Code `2.1.296`
+    (`user`, `project`, `local`), in disposable homes.
+  - Every step also checked the controller skill: installed after apply,
+    verified, removed after rollback and remove, with a foreign skill in the
+    same directory untouched.
+  - The real client registrations were unchanged, no process remained, and the
+    build stayed byte-identical.
+- Multi-session skill acceptance: it ran on the branch candidate `0ebbaa0`
+  (recorded above), not on the tag. According to the release notes, its
+  sources equal the release apart from the version and the documentation.
+  Claude Code `2.1.296` and Codex CLI `0.162.1` were the controllers, with Pi
+  SDK `1.1.0` workers. Both the `parallel` scenario (overlapping turns, a
+  same-session follow-up and a skill-only token written by the worker) and the
+  targeted `abort` scenario with a neighbor that kept running passed every
+  check for both clients. The Claude Code controller skill was installed with
+  `setup --apply`, and all catalog skills were `builtin:` references.
+
+This record does not cover:
+- A full ten-task Level 3 cycle. The multi-session check is targeted.
+- A Codex controller that reads the skill from `~/.agents/skills` live (setup
+  installs it there and Level 2 checks the file), the extension profile path
+  live with skills (the SDK contract tests cover it), more than two concurrent
+  sessions, and macOS beyond CI.
+- The contents of skill files: they are not snapshotted, so skill files must
+  not change while sessions use them. The model sees skill paths in its system
+  prompt and may repeat them in its answers.
+- Isolation: skill selection limits the regular skill catalog only. An
+  allowlisted extension stays trusted code, and a `coding` profile is no
+  operating-system sandbox.
+- Package provenance: the npm package has no provenance attestation, because it
+  was published from the maintainer's machine.
+
+The post-0.8.0 stabilization (#47 and #50 to #54) passed on 2026-10-12, on
+Linux (`x64`) with Node.js `26.11.1`, Claude Code `2.1.296`, Codex CLI
+`0.162.1`, Pi SDK `1.1.0` and `pi-cursor-sdk@0.5.3`:
+- Candidate: a clean detached checkout of `1e904be`, built with `npm ci`,
+  `npm run build` and `npm run build:cli`. `dist/main.js` has the SHA-256
+  `47875d38886528ace6b242df2c6ad79d624c51e330e63c2f401576eadc449ed7`, and the
+  dist tree the SHA-256
+  `7b16757f9a1a0318247914f56debe79119a3845e1a1debcf1ad371db3a958fce`. The
+  built `dist/` and `.pi-session-mcp-cli/` are byte-identical for every
+  candidate below (`0f7c376`, `06471b5`, `cb6e949` and `1e904be`): the commits
+  after `0f7c376` change only the acceptance harness, its tests and
+  documentation. The commits after `1e904be` change only tests and documentation.
+- Level 1 on that checkout: every command exited with `0`. The test run
+  reported 50 files, 1035 passed and 6 skipped; `npm audit` and
+  `npm audit --omit=dev` reported 0 vulnerabilities; `npm pack --dry-run`
+  listed 129 files with the three skills and no acceptance harness;
+  `git diff --check` and `git status --short` printed nothing.
+- Level 2 through `scripts/setup-acceptance.mjs` with the setup of that
+  checkout: 160 of 160 checks passed. All nine steps passed on all four
+  targets. The real client registrations were unchanged, no process remained,
+  no report leaked a path, and the build was unchanged. `06471b5` and
+  `cb6e949` had passed 160 of 160 as well.
+- Multi-session skill acceptance, run 4, with the harness of that checkout
+  (SHA-256 `e694c9be2779aae164ced0b771db035dac64f136160cc98d2c9e9cf63b629afe`):
+  - `prepare --with-extensions` derived the configuration from the operator's
+    Cursor profile: provider `cursor`, model `composer-2.5`, thinking level
+    `off` and the exact allowlist `npm:pi-cursor-sdk@0.5.3` on both run
+    profiles. Nothing else was copied. Fingerprint
+    `sha256:05a3fb00f9a1bb57b891d4cfe273aa19e1a716c0d17d2d24097e4225dbea4142`.
+  - `prepare` installed the Claude Code controller skill with the candidate's
+    `setup --apply`: `applied` and `skill_installed`, a regular copy identical
+    to the shipped skill.
+  - Every invocation confirmed the candidate and the fingerprint through
+    `pi_capabilities_get` as its first call, saw the skills `implementation`
+    and `handshake` on `accept-code`, and had exactly one server of the run
+    observed. No process remained, no bound resource changed, and no Pi
+    Session MCP result contained a local path, the token or a credential
+    marker.
+  - Both Claude Code invocations, the required part, and Codex `parallel`
+    passed every check. Codex `abort` failed one check (`range:changes`); every
+    other check of it passed.
+
+| Client | Scenario | Result |
+| --- | --- | --- |
+| Claude Code | `parallel` | Passed. First turns of two Cursor sessions overlapped by 20.4 s; follow-up in the same session completed; both fixtures pass their tests and the business checks with only the allowed files changed, each last written during a worker turn; `HANDSHAKE.txt` holds the token and was written during the follow-up turn, although no prompt contained the token |
+| Claude Code | `abort` | Passed. First turns overlapped by 21.5 s; one abort, result `ok`; `aborted` seen through `pi_turn_get` after the abort and before close; the abort fell inside the running interval of the neighbor, which completed and passes its tests; the worker's `sleep` was observed running, and at the end of the run it was gone and had written no file; both sessions closed |
+| Codex | `parallel` | Passed, as for Claude Code, with an overlap of 21.1 s |
+| Codex | `abort` | Failed with `range:changes`. The abort, its order, the running neighbor, cleanup and the neighbor's tests and business checks passed (overlap 19.2 s). The `range` worker also wrote `HANDSHAKE.txt`: the controller's prompt said "Change only src/range.js" and did not mention a handshake, so the Cursor worker applied the `handshake` skill of its profile on its own. The scope check caught it, as intended. This is worker behavior, not a Pi Session MCP defect |
+
+The controllers made 5 to 7 `pi_turn_get` calls per invocation, and each
+invocation took 90 to 127 seconds.
+
+- Turn liveness (#47): in every Cursor turn that a controller polled while it
+  was `running`, `updatedAt` had moved past `startedAt`: 7 of 7 turns in run
+  4, 31 of 31 in runs 1 to 4. Turns that no poll saw running are not counted.
+  This shows public stream events reaching `updatedAt` before the turn ended.
+  It does not show progress, and work without a public event stays
+  invisible.
+- Controller skill use, checked in the private transcripts of runs 1, 3 and
+  4:
+  - Each Claude Code invocation invoked its skill once and loaded the copy
+    that setup had installed for the candidate. A phrase that only the
+    candidate's skill contains appeared, and none from the operator's personal
+    copy in `~/.claude/skills`, which is the 0.8.0 skill. So the personal copy
+    did not shadow the project copy.
+  - Each Codex invocation read the candidate's skill through the run-scoped
+    link with one shell command.
+  - The handshake token, which only the override-directory skill held, shows
+    that the worker skills reached the Cursor sessions.
+
+Earlier attempts on the same build, kept on record:
+- Before a reboot, on `0f7c376`:
+  - Level 1 passed, with 1028 tests passed and 6 skipped, and the working-tree
+    Level 2 passed 160 of 160.
+  - Claude Code `parallel` passed every check, with an overlap of 52.2 s.
+  - Claude Code `abort` failed with `sessionsNotClosed`, `abortFailed`,
+    `abortOrder`, `neighborNotRunningDuringAbort` and `range:tests`: neither
+    `pi_session_start` started a session. At that time the operator's Pi agent
+    directory was not writable, because `/home` had run out of Btrfs metadata
+    space. The run directory was on a memory-backed file system and was lost in
+    the reboot, so only the maintainer's summaries remain: there is no evidence
+    file, and the exact start error is not on record.
+- Run 1 on `0f7c376`, with the harness SHA-256
+  `9135f8d9a3d904172475e2fd0d5fce762613a8683a642b53642167572e02ab91`: all four
+  invocations passed every check. The overlaps were 29.0 s and 22.2 s for
+  Claude Code (`parallel`, `abort`) and 22.8 s and 26.5 s for Codex.
+- Run 2 on `06471b5`, with the harness SHA-256
+  `d63b03065b28f3714ee2e9f76d722053c835f080b3a6edc96e1aab0031a0eadc`:
+  - Codex `parallel` passed.
+  - The other three invocations failed only with `noServerObserved`, and every
+    other check passed, including the aborts, the running neighbors and the
+    absence of residual processes.
+  - The cause was in the harness. It replaced a process's earlier sighting on
+    every sweep, so a sweep that caught the server while its client was ending
+    it (exiting or an unreaped zombie, with nothing left to read) recorded it as
+    a plain descendant of the client. `cb6e949` keeps the server role.
+- Run 3 on `cb6e949`, with the harness SHA-256
+  `9f62535c3cb28506595ba72e5bafad772df71f473b4711799724186a946713b9`: Level 2
+  passed 160 of 160, and all four invocations passed every check. The overlaps
+  were 22.8 s and 22.2 s for Claude Code and 24.2 s and 18.6 s for Codex. One
+  `assistantText` in Codex `parallel` named the absolute path of the worker's
+  own `HANDSHAKE.txt`; `assistantText` is the worker's free text, counted
+  separately, and not a structural leak. The two harness commits after it keep
+  a process's ownership across sightings and match the client by PID and
+  start time.
+
+This record does not cover:
+- macOS beyond CI, or a ten-task Level 3 cycle.
+- A Codex controller that reads the skill from a copy setup installed in
+  `~/.agents/skills`, because the run must not change the operator's home.
+  Codex read the candidate's skill through a run-scoped link, and Level 2
+  checks the installed file.
+- A third concurrent session, a `read-only` worker, or more than two
+  concurrent sessions.
+- A real crash in the middle of a setup skill update, a real contention of
+  two customization processes outside the tests, and an operating-system
+  signal to the harness during a live analysis. The provider-free tests cover
+  these.
+
+After its release, `v0.8.0` was installed for the maintainer on Linux: the npm
+package `pi-session-mcp@0.8.0` in the user's npm prefix, registered for Claude
+Code. Checked on 2026-10-12:
+- Offline Doctor reported `packageVersion` `0.8.0` and no finding.
+- `--verify` for `claude-code:user:pi-session-mcp` reported `mcp_verified`, and
+  `skill_verified` for the controller skill.
+- Codex has no registration of the server on that machine, so `codex:user` was
+  not part of this installation.
+
+Before its release, `v0.8.1` passed Level 1 and the working-tree Level 2 on its
+release candidate `baa6406` on Linux (`x64`), with Node.js `26.11.1`, Codex CLI
+`0.162.1` and Claude Code `2.1.296`, on 2026-10-12:
+- Level 1 on a clean detached checkout: every command exited with `0`.
+  - The test run reported 50 files, 1035 passed and 6 skipped.
+  - `npm audit` and `npm audit --omit=dev` reported 0 vulnerabilities.
+  - `npm pack --dry-run` listed 129 files, including the three skills, and no
+    acceptance harness.
+  - Doctor reported `packageVersion` `0.8.1`. 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,
+  including the controller skill finding of every step. 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
+  `0c7bad3`. Its built modules have the same dist tree SHA-256
+  (`7b16757f9a1a0318247914f56debe79119a3845e1a1debcf1ad371db3a958fce`) as the
+  final candidate `1e904be` of the multi-session acceptance recorded above.

package/docs/adr/0006-pi-extension-allowlist.md

@@ -3,6 +3,9 @@
 **Status:** Accepted (2026-10-11). Issue #34. Design:
 [Pi extensions design](../pi-extensions-design.md).
 
+Amended by [ADR 0007](0007-profile-skill-selection.md) for skills that extension
+packages ship.
+
 ## Context
 
 Embedded sessions loaded no Pi extensions. Providers that exist only as Pi