pi-session-mcp 0.7.0 → 0.8.0

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
@@ -124,6 +129,55 @@ that checkout with Doctor reporting the release version, and confirms that the
 manifests and built runtime files are byte-identical before and after the
 client cycles.
 
+### Tooling
+
+`scripts/setup-acceptance.mjs` runs the isolation, the sequence and the pass
+criteria above with the real clients. It uses disposable homes below its work
+directory (default `~/.cache/pi-session-mcp-acceptance`, never below `/tmp`,
+`/var/tmp`, `/dev/shm` or `$TMPDIR`), removes them afterwards (also after Ctrl-C
+or SIGTERM, with exit `130` or `143`) and writes a sanitized JSON result without
+paths or environment values. It exits with `0` when every check passed, `1` when
+a check failed and `2` on a usage, environment or harness error.
+
+`--setup` is split on whitespace, so paths in it must not contain spaces. Its
+first token must be an absolute path to an existing file or a command found on
+`PATH`; otherwise the script exits with `2`.
+
+The script only reads the real `~/.codex/config.toml` and `~/.claude.json` to
+prove that the MCP registrations in them did not change. A file that does not
+exist counts as the constant digest `absent`; one that exists but cannot be read
+fails the check. A real client session that changes its own MCP registrations
+during the run makes the digest check fail (a false fail), so close or idle real
+clients first.
+
+Working tree, after `npm run build` and `npm run build:cli`:
+
+```bash
+node scripts/setup-acceptance.mjs \
+  --setup "node $PWD/dist/setup-main.js" --build-dir "$PWD" \
+  --label working-tree --out level2-result.json
+```
+
+Published package: install it into a temporary prefix outside `/tmp`, then pass
+the installed executable and package directory.
+
+```bash
+npm install -g --prefix "$PREFIX" pi-session-mcp@<version>
+node scripts/setup-acceptance.mjs \
+  --setup "$PREFIX/bin/pi-session-mcp-setup" \
+  --build-dir "$PREFIX/lib/node_modules/pi-session-mcp" \
+  --label npm-<version> --out level2-result.json
+```
+
+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.
+
+`--clients codex` or `--clients claude-code` limits a run to one client, for
+example on a macOS machine without Codex. The script does not cover the macOS
+lock-contention and interruption steps, Level 1, or the tag identity checks
+(tag object, peeled commit, `git describe`). Run those by hand.
+
 ### macOS
 
 macOS uses the same isolation, sequence and pass criteria, with the additions
@@ -154,7 +208,7 @@ CI-tested, and it has not passed Level 2 for Codex.
 - **Interruption.** Start `--apply` for one target and press Ctrl-C while it
   runs.
   - The run exits with `130` and reports `operation_interrupted`.
-  - Afterwards `ps -A -o pid=,command=` lists no `claude mcp` or `codex mcp`
+  - Afterwards `ps -ww -A -o pid=,command=` lists no `claude mcp` or `codex mcp`
     command and no `setup-main.js` or `setup-command-guardian.js` process of
     the build under test.
   - A following `--apply` reports one of three outcomes, depending on where
@@ -166,7 +220,8 @@ CI-tested, and it has not passed Level 2 for Codex.
   - A following `--remove` reports `ok (removed)`.
   - If the operation completes before the interrupt arrives, record that and
     repeat. An interrupt that never lands is not a pass.
-- **Processes.** Check that no process remains with `ps` instead of `/proc`.
+- **Processes.** Check that no process remains with `ps -ww` instead of `/proc`;
+  without `-ww`, `ps` truncates long commands when it has no terminal.
 
 The evidence record names the build (commit or tag), the environment above,
 every command with its exit status, and the sanitized JSON results. It
@@ -273,6 +328,99 @@ 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 one working profile
+  without extensions or MCP servers into a temporary 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.
+- 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.
+- 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.
+
+### 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. 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.
+- Fixture oracles run on the workspace after the controller exits: `node
+  --test` and `git status` per fixture. 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.
+- 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.
+- `evidence` writes one sanitized JSON record and refuses to write a local path
+  or the token. 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 do.
+If a client or its authentication is not available, record that client's part
+as blocked.
+
 ## Evidence rules
 
 - Record only sanitized evidence: statuses, booleans, counts, durations,
@@ -485,3 +633,224 @@ Claude Code `2.1.296`, on 2026-10-11:
 The Pi extension live check above ran on `eeaa597`, before the final fixes to
 extension tool names and the `read-only` contract test. It has not been
 repeated on the release candidate.
+
+After its release, `v0.7.0` passed Level 1 and Level 2 on a fresh clone of its
+tag, and Level 2 as published npm package, on 2026-10-11, on Linux with Node.js
+`26.11.1`, Codex CLI `0.162.1` and Claude Code `2.1.296`:
+- Tag clone: `git describe --tags --exact-match` reported `v0.7.0`. The tag
+  object is `a5516ce6e4e159ef1e20ee38aba06672379e9cb7` and the peeled commit
+  `6783631d2ae1813707cf798360a0a0f4c58ca66d`.
+- Level 1 on the tag clone:
+  - every command exited with `0`;
+  - the test run reported 37 files, 660 passed and 5 skipped;
+  - `npm audit` and `npm audit --omit=dev` reported 0 vulnerabilities;
+  - Doctor reported `packageVersion` `0.7.0` and no finding;
+  - `dist/main.js` has the SHA-256
+    `47875d38886528ace6b242df2c6ad79d624c51e330e63c2f401576eadc449ed7`.
+- Level 2 passed 96 of 96 checks on the tag clone, and 96 of 96 with the npm
+  package installed into a temporary prefix through
+  `pi-session-mcp-setup`. In both runs the real client registrations were
+  unchanged, no process remained, and the built files were byte-identical
+  before and after the client cycles.
+  - These runs, and the release candidate's runs above, used the harness that
+    #40 later checked in as `scripts/setup-acceptance.mjs`.
+  - The checked-in script, after its review fixes, also passed 96 of 96 on the
+    tag clone.
+- The npm package has the shasum `c8d73311dbde1bdebd78e58b1f01c7cf3bebf374`.
+  The tarball downloaded from the registry had the same SHA-1 and SHA-512
+  integrity.
+- Installed package:
+  - `pi-session-mcp-doctor` reported a healthy package `0.7.0` when run from an
+    unrelated working directory;
+  - with a configuration that pins `pi-cursor-sdk@0.5.3` on three profiles,
+    `setup --apply` and `--verify` for `claude-code:user:pi-session-mcp`
+    reported `applied` and `mcp_verified`.
+
+On 2026-10-11 the installed `v0.7.0` package also passed the Pi extension live
+check on Linux:
+- Method: the same scripted JSON-RPC client as above drove the installed
+  server. It used the operator's configuration with three `pi-cursor-sdk@0.5.3`
+  profiles: one `read-only` and one `coding` profile with
+  `claude-opus-5-5@1m` and `claude-opus-5-5@300k` at thinking level `high`, and
+  one `coding` profile with `composer-2.5` at thinking level `off`.
+- Each of the three profiles started, completed a prompt with the expected
+  one-word answer, and closed. One `coding` and one `read-only` Cursor session started in parallel
+  and both completed.
+- Profiles without extensions on three other providers (xAI, Mistral and
+  DeepSeek) each completed a prompt.
+- After close no descendant process of the server remained. No stdout line
+  failed to parse as an MCP frame; stderr carried four
+  `foreign_stdout_suppressed` reports for 12 suppressed writes and no other
+  event.
+- The two OpenAI profiles ended `failed` with `turn_failed`. A direct Pi CLI
+  call outside the server showed that the account had reached its usage limit,
+  so they are not evidence for or against the release.
+
+This check does not cover macOS, an MCP client in the loop, or a session that
+uses Cursor's own tools.
+
+Before its release, `v0.7.1` passed Level 1 and the working-tree Level 2 on its
+release candidate `82dff20` on Linux, with Node.js `26.11.1`, Codex CLI
+`0.162.1` and Claude Code `2.1.296`, on 2026-10-11:
+- Level 1: every command exited with `0`.
+  - The test run reported 38 files, 684 passed and 5 skipped.
+  - `npm audit` and `npm audit --omit=dev` reported 0 vulnerabilities.
+  - Doctor reported `packageVersion` `0.7.1` and no finding.
+- Level 2 ran through `scripts/setup-acceptance.mjs` on a fresh clone of the
+  candidate.
+  - All nine steps passed on all four targets, 96 of 96 checks.
+  - The real client registrations were unchanged, and no process remained.
+  - The built files were byte-identical before and after the client cycles.
+- `dist/main.js` is byte-identical to that of `v0.7.0`. The changed modules are
+  the extension tool-name rule, the pin format and the prompt source.
+
+The branch build of `8d5b069`, whose sources match this candidate, passed the
+Pi extension live check with the operator's configuration on 2026-10-11:
+- Three `pi-cursor-sdk@0.5.3` profiles and one xAI profile each completed a
+  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.
+
+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.

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
@@ -40,8 +43,8 @@ model runtime per session:
 
 Profiles without extensions keep the previous path. Client prompts are plain
 text for every profile: they never dispatch extension commands, skills or
-templates. An always-on stdout guard gives the MCP transport the only real
-stdout writer.
+templates, and extension input hooks see them with `source: "rpc"`. An
+always-on stdout guard gives the MCP transport the only real stdout writer.
 
 ## Consequences
 

package/docs/adr/0007-profile-skill-selection.md

@@ -0,0 +1,217 @@
+# ADR 0007: Execution profiles select Pi skills from an operator catalog
+
+**Status:** Accepted (2026-10-12). Issue #46. Guide: [Pi skills in execution
+profiles](../skills.md).
+
+## Context
+
+Embedded sessions are meant to run without skills. A controlling agent that
+delegates work to Pi workers needs a way to give a worker role-specific
+instructions, such as an implementation or review procedure, under the same
+rule as everything else: the operator decides, the MCP caller picks aliases.
+
+Verified behavior of Pi SDK 1.1.0:
+
+- `noSkills` does not stop skills that an allowlisted extension package
+  ships. Those skills reached the session although `noSkills` was set. The
+  same held for prompt templates and themes that packages ship. ADR 0006 did
+  not intend this and did not decide it.
+- `loadSkills` removes duplicate skill names before the SDK's `skillsOverride`
+  runs. An override alone therefore cannot report a collision between two
+  selected files, so the server has to check names itself.
+- Resources that extension hooks add later (`resources_discover`) pass through
+  the same override.
+
+ADR 0003 chose maintenance without a new feature phase and reserves public
+contract changes for a minor release with their own decision. ADR 0006 is the
+precedent for an owner-approved scope expansion. This ADR is such a decision
+for issue #46. It does not rewrite ADR 0006; that ADR records only a forward
+link.
+
+On 2026-10-12 the owner rejected installing the shipped skills by manual
+symlinking and asked for skills that can be installed at install time and
+adjusted and extended one by one. The decisions under "Skill library,
+installation and customization" below record that, in the same change.
+
+## Decision
+
+The operator may register skills in a catalog and select them per execution
+profile.
+
+- **Catalog.** An optional top-level `skillCatalog` maps a skill alias
+  (`^[a-z][a-z0-9_-]{0,63}$`, at most 64 entries) to the path of exactly one
+  `SKILL.md` (at most 4096 characters). Directories, globs, URLs,
+  scheme-prefixed sources, `~` and backslashes are invalid. The one accepted
+  scheme is `builtin:<name>` (see below). Relative paths resolve against the
+  configuration file's directory. A missing catalog is empty. A skill folder
+  needs no `package.json` and no extension.
+- **Selection.** An optional `executionProfiles.<alias>.skills` lists catalog
+  aliases (at most 16, no duplicates). Missing or empty means no skills. There
+  is no inheritance and no default skill. An unknown alias, a duplicate alias,
+  or two selected aliases that resolve to the same path is
+  `invalid_execution_profile_config`. All other profile fields are unchanged
+  and unknown fields are still rejected.
+- **MCP surface.** Callers still choose only workspace and profile aliases.
+  `pi_session_start` and `pi_session_prompt` get no skill input. No tool is
+  added.
+- **Loading.** At session start the server loads exactly the selected files
+  through the SDK's public `loadSkills`, with no default directories, and
+  validates them completely. `skillsOverride` returns exactly that set, also
+  after later resource additions by extension hooks.
+- **Failure.** A missing, unreadable or oversized (over 256 KiB) file, an
+  invalid skill (SDK diagnostics such as a missing description or invalid
+  name), two selected files with the same Pi skill name, two aliases on the
+  same canonical file (for example through a symlink), or
+  `disable-model-invocation: true` fail the start with the new error
+  `skill_load_failed` and the fixed message `Configured Pi skill could not be
+  loaded`. The message never contains a path, a skill name or SDK text. The
+  same Pi skill name in different sessions is fine.
+- **Explicit-only skills are incompatible in v1.** MCP prompts never run
+  `/skill:` commands, and Pi hides such skills from the model. The server does
+  not rewrite the flag.
+- **Names.** The catalog alias may differ from the skill's declared `name`.
+  Nothing is renamed.
+- **Capabilities.** Every execution profile in `pi_capabilities_get` gains
+  `skills: string[]`, the selected catalog aliases in configured order, `[]`
+  when none. No paths, file names, contents or SDK diagnostics. The setup
+  verifier accepts the field and still rejects unexpected fields.
+- **Doctor.** Offline, it never parses or executes a skill. New check IDs after
+  the extension checks, with the subject `<profile>:<skill-alias>`:
+  `skill_missing`, `skill_unreadable` (not a regular file, over 256 KiB, or not
+  readable) and `skill_duplicate`. Frontmatter, name rules, collisions and
+  explicit-only flags are checked only at session start. A further warning
+  check, `skill_override_outdated`, is described below.
+- **Diagnostics.** Stderr gets the new stage `skill_load` for a selected file
+  that fails validation, with an optional `skill` field holding the catalog
+  alias. A catalog that differs from the selection after construction reports
+  the existing stages `postcheck`, `extension_load` or `extension_bind`. No
+  diagnostic carries a path.
+- **Snapshot semantics.** Profile and skill selection are fixed per session.
+  The content is not snapshotted: the SDK keeps file paths and later reads may
+  see changed files. Operators manage skill files and companion files, do not
+  change them during active sessions, and close affected sessions before an
+  update. The configuration fingerprint covers configuration bytes, not skill
+  contents. There is no hot reload, watcher, copy store for sessions or
+  versioning.
+- **Shipped skills.** The package ships `pi-session-orchestration`,
+  `pi-session-implementation` and `pi-session-review` under `skills/`, one
+  canonical copy each. They are ordinary skill files. The two worker skills are
+  registered through the catalog like any operator skill, by `builtin:`. The
+  orchestration skill is for the controlling client agent and is not a Pi
+  worker skill.
+
+## Skill library, installation and customization
+
+Owner decision of 2026-10-12, same issue. The first design of this change had
+the operator register shipped skills by absolute path and link the
+orchestration skill into the clients by hand; the owner rejected that. Three
+decisions were taken:
+installation through `pi-session-mcp-setup --apply`, an override directory for
+customization, and `builtin:` references in the Pi skill catalog.
+
+- **Skill library.** Shipped skills live in the package's `skills/` directory.
+  The operator's override directory is `skills/` next to the configuration file
+  (for the default configuration `~/.config/pi-session-mcp/skills/<name>/SKILL.md`).
+  An override with the same name replaces the shipped skill; a new name adds a
+  skill. Names follow the Agent Skills rule: lowercase letters and digits in
+  hyphen-separated groups, 1 to 64 characters. Nothing else is searched.
+- **`builtin:<name>`.** A `skillCatalog` value resolves to the override if
+  `<override dir>/<name>/SKILL.md` exists, else to the shipped skill. A missing
+  skill keeps the shipped location, so Doctor reports `skill_missing` and the
+  session start fails with `skill_load_failed`. Resolution happens when the
+  server loads the configuration: adding or removing an override needs a
+  restart, like any configuration change. Edits to an existing skill file reach
+  new sessions under the snapshot semantics above. The example configuration
+  uses `builtin:pi-session-implementation` and `builtin:pi-session-review`, so a
+  copied example needs no path edits.
+- **Customization.** `pi-session-mcp-setup --customize-skill <name>` (a
+  dry-run) and `--apply --customize-skill <name>` copy a shipped skill into the
+  override directory as a starting point and record the shipped fingerprint in
+  `<override dir>/.pi-session-mcp-bases.json`. An existing override is never
+  overwritten. When the shipped skill changed after the copy, or no base is
+  recorded, the command reports `skill_override_outdated`; `--apply` then moves
+  only the recorded base (`skill_base_updated`) and never touches the
+  operator's files, which is how an operator acknowledges a reviewed change.
+  The finding target is `{ client: "skills", scope: "override", alias: <name> }`.
+  It works without `--target`, requires `PI_SESSION_MCP_CONFIG`, and follows
+  the platform rule of setup. A completely new skill needs no command: create
+  `<override dir>/<new-name>/SKILL.md` and reference it as `builtin:<new-name>`.
+- **Installation of the controller skill.** `setup --apply` installs
+  `pi-session-orchestration` for each target, after the registration, as a real
+  copy of the effective skill (override, else shipped). Codex `codex:user` goes
+  to `~/.agents/skills/`, Claude Code `user` and `local` share
+  `~/.claude/skills/`, and Claude Code `project` goes to
+  `<project>/.claude/skills/`, the directory setup runs in. Ownership records
+  hold only a content fingerprint and, while an update is pending, the
+  fingerprint it replaces; a project record is bound to an opaque project
+  identity, never a path. 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`, which does not
+  block the registration. A link to exactly the effective skill is the
+  operator's own equivalent setup (`skill_linked`) and is never owned. In the home directory the client's skills
+  directory may be the operator's own link and is followed. Inside a project,
+  which may be untrusted, any link below the project root makes the slot
+  divergent, so setup never writes outside the project. Setup installs only
+  `pi-session-orchestration` into clients; the worker skills are for Pi
+  profiles through `builtin:`, and controller skills of the operator's own
+  belong in the clients' native skill directories. The operator customizes the
+  controller skill through the override and runs `--apply` again, and never
+  edits the installed copy.
+- **Doctor.** The warning check `skill_override_outdated` has the subject
+  `skill:<name>` when a shipped skill's current fingerprint differs from the
+  recorded base, with a remediation that names the customize command. A
+  corrupt bases file reports the subject `skill:bases`. Doctor stays offline
+  and executes nothing.
+- **Fallback.** Where setup does not run, the operator copies the controller
+  skill directory into the client's documented skill directory. There is no
+  symlink instruction.
+
+## Compatibility change
+
+Previously, with Pi SDK 1.1.0, an allowlisted extension package's bundled
+skills, prompt templates and themes reached the session although `noSkills`
+was set. Now an extension allowlist alone makes none of its skills available.
+A skill is available only through the catalog plus the profile's explicit
+selection.
+
+Migration: add a catalog entry with the absolute path to the package's
+`SKILL.md` inside Pi's install (normally under
+`<Pi agent dir>/npm/node_modules/<package>/…`; `~` is not expanded) and select
+it in the profile. Prompt templates and themes that packages ship are now also
+closed through the SDK's public overrides. They were already never expanded
+for MCP prompts. This does not mean every previous profile behaves unchanged:
+a profile that used a package's skills needs the migration above.
+
+## Consequences
+
+- Skills are operator-managed prompt content. In `coding` profiles a skill's
+  instructions are executed with the profile's tools. A skill grants no rights.
+- Skill selection limits the regular skill catalog only. An allowlisted
+  extension stays trusted executable code and can still read files or inject
+  prompt text. This is no sandbox.
+- Three states stay distinct: configured (capabilities list the alias; intent
+  only), available in the SDK catalog (validated at session start and listed
+  to the model in its system prompt), and actually read by the model (the model
+  decides; not guaranteed). Task success is separate again.
+- Skill files can change under a running session. Operators carry that
+  discipline; the server does not enforce it.
+- Setup now writes into client skill directories, in the home directory and in
+  a project. It copies only from the package or the operator's override
+  directory, never follows a link inside a project, and never replaces what it
+  did not install or what the operator modified. The override directory and its
+  bases file are operator-trusted configuration, not a workspace. Installed
+  skill content becomes instructions for the controlling agent.
+- The server needs a name check of its own for selected files, because
+  `loadSkills` dedupes by name before `skillsOverride`.
+- Sessions of profiles with extensions each have their own model runtime
+  (ADR 0006). Skill loading does not change that.
+
+## Versioning
+
+ADR 0003 requires a minor release for a public contract change. The new
+`skills` capability field and the new `skill_load_failed` error code are such a
+change, and so are the new setup findings, the `--customize-skill` option and
+the controller skill that `setup --apply` installs, so the next release after
+0.7.1 is 0.8.0. The change is recorded under
+`## Unreleased` in the changelog. Implementing it does not itself release or
+bump the version.