pi-session-mcp 0.11.9 → 0.12.0

package/docs/adr/0012-leased-writer-pool.md

@@ -0,0 +1,357 @@
+# ADR 0012: One registration with a leased writer pool
+
+**Status:** Accepted (2026-10-28, maintainer decision) for release 0.12.0;
+implementation tracked in
+[#157](https://github.com/plagor44-ux/pi-session-mcp/issues/157). Amends
+[ADR 0002](0002-embedded-pi-sdk.md) (container sessions are relayed to a Pi
+session in a writer process; host sessions stay embedded),
+[ADR 0008](0008-coding-profile-isolation.md) (adopts its option 4 in container
+form and retires the client registration per writer),
+[ADR 0009](0009-execution-modes.md) (container entries record a default base;
+coding on `container` workspaces runs through the host server) and
+[ADR 0011](0011-turn-events-and-controller-wake.md) (relayed sessions use the
+host spool).
+
+## Context
+
+Today every container writer is its own client registration,
+`pi-coding-<alias>-w<n>`, for Claude Code and optionally for Codex. Its
+`wrapper.sh` runs the writer launcher (`writer-launch`), which checks state and
+acceptance, projects boundary credentials, refreshes them every 60 s and runs
+`podman run -i --rm …` with a pi-session-mcp server inside the writer's
+container, bound to that writer's full clone. This follows ADR 0008: one
+wrapped registration sees the union of what it mounts, so writers are isolated
+from each other only with one boundary per writer.
+
+Observed costs on 2026-10-27, with four writers for each of several
+repositories:
+
+- Each client session holds one tool set per writer registration plus the host
+  set, and the controller has to pick a writer by tool prefix.
+- Each registration starts its container when the client connects and keeps it
+  for the whole client session: 15 idle writer containers were running on one
+  workstation.
+- Reset, finish and recreate replace the writer's projected credentials, so the
+  running writer server needs an MCP reconnect before the next coding start
+  (#136, `writer_reconnect_required`).
+- Nothing stops two client processes from launching the same writer at the
+  same time. The writer guard's `writer_busy` counts sessions inside one server
+  process only.
+- The wake hook accepts writer tool names only up to `-w16`.
+- Each writer has its own base branch. `--reset --base <branch>` moves a writer
+  to another branch, for example for a fix round on collected work, and a
+  later `--finish` resets it to that same branch again. Today the controller
+  reaches that writer by its tool prefix; a pool that picks any writer at
+  baseline would ignore which branch the writer is on.
+
+ADR 0008 listed "one sandboxed worker process per session, with the server
+relaying MCP calls" as option 4 and deferred it to its own decision. ADR 0002
+chose embedding to avoid subprocess and RPC translation; that choice stays for
+host sessions.
+
+## Decision
+
+Coding on a `container` workspace runs through the one host registration,
+`pi-session-mcp`. Per coding session the host server leases a writer of that
+workspace, starts the writer's existing launcher as a child process and relays
+the session to the pi-session-mcp server inside the writer's container.
+
+### 1. Transport and launch path
+
+- Each client still starts its own host server over stdio. No HTTP, socket,
+  daemon or shared process is added.
+- The host server spawns the writer's `wrapper.sh` with stdio pipes and talks
+  MCP to the inner server through it. The launcher keeps its role: state and
+  acceptance checks, credential projection and the maintainer-approved
+  `getAuth` refresh (#142) stay in the launcher process, so the AGENTS.md
+  exception is not widened.
+- The launcher gives the session container a fixed name derived from the
+  writer name (`pi-writer-<name>`), and every container that touches a writer,
+  including setup's throwaway containers, a label `pi-session-mcp.writer=<name>`.
+  Podman refuses a second container with the fixed name while one exists.
+
+### 2. Fence: a lease held by the guardian process, plus container absence
+
+Exclusive use of a writer needs both:
+
+- **Lease held by the trusted host-side process that acts on the writer.** For a
+  session that is the launcher, not the host server; for setup operations it is
+  the setup process. A lock file per writer lives in a host-only lease directory
+  (`~/.local/state/pi-session-mcp/leases/<name>.lock`), outside every writer
+  root, never deleted, opened without following links and checked for type,
+  owner and mode. The launcher takes it with a true non-blocking `flock` as its
+  first step and holds it for its whole lifetime: credential warm-up and
+  projection, container run, refresh, and cleanup. Setup takes it with a
+  bounded wait.
+- **The lease descriptor is inherited by every mutating host-side child.** The
+  holder passes the locked descriptor to each child that can change the writer
+  (Podman client calls, host Git against the bundles, a nested launcher started
+  by acceptance), so the lock's open file description stays locked until the
+  last of these processes ends. A killed holder therefore cannot leave a
+  pending `podman run` or Git child behind that acts after the next holder has
+  taken over. A nested launcher receives the descriptor and its number
+  explicitly, verifies that it refers to the lease file (device and inode) and
+  holds the lock, and uses it instead of opening a new one; this is how
+  acceptance launches the wrapper while setup holds the fence. The descriptor
+  is never passed into a container (no `--preserve-fds`); tests must confirm
+  that neither the container nor Podman's monitor process holds it.
+- **Container absence.** After taking the lease, and before any credential
+  write or clone change, the holder checks through Podman that no container
+  with the writer's label exists and that no container mounts the writer's
+  clone (this also finds unlabeled containers started by older releases). A
+  container found while holding the lease belongs to a dead holder: the holder
+  stops it, waits a bounded time until Podman reports it removed, and kills it
+  if needed. If absence cannot be confirmed, the writer stays fenced and the
+  operation fails.
+
+A launcher that outlives its host server keeps the lease until it has stopped
+its container and joined its refresh. Only a killed launcher can leave a
+container behind, and the next holder removes that container before it touches
+the writer.
+
+### 3. Every mutating operation takes the fence
+
+Coding sessions, `--collect`, `--reset`, `--finish`, `--recreate`, `--remove`,
+acceptance and every provisioning reconciliation or recovery path run under the
+same fence for the whole operation, not after a separate busy check. A setup
+operation that cannot get the fence reports `writer_busy`.
+
+### 4. Base selection
+
+- The controller selects work by base branch, not by writer. `pi_session_start`
+  gains an optional `base`: a short branch name, validated with the same
+  safe-ref rules setup applies to `--base`, without `refs/` prefix, commit IDs,
+  `HEAD` or path syntax. It is accepted only for coding profiles on `container`
+  workspaces; elsewhere the start fails with `base_not_applicable` before
+  creating a session.
+- Each container workspace records a **default base** in its
+  `execution-modes.json` entry (`base`, a short branch name). Provisioning sets
+  it from `--base` or, without one, from the existing resolution
+  (`origin/HEAD`, else `main`). A repeated mode request without `--base` keeps
+  the recorded value.
+- A start without `base` uses the default base. A writer is a candidate only if
+  its recorded `base.ref` equals `refs/heads/<base>`. Matching reads host-side
+  writer state only, never the clone, and compares the branch, not the commit:
+  the start result reports the writer's base commit, so the controller sees
+  which state it got. Selection happens before the lease; once the inner start
+  succeeded, the relay reads the writer state again and closes the session and
+  moves on if the base changed in between.
+- `--finish` resets a persistent writer, and recreates an ephemeral one, on the
+  workspace default base instead of the writer's current base. Moving a writer
+  to another branch stays an explicit `--reset --base <branch>`. A writer
+  therefore leaves the default pool only for the time between that reset and
+  its finish.
+- Doctor warns offline with `writer_off_default_base` and a count when ready
+  writers sit on another branch, because they shrink the default pool.
+
+The fix-round flow becomes: create a local branch at the collected ref, run
+`--writer <name> --reset --base <branch> --apply`, start with
+`base: "<branch>"`. Default starts, from this or another client, cannot land on
+that writer, and the fix-round start cannot land on a writer at the default
+base.
+
+### 5. Allocation
+
+- Candidates are the workspace's writers in index order whose state is `ready`,
+  whose acceptance is current and whose base matches (section 4). There is no
+  host-side pre-filter of the clone's contents.
+- The host server starts the launcher of the first candidate. A launcher that
+  cannot take the lease returns `writer_busy`; an inner start that refuses
+  because the clone is not at baseline or holds uncollected work also moves on.
+  In both cases the host server closes that launcher and tries the next
+  candidate. The inner writer guard stays the authority for baseline admission
+  inside the boundary.
+- Before the inner start the relay compares the requested profile's entry in
+  the writer's validated `pi_capabilities_get` (permission profile, provider,
+  model, thinking level) with the host's configured profile and moves on with
+  `writer_settings_changed` on any difference, so a writer never runs an
+  outdated version of a host profile. The launcher cannot do this check: it
+  starts before the profile is known.
+- If no candidate is admitted, the start fails with `writer_unavailable`, a
+  content-free reason and content-free counts. `none_ready`: no writer of the
+  workspace is ready, migrated and has a recorded acceptance (whether that
+  acceptance is still current is decided by the launcher, which refuses a
+  stale one). `none_at_base`: ready writers
+  exist, none on the requested base. `none_admitted`: candidates existed and
+  each refused; the counts `busy`, `notAtBaseline` and `settingsChanged` say
+  why.
+- The controller cannot name a writer in this version (see Alternatives).
+
+### 6. Start, budgets and uncertain outcomes
+
+- A container start has its own end-to-end budget (initial value 60 s, to be
+  measured), split into launch and credential warm-up, MCP handshake,
+  validated `pi_capabilities_get`, and inner `pi_session_start`. Every step has
+  a bound below the remaining budget (cleanup of a refused candidate has its
+  own bound on top), and cancellation of the outer start is
+  propagated.
+- The launcher's refusal server answers the handshake and lists tools, then
+  returns refusal codes. Readiness is therefore decided by the validated
+  capabilities and the inner start result, never by exit status or the tool
+  list. Inner refusals map to the existing public codes.
+- Relayed prompts get an outer preflight deadline longer than the inner one.
+  If the outer side times out or loses the response while the inner turn may
+  have been accepted, the relay aborts the inner turn, waits for its terminal
+  state within the abort budget and reports the outer prompt as failed. If the
+  inner state cannot be determined, the session is marked lost (see 8).
+
+### 7. Relay behind `PiSessionAdapter`
+
+- The relay is a `PiSessionAdapter`. The host registry keeps owning session
+  and turn IDs, the one-running-turn rule, terminal state and the host event
+  spool, so the wake hook sees relayed turns like host turns.
+- The relay observes the inner turn with bounded `pi_turn_get` polling inside
+  the host process. It advances activity only when the inner `updatedAt`
+  changes, and carries the inner `truncated` flag into the outer result
+  (`PiTurnOutcome` gains an optional `truncated`).
+- **Abort.** The relay sends `pi_session_abort`, then reads the inner turn and
+  settles the outer turn with the inner turn's actual terminal state: a turn
+  that completed before the abort stays `completed`. A failed or timed-out
+  abort marks the session lost (see 8): further prompts are refused, get and
+  close keep working.
+- Inner responses are untrusted data: schema-validated, size-bounded and never
+  passed through as raw frames.
+
+### 8. Lost sessions and close
+
+- If the child exits or the transport breaks, the running turn, if any, ends
+  `failed`, and the session becomes lost: further prompts return
+  `writer_session_lost`; get and close keep working. This also applies while
+  the session is idle.
+- `pi_session_close`, server shutdown and client transport loss close the
+  inner session and then the launcher's stdin. The launcher runs in its own
+  process group and treats stdin end, `SIGTERM` and `SIGHUP` alike: it stops
+  scheduling refreshes, joins an outstanding refresh, stops and removes its
+  container, confirms its absence, and only then exits and so releases the
+  lease. Its cleanup has its own bound, longer than the longest refresh.
+- The host server does not wait for the full cleanup: close returns once the
+  inner session is closed and the launcher has been told to stop. Fencing does
+  not depend on the host server, because the launcher still holds the lease. A
+  launcher whose cleanup exceeds its bound exits without releasing the
+  container check: the next holder finds and removes the container (section 2).
+
+### 9. Visibility
+
+`pi_session_start` and `pi_session_get` report the leased writer name and its
+base branch and commit for container sessions, so the controller can collect
+that writer's work and see which state the session started from.
+`pi_capabilities_get` reports each container workspace's configured writer
+count and default base, not a free count or the branches of other writers.
+
+### 10. Events
+
+Relayed sessions emit terminal events through the host registry into the host
+spool. The launcher starts relayed containers without the writer spool mount.
+The wake hook matches the host tool names only.
+
+### 11. Setup, migration and acceptance
+
+- Container mode no longer registers writer servers with any client.
+- Migration needs a quiescence barrier. The upgrade runbook keeps the existing
+  rule to close coding sessions and controllers first, so no launcher of the
+  old release is in flight, and the wrapper rebinding below makes every later
+  launch, also through a not yet removed writer registration, run the new
+  launcher, which takes the lease and checks container absence.
+- The migration step then, per writer and under the fence, confirms that no
+  container mounts the clone, removes the `pi-coding-<alias>-w<n>`
+  registrations that setup owns, and marks the writer `launch: "relay"` in its
+  state. Removal uses the existing ownership-checked unregister path. A
+  client's inspection can health-check the registration and so start its
+  wrapper, but only while setup holds the writer's lease: that launch then
+  serves a `writer_busy` refusal and starts no container. A
+  writer whose registration is divergent stays out of the pool and is reported;
+  setup never replaces or deletes a divergent registration. Because every
+  launch repeats the absence check, a legacy launch that slips through later is
+  still fenced.
+- Migration records the workspace default base (section 4). If all writers
+  share one base branch, that branch is recorded; otherwise migration requires
+  an explicit `--base` and stops with `workspace_base_ambiguous` without it.
+- `wrapper.sh` stays as the launch entry point at its stable path. Wrappers
+  embed an absolute release root, so migration rewrites the wrapper of every
+  writer it migrates for the new release before the writer is marked
+  `launch: "relay"`. A writer held back by settings drift or a divergent
+  registration keeps its wrapper unchanged; it stays out of the pool, and its
+  retained registration must not be used until the operator resolves it. With
+  a release installed at the same path, such a wrapper already runs the new,
+  fenced launcher. Acceptance keeps binding the wrapper, release version and
+  launch settings. Because the launch arguments
+  change (container name, no spool mount for relayed sessions), every writer is
+  re-accepted provider-free through the relay launch path before it becomes a
+  pool candidate, as on any release upgrade.
+- Verify checks the host registration, Doctor, and for each writer a bounded
+  spawn through the relay path with credential refresh suppressed, MCP
+  handshake, `tools/list` and validated capabilities, without starting a
+  session or using a provider.
+- `writer_reconnect_required` is removed: reset and finish run under the fence
+  and no long-lived writer server exists between sessions.
+- Doctor stays offline. It gains checks for the lease directory, for writers
+  not yet migrated, for container workspaces without a recorded default base,
+  and the `writer_off_default_base` warning (section 4).
+
+## Boundary
+
+The product boundary stays local stdio, in-memory state and one trusted local
+MCP peer per server process. The writer boundary is unchanged: one container
+and one full clone per writer, the same mounts and exclusions, `.git/config`
+and hooks read-only, and no host Git inside a clone. What changes is who starts
+the launcher (the host server instead of the client) and when (per session
+instead of per client connection). The host server already runs with the
+operator's rights; setup and the launcher already run Podman today.
+
+## Consequences
+
+- One tool set per client; no per-writer registrations; no idle writer
+  containers.
+- A coding start on a container workspace takes seconds longer.
+- No reconnect after reset or finish. Reset, finish and collect refuse while a
+  session holds the writer.
+- Two clients cannot use the same writer at the same time, including after a
+  crash of the previous holder.
+- Follow-up rounds on collected work keep the branch and reset steps and add
+  `base: "<branch>"` to the start (section 4). Default starts never land on a
+  writer moved to another branch.
+- `--finish` returns a writer to the workspace default base instead of keeping
+  the branch it was last reset to.
+- Contract change: the optional `base` start argument, new error codes
+  (`writer_unavailable` with reason and counts, `writer_session_lost`,
+  `base_not_applicable`), the writer and base fields in session results, the
+  default base in capabilities and an optional `truncated` in the adapter
+  outcome. Minor version bump (0.12.0) with re-acceptance of every writer.
+
+## Alternatives considered
+
+- **Keep one registration per writer and add only the fence.** Fixes the
+  concurrent-launch gap, but keeps the tool sets, idle containers and
+  reconnects. Rejected as the end state; the fence is reused.
+- **Fewer writers per repository.** Configuration only; reduces but keeps every
+  cost. Rejected by the maintainer (2026-10-28).
+- **A shared pool daemon over HTTP or a Unix socket.** Would let clients share
+  sessions, but adds a long-lived service, persistence and multi-client trust,
+  all outside the product boundary. Not needed for the goal.
+- **Spawn `podman run` from the host server directly.** Moves the credential
+  refresh into the host server and widens the AGENTS.md exception, and drops
+  the acceptance binding to the wrapper. Rejected in favour of spawning the
+  launcher.
+- **Pass the lease descriptor into the container.** Would keep the lock until
+  the container ends, but a process inside could release it with `LOCK_UN` on
+  the shared open file description. Rejected in favour of a host-side holder.
+- **Hold the lease in the host server.** The host server can die while its
+  launcher still writes credentials or starts a container. Rejected in favour of
+  the launcher as the holder.
+- **Server picks any writer at baseline, ignoring its base.** Simplest
+  contract, but a fix-round start can land on a writer at the default base, and
+  an unrelated start can land on a writer just reset to a fix branch, also from
+  another client. Rejected.
+- **Controller names the writer.** Deterministic and close to today's flow,
+  but capabilities would have to list writer names, a pinned busy writer fails
+  instead of falling back, and a start without a name could still land on a
+  writer moved to another branch, so base matching would be needed anyway.
+  Deferred; a diagnostic writer argument can be added later without breaking
+  the contract.
+- **Preferred writer with silent fallback.** Can silently start work from the
+  wrong branch. Rejected.
+
+## Open questions
+
+- Measured start budget on the reference machines.
+- Whether ephemeral writers recreate on close instead of on finish.

package/docs/architecture.md

@@ -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`),
@@ -49,6 +49,55 @@ 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, `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
 
 The SDK adapter owns one durable `ModelRuntime` for profiles without extensions. (A profile with `extensions` creates a fresh runtime for each session; see [Pi extensions design](pi-extensions-design.md).) For the configured profile, it uses that runtime to call `getProvider(providerId)`, `getModel(providerId, modelId)`, `checkAuth()`, `getAuth(model)`, and `getAvailable(providerId)`. It rejects an absent provider or model, missing or unavailable local authentication, and a model not present in the local available-model set before constructing a session. Authentication uses only Pi's existing local mechanism; auth objects are presence-checked and never retained, serialized, or logged.
@@ -73,9 +122,9 @@ 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.
 
@@ -94,7 +143,7 @@ Claude Code asyncRewake <-- exit 2 + one line <-- pi-session-mcp-wake <---+
 ```
 
 - **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. If a writer launch has pruned the instance directory as idle, the next write recreates it once under the same owner and mode rules.
+- **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.
@@ -106,20 +155,19 @@ $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/
-
-~/.local/state/pi-session-mcp/writers/<name>/     on disk, one per container writer
-  events/                              0700, mounted at /pi/events
-    inst-<16 hex>/                     one per server process in that writer
 ```
 
-A host server uses `events/` itself as its spool root unless `PI_SESSION_MCP_EVENTS_DIR` names an absolute directory; the writer wrapper sets it to `/pi/events`, so inside the boundary the instance directories sit directly in the mount. 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.
+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), a container writer's spool is on disk and only what a crashed server left behind outlives a logout (a later launch prunes it after 24 hours), and no event is replayed. This is the narrow, content-free exception to in-memory-only operation that ADR 0011 records.
+- **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.
 
-Container writers get one dedicated spool directory each, on disk in the writer's own state directory (not on the runtime tmpfs), bind-mounted read-write; see [Isolation setup](isolation-setup.md#event-spool-mount). Codex has no external wake and keeps polling.
+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
 

package/docs/client-setup.md

@@ -208,10 +208,10 @@ of the target's scope, after the registration succeeded. Guided steps and limits
 
 **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`.
-The hook that a `pi-coding-<name>-wN` tool call arms reads only the `inst-*`
-directories of that writer's own spool, `~/.local/state/pi-session-mcp/writers/<name>-wN/events`.
-It reads no other location, and it keeps its claims and waiter locks in
-`$XDG_RUNTIME_DIR/pi-session-mcp/claims`, outside both spools.
+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,
@@ -262,17 +262,13 @@ applicable), delivery off while setup holds no entry (`hook_not_enabled`), and
 setup report with delivery off and no owned entry therefore has the same
 findings, order and exit code as before the hook existed.
 
-Writer registrations (`pi-coding-<name>`, Claude Code local scope) get the entry
-in `<project>/.claude/settings.local.json` of the operator's project when the
-writer's own configuration enables delivery. One entry and one record serve the
-project, so it is removed only when no other owned registration needs it: a
-writer of the same project whose configuration enables delivery, or the owned
-host registration `claude-code:local:pi-session-mcp` while the host
-configuration enables delivery (its project is not recorded, so it counts for
-every project). When in doubt the entry stays. A hook problem while removing a
-writer is reported (`settings_*`, `hook_divergent`) but does not keep the
-writer: its registration and files are removed, and the record keeps the entry
-owned for the next removal. Codex writer registrations get no hook.
+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

package/docs/doctor-design.md

@@ -34,10 +34,15 @@ and owners are:
 | `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>` |
@@ -70,9 +75,10 @@ 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, registration equality and a bounded direct MCP handshake/tools/list/
-capabilities; Claude's registration inspection health-check briefly starts a
-container. Its direct verification launch disables credential refresh.
+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).
@@ -85,7 +91,7 @@ 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 fails with the startup code `event_spool_unavailable` when it has neither that directory nor `PI_SESSION_MCP_EVENTS_DIR`. The check says nothing about writer spool directories: a writer's launch creates and verifies its own (`events_directory_unavailable`, see [Isolation setup](isolation-setup.md#event-spool-mount)). The report holds the fixed subject `event spool` and a fixed remediation, never a path.
+`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