pi-session-mcp 0.11.9 → 0.12.0

package/docs/execution-modes.md

@@ -11,9 +11,11 @@ does not itself prove a live rollout or acceptance on your machine.
 - **`host`:** coding writes in the operator's checkout; requires stored
   `acceptHostWrites: true`. Tools, providers and trusted extensions run with
   the host process's rights, not inside an OS boundary.
-- **`container`:** the host refuses coding. Setup provisions separate full clones
-  and wrapped stdio registrations on Linux with usable rootless Podman. A mode
-  entry alone is not containment: each writer needs successful acceptance.
+- **`container`:** coding goes through the one host `pi-session-mcp`
+  registration, which leases a separate full-clone writer per session on Linux
+  with usable rootless Podman ([ADR 0012](adr/0012-leased-writer-pool.md)).
+  There are no per-writer registrations or tool sets. A mode entry alone is
+  not containment: each writer needs successful acceptance.
 - **`read-only`:** the host refuses coding; read-only profiles remain available.
   This is tool policy, not an OS sandbox for provider runtimes or child processes.
 - **`unset`:** a missing entry retains host coding for backward compatibility.
@@ -47,7 +49,7 @@ dependencies, not a development checkout. Never pass a workspace path.
 pi-session-mcp-setup --repo my-project --mode container --profiles code
 # Explicit host control: creates real canary files below $HOME and removes them.
 pi-session-mcp-setup --isolation-control --repo my-project --apply
-# Provisions, accepts and registers the writers.
+# Provisions and accepts the writer pool; no writer registrations.
 pi-session-mcp-setup --repo my-project --mode container --profiles code --apply
 ```
 
@@ -70,7 +72,8 @@ pi-session-mcp-setup --repo my-project --mode container --profiles code,code-loc
 Repeat the reviewed request with `--apply` to mutate. Mode requests cannot be
 combined with `--target` registration or `--customize-skill`.
 A `--repo` dry run for a container alias inspects existing writers using
-read-only throwaway containers: no network access and nothing written.
+read-only throwaway containers: no network access and nothing written to the
+clone.
 
 | Flag | Accepted values and defaults |
 | --- | --- |
@@ -82,9 +85,10 @@ read-only throwaway containers: no network access and nothing written.
 | `--profiles a,b` | Required non-empty coding-profile aliases; no Cursor provider |
 | `--image <value>` | `node` (default, built-in digest pin) or an existing local 64-character lowercase hex image ID; no arbitrary tags |
 | `--network <value>` | `pasta` (default, not limited) or `none` |
-| `--cache <value>` | `none` (default) or `go` for the writer's Go module/build cache |
+| `--tags <value>` | `none` (default), or `reachable` for the tags reachable from the selected base commit |
+| `--cache <value>` | `none` (default), `go` for the writer's Go module/build cache, or `uv` for its private uv and npm cache |
 | `--base <ref>` | Named local or remote branch for provisioning; also supported by writer reset; not HEAD or a raw commit hash |
-| `--client codex` | Also register writers with Codex (user scope); Claude Code local registration is the default |
+| `--client codex` | No writer effect; coding uses the host registration for either client |
 | `--discard` | Explicitly allow loss of uncollected surplus writers on mode/count changes |
 | `--dry-run` / `--apply` | Dry-run is the default; apply mutates |
 | `--json` | Sanitized JSON projection of the same report |
@@ -106,16 +110,25 @@ other workspace entries. The main configuration's `workspaces` stays an
 alias-to-path map. Older servers ignore modes; upgrade all relevant registrations.
 Invalid modes fail startup rather than silently falling back.
 
-Writers are `<alias>-w1` through `<alias>-w16`, with registrations
-`pi-coding-<alias>-w<n>`. Their private state lives under
+Writers are `<alias>-w1` through `<alias>-w16`, leased by the host server,
+not selected by tool prefix. Their private state lives under
 `$HOME/.local/state/pi-session-mcp/writers/<name>/`: `clone`, `agent`, `config`,
 `bundles`, optional `go`, `wrapper.sh` and `state.json`. This lifecycle metadata
 is distinct from in-memory MCP sessions; it does not implement session resume.
 Each clone is made via a bundle, with no hardlinks to the operator's repository.
-The base defaults to origin's symbolic HEAD, falling back to local main.
-
-The generated wrapper launches one disposable `podman run -i --rm` per client
-connection: keep-id user namespace, read-only root, dropped capabilities,
+The workspace records a short default `base` in its container entry, selected
+by `--base` or origin's symbolic HEAD, falling back to local main. Repeating a
+mode request without `--base` preserves that recorded value. Migration infers
+a shared writer base or fails with `workspace_base_ambiguous` unless given one.
+Capabilities report configured `writers` and `defaultBase`, not free capacity.
+
+Start with an explicit coding profile on `pi-session-mcp`. Optional `base` is
+only for container coding and selects a branch, not a writer; elsewhere it
+fails with `base_not_applicable`. Start and get report `writer` and
+`base: { ref, commit }`. Omit `base` for ordinary default-pool work.
+
+The generated wrapper launches one disposable `podman run -i --rm` per coding
+session: keep-id user namespace, read-only root, dropped capabilities,
 no-new-privileges, tmpfs home and /tmp. The clone and isolated agent copy are
 writable; clone hooks/config, boundary config and release installation are
 read-only mounts. Host Git never runs in the clone. Throwaway lifecycle
@@ -125,7 +138,7 @@ Each contained config has only its workspace and selected coding profiles,
 plus the synthetic default **`boundary-read-only`**. Coding sessions must name
 their coding profile explicitly. The clone's internal mode is acknowledged host
 because writes there are intended *inside* the boundary; the operator's host
-alias stays container and never dispatches coding automatically.
+alias stays container and routes coding through the relay, never host tools.
 
 State phases are provisioning, not_ready and ready. Acceptance binds wrapper
 bytes, package version, image ID, Podman version, network and cache settings.
@@ -137,9 +150,9 @@ silently replaced. Review
 and collect work before removing/reprovisioning them. Restart/reconnect affected
 controllers after successful changes; setup never restarts them.
 
-**Inspection has side effects:** `claude mcp get` health-checks the registration,
-briefly starting its container. Setup's registration inspect and verify do this
-too. Do not mistake inspection for a purely offline read. Doctor alone is offline:
+**Inspection has side effects:** `claude mcp get` health-checks the host
+registration, starting the host server but no writer container. Writer verify
+explicitly spawns the fenced relay launch path. Doctor alone is offline:
 it starts no writer, session or provider request and reads no credentials.
 
 The launcher copies only selected providers from the host Pi auth store at launch
@@ -172,7 +185,7 @@ new work invalidates that authorization. Stashes are not exported as branches:
 resolve any needed stash inside the boundary before collection.
 
 `--finish` collects, then resets a persistent writer or recreates an ephemeral
-writer. A collect refusing any branch name is incomplete (`writer_collect_incomplete`,
+writer, on the workspace default base. A collect refusing any branch name is incomplete (`writer_collect_incomplete`,
 `ref_name_refused`), even if other refs were imported. Finish stops without reset
 or recreation. Resolve by renaming inside the writer and collecting again, or
 by an operator's explicit `--reset --discard --apply` after deciding to lose the
@@ -182,28 +195,33 @@ unexported work. Do not blindly retry or bypass a refusal by changing profiles.
 | --- | --- |
 | `--collect --apply` | Bundle export; retain clone |
 | `--reset --apply [--base <ref>]` | Reset to current source base branch, delete extra branches/stash and clean untracked files; falls back to recreation if post-reset verification fails |
-| `--recreate --apply` | Rebuild clone and agent copy from the source base, retaining image/settings |
-| `--finish --apply` | Collect, then reset persistent / recreate ephemeral |
+| `--recreate --apply` | Rebuild clone and agent copy from the workspace default base, retaining image/settings |
+| `--finish --apply` | Collect, then reset persistent / recreate ephemeral on the workspace default base |
 | `--remove` | Explicit mutation: unregister owned registrations before removing writer state |
-| `--verify` | Doctor, registration equality and bounded direct MCP handshake/tools/list/capabilities; no session or provider request |
+| `--verify` | Doctor and bounded relay-path MCP handshake/tools/list/capabilities; verify the host registration with client-target verify too; no session or provider request |
 
 Other than explicit `--remove` and `--verify`, omitting apply only plans.
 Reset/recreate/remove refuse changed uncollected work unless given `--discard`.
-`--reset`, `--recreate` or `--remove` with `--discard` cannot see open sessions
-in the writer; close those sessions first.
-Only reset accepts `--base`; finish does not accept discard.
-
-**Verify and registration health checks:** setup's registration inspect in apply,
-verify and remove uses `claude mcp get`, which health-checks a registered server
-through its normal writer launcher. That start may re-copy the boundary
-credentials. Only if a selected OAuth token expires within **10 minutes** (or is
-already expired; invalid/missing expiry is treated as needing refresh) may it
-refresh the host credential through **Pi's own locked store**. The client CLI cannot
-be given a different environment for that health check. Verify's own direct MCP
-handshake uses `PI_WRITER_NO_CREDENTIAL_REFRESH=1`, touching no credential in
-that launch and making no session or provider request. **Setup itself never
-writes the host credential file**; host login updates, when needed, are performed
-by Pi through its locked store.
+Every mutating writer operation holds the host-only lease and container fence,
+including collect, acceptance and reconciliation. A held session (even idle)
+or launcher cleanup makes setup fail with `writer_busy` after a 10-second wait,
+also with `--discard`; close sessions first. Only reset accepts `--base`;
+finish does not accept discard. No reconnect is needed after reset, finish or
+recreate.
+
+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` with the coding profile and `base: "<branch>"`. Read `writer`
+from the result for collection; default starts cannot take a writer on that
+other branch. `writer_unavailable` is a capacity/state signal, not a reason to
+switch profiles; see [Tool contracts](tool-contracts.md).
+
+**Verify:** the direct relay-path MCP handshake uses
+`PI_WRITER_NO_CREDENTIAL_REFRESH=1`, touching no credential in that launch and
+making no session or provider request. Host registration equality is checked
+by client-target verify; no writer registration is required. **Setup itself
+never writes the host credential file**; host login updates, when needed, are
+performed by Pi through its locked store.
 
 The server guard refuses coding when the clone differs from its recorded baseline
 (extra branches, stash, uncommitted/untracked changes, or different HEAD), and
@@ -245,7 +263,7 @@ listed below; dynamic planned and MCP verification outcomes are listed explicitl
 | `writer_provisioned` | Clone/config/wrapper prepared, not yet accepted |
 | `writer_unchanged` | Provisioned settings already match |
 | `writer_settings_changed` | Existing writer settings or its rendered configuration differ from the current ones; no silent replacement, no acceptance and no registration change ([Isolation setup](isolation-setup.md)) |
-| `writer_registered` | Registration added or already equivalent |
+| `registration_divergent` | Writer registration is foreign or differs from its ownership record; it is retained and the writer stays in legacy launch mode |
 | `writer_reconcile_failed` | Unexpected reconciliation failure |
 | `writer_operation_failed` | Unclassified lifecycle/orchestrator failure |
 | `hook_install_failed` | The wake hook step of a writer failed unexpectedly; other `hook_*` and `settings_*` codes are in [Client setup](client-setup.md#wake-hook) |
@@ -269,10 +287,12 @@ listed below; dynamic planned and MCP verification outcomes are listed explicitl
 | `writer_reset` | Persistent clone reset and verified |
 | `writer_recreate_failed` | Recreated clone is not at baseline |
 | `writer_recreated` | Clone/agent recreated and verified |
-| `writer_reconnect_required` | Writer credentials were cleared; reconnect the writer's MCP server before the next coding start |
+| `writer_busy` | Another process holds the writer's lease (a relayed session, a launcher still cleaning up, or another setup run) for longer than the setup wait; retry after it ends |
+| `writer_fenced` | The writer's container fence could not confirm that no container of this writer exists; nothing was changed |
+| `writer_lease_unavailable` | The writer's lease file or directory could not be opened safely (see Doctor `writer_lease_directory`) |
 | `writer_removed` | Writer state deleted after registration cleanup |
 | `ownership_unavailable` | Existing registration lacks ownership proof; removal refused |
-| `registration_not_equivalent` | Verify found absent/divergent/unsupported required registration |
+| `workspace_base_ambiguous` | Existing writers have different base branches; supply an explicit base before migration can change the workspace modes |
 | `isolation_control_planned` | Control planned only; no canaries written |
 | `isolation_control_required` | Passing host control record required before writer acceptance |
 | `isolation_control_passed` | Uncontained control detected expected escapes and cleaned up |
@@ -312,22 +332,23 @@ The writer baseline guard is the deliberate re-read exception, not general reloa
 
 ## Migration from manual writers
 
-For **`psm-alpha`** and **`go-app-alpha`**, collect/review all work first through
+For hand-made writers, collect/review all work first through
 the old boundary's bundle route. Automated setup does not adopt their manual
 state, wrappers or names.
 
 1. In each writer's original project remove its manual local registration:
-   `claude mcp remove pi-coding-<name> -s local` (substitute `psm-alpha` or
-   `go-app-alpha`). Remove any separately configured Codex registration too.
+   `claude mcp remove pi-coding-<name> -s local`. Remove any separately
+   configured Codex registration too.
 2. After preserving work, remove that manual wrapper and state directory.
    Do not delete the operator's source checkout or another writer's files.
 3. Configure the desired coding profiles, pass the explicit host isolation
    control above, then run
    `pi-session-mcp-setup --repo <alias> --mode container --profiles <coding-aliases> --apply`.
    New names derive from the configured repository alias, not the old manual name.
-4. Restart/reconnect controllers and verify the new writer registrations before use.
+4. Restart/reconnect the host `pi-session-mcp` server, verify its client targets
+   and run `--writer <name> --verify` before use; no writer registrations are added.
 
-For the Go-toolchain writer **`go-app-alpha`**, supply an **operator-supplied
+For a Go-toolchain writer, supply an **operator-supplied
 local image ID** containing Node, Git and the Go toolchain, plus `--cache go`:
 
 ```sh
@@ -341,5 +362,27 @@ Container options are rebuilt from supplied values and defaults each time:
 repeat the image ID and `--cache go` on later mode requests, or cache defaults
 to `none`. Setup does not build or install the Go toolchain for you.
 
+A Python writer using uv and npm uses the same pattern with `--cache uv`:
+
+```sh
+pi-session-mcp-setup --repo <alias> --mode container --profiles <coding-aliases> \
+  --image <image-id> --cache uv --apply
+```
+
+This 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, so download and network policy stay the
+image's. The directory is per writer: it is never shared between writers and
+never a host cache mount. Setup does not install uv or npm for you.
+
+### Base tags (opt-in)
+
+Container writers default to `tags: "none"`. Pass `--tags reachable` to bundle
+only operator-checkout tags merged into the selected base commit. Repeat this
+flag on later mode requests to retain it. Reset deletes every clone tag before
+importing the selected base tags; tags created by workers are never collected
+and do not change the collected-work digest. Changing the tag setting requires
+reprovisioning for settings drift, but does not change boundary acceptance.
+
 See [Isolation setup](isolation-setup.md) for boundary prerequisites and what
 setup automates, and the historical manual acceptance evidence linked there.

package/docs/installation.md

@@ -65,8 +65,9 @@ the same arguments.
   [client setup reference](client-setup.md), works independently of `setup`.
 - 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; writer registration health checks can
-  start its launcher and copy/refresh selected credentials. Direct writer verify
+  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
@@ -207,12 +208,12 @@ coding-profile aliases (`--profiles a,b`); without it, setup reports
 [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,
-then registers their wrappers. First explicitly authorize the host isolation
+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 `psm-alpha` and `go-app-alpha`.
+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.
 
@@ -395,8 +396,8 @@ not a token or cost saving, and none is measured on short tasks. Design:
    `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` and of the
-`pi-coding-*` writer registrations, and one command hook:
+`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
@@ -405,17 +406,16 @@ 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 spool of the server that armed it: the host's
-`$XDG_RUNTIME_DIR/pi-session-mcp/events/inst-*` for `pi-session-mcp`, and a
-writer's own `~/.local/state/pi-session-mcp/writers/<name>-wN/events/inst-*` for
-`pi-coding-<name>-wN`. Its claims stay in `$XDG_RUNTIME_DIR/pi-session-mcp/claims`.
+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`). The local-scope entry of a project is shared by
-the host registration and the writer registrations there and stays
-(`hook_kept_shared`) until the last of them that needs it is removed. With
+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
@@ -446,8 +446,8 @@ package path. The settings-file codes are in the
   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 writers need their own spool mount; see
-  [Isolation setup](isolation-setup.md#event-spool-mount).
+- 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
 
@@ -728,13 +728,24 @@ Writer acceptance binds the package version, so every container writer is
 targets until they are accepted again. With container writers, run the
 repository step between the install and the client targets:
 
-1. Install the new package (`npm install -g` or the release checkout above).
-2. For each repository in mode `container`, repeat its provisioning command
+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
-   accepts every writer again whose acceptance is not current and keeps its
-   clone and the work in it. Close the coding sessions on those writers
-   first: acceptance briefly places canaries in the clone. Use the same
+   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
@@ -743,7 +754,8 @@ repository step between the install and the client targets:
    `--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.
+   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