pi-session-mcp 0.8.3 → 0.12.0

package/docs/installation.md

@@ -6,6 +6,10 @@ Code, and covers configuration changes, upgrades and removal. Related documents:
 - [Client setup reference](client-setup.md): manual registration, the expected
   tool flow and troubleshooting.
 - [Acceptance](acceptance.md): how a release is accepted.
+- [Execution modes](execution-modes.md): choose host, container or read-only per
+  repository; automated Linux container writers, readiness, collection and finish.
+- [Isolation setup](isolation-setup.md): rootless Podman prerequisites, what setup
+  automates and migration from hand-made writers.
 
 ## What gets installed
 
@@ -20,8 +24,10 @@ An installation consists of these locations:
 | --- | --- | --- |
 | Package | the npm global prefix, or a dedicated directory per release such as `~/.local/share/pi-session-mcp/releases/<tag>` | The built server, `setup` and Doctor. |
 | Configuration | a file outside the package, for example `~/.config/pi-session-mcp/pi-session-mcp.json` | Operator-owned, mode `0600`, never committed. |
+| Execution modes | `execution-modes.json` next to the configuration | Per-alias write policy; selected with `setup --repo`. See [Execution modes](execution-modes.md). |
 | Skill overrides (optional) | the `skills/` directory next to the configuration file, for example `~/.config/pi-session-mcp/skills/` | Your own or customized skills, plus `.pi-session-mcp-bases.json` and its lock file `.pi-session-mcp-bases.lock`. Created by you or by `setup --customize-skill`. See [Pi skills](#pi-skills). |
 | Controller skill | `~/.agents/skills/pi-session-orchestration` (Codex), `~/.claude/skills/pi-session-orchestration` or `<project>/.claude/skills/pi-session-orchestration` (Claude Code) | Written by `setup --apply`; see [Register a client](#4-register-a-client). |
+| Wake hook (optional) | `hooks.PostToolUse` in a Claude Code settings file: `~/.claude/settings.json` (user), `<project>/.claude/settings.json` (project) or `<project>/.claude/settings.local.json` (local); the program is `dist/wake-main.js` of the package | Written by `setup --apply` only when the configuration enables event delivery; see [Wake the controller](#wake-the-controller-claude-code). |
 | Setup ownership state | `~/.local/state/pi-session-mcp/ownership.json` | Written by `setup` only. Path-free and secret-free. |
 
 Never register a development checkout. A registered client launches
@@ -55,14 +61,19 @@ the same arguments.
 - 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.1` and Claude Code `2.1.296`. Manual registration, described in the
+  `0.162.1` and Claude Code `2.1.310`. 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
-  no credentials, no provider and no network access beyond `npm ci`.
+- For real prompts: local Pi authentication and a provider/model pair that Pi
+  knows. Doctor is offline. Container apply may pull the built-in pinned image
+  and runs the acceptance network probes; coding session launchers can
+  copy/refresh selected credentials. Host registration health checks do not
+  start writer containers. Direct writer verify
+  disables credential refresh and uses no session or provider request.
 
 Pi Session MCP embeds the Pi SDK version pinned in `package.json`. It reuses the
-local user's existing Pi authentication and never stores or prints it.
+local user's existing Pi authentication and never prints it. Automated writers
+keep selected provider credentials in their private boundary agent copy; see
+[Execution modes](execution-modes.md#writer-storage-launch-and-readiness).
 
 ## 1. Install
 
@@ -169,6 +180,11 @@ Rules:
   configuration file's directory; `~` is not expanded. The example already uses
   `builtin:` for the two worker skills, so you need not change its skill
   entries. See [Pi skills](#pi-skills).
+- An optional top-level `events` field, `{ "delivery": "spool" }` or
+  `{ "delivery": "off" }`, turns turn-event delivery for the Claude Code wake on
+  or states explicitly that it is off. Delivery is off by default and when the
+  field is absent; any other shape fails startup with `invalid_event_delivery`. See
+  [Wake the controller](#wake-the-controller-claude-code).
 - Never put keys, tokens, credential objects, headers, base URLs or
   authentication paths into this file.
 
@@ -182,6 +198,25 @@ directory is the client's project, so a file found there must never become the
 policy. Each registration stores the absolute configuration path, so registered
 clients do not depend on your shell environment.
 
+### Choose repository execution modes
+
+Before registering a client, choose a mode for every workspace alias with
+`pi-session-mcp-setup --repo <alias> --profiles <coding-alias>` (dry-run), then
+repeat with `--apply`. Container mode requires a non-empty list of configured
+coding-profile aliases (`--profiles a,b`); without it, setup reports
+`container_profiles_required` and writes nothing. See
+[Execution modes](execution-modes.md#choose-at-installation) for explicit
+host-write acknowledgment and all options. With usable rootless Podman, setup
+proposes container; otherwise it requires an explicit host or read-only choice.
+On Linux, container apply provisions and accepts separate full-clone writers
+for the host registration's leased pool; it adds no writer registrations. First explicitly authorize the host isolation
+control (`--isolation-control --repo <alias> --apply`): it writes real canaries
+below $HOME and removes them. Without a passing control writers remain not ready.
+See [Isolation setup](isolation-setup.md) for prerequisites, residual credential
+and network risks, and migration of hand-made writers.
+Missing entries retain host behavior as `unset` for compatibility and warn in
+Doctor when a coding profile exists.
+
 ## 3. Check the installation
 
 ```bash
@@ -310,6 +345,110 @@ directory, where the client discovers it without further steps:
 The codes and the rules are in [Pi skills](skills.md#install-the-orchestration-skill-into-codex-and-claude-code)
 and the [setup lifecycle design](client-setup-design.md#skill-installation).
 
+### Wake the controller (Claude Code)
+
+By default a controller learns that a turn ended by polling `pi_turn_get`. For
+Claude Code you can opt in to a wake instead, decided in
+[ADR 0011](adr/0011-turn-events-and-controller-wake.md): the server writes one
+content-free event file when a turn ends, and a Claude Code hook starts a new
+controller request that reads the turn once. This improves reaction time. It is
+not a token or cost saving, and none is measured on short tasks. Design:
+[Architecture](architecture.md#turn-events-and-controller-wake).
+
+1. Add the field to the server configuration and start a new client session
+   (the file is read at startup):
+
+   ```json
+   "events": { "delivery": "spool" }
+   ```
+
+   The server and the hook locate the spool through an absolute
+   `XDG_RUNTIME_DIR` (set by systemd user sessions; macOS does not set it by
+   default, and delivery there is untested). If the server's environment has
+   no runtime directory, delivery stays inactive: the server starts, reports
+   `events.delivery: "off"` and writes one `event_delivery_inactive` warning.
+   This is how a Codex registration that shares the configuration behaves,
+   because Codex passes no `XDG_RUNTIME_DIR` to MCP servers. A runtime
+   directory that exists but is unusable stops the server with the startup
+   code `event_spool_unavailable`. Doctor checks
+   the runtime, `events` and `claims` directories offline (`event_spool_root`):
+   each that exists must be a real directory of your user without group or
+   other access.
+2. Plan, then apply, for each Claude Code target. Run `setup` from the project
+   directory for `project` and `local` scope, as in [Register a client](#4-register-a-client):
+
+   ```bash
+   pi-session-mcp-setup --dry-run --target claude-code:user:pi-session-mcp
+   pi-session-mcp-setup --apply --target claude-code:user:pi-session-mcp
+   pi-session-mcp-setup --verify --target claude-code:user:pi-session-mcp
+   ```
+
+   After the registration, `--apply` adds one `PostToolUse` entry to the settings
+   file of the same scope. A report line has the alias `hook:pi-session-mcp-wake`:
+
+   ```text
+   claude-code/user/hook:pi-session-mcp-wake: ok (hook_added)
+   ```
+
+3. Restart Claude Code, or review the new hook in `/hooks`, before relying on
+   it. Setup writes the file and cannot observe what the running client loaded.
+   The skill `pi-session-orchestration` reads `events.delivery` from
+   `pi_capabilities_get` and stops polling only when it is `spool`.
+
+**What setup writes.** One entry, with `matcher` for
+`pi_session_prompt` and `pi_turn_get` of `pi-session-mcp` only
+(`mcp__pi-session-mcp__*`), and one command hook:
+`<node> <package>/dist/wake-main.js --budget-ms 1800000`, `asyncRewake: true`
+and `timeout` 1860 seconds (the 30-minute wait budget plus 60 seconds, so the
+client never ends the hook before its own budget). The entry is compared by
+fingerprint. Setup edits the JSON file with a compare-and-swap on its bytes
+and keeps its permissions; every other setting stays as it was. Verify checks
+the file and that the program exists; it does not test that Claude Code honors
+the hook.
+
+The hook reads only the host spool
+`$XDG_RUNTIME_DIR/pi-session-mcp/events/inst-*`, including relayed container
+turns. Its claims stay in `$XDG_RUNTIME_DIR/pi-session-mcp/claims`. There are no
+writer hook entries or per-session writer spool mounts.
+
+**Change and remove.** With delivery switched off, `--apply` removes an entry
+that setup owns (`hook_removed`); `--remove` and `--rollback` remove it with the
+registration. Setup never replaces or deletes an entry it did not write or that
+you edited (`hook_divergent`). During migration an owned shared legacy entry may stay
+(`hook_kept_shared`) while another owned registration still needs it. With
+delivery off and no entry of its own, setup does not read the settings file. The upgrade procedure below removes the entry with the
+old registration and adds it again with the new one, because it names the
+package path. The settings-file codes are in the
+[client setup reference](client-setup.md#wake-hook).
+
+**Limits.**
+
+- Linux only. The server spool needs `XDG_RUNTIME_DIR`, and the hook reads
+  through `/proc/self/fd`; on any other platform `pi-session-mcp-wake` exits
+  without a wake, so the controller polls.
+- Claude Code only. Codex has no external wake, so Codex controllers keep
+  polling; `setup` reports no hook finding for a Codex target.
+- Use interactive or stream-json sessions. A one-shot `claude -p` run holds its
+  next model request until the hook ends, so do not use it with delivery on.
+- The path of the Node executable and of the package must contain only
+  letters, digits and `_ @ % + = : , . / -`. Otherwise setup refuses with
+  `hook_path_unsafe` and writes nothing, because the command is embedded in the
+  settings file without quoting. Install the package
+  under a path that fits.
+- Claude Code's managed settings can disable hooks; the controller then polls.
+- Wake in the interactive TUI and in the VS Code extension was not tested in
+  the evaluation behind ADR 0011. Later observations, not a test matrix:
+  - the operator confirmed the TUI wake after the 0.11.0 release;
+  - on 2026-10-24 the VS Code extension woke on 0.11.2;
+  - on 2026-10-24 a running stream-json session of Claude Code 2.1.308 used a
+    project hook that setup wrote after the session started.
+
+  Whether a running extension or TUI session does the same is not checked, so
+  step 3 above stays the rule
+  ([Sprint 7 evidence](evaluation/s7-live-acceptance-2026-10-24/README.md)).
+- Container turns are relayed into the host spool, with no writer spool mount;
+  see [Isolation setup](isolation-setup.md#event-spool-mount).
+
 ### Register without setup
 
 `setup` runs on Linux and macOS. On every other platform, Windows included, it
@@ -395,11 +534,17 @@ define every field and error code.
 
 The server reads the configuration once when it starts. After editing the file,
 start a new client session so that the client launches a new server process.
-`pi_capabilities_get` returns the SHA-256 fingerprint of the loaded
-bytes and `reloadPolicy: "restart-required"`, which shows which version of the
-file a running server uses. The same applies to changes of the local Pi provider
+`pi_capabilities_get` returns the SHA-256 fingerprint of the loaded main
+configuration file's bytes and `reloadPolicy: "restart-required"`, which shows
+which version of that file a running server uses. The fingerprint does not
+cover `execution-modes.json`; each workspace's `mode` in `pi_capabilities_get`
+confirms the running execution-mode policy. The same applies to changes of the local Pi provider
 configuration or credentials.
 
+Execution-mode changes also require a new server process; setup reports
+`controllers_restart_required` after applying a mode change and never restarts
+controllers itself. See the [restart rule](execution-modes.md#restart-rule).
+
 The configuration path is part of the registration. Editing the file in place
 needs no new registration; moving it does.
 
@@ -420,6 +565,42 @@ pin the installed version in the profile:
 }
 ```
 
+For a review profile, grant individual extension tools rather than every tool
+in a package. This example assumes the named tool is available from the pinned
+extension; it is not evidence of a live provider check:
+
+```json
+"review-navigation": {
+  "default": false,
+  "permissionProfile": "read-only",
+  "provider": "your-configured-provider",
+  "model": "your-configured-model",
+  "thinkingLevel": "medium",
+  "extensions": ["npm:pi-lens@4.4.3"],
+  "grantedExtensionTools": ["symbol_search"]
+}
+```
+
+- **Grants.** `grantedExtensionTools` is allowed only on `read-only` profiles
+  with at least one extension. At most 32 unique names are allowed, each 1–64
+  characters of `[A-Za-z0-9_-]`, not starting with `-`, not MCP-reserved (see
+  **Fail-closed start** below), and not a built-in name (`read`, `bash`, `edit`,
+  `write`, `grep`, `find`, `ls`). A violation prevents startup with
+  `invalid_execution_profile_config`. A grant is your trust decision, not proof
+  that a tool only reads: third-party tools may write. Workspace modes
+  `container` and `read-only` do not restrict them. See
+  [ADR 0010](adr/0010-read-only-extension-tools.md).
+- **Availability.** Each grant must be registered when extensions load; the
+  registered set is re-checked after bind. Each grant must also be active and
+  declared to the model at admission, or `pi_session_start` fails with
+  `extension_tool_missing`, message `Granted Pi extension tool is not available`,
+  class `needs_operator`. Resolution errors (`extension_not_installed`,
+  `extension_version_mismatch`) take precedence; tool conflicts are checked
+  first. Lazy registration in `session_start` or later is unsupported. The SDK
+  activates only declarable tools: several registered `pi-lens` tools were never
+  active in the [evaluation](evaluation/pi-lens-registration-2026-10-19/).
+  Granting such a tool fails closed. Capabilities show configured grants only;
+  Doctor stays offline and does not import extensions to inspect tool names.
 - **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
@@ -430,9 +611,11 @@ pin the installed version in the profile:
   `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
+  and system-prompt changes. In `read-only` profiles the active tools are
+  `read`, `grep`, `find`, `ls`, the granted MCP tools and exactly the granted
+  extension tools. Without grants extension tools remain inactive. An
+  extension's `setActiveTools` cannot add others. 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
@@ -538,6 +721,56 @@ pi-session-mcp-setup --apply --target claude-code:user:pi-session-mcp
 pi-session-mcp-setup --verify --target claude-code:user:pi-session-mcp
 ```
 
+### Container writers
+
+Writer acceptance binds the package version, so every container writer is
+`writer_not_ready` after an upgrade, and Doctor blocks `--apply` for the client
+targets until they are accepted again. With container writers, run the
+repository step between the install and the client targets:
+
+1. Close all coding sessions and controllers first. This quiescence barrier
+   ensures no old-release launcher is still in flight. Install the new package
+   (`npm install -g` or the release checkout above).
+2. For each repository in mode `container`, repeat its existing provisioning command
+   with `--apply`, for example
+   `pi-session-mcp-setup --repo <alias> --mode container ... --apply`. It
+   migrates writers under the lease and container fence: removes owned writer
+   registrations and hooks, rewrites stable wrappers for the new release,
+   marks writers `launch: "relay"` and re-accepts them provider-free before
+   admitting them to the pool. It keeps the clone and work in it; acceptance
+   briefly places canaries in the clone. Migration records the shared default
+   base; differing writer bases fail with `workspace_base_ambiguous` unless
+   you supply an explicit `--base <branch>`. A divergent registration is never
+   deleted or replaced: it reports `registration_divergent` and keeps that
+   writer legacy, outside the pool. Resolve divergence before use; do not
+   launch through a retained legacy registration. `--client codex` has no writer effect any
+   more; both clients code through the one host `pi-session-mcp` registration.
+   Use the same
+   settings as before: a writer whose settings or coding profiles changed is
+   reported as `writer_settings_changed` and left as it is, and one whose
+   coding profile selects an overridden or unshipped `builtin:` skill as
+   `container_profile_unsupported`. Such a writer stays `writer_not_ready`
+   until you change the profile or remove the override, or collect it,
+   `--writer <name> --remove` it and provision it again
+   ([Isolation setup](isolation-setup.md)).
+3. `--apply` and `--verify` the client targets, then `--writer <name> --verify`
+   for each writer. Reconnect the host `pi-session-mcp` server after migration
+   and client setup. Later reset, finish and recreate need no reconnect.
+
+The repository step does not count another repository's writers that are not
+ready yet, so the repositories can be accepted one after the other. Releases
+before this fix did, so with two or more container repositories no repository
+step could pass after an upgrade to such a release
+([#148](https://github.com/plagor44-ux/pi-session-mcp/issues/148)). If that
+happens, install the previous version again: its writers are still accepted
+for it.
+
+Releases up to 0.11.4 accepted only writers whose phase was not ready, so a
+ready writer stayed `writer_not_ready` after the upgrade
+([#130](https://github.com/plagor44-ux/pi-session-mcp/issues/130)). With such a
+release on the new side, collect the writer's work, `--writer <name> --remove`
+it, and provision it again.
+
 ### Release checkout
 
 Install the new release next to the old one, move the registrations, and
@@ -588,7 +821,8 @@ same owned removal and reports `rolled_back`; use it to undo an apply. After
 every target reports `removed`, uninstall the package or delete the release
 directory, and delete the configuration file and
 `~/.local/state/pi-session-mcp/`. The same call removes the controller skill
-that `setup` installed (`skill_removed`). It keeps a copy that you modified
+that `setup` installed (`skill_removed`) and the wake hook entry it added
+(`hook_removed`). It keeps a copy that you modified
 (`skill_divergent`) and the shared Claude Code directory while the other
 Claude Code registration is still owned (`skill_kept_shared`). Your override
 directory `skills/` next to the configuration file is yours: delete it with the

package/docs/isolation-setup.md

@@ -0,0 +1,258 @@
+# Isolation setup for coding profiles (rootless Podman)
+
+This is the operator reference for what **setup now automates** under
+[ADR 0008](adr/0008-coding-profile-isolation.md) and
+[ADR 0009](adr/0009-execution-modes.md), Plan B, as amended by
+[ADR 0012](adr/0012-leased-writer-pool.md). Start with
+[Execution modes](execution-modes.md) for exact flags, lifecycle commands,
+readiness, finding codes and migration. Automation is implemented, not a claim
+of new live acceptance or a release.
+
+The historical Linux manual acceptance for hand-made writers is
+preserved in [the 2026-10-18 evidence](evaluation/isolation-acceptance-2026-10-18/README.md).
+It does not automatically accept another image, wrapper, Podman version or writer.
+macOS containment remains unaccepted and keeps the
+[Sprint 4 interim rules](sprints/2026-10-15-s4-decision.md#interim-operating-rules).
+
+## Commit identity and base tags
+
+Provisioning, recreation and reset copy the operator checkout's effective
+`user.name` and `user.email` into the clone's local Git config. Both must be
+1–256 characters without control characters and must not start with `-`; if
+either is absent or invalid, both clone values are unset. Missing identity does
+not block setup, but commits need it: set both values in the operator checkout,
+then reset the writer.
+Doctor reports `writer_git_identity_missing` without exposing either value.
+Identity is not stored in writer state or boundary acceptance.
+
+Tags default to `none`. Add `--tags reachable` to a container mode request to
+include tags merged into the selected base commit. Reset always deletes all
+clone tags, then imports the selected base tags when enabled. Worker-created
+tags are not collected work and do not affect the collected digest. The setting
+participates in settings drift, not the acceptance fingerprint.
+
+## Prerequisites
+
+- Linux with usable **rootless** Podman, Node.js 22.19.0 or newer and Git.
+  macOS is not supported: the setup reports `platform_unsupported` even with a
+  Podman machine (evaluation in
+  [#144](https://github.com/plagor44-ux/pi-session-mcp/issues/144)).
+  Follow your distribution's packaging and the
+  [Podman rootless tutorial](https://github.com/containers/podman/blob/main/docs/tutorials/rootless_tutorial.md).
+  User namespaces and subordinate UID/GID ranges must be configured. Do not
+  run the writer as root or with `--privileged`.
+- A release installation with production dependencies, not a development checkout;
+  configured workspace aliases, coding profiles and `PI_SESSION_MCP_CONFIG`.
+  See [Installation](installation.md).
+- Profiles supported in the boundary: non-default coding, no Cursor provider,
+  no extensions or external MCP grants, only shipped builtin skills without an
+  operator override (overrides do not reach the writer). Each container
+  gets the synthetic default `boundary-read-only`; name coding profiles explicitly.
+- Review setup's dry-run before applying. Image `node` resolves a built-in digest
+  pin and can be pulled on apply if absent; an operator-supplied image must be
+  present locally and named by its full 64-character lowercase hex image ID.
+  A custom image needs Node, Git, bash, ssh and coreutils for the acceptance harness.
+
+## What setup automates
+
+| Area | Automation and limits |
+| --- | --- |
+| Workspace | Separate full clone per writer, created via a base bundle; no hardlinks or shared linked-worktree metadata |
+| Wrapper | Generated stdio-only launcher bound to the release and writer name; no daemon between client connections |
+| Boundary | Rootless keep-id, read-only root, capability drop, no-new-privileges, tmpfs home and /tmp; clone read-write with hooks/config overmounted read-only |
+| Mounts | Only clone, release read-only, contained config read-only, isolated writable agent directory, optional Go or uv/npm cache; no per-session writer spool mount ([below](#event-spool-mount)) |
+| Configuration | One workspace, selected coding profiles and a synthetic read-only default; internal acknowledged host mode permits writes only in the contained clone |
+| Credentials | Selected provider entries only; OAuth refresh token emptied, API keys retained; no host SSH/Git/client credentials intentionally mounted |
+| Acceptance | Explicit uncontained host control, then provider-free contained harness per writer; fingerprint gates readiness |
+| Registration | One host `pi-session-mcp` registration; no per-writer tool sets or registrations; `--client codex` has no writer effect |
+| Results | Bundle export into namespaced refs in the operator's checkout; never host Git inside the writer clone |
+| Reuse | Collect then reset persistent writers or recreate ephemeral writers; refuse loss of uncollected work unless explicitly discarded |
+
+The environment passed into the container is an explicit allowlist; no host
+environment passthrough. The package and configuration are read-only mounts,
+but the isolated agent directory is writable because Pi auth storage requires
+writes even without refreshing. It is not the host's agent directory.
+
+## Provision and accept
+
+```sh
+pi-session-mcp-setup --repo my-project --mode container --profiles code
+pi-session-mcp-setup --isolation-control --repo my-project
+# Explicit permission: the uncontained control writes real canaries below $HOME and removes them.
+pi-session-mcp-setup --isolation-control --repo my-project --apply
+pi-session-mcp-setup --repo my-project --mode container --profiles code --apply
+pi-session-mcp-setup --writer my-project-w1 --verify
+```
+
+The host control uses a disposable clone and must detect the expected escapes.
+Without apply it plans only. Writers remain not ready until the control passes
+and their contained harness passes. Failed control invalidates the host control
+record. Contained acceptance records network classification as limited or not
+limited; both can pass. Readiness fingerprints bind wrapper, package version,
+image ID, Podman version, network and cache.
+
+Before the acceptance, `--repo <alias> ... --apply` checks each kept writer
+against the settings and configuration it would be provisioned from now: the
+image ID (resolved locally, never pulled), lifecycle, network, cache, profile
+list and providers in its state, and the whole rendered writer configuration
+with each selected profile's model, thinking level and skills and the event
+delivery. A difference reports `writer_settings_changed` and leaves the writer
+as it is
+([#134](https://github.com/plagor44-ux/pi-session-mcp/issues/134)). The same
+holds for the other findings of this check: `podman_unavailable` when Podman
+cannot be asked, `image_unavailable` when Podman answers but cannot resolve the
+image, and `container_profile_unsupported` when a selected coding profile is
+no longer supported in the boundary, for example because it now selects an
+overridden or unshipped `builtin:` skill. The dry run runs the same check, so
+it also asks Podman. To adopt new settings, collect the writer's work,
+`--writer <name> --remove` it and run the provisioning command again; for
+`container_profile_unsupported` first change the profile or remove the
+override. The key order of the profile objects does not count as a change, and
+an explicit `events: { "delivery": "off" }` counts the same as no `events`
+field.
+
+A changed binding must be accepted
+again: `--repo <alias> ... --apply` accepts every kept writer whose acceptance is
+not current (the same predicate as Doctor's `writer_not_ready`: not ready, a
+stale fingerprint, or a missing image), not only writers whose phase is not
+ready. When Podman cannot be asked or fails at that point, setup leaves a ready
+writer as it is and reports `podman_unavailable`,
+rather than downgrading it. A missing image is detected, but acceptance cannot
+pass without it: `--writer <name> --recreate --apply` provisions the writer
+again. Acceptance briefly places canaries and a `.git/commondir` file in the
+writer's clone and removes them, so run it while no session uses the writer.
+Doctor is offline and cannot substitute for acceptance.
+
+The harness launches the writer with `PI_WRITER_NO_CREDENTIAL_REFRESH=1`, as
+direct verify does: acceptance makes no provider request, and a host login
+warm-up for an expiring token would change the host's Pi agent directory inside
+the harness's digest window and fail `digests.preexisting_changed`.
+
+The harness checks launch binding, file writes outside the clone, host credential
+visibility, detached-process persistence, child environment names and network.
+Canaries have per-run names; it never intentionally replaces pre-existing files,
+removes its canaries and verifies cleanup. It does not prove the runtime is
+escape-free or that credentials cannot be exfiltrated. The historical manual
+live/provider checks are separate evidence, not something setup newly performs.
+For harness details see `scripts/isolation-acceptance.mjs` and the historical
+evidence linked above; do not claim a live provider test from provider-free acceptance.
+
+**Health-check warning:** `claude mcp get` starts the registered host server
+briefly, not a writer container. Writer verify and acceptance explicitly launch
+the wrapper with `PI_WRITER_NO_CREDENTIAL_REFRESH=1`; they start no session,
+use no provider and touch no credentials in that direct launch.
+
+## Event spool mount
+
+Relayed sessions report terminal turn events through the host registry into the
+host spool (`$XDG_RUNTIME_DIR/pi-session-mcp/events/`). Per-session writer spool
+mounts and writer wake-hook entries are gone under
+[ADR 0012](adr/0012-leased-writer-pool.md). The Claude Code wake hook matches
+only `mcp__pi-session-mcp__*`; a wake is a trigger to read `pi_turn_get`, never
+state. No container can write the host spool or claims through a spool mount.
+See [Installation](installation.md#wake-the-controller-claude-code).
+
+## Lease and container fence
+
+Coding on container workspaces goes through the one host registration
+`pi-session-mcp`. Per session the host leases a ready writer on the requested
+or default base and spawns its stable `wrapper.sh`. The launcher, not the host
+server, holds the host-only lease
+`~/.local/state/pi-session-mcp/leases/<name>.lock` for warm-up, credential
+projection, the container lifetime, refresh and cleanup. The directory is 0700
+and the file 0600; it is opened without following links, checked for type,
+owner and mode, and never deleted. Do not remove lease files to clear busy state.
+
+Every mutating operation, including collect, reset, finish, recreate, remove,
+acceptance and provisioning reconciliation, takes the same fence. Setup waits
+up to 10 seconds, then returns `writer_busy`. Mutating host children inherit
+the locked descriptor; nested acceptance launchers validate and adopt it.
+Neither the container nor Podman's monitor receives that descriptor.
+
+After acquiring the lease and before writing credentials or changing a clone,
+the holder confirms container absence by label `pi-session-mcp.writer=<name>`
+and by clone mount, including unlabeled old containers. It removes remnants
+of dead holders, waits boundedly and fails with `writer_fenced` if absence
+cannot be confirmed. Session containers have the fixed name
+`pi-writer-<name>`; setup's throwaway containers also carry the label.
+
+On stdin end, SIGTERM or SIGHUP the launcher stops scheduling refreshes, joins
+an outstanding refresh, stops/removes its container and checks absence before
+exiting and releasing the lease. Close need not wait for that full cleanup;
+the launcher continues to fence the writer. After a killed holder the next
+holder must remove any leftover container before touching the writer. This
+combination prevents a second client or setup run from using the clone early.
+
+To inspect a running writer container with `podman exec`, use the same
+`XDG_RUNTIME_DIR` as the client that started it. Rootless Podman keeps its
+runtime state there, and with another value `exec` reports that the container
+does not exist.
+
+## Credentials and residual risks
+
+The launcher checks on launch and every **60 seconds**. Only when a selected
+OAuth token expires within **10 minutes** or is expired does it refresh the host
+credential (invalid/missing expiry also triggers it). The refresh asks the Pi
+SDK for that much remaining validity through Pi's own locked host store,
+without a model request, and is bounded at 20 seconds; the launcher then
+copies the selected credentials even if the refresh failed. Boundary refresh
+tokens are empty; API-key entries are copied unchanged, not refreshed.
+
+The boundary still holds provider credentials: an **access token**, or the
+**API key** for API-key providers. The worker can read and use them. Network
+**`pasta` is not limited**, and no provider-only proxy/firewall is configured.
+`none` removes network entirely and normally prevents remote provider access.
+Credential exfiltration and runtime escapes remain residual risks.
+
+## Review, finish and migration
+
+Never run host Git in a writer clone, even for diff/log or direct fetch: mutable
+Git metadata can redirect reads to worker-controlled configuration. Setup checks
+clone layout and runs clone-side Git only in throwaway no-network containers.
+Collect with `--writer <name> --collect --apply`, then review
+`refs/remotes/writer-<name>/<branch>` in your own checkout, with dirty work at
+`<branch>-wip`. Imported refs are untrusted until reviewed.
+
+After taking over the result and closing its coding session, run
+`pi-session-mcp-setup --writer <name> --finish --apply` before another task.
+It collects then resets (persistent) or recreates (ephemeral). If any branch name
+was refused, collection is incomplete and finish stops. Rename inside the writer
+or have the operator explicitly resolve loss with `--reset --discard --apply`.
+Finish returns persistent and ephemeral writers to the workspace default base.
+No reconnect is needed after finish, reset or recreate: each session starts a
+fresh launcher. Setup operations on a held writer fail with `writer_busy` after
+a 10-second lease wait, including collection and operations with `--discard`.
+Mode policy changes still require controller/server restart.
+
+For a fix round, create a local branch at the collected ref in the operator's
+checkout, run `--writer <name> --reset --base <branch> --apply`, then call
+`pi_session_start` on `pi-session-mcp` with a coding profile and
+`base: "<branch>"`. Read `writer` from the result for collection. Default starts
+cannot take a writer moved to another branch.
+
+For hand-made writers:
+
+1. Preserve and review any work through their old bundle route.
+2. In each original project remove the manual registration with
+   `claude mcp remove pi-coding-<name> -s local`; remove any manual Codex entry too.
+3. Remove the manual wrapper and state directory only after collecting needed work.
+4. Run the explicit isolation control, then
+   `pi-session-mcp-setup --repo <alias> --mode container --profiles <coding-aliases> --apply`.
+5. Reconnect/restart the host `pi-session-mcp` server, verify its client targets
+   and run `--writer <name> --verify` for the new alias-derived writers.
+
+The Go-toolchain writer uses an operator-supplied local **image ID** with
+`--image <image-id> --cache go`, recording `cache: "go"` in container settings.
+Mode requests rebuild options from supplied values/defaults: repeat the image
+and cache flags each time. The Go mount is `/pi/go`, with GOPATH, GOCACHE and
+`GOTOOLCHAIN=local`; setup does not build the operator's toolchain image.
+
+A Python writer using uv and npm uses `--image <image-id> --cache uv`, which
+records `cache: "uv"` and mounts a private per-writer directory at `/pi/uv`
+with `UV_CACHE_DIR=/pi/uv/cache` and `npm_config_cache=/pi/uv/npm`. No other uv
+or npm variables are set. The cache belongs to one writer: it is never shared
+between writers and never a host cache mount, and setup does not install uv
+or npm for you.
+
+See [Execution modes](execution-modes.md#migration-from-manual-writers) for
+migration limitations and [Doctor](doctor-design.md) for offline writer checks.

package/docs/macos-setup-design.md

@@ -36,7 +36,7 @@ the documentation calls it CI-tested.
 | 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` |
+| Process-group proof | `/proc/<pid>/stat` scan; a `Z` entry does not count as live unless its `num_threads` is above 1 (#118) | `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` |
 
@@ -63,7 +63,7 @@ export function currentSetupPlatform(platform?: NodeJS.Platform): SetupPlatform
 
 export type ProcessGroupState = "alive" | "gone" | "unknown";
 export interface ProcessTable {
-  /** "alive" if any non-zombie process has this process group ID. */
+  /** "alive" for a non-zombie group member, or on Linux a zombie leader with other threads. */
   groupState(group: number): Promise<ProcessGroupState>;
   /** True only if a scan is trustworthy and contains the calling process. */
   readable(): Promise<boolean>;