pi-session-mcp 0.8.3 → 0.12.0

package/docs/pi-extensions-design.md

@@ -39,7 +39,34 @@ Success means:
 - Installing or updating extensions. Pi owns that (`pi update --extensions`).
 - Version ranges or "latest". A version is pinned exactly.
 - Pi's built-in extensions (`mcp`, `codemode`, `tool-search`, `llama.cpp`).
-  pi-session-mcp keeps its own `mcpServers` bridge.
+  pi-session-mcp keeps its own `mcpServers` bridge. Re-checked against Pi SDK
+  1.4.0 for [#115](https://github.com/plagor44-ux/pi-session-mcp/issues/115):
+  - **Not loaded.** Only the Pi CLI passes its `builtInExtensions` to the
+    resource loader. `createAgentSession` and `createAgentSessionServices` add
+    them only when `extensionFactories` names them, which this server never
+    does. Both resource loaders also set `noExtensions`.
+  - **Regression guard.** `test/sdk-extension-contract.test.ts` places a
+    `mcp.json` in the global agent directory (`PI_CODING_AGENT_DIR`), in the
+    workspace and in `.pi/`. It checks that a session, including its
+    `session_start`, starts none of these servers. With the built-ins
+    injected, the test fails.
+  - **Why the own bridge stays.**
+    - Pi's client discovers servers from files: `<agent dir>/mcp.json`, which
+      `pi mcp add` writes, and, for trusted projects, `.pi/mcp.json`.
+      Config values may run commands (`!cmd`). HTTP servers can carry OAuth or
+      a provider token (`auth.provider`).
+    - Its `exposure` and `toolExposure` settings control visibility to the
+      model, not authorization. A `--tools` allowlist without an `mcp__` entry
+      keeps MCP tools outside the allowlist.
+    - The bridge, in contrast, connects only operator-configured local stdio
+      servers with absolute commands and an `envFrom` allowlist. It grants
+      named tools per profile, and in `read-only` profiles only those the
+      operator marked `readOnly`. Startup, calls and shutdown are bounded.
+  - **Grants for `mcp__` names** are not planned. They would require loading
+    the built-in client and the codemode or tool-search machinery around it.
+    The rejection of extension tool names that start with `mcp__` stays.
+  - **Revisit** if the SDK offers, as a root export, a per-session MCP
+    configuration without file discovery and with an exact tool allowlist.
 - Extension CLI flags (for example `--cursor-runtime`) and extension UI. Flags
   keep their defaults; UI calls go to the SDK's no-op UI.
 - Extension slash commands triggered by client prompt text.
@@ -52,7 +79,7 @@ Success means:
 | Capability scope | Full: providers, tools, hooks, system-prompt changes. |
 | Naming and pinning | `npm:<name>@<exact version>`, resolved from Pi's user install; any other installed version fails closed. |
 | Granularity | Per execution profile. |
-| `read-only` profiles | Extensions allowed; the model's tools stay read/grep/find/ls. |
+| `read-only` profiles | Extensions allowed; read/grep/find/ls plus granted MCP tools and individually granted extension tools (ADR 0010). |
 | Integration approach | Pi SDK session lifecycle API (`createAgentSessionServices`, `createAgentSessionFromServices`, `AgentSessionRuntime`). |
 
 ## Current behavior and constraints
@@ -200,8 +227,10 @@ For a profile with `extensions`, `SdkPiSessionAdapter.create` runs:
    failure is `extension_load_failed`.
 8. **Postchecks.** Model, thinking level and active tools. For extension
    sessions no active tool may be outside the composed allowlist, but fewer
-   active tools are allowed: an extension may deactivate tools, as
-   `pi-cursor-sdk` does with its own tool in `session_start`. Sessions without
+   active tools are allowed except for explicitly granted extension tools in
+   read-only profiles: each must be active and declared to the model at admission
+   (ADR 0010). An extension may otherwise deactivate tools, as `pi-cursor-sdk`
+   does with its own tool in `session_start`. Sessions without
    extensions keep the exact-equality check as today.
 
 Step 3, step 6 and step 7 are each bounded by the existing session-creation
@@ -213,11 +242,26 @@ and step 6 leaves no session to dispose.
 
 ### Tools, hooks and prompts
 
-- **`read-only`.** The tool list is `read`, `grep`, `find`, `ls`, exactly as
-  today. Extension tools are registered but inactive. An extension that calls
-  `setActiveTools` cannot activate a tool outside the list; a contract test
-  proves this against the real SDK. If the SDK does not enforce it, the
-  adapter adds its own check before the implementation is accepted.
+- **`read-only`.** Under [ADR 0010](adr/0010-read-only-extension-tools.md),
+  the active tools are `read`, `grep`, `find`, `ls`, the granted MCP tools and
+  exactly the extension tools named in `grantedExtensionTools`. Without grants,
+  extension tools remain inactive. An extension's `setActiveTools` cannot add
+  others. The field is allowed only on read-only profiles with at least one
+  extension: at most 32 unique names satisfying the extension name rule below,
+  with no built-in names. A violation prevents startup with
+  `invalid_execution_profile_config`.
+  Each grant must be registered at extension load, before bind; after bind the
+  existing re-check applies. Each granted tool must also be active and declared
+  to the model at admission, or start fails with `extension_tool_missing`,
+  message `Granted Pi extension tool is not available`, class `needs_operator`.
+  Resolution errors (`extension_not_installed`, `extension_version_mismatch`)
+  take precedence; conflicts are checked first as `extension_tool_conflict`.
+  The SDK activates only declarable tools, so registration alone is insufficient.
+  Several registered `pi-lens` tools were never active in the
+  [evaluation](evaluation/pi-lens-registration-2026-10-19/); granting one fails
+  closed. Lazy registration in `session_start` or later is unsupported.
+  A grant is the operator's trust decision: third-party tools may write, and
+  workspace modes `container` and `read-only` do not restrict them.
 - **`coding`.** The tool list is the built-in coding tools, the granted MCP
   tools, and every tool registered by the profile's extensions. The adapter
   reads the registered tool names from the services' resource loader after
@@ -239,9 +283,12 @@ and step 6 leaves no session to dispose.
   This server's own MCP bridge tools use a single underscore (`mcp_<server>_<tool>`)
   and never collide.
   The check runs after load and again after binding, because a `session_start`
-  handler can register a tool during `bindExtensions`. If the registered tool
-  set then differs from the one the session was created with, the start fails
-  with `extension_tool_conflict`. Tools an extension registers later, during a
+  handler can register a tool during `bindExtensions`. In read-only profiles,
+  the re-check fails on a name conflict (`extension_tool_conflict`) or a missing
+  grant (`extension_tool_missing`); an extra, non-colliding registration stays
+  inactive outside the allowlist. In coding profiles the composed list includes
+  all registered extension tools, so a changed registered set fails with
+  `extension_tool_conflict`. Tools an extension registers later, during a
   turn, are not re-checked; allowlisted extensions are trusted code.
 - **Hook errors while binding.** A hook error reported while binding fails the
   start with `extension_load_failed`. Failure cleanup disposes the session
@@ -319,19 +366,26 @@ cannot be intercepted in Node.js; this is a documented residual risk.
 
 `pi_capabilities_get` adds `extensions` to every execution profile: an array of
 the configured spec strings, empty for profiles without extensions. The field
-is path-free and secret-free. `capabilitiesSchema` and
+is path-free and secret-free. Each profile also has `grantedExtensionTools`
+directly after `extensions`, in configured order, or `[]` when absent. It is
+configuration intent only, not proof of runtime availability; setup verify
+validates it. `capabilitiesSchema` and
 `docs/tool-contracts.md` change accordingly.
 
 ### Doctor
 
-Doctor gains two checks after the workspace checks, one per profile and
+Doctor includes these checks after the workspace checks, one per profile and
 extension, with the subject `<profile>:<package name>`:
 
 - `extension_missing` (error) when the resolver finds no installed package;
 - `extension_version_mismatch` (error) when the installed manifest version
-  differs, or the manifest is unreadable.
+  differs, or the manifest is unreadable;
+- `extension_unpinned` (warning) when Pi's agent `settings.json` lists the
+  configured extension as `npm:<name>` (a string or an object's `source`). Pin
+  it with `pi install npm:<name>@<version>`. Missing, unreadable, or invalid
+  settings are ignored by this advisory check.
 
-Doctor reads manifests only; it never imports extension code. It stays
+Doctor reads manifests and settings only; it never imports extension code. It stays
 offline. `setup --verify` includes Doctor and therefore these checks.
 
 ### Diagnostics
@@ -352,6 +406,7 @@ admitted:
 | `extension_version_mismatch` | Configured Pi extension version is not installed | The installed version differs from the pinned version. |
 | `extension_load_failed` | Configured Pi extension could not be loaded | Invalid manifest, entry outside the package, load or bind error, services diagnostic of type `error`. |
 | `extension_tool_conflict` | Configured Pi extension tools conflict | An extension tool name collides with a built-in, MCP or other extension tool, or is unsafe (see *Name conflicts*). |
+| `extension_tool_missing` | Granted Pi extension tool is not available | A read-only grant is not registered at load, or is not active and declared to the model at admission; class `needs_operator`. |
 
 Existing codes keep their meaning. An extension provider that is unknown after
 loading is `unknown_provider`.

package/docs/releasing.md

@@ -37,13 +37,15 @@ SDK's own packages are pinned directly (see [Update the Pi SDK](#update-the-pi-s
 The Pi SDK is pinned exactly, together with the SDK's internal
 `@earendil-works` packages: `pi-ai`, `pi-mcp`, `pi-tui`, `pi-codemode` and
 `pi-agent-core`, which the SDK declares, and `pi-telemetry`, which `pi-ai`
-declares. They are declared with caret ranges, and npm does not ship our
-lockfile inside the package, so a consumer install resolves those ranges fresh.
-A newer family member can then break the pinned SDK, as in
+declares. Up to `1.2.0` they were declared with caret ranges, and npm does not
+ship our lockfile inside the package, so a consumer install resolved those
+ranges fresh. A newer family member could then break the pinned SDK, as in
 [#78](https://github.com/plagor44-ux/pi-session-mcp/issues/78), where
-`pi-codemode` 1.2.0 removed an export that `pi-coding-agent` 1.1.0 imports. We
-do not import the family members; they are direct, exactly pinned dependencies
-only so that a fresh install resolves the SDK's ranges to the tested versions.
+`pi-codemode` 1.2.0 removed an export that `pi-coding-agent` 1.1.0 imports.
+Since `1.3.0` the SDK pins its family exactly. We do not import the family
+members; they stay direct, exactly pinned dependencies as a guard, so that a
+fresh install resolves to the tested versions even if upstream returns to
+ranges.
 The SDK and the six packages therefore always move together, each to the
 version the canary resolves from the declared ranges.
 
@@ -198,6 +200,8 @@ Steps:
 5. Run the working-tree
    [Level 2 acceptance](acceptance.md#tooling) on the release candidate with
    `scripts/setup-acceptance.mjs`, unless the release notes state its absence.
+   Run it twice: once as is, with delivery off, and once with
+   `--events spool`, with turn-event delivery enabled (#113).
 6. Run the packed-tarball Level 2 acceptance on the same candidate. Pack the
    built package, install the tarball into a fresh prefix and point the harness
    at the installed package:
@@ -213,6 +217,8 @@ Steps:
    rm -rf "$PREFIX" ./pi-session-mcp-<x.y.z>.tgz
    ```
 
+   Repeat the harness run with `--events spool` against the same prefix.
+
    This is the only acceptance-level pre-release check that resolves
    dependencies like a consumer: the working tree and the CI build use our
    lockfile, which a published package does not carry (#78). The CI install

package/docs/reviews/2026-10-18-adr-0008-decision-brief.md

@@ -0,0 +1,53 @@
+# Decision brief: ADR 0008 (#79), state on 2026-10-18
+
+For the maintainer. ADR 0008 stays **Proposed**; this brief prepares the decision
+and changes nothing at runtime. Base main `612fbcb`. First draft by a read-only
+agy/Gemini pass over the repository; every statement below was rechecked against
+the cited files by the integrator.
+
+## What changed since the ADR was written
+
+- **Stale, corrected in this sprint:** the ADR said macOS live acceptance (R10,
+  R11) was open. It passed for Claude Code on 2026-10-16 with release 0.8.3 on a
+  real Mac: Level 1, R10 setup (117/117 checks), R11 smoke and a one-client live
+  check ([Acceptance](../acceptance.md#macos-acceptance-on-real-hardware-2026-10-16)).
+  Not established there: Codex on macOS, the two-client Level 3 cycle, lock
+  contention and interruption.
+- **Still not proven anywhere:** containment on macOS. No VM or container setup
+  was tried or accepted; the R10/R11 evidence covers setup and smoke, not
+  isolation. The live check's diff restriction was model compliance, not an OS
+  boundary.
+- **#81 delivered as advice:** Doctor now warns (`workspace_gitfile`) when a
+  workspace has a `.git` gitfile and a coding profile exists. This is
+  implemented and unreleased; it detects a *possible* linked worktree
+  conservatively and enforces nothing.
+- Unchanged and current: the threats T1–T6, the coding tool grant, the
+  one-process-per-client union boundary and the shared-hook risk of linked
+  worktrees.
+
+## Recommendation as a decision template (option 1, wrapped registration)
+
+| Element | Proposed rule |
+| --- | --- |
+| Boundary | One rootless Podman container (Linux) or separate OS user per **writer**; the host registration stays read-only |
+| Repository | A full clone per writer inside the boundary, never a linked worktree |
+| Git metadata | Hooks and config not writable from inside, or the host never runs Git in the writer's clone |
+| Review | Fetch the writer's branch into the host repository and review it there before anything leaves |
+| Authentication | Only that boundary's credentials; whether Pi's auth refresh needs a writable agent directory is an open question |
+| External MCP / `envFrom` | Explicit allowlist per coding registration; no ambient host secrets (`SSH_AUTH_SOCK`, tokens) |
+| Cursor-backed coding | Off non-disposable repositories until accepted inside the boundary |
+| macOS | Keeps the Sprint 4 interim rules until a VM-based setup (Lima or Podman machine) is accepted |
+
+## Decisions and evidence needed to accept the ADR
+
+1. **Accept option 1 as the direction** (or choose another option). Maintainer decision; no evidence beyond the ADR's comparison.
+2. **Auth refresh policy.** Evidence: a provider-free or approved test inside the boundary showing whether refresh writes Pi's agent directory, and that only the boundary's credentials are present.
+3. **External MCP and `envFrom` allowlist** for coding registrations. Evidence: process inspection showing only allowlisted variables reach children.
+4. **Linux acceptance run** of the synthetic isolated-write test defined in the ADR (`edit`, `write`, `bash`, writes outside the workspace and through symlinks, credential absence, process cleanup). Evidence: a sanitized acceptance record.
+5. **macOS policy.** Decide whether macOS keeps the interim rules open-ended or gets a VM runbook; record the decision in the roadmap.
+6. **A decision date or review point**, because the interim period is open-ended today.
+
+## Out of scope now
+
+No Podman, VM or sandbox build; no move away from the embedded SDK (ADR 0002);
+no runtime or MCP contract change; no session refusal on gitfile workspaces.

package/docs/roadmap.md

@@ -12,8 +12,26 @@ mean they are implemented or that their gates passed.
 
 ## Current state
 
-Updated 2026-10-15. Base main `bdfb95de9a46defa64d2eb382d58d454f97fc8fb`
-(the merge of the 0.8.2 release).
+- 2026-10-28: [ADR 0012](adr/0012-leased-writer-pool.md) was accepted and
+  implemented in #157: one host registration with a leased container writer
+  pool, base-aware allocation and host-spool events. Prepared as minor release
+  0.12.0 together with #151 and #154; no new live acceptance is claimed.
+
+The explicit 2026-10-17 user request adds a bounded development-only
+[token-footprint measurement](sprints/2026-10-17-token-footprint.md), following
+PR #84. It does not change maintenance mode or the isolation priority below.
+Live measurement requires its own current source-bound matrix/route/budget
+approval; historical evaluation approvals do not apply.
+Its [offline results](evaluation/token-footprint-2026-10-17/README.md) record
+80 transport cases, 50 filter cases and ten adverse-report controls. The
+operator-approved [M1 pilot](evaluation/token-footprint-2026-10-17/m1-pilot/README.md)
+passed on 2026-10-18 on its third attempt (attempts 1 and 2 failed on harness
+defects and are preserved); it measured Codex **controller** usage on one route.
+Worker usage and money cost remain unknown. An A/B is proposed, not approved.
+
+Updated 2026-10-18. Base main `612fbcb976d4563ea597e87be56123055b782c1a`
+(the merge of PR #85). Sprint 5 is the
+[maintenance and orchestration sprint](sprints/2026-10-18-s5-maintenance-orchestration.md).
 
 - R21 (this roadmap) was delivered as documentation by
   [#58](https://github.com/plagor44-ux/pi-session-mcp/pull/58), which closed
@@ -55,7 +73,293 @@ Updated 2026-10-15. Base main `bdfb95de9a46defa64d2eb382d58d454f97fc8fb`
   Proposed), with interim operating rules until it is accepted. R12, R15 and
   R17 stay deferred (not met), R18 stays deferred (not determinable), and
   [#74](https://github.com/plagor44-ux/pi-session-mcp/issues/74) is closed as
-  not planned. R10, R11 and R22 stay open.
+  not planned. R10, R11 and R22 stayed open at that point; R10 and R11 were verified on 2026-10-16 (see the table below).
+- Release 0.8.3 was merged in [#80](https://github.com/plagor44-ux/pi-session-mcp/pull/80)
+  and published on 2026-10-15. It fixes #78 with Pi SDK 1.2.0 and exact pins
+  of the SDK's internal packages, and adds the install smoke and the
+  packed-tarball pre-release check. Its published-release acceptance passed on
+  2026-10-16 for the tag and the npm package, and the workstation and server
+  installations were upgraded (see
+  [Acceptance](acceptance.md#v083-post-release-evidence)). Fresh installs of
+  0.6.1 to 0.8.2 do not start.
+- [ADR 0008](adr/0008-coding-profile-isolation.md) for
+  [#79](https://github.com/plagor44-ux/pi-session-mcp/issues/79) was accepted for
+  Linux on 2026-10-18: option 1, wrapped registration in rootless Podman, one
+  boundary per writer. The Linux acceptance passed on 2026-10-18 for one writer
+  ([evidence](evaluation/isolation-acceptance-2026-10-18/README.md)); review point
+  2026-11-15. macOS keeps the interim rules.
+- [ADR 0009](adr/0009-execution-modes.md), accepted 2026-10-18, records
+  [per-repository execution modes](execution-modes.md). Both plans ship as
+  minor release 0.9.0 (Plan A in #98, Plan B in #99). Plan A: separate modes
+  file, host-server enforcement, setup selection and offline Doctor checks.
+  Plan B: automated Linux
+  rootless-Podman provisioning, explicit host control and contained acceptance,
+  collect/reset/recreate/finish, wrappers, refusal server, registration and
+  periodic credential checks with near-expiry host warmup. The
+  [operator runbook](isolation-setup.md) covers migration of the manual writers,
+  including operator-supplied Go images and the `--cache go` selection. New live acceptance and
+  rollout are not claimed; each writer must pass its readiness gates.
+
+### Sprint 8 migration, steps 3 and 4 (2026-10-27)
+
+On the published 0.11.8, without a product change
+([progress](sprints/2026-10-24-s8-writer-migration.md#progress-2026-10-27)):
+
+- Step 3: operator images `node-go` (Go 1.27.3) and `node-python-uv`
+  (Python 3.12.16, uv 0.13.6), built outside this repository, checked under the writer's
+  run flags against real builds of the target repositories.
+- Step 4: go-app runs on four container writers with `--cache go`; the manual
+  writer `go-app-alpha` and the host aliases `go-app-w1`–`go-app-w7` are retired,
+  `go-app-rev` is `read-only`.
+- The server the second machine was upgraded to 0.11.8.
+- New: [#151](https://github.com/plagor44-ux/pi-session-mcp/issues/151), a
+  persistent uv cache for Python writers. Step 5 must also decide on
+  pynode-app's tests that need a local Postgres.
+
+### Sprint 11: orchestration gaps (2026-10-26)
+
+Base main `d93a6d6`, published 0.11.6
+([Sprint 11](sprints/2026-10-26-s11-orchestration-gaps.md)). One branch and
+one pull request, no release:
+
+- [#141](https://github.com/plagor44-ux/pi-session-mcp/issues/141): Doctor
+  reports coding profiles a container writer would refuse (from #139).
+- [#142](https://github.com/plagor44-ux/pi-session-mcp/issues/142): writers
+  refresh the host's OAuth credential ten minutes before expiry, before the
+  SDK's own five-minute window, which failed writer turns.
+- K3 and K9 as evaluation hooks outside the package (D1), K5 in the controller
+  skill, K7 answered by a provider-free probe, K8 closed without a product
+  change.
+- Recorded: the v0.11.6 post-release acceptance and migration step 2
+  (`node-app`, four writers).
+- Decided: D3 no ADR yet; #120 waits for an SDK release.
+- Released afterwards: 0.11.7 (#141, #142, the review stage) on 2026-10-26.
+  Its upgrade on the workstation failed: with two container repositories the
+  repository step's Doctor gate blocked on the other repository's unready
+  writers ([#148](https://github.com/plagor44-ux/pi-session-mcp/issues/148)),
+  and the workstation was rolled back to 0.11.6. 0.11.8 fixed #148 the same
+  day; the workstation was upgraded from 0.11.6 to 0.11.8 and all six writers
+  were accepted again.
+
+### Sprints 9 close-out and 10: orchestration reliability (2026-10-26, shipped in 0.11.6)
+
+Base main `e6fc87c`, published 0.11.5. The operator's orchestration concept of
+2026-10-25 (candidates K1–K11) is assessed against the repository and planned
+in the [Sprint 10 file](sprints/2026-10-26-s10-orchestration-reliability.md).
+Items 1 and 2 are implemented on the consolidated branch and its pull request (status in the Sprint 10 file's progress log); items 3 and 4 are planned:
+
+1. Sprint 9 close-out: #136, #137 and the #135 record.
+2. Sprint 10, controller reliability: a provider-free probe of the worker
+   system prompt (`phase-0-system-prompt-disabled` in `src/sdk-pi-adapter.ts`),
+   a `claude plugin eval` suite for the controller skill (K1), then one skill
+   change for the report contract, the early-stop rule and routing defaults
+   (K2, K4, K6), measured before and after.
+   Items 1 and 2 travel on one branch and one pull request with one patch
+   release, 0.11.6.
+3. Sprint 11: file ledger with a compaction hook and a verification `Stop`
+   gate (K3, K9) after maintainer decision D1, the wake gaps (K8) and a
+   provider-free subagent probe (K7).
+4. In parallel: Sprint 8 migration steps 2–7, one repository at a time.
+
+A review stage with a capped fix loop (K5) runs as process from Sprint 10 on.
+The guided profile setup (K10, #139) and a worker report extension (K11) stay
+proposals; K11 needs an ADR.
+
+### Sprint 9: writer settings drift and override skills (2026-10-25)
+
+Base main `a8f6397`, published 0.11.5. Fixes that make `--repo ... --apply` the
+reliable way to tell whether a writer still matches its configuration before
+more repositories move to container writers:
+
+- [#134](https://github.com/plagor44-ux/pi-session-mcp/issues/134): reconcile
+  and its dry run report `writer_settings_changed` for a kept writer whose
+  settings or coding profiles changed, instead of keeping it silently.
+- [#135](https://github.com/plagor44-ux/pi-session-mcp/issues/135): a container
+  coding profile may select only shipped `builtin:` skills without an operator
+  override, because overrides do not reach the writer.
+- Open for this sprint: [#136](https://github.com/plagor44-ux/pi-session-mcp/issues/136)
+  (reset or finish under a running writer server) and
+  [#137](https://github.com/plagor44-ux/pi-session-mcp/issues/137) (unpinned Pi
+  extensions and the repository step's Doctor gate).
+- #135 stays open after PR #138 although its fail-closed part shipped; the
+  close-out records that and asks decision D4.
+- Proposals, not in this sprint: a guided, interactive setup in the agent
+  harness that works out the execution profiles together with the operator;
+  copying operator overrides into a writer; adopting a changed image while
+  keeping the writer's clone.
+
+### Sprint 8: migration to container writers (2026-10-25)
+
+Base main `19d0d4f`
+([Sprint 8](sprints/2026-10-24-s8-writer-migration.md), tracking
+[#79](https://github.com/plagor44-ux/pi-session-mcp/issues/79)):
+
+- Decided on 2026-10-25: productive coding moves to container writers, repository
+  by repository, with the pilot on pi-session-mcp.
+- Done: [#121](https://github.com/plagor44-ux/pi-session-mcp/issues/121), a
+  failed writer acceptance now names its cause
+  ([#123](https://github.com/plagor44-ux/pi-session-mcp/pull/123)).
+- Prepared as 0.11.3: the #118 and #121 fixes and the `zod` patch. The
+  maintainer decided on 2026-10-25 to release with the open `undici` finding
+  ([#120](https://github.com/plagor44-ux/pi-session-mcp/issues/120)) stated in
+  the release record, so that the writers run on a published version.
+- Released 0.11.3 on 2026-10-25.
+- Pilot started on 2026-10-25 on the workstation: host alias
+  `pi-session-mcp-w1` retired, isolation control passed, mode `container` with
+  two writers. The first `--apply` failed the acceptance of both writers
+  ([#126](https://github.com/plagor44-ux/pi-session-mcp/issues/126), the cause
+  behind #121), the repeated one accepted them. Claude Code 2.1.310 blocked the
+  second writer's Claude Code registration
+  ([#127](https://github.com/plagor44-ux/pi-session-mcp/issues/127)).
+- Prepared as 0.11.4: the #125, #126 and #127 fixes
+  ([#128](https://github.com/plagor44-ux/pi-session-mcp/pull/128)), again with
+  the open `undici` finding by maintainer decision.
+- Released 0.11.4 on 2026-10-25. The upgrade from 0.11.3 exposed two defects:
+  `--repo ... --apply` did not accept the ready writers again
+  ([#130](https://github.com/plagor44-ux/pi-session-mcp/issues/130)), so both
+  were removed and provisioned again, and one acceptance failed because the
+  writer launch refreshed an expired host token inside the harness
+  ([#131](https://github.com/plagor44-ux/pi-session-mcp/issues/131)); a
+  repeated `--apply` accepted it.
+- Prepared as 0.11.5: the #130 and #131 fixes
+  ([#132](https://github.com/plagor44-ux/pi-session-mcp/pull/132)).
+- Released 0.11.5 on 2026-10-25
+  ([#133](https://github.com/plagor44-ux/pi-session-mcp/pull/133)), again with
+  the open `undici` finding by maintainer decision. The workstation upgrade
+  accepted both ready pilot writers in one `--repo ... --apply` without
+  removal. An unpinned Pi package update blocked that step first
+  ([#137](https://github.com/plagor44-ux/pi-session-mcp/issues/137)).
+- Pilot delegation on 2026-10-25: one coding task per writer with
+  `code-deepseek`, each a failing test for a newly found defect
+  ([#134](https://github.com/plagor44-ux/pi-session-mcp/issues/134),
+  [#135](https://github.com/plagor44-ux/pi-session-mcp/issues/135)), verified
+  by the controller, collected and finished. A reset of a writer with a running
+  server cleared that server's credentials
+  ([#136](https://github.com/plagor44-ux/pi-session-mcp/issues/136)).
+- Next: the remaining repositories, after Sprint 9.
+
+### Sprint 7: stabilization and live acceptance (2026-10-24)
+
+Base main `f69c40f`, published 0.11.2
+([Sprint 7](sprints/2026-10-24-s7-stabilization-live-acceptance.md)). A
+maintenance sprint without a contract change or a version bump:
+
+- [#118](https://github.com/plagor44-ux/pi-session-mcp/issues/118): the Linux
+  process table counted a zombie thread-group leader with live threads as gone,
+  so the setup fence could end while those threads still held the lock. Fixed
+  in this sprint's pull request; the issue closes on merge.
+- Planning documents reconciled with the delivered 0.11.x releases.
+- Live acceptance of the candidate `6651a47`
+  ([evidence](evaluation/s7-live-acceptance-2026-10-24/README.md)); a candidate
+  result is not a result for the published 0.11.2:
+  - Level 2 passed.
+  - Level 3: 10 of 10 tasks passed. The gate is not met because `npm audit`
+    fails on `undici`, which Pi SDK 1.4.0 pins
+    ([#120](https://github.com/plagor44-ux/pi-session-mcp/issues/120)).
+  - Wake: setup path, parallel turns, budget wake, abort and close, and the
+    Codex fallback passed. A running CLI session picked up a newly installed
+    hook.
+  - A container writer with delivery passed its delegation, boundary and
+    crafted-event checks; one first-time acceptance failure was not
+    diagnosable ([#121](https://github.com/plagor44-ux/pi-session-mcp/issues/121)).
+- Still open after Sprint 7:
+  - VS Code wake on a candidate build, and hook pickup by a running VS Code
+    session; both need the operator, and the procedure is in the evidence.
+  - A forged event during a real controller turn on a writer.
+  - #120, #121 and #79.
+- Next priority, in this order:
+  1. Decide #120, because without it no release can pass Level 1.
+  2. Merge this fix as a patch candidate.
+  3. Then #121.
+  4. Then the #79 migration decision at the 2026-11-15 review.
+
+### Sprint 6: ledger and event-bridge evaluation (2026-10-21)
+
+Added at the operator's explicit request of 2026-10-21 as a bounded,
+development-only evaluation
+([#104](https://github.com/plagor44-ux/pi-session-mcp/issues/104),
+[Sprint 6](sprints/2026-10-21-s6-ledger-event-bridge.md),
+[report](evaluation/ledger-event-bridge-2026-10-21/README.md)). It does not
+replace the isolation priority under #79. The evaluation itself changed no
+product code; the bridge implementation that followed shipped in 0.11.0 (below).
+
+- Done: inventory of controller ledger, SDK completion semantics, client wake
+  paths and OMO Boulder; a provider-free prototype under `eval/bridge/` (ledger,
+  completion bridge, question broker, Claude Code `asyncRewake` adapter) with 91
+  tests; a client-level probe on Claude Code 2.1.303 with a scripted model
+  (idle stream-json session woken once per event, question round trip,
+  controls; four attempts kept); two independent reviews, findings fixed.
+- Verdict: a lean completion bridge with Claude Code rewake is technically
+  viable. A file ledger and a polling supervisor are not recommended as product
+  features.
+- Done on 2026-10-21 with operator approval: two real-model pairs (L4, case L1)
+  ([live results](evaluation/ledger-event-bridge-2026-10-21/live/README.md)).
+  - The woken controller read once, without polls or sleeps, and acted on a
+    finished turn after about 2 s instead of 10–21 s.
+  - The decision rule was not met: requests 7/8 and 8/8, mixed uncached input
+    and cost. The evaluation recommended deferring ADR 0011.
+- Decided on 2026-10-21: the maintainer accepted
+  [ADR 0011](adr/0011-turn-events-and-controller-wake.md) items 1–3 for
+  controller reaction time, knowingly against that recommendation. It covers
+  opt-in spool delivery, one spool mount per container writer (ADR 0008
+  amendment), a setup-installed Claude Code hook, a capabilities field and a
+  skill section, shipped as minor release 0.11.0.
+- Implemented: [#108](https://github.com/plagor44-ux/pi-session-mcp/issues/108)
+  was implemented to the approved
+  [plan](superpowers/plans/2026-10-21-turn-events-and-controller-wake.md) and
+  merged in [#110](https://github.com/plagor44-ux/pi-session-mcp/pull/110)
+  (Linux only), after several independent review rounds and a provider-free
+  product probe on Claude Code 2.1.306. Released as 0.11.0 on 2026-10-22; the
+  operator confirmed the wake in the interactive Claude Code TUI.
+- Fixed in 0.11.1: [#113](https://github.com/plagor44-ux/pi-session-mcp/issues/113).
+  With delivery enabled, 0.11.0 refused to start without `XDG_RUNTIME_DIR`,
+  which Codex never passes, so a shared configuration broke Codex and setup
+  verification. Delivery now stays inactive there (ADR 0011 amendment).
+- Released as 0.11.2 on 2026-10-22 ([#116](https://github.com/plagor44-ux/pi-session-mcp/pull/116);
+  [post-release evidence](acceptance.md#v0112-post-release-evidence) in
+  [#119](https://github.com/plagor44-ux/pi-session-mcp/pull/119)):
+  - [#109](https://github.com/plagor44-ux/pi-session-mcp/issues/109): processes
+    that exited during a `/proc` scan made the Linux setup fence fail at random
+    with `ownership_lock_unavailable`, in CI and on busy hosts.
+  - [#117](https://github.com/plagor44-ux/pi-session-mcp/issues/117): Pi SDK
+    1.4.0.
+- Decided in [#119](https://github.com/plagor44-ux/pi-session-mcp/pull/119):
+  [#115](https://github.com/plagor44-ux/pi-session-mcp/issues/115). The server
+  keeps its own controlled `mcpServers` bridge and guards against Pi's built-in
+  MCP client.
+- Open operator checks: wake in the VS Code extension, whether a running
+  session loads a newly written hook without a restart or `/hooks` review, and
+  a wrapped container writer with delivery under rootless Podman, including the
+  isolation check of the extra mount; Sprint 7 runs them. The question channel
+  (ADR 0011 item 4) is still undecided; a ledger and a supervisor are not
+  product features.
+  The #79 isolation review point of 2026-11-15 stays.
+- Deferred: Codex wake (no documented path), macOS delivery (no
+  `XDG_RUNTIME_DIR` and no `/proc/self/fd` by default), a supervisor-only
+  detection arm.
+
+### Sprint 5 issue status
+
+Implemented means the code or text exists on the Sprint 5 branch; verified
+means its named checks passed with evidence. The implemented items shipped in
+0.9.0; live acceptance stays as stated per row.
+
+| Issue | Scope | Owner | Depends on | Status |
+| --- | --- | --- | --- | --- |
+| [#79](https://github.com/plagor44-ux/pi-session-mcp/issues/79) | Isolation decision, ADR 0008; execution policy, ADR 0009 | maintainer | — | accepted for Linux; [Linux acceptance](evaluation/isolation-acceptance-2026-10-18/README.md) passed on 2026-10-18 for writers `psm-alpha` and `go-app-alpha` (contained and live), both registered in Claude Code's local scope; Plan A per-repository modes (#98) and Plan B automated container writers with near-expiry credential refresh (#99) ship in 0.9.0; no live rollout or new live writer acceptance claimed yet; remaining host routes/repositories need operator choices, review point 2026-11-15 |
+| [#81](https://github.com/plagor44-ux/pi-session-mcp/issues/81) | Doctor `workspace_gitfile` warning | Sprint 5 | — | implemented; provider-free tests |
+| [#86](https://github.com/plagor44-ux/pi-session-mcp/issues/86) | Orchestration skill: consume once, cadence, start-error reference | Sprint 5 | — | implemented; live effect unmeasured (#93) |
+| [#87](https://github.com/plagor44-ux/pi-session-mcp/issues/87) | Concise worker reports | Sprint 5 | — | implemented; live effect unmeasured; untested by the A/B unless worker skills are selected |
+| [#88](https://github.com/plagor44-ux/pi-session-mcp/issues/88) | Tool-description hints | Sprint 5 | — | implemented; Codex 0.162.1 projection +255 bytes; Claude Code bare route −819 bytes together with #90 |
+| [#89](https://github.com/plagor44-ux/pi-session-mcp/issues/89) | Claude Code projection | Sprint 5 research | — | partial: q1 output schema not observed, q2 one representation, q3 deferral observed on a non-bare route; q4 needs approval |
+| [#90](https://github.com/plagor44-ux/pi-session-mcp/issues/90) | Input schemas without the UUID pattern | Sprint 5 | compatibility proof | implemented after the proof (156 identical responses); no effect on the Codex 0.162.1 projection, which drops `pattern` itself; wire −1,074 bytes |
+| [#91](https://github.com/plagor44-ux/pi-session-mcp/issues/91) | Bounded wait decision | maintainer | — | decided 2026-10-18: no bounded wait; trigger C restated with the cost dimension in ADR 0003 |
+| [#92](https://github.com/plagor44-ux/pi-session-mcp/issues/92) | Worker usage research | Sprint 5 research | — | research note delivered; no contract change |
+| [#93](https://github.com/plagor44-ux/pi-session-mcp/issues/93) | M1 A/B | operator approval | — | A/B done: probe attempt 4 passed after three preserved failures; four pairs all PASS; quality kept, cumulative controller input lower in B in 10 of 12 case-pairs (mostly cached), no consistent uncached difference; #87 untested ([results](evaluation/m1-ab-proposal-2026-10-18/results/README.md)) |
+
+Gates for later sprints: the #79 decision before any isolation work; the #93
+approval before the A/B; the A/B before the final #91 decision; a public
+contract decision before any minor-release work.
 
 ### Sprint 3 task status
 
@@ -66,13 +370,16 @@ Updated 2026-10-15. Base main `bdfb95de9a46defa64d2eb382d58d454f97fc8fb`
 | R05 / R09 ten-task Level 3 cycle | None (acceptance) | verified: accepted, 10 of 10 tasks |
 | R06 new Codex abort run | None (acceptance) | verified |
 | R07 Codex discovery of the setup-installed skill | None (acceptance) | verified |
-| R10 / R11 current macOS Level 2 and smoke | None | blocked: work Mac not reachable; runbook in the Sprint 3 file |
-| R22 ChatGPT project instructions | None (outside this repository) | blocked on an operator action; proposal in the Sprint 2 file |
+| R10 / R11 current macOS Level 2 and smoke | None | verified for Claude Code on 2026-10-16 (release 0.8.3, real Mac) and again on 2026-10-26 (release 0.11.6: Level 2 with and without turn-event delivery, lock contention, interruption, install smoke and a live check with a stdio driver); Codex on macOS, the two-client Level 3 gate, Claude Code as controller of a live run on 0.11.x and Intel Macs not established; see [Acceptance](acceptance.md#macos-acceptance-on-real-hardware-2026-10-26) |
+| R22 ChatGPT project instructions | None (outside this repository) | blocked on an operator action; current proposal in the [Sprint 4 decision](sprints/2026-10-15-s4-decision.md#appendix-proposed-chatgpt-project-instructions-r22) |
 
 Status words: planned, in progress, implemented (code exists), verified (named
 criteria met with evidence), blocked, failed (ran and missed its criteria; kept
-on record). Sprints 1 to 4 are closed; the next investment is the isolation
-decision in [#79](https://github.com/plagor44-ux/pi-session-mcp/issues/79).
+on record). Sprints 1 to 4 are closed; Sprint 5 is a maintenance sprint; the next
+investment remains isolation under
+[#79](https://github.com/plagor44-ux/pi-session-mcp/issues/79), now decided in
+ADRs 0008 and 0009; both plans ship as 0.9.0. Operator migration and live
+writer acceptance remain separate from the release.
 
 ## Sprints and exit gates
 
@@ -126,6 +433,10 @@ in-memory state and one trusted local peer.
 | --- | --- |
 | OS isolation | Trigger fired on 2026-10-15 (coding profiles wrote on non-disposable repositories); decision in [#79](https://github.com/plagor44-ux/pi-session-mcp/issues/79) and ADR 0008, interim rules in the [Sprint 4 decision](sprints/2026-10-15-s4-decision.md#interim-operating-rules); profiles/skills are not an OS sandbox |
 | pi_turn_wait | Measured high polling cost per turn with pauses or tool/approval cost; 5–7 polls per invocation is insufficient evidence |
+| Question channel for worker questions (ADR 0011 item 4, undecided) | Demonstrated demand, its own decision, contract tests and a minor release |
+| Worker result channel or report extension (K11) | Sprint 10 shows that the report contract in the skills is not enough; an ADR on either an extension allowance in the writer boundary or a result field in the MCP contract, and a minor release |
+| `Stop` gate on open sessions, MCP elicitation for worker questions, pi-goal-x, pi-subagents, the `subagent`, `structured-output.ts` and `git-checkpoint.ts` examples | Not planned: each collides with the wake, reaches the human instead of the model, continues outside the turn or loses its result (operator concept of 2026-10-25, consistent with #91 and ADR 0011) |
+| pi-lens on coding profiles | Not planned: no benefit in two ablation waves, 1.47 times the cost |
 | Persistence/resume | Actual loss of useful work on restart |
 | HTTP/remote/mobile | Concrete need existing SSH/remote development cannot meet; separate ADR/security decision |
 | Finer turn_failed | Closed public final SDK cause discriminator after retry/compaction, not error-text guessing |
@@ -134,7 +445,7 @@ in-memory state and one trusted local peer.
 | Former pi-control #31/#32 | Closed as not_planned; no automatic migration/reopening |
 | Former release gates/#11–#14 | Historical; bind current acceptance to the current build |
 
-0.8.3 is a patch release only if the MCP contract remains unchanged and its
-gates pass. Apply the current [release procedure](releasing.md): version and
+A patch release ships only if the MCP contract remains unchanged and its gates
+pass. Apply the current [release procedure](releasing.md): version and
 pre-release acceptance travel in the change PR. Merge, tagging and
 publication remain maintainer decisions. No release is authorized by this plan.

package/docs/session-mcp.md

@@ -10,7 +10,11 @@ before the session is returned.
 Global and project extensions are never auto-discovered; only the extensions
 that a profile allowlists load (see [Pi extensions](installation.md#pi-extensions)).
 Installing `pi-mcp-adapter` globally is neither required nor sufficient for this
-integration. Skills are likewise never auto-discovered; a profile gets only the
+integration. The same holds for Pi's own MCP client (Pi 1.2 and later: `pi mcp
+add`, `~/.pi/agent/mcp.json`, the built-in `mcp` extension). It belongs to the
+Pi CLI; embedded sessions never load it. A server added with `pi mcp add` or
+listed in a project `.pi/mcp.json` is therefore invisible to Pi Session MCP
+workers. Grant it through `mcpServers` instead. Skills are likewise never auto-discovered; a profile gets only the
 skills it selects from the operator's catalog (see [Pi skills](skills.md)).
 Granting an external MCP tool through `mcpServers` and selecting a skill are
 independent: a skill grants no tool.