pi-session-mcp 0.6.4 → 0.7.1

package/docs/doctor-design.md

@@ -9,8 +9,9 @@ directory: an npm executable can run from any directory.
 `runDoctor` returns one frozen result model (`schemaVersion: 1`, `ok`, a
 sanitized semver `packageVersion` when metadata is available, ordered `checks`,
 and `exitCode`). Human and JSON output are projections of that same model.
-Subjects are only fixed component names or validated workspace aliases; paths,
-configuration values, errors, credentials, and provider data are never output.
+Subjects are only fixed component names, validated workspace aliases, or
+validated `<profile>:<package>` pairs; paths, configuration values, errors,
+credentials, and provider data are never output.
 
 Each check is `{ id, severity, subject, remediation? }`. Severity is `ok`,
 `warning`, or `error`; remediation is a fixed safe sentence. The initial IDs
@@ -31,6 +32,10 @@ and owners are:
 | `workspace_not_directory` | A resolved workspace is not a directory | validated workspace alias |
 | `workspace_unreadable` | A resolved workspace cannot be read | validated workspace alias |
 | `workspace_not_writable` | A workspace is not writable while a coding profile can target it | validated workspace alias |
+| `extension_missing` | Pi has no user install of a package that a profile's `extensions` names | `<profile>:<package>` |
+| `extension_version_mismatch` | The installed manifest's version differs from the pinned version, or the manifest or its `pi.extensions` entries are invalid | `<profile>:<package>` |
+
+Doctor reads extension manifests from Pi's user install location only; it never installs packages and never imports extension code.
 
 The Doctor reuses `loadConfig`; it does not duplicate alias, profile, thinking
 level, or read-only-default rules. Workspace values are used only for local

package/docs/installation.md

@@ -35,19 +35,25 @@ the same arguments.
 
 ## Requirements
 
-- Linux. `setup` fails closed on every other platform, and the server has only
-  been accepted on Linux.
+- Linux or macOS. `setup` fails closed on every other platform. macOS is tested
+  in CI on macOS 15 and 26 on Apple silicon. Setup acceptance on a real Mac is
+  recorded for Claude Code only; Codex is still pending. See
+  [Acceptance](acceptance.md#status).
 - Node.js **22.19.0 or newer**. `setup` registers the absolute path of the Node
   executable that runs it, so run it with the Node installation that clients
   should use.
-- For `setup`: a root-owned util-linux `flock` at `/usr/bin/flock` or
+- For `setup` on Linux: a root-owned util-linux `flock` at `/usr/bin/flock` or
   `/bin/flock`, readable `/proc`, and the ownership state directory
   `~/.local/state/pi-session-mcp` on ext2/3/4, XFS, Btrfs, tmpfs, overlayfs, ZFS,
   F2FS, UBIFS or bcachefs. Network and FUSE filesystems fail closed.
+- For `setup` on macOS: the system `/bin/ps`, and the ownership state directory
+  `~/.local/state/pi-session-mcp` on the same filesystem type as `/`, which is
+  APFS. A home directory on HFS+, exFAT, a network volume or any other
+  filesystem fails closed.
 - Codex CLI or Claude Code. `setup` does not pin client versions. It accepts a
   client whose public `mcp` command output matches the expected contract and
   reports `unsupported` otherwise. The contract was last recorded with Codex CLI
-  `0.162.0` and Claude Code `2.1.296`. Manual registration, described in the
+  `0.162.1` and Claude Code `2.1.296`. Manual registration, described in the
   [client setup reference](client-setup.md), works independently of `setup`.
 - For real prompts only: local Pi authentication and a provider and model pair
   that the local Pi configuration knows. Installation, Doctor and `setup` need
@@ -146,6 +152,10 @@ Rules:
   `azure`; a profile that names the old key must be changed.
 - A profile may grant tools from local stdio MCP servers through `mcpServers`.
   See [External MCP tools in embedded sessions](session-mcp.md).
+- A profile may load Pi extensions that Pi has installed, through
+  `extensions`: a list of at most 8 entries of the form
+  `npm:<name>@<exact version>`, each package once. Ranges, tags, `git:`
+  sources, paths and build metadata (`+build`) are rejected. See [Pi extensions](#pi-extensions).
 - Never put keys, tokens, credential objects, headers, base URLs or
   authentication paths into this file.
 
@@ -245,6 +255,67 @@ If a registration already exists, `setup` never replaces it:
 Start a new client session after registering. The client launches the server on
 demand; there is nothing to start by hand.
 
+### Register without setup
+
+`setup` runs on Linux and macOS. On every other platform, Windows included, it
+refuses every operation, `--verify` included, with `platform_unsupported`
+before it starts a client command. On Linux and macOS, `--apply`, `--verify`,
+`--rollback` and `--remove` also fail closed when the platform prerequisites in
+[Requirements](#requirements) are not met. A manual registration needs none of
+this: it uses the client's own commands and writes no ownership state. Use it
+when `setup` cannot run, or when you manage client configuration yourself. No
+acceptance level covers this path.
+
+1. Install as in section 1, configure as in section 2, and run Doctor as in
+   section 3. Doctor has no platform-specific check and needs neither the lock
+   nor the process-table prerequisites of `setup`.
+2. Register the server with the client's own command, as the
+   [Codex](client-setup.md#register-with-codex) and
+   [Claude Code](client-setup.md#register-with-claude-code) sections of the
+   client setup reference show. Use absolute paths and the Node executable that
+   clients should use. The entry point is `dist/main.js` inside the package
+   directory: in an npm installation `echo "$(npm root -g)/pi-session-mcp"`
+   prints that directory, in a release checkout it is the checkout. Write the
+   resulting absolute path into the command; a substitution inside the single
+   quotes of the Codex example would not be expanded.
+3. Check the registration. These checks are not a replacement for
+   `setup --verify`: it also performs a bounded direct MCP handshake, and
+   outside `setup` nothing does that yet. The last check below depends on the
+   client, which can hang or hide a handshake problem, so treat the result as
+   weaker evidence than `--verify`.
+   - Doctor passed in item 1.
+   - Compare the stored registration with what you meant to register.
+     `claude mcp get pi-session-mcp` and `codex mcp get pi-session-mcp` print
+     the Node executable, the entry point and the configuration path that the
+     client stored, and Claude Code also prints the scope. Each must equal the
+     value you passed. `--verify` makes this comparison for `setup`. Without
+     it, a registration that still points at an old release directory passes
+     every other check.
+   - `claude mcp list` and `claude mcp get pi-session-mcp` report `Connected`
+     when the client could start the server and complete the MCP connection.
+     A registration with `-s project` reports `Pending approval` instead,
+     because Claude Code connects to a project server only after you approve it
+     in a session in that project. Approve it, then expect `Connected`.
+   - Start a new client session and call `pi_capabilities_get` with `{}`. The
+     client lists the eight tools, and the call returns the configured aliases.
+
+   Like `--verify`, none of these starts a Pi session or contacts a provider.
+4. Upgrade and remove with the client's own commands. Nothing owns the
+   registration and it is not bound to the build.
+   - An npm upgrade replaces the package in place and keeps the entry point.
+     Close the client sessions, install the new version as in section 1, run
+     Doctor as in section 3, and repeat the checks of item 3. Do not run the
+     `cp` of section 2 again: it replaces your configuration with the packaged
+     example.
+   - A new release directory needs a new registration. Run
+     `codex mcp remove pi-session-mcp` or
+     `claude mcp remove pi-session-mcp -s <scope>`, add the server again with
+     the new paths, run Doctor, and repeat the checks of item 3.
+   - To remove it entirely, run the client's remove command, then uninstall the
+     package or delete the release directory and the configuration file. A
+     manual registration leaves no ownership state, so the `--remove` of the
+     Remove section does not apply.
+
 ## 5. Run a first session
 
 From the client, call the tools in this order:
@@ -273,6 +344,56 @@ configuration or credentials.
 The configuration path is part of the registration. Editing the file in place
 needs no new registration; moving it does.
 
+## Pi extensions
+
+An execution profile can load Pi extensions that Pi has installed. Install them
+with Pi (`pi install npm:<name>`; update with `pi update --extensions`), then
+pin the installed version in the profile:
+
+```json
+"code-cursor": {
+  "default": false,
+  "permissionProfile": "coding",
+  "provider": "cursor",
+  "model": "<model id from Pi's cursor catalog>",
+  "thinkingLevel": "high",
+  "extensions": ["npm:pi-cursor-sdk@0.5.3"]
+}
+```
+
+- **Install location.** Only Pi's own user install counts:
+  `<Pi agent dir>/npm/node_modules/<name>`, normally `~/.pi/agent/npm/…`,
+  created by `pi install npm:<name>`. A package installed with `npm i -g` is
+  reported as not installed: sessions report `extension_not_installed`, Doctor
+  reports `extension_missing`.
+- **Version pin.** The server never installs or updates extensions. If Pi has
+  another version installed, sessions of that profile fail with
+  `extension_version_mismatch` and Doctor reports it. After `pi update
+  --extensions`, update the pinned version and restart the client.
+- **Full capabilities.** An extension loads with its providers, tools, hooks
+  and system-prompt changes. In `read-only` profiles the model still gets only
+  `read`, `grep`, `find` and `ls`; in `coding` profiles every extension tool
+  may be active. Extension commands never run from client prompts, but
+  extension input hooks can still see, rewrite or consume a client prompt;
+  they receive it with `source: "rpc"`, never `interactive`.
+- **Fail-closed start.** A session start fails with `extension_load_failed` if
+  an extension reports a hook error while binding. It fails the same way if an
+  extension registers an MCP server while loading or starting, because Pi's
+  built-in MCP extension is not loaded. An extension tool whose name collides
+  with another tool, or whose name is not 1 to 64 letters, digits, `_` or `-`
+  (not starting with `-`), or whose name Pi treats as an MCP tool (starting
+  with `mcp__`, or `list_mcp_resources`, `list_mcp_resource_templates`,
+  `read_mcp_resource`), fails with `extension_tool_conflict`.
+- **Cursor runtime.** `pi-cursor-sdk` runs Cursor's local agent runtime. That
+  runtime starts its own processes (for example git and the MCP servers
+  configured for Cursor) and may act through Cursor's own tooling, so a
+  `read-only` profile limits only Pi's tools, not what the Cursor runtime does.
+- **Trust.** Only list extensions you trust like any other program you run:
+  they execute inside the server process with your rights.
+- **Cursor sign-in limit.** Without a stored Cursor key, `pi-cursor-sdk`
+  reports a placeholder key. Session start succeeds and the first prompt fails
+  with `turn_failed`. Store the key with Pi first.
+
 ## Upgrade
 
 `setup` binds each owned registration to the package manifests and to every

package/docs/macos-setup-design.md

@@ -0,0 +1,386 @@
+# macOS setup platform design
+
+**Status:** Implemented (2026-10-10); Level-2 acceptance on real hardware is
+recorded for Claude Code (2026-10-11) and pending for Codex. Tracking issue: #32. Follows #28 and PR #30. The decision record is
+[ADR 0005](adr/0005-macos-setup-platform.md).
+
+## Goal
+
+The complete setup lifecycle (`--dry-run`, `--apply`, `--verify`,
+`--rollback`, `--remove`) works on macOS with the same guarantees as on Linux:
+
+- a kernel lock fences the whole inspect → pending → client mutation → owned
+  transaction;
+- the fence is released only after a determinate process-table scan confirms
+  that no non-zombie member of a client command's process group remains;
+- the ownership directory sits on a filesystem whose lock and fsync semantics
+  are accepted.
+
+macOS counts as accepted only after Level-2 setup acceptance on real hardware
+(see [Acceptance on real hardware](#acceptance-on-real-hardware)). Until then,
+the documentation calls it CI-tested.
+
+## Non-goals
+
+- Windows and every platform other than `linux` and `darwin` keep failing
+  closed with `platform_unsupported` before any client command is spawned.
+- Intel Macs are not part of the CI matrix. The code path is identical, so
+  they are expected to work but are documented as untested.
+- The ownership location stays `~/.local/state/pi-session-mcp/` on both
+  platforms.
+- No new public result codes, statuses, exit codes or result schema changes.
+- No release or version change; that is a separate release change.
+
+## Current Linux dependencies
+
+| Concern | Linux mechanism | Location |
+| --- | --- | --- |
+| Kernel lock | util-linux `flock -E 75 -w N 3` locks the open file description that the parent opened; the guardian inherits it as fd 3 | `src/setup-process.ts` `acquireSetupGuardian` |
+| Process-group proof | `/proc/<pid>/stat` scan; `Z` entries do not count as live | `src/setup-process.ts` `processGroupState`, `src/setup-command-guardian.ts` `groupState`, `processTableReadable` |
+| Filesystem | `statfs().type` allowlist of Linux magic numbers | `src/setup-ownership.ts` `SUPPORTED_LOCAL_FILESYSTEMS` |
+| Platform gates | `process.platform !== "linux"` | `src/setup-main.ts`, `src/setup-process.ts` (runner, guardian), `src/setup-ownership.ts` |
+
+Facts that rule out a direct port, with sources from the research on
+2026-10-10:
+
+- macOS ships no `flock(1)`.
+- macOS has no `/proc`.
+- On macOS, `statfs` `f_type` is a dynamically assigned VFS type index, not a
+  stable magic number (Apple Developer Forums thread 87745). Node does not
+  expose `f_fstypename`.
+
+## Design
+
+### Platform module
+
+A new module `src/setup-platform.ts` owns every operating-system fact that the
+fence relies on. It has no relative imports, so the guardian can load it in
+both source and built form.
+
+```ts
+export type SetupPlatform = "linux" | "darwin";
+export function currentSetupPlatform(platform?: NodeJS.Platform): SetupPlatform | undefined;
+
+export type ProcessGroupState = "alive" | "gone" | "unknown";
+export interface ProcessTable {
+  /** "alive" if any non-zombie process has this process group ID. */
+  groupState(group: number): Promise<ProcessGroupState>;
+  /** True only if a scan is trustworthy and contains the calling process. */
+  readable(): Promise<boolean>;
+  /** Poll interval for cleanup loops: 10 ms on Linux, 50 ms on macOS. */
+  readonly pollMs: number;
+}
+export function createProcessTable(platform: SetupPlatform): ProcessTable;
+
+export function parsePsTable(output: string): readonly ProcessEntry[] | undefined;
+export function isTrustedSystemBinary(path: string): boolean;
+export function assertSupportedFilesystem(path: string, platform: SetupPlatform): Promise<void>;
+export function openLockedDarwin(path: string, options: DarwinLockOptions): Promise<FileHandle>;
+```
+
+The exact signatures may gain injected dependencies for tests, such as `stat`,
+`statfs`, `open` and the `ps` executor. The behavior below is the contract.
+
+`isTrustedSystemBinary` is the existing `flock` check, moved and shared: a
+regular file owned by uid 0, not group- or world-writable, and executable.
+
+### Kernel lock
+
+**Linux (unchanged):**
+
+1. The parent opens the lock file with `O_CREAT | O_RDWR | O_NOFOLLOW`.
+2. It validates the file.
+3. A trusted `flock -E 75 -w N 3` locks the shared open file description.
+4. The guardian inherits that description as fd 3.
+
+**macOS:**
+
+1. The parent opens the lock file with
+   `O_CREAT | O_RDWR | O_NOFOLLOW | O_EXLOCK | O_NONBLOCK`.
+   - `O_EXLOCK` (`0x20`) and `O_NONBLOCK` (`0x4`) come from XNU
+     `bsd/sys/fcntl.h`. `fs.constants` does not export `O_EXLOCK`, so it is a
+     named constant in the module with that citation.
+   - XNU takes an `F_FLOCK` write lock on the open file description at open
+     time. libuv passes the flags through unchanged, adding only
+     `O_CLOEXEC`.
+2. `EAGAIN` or `EWOULDBLOCK` means the lock is held elsewhere. The open is
+   retried every 50 ms until the existing acquisition timeout
+   (`acquireTimeoutMs`, default 30 s, at most 120 s); then it fails with
+   `ownership_lock_busy`.
+   - An abort signal ends the loop with `operation_aborted`.
+   - Every other error, including `EOPNOTSUPP` or `ENOTSUP` on a filesystem
+     without locking, is `ownership_lock_unavailable`.
+   - A failed attempt returns no descriptor and cannot release another
+     holder's lock, because these are flock semantics on the open file
+     description.
+3. The rest is the Linux path, unchanged:
+   - `chmod 0600`;
+   - fsync of the file and its directory;
+   - the inode comparison between descriptor and path;
+   - the `afterLockOpen` test hook;
+   - `validateFence`;
+   - starting the guardian with the locked descriptor as fd 3;
+   - the second validation.
+4. `acquireSetupGuardian` derives the lock step from the platform:
+   - on Linux it runs the util-linux step;
+   - on macOS it skips it, because the caller passes a descriptor from
+     `openLockedDarwin` that is already locked.
+
+   There is no lock-mode parameter, so a caller cannot select the
+   already-locked mode for an unlocked descriptor by mistake. The guardian
+   start, IPC protocol and release are shared.
+
+### Process-group proof
+
+**Linux:** the existing `/proc` scan moves unchanged into the platform module.
+The two copies in `setup-process.ts` and `setup-command-guardian.ts` become
+one.
+
+**macOS:** one scan runs `/bin/ps -A -o pid=,pgid=,stat=`. The call:
+
+- uses the absolute path;
+- passes `isTrustedSystemBinary` before every call;
+- runs with fixed arguments, an environment of only `LC_ALL=C`, a 2 s timeout
+  and a 1 MiB output cap;
+- is not detached, so `ps` is never a member of the group under test.
+
+`parsePsTable` accepts only lines that match `^\s*(\d+)\s+(\d+)\s+(\S+)\s*$`.
+Any other line rejects the whole output.
+
+The scan result is `unknown` if any of these holds:
+
+- `ps` is untrusted, fails to start, times out or exits non-zero;
+- the output exceeds the cap or fails to parse;
+- the output does not contain the calling process's own PID.
+
+Otherwise the result is `alive` if any entry has the requested process group
+ID and a `stat` that does not start with `Z`, and `gone` if none does.
+
+`readable()` is true only for a scan that is not `unknown`. The guardian sends
+`ready` only after `readable()` succeeds, as it does today with `/proc`.
+
+`kill(-pgid, 0)` is deliberately not used as proof. The XNU source treats
+zombie-only groups inconsistently.
+
+**Callers become asynchronous:**
+
+- the process runner's `finishAfterGroup`;
+- the MCP launcher's `kill`;
+- the guardian's `groupState` loops.
+
+Deadlines stay as they are (2 s report deadline, 1 s launcher cleanup). Only
+the poll interval comes from `ProcessTable.pollMs`.
+
+**Guardian loading.** The guardian is started as `.ts` in source-mode tests
+(Node type stripping) and as `.js` in production. A static relative import
+would fail in source mode. The guardian therefore loads the platform module
+with a dynamic import that picks `./setup-platform.ts` or
+`./setup-platform.js` next to itself. This is the same selection that
+`setup-process.ts` already uses to locate the guardian. `setup-platform.js`
+becomes a mandatory regular, non-symlink release artifact next to `main.js`
+and `setup-command-guardian.js` in `src/setup.ts`. The ownership fingerprint
+already binds every built runtime module.
+
+### Filesystem rule
+
+**Linux:** unchanged magic-number allowlist.
+
+**macOS:** the ownership directory, and the nearest existing ancestor that is
+checked before creation, must have the same `statfs().type` as `/`. The
+reasoning:
+
+- The minimum macOS that Node.js 22 supports is macOS 11.
+- From macOS 11 on, `/` is the sealed APFS system volume, so its type is
+  APFS in every case.
+- `f_type` identifies a filesystem type for the running kernel, so equality
+  with `/` means APFS.
+- APFS volumes are local.
+- HFS+, exFAT, MS-DOS, SMB, NFS, AFP and every other type fail closed with
+  `ownership_filesystem_unsupported`.
+
+Directory fsync uses the existing `FileHandle.sync()`. On macOS, libuv already
+tries `F_FULLFSYNC`, then `F_BARRIERFSYNC`, then `fsync`. Whether this
+succeeds on a directory descriptor on APFS is unverified, so a macOS CI test
+asserts it. A failure fails closed.
+
+### Platform gates
+
+`process.platform !== "linux"` becomes `currentSetupPlatform() === undefined`
+in these places:
+
+- `setup-main.ts`, before any client command;
+- the process runner, which returns exit code 126;
+- `acquireSetupGuardian`;
+- `DurableOwnershipStore.withLock`.
+
+## Failure semantics
+
+Public behavior is identical on both platforms:
+
+- The stable codes are unchanged. The internal lock and filesystem errors are
+  `ownership_lock_busy`, `ownership_lock_unavailable` and
+  `ownership_filesystem_unsupported`. They never reach a report. When one
+  ends an ownership transaction, the CLI reports `operation_failed` with
+  exit 1, or `operation_interrupted` with exit 130 or 143 after a signal. This
+  is the same as on Linux. Failures inside a transaction keep their existing
+  public codes, such as `ownership_unavailable` and `cleanup_failed`.
+- An `unknown` process-group state while the guardian holds the fence keeps
+  the fence and reports exit code 126 to the caller. Cleanup continues in the
+  detached guardian.
+- Exit codes stay `0`, `1`, `64`, `130` and `143`.
+- Results never contain paths, command arguments, command output or raw
+  errors. `ps` output never leaves the platform module.
+
+## Trust boundary and limits
+
+These are recorded in `threat-model.md`; `client-setup-design.md` names the platform requirements:
+
+- On macOS, the proof that no live group member remains rests on `/bin/ps`,
+  which sits on the sealed, SIP-protected system volume, together with the
+  uid and mode check.
+- Tampering by the same UID with the stable lock path stays outside the
+  fence's trust boundary on both platforms.
+- On both platforms, the fence does not cover descendants that escape the
+  process group, and it does not promise PID reaping.
+- The macOS lock depends on the documented `O_EXLOCK` behavior of open(2):
+  flock(2) semantics, with `EOPNOTSUPP` on filesystems without locking.
+
+## Testing
+
+**Unit tests, run on Linux and macOS with injected dependencies:**
+
+- `parsePsTable`:
+  - a live group, a zombie-only group and a foreign group;
+  - a malformed line, an extra header line, empty output;
+  - a missing own PID, a non-zero exit, output over the cap.
+- `isTrustedSystemBinary`: not root-owned, group-writable, world-writable,
+  not executable, not a regular file, missing. Like the existing `flock`
+  check, it follows symlinks, so Linux behavior is unchanged.
+- macOS filesystem rule: same type, different type, and `statfs` failure.
+- macOS lock loop:
+  - `EAGAIN` then success; persistent `EAGAIN` until the timeout gives
+    `ownership_lock_busy`;
+  - `EOPNOTSUPP` gives `ownership_lock_unavailable`;
+  - an abort during the wait gives `operation_aborted`;
+  - no descriptor leaks on any of these paths.
+- `currentSetupPlatform`: `linux`, `darwin`, `win32`, `freebsd`.
+
+**Integration tests:** their gate changes from `process.platform !== "linux"`
+to "setup platform supported", so they also run on macOS:
+
+- `test/setup-ownership.test.ts`: the durable store, including real lock
+  contention between processes;
+- `test/setup-process.test.ts`: the runner terminates a real process group,
+  and fence retention on an indeterminate scan;
+- `test/setup-main.test.ts`: the `SIGINT` and `SIGTERM` cleanup with exit
+  codes 130 and 143, and the stubborn process group;
+- `test/setup-lifecycle.test.ts`: the corrupt durable ownership store.
+
+**macOS-only tests:**
+
+- `O_EXLOCK` semantics:
+  - a second non-blocking open is busy while the first descriptor is open;
+  - a child process that inherited the descriptor keeps the lock after the
+    parent closes its copy;
+  - the lock is free after the last close.
+- Directory fsync on the test's temporary APFS directory succeeds.
+- `os.tmpdir()` passes the macOS filesystem rule.
+
+**Server lifecycle:** `test/process-fixture.ts` reads `/proc/<pid>/stat` and
+`/proc/<pid>/cmdline`. It moves to a platform helper that uses `/proc` on
+Linux and `/bin/ps -p <pid> -o stat=,command=` on macOS. Then
+`test/process-stdin-eof.test.ts` also runs on macOS and proves that the server
+exits on stdin EOF there. This is a separate commit.
+
+**Load sensitivity:** no timeout is raised in advance. Flaky tests observed on
+macOS runners are treated individually, with the cause recorded.
+
+## CI
+
+The ruleset "Protect main" requires a status check named `verify`. A plain
+matrix would rename it to `verify (macos-15)` and so on, and block every merge.
+The workflow therefore has two jobs:
+
+- **`test`:** a matrix over `os: [ubuntu-latest, macos-15, macos-26]` with
+  `fail-fast: false`, the same steps as today, and Node pinned to `22.19.0`.
+- **`verify`:** depends on `test`, always runs, and passes only if every
+  platform passed. It keeps the required check name, so the ruleset does
+  not change.
+
+Standard GitHub-hosted runners are free for this public repository. The Pi SDK
+canary stays on Linux.
+
+## Documentation and governance
+
+- **ADR 0005, "macOS as a supported setup platform":**
+  - It records that the B-type revisit trigger of ADR 0003 (repeated setup
+    friction) fired with #28.
+  - It records the chosen approach and the rejected alternatives:
+    - a `lockf(1)` helper with `/sbin/mount` parsing, rejected because the fd
+      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.
+  - It sets the condition that macOS counts as accepted only after Level-2
+    acceptance on real hardware.
+  - Its revisit triggers: a change in the `ps` output format, in `O_EXLOCK`
+    semantics, or in the minimum macOS version that Node supports.
+- **`AGENTS.md`:** the rule "Mutating setup is Linux-only and requires …"
+  becomes a rule for Linux or macOS, each with its platform's requirements.
+  This change to an agent rule is called out in the PR.
+- **`docs/client-setup-design.md` and `docs/threat-model.md`:** platform
+  requirements and the trust boundary for both platforms.
+- **`docs/installation.md`:**
+  - `setup` on macOS;
+  - "Register without setup" stays as a general alternative, without a macOS
+    special case.
+- **`README.md`:** the Status line names Linux and macOS, the macOS CI
+  versions, Intel as untested, and the acceptance status.
+- **`docs/acceptance.md`:** the macOS Level-2 checklist and its evidence
+  format.
+- **`CHANGELOG.md`:** an Unreleased entry.
+
+## Acceptance on real hardware
+
+A Level-2 run on the owner's Mac, from the PR branch build, records:
+
+- **Environment:** macOS version, architecture, Node version, Claude Code and
+  Codex versions.
+- **Before mutating:** `doctor`, and `setup --dry-run` for
+  `claude-code:user:pi-session-mcp` and `codex:user:pi-session-mcp`.
+- **The lifecycle, for each target:** `--apply`, `--verify`, `--rollback`,
+  then `--apply` and `--remove`.
+- **Lock contention:** two `--apply` runs for the same target, started in
+  parallel.
+  - The second waits for the first, because the acquisition timeout is 30 s.
+  - It then reports the registration as already equivalent.
+  - Both exit with 0, and the ownership record stays readable.
+  - A waiting run that reports `operation_failed` with exit 1 did not get the
+    lock within the timeout.
+- **Interruption:** Ctrl-C during `--apply` gives exit code 130, leaves no
+  process from the client command's group behind, and a following run
+  reconciles.
+- **Evidence:** exit codes and the sanitized human and JSON results. No paths,
+  environment values or secrets are recorded.
+
+The evidence is committed to the same PR before merge.
+
+## Delivery
+
+One branch, `feat/macos-setup`, and one PR referencing #32. Separate commits,
+in this order:
+
+1. platform module;
+2. macOS lock;
+3. process table and guardian;
+4. filesystem rule;
+5. server lifecycle fixture;
+6. CI matrix;
+7. documentation, ADR 0005 and `AGENTS.md`;
+8. acceptance evidence.
+
+The merge requires all of the following:
+
+- green CI on all three runners;
+- reviews without open findings;
+- the owner's evidence from the Mac.