pi-session-mcp 0.6.4 → 0.7.0

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. 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; 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

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 and paths 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,53 @@ 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.
+- **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 a plain identifier, 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