pi-session-mcp 0.6.4 → 0.7.1

package/docs/acceptance.md

@@ -124,6 +124,104 @@ 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
+below. A run for Claude Code is recorded under [Status](#status). macOS is
+CI-tested, and it has not passed Level 2 for Codex.
+
+- **Environment.** Record:
+  - the macOS version and architecture (`sw_vers`, `uname -m`);
+  - the Node.js version;
+  - the Codex CLI and Claude Code versions.
+- **Disposable home.** It must be on the APFS volume type of `/`. A directory
+  below the user's home qualifies.
+  - For an ownership directory on another filesystem, `--apply`, `--verify`,
+    `--rollback` and `--remove` fail closed with `failed (operation_failed)`
+    and exit `1`.
+  - Keep the Codex home outside both `$TMPDIR` (normally below `/var/folders`)
+    and `/tmp`, for the reason given under [Isolation](#isolation).
+- **Before the sequence:** run `npm run --silent doctor`.
+- **Lock contention.** After step 9, start two `--apply` runs for
+  `claude-code:user:pi-session-mcp` at the same time.
+  - One run reports `ok (applied)`. The other waits for the lock, then
+    reports `unchanged (already_equivalent)`.
+  - Both exit with `0`.
+  - A following `--remove` reports `ok (removed)`.
+  - A waiting run that reports `failed (operation_failed)` with exit `1` did
+    not get the lock within the 30 s acquisition bound. That counts as a
+    failure of the run.
+- **Interruption.** Start `--apply` for one target and press Ctrl-C while it
+  runs.
+  - The run exits with `130` and reports `operation_interrupted`.
+  - 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
+    the interrupt landed:
+    - it reconciles the pending record (`ok (pending_recovered)`);
+    - it applies again (`ok (applied)`);
+    - it finds the registration already owned
+      (`unchanged (already_equivalent)`).
+  - 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 -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
+contains no paths, environment values or secrets.
+
 ## Level 3: live two-client acceptance
 
 Live acceptance delegates real work from Codex and from Claude Code to Pi
@@ -213,6 +311,18 @@ 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.
 
+## 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.
+
+1. `pi_session_start`, a prompt answered with "PONG", `pi_turn_get` completed, `pi_session_close`.
+2. Two parallel sessions of that profile, each completing a prompt.
+3. After close, no Cursor child process of the server remains.
+4. stderr shows no `foreign_stdout_suppressed` storm and no stdout frame fails to parse.
+5. Record how the Cursor local runtime starts its child processes (inherited or piped stdio).
+
+Record date, source commit, versions and outcome under Status. No secret, path or prompt content goes into the record.
+
 ## Evidence rules
 
 - Record only sanitized evidence: statuses, booleans, counts, durations,
@@ -269,3 +379,236 @@ Before its release, `v0.6.4` passed Level 1 and the working-tree Level 2 on its
 release candidate, with Codex CLI `0.162.0` and Claude Code `2.1.296`. Its
 server entry point `dist/main.js` is byte-identical to that of `4d333da` and of
 `v0.6.3`.
+
+After its release, `v0.6.4` passed Level 1 on a fresh clone of its tag. It also
+passed Level 2 as published release and as published npm package, with Codex
+CLI `0.162.0` and Claude Code `2.1.296`, on 2026-10-10. The installed
+`pi-session-mcp-doctor` reported a healthy package when run from an unrelated
+working directory.
+
+macOS: `setup` supports macOS from the change that tracks #32. That change is
+tested in CI on macOS 15 and macOS 26 (Apple silicon) next to Linux.
+
+On 2026-10-11, the build of `d89740c`, the head of the pull request branch,
+passed the working-tree Level 2 on a real Mac with Claude Code as the only
+client:
+- Environment: macOS 26.7.1 (`25G241`) on `arm64`, Node.js `22.23.3` and Claude
+  Code `2.1.294`. The disposable home was on the APFS data volume that the
+  root volume belongs to.
+- Level 1 on that checkout: `npm ci`, `npm run typecheck`, `npm run build`,
+  `npm run build:cli` and `npm test` exited with `0`. The test run reported 531
+  passed and 23 skipped. The skipped tests are the 21 Linux `/proc` fixture
+  tests, the Linux-only lock-inode replacement test and the probe-only
+  controller output test. `npm audit` reported 0 vulnerabilities, and
+  `git diff --check` reported nothing. `git status --short` printed nothing
+  before the evidence was written.
+- Doctor with the acceptance configuration reported no error.
+- All three Claude Code targets (`user`, `project` and `local`) completed the
+  nine-step sequence. Every step reported the expected overall status, finding
+  and exit status.
+- After the sequences the `pi-session-mcp` registration was absent, the sentinel
+  was still present and the ownership record set was empty. The ownership
+  directory had mode `0700` and the ownership file mode `0600`. No server,
+  setup or guardian process of the build remained, and the digest of the real
+  Claude Code registrations was unchanged. No report contained a path, an
+  environment value or a secret.
+- Lock contention: two simultaneous `--apply` runs for
+  `claude-code:user:pi-session-mcp` finished within 5 s. One reported
+  `ok (applied)` and the other `unchanged (already_equivalent)`. Both exited
+  with `0`, and the following `--remove` reported `ok (removed)`.
+- Interruption: SIGINT was sent to the process group of a running `--apply`
+  after 0.2 s, 0.5 s and 0.9 s. Each run exited with `130` and reported
+  `operation_interrupted`. None left a `claude mcp` command or a setup or
+  guardian process behind. In each case the following `--apply` reported
+  `ok (applied)` and the following `--remove` reported `ok (removed)`.
+
+This run does not cover:
+- Codex, which was not installed on the machine, so macOS has not passed
+  setup acceptance for Codex.
+- A Ctrl-C keypress in an interactive terminal. A script sent the signal from a
+  shell without a terminal.
+- The `pending_recovered` and `already_equivalent` outcomes after an interrupt.
+  The following `--apply` reported `applied` in every case.
+- Intel Macs, the published-release and published-package variants, and
+  Level 3.
+
+On 2026-10-11 the same build also passed a narrower live check on that Mac:
+- Scope: Claude Code `2.1.294` as the only client, with Pi SDK `1.1.0` on a
+  local `qwen3.6-35b-a3b-splash` model served by LM Studio. The server was the
+  build of `d89740c`: the sources are identical to it, and `dist/main.js` has
+  the SHA-256 `a69bfec2f9f161b74a6d7b067fda9b76d94c294170bc59a771a79e3f29a7123c`.
+- Method: three sequential headless invocations, one per task group, with a
+  temporary per-invocation MCP configuration (`--strict-mcp-config`), a
+  credential-free configuration with one `read-only` and one `coding` profile,
+  and a disposable Pi agent directory. The client could run `sleep` between
+  polls. The plan, prompts, oracles and fixture digests were fixed before the
+  first invocation, and no task was repeated.
+- Preflight: one bounded request to the model returned HTTP `200` in about 1 s.
+  The loaded model was the same and idle before and after every invocation, and
+  nothing was loaded or unloaded.
+- Read-only analysis with a same-session follow-up: both turns ended
+  `completed`. The first answer contained the expected marker, and the second
+  answer was exactly the expected number. The fixture digest (path, mode and
+  content) was identical before and after.
+- Bounded coding change with a same-session follow-up: both turns ended
+  `completed`. The oracle passed on a snapshot taken between the turns and on
+  the final workspace, and that snapshot did not yet contain the second turn's
+  change. Only the one allowed file differed, with no added or removed file and
+  unchanged modes.
+- Abort and recovery: the turn was `running`, then `aborted` after
+  `pi_session_abort`. `pi_session_close` succeeded, `pi_session_list` returned
+  no session, and a fresh session started `idle` and closed.
+- Counts: `pi_turn_get` was called 3, 3 and 2 times in the three invocations,
+  and no Pi Session MCP tool returned an error.
+- A scan of every Pi Session MCP tool result in the three transcripts found no
+  absolute path, configuration file name, endpoint, key or token marker, or stack
+  frame. No server or client process remained after any invocation, each
+  client's standard error was empty, and the digest of the real Claude Code
+  registrations was unchanged.
+
+This check does not cover:
+- Codex, or any task from a second client. It is not a ten-task cycle and does
+  not satisfy the Level 3 gate.
+- The check that the first turn's terminal view stays unchanged after a second
+  turn started. The transcripts do not poll the first turn again.
+- A git-based check of the allowed diff. The coding fixture is not a Git
+  repository, so a path, mode and content digest stood in for it.
+- A coding turn that tries to change a file outside the allowed set.
+- Interactive approval dialogs, external MCP grants, and client restart or
+  resume.
+
+On 2026-10-11 the working-tree build of `eeaa597` on the `feat/pi-extensions`
+branch (#34) passed the Pi extension live check on Linux:
+- Environment: Node.js `26.11.1`, Pi SDK `1.1.0`, and `pi-cursor-sdk@0.5.3`
+  installed by Pi with a stored Cursor key. `dist/main.js` has the SHA-256
+  `47875d38886528ace6b242df2c6ad79d624c51e330e63c2f401576eadc449ed7`.
+- Method: a scripted JSON-RPC client drove `node dist/main.js` over stdio, with
+  a temporary configuration passed through `PI_SESSION_MCP_CONFIG`. The
+  configuration had a `coding` and a `read-only` profile, each with provider
+  `cursor`, model `auto`, thinking level `off` and
+  `"extensions": ["npm:pi-cursor-sdk@0.5.3"]`.
+- The `coding` profile started, its prompt completed with "PONG", and the
+  session closed.
+- Two sessions, one of each profile, started in parallel and both prompts
+  completed with "PONG".
+- After close, no descendant process of the server remained.
+- No stdout line failed to parse as an MCP frame. stderr carried two
+  `foreign_stdout_suppressed` reports for 21 suppressed writes and no other
+  event.
+- During turns the Cursor local runtime started `git`, `ssh`, `gh`, `node` and
+  the MCP servers configured for Cursor through `npm exec`, in the `read-only`
+  profile as well. None of them inherited the server's stdout: each had its own
+  pipe, a socket, `/dev/null` or a file as standard output.
+- The first run, on the earlier build of `6740484`, failed to start the
+  `coding` profile with `execution_selection_mismatch`: `pi-cursor-sdk`
+  deactivates its own `cursor_activate_skill` tool when the session starts.
+  `eeaa597` lets an extension narrow its active tools while still rejecting
+  any tool outside the allowlist.
+
+This check does not cover macOS, Codex or Claude Code as the client, the Cursor
+cloud runtime, or a session that uses Cursor's own tools.
+
+Before its release, `v0.7.0` passed Level 1 and the working-tree Level 2 on its
+release candidate on Linux, with Node.js `26.11.1`, Codex CLI `0.162.1` and
+Claude Code `2.1.296`, on 2026-10-11:
+- The first working-tree Level 2, on `2d05e55`, failed. On all four targets
+  `--verify` (steps 5 and 8) reported `failed (mcp_failed)` with exit `1`; every
+  other step passed. The verifier rejected the `extensions` field that
+  `pi_capabilities_get` lists since #34. This is #36.
+- After the fix, the working-tree Level 2 on `2c5ab3d` passed all nine steps on
+  all four targets, 96 of 96 checks.
+  - The real client registrations were unchanged, no process remained, and the
+    built files were byte-identical before and after the client cycles.
+  - The run placed one sentinel in each Claude Code scope instead of one per
+    client, so its check count differs from earlier records.
+- Level 1 on `09b32a8`: 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.
+  - The commits after `2c5ab3d` change only tests and documentation. The built
+    `dist/` and `.pi-session-mcp-cli/` are byte-identical to those of `2c5ab3d`,
+    and `dist/main.js` has the SHA-256
+    `47875d38886528ace6b242df2c6ad79d624c51e330e63c2f401576eadc449ed7`.
+- The Codex CLI `0.162.1` contract was recorded. It differs from `0.162.0` only
+  in the version line.
+
+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.

package/docs/adr/0005-macos-setup-platform.md

@@ -0,0 +1,84 @@
+# ADR 0005: setup supports macOS with the same fence as on Linux
+
+**Status:** Accepted (2026-10-10). macOS counts as accepted only after
+Level-2 setup acceptance on real hardware; see [Acceptance](../acceptance.md).
+That acceptance is recorded for Claude Code (2026-10-11); Codex is still pending.
+
+## Context
+
+`setup` refused every operation on macOS with `platform_unsupported`. #28
+reported this from a Mac: Doctor and a manual registration worked, but
+`--verify` and the ownership lifecycle were unavailable. ADR 0003 names
+repeated setup friction beyond version drift as a trigger to revisit this
+area.
+
+The setup fence relied on three Linux facts:
+
+- util-linux `flock` locks the open file description of the ownership lock
+  file, and the transaction guardian inherits it;
+- a `/proc` scan proves that no non-zombie member of a client command's
+  process group remains before the fence is released;
+- `statfs` magic numbers identify the local filesystems on which lock and
+  fsync semantics are accepted.
+
+None of them carries over: macOS ships no `flock(1)` and no `/proc`, and its
+`statfs` `f_type` is a dynamically assigned VFS index rather than a stable
+magic number.
+
+## Decision
+
+`setup` supports Linux and macOS. Every other platform still fails closed with
+`platform_unsupported` before any client command is spawned.
+
+`src/setup-platform.ts` owns the operating-system facts behind the fence. Its
+macOS primitives are:
+
+- **Lock.** The lock file is opened with `O_EXLOCK | O_NONBLOCK`. XNU takes a
+  flock(2)-semantics lock on the open file description at open time. A busy
+  lock is retried every 50 ms within the existing acquisition bound, and the
+  guardian inherits the locked description as on Linux.
+- **Process-group proof.** The trusted system `/bin/ps -A -o pid=,pgid=,stat=`
+  is parsed strictly. A scan that fails, times out, has an unexpected line or
+  does not list the caller is `unknown`, and `unknown` retains the fence.
+- **Filesystem.** The ownership directory must have the same `statfs` type
+  as `/`, which is the APFS system volume on every macOS that Node.js 22
+  supports. Any other type fails closed.
+
+Public result codes, statuses, exit codes and the result schema do not
+change. CI runs on Linux, macOS 15 and macOS 26. A `verify` job aggregates
+the matrix, so the required status check keeps its name.
+
+## Consequences
+
+- Operators on macOS get the same lifecycle, ownership records and
+  verification as on Linux, including `--verify` for a registration that
+  `setup` made.
+- On macOS, the proof that no live group member remains rests on `/bin/ps`,
+  which sits on the sealed system volume, plus the uid and mode check that
+  already guarded `flock`. As on Linux, it does not cover descendants that
+  escape the process group, and it does not promise PID reaping.
+- An ownership directory on HFS+, exFAT, a network volume or any other
+  non-APFS filesystem fails closed on macOS.
+- Intel Macs run the same code path but are not in the CI matrix.
+- The guardian and the process runner load the platform module with a
+  dynamic import, because source-mode tests run them through Node type
+  stripping. `setup-platform.js` is therefore a mandatory release artifact
+  next to `main.js` and `setup-command-guardian.js`.
+
+## Alternatives considered
+
+- **A `lockf(1)` helper and `/sbin/mount` parsing.** This would have mirrored
+  the Linux shape. Rejected: the descriptor mode of `lockf` on macOS 15 and
+  the `mount` output format are unverified.
+- **A weaker macOS profile without the kernel fence or the process-group
+  proof.** Rejected: it would break the guarantee that a later setup
+  transaction cannot race an orphaned client command.
+- **`kill(-pgid, 0)` as the process-group proof.** Rejected: the XNU source
+  handles groups that contain only zombies inconsistently.
+
+## Revisit triggers
+
+- The `ps` output format or its `stat` letters change.
+- The `O_EXLOCK` semantics of open(2) change.
+- The minimum macOS version that Node.js supports changes.
+- A request to add Intel Macs to CI, or to support another platform.

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

@@ -0,0 +1,58 @@
+# ADR 0006: Execution profiles may load pinned Pi extensions
+
+**Status:** Accepted (2026-10-11). Issue #34. Design:
+[Pi extensions design](../pi-extensions-design.md).
+
+## Context
+
+Embedded sessions loaded no Pi extensions. Providers that exist only as Pi
+extensions, such as `cursor` from `pi-cursor-sdk`, were unusable through Pi
+Session MCP although Pi had them installed and authenticated.
+
+ADR 0003 chose maintenance without a new feature phase. Unlike ADR 0005,
+which followed a fired ADR 0003 revisit trigger, this is a scope expansion
+the owner explicitly approved (2026-10-11, issue #34).
+
+## Decision
+
+An execution profile may name Pi extensions as
+`npm:<name>@<exact version>`.
+- The server resolves each one from Pi's own user install, normally
+  `~/.pi/agent/npm/node_modules/<name>` from `pi install npm:<name>`, and never
+  installs anything. A package installed anywhere else, for example with
+  `npm i -g`, counts as not installed.
+- A missing package or another installed version fails closed before a session
+  exists.
+- An extension loads with its full capabilities: providers, tools, hooks and
+  system-prompt changes.
+- In `read-only` profiles the model's tools stay `read`, `grep`, `find` and
+  `ls`.
+- In `coding` profiles every extension tool may be active.
+- An extension tool name that collides with another tool fails closed in both
+  profiles.
+
+A profile with extensions uses the Pi SDK session-lifecycle API with its own
+model runtime per session:
+- `createAgentSessionServices`, then the existing verification, then
+  `createAgentSessionFromServices` and `bindExtensions`.
+- Close goes through `AgentSessionRuntime.dispose()`, which emits
+  `session_shutdown`.
+
+Profiles without extensions keep the previous path. Client prompts are plain
+text for every profile: they never dispatch extension commands, skills or
+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
+
+- An allowlisted extension is trusted operator code with the user's full
+  rights inside the server process. Version pinning prevents silent updates,
+  not tampering with the installed package.
+- Extensions may persist their own state; Pi Session MCP itself stays
+  in-memory.
+- A child process that an extension starts with inherited stdio can still
+  write to the MCP stream directly. This is a documented residual risk.
+- Extension tool names are checked for conflicts after loading and again after
+  binding. A tool that an extension registers later, during a turn, is not
+  re-checked, because allowlisted extensions are trusted code.
+- Doctor checks configured extensions offline by reading their manifests.

package/docs/architecture.md

@@ -79,4 +79,4 @@ Public errors are stable and sanitized. They omit caller values, complete prompt
 
 ## Scope
 
-The product boundary is local stdio and in-memory-only operation for one trusted local MCP peer. A controller keeps one immutable configuration/profile snapshot for its lifetime; file edits require a genuinely new controller process and do not hot-reload, mark stale, or mutate running sessions. Each new session performs external catalog discovery within the loaded grants, so catalog changes do not require a controller restart, but a running session's active tools remain fixed. Restarting the controller loses all sessions; reconnecting a client reloads configuration only when it actually starts a new controller process. Capability discovery reports captured metadata only and does not prove current-file freshness, server reachability, provider availability, or catalog state. It excludes HTTP, a web UI, persistence/resume, remote access, multi-user behavior, transcript export, streaming, live provider/model discovery, availability probes during capability discovery, and provider credential management. A coding execution profile is an application-level tool selection, not an OS sandbox.
+The product boundary is local stdio and in-memory-only operation for one trusted local MCP peer. Allowlisted Pi extensions may persist state of their own outside this boundary, and their input hooks see every client prompt as `rpc` input, never `interactive`; Pi Session MCP itself keeps no state beyond process memory. A controller keeps one immutable configuration/profile snapshot for its lifetime; file edits require a genuinely new controller process and do not hot-reload, mark stale, or mutate running sessions. Each new session performs external catalog discovery within the loaded grants, so catalog changes do not require a controller restart, but a running session's active tools remain fixed. Restarting the controller loses all sessions; reconnecting a client reloads configuration only when it actually starts a new controller process. Capability discovery reports captured metadata only and does not prove current-file freshness, server reachability, provider availability, or catalog state. It excludes HTTP, a web UI, persistence/resume, remote access, multi-user behavior, transcript export, streaming, live provider/model discovery, availability probes during capability discovery, and provider credential management. A coding execution profile is an application-level tool selection, not an OS sandbox.

package/docs/client-setup-design.md

@@ -22,22 +22,34 @@ Codex supports only `codex:user:pi-session-mcp`. Claude Code supports `user`,
 registration output, or scope outside the recorded contracts is `unsupported`,
 and the client version is reported for information only. The adapters do not
 parse undocumented client config files.
-Setup is currently supported on Linux with a root-owned, non-writable
-util-linux `flock` at `/usr/bin/flock` or `/bin/flock`, readable `/proc`, and an
-ownership directory on ext2/3/4, XFS, Btrfs, tmpfs, overlayfs, ZFS, F2FS,
-UBIFS, or bcachefs. Other filesystems fail closed before lock acquisition.
-Every non-Linux platform fails closed with `platform_unsupported` before any
-client command is spawned.
+Setup is supported on Linux and macOS
+([ADR 0005](adr/0005-macos-setup-platform.md)); `src/setup-platform.ts` owns
+the operating-system facts behind the fence.
+
+- **Linux:**
+  - a root-owned, non-writable util-linux `flock` at `/usr/bin/flock` or
+    `/bin/flock`;
+  - readable `/proc`;
+  - an ownership directory on ext2/3/4, XFS, Btrfs, tmpfs, overlayfs, ZFS,
+    F2FS, UBIFS, or bcachefs.
+- **macOS:**
+  - the root-owned, non-writable system `/bin/ps`;
+  - an ownership directory with the same `statfs` type as `/`, which is the
+    APFS system volume on every macOS that Node.js 22 supports. macOS assigns
+    `f_type` dynamically, so no fixed number is compared.
+
+Other filesystems fail closed before lock acquisition. Every other platform
+fails closed with `platform_unsupported` before any client command is spawned.
 
 ## Ownership and transactions
 
 Each adapter exposes inspection, apply, verify, and remove operations. Apply first inspects and refuses divergence; equivalent registrations are left unchanged. Before adding an absent registration, setup records a path-free `pending` transaction containing only the target, an opaque fingerprint, the previous `absent` state, and a transaction identifier. Post-apply inspection promotes it to `owned`. Rollback/remove require owned metadata and the same effective fingerprint. Any mismatch fails closed and leaves the registration untouched.
 
-The production bridge derives Node from `process.execPath` and the entry point from the package root; configuration comes only from `PI_SESSION_MCP_CONFIG`. These values are internal command arguments and never CLI arguments, reports, or metadata. The opaque ownership fingerprint also binds `package.json`, the lockfile when the installation has one, and every built runtime JavaScript module. Both `main.js` and the regular, non-symlink `setup-command-guardian.js` are mandatory release artifacts; any runtime symlink fails closed. A package/lock mismatch or later build-content drift therefore fails closed instead of silently reusing ownership. Public client commands run through a bounded `CommandRunner` (timeout, process-group termination, and output cap); undocumented config files are not parsed.
+The production bridge derives Node from `process.execPath` and the entry point from the package root; configuration comes only from `PI_SESSION_MCP_CONFIG`. These values are internal command arguments and never CLI arguments, reports, or metadata. The opaque ownership fingerprint also binds `package.json`, the lockfile when the installation has one, and every built runtime JavaScript module. `main.js` and the regular, non-symlink `setup-command-guardian.js` and `setup-platform.js` are mandatory release artifacts; any runtime symlink fails closed. A package/lock mismatch or later build-content drift therefore fails closed instead of silently reusing ownership. Public client commands run through a bounded `CommandRunner` (timeout, process-group termination, and output cap); undocumented config files are not parsed.
 
-The production CLI uses an atomic durable store with restrictive filesystem modes; the in-memory store exists only for library tests. Neither form persists paths, environment values, secrets, prompts, SDK errors, or auth metadata. On Linux, a stable, never-renamed lock file is held through a kernel `flock` for the complete inspect → pending → client mutation → owned transaction. Newly created ownership directories and every atomic state rename are fsynced through their parent directory before success. There is no clock-based stale recovery: the kernel releases the lock only when every holder of the locked open-file description exits. Missing or untrusted `flock`, an unsupported filesystem, a symlink/non-regular lock file, or an inode mismatch fails closed. The trusted same-UID operator must not unlink or replace the stable lock path while setup is running; setup checks its inode before acquisition, after acquisition, and before exposing transaction access, but same-UID filesystem tampering is outside the fence's trust boundary. A later run reconciles `pending` state: a matching equivalent registration is promoted to owned, an absent registration is safely retried, and any divergence fails closed.
+The production CLI uses an atomic durable store with restrictive filesystem modes; the in-memory store exists only for library tests. Neither form persists paths, environment values, secrets, prompts, SDK errors, or auth metadata. A stable, never-renamed lock file is held through a kernel lock for the complete inspect → pending → client mutation → owned transaction. On Linux, the trusted util-linux `flock` locks the open file description that setup opened. On macOS, setup opens the lock file with `O_EXLOCK | O_NONBLOCK`, which takes a lock with flock(2) semantics on the open file description at open time; a busy lock is retried every 50 ms within the same acquisition bound. Newly created ownership directories and every atomic state rename are fsynced through their parent directory before success. There is no clock-based stale recovery: the kernel releases the lock only when every holder of the locked open-file description exits. A missing or untrusted `flock` or `ps`, an unsupported filesystem, a symlink/non-regular lock file, or an inode mismatch fails closed. The trusted same-UID operator must not unlink or replace the stable lock path while setup is running; setup compares the inode of the open lock file with the path after opening it, again once the fence is held, and before exposing transaction access, but same-UID filesystem tampering is outside the fence's trust boundary. A later run reconciles `pending` state: a matching equivalent registration is promoted to owned, an absent registration is safely retried, and any divergence fails closed.
 
-Mutating public client commands run under a transaction guardian that inherits the locked file description, starts the client in its own process group, and watches both the parent PID and IPC channel. Parent EOF, `SIGINT`, `SIGTERM`, or command timeout causes TERM then KILL. The guardian releases the fence only after `/proc` confirms that no non-zombie group member remains. Indeterminate cleanup returns a stable failure to the caller while the detached guardian retains the fence and continues cleanup, preventing a later setup transaction from racing the orphan. A mutation already accepted by an external client CLI or configuration backend cannot be rolled back automatically; ownership remains `pending` for reconciliation.
+Mutating public client commands run under a transaction guardian that inherits the locked file description, starts the client in its own process group, and watches both the parent PID and IPC channel. Parent EOF, `SIGINT`, `SIGTERM`, or command timeout causes TERM then KILL. The guardian releases the fence only after a determinate process-table scan confirms that no non-zombie group member remains: `/proc` on Linux, and on macOS a strictly parsed `/bin/ps -A -o pid=,pgid=,stat=` that must list the scanning process itself. Indeterminate cleanup returns a stable failure to the caller while the detached guardian retains the fence and continues cleanup, preventing a later setup transaction from racing the orphan. A mutation already accepted by an external client CLI or configuration backend cannot be rolled back automatically; ownership remains `pending` for reconciliation.
 
 Here “gone” means no group member can still execute: a zombie has terminated and
 released its file descriptors, even when its PID awaits an external reaper. The

package/docs/client-setup.md

@@ -7,8 +7,14 @@ installation with upgrade and removal, start with [Installation](installation.md
 ## Prerequisites
 
 - Node.js **22.19.0 or newer**
-- Linux with a root-owned util-linux `flock` at `/usr/bin/flock` or `/bin/flock`,
-  readable `/proc`, and a supported local ownership filesystem
+- Linux or macOS. For `setup` also:
+  - on Linux, a root-owned util-linux `flock` at `/usr/bin/flock` or
+    `/bin/flock`, readable `/proc`, and a supported local ownership filesystem;
+  - on macOS, the system `/bin/ps` and an ownership directory on the APFS
+    volume type of `/`.
+
+  A manual registration does not need these; see
+  [Register without setup](installation.md#register-without-setup).
 - A local checkout of this repository
 - Existing local Pi authentication only when sending a real prompt
 
@@ -64,11 +70,20 @@ divergent existing registration is reported and never automatically replaced.
 Ownership is durable and contains only path-free, secret-free pending/owned
 state. A kernel-fenced guardian retains transaction ownership until every
 mutating client process-group member is gone, including after parent signals or
-hard parent exit. Non-Linux setup fails closed before client spawn.
-Supported ownership filesystems are ext2/3/4, XFS, Btrfs, tmpfs, overlayfs,
-ZFS, F2FS, UBIFS, and bcachefs. Network, FUSE, unreadable `/proc`, an untrusted
-`flock` binary, or same-UID replacement of the stable lock path are outside the
-accepted setup boundary and fail closed where they can be detected.
+hard parent exit. Setup on any platform other than Linux and macOS fails
+closed before client spawn.
+
+Supported ownership filesystems:
+- **Linux:** ext2/3/4, XFS, Btrfs, tmpfs, overlayfs, ZFS, F2FS, UBIFS, and
+  bcachefs.
+- **macOS:** the APFS volume type of `/`.
+
+The following are outside the accepted setup boundary and fail closed where
+they can be detected:
+- network or FUSE filesystems;
+- unreadable `/proc`;
+- an untrusted `flock` or `ps` binary;
+- same-UID replacement of the stable lock path.
 
 Verify runs Doctor, checks exact registration equality, and then performs a
 bounded direct MCP `initialize`, `tools/list`, and
@@ -103,7 +118,7 @@ Create an unversioned JSON configuration file such as `pi-session-mcp.json`:
 }
 ```
 
-Configuration is strict. A profile has exactly `default`, `permissionProfile`, `provider`, `model`, and `thinkingLevel`; aliases follow the configured alias naming rules. At least one profile and exactly one default are required, and that default must be `read-only`. `thinkingLevel` is one of `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. Workspace paths resolve relative to the configuration file. Clients can select only configured aliases, never an arbitrary working directory.
+Configuration is strict. A profile has exactly `default`, `permissionProfile`, `provider`, `model`, and `thinkingLevel`, plus the optional `mcpServers` and `extensions` described in [Installation](installation.md); aliases follow the configured alias naming rules. At least one profile and exactly one default are required, and that default must be `read-only`. `thinkingLevel` is one of `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. Workspace paths resolve relative to the configuration file. Clients can select only configured aliases, never an arbitrary working directory.
 
 Use placeholders until a locally available provider/model pair is known. Do not put keys, tokens, credential objects, headers, base URLs, or authentication paths in this file.
 
@@ -186,8 +201,8 @@ Server deadlines are profile-specific authentication/catalog work 5,000 ms per o
 
 There are eight tools: `pi_capabilities_get`, `pi_session_start`, `pi_session_list`, `pi_session_get`, `pi_session_prompt`, `pi_session_abort`, `pi_session_close`, and `pi_turn_get`. Capability discovery accepts only `{}`. `pi_session_start` rejects the old `profile` input, raw `provider`, `model`, `thinkingLevel`, credential-like fields, and all unknown fields. Its safe session metadata includes the configured execution-profile alias and post-verified provider/model/effective thinking level; the existing `profile` output remains derived permission metadata.
 
-The returned `thinkingLevel` records the effective Pi session setting. Pi
-Control compares it with the configured profile selection before admitting the
+The returned `thinkingLevel` records the effective Pi session setting. The
+server compares it with the configured profile selection before admitting the
 session; it does not verify provider-side reasoning or measure or cap its
 reasoning-token budget: a provider may use reasoning tokens even when the session
 selects `off`. Pi Session MCP does not project thinking content or provider-side