pi-session-mcp 0.8.3 → 0.12.0

package/docs/architecture.md

@@ -2,7 +2,7 @@
 
 ## Validated dependency baseline (2026-10-09)
 
-- [`@earendil-works/pi-coding-agent` 1.2.0](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) supplies the documented root exports used by this server, including `ModelRuntime` and `createAgentSession`. Since 0.99 the prompt preflight hook reports a dispatch disposition (`started`, `queued`, `handled`) and is not called on rejection; only `started` admits a public turn (`admitsTurn` in `src/sdk-pi-adapter.ts`). Model-visible tools are declared on transcript system messages rather than in the provider context. `test/sdk-contract.test.ts` pins both assumptions provider-free.
+- [`@earendil-works/pi-coding-agent` 1.4.0](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) supplies the documented root exports used by this server, including `ModelRuntime` and `createAgentSession`. Since 0.99 the prompt preflight hook reports a dispatch disposition (`started`, `queued`, `handled`) and is not called on rejection; only `started` admits a public turn (`admitsTurn` in `src/sdk-pi-adapter.ts`). Model-visible tools are declared on transcript system messages rather than in the provider context. `test/sdk-contract.test.ts` pins both assumptions provider-free.
 - [`@modelcontextprotocol/server` 2.3.1](https://www.npmjs.com/package/@modelcontextprotocol/server) supplies `McpServer`, structured tool output, and the stdio entry point.
 - [Zod 4.6.5](https://zod.dev/) validates strict configuration, tool input, and structured output.
 
@@ -13,9 +13,9 @@ validated config --> capability projection --> McpServer discovery tool
         |
         +---------> SessionRegistry --> PiSessionAdapter
                        |                    |
-                 in-memory state       SDK Pi adapter
-                 session + turn        ModelRuntime + AgentSession
-                 read models
+                 in-memory state       routing adapter
+                 session + turn        host: SDK ModelRuntime + AgentSession
+                 read models           container coding: writer relay
 ```
 
 There are three separate local CLI paths: the MCP stdio server (`main.ts`),
@@ -47,7 +47,56 @@ reconciled only when the registration still matches that binding. A changed
 release fails closed and cannot silently inherit or replace another release's
 registration.
 
-`pi_capabilities_get` projects the validated workspace and execution-profile maps plus the immutable configuration metadata captured while loading the file. It returns aliases plus the configured permission/provider/model/thinking intent, the configured extension specs and the selected skill aliases, sorted by alias, and `configuration: { fingerprint, reloadPolicy: "restart-required" }`. The fingerprint is SHA-256 over the exact loaded file bytes, including formatting; it is not a current-file freshness check. The projection makes no provider, authentication, filesystem, network, server-reachability, or catalog-state probe, so it cannot assert availability.
+`pi_capabilities_get` projects the validated workspace and execution-profile maps plus the immutable configuration metadata captured while loading the file. It returns aliases plus the configured permission/provider/model/thinking intent, the configured extension specs and the selected skill aliases, sorted by alias, `configuration: { fingerprint, reloadPolicy: "restart-required" }` and `events: { delivery: "spool" | "off" }`. The fingerprint is SHA-256 over the exact loaded file bytes, including formatting; it is not a current-file freshness check. The projection makes no provider, authentication, filesystem, network, server-reachability, or catalog-state probe, so it cannot assert availability.
+
+## Leased container writers
+
+[ADR 0012](adr/0012-leased-writer-pool.md) routes coding on `container`
+workspaces through the one host registration `pi-session-mcp`, without
+per-writer registrations, tool sets or writer selection by prefix. The host
+spawns a writer's stable wrapper per session and relays MCP stdio behind
+`PiSessionAdapter`. Host and read-only sessions stay embedded. Each client
+still owns a separate host process; there is no daemon or shared session store.
+
+Optional start `base` is a short branch name, applicable only to container
+coding; elsewhere it fails with `base_not_applicable`. Omission uses the
+workspace default base. Allocation tries ready accepted relay writers in index
+order on that branch, checks the inner profile selection against the host and
+leaves baseline admission to the inner guard. Start and get report `writer`
+and `base: { ref, commit }`; capabilities report configured `writers` and
+`defaultBase`, not free capacity. `writer_unavailable` gives content-free
+reason/counts; transport loss makes the session lost (`writer_session_lost`
+on later prompts), while get and close still work.
+
+The launcher is the session lease holder, not the host server. Its host-only
+`~/.local/state/pi-session-mcp/leases/<name>.lock` is opened without following
+links, checked for type/owner/mode, never deleted, and held throughout warm-up,
+credential projection, refresh, container use and cleanup. The directory is
+0700 and file 0600. Setup takes the same lease for every mutating operation,
+including collection, acceptance and reconciliation, with a 10-second wait
+before `writer_busy`. Mutating host children inherit the locked descriptor;
+nested acceptance launchers verify and adopt it. It never enters a container
+or Podman's monitor.
+
+After taking the lease, before credential or clone changes, the holder confirms
+absence of containers labeled `pi-session-mcp.writer=<name>` and any container
+mounting the clone, including unlabeled legacy containers. It removes remnants
+of a dead holder and fails closed (`writer_fenced`) if absence is uncertain.
+Session containers use the fixed name `pi-writer-<name>`; setup throwaway
+containers also carry the label. On stdin end, SIGTERM or SIGHUP, the launcher
+stops refresh scheduling, joins outstanding refresh, stops/removes the
+container and checks absence before exiting. Close tells the launcher to stop
+without waiting for all cleanup; its lease still fences the clone. A killed
+launcher leaves cleanup to the next holder's absence check.
+
+`--finish` returns writers to the workspace default base. A fix round uses a
+local branch at the collected ref, `--writer <name> --reset --base <branch>
+--apply`, then start with `base: "<branch>"` and collect the returned `writer`.
+No reconnect is needed after reset, finish or recreate. Inner replies are
+validated and bounded; the host owns IDs, turn state and terminal events.
+Relayed turns use bounded inner polling; only inner `updatedAt` changes advance
+activity, and inner truncation survives projection. Abort observes the actual
+inner outcome, so a completed turn remains completed in an abort race.
 
 ## Deterministic Pi selection
 
@@ -73,14 +122,53 @@ The registry owns public UUIDs, lifecycle state, the turn read model, background
 
 `pi_session_prompt` creates a provisional turn identity, invokes Pi preflight, and only after accepted preflight publishes `{session, turn}`; rejected preflight leaves no orphan turn. Completion returns to `idle`; failure is generic. Each active session retains at most 20 turns. A turn is `running`, `completed`, `failed`, or `aborted`; its public view contains IDs, timestamps, and terminal `completedAt`. While a turn runs, its `updatedAt` is the time of the last observed public SDK activity (assistant message and tool execution events, content-free) and is a liveness lower bound only; see [Tool contracts](tool-contracts.md). Completed text is normalized and capped at 64 KiB UTF-8 with Unicode-safe truncation. It can contain model-visible workspace data and remains potentially sensitive.
 
-Session metadata contains only whitelisted values: public session ID, workspace alias, execution-profile alias, derived permission `profile`, post-verified provider/model/effective thinking level, lifecycle state, and timestamps. Capability metadata uses a separate whitelist: server name/version, loaded configuration fingerprint/reload policy, workspace aliases, and configured profile fields, including the selected skill aliases. Neither view contains workspace paths, full model objects, SDK session IDs, auth sources, credential paths, headers, base URLs, prompts, transcripts, or raw provider errors.
+Session metadata contains only whitelisted values: public session ID, workspace alias, execution-profile alias, derived permission `profile`, post-verified provider/model/effective thinking level, lifecycle state, timestamps, and for container sessions the writer and base ref/commit. Capability metadata uses a separate whitelist: server name/version, loaded configuration fingerprint/reload policy, workspace aliases, and configured profile fields, including the selected skill aliases. Neither view contains workspace paths, full model objects, SDK session IDs, auth sources, credential paths, headers, base URLs, prompts, transcripts, or raw provider errors.
 
-Profile-specific authentication/catalog operations and session creation have fixed server-side deadlines of 5,000 ms and 10,000 ms. Prompt preflight, abort, close cleanup, registry shutdown, and process shutdown have fixed server-side deadlines of 5,000 ms, 5,000 ms, 5,000 ms, 12,000 ms, and 15,000 ms respectively. A preflight timeout returns `prompt_timeout` without publishing a turn. The unpublished operation remains quarantined until its prompt and abort cannot race with later work; late settlement can release that quarantine but never publish the turn. An abort timeout returns `abort_timeout` without falsely marking the turn aborted; a later normal outcome or successful SDK abort may still terminalize it exactly once. Close marks the session terminal, removes its public registry entry deterministically, and performs best-effort abort/dispose. Repeated close calls return a cached closed view while its tombstone is retained. Each SDK handle is disposed at most once. A late promise cannot revive a removed session or mutate a removed turn.
+Embedded profile-specific authentication/catalog operations and session creation have fixed server-side deadlines of 5,000 ms and 10,000 ms. Relayed container starts have a 60-second budget; their prompt preflight, abort and close cleanup use 15,000 ms, 15,000 ms and 10,000 ms respectively. Embedded prompt preflight, abort and close cleanup, plus registry shutdown and process shutdown, have fixed server-side deadlines of 5,000 ms, 5,000 ms, 5,000 ms, 12,000 ms, and 15,000 ms respectively. A preflight timeout returns `prompt_timeout` without publishing a turn. The unpublished operation remains quarantined until its prompt and abort cannot race with later work; late settlement can release that quarantine but never publish the turn. An abort timeout returns `abort_timeout` without falsely marking the turn aborted; a later normal outcome or successful SDK abort may still terminalize it exactly once. Close marks the session terminal, removes its public registry entry deterministically, and performs best-effort abort/dispose. Repeated close calls return a cached closed view while its tombstone is retained. Each SDK handle is disposed at most once. A late promise cannot revive a removed session or mutate a removed turn.
 
 The public SDK does not provide a hard-kill guarantee for a blocked provider/network operation, so a timeout must not be described as graceful provider cancellation. `SIGINT`, `SIGTERM`, and stdin EOF from the MCP client start the same process shutdown. The first trigger wins and sets the exit status (130, 143, or 0). Stdin EOF or the first `SIGINT` or `SIGTERM` during a running shutdown neither restarts it nor changes that status; a signal that arrives a second time keeps Node's default effect and ends the process immediately. Shutdown closes registry entries and the MCP transport best-effort, then explicitly exits the Pi Session MCP process no later than its 15,000 ms deadline. That terminal process policy may cut off still-running external work and does not prove the provider stopped cleanly. Closed tombstones are FIFO-retained up to 100 entries and contain no turn data. All sessions, turns, tombstones, and loaded configuration snapshots disappear on process exit; there is no persistence or reconnect/resume.
 
 Public errors are stable and sanitized. They omit caller values, complete prompts, paths, provider/SDK details, authentication data, credential locations, and SDK identifiers.
 
+## Turn events and controller wake
+
+Event delivery is opt-in (`"events": { "delivery": "spool" }` in the server configuration, default `off`) and decided in [ADR 0011](adr/0011-turn-events-and-controller-wake.md). Without it nothing below exists and no client sees a difference.
+
+```text
+registry terminal transition --> onTurnTerminal --> TurnEventSpool --> event file
+                                                                          |
+Claude Code asyncRewake <-- exit 2 + one line <-- pi-session-mcp-wake <---+
+        |
+        +--> controller reads pi_turn_get once
+```
+
+- **Observer.** `SessionRegistry` calls the optional `onTurnTerminal` listener from the one place that makes a published turn terminal (`notifyTerminal`), once per turn, with session ID, turn ID, state (`completed`, `failed` or `aborted`) and `via`. `via` is `close` when `close` marked a still running turn aborted and `registry` otherwise. A rejected, timed-out or restored preflight never had a public turn and emits nothing. A throwing listener is swallowed; it cannot change registry state or reach a caller.
+- **Spool.** `src/main.ts` opens a `TurnEventSpool` at startup only when delivery is `spool` and writes one `turn_terminal` event per notice. An unusable spool root stops the server with the startup code `event_spool_unavailable`. Without any spool location (no `PI_SESSION_MCP_EVENTS_DIR` and no absolute `XDG_RUNTIME_DIR`, as when Codex starts the server) delivery stays inactive instead: the server starts, `pi_capabilities_get` reports `events.delivery: "off"`, and one `event_delivery_inactive` warning goes to stderr (#113). Later write failures never reach the registry: they are counted, and one sanitized `event_spool_write_failed` diagnostic goes to stderr. An instance keeps only its newest 256 event files (it deletes older ones by name from an in-memory list and never lists the directory), so a long-lived server cannot outgrow the hook's bounded scan.
+- **Event.** One file per event, `<8-digit sequence>-<kind>.json`, at most 1,024 bytes, mode 0600, written to a temporary name and renamed into place. It holds `v`, `seq`, `at`, `instance` and, for `turn_terminal`, `session`, `turn`, `state` and `via`; `instance_ended` holds a `reason` (`eof`, `signal` or `shutdown`) instead. Never a prompt, an answer, a path or an error text. `src/turn-events.ts` owns the contract and its strict parser; the server and the hook program share it.
+- **Hook.** `pi-session-mcp-wake` (`dist/wake-main.js`) is a Claude Code `PostToolUse` command hook with `asyncRewake`. It arms on `pi_session_prompt` and on `pi_turn_get` results that show a running turn, waits for that turn's event, claims it exactly once and exits 2 with one line on stderr, which Claude Code turns into a new model request. After its wait budget it wakes with a different line so that the controller reads once and re-arms. Every other path exits 0 silently.
+- **Controller.** It reads `pi_turn_get` once. An event is a wake trigger and never state: the registry read model stays the only truth, and the controller never acts on a state taken from a wake line.
+
+### Layout and lifecycle
+
+```text
+$XDG_RUNTIME_DIR/pi-session-mcp/       runtime tmpfs, cleared at logout
+  events/                              0700, owned by the operator
+    inst-<16 hex>/                     one per host server process
+  claims/                              wake claims, never inside events/
+```
+
+A host server uses `events/` itself as its spool root unless `PI_SESSION_MCP_EVENTS_DIR` names an absolute directory. The root is created with mode 0700 if missing and must be a real directory of the current user without group or other access. Each server process creates its own instance directory.
+
+- **Start.** The instance directory is created when the server starts with delivery enabled.
+- **Stop.** After the registry shutdown has finished, so that the terminal events which `close` generates come first, the spool writes `instance_ended` and removes its instance directory immediately afterwards. A reader therefore normally never sees `instance_ended`: it is a best-effort marker for a reader that is already scanning the directory at that moment, and no waiter relies on it. A waiter ends with a wake, silently on a `via: "close"` event for its turn, when its namespace has no instance directory after a short grace period, when its client process goes away, or at its budget. This runs on stdin EOF, signals, a failed start and the shutdown deadline. A crash or `SIGKILL` leaves a stale instance directory of content-free files; nothing cleans it up automatically, and the hook reads only the 64 newest instance directories of a namespace.
+- **Claims.** The hook creates `claims/<namespace>-<instance>-<sequence>` exclusively; the winner wakes, so one event wakes at most once even with several waiting hooks. A hook that is killed before its wake was delivered releases its claim. Claims older than 24 hours are removed by later hook runs.
+- **Not state.** The server never reads the spool back, nothing of the host spool survives a logout (the runtime directory is a tmpfs on systemd hosts), and no event is replayed. This is the narrow, content-free exception to in-memory-only operation that ADR 0011 records.
+
+Relayed sessions emit events through the host registry and host spool, without
+per-session writer spool mounts or writer hook entries. The wake hook matches
+only `mcp__pi-session-mcp__*`; see [Isolation setup](isolation-setup.md#event-spool-mount).
+Codex has no external wake and keeps polling.
+
 ## Scope
 
-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. Skill selection is part of that snapshot, but skill file contents are not: the SDK keeps file paths, so operators must not change a skill file while sessions that use it are active (see [Pi skills](skills.md)). 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; the opt-in event spool is a transient, content-free notification channel, not state (see above). 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. Skill selection is part of that snapshot, but skill file contents are not: the SDK keeps file paths, so operators must not change a skill file while sessions that use it are active (see [Pi skills](skills.md)). 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

@@ -50,14 +50,18 @@ The production bridge derives Node from `process.execPath` and the entry point f
 
 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 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
-runner and guardian both exclude `Z` entries from their live-member scan. This
-does not promise full PID reaping or termination of descendants that independently
-escape the process group. A stat read other than the expected disappearance
-(`ENOENT`) makes the scan indeterminate and keeps the guardian-held fence. Tests
+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 live 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 single-threaded zombie has
+terminated and holds no descriptors, even when its PID awaits an external reaper.
+On Linux a zombie thread-group leader counts as alive while the kernel still
+counts other threads in its group (`num_threads` above 1), because those threads
+share its descriptors (#118). This does not promise full PID reaping or termination
+of descendants that independently escape the process group. On Linux an entry that
+disappears during the scan (`ENOENT` or `ESRCH`, or process group `-1` followed by
+a disappearance on one more read, #109) is gone; any other failed stat read, and a
+zombie group member whose thread count cannot be read, makes the scan
+indeterminate and keeps the guardian-held fence. Tests
 of descendant termination must assert zombie-or-absence without catching their
 own failed assertion; fence retention is checked separately with a live member
 and an indeterminate scan.

package/docs/client-setup.md

@@ -192,6 +192,88 @@ takes no lock and writes nothing.
 After `skill_override_outdated`, `--apply` moves only the recorded base, which
 acknowledges a change you reviewed. Details: [Pi skills](skills.md#customize-and-add-skills).
 
+### Wake hook
+
+For a Claude Code target and a configuration with `"events": { "delivery": "spool" }` (`"off"` or an absent field means no hook),
+`--apply` adds one `PostToolUse` entry with `asyncRewake` to the settings file
+of the target's scope, after the registration succeeded. Guided steps and limits:
+[Installation](installation.md#wake-the-controller-claude-code); design:
+[Architecture](architecture.md#turn-events-and-controller-wake).
+
+| Scope | Settings file |
+| --- | --- |
+| `claude-code:user` | `$CLAUDE_CONFIG_DIR/settings.json`, else `~/.claude/settings.json` |
+| `claude-code:project` | `<project>/.claude/settings.json` |
+| `claude-code:local` | `<project>/.claude/settings.local.json` |
+
+**Where the hook reads.** The hook that a `pi-session-mcp` tool call arms reads only
+the `inst-*` directories directly under `$XDG_RUNTIME_DIR/pi-session-mcp/events`.
+Relayed container sessions emit through that host spool too. The hook matches
+only `mcp__pi-session-mcp__*`; writer hook entries and per-session writer spool
+mounts are gone. It reads no other location, and keeps claims and waiter locks
+in `$XDG_RUNTIME_DIR/pi-session-mcp/claims`, outside the spool.
+
+`<project>` is the real path of the directory in which setup runs. Claude Code
+has no command for hooks, so setup follows the contract of the settings file,
+not a client version (ADR 0004): it edits the JSON, and `--verify` compares the
+file's entry and checks that `dist/wake-main.js` exists. It cannot tell whether
+the running client honors the entry; restart Claude Code or review `/hooks`.
+In a project, a link at `.claude` or at the settings file makes the location
+invalid; in the user directory a linked settings file is followed. Ownership
+is the same pending-before-write transaction as for skills, keyed by scope
+(and by project for `project` and `local`), and holds a fingerprint only.
+
+The finding has the alias `hook:pi-session-mcp-wake`. Codes per operation:
+
+- `--dry-run`: `hook_add_planned` and `hook_update_planned` (planned; the update
+  replaces an entry that setup wrote for an earlier package path),
+  `hook_remove_planned` (planned; delivery is off and setup owns an entry),
+  `hook_already_equivalent` (unchanged), `hook_divergent` (divergent).
+- `--apply`: `hook_added`, `hook_updated`, `hook_recovered` (ok; an interrupted
+  run was settled and needed no further change) and `hook_removed` (ok; delivery
+  is off and an owned entry went), `hook_absent` (ok; the owned entry was
+  already gone and only the record was cleared), `hook_already_equivalent`
+  (unchanged), `hook_divergent` (divergent).
+- `--verify`: `hook_verified` (ok); `hook_missing`, `hook_not_equivalent`,
+  `hook_not_owned`, `hook_ownership_pending`, `hook_program_missing` and
+  `hook_delivery_off` (failed; the entry exists but the configuration disables
+  delivery). `hook_not_owned` here means the entry exists but setup does not own it.
+- `--rollback` and `--remove`: `hook_removed`, `hook_absent` and `hook_divergent` (more than one candidate, or an entry that
+  is not exactly the one setup wrote; nothing is deleted).
+- Removal of a shared entry (`--apply` with delivery off, `--remove`,
+  `--rollback`, or removing a writer): `hook_kept_shared` (unchanged; another
+  owned registration in the same local settings still needs the entry, see
+  below).
+- Any operation: `hook_config_unreadable` (failed), `hook_path_unsafe` (failed; the Node or
+  package path contains a character that the unquoted command cannot carry),
+  `hook_budget_invalid` (failed; the wait budget is not a positive integer),
+  `settings_location_invalid`, `settings_unreadable`, `settings_unparseable`,
+  `settings_shape_invalid` (`hooks` or `hooks.PostToolUse` has another shape),
+  `settings_changed` (the file changed twice during the edit) and
+  `hook_install_failed` (failed).
+
+With delivery off and no entry that setup owns, setup does not read the
+settings file at all, so an unparseable or linked file there changes nothing
+and fails nothing.
+
+Findings without news are not reported at all: a Codex target (not
+applicable), delivery off while setup holds no entry (`hook_not_enabled`), and
+`--remove` or `--rollback` without a record (`hook_not_owned`, unchanged). A
+setup report with delivery off and no owned entry therefore has the same
+findings, order and exit code as before the hook existed.
+
+Container provisioning creates no writer client registrations or writer hooks.
+Coding for either client uses the one host `pi-session-mcp` registration and a
+coding profile, not a per-writer tool prefix. `--client codex` has no writer
+effect. Migration removes owned legacy registrations and hook ownership under
+the writer fence; divergent entries are retained and reported, never replaced.
+An owned shared legacy hook can stay while another registration needs it.
+Use the [container upgrade runbook](installation.md#container-writers).
+
+Setup never replaces or deletes an entry that it did not write or that was
+edited, and it keeps all other settings. The entry is not part of the MCP
+registration, so `claude mcp` does not show it.
+
 ## Local configuration
 
 Create an unversioned JSON configuration file such as `pi-session-mcp.json`:
@@ -220,7 +302,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`, plus the optional `mcpServers`, `extensions` and `skills` described in [Installation](installation.md) and [Pi skills](skills.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.
+Configuration is strict. A profile has exactly `default`, `permissionProfile`, `provider`, `model`, and `thinkingLevel`, plus the optional `mcpServers`, `extensions` and `skills` described in [Installation](installation.md) and [Pi skills](skills.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`. An optional top-level `events` field, exactly `{ "delivery": "spool" }` or `{ "delivery": "off" }`, controls turn-event delivery for the Claude Code wake (`spool` enables it; `off`, the default when the field is absent, writes nothing); any other shape fails startup with `invalid_event_delivery`. 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.
 
@@ -294,7 +376,7 @@ Claude Code enforces each tool's declared JSON Schema (`additionalProperties: fa
 1. Call `pi_capabilities_get` with `{}` and select explicit workspace and read-only execution-profile aliases from the returned config-derived lists.
 2. Call `pi_session_start` with those aliases. The server resolves the configured provider/model through its shared `ModelRuntime` (a profile with extensions gets a fresh runtime for each session), loads and validates the profile's selected skills, checks existing local Pi authentication and availability, creates with explicit model/thinking/tools, and verifies the effective SDK result.
 3. Call `pi_session_prompt` with the returned `sessionId` and a read-only prompt. It returns after accepted preflight with a `turnId` in `running` state.
-4. Poll `pi_turn_get` with that `sessionId` and `turnId` until `completed`, `failed`, or `aborted`, with a deadline no longer than three minutes. There is no `pi_turn_wait` tool.
+4. Poll `pi_turn_get` with that `sessionId` and `turnId` until `completed`, `failed`, or `aborted`, with a deadline no longer than three minutes. There is no `pi_turn_wait` tool. With event delivery active (`events.delivery` is `spool` in `pi_capabilities_get`) and the wake hook installed, a Claude Code controller waits for the wake instead and reads the turn once.
 5. Call `pi_session_close` when the session is no longer needed.
 
 Capability discovery sorts both arrays by alias and returns no workspace paths. It reports configured provider/model intent without checking authentication, provider availability, the filesystem, or the network. Session start remains the first runtime check.

package/docs/doctor-design.md

@@ -32,12 +32,58 @@ 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 |
+| `workspace_gitfile` | Warning. A workspace's `.git` is a regular file starting with `gitdir:` while at least one execution profile has the `coding` permission profile | validated workspace alias |
+| `workspace_mode_unset` | Warning. A workspace has mode `unset` while at least one execution profile has the `coding` permission profile | validated workspace alias |
+| `workspace_base_unset` | Warning. A workspace has mode `container` without a recorded default base in its execution-modes entry | validated workspace alias |
+| `workspace_host_writes_accepted` | Always `ok`, without remediation. The operator has explicitly accepted host writes for this workspace | validated workspace alias |
+| `container_runtime_unavailable` | A workspace has mode `container` and the local rootless Podman probe fails | validated workspace alias |
+| `container_profile_refused` | A selected container coding profile cannot be rendered: missing profile, extensions or MCP grants, non-false default, non-coding permission, invalid skills, non-builtin/unshipped/operator-overridden skills, or schema-invalid rendered configuration (error); one ok per workspace when all selected profiles pass; one workspace error saying selected profiles could not be checked if the original configuration cannot be read | workspace alias:profile alias on refusal; workspace alias on success or unreadable configuration |
+| `writer_lease_directory` | Error when `~/.local/state/pi-session-mcp/leases` cannot be inspected, or exists as a symbolic link, is not a real directory, is not owned by the current user, or has a mode other than exactly 0700; an absent directory is not reported. A wrong owner or mode is repaired in place: lease files keep their inodes, so the directory is never moved or deleted while a writer may hold a lease | `writer lease` |
+| `writer_not_ready` | State is missing or invalid, phase is not ready, acceptance fingerprint is stale, or the local image is absent (error) | validated writer name |
+| `writer_not_migrated` | Warning. The writer state still records the legacy launch, so the writer is not in the relay pool | validated writer name |
+| `writer_off_default_base` | Warning. One or more ready writers of a container workspace have a base other than the workspace default base; the remediation states only their count | validated workspace alias |
+| `writer_git_identity_missing` | Clone Git config lacks a readable user name and email (warning); set both in the operator checkout, then reset the writer | validated writer name |
+| `writer_dirty` | HEAD is not the base branch, its commit differs, another branch exists, or Git metadata cannot safely be inspected (warning) | validated writer name |
+| `writer_uncollected_bundle` | Bundles directory is unsafe/unreadable or contains entries other than base.bundle (warning; an absent directory alone does not warn) | validated writer name |
 | `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>` |
+| `extension_unpinned` | Warning. Pi's agent settings list a configured pinned extension without a version, as a string or object's `source`; pin it with `pi install npm:<name>@<version>`. Missing, unreadable, or invalid settings are ignored | `<profile>:<package>` |
 | `skill_missing` | The `SKILL.md` file that a profile's selected skill alias names does not exist; a `builtin:<name>` value that matches no override and no shipped skill resolves to the shipped location and is reported here | `<profile>:<skill-alias>` |
 | `skill_unreadable` | A selected skill path is not a regular file, is larger than 256 KiB, or cannot be read | `<profile>:<skill-alias>` |
 | `skill_duplicate` | Two selected skill aliases of one profile resolve to the same canonical file | `<profile>:<skill-alias>` |
 | `skill_override_outdated` | Warning. The current fingerprint of a shipped skill differs from the base recorded in the skill bases file next to the configuration file, or the bases file is corrupt | `skill:<name>`, or `skill:bases` for a corrupt file |
+| `event_spool_root` | Only when `events.delivery` is `spool`. Warning: no absolute `XDG_RUNTIME_DIR` is set in Doctor's environment; a server started that way runs with delivery inactive. Error: the `pi-session-mcp` entry in the runtime directory, or its `events` or `claims` entry, cannot be inspected, is not a directory (a link counts), belongs to another user, or has group or other permission bits. An absent entry is `ok`: the server creates it | `event spool` |
+
+`workspace_gitfile` is advice, not a boundary. A linked Git worktree shares `hooks/` and `config` with its main repository, so a coding worker could plant code that runs in the operator's later Git commands. A `.git` gitfile alone does not prove a linked worktree, however: submodules and `git init --separate-git-dir` use gitfiles too, and the content of the three is indistinguishable without following the pointer. Doctor therefore never follows, resolves, stats or reads the pointer target and never runs Git. It calls `lstat` on `<workspace>/.git` and, for a regular file of at most 4 KiB, reads at most that many bytes (without following a symbolic link) and checks for a `gitdir:` prefix followed by a non-blank value. Every such file warns, including submodule and separate-git-dir gitfiles, with a fixed path-free remediation that says "possible linked worktree or Git metadata stored outside the workspace" and recommends a separate full clone for coding workers. The check runs only when a coding profile exists and emits one entry per workspace alias: a warning, or `ok` when no gitfile pointer was found. A `.git` directory, an absent `.git`, an empty, oversized or malformed file, a symbolic link named `.git` (not followed, so nothing is known about its target), and any `lstat` or read error (for example `EACCES`) produce `ok`, never a failure and never a crash; an unreadable `.git` therefore means "not detected", not "verified clean". The warning cannot mask an error: the exit code stays 2 whenever any error exists.
+
+For choosing modes, setup findings and host-server enforcement, see
+[Execution modes](execution-modes.md). Invalid `execution-modes.json` content
+fails the `config_invalid` check; a valid container entry does not prove that a
+writer is provisioned or accepted. Doctor checks every configured writer separately.
+
+Writer subjects use `<alias>-w<n>`. Readiness fingerprints share the launcher's
+helper and bind current wrapper bytes, package version, image ID, Podman version,
+network and cache settings. The injected `writerRuntime` probe defaults to bounded,
+offline `podman info`, `podman version`, and `podman image exists` commands; it never
+pulls an image. Dirty checks run no Git: they inspect HEAD, recursive local branch
+refs and packed-refs with 64 KiB per-file limits, rejecting symbolic links and
+unsafe directory entries. These checks do not inspect uncommitted worktree edits.
+Bundle warnings detect outstanding entries without reading their contents.
+Each successful check emits an `ok` entry; remediation text contains no paths.
+Acceptance and the disposable-clone control run are explicit setup operations,
+never Doctor actions. Under Plan B, `--isolation-control --repo <alias> --apply`
+writes real canaries below $HOME and removes them; omitting apply only plans.
+Doctor never runs this control, refreshes credentials, inspects client
+registrations or starts containers. In contrast, setup's writer verify checks
+Doctor and a bounded relay-path MCP handshake/tools/list/capabilities;
+client-target verify checks host registration equality separately. Claude's host
+registration inspection starts no writer container. The direct writer
+verification launch disables credential refresh and starts no session.
+Doctor's metadata-only dirty warning is not the server's stronger coding guard:
+that guard also checks stash and uncommitted/untracked work on every admission.
+See [Execution modes](execution-modes.md#writer-storage-launch-and-readiness).
+
+Execution-mode checks follow `workspace_gitfile`. Unset modes warn only when a coding profile exists; explicit host modes always show the accepted write risk as an `ok` line. If any alias uses container mode, Doctor probes the local runtime once with `podman info --format {{.Host.Security.Rootless}}`, without a shell, with a 10-second timeout and a 4 KiB stdout cap. Only exit status 0 and trimmed stdout `true` pass; a missing binary, timeout, excessive output or any other error fails each container alias, even with only read-only profiles. No runtime diagnostics or paths enter reports. This local probe stays offline and never runs Git.
 
 Doctor reads extension manifests from Pi's user install location only; it never installs packages and never imports extension code.
 
@@ -45,6 +91,8 @@ The skill checks run after the extension checks. They look only at file availabi
 
 `skill_override_outdated` concerns the operator's skill overrides, not a profile. It is `ok` for a recorded base that still matches the shipped skill, and a warning (exit status 1, never blocking `setup`) when the shipped skill changed after the operator ran `pi-session-mcp-setup --customize-skill <name>`; its remediation names `pi-session-mcp-setup --apply --customize-skill <name>` to acknowledge a reviewed change. Only skills with a recorded base are compared, and a recorded name that is no longer shipped is skipped. A recorded base of 0.8.0 (a version 1 fingerprint) is compared through the version 2 value of the released 0.8.0 skill it names; a version 1 base that names no released skill cannot be confirmed and yields a warning that says so, with the same remediation. A corrupt bases file yields a warning with the subject `skill:bases`. Doctor reads the bases file and the shipped skill files only; nothing is executed and the subject is a validated skill name, never a path. The check sorts after `skill_duplicate`.
 
+`event_spool_root` is the last check and exists only for a configuration that enables turn-event delivery ([ADR 0011](adr/0011-turn-events-and-controller-wake.md)); with delivery off or unset it is absent from the report. It inspects `$XDG_RUNTIME_DIR/pi-session-mcp` and, when they exist, its `events` and `claims` entries with one `lstat` each, and never creates, repairs or reads anything below them. The rule is the one the server applies to the events root at startup (`TurnEventSpool.open`: a real directory of the current user without group or other access) and the hook applies to the claims directory, so Doctor is not green where startup would fail with `event_spool_unavailable` for these directories. When `PI_SESSION_MCP_EVENTS_DIR` is set in the server's environment the server uses that directory instead of `events`; Doctor does not read it. A missing runtime directory variable is only a warning, because Doctor may run in another environment than the server; the server itself keeps delivery inactive when it has neither that directory nor `PI_SESSION_MCP_EVENTS_DIR`, with an `event_delivery_inactive` warning. Relayed container sessions use the host spool; there are no per-session writer spool mounts (see [Isolation setup](isolation-setup.md#event-spool-mount)). The report holds the fixed subject `event spool` and a fixed remediation, never a path.
+
 The Doctor reuses `loadConfig`; it does not duplicate alias, profile, thinking
 level, or read-only-default rules. Workspace values are used only for local
 filesystem checks and are never copied into the result.

package/docs/evaluation/2026-10-17-live-screening.md

@@ -0,0 +1,121 @@
+# Live profile screening — 2026-10-17
+
+The consolidated [test coverage register](2026-10-17-test-coverage.md) distinguishes
+live execution, local extension/MCP fixtures, inventory-only entries and untested
+production integrations.
+
+The operator-authorized wave completed **eight starts, zero controller retries,
+four accepted task results and four rejected task receipts**. All eight harness
+records passed, all eight turns completed, and all eight routes matched the
+approved provider/model/effort. Total measured run interval: **172.993 seconds**.
+No pilot or ablation was started. No production routing was changed.
+
+The CLI returned exit code 1 because four tasks did not meet their acceptance
+gates. This does not indicate a transport failure: all route, session cleanup,
+observed process cleanup and diff-scope checks passed.
+
+## Authorization and provenance
+
+The operator explicitly authorized the proposed live screening with existing
+access, at most eight runs and a USD 5 advisory budget, acknowledging that this
+was not a hard cost limit. The immutable [approval](live-screening-2026-10-17/approval.json),
+[manifest](live-screening-2026-10-17/approved-manifest.json) and
+[budget](live-screening-2026-10-17/approved-budget.json) bind the exact matrix to:
+
+- Base commit: `406dae7e6b99aa5715960490e869bd3fc668cca2`.
+- Source digest: `sha256:686887d57899c2e55593bb7dd98b78be08ea0fc6c471a6dd4eab3298f890d160`.
+- Approved manifest digest: `sha256:b8eb63eb4013e0943124376cfe72071efab3e584154e1dff8c7cbee420e09f0e`.
+- Baseline A, no selected skills, extensions or external MCP grants.
+- Sequential execution, zero controller retries, 180 seconds per run and 1,440
+  seconds total plus bounded cleanup.
+- Existing OAuth/subscription routes for OpenAI Codex and xAI; existing native
+  DeepSeek API-key route classified as API billing. This classification is not
+  a provider billing measurement.
+
+The [metadata inventory](live-screening-2026-10-17/inventory.json) used no provider
+request. No separate connectivity/PONG call was added. Each of the eight session
+starts belongs to exactly one planned task slot. The evaluated source remained
+unchanged before, during and after the wave. Documentation and evidence are
+outside the evaluated source digest.
+
+Execution interval: 2026-10-17T08:13:31.962Z through 2026-10-17T08:16:24.955Z
+(UTC; Europe/Berlin was UTC+02:00). Package 0.8.3, Pi SDK 1.2.0,
+profile-evaluation client 1.0.0.
+
+## Results
+
+| Run | Exact route and effort | Task / view | Task gate | Seconds | Failed task checks |
+| --- | --- | --- | --- | ---: | --- |
+| screen-1 | openai-codex / gpt-6-luna / low | T1 / scout | FAIL | 7.881 | api-data-flow, stale-doc-contradiction |
+| screen-2 | openai-codex / gpt-6-luna / low | T2 / implementer | PASS | 13.553 | — |
+| screen-3 | openai-codex / gpt-6.1-sol / medium | T1 / scout | FAIL | 13.776 | api-data-flow |
+| screen-4 | openai-codex / gpt-6.1-sol / medium | T2 / implementer | PASS | 18.767 | — |
+| screen-5 | deepseek / deepseek-flash / high | T1 / scout | FAIL | 7.974 | api-data-flow |
+| screen-6 | deepseek / deepseek-flash / high | T2 / implementer | PASS | 9.667 | — |
+| screen-7 | xai / grok-4.7 / high | T5 / reviewer | PASS | 38.013 | — |
+| screen-8 | xai / grok-4.7 / high | T5 / reviewer | FAIL | 62.758 | clean-counterexample |
+
+T1 is a code-understanding receipt check. All three candidates failed its exact
+ordered path/symbol gate. Sol and DeepSeek passed the stale-document contradiction
+check; Luna did not. These results establish failure to meet this receipt
+contract, not a general inability to explain a codebase.
+
+All three T2 candidates made the same minimal change to `contract.mjs`:
+`Number.isFinite(parsed) && parsed >= 0`. Fail-before and independent regression
+checks passed. The controller separately read the actual patches and reran seven
+cases on each preserved snapshot, including negative fractional input, zero and
+a valid fraction; all 21 assertions passed. Patches and snapshots are linked from
+the individual [run records](live-screening-2026-10-17/runs/comparison.json), and
+these additional checks are recorded in the [audit](live-screening-2026-10-17/audit.json).
+Only the allowed file changed. The coding boundary remains **FAIL** because Pi's
+coding profile does not enforce an OS file-scope boundary. These are restricted
+synthetic task successes, not general production implementation approval.
+
+Grok detected both seeded defects in each T5 repetition: four detected of four
+possible, four confirmed findings of four reported, and no additional findings
+or findings on the clean comparison file. The first repetition passed every
+check. The second failed only `clean-counterexample`. The oracle requires
+exactly one clean-case entry with status `no finding`; the task prompt asked for
+`clean_cases [{path,status}]` and an assessment of `clean.ts`, but did not specify
+that exact status spelling. This limits the inference from that rejection. The
+raw model receipt is deliberately not archived, so the exact rejected content
+cannot be reconstructed. It is not evidence of a false positive or a missed seed.
+
+No route has the complete accepted screening evidence needed for a later pilot:
+Luna, Sol and DeepSeek each lack accepted T1 evidence; Grok lacks two accepted T5
+repetitions. The [comparison](live-screening-2026-10-17/runs/comparison.json) keeps
+routes and task views separate. No general model ranking or production routing
+recommendation follows from this small wave. Later pilot, UI, tester, document
+writing and controlled compaction evaluations remain outside this authorization.
+
+## Budget, cleanup and verification
+
+**Actual cost and token usage are unknown.** The production MCP contract exposes
+neither. Every record retains `cost_usd:null` and `usage:null`; no cost per
+accepted result is computable. The USD 5 amount was advisory, with no provider-side
+hard cap, and actual compliance with it cannot be demonstrated. SDK-internal
+request retries and subscription quota use are also unmetered through this path.
+There were no controller retries or extra model calls.
+
+The [audit](live-screening-2026-10-17/audit.json) independently checks eight claims,
+eight resolved sessions, eight terminal results, unique scopes, exact approved
+routes, result schemas, all artifact hashes, source stability, sequential
+intervals, per-run and total wall time, empty-session checks, observed process
+cleanup, diff scope and recomputed comparison. All passed. Four successful
+fixture directories were removed; four failed fixtures were retained for scoped
+diagnostics. No unexpected changed path was observed. The longest run was 62.758
+seconds, below its 180-second budget.
+
+A separate read-only reviewer recomputed these bindings and aggregates and found
+no additional execution defect. The reviewer confirmed the narrow interpretation
+of T1 and the second T5 receipt rejection. No reviewer model/provider calls or
+file changes were made. Process cleanup covers observed identities and groups;
+it does not establish containment of deliberately detached unsampled processes.
+
+The sanitized archive contains approval inputs, metadata inventory, eight claims,
+eight result records, scoped diagnostic identifiers, three accepted synthetic
+snapshots and patches, comparison and audit. It contains no credentials, private
+absolute host paths, raw provider errors, prompts or full model responses. Its
+[integrity index](live-screening-2026-10-17/integrity.json) hashes all archived
+machine evidence. The earlier [offline evidence](2026-10-17-profile-evaluation-evidence.md)
+is preserved as the historical pre-live record.

package/docs/evaluation/2026-10-17-node-runtime-followup.md

@@ -0,0 +1,33 @@
+# Node runtime follow-up — 2026-10-17
+
+The four absent Pi packages were rechecked at their exact user-scope Pi install
+paths: `pi-lens`, `context-mode`, `pi-cache-optimizer` and
+`@gotgenes/pi-permission-system` remain absent. The audited candidate pins are
+4.4.3, 1.0.169, 2.9.3 and 40.3.0 respectively. No package was installed.
+
+The evaluation process still resolves Node 22.23.2 from the system Node binary;
+the OS package is `nodejs 22.23.2-1nodesource1`. However, a separate user-local
+Node 24.20.0 binary already exists and its version command succeeded. Thus the
+earlier Cursor engine gate concerns the selected Node 22 process, not absence of
+every compatible Node runtime on the host.
+
+The `pi-session-mcp` executable uses an `env node` shebang. A scoped PATH selecting
+the existing Node 24 installation can therefore select the appropriate interpreter
+for evaluation/MCP processes without replacing the system package. The Pi CLI
+launcher also checks its own managed runtime path first; that optional runtime
+was absent in this inspection, so launcher/runtime selection must be verified for
+each actual entry point. Changing a shell does not change an already running
+server's interpreter.
+
+Node's [official download page](https://nodejs.org/en/download) reports 24.22.0
+as the current 24 LTS release at inspection time. A durable refresh can add the
+verified official Linux artifact alongside existing runtimes, then explicitly
+select that runtime for Pi/MCP entry points. This avoids changing unrelated
+services as a side effect. No download, install, system package update, PATH or
+launcher modification was made in this follow-up.
+
+Only binary version checks ran under Node 24. No SDK, Cursor import, extension
+tool, model request or Node 24 compatibility suite was executed. The prior
+[extension evidence](extension-audit-2026-10-17/README.md) remains a historical
+record of the actual Node 22 checks. A selected Node 24 runtime removes that
+declared engine prerequisite; it does not establish Cursor compatibility or safety.