pi-session-mcp 0.8.3 → 0.12.0

package/CHANGELOG.md

@@ -2,6 +2,533 @@
 
 ## Unreleased
 
+## 0.12.0 — 2026-10-28
+
+Minor release under ADR 0003 for
+[ADR 0012](docs/adr/0012-leased-writer-pool.md)
+([#157](https://github.com/plagor44-ux/pi-session-mcp/issues/157)): one host
+registration codes in container workspaces through a leased writer pool. The
+MCP contract changes: `pi_session_start` gains an optional `base`, sessions and
+capabilities gain writer fields, and there are new error codes. It also ships
+the writer cache and identity changes of
+[#151](https://github.com/plagor44-ux/pi-session-mcp/issues/151) and
+[#154](https://github.com/plagor44-ux/pi-session-mcp/issues/154). `npm audit`
+still reports `undici` 8.10.2, pinned by Pi SDK 1.4.0, the latest SDK release
+([#120](https://github.com/plagor44-ux/pi-session-mcp/issues/120)).
+
+Upgrading needs a one-time migration of every container repository; follow
+[Installation](docs/installation.md#upgrade). Writers must be accepted again
+after the upgrade, as after every release.
+
+- Changed: coding on a `container` workspace goes through the one host
+  registration `pi-session-mcp`. The host leases a ready, accepted writer at
+  the requested or default base and relays the session to the writer's
+  contained server over stdio. Setup no longer adds `pi-coding-<alias>-w<n>`
+  registrations or writer hook entries, and `--client codex` has no writer
+  effect any more. Relayed start has a 60-second budget, prompt preflight and
+  abort 15 seconds each, and close cleanup 10 seconds; inner replies are
+  validated and size-bounded.
+- Changed: every writer operation, from launch to setup's collect, finish,
+  reset and recreate, runs under a per-writer host lease
+  (`~/.local/state/pi-session-mcp/leases/<name>.lock`) and a container fence
+  (container name, label and clone mount). A held lease fails with
+  `writer_busy`; setup waits up to 10 seconds for it. A container that cannot be
+  removed fails with `writer_fenced`. The lease descriptor never enters a
+  container.
+- Changed: reset, finish and recreate no longer need a reconnect of the writer
+  server; setup no longer reports `writer_reconnect_required`.
+- Added: `pi_session_start` accepts an optional `base`, a short branch name,
+  for coding profiles on `container` workspaces; elsewhere it fails with
+  `base_not_applicable`. Container coding sessions carry `writer` and `base`,
+  and `pi_capabilities_get` lists each container workspace's `writers` and
+  `defaultBase`.
+- Added: error codes `writer_unavailable` (with `reason` `none_ready`,
+  `none_at_base` or `none_admitted`, and the counts `busy`, `notAtBaseline`
+  and `settingsChanged`), `writer_session_lost` and `base_not_applicable`.
+- Added: container modes record a default base. Setup records the base that
+  provisioning resolves (`--base`, else `origin/HEAD`, else `main`); migration
+  records the writers' shared base and fails with `workspace_base_ambiguous` if
+  they differ and no `--base` is given. Finish returns a writer to the default
+  base.
+- Added: re-running a repository's provisioning command migrates its writers:
+  it removes the owned writer registrations and hooks, rewrites the wrappers,
+  marks the writers `launch: "relay"` and accepts them again. A divergent
+  registration is never removed; it reports `registration_divergent`, and that
+  writer stays outside the pool.
+- Added: Doctor checks `writer_lease_directory`, `writer_not_migrated`,
+  `workspace_base_unset` and `writer_off_default_base`.
+- Added: `--cache uv` mounts a private per-writer cache at `/pi/uv` with
+  `UV_CACHE_DIR=/pi/uv/cache` and `npm_config_cache=/pi/uv/npm`
+  ([#151](https://github.com/plagor44-ux/pi-session-mcp/issues/151)).
+- Added: writer clones get the operator checkout's commit identity when both
+  values are valid, and Doctor warns with `writer_git_identity_missing`
+  otherwise. `--tags reachable` bundles the tags reachable from the base
+  commit; the default stays `none`
+  ([#154](https://github.com/plagor44-ux/pi-session-mcp/issues/154)).
+- Changed: the wake hook matches only `mcp__pi-session-mcp__*` and reads the
+  host spool, which now also carries relayed container turns. Migrated writers
+  get no spool mount; a writer that is not yet migrated keeps it.
+- Limits: lease, fence and relay need Linux. The live migration of an existing
+  installation and a relayed coding turn follow the release.
+
+## 0.11.9 — 2026-10-27
+
+Documentation-only release. The published `docs/` of 0.9.0 to 0.11.8 contained
+references to the maintainer's private environment; they are removed, and those
+versions are withdrawn from npm. Code, MCP contract and behavior are unchanged
+from 0.11.8.
+
+## 0.11.8 — 2026-10-26
+
+Patch release for [#148](https://github.com/plagor44-ux/pi-session-mcp/issues/148):
+installations with two or more container repositories could not complete an
+upgrade. It also carries the fixes of 0.11.7, which such installations could
+not install. The MCP contract is unchanged. `npm audit` still reports
+`undici` 8.10.2, pinned by Pi SDK 1.4.0, the latest SDK release
+([#120](https://github.com/plagor44-ux/pi-session-mcp/issues/120)).
+
+- Fixed: after an upgrade, the repository step of one container repository no
+  longer fails with `doctor_failed` because the writers of another container
+  repository are still `writer_not_ready`. With two or more container
+  repositories no repository step could pass, and the client targets stayed
+  unregistered ([#148](https://github.com/plagor44-ux/pi-session-mcp/issues/148)).
+  Every release before this one has the gap; it shows once two or more
+  repositories use container mode. Upgrade such an installation straight to
+  this release.
+
+## 0.11.7 — 2026-10-26
+
+Patch release for Sprint 11
+([#141](https://github.com/plagor44-ux/pi-session-mcp/issues/141),
+[#142](https://github.com/plagor44-ux/pi-session-mcp/issues/142)) and the
+controller skill's review stage. The MCP contract is unchanged. `npm audit`
+still reports `undici` 8.10.2, pinned by Pi SDK 1.4.0, the latest SDK release
+([#120](https://github.com/plagor44-ux/pi-session-mcp/issues/120)). Writers
+must be accepted again after the upgrade, as after every release.
+
+- Fixed: Doctor reports `container_profile_refused` for selected coding profiles that container writer provisioning would reject, and reports unreadable configuration without blaming individual profiles (#141).
+- Fixed: writer launches now refresh a selected OAuth credential on the host
+  when it expires within **10 minutes** (was 2), through the Pi SDK's
+  documented `ModelRuntime` on the host's locked credential store, before the
+  SDK inside the writer opens its own five-minute pre-expiry window, in which
+  writer turns could fail; not yet confirmed by a live turn
+  ([#142](https://github.com/plagor44-ux/pi-session-mcp/issues/142)).
+  Several OAuth providers are refreshed in parallel under one 20 s bound.
+- Fixed: the setup Doctor gate counts `container_profile_refused` for the
+  repository's own profile as the repository's own finding, so collect, finish
+  and the profile change that fixes it are not blocked by it (#141).
+- Changed: the orchestration skill asks for a cross-family read-only review of
+  every code task, with a verdict line and at most three fix rounds, and
+  explains how a fresh session continues from collected writer work.
+
+## 0.11.6 — 2026-10-26
+
+Patch release for the Sprint 9 close-out
+([#134](https://github.com/plagor44-ux/pi-session-mcp/issues/134),
+[#135](https://github.com/plagor44-ux/pi-session-mcp/issues/135),
+[#136](https://github.com/plagor44-ux/pi-session-mcp/issues/136),
+[#137](https://github.com/plagor44-ux/pi-session-mcp/issues/137)) and the
+Sprint 10 skill changes. The MCP contract is unchanged. `npm audit` still
+reports `undici` 8.10.2, pinned by Pi SDK 1.4.0, the latest SDK release
+([#120](https://github.com/plagor44-ux/pi-session-mcp/issues/120)).
+
+- Fixed: `setup --writer <name> --reset`, `--finish` and `--recreate` rewrite
+  the writer's projected credentials, so a running writer server could fail
+  its next coding start with `local_authentication_missing` until the client
+  reconnected it. After an applied, successful reset, finish or recreate, setup
+  now reports `writer_reconnect_required`, and the orchestration skill and
+  `docs/isolation-setup.md` name the reconnect
+  ([#136](https://github.com/plagor44-ux/pi-session-mcp/issues/136)).
+- Added: Doctor warns with `extension_unpinned` when an extension that an
+  execution profile pins as `npm:<name>@<version>` is listed in Pi's agent
+  `settings.json` without a version, as a string or as an object's `source`.
+  Pi can update such a package by itself, which then fails Doctor with
+  `extension_version_mismatch`. Missing or unreadable settings are ignored, and
+  Doctor loads the Pi SDK only for this check
+  ([#137](https://github.com/plagor44-ux/pi-session-mcp/issues/137)).
+- Changed: when the Doctor gate blocks `setup --repo <alias> --mode container
+  ... --apply` or a mutating `--writer` operation, setup reports one failed
+  finding per blocking check next to `doctor_failed`, with the Doctor check id
+  as its code and the profile or workspace alias of its subject. The gate's
+  tolerance is unchanged: an error in a profile that the repository does not
+  select still blocks
+  ([#137](https://github.com/plagor44-ux/pi-session-mcp/issues/137)).
+- Changed: the shipped skills carry a report contract. The orchestration skill
+  asks workers for a first line `STATUS:` with `DONE`, `DONE_WITH_CONCERNS`,
+  `NEEDS_CONTEXT` or `BLOCKED`, checks the report format before verifying,
+  acts on each status, follows up once on a turn that finished quickly without
+  a change, and routes tasks by type with the evidence level stated. The
+  implementation and review skills emit the status line, stop with `BLOCKED`
+  on a wrong base instead of fetching, and do not end a turn on a plan alone.
+  Container writers use the new worker skills after the upgrade and a
+  `--repo <alias> ... --apply`; until then the new controller asks once more
+  for a report in the new format.
+- Fixed: `setup --repo <alias> --mode container ... --apply` kept an existing
+  writer silently on its old settings when the image, network, cache, profile
+  list or a selected coding profile (model, thinking level, skills) or the
+  event delivery had changed, and reported only `writer_registered`. Reconcile
+  now checks every kept writer first against the settings and the configuration
+  it would be provisioned from now and reports `writer_settings_changed`
+  without accepting the writer or changing its registrations. The image is
+  resolved locally only and never pulled: Podman that cannot be asked reports
+  `podman_unavailable`, an image it cannot resolve `image_unavailable`. The dry
+  run runs the same check, so it now asks Podman too. Key order in the profile
+  objects does not count as a change, and an explicit `events.delivery` of
+  `"off"` counts the same as no `events` field
+  ([#134](https://github.com/plagor44-ux/pi-session-mcp/issues/134)).
+
+- Fixed: a coding profile for a container repository could select a `builtin:`
+  skill that the writer cannot resolve the same way as the host. Operator
+  overrides never reach the writer, so a customized `pi-session-implementation`
+  was replaced silently by the shipped text, and a name that exists only as an
+  override failed the session start with `skill_load_failed`. Setup now refuses
+  such a profile with `container_profile_unsupported`: a selected `builtin:`
+  skill must be shipped by the package and must have no override. For an
+  existing writer reconcile reports the same code and leaves the writer as it
+  is, so after an upgrade it stays `writer_not_ready` until the profile changes,
+  the override is removed, or the writer is removed and provisioned again
+  ([#135](https://github.com/plagor44-ux/pi-session-mcp/issues/135)).
+- Development: a provider-free `claude plugin eval` suite for the
+  orchestration skill under `eval/controller-skill/`, and a probe showing that
+  worker sessions keep Pi's default system prompt
+  (`docs/evaluation/worker-system-prompt-2026-10-26/`).
+
+## 0.11.5 — 2026-10-25
+
+Patch release for the Sprint 8 upgrade defects
+[#130](https://github.com/plagor44-ux/pi-session-mcp/issues/130) and
+[#131](https://github.com/plagor44-ux/pi-session-mcp/issues/131), found when
+the pilot writers were upgraded to 0.11.4. `npm audit` still reports `undici`
+8.10.2, pinned by Pi SDK 1.4.0
+([#120](https://github.com/plagor44-ux/pi-session-mcp/issues/120)).
+
+- Fixed: after a package upgrade, `setup --repo <alias> ... --apply` reported
+  `writer_registered` for container writers but did not accept them again, so
+  Doctor kept reporting `writer_not_ready` and blocked the client targets.
+  Reconciliation now accepts every kept writer whose acceptance is not current,
+  using Doctor's `writer_not_ready` predicate (not ready, a stale fingerprint or
+  a missing image), instead of only writers whose phase is not ready. A writer
+  whose re-acceptance fails is not registered again; an existing registration
+  stays and refuses with `writer_not_ready` until the writer is accepted. When
+  Podman cannot be asked or fails, a ready writer is left as it is and setup
+  reports `podman_unavailable`. `docs/installation.md#upgrade` describes the
+  order for operators with container writers
+  ([#130](https://github.com/plagor44-ux/pi-session-mcp/issues/130)).
+- Fixed: writer acceptance failed with `acceptance_harness_failed`
+  (`digests.preexisting_changed`) when a selected host OAuth token was expired
+  or about to expire, because the writer launch inside the harness refreshed it
+  in the host's Pi agent directory. The harness now launches the writer with
+  `PI_WRITER_NO_CREDENTIAL_REFRESH=1`, as direct verify does; acceptance makes
+  no provider request. `acceptance-failure.json` also records the ids of the
+  changed digest groups (`changedDigestGroups`), without digests or paths
+  ([#131](https://github.com/plagor44-ux/pi-session-mcp/issues/131)).
+
+## 0.11.4 — 2026-10-25
+
+Patch release for the Sprint 8 pilot defects
+[#125](https://github.com/plagor44-ux/pi-session-mcp/issues/125),
+[#126](https://github.com/plagor44-ux/pi-session-mcp/issues/126) and
+[#127](https://github.com/plagor44-ux/pi-session-mcp/issues/127). `npm audit`
+still reports `undici` 8.10.2, pinned by Pi SDK 1.4.0
+([#120](https://github.com/plagor44-ux/pi-session-mcp/issues/120)); this
+release ships with that finding by maintainer decision.
+
+- Fixed: `setup --verify` and `setup --writer <name> --verify` killed the
+  launched server with SIGKILL 100 ms after stdin EOF and SIGTERM. A server
+  that needed longer to shut down its registry and close its event spool was
+  killed first and could leave a stale `inst-*` directory under
+  `$XDG_RUNTIME_DIR/pi-session-mcp/events` or the writer's spool directory.
+  Both launchers now wait for the server to exit for up to 2 s before SIGKILL,
+  and the verifier allows up to 5 s (`min(timeout, 5 s)`, after the MCP
+  exchange ends) for stopping the server. A server that exits sooner is not waited for
+  ([#125](https://github.com/plagor44-ux/pi-session-mcp/issues/125)). Also
+  gave the multi-session acceptance test's temporary-root cleanup an explicit
+  120 s hook timeout, which it exceeded on macOS CI, and the bulk spool-cleanup
+  test a 60 s timeout. No MCP contract change.
+- Fixed: the first acceptance of every newly provisioned writer failed with
+  `acceptance_harness_failed` (`digests.preexisting_changed`) when event
+  delivery was on, and a repeated `--apply` passed. The writer's spool directory
+  was created at its first launch, which is the acceptance harness's own
+  launch, so the harness saw a new entry in the writer root. Provisioning now
+  creates the directory (0700) when delivery is on. This is the cause behind
+  [#121](https://github.com/plagor44-ux/pi-session-mcp/issues/121); writers
+  provisioned by an earlier release keep needing one repeated `--apply`
+  ([#126](https://github.com/plagor44-ux/pi-session-mcp/issues/126)).
+- Fixed: with Claude Code 2.1.310, setup reported `client_unsupported` for the
+  second and every further writer of a repository, because `claude mcp get`
+  now appends `Did you mean "<name>"? Run \`claude mcp list\` to see all.` to
+  the absent message when a similar server is configured. The same message made
+  `--remove` of one writer fail with `post_remove_mismatch` while a sibling
+  writer stayed registered. Both Claude Code adapters accept this suffix with
+  any quoted suggestion of up to 256 characters without quotes or line breaks
+  (Claude also suggests plugin servers and connectors); any other text stays
+  unsupported. Added the Claude Code 2.1.310 client contract fixture
+  ([#127](https://github.com/plagor44-ux/pi-session-mcp/issues/127)).
+
+## 0.11.3 — 2026-10-25
+
+Patch release for [#118](https://github.com/plagor44-ux/pi-session-mcp/issues/118) and
+[#121](https://github.com/plagor44-ux/pi-session-mcp/issues/121). `npm audit`
+still reports `undici` 8.10.2, pinned by Pi SDK 1.4.0
+([#120](https://github.com/plagor44-ux/pi-session-mcp/issues/120)); this
+release ships with that finding by maintainer decision.
+
+- Fixed: a failed writer acceptance ended as one undiagnosable
+  `writer_acceptance_failed`. It now returns `writer_state_invalid`,
+  `writer_state_unreadable`, `podman_unavailable`, `acceptance_harness_failed` (including a harness that
+  exits without writing its report) or `acceptance_fingerprint_changed`, and
+  writes a path-free `acceptance-failure.json` into the writer's state
+  directory, removed by the next successful acceptance. The setup report codes
+  changed; `writer_acceptance_failed` remains only for unexpected errors
+  ([#121](https://github.com/plagor44-ux/pi-session-mcp/issues/121)). No MCP
+  contract change.
+- Fixed: on Linux the setup fence's process table counted a zombie
+  thread-group leader as gone while other threads of its process still ran and
+  held its file descriptors, including the setup lock. A zombie group member
+  now counts as gone only when `/proc/<pid>/stat` reports one thread; more
+  threads count as alive, and an unreadable thread count keeps the fence
+  ([#118](https://github.com/plagor44-ux/pi-session-mcp/issues/118)). The
+  handling of processes that exit during a scan (#109) and the macOS path are
+  unchanged. No MCP contract change.
+- Security: `zod` 4.6.5 → 4.6.7 (direct pin, production install path;
+  GHSA-mrhx-c7xc-m3w5). In the lockfile only, development path: `fast-uri`
+  3.1.8 → 3.1.9 (via MCP Inspector's `ajv`; GHSA-w74x-v6f9-j3xg,
+  GHSA-xhq7-xmqj-769h, GHSA-wjr9-j795-jxcr, GHSA-333x-w4r6-6crp) and the
+  Inspector's `undici` 8.11.2 → 8.12.3. Still open: `undici` 8.10.2 in the
+  production path, pinned exactly by Pi SDK 1.4.0 (GHSA-4qv8-2p9j-2685,
+  GHSA-f72v-6w45-q472, GHSA-xjj6-f33q-929c), so `npm audit` still reports it.
+- Documentation: Pi's own MCP client (Pi 1.2 and later: `pi mcp add`,
+  `~/.pi/agent/mcp.json`, the built-in `mcp` extension) is never loaded in
+  embedded sessions. A server registered with it is invisible to workers and
+  must be granted through `mcpServers`
+  ([#115](https://github.com/plagor44-ux/pi-session-mcp/issues/115)). A new
+  SDK contract test makes sure that no `mcp.json` starts a server in a session.
+
+## 0.11.2 — 2026-10-22
+
+Patch release for [#109](https://github.com/plagor44-ux/pi-session-mcp/issues/109) and
+[#117](https://github.com/plagor44-ux/pi-session-mcp/issues/117).
+
+- Changed: Pi SDK `@earendil-works/pi-coding-agent` 1.4.0, together with its
+  family packages `pi-ai`, `pi-mcp`, `pi-tui`, `pi-codemode`, `pi-agent-core`
+  and `pi-telemetry`, all exactly pinned at 1.4.0
+  ([#117](https://github.com/plagor44-ux/pi-session-mcp/issues/117)). No MCP
+  contract change. The SDK's reserved MCP tool names and stop reasons are
+  unchanged. Upstream changes that operators may notice:
+  - The `grep` tool runs `rg --no-config` and ignores `RIPGREP_CONFIG_PATH`.
+  - Provider attribution headers come from pi-ai's client identity, so an
+    extension's `before_provider_headers` handler no longer sees the
+    OpenRouter, NVIDIA NIM and OpenCode attribution headers.
+  - Default models changed for GitHub Copilot (`gpt-6.1-sol`), NVIDIA and
+    Xiaomi. The `openai-codex` provider no longer offers `gpt-5.5` and
+    `gpt-5.3-codex-spark`.
+  - Compaction summaries use the model's output limit. A session now recovers
+    after a response cut off at the output limit, and automatic retry covers
+    more transient gateway errors.
+- Fixed: on Linux, a mutating `setup` run could fail at random with
+  `ownership_lock_unavailable` while other processes exited
+  ([#109](https://github.com/plagor44-ux/pi-session-mcp/issues/109)). The
+  process-table scan behind the setup fence treated a process that vanished
+  during the scan as indeterminate. Listing `/proc` with file types made Node
+  `lstat` an entry whose type procfs did not report, which happens for a
+  process that exits during the listing, and that `lstat` threw `ENOENT`.
+  Reading `/proc/<pid>/stat` of a process that is being reaped returns
+  `ESRCH` or process group `-1`. The guardian then refused to start, and a
+  cleanup loop could report an indeterminate state. Such processes now count
+  as gone, as a vanished `/proc` entry already did; a group of `-1` is read
+  once more and counts as gone only if the process has vanished by then. Any
+  other read or parse failure still makes the scan indeterminate and keeps the
+  fence.
+
+## 0.11.1 — 2026-10-22
+
+Patch release for [#113](https://github.com/plagor44-ux/pi-session-mcp/issues/113).
+
+- Fixed: with `events.delivery: "spool"`, 0.11.0 refused to start
+  (`event_spool_unavailable`) when the server's environment had neither
+  `PI_SESSION_MCP_EVENTS_DIR` nor an absolute `XDG_RUNTIME_DIR`. Codex passes
+  only `HOME`, `LANG`, `LOGNAME`, `PATH`, `SHELL` and `USER` to stdio MCP
+  servers, so a configuration shared with a Codex registration broke
+  pi-session-mcp in every new Codex session. The server now starts with
+  delivery inactive: `pi_capabilities_get` reports `events.delivery: "off"`,
+  and stderr carries one `event_delivery_inactive` warning with code
+  `event_runtime_dir_missing`. A relative `PI_SESSION_MCP_EVENTS_DIR` or an
+  unsafe spool root still fails startup with `event_spool_unavailable`
+  ([ADR 0011 amendment](docs/adr/0011-turn-events-and-controller-wake.md#amendment-2026-10-22-inactive-delivery-without-a-runtime-directory)).
+- Fixed: `setup --verify` reported `mcp_unsupported` for every target when
+  delivery was enabled, because its direct MCP check started the server with
+  `PI_SESSION_MCP_CONFIG` only. It now also passes the caller's
+  `XDG_RUNTIME_DIR`.
+- Changed: Doctor's `event_spool_root` warning says that delivery stays
+  inactive without a runtime directory.
+- Operators of 0.11.0: leave `events` unset in a configuration that a Codex
+  registration uses, or upgrade.
+
+## 0.11.0 — 2026-10-22
+
+Minor release under ADR 0003 for
+[ADR 0011](docs/adr/0011-turn-events-and-controller-wake.md) (#108, #110):
+`pi_capabilities_get` gains `events`.
+
+- Security, development dependencies only (nothing in the production install
+  path; `npm audit` and `npm audit --omit=dev` report 0 vulnerabilities):
+  - `@modelcontextprotocol/inspector` 2.10.1 → 2.11.0, which pins the MCP SDK at
+    2.3.1 like this package, so the nested `@modelcontextprotocol/client` and
+    `server` 2.2.0 copies are gone (GHSA-6prh-2h8m-c8cw, GHSA-jm63-cq47-j5jp,
+    GHSA-46jr-4wx8-v453, GHSA-rvq5-wwqv-78pq).
+  - Lockfile only: `hono` 4.13.7 → 4.13.13 (GHSA-5r4p-p66f-jhc7) and `vite`
+    8.3.0 → 8.3.5 (GHSA-9jrq-w75r-8gcw and the bundled `launch-editor`
+    advisories), with their `@rolldown`, `@napi-rs` and `@oxc-project` builds.
+
+- Added: opt-in turn events for a Claude Code controller wake. The optional
+  top-level server configuration field `events: { "delivery": "spool" | "off" }`
+  (`off` is the default; any other shape fails startup with
+  `invalid_event_delivery`). With `spool`, the registry's terminal transition
+  writes one content-free event file per turn (identifiers, state, time) into a
+  private spool below `$XDG_RUNTIME_DIR/pi-session-mcp/events/`, removed at
+  shutdown. An unusable
+  spool root stops startup with `event_spool_unavailable`; a later write failure
+  is one sanitized `event_spool_write_failed` diagnostic on stderr.
+- Added: the `pi-session-mcp-wake` executable, a Claude Code `PostToolUse`
+  `asyncRewake` hook. It waits for the event of a running turn, claims it exactly
+  once and wakes the controller with one line; after its wait budget (30 minutes)
+  it wakes so that the controller reads once and re-arms. At most one waiter runs
+  per turn: a re-arming read of a still running turn does not start a second
+  wait. A turn ended by `close` (the session is gone) does not wake. A waiter
+  whose namespace shows no spool directory within a short grace period (2 s)
+  exits quietly. If the runtime directory is full (`ENOSPC`, `EDQUOT`), claims
+  and waiter locks cannot be written and the waiter falls back to the budget
+  wake.
+- Added: `setup --apply` installs, `--verify` checks and `--remove` /
+  `--rollback` remove the hook entry in the settings file of the Claude Code
+  target's scope, under the existing dry-run, ownership and divergence rules
+  (`hook_*` and `settings_*` finding codes, see the
+  [client setup reference](docs/client-setup.md#wake-hook)). With delivery off
+  and no entry of its own, and for Codex targets, setup reports no hook finding,
+  so its report keeps the 0.10 shape; Codex controllers keep polling.
+- Added: container writers with delivery enabled get one dedicated spool mount
+  at `/pi/events`. The spool lives on disk in the writer's own state directory
+  (`~/.local/state/pi-session-mcp/writers/<name>/events/`), not on the runtime
+  tmpfs. Each launch creates and checks it, resets a mode the worker changed and
+  prunes it (everything that is not an instance directory, and entries older than
+  24 hours inside instance directories); `events_directory_unavailable` refuses
+  the launch. A crashed instance directory can survive until a later launch prunes
+  it, after 24 hours at the earliest. Acceptance binds delivery when enabled, and changing
+  delivery on an existing writer reports `writer_settings_changed` (remove and
+  add the writer). Amends ADR 0008.
+- Added: a server keeps only the newest 256 event files of its spool instance
+  and recreates its instance directory once if a launch pruned it.
+- Added: Doctor check `event_spool_root` (only when delivery is enabled) and a
+  section "Event delivery" in the controller skill `pi-session-orchestration`:
+  with `events.delivery` `spool`, wait for the wake instead of polling.
+- Changed: `pi_capabilities_get` gains `events: { delivery: "spool" | "off" }`.
+  This is a public contract change, hence a minor release under
+  [ADR 0003](docs/adr/0003-post-mvp-maintenance.md#versioning). The eight tools
+  and their other fields are unchanged.
+- Security: events are wake triggers only and carry no prompt, answer, path or
+  error text. A worker can write to its own writer's spool mount, so it can
+  forge, delete or flood events there; the effect is a spurious or missing wake
+  inside that namespace (a missing wake is replaced by the budget wake after up
+  to 30 minutes, on which the controller reads once), never a changed
+  result, since the controller always reads `pi_turn_get`. The hook validates
+  events strictly, bounds its scans and follows no link, and its claims live
+  outside every writer mount. The mount gives the worker no other host access.
+  See the [threat model](docs/threat-model.md).
+- Limits: Linux only (on other platforms the hook exits without a wake and the
+  controller polls); Claude Code only, in interactive or stream-json sessions (one-shot
+  `claude -p` blocks until the hook ends); Codex keeps polling. Claude Code may
+  need a restart or a `/hooks` review to load a new hook, and managed settings
+  can disable hooks. The setup hook path must be free of shell metacharacters
+  (`hook_path_unsafe`). No token or cost saving is claimed.
+- Evaluation (#104): a provider-free ledger, completion-event bridge and
+  Claude Code rewake prototype under `eval/bridge/` (not shipped), its
+  [report](docs/evaluation/ledger-event-bridge-2026-10-21/README.md) (including
+  two operator-approved real-model pairs) and
+  [ADR 0011](docs/adr/0011-turn-events-and-controller-wake.md) (accepted
+  2026-10-21, items 1–3, with an ADR 0008 amendment), implemented in #108 as described
+  above.
+
+## 0.10.0 — 2026-10-19
+
+- Added: individual `grantedExtensionTools` on read-only profiles with
+  extensions, decided in [ADR 0010](docs/adr/0010-read-only-extension-tools.md),
+  amending ADR 0006. Active tools include exactly these grants alongside the
+  read-only built-ins and granted MCP tools. A grant must be registered at load
+  and active and declared to the model at admission, or start fails closed with
+  `extension_tool_missing` (`needs_operator`). Capabilities expose the configured
+  grants; setup verify validates them. This is a public contract change for minor
+  release **0.10.0** under [ADR 0003](docs/adr/0003-post-mvp-maintenance.md#versioning).
+  Grants are operator trust decisions: third-party tools may write, and workspace
+  modes `container` and `read-only` do not restrict them. Lazy registration in
+  `session_start` or later is unsupported.
+
+## 0.9.1 — 2026-10-19
+
+- Changed: Pi SDK `@earendil-works/pi-coding-agent` from `1.2.0` to `1.3.0`,
+  together with its family packages `pi-ai`, `pi-mcp`, `pi-tui`,
+  `pi-codemode`, `pi-agent-core` and `pi-telemetry`, all at `1.3.0`. The public
+  MCP contract is unchanged. The SDK's stop reasons, its `AssistantMessage`
+  type and its reserved MCP tool names (`isMcpToolName`) are unchanged, and the
+  SDK now pins its own family packages exactly. Operator note from upstream:
+  a `models.json` override of the `kimi-coding` base URL must now include
+  `/v1`. Upstream also retries more gateway errors automatically and rejects
+  tool calls with malformed JSON arguments instead of running them partially.
+
+## 0.9.0 — 2026-10-19
+
+- Added: [per-repository execution modes](docs/execution-modes.md), decided in
+  [ADR 0009](docs/adr/0009-execution-modes.md) as a minor release because the
+  public MCP contract changes. A separate `execution-modes.json` records acknowledged `host`,
+  `container` or `read-only`; missing entries remain `unset` with compatible
+  host behavior. Capabilities workspace entries include `mode`; coding starts
+  on container/read-only aliases fail with `workspace_mode_forbids_coding`.
+  Invalid modes fail startup with `invalid_execution_modes`. Setup `--repo`
+  plans by default and writes only with `--apply`; Doctor reports unset modes,
+  accepted host writes and unavailable rootless Podman. Controllers must restart
+  after changes.
+- Added: Plan B automated Linux rootless-Podman writers: separate full clones,
+  generated wrappers, explicit isolation control and contained acceptance,
+  readiness/refusal servers, registration, collect/reset/recreate/remove/verify
+  and controller `--finish`. Collected refs remain untrusted until reviewed.
+  Each writer defaults to `boundary-read-only`; coding requires an explicit
+  profile. Credential checks run every 60 seconds, with host OAuth warmup only
+  within 2 minutes of expiry, then a boundary copy. Provider credentials remain
+  in the boundary and pasta networking is not limited. The controller skill
+  teaches finish before reuse; operator docs cover migration and selecting
+  the writer toolchain cache with `--cache none|go`. No new live acceptance is claimed.
+
+- Added: Doctor warning `workspace_gitfile` when a configured workspace has a
+  `.git` gitfile (`gitdir:` pointer) and at least one execution profile uses the
+  `coding` permission profile. A gitfile can mean a linked worktree, a submodule
+  or a separate Git directory, so hooks and config may be shared with another
+  repository. Advice only: Doctor never follows the pointer or runs Git, the
+  remediation recommends a separate full clone, exit status rules are unchanged.
+  Issue #81.
+- Changed: the `pi-session-orchestration` controller skill records a terminal
+  turn (`completed`, `failed`, `aborted`) once and does not fetch it again in
+  normal operation, gives a concrete polling cadence (first poll about 10 s
+  after the prompt, then every 15–30 s, running tasks only) with fixed task and
+  cleanup budgets, and notes as a Codex route observation that every controller
+  tool call re-sent the accumulated context. The `pi_session_start` error
+  classification moved to `references/start-errors.md` in the skill tree, read
+  only after a start failure; a start error is never retried before it is
+  classified. Issue #86.
+- Changed: the worker skills `pi-session-implementation` and
+  `pi-session-review` ask for concise final reports without full diffs or logs
+  by default, never drop failed checks, blockers or risks, and state what
+  `truncated` does and does not mean. Issue #87.
+- Changed: the descriptions of `pi_capabilities_get`, `pi_session_prompt`,
+  `pi_session_close` and `pi_turn_get` carry short behavior hints. No tool,
+  argument, result, state, annotation or error changed. Issue #88.
+- Changed: the input JSON Schemas of the six `sessionId`/`turnId` fields keep
+  `format: "uuid"` but no longer repeat the long `pattern`; the server still
+  validates with the same rule, and accepted values and error responses are
+  byte-identical (156 compared responses). `tools/list` shrinks by 1,074 bytes
+  against the #88 state; net against 0.8.3 it is 819 bytes smaller (19,962 to
+  19,143 bytes), because #88 adds 255 bytes.
+  Output schemas are unchanged. Codex 0.162.1 already drops `pattern` from the
+  projected schemas, so its model-visible tool bytes do not change. Issue #90.
+
 ## 0.8.3 — 2026-10-15
 
 - Fixed: a fresh `npm install -g pi-session-mcp@0.8.2` produced a server that

package/README.md

@@ -30,14 +30,16 @@ It is not the right tool when:
 
 ## Status
 
-The package version is **0.8.3**.
+The package version is **0.12.0**.
+
+[Per-repository execution modes](docs/execution-modes.md) make host writes explicit and block coding on read-only aliases. On container workspaces, the one host `pi-session-mcp` registration leases a rootless-Podman writer per coding session on Linux; no per-writer registrations or tool prefixes are needed ([ADR 0012](docs/adr/0012-leased-writer-pool.md)). Setup provisions, accepts, collects and resets the pool. Starts normally use the workspace default base; fix rounds can pass a short branch `base`. Start/get report `writer` and `base` for collection, and capabilities report configured `writers` and `defaultBase`. Reset, finish and recreate need no reconnect; finish returns the writer to the default base. See the [container upgrade runbook](docs/installation.md#container-writers).
 
 - **Pre-1.0.** The public tool contract is stable within a minor line: a change to tools, fields, states or error codes needs a new minor release.
 - **Linux and macOS**, Node.js 22.19.0 or newer. macOS is tested in CI on macOS 15 and 26 on Apple silicon; Intel Macs run the same code but are untested. Setup acceptance on a real Mac is recorded for Claude Code only; Codex is still pending. See [Acceptance](docs/acceptance.md#status). On other platforms `setup` refuses with `platform_unsupported`.
 - **Clients:** Codex CLI and Claude Code. The `setup` command does not pin client versions: it accepts a client whose public `mcp` command output matches the expected contract and fails closed otherwise.
 - **Out of scope by design:** HTTP, a web UI, persistence, resume, remote access and multi-user behavior. One trusted local MCP peer talks to one server process.
 - **Not a sandbox.** A `coding` profile restricts the Pi tools that a session may use. It does not isolate the process from the operating system.
-- **Acceptance.** Every release passes the provider-free checks. The live two-client acceptance has not yet been repeated on a build with Pi SDK `1.x`; see [Acceptance](docs/acceptance.md).
+- **Acceptance.** Every release passes the provider-free checks. The last live two-client acceptance (Level 3) ran on Pi SDK `1.1.0` with one provider pair on Linux and has not been repeated on later SDK pins; see [Acceptance](docs/acceptance.md).
 
 ## How it works
 
@@ -114,6 +116,7 @@ The [installation guide](docs/installation.md) also covers installing from a rel
 - An execution profile binds a permission profile (`read-only` or `coding`), a provider, a model and a thinking level. Exactly one profile is the default, and it must be `read-only`.
 - A profile can grant individual tools of local stdio MCP servers to its sessions; see [External MCP tools in embedded sessions](docs/session-mcp.md).
 - An optional top-level `skillCatalog` maps skill aliases to `builtin:<name>` (a skill of the package or of your override directory) or to a `SKILL.md` file, and a profile's optional `skills` selects aliases from it. A profile without `skills` gets no skills. See [Pi skills](docs/skills.md).
+- An optional top-level `"events": { "delivery": "spool" }` turns on content-free turn events, so that a Claude Code hook can wake the controller when a turn ends instead of polling. It is off by default and changes nothing for Codex. See [Wake the controller](docs/installation.md#wake-the-controller-claude-code).
 - The server reads the file once at startup. Start a new client session after changing it.
 
 ## Run it by hand
@@ -169,10 +172,13 @@ Contract and design:
 - [ADR 0003: no new feature phase after the MVP](docs/adr/0003-post-mvp-maintenance.md)
 - [ADR 0004: setup accepts clients by contract, not by version](docs/adr/0004-client-contract-not-version.md)
 - [ADR 0007: execution profiles select Pi skills from an operator catalog](docs/adr/0007-profile-skill-selection.md)
+- [ADR 0011: turn events and controller wake](docs/adr/0011-turn-events-and-controller-wake.md)
+- [ADR 0012: one registration with a leased writer pool](docs/adr/0012-leased-writer-pool.md)
 
 Maintain:
 
 - [Acceptance](docs/acceptance.md)
+- [Synthetic profile evaluation](docs/evaluation/README.md): current results, provider-free harness and gated live plan
 - [Maintenance roadmap](docs/roadmap.md)
 - [Post-0.8.1 audit and backlog snapshot](docs/reviews/2026-10-13-post-0.8.1-audit.md)
 - [Releasing](docs/releasing.md)

package/dist/capabilities.d.ts

@@ -1,7 +1,8 @@
 import type { ConfigurationMetadata } from "./config.js";
+import type { WorkspaceModeEntry } from "./execution-modes.js";
 import type { ConfiguredExecutionProfile } from "./execution-profile.js";
 /** Pure projection of the snapshot captured at load time; never reads the configuration file. */
-export declare function projectCapabilities(workspaces: ReadonlyMap<string, string>, executionProfiles: ReadonlyMap<string, ConfiguredExecutionProfile>, configuration: ConfigurationMetadata): {
+export declare function projectCapabilities(workspaces: ReadonlyMap<string, string>, executionProfiles: ReadonlyMap<string, ConfiguredExecutionProfile>, configuration: ConfigurationMetadata, workspaceModes?: ReadonlyMap<string, WorkspaceModeEntry>, eventDelivery?: "spool" | "off"): {
     ok: true;
     server: {
         name: string;
@@ -11,8 +12,14 @@ export declare function projectCapabilities(workspaces: ReadonlyMap<string, stri
         fingerprint: `sha256:${string}`;
         reloadPolicy: "restart-required";
     };
+    events: {
+        delivery: "off" | "spool";
+    };
     workspaces: {
         alias: string;
+        mode: import("./execution-modes.js").WorkspaceMode;
+        writers?: number;
+        defaultBase?: string | null;
     }[];
     executionProfiles: {
         alias: string;
@@ -22,6 +29,7 @@ export declare function projectCapabilities(workspaces: ReadonlyMap<string, stri
         model: string;
         thinkingLevel: import("./execution-profile.js").ThinkingLevel;
         extensions: string[];
+        grantedExtensionTools: string[];
         skills: string[];
     }[];
 };

package/dist/capabilities.js

@@ -1,7 +1,7 @@
 import packageMetadata from "../package.json" with { type: "json" };
 const compareAliases = (left, right) => left < right ? -1 : left > right ? 1 : 0;
 /** Pure projection of the snapshot captured at load time; never reads the configuration file. */
-export function projectCapabilities(workspaces, executionProfiles, configuration) {
+export function projectCapabilities(workspaces, executionProfiles, configuration, workspaceModes = new Map(), eventDelivery = "off") {
     return {
         ok: true,
         server: { name: packageMetadata.name, version: packageMetadata.version },
@@ -9,12 +9,16 @@ export function projectCapabilities(workspaces, executionProfiles, configuration
             fingerprint: configuration.fingerprint,
             reloadPolicy: configuration.reloadPolicy,
         },
+        events: { delivery: eventDelivery },
         workspaces: [...workspaces.keys()]
             .sort(compareAliases)
-            .map((alias) => ({ alias })),
+            .map((alias) => {
+            const entry = workspaceModes.get(alias);
+            return { alias, mode: entry?.mode ?? "unset", ...(entry?.mode === "container" && entry.container ? { writers: entry.container.writers, defaultBase: entry.container.base ?? null } : {}) };
+        }),
         executionProfiles: [...executionProfiles.values()]
             .sort((left, right) => compareAliases(left.alias, right.alias))
-            .map(({ alias, default: isDefault, permissionProfile, provider, model, thinkingLevel, extensions, skills }) => ({
+            .map(({ alias, default: isDefault, permissionProfile, provider, model, thinkingLevel, extensions, grantedExtensionTools, skills }) => ({
             alias,
             default: isDefault,
             permissionProfile,
@@ -22,6 +26,7 @@ export function projectCapabilities(workspaces, executionProfiles, configuration
             model,
             thinkingLevel,
             extensions: (extensions ?? []).map((extension) => extension.spec),
+            grantedExtensionTools: [...(grantedExtensionTools ?? [])],
             skills: (skills ?? []).map((skill) => skill.alias),
         })),
     };