pi-session-mcp 0.8.3 → 0.12.0

package/docs/sprints/2026-10-24-s7-stabilization-live-acceptance.md

@@ -0,0 +1,173 @@
+# Sprint 7: stabilization and live acceptance (2026-10-24)
+
+Planning basis: main `f69c40f2f2f7ab5fb98767715ed2dc394e58a3cb`, published
+release 0.11.2, Pi SDK 1.4.0. Open issues at the start: #118 and #79; no open
+pull requests; CI, install smoke and the SDK canary green on that commit.
+
+This is a maintenance sprint, requested by the maintainer on 2026-10-24. It
+fixes one confirmed defect, reconciles the planning documents with what was
+delivered, and accepts the integrated candidate with real controllers and real
+Pi model turns. It does not change the MCP contract and adds no minor version.
+
+## Mandate
+
+| Goal | Content |
+| --- | --- |
+| A | Fix [#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. |
+| B | Reconcile roadmap, sprint files, implementation plans and trackers with the delivered releases. |
+| C | Accept the integrated candidate with real Claude Code and Codex controllers and real Pi worker turns. |
+| D | Check the normal setup and hook path and an automated container writer with event delivery. |
+| E | Record remaining gaps precisely and prioritize them. |
+
+Authorized: the focused fix, parallel delegation to internal subagents, Pi
+workers and agy, real model calls for development, review and the acceptance
+below, temporary configurations, synthetic repositories, isolated client
+settings and writers created only for this sprint, setup mutations inside
+those isolated environments, tracker and documentation upkeep, and one
+reviewable pull request against main.
+
+Not authorized: merge, tag, npm publication or rollout; changes to other
+running sessions or to existing client registrations and writers; wider
+permissions or credentials; new paid services or budgets; a new public MCP
+contract, a production task ledger, a supervisor daemon or a production
+question channel.
+
+Live acceptance limits set by the maintainer for the acceptance matrix: at most
+20 worker starts and 32 worker turns, at most 120 minutes of active live
+acceptance, no open-ended repetition, and at most one targeted rerun of a
+failed scenario after a demonstrated correction. No money limit was set by the
+maintainer, and none is claimed here. Development and review delegations are
+counted separately.
+
+## Scope
+
+- In: the #118 fix and its regression tests; corrections of the over-general
+  zombie statement in the rules and design documents; the documentation and
+  tracker reconciliation; a frozen candidate with Level 1, Level 2 (delivery
+  off and spool, packed tarball) and the Level 3 cycle; event-delivery
+  scenarios E1–E6; one automated container writer with delivery.
+- Out: the question channel (ADR 0011 item 4), a production ledger or
+  supervisor, Codex wake, macOS delivery, any change on macOS for #118 (the
+  `ps` path is not checked for the same case).
+
+## Source binding
+
+Three builds are kept apart in every record:
+
+1. Reference: the published 0.11.2 (`f69c40f` source, npm package).
+2. Candidate: the head of this sprint's pull request with the #118 fix. Its
+   package version stays `0.11.2` because the version is not raised in this
+   sprint (changelog entries go under Unreleased); the candidate is identified
+   by commit and `dist/` digests, never by the version string.
+3. Loaded: what a controller actually started, recorded per run.
+
+A pass of the candidate is never reported as live acceptance of the published
+0.11.2.
+
+## Work split
+
+The integrator (Claude Code) owns shared documents, the changelog, integration,
+the acceptance runs and the final verdict.
+
+| Package | Owner | Workspace | Writes |
+| --- | --- | --- | --- |
+| A: #118 fix and tests | Pi worker, profile `code` | full clone alias `pi-session-mcp-w1` | `src/setup-platform.ts`, `test/setup-platform.test.ts`, rule and design text on zombies |
+| B: documentation and tracker reconciliation | internal subagent | separate worktree | event-bridge plan, Sprint 6 file, ADR status lines; proposals for the roadmap and #79 |
+| C: live oracles, client configurations, evidence capture | internal subagent | scratch directory outside the repository | nothing tracked |
+| D: independent review of the frozen candidate | internal reviewer and a Pi reviewer of another model family | read-only | nothing |
+
+A, B and C run in parallel. D starts on a frozen, integrated state.
+
+## Gate order
+
+1. Reproduce #118 on the unchanged source; targeted regression tests.
+2. Integrate; independent review.
+3. Fix confirmed findings.
+4. Freeze the candidate.
+5. Level 1 and the Level 2 variants (delivery off, delivery spool, packed tarball).
+6. Live acceptance on that candidate: the Level 3 cycle, E1–E6 and the container
+   writer.
+
+A runtime change after a live run needs a new source binding and a rerun of the
+affected acceptance.
+
+## Acceptance criteria
+
+- #118 reproduced on `f69c40f` with an oracle independent of the function under
+  test, and fixed; the #109 handling for vanished processes is unchanged.
+- Level 1 green on the final source; Level 2 passes for delivery off and spool,
+  working tree and packed tarball.
+- Level 3: the gate in [Acceptance](../acceptance.md#gate) holds. Eight of ten
+  is the floor for task outcomes only; every security, scope and cleanup
+  criterion must hold on its own.
+- Wake scenarios have their own status and never stand in for the Level 3 cycle:
+  - E1: the hook installed only by setup in an isolated environment; a real
+    Pi turn ends while the controller waits; a new controller model round is
+    observed; one result read; no polls and no sleep loop.
+  - E2: two sessions with different end times; each wake reaches the right
+    session and turn; nothing lost or handled twice.
+  - E3: a longer deterministic worker task; task deadline, hook budget and hook
+    timeout aligned; a budget wake causes exactly one status read and a re-arm.
+  - E4: abort and close; no useless wake for a removed session; no stray hook,
+    server or worker processes.
+  - E5: Codex with a typical minimal environment starts with delivery off and
+    completes the core workflow by polling; no Codex wake is claimed.
+  - E6: wake in the VS Code extension, checked in a reachable VS Code instance;
+    hook pickup by an already running session checked separately; otherwise
+    blocked with the shortest operator procedure.
+- Container writer: provisioned from the frozen candidate, readiness and
+  isolation checks pass, the spool mount reaches no other writer namespace and
+  no extra host files, crafted events cannot fake success, collect and finish
+  lose no work, and nothing created by this sprint remains.
+- Every scenario record names commit, build, versions, route, profiles,
+  preconditions, steps, oracle, outcome (passed, failed, blocked, not run),
+  cleanup and limits.
+
+## Status
+
+Planned on 2026-10-24. Results are added below as they are taken; failed runs
+stay on record.
+
+### Results (2026-10-24)
+
+Evidence: [Sprint 7 live acceptance](../evaluation/s7-live-acceptance-2026-10-24/README.md).
+Candidate `6651a47`; the package version string stays `0.11.2`.
+
+| Item | Outcome |
+| --- | --- |
+| #118 reproduction on `f69c40f` | reproduced: `groupState` reported `gone` while an independent oracle saw a live thread with four descriptors and the kernel `flock` still held |
+| #118 fix and tests | implemented; the new tests fail on `f69c40f` (9 failures, the live test among them) and pass on the candidate; the same oracle reports `alive` while the lock is held and `gone` after exit |
+| Independent review | two reviews of the integrated state (Claude Opus 5.5 subagent, Pi `review-grok`): no blocking finding; the Low findings and one nit were fixed |
+| Level 1 | green except `npm audit`: `undici` 8.10.2 pinned by Pi SDK 1.4.0 ([#120](https://github.com/plagor44-ux/pi-session-mcp/issues/120)); `zod` and the development-path advisories were patched |
+| Level 2 | passed: working tree and packed tarball, delivery off (160/160) and spool (228/228) |
+| Level 3 | 10 of 10 tasks passed with every oracle check; gate not met only because Level 1 is not green (#120) |
+| E1 setup path wake | passed |
+| E2 parallel turns | passed |
+| E3b budget wake (manual hook) | passed |
+| E4 abort and close | passed against the pre-registered criteria; one stricter kit-oracle check failed and is recorded |
+| E5 Codex fallback | passed |
+| E6 VS Code | the wake was observed in the integrator's VS Code extension session on the published 0.11.2 only; the candidate was not loaded there; hook pickup by a running VS Code session not checked (procedure in the evidence) |
+| E6b hook pickup, CLI stream-json | picked up without restart |
+| Container writer with delivery | provisioning needed a second apply after one undiagnosable `writer_acceptance_failed` ([#121](https://github.com/plagor44-ux/pi-session-mcp/issues/121)); delegation, wake, collect, review, finish and remove passed; boundary and crafted-event checks passed provider-free; the forged event during a real controller turn was not run (harness defect, rerun and start limit used) |
+
+Delegations for development and review, counted apart from the acceptance
+matrix:
+
+| Task | Route | Result |
+| --- | --- | --- |
+| A: #118 fix and tests | Pi `code` (openai gpt-6.1-sol) on the full clone `pi-session-mcp-w1`, a host writer: the alias has mode `unset`, as all 29 configured aliases do | completed in one turn; diff reviewed and cherry-picked |
+| B: documentation reconciliation | Claude subagent (Sonnet 5.5) in a separate worktree | four files; cherry-picked; roadmap and #79 text applied by the integrator |
+| C: acceptance kit | Claude subagent (Sonnet 5.5), scratch directory | kit with self-test; one runbook defect (preflight configuration) found live |
+| D: review | Claude reviewer (Opus 5.5) and Pi `review-grok` (xai grok-4.7) | no blocking finding |
+
+Not done in this sprint: a structured question channel (ADR 0011 item 4).
+Completion wakes are a product feature since 0.11.0; structured questions were
+only examined in the Sprint 6 prototype; a public answer channel stays
+undecided. A human elicitation is not an autonomous answer of the controller,
+and a second prompt to a session with a running turn is refused
+(`session_running`), so it is no answer channel either. This sprint found no
+new demand that would justify an issue.
+
+Known gap outside #118: the acceptance harness
+`scripts/multi-session-acceptance.mjs` still treats every `Z` process as
+terminated in its own leftover check; it is not part of the setup fence.

package/docs/sprints/2026-10-24-s8-writer-migration.md

@@ -0,0 +1,235 @@
+# Sprint 8: migrate productive coding to container writers
+
+Planning basis: main `47b8d26` (Sprint 7 merged), installed release 0.11.2.
+Tracking: [#79](https://github.com/plagor44-ux/pi-session-mcp/issues/79),
+prerequisite [#121](https://github.com/plagor44-ux/pi-session-mcp/issues/121).
+
+Status: **planned**. The maintainer made the choices on 2026-10-25; see
+[Decisions](#decisions-2026-10-25). Nothing below has been changed on any
+machine yet.
+
+## Mandate
+
+On 2026-10-24 the maintainer decided that productive coding moves to
+automated container writers ([ADR 0008](../adr/0008-coding-profile-isolation.md),
+[ADR 0009](../adr/0009-execution-modes.md)). The host worktree writers will be
+retired. This sprint plans and carries out that migration per repository. It
+changes operator configuration, not product code, unless a migration step
+exposes a defect. The one planned product change is the diagnosability of a
+failed writer acceptance (#121), because every writer of the migration passes
+through that acceptance.
+
+Out of scope: product features other than #121, macOS writers, Codex wake, a
+writer lifecycle the release does not ship, and `bun-app` (its alias stays
+as it is until a later decision).
+
+## Inventory (workstation, 2026-10-24)
+
+All 29 configured workspace aliases have mode `unset`, so host coding is
+allowed everywhere. Every worker worktree is clean and detached.
+
+| Repository | Main alias | Host writer aliases today | Review alias | Toolchain needed |
+| --- | --- | --- | --- | --- |
+| pi-session-mcp | `pi-session-mcp` | `pi-session-mcp-w1` (full clone) | — | Node ≥ 22.19, npm |
+| node-app | `node-app` | `node-app-w1`–`node-app-w4` (worktrees) | — | Node ≥ 22.13, npm |
+| go-app | `go-app` | `go-app-w1`–`go-app-w7` (worktrees); manual container writer `go-app-alpha` | `go-app-rev` | Go 1.27.3 (`go.mod`), Node |
+| py-app | `py-app` | `py-app-w1`–`py-app-w3` (worktrees) | `py-app-rev` | Python ≥ 3.12 with `uv` |
+| pynode-app | `pynode-app` | `pynode-app-stab-a`–`pynode-app-stab-e`, `pynode-app-stab-int` (worktrees) | — | Python ≥ 3.12 with `uv` (backend), Node with npm (frontend) |
+| bun-app | `bun-app` | — | — | `bun` |
+
+The built-in writer image (`--image node`, a pinned digest) provides
+Node.js 22.23.3, Python 3.11 and Git. It has no Go, no `uv` and no `bun`.
+The operator image of `go-app-alpha` provides Go 1.26.9, which cannot build a
+module that requires Go 1.27.3 under `GOTOOLCHAIN=local`. Repository sizes
+(12–36 MB of Git data each) make disk space a non-issue for full clones.
+
+Second machine: the second machine has 9 aliases, among them `node-app-w1`–`node-app-w4`,
+and no `events` setting. **Podman is not installed there**, so container
+writers cannot run on it without a privileged installation.
+
+## Target
+
+Read-only profiles stay allowed in every mode. Main aliases and review aliases
+therefore stay usable for analysis and review on the host server. Coding moves
+to writers `<alias>-w<n>`, registered as `pi-coding-<alias>-w<n>`.
+
+A writer is not bound to a provider: every writer carries all profiles of its
+boundary, and the controller names the profile when it starts a session. A
+writer admits one open coding session at a time, so the writer count is the
+number of parallel coding sessions per repository. Every writer is one more
+project-local MCP registration with the full tool list, so counts can be raised
+later (up to 16) with another `--apply` rather than provisioned ahead of need.
+
+All writers use lifecycle `persistent` (finish collects, then resets the clone
+to its baseline) and network `pasta`; `none` would cut the boundary off from
+every provider.
+
+| Repository | Mode of the main alias | Writers | Image | Profiles in the boundary |
+| --- | --- | --- | --- | --- |
+| pi-session-mcp (pilot) | `container` | 2 | `node` | `code`, `code-deepseek`, `code-glm`, `code-mistral`, `code-grok` |
+| node-app | `container` | 4 | `node` | as above |
+| go-app | `container` | 4 | operator image: Go 1.27.3 and Node, `--cache go` | as above |
+| py-app | `container` | 3 | operator image: Python 3.12, `uv`, Node | as above |
+| pynode-app | `container` | 4 | operator image: Python 3.12, `uv`, Node | as above |
+
+Review aliases `go-app-rev` and `py-app-rev` become mode `read-only`. After a
+repository's writers are ready, its host writer aliases are removed from the
+configuration, and their worktrees are retired by the existing worktree-closing
+rule (commits checked into the integration branch, detached on `main`, branch
+deleted). `code-cursor` is dropped for coding: ADR 0009 does not admit the
+Cursor provider in a boundary. `review-cursor` stays a read-only route.
+
+Writer names collide with today's host alias names: `go-app-w1` is a host
+worktree today and would also be the first go-app writer. Each repository's
+host writer aliases are therefore removed in the same change that provisions
+its writers.
+
+## Operator images
+
+Setup does not build images; it accepts a local image ID. The sprint adds one
+Containerfile per toolchain with pinned base digests to the operator's private
+infrastructure repository, built
+with rootless `podman build` on each machine that runs writers:
+
+- `node-go`: Node 22 and Go 1.27.3 (go-app);
+- `node-python-uv`: Node 22, Python 3.12 and `uv` (py-app,
+  pynode-app).
+
+Each image needs Node, Git, bash, ssh and coreutils for the acceptance
+harness. A new image ID requires the provisioning command again and a new
+acceptance. The toolchain versions in those Containerfiles must follow the
+repositories' `go.mod` and Python requirements; a version bump there is a new
+image and a new acceptance.
+
+## Changes to the operator workflow
+
+- Writer registrations are project-local in Claude Code: the writer tools are
+  visible only to a controller started in that repository's checkout. Every
+  writer is also registered for Codex with `--client codex`, so both
+  controllers keep coding access.
+- Results come back through `--collect --apply` as
+  `refs/remotes/writer-<name>/<branch>` in the operator checkout, and a writer
+  is reused only after `--finish --apply`. This replaces cherry-picking from
+  host worktrees.
+- `~/.claude/rules/pi-routing.md` and `orchestration.md` must name the writer
+  registrations instead of the worktree aliases. The rule that both machines
+  have identical profile aliases stays.
+- After every release upgrade, each writer must be accepted again, because
+  acceptance binds the package version. The next release (with #118, #121 and
+  whatever resolves #120) therefore adds one provider-free acceptance run per
+  writer and does not block the migration.
+
+## Order and gates
+
+0. #121: a failed writer acceptance reports which check failed, under distinct
+   codes, and keeps a sanitized report in the writer's private state.
+   - Gate: tests for every failure path, Level 1 except the known #120
+     finding, independent review. Shipped in the same pull request as this
+     plan; the pilot runs from that build.
+1. Pilot: `pi-session-mcp`, built-in image, 2 writers.
+   - Gate: control, provisioning, acceptance and `--verify` pass.
+   - Gate: one real coding delegation per writer, collected, reviewed and
+     finished.
+   - Gate: the host writer alias `pi-session-mcp-w1` is retired.
+2. `node-app`, built-in image; retire `node-app-w1`–`node-app-w4` on
+   the workstation.
+3. Build and check the operator images (the toolchain version inside each
+   image, and the acceptance harness).
+4. go-app: first collect and review all `go-app-alpha` work and remove the
+   manual writer as documented, then provision. Retire `go-app-w1`–`go-app-w7`.
+   `go-app-rev` becomes `read-only`.
+5. py-app, then pynode-app, each with its retirement step.
+6. the second machine: the operator installs rootless Podman (a privileged
+   step). Then the same isolation control, image builds and provisioning as on
+   the workstation, starting with `node-app`; retire the
+   server's `node-app-w1`–`node-app-w4`.
+7. Update the routing rules and both machines' configuration. Record the
+   outcome on #79 and close it if every repository in scope is migrated;
+   `bun-app` is recorded as deferred.
+
+Every step is one repository at a time, with a rollback: collect the writers'
+work, `--remove` them, and set the mode back to `host` with
+`--accept-host-writes`. Open sessions of other controllers on an affected
+repository must be closed before its mode changes, and controllers must be
+restarted afterwards.
+
+## Acceptance per repository
+
+- Setup reports `writer_accepted`, `writer_registered`, `hook_added` (delivery
+  on), and `--verify` reports `mcp_verified`.
+- One real coding turn per writer through Claude Code, with wake when delivery
+  is on. The result is collected, reviewed in the operator checkout,
+  test-checked, and finished.
+- No host writer alias of the repository remains in the configuration, and
+  no worktree of it remains with unintegrated commits.
+- Doctor reports no `unset` warning for the repository.
+
+Known risk: [#121](https://github.com/plagor44-ux/pi-session-mcp/issues/121).
+A first acceptance can fail once. With step 0 the failure names its cause; one
+repeated `--apply` is allowed. A second failure stops that repository.
+
+## Decisions (2026-10-25)
+
+1. **Writer counts:** 2, 4, 4, 3, 4 as in the target table.
+2. **Images:** built in this sprint; Containerfiles live in the operator's
+   private infrastructure repository.
+3. **bun-app:** out of scope for this sprint.
+4. **Profiles in the boundary:** `code`, `code-deepseek`, `code-glm`,
+   `code-mistral` and the new `code-grok` (provider `xai`, `grok-4.7`, high),
+   so xAI keeps a coding route without Cursor. `code-grok` was added to the
+   operator configuration on both machines on 2026-10-25 and passed Doctor and
+   a provider round trip on 0.11.2 there. `code-cursor` is dropped for coding.
+5. **Codex:** writers are registered for Claude Code and Codex.
+6. **Server the second machine:** the operator installs rootless Podman; the
+   server gets container writers too (step 6).
+7. **Network:** `pasta` for all writers. Lifecycle: `persistent`.
+
+## Progress (2026-10-27)
+
+Step 3, operator images: done. The operator's private infrastructure repository
+now holds two Containerfiles on the same pinned Node base
+as the built-in image, a check script and a README.
+
+| Image | Repositories | Toolchain | Image ID on the workstation |
+| --- | --- | --- | --- |
+| `node-go` | go-app | Go 1.27.3 (official SHA-256 checked) | `fe14e8543500969bca13782b5e9aa43d7a2bb989e67f705e65fbf6d48034d91f` |
+| `node-python-uv` | py-app, pynode-app | Python 3.12.16, uv 0.13.6 (digest-pinned) | `eb2746450f5669ac8d01dbd9779f9e0833a2843b7ce9ad246e4ba80625466770` |
+
+- Under the writer's run flags (`--userns=keep-id --read-only --cap-drop=all`,
+  tmpfs `/tmp` 512 MB and `/pi/home` 64 MB) on throwaway clones: `go build ./...`
+  in go-app with `GOTOOLCHAIN=local`; `uv sync --frozen` in py-app
+  and in pynode-app's backend; `npm ci` and `npm run build` in its frontend.
+- One independent review, `NON_BLOCKING_ONLY`; its findings were fixed or
+  recorded as limits.
+- Limits that bear on step 5:
+  - after the pynode-app backend sync the uv cache holds about 483 MB of the
+    512 MB `/tmp`, and it is empty after every container start
+    ([#151](https://github.com/plagor44-ux/pi-session-mcp/issues/151) proposes
+    a `--cache uv`);
+  - pynode-app's backend tests need a test Postgres on `127.0.0.1:5544`,
+    which a writer does not have, and the image has no `tesseract`. A
+    pynode-app writer can build but not run those tests. Step 5 has to
+    decide whether that is acceptable.
+
+Step 4, go-app: done on `0.11.8` (record in
+[Acceptance](../acceptance.md#v0118-post-release-evidence)). Four writers
+`go-app-w1`–`go-app-w4` with the `node-go` image and `--cache go`; `go-app-alpha`
+unregistered and archived; host aliases `go-app-w1`–`go-app-w7` removed;
+`go-app-rev` is `read-only`. Process slip: while checking `go-app-alpha` for
+unintegrated work, the controller ran host Git (`status`, `fetch`,
+`update-ref`) in its clone, against the rule in
+[Isolation setup](../isolation-setup.md#review-finish-and-migration). Its Git
+configuration and hooks were then inspected without Git: unchanged since
+2026-10-18, sample hooks only. The clone is archived with the writer state.
+
+Also on 2026-10-27: the server the second machine was upgraded to `0.11.8`
+(no writers there yet).
+
+Open:
+- one real coding turn per go-app and `node-app` writer, from a
+  controller started in that repository's checkout;
+- step 5 (py-app, pynode-app) with the `node-python-uv` image,
+  after the decision on the test limits above;
+- step 6 needs rootless Podman on the second machine (operator, privileged);
+- step 7: routing rules and the #79 record;
+- the #79 review point on 2026-11-15.

package/docs/sprints/2026-10-26-s10-orchestration-reliability.md

@@ -0,0 +1,250 @@
+# Sprints 9 close-out to 11: orchestration reliability
+
+Planning basis: main `e6fc87c` (merge of PR #138), published 0.11.5, 2026-10-26.
+Input: the operator's concept "Pi-Orchestrierung verbessern: Kandidaten, Evidenz
+und Testplan" (2026-10-25, not tracked in this repository), checked against the
+repository below. This file plans work; it does not claim that any item is
+implemented or that any gate passed.
+
+## Where the project stands
+
+- 0.11.5 is published and runs the container-writer pilot on the workstation
+  (`pi-session-mcp-w1`, `pi-session-mcp-w2`).
+- Sprint 9 delivered #134 (closed) and the fail-closed part of #135 in PR #138.
+  #135 is still open; its remaining proposal (copying operator overrides into a
+  writer) is explicitly out of the sprint. #136 and #137 are open.
+- The Sprint 8 migration stopped after the pilot; steps 2–7 (the remaining
+  repositories and the second machine) wait for Sprint 9.
+- Open product decisions: #79 review point 2026-11-15, #120 (`undici` in Pi
+  SDK 1.4.0), ADR 0011 item 4 (question channel).
+- Route availability on 2026-10-26 (operator routing notes): the xAI profiles
+  (`code-grok`, `review-grok`) fail with HTTP 402 and the Cursor profiles end
+  with `turn_failed`. Usable coding routes in the writers: `code`,
+  `code-deepseek`, `code-glm`, `code-mistral`. Usable read-only routes on the
+  host alias: `review`, `review-glm`, `explore-fast`.
+
+## Concept assessment
+
+The concept proposes eleven candidates (K1–K11). Most of them change the
+controller skill, the shipped worker skills or client hooks, not the MCP
+contract. Checked against the repository:
+
+| # | Candidate | Repository check | Decision |
+| --- | --- | --- | --- |
+| K1 | Eval suite for the controller skill with `claude plugin eval` and mocked pi-session-mcp tools | `claude plugin eval` exists on Claude Code 2.1.310 here, with `--mocks` and a with/without ablation. Each run costs Claude tokens, not Pi provider tokens. | Sprint 10. Dev-only under `eval/controller-skill/`; the plugin wrapper is a test fixture, not a new distribution channel. |
+| K2 | Brief and report contract with fixed status tokens | The worker skills already require a five-part report ("done, partly done or blocked"); no exact tokens. The M1 receipt failures and the Grok T5 status spelling support exact tokens. | Sprint 10. |
+| K3 | File ledger per run plus a `SessionStart` hook (matcher `compact`) | Sprint 6 named compaction as the only gap of the in-context ledger (4.1 a) but rejected a file ledger as a **product feature** and called a hook writer a development aid. | Sprint 11, after maintainer decision D1. |
+| K4 | Early-stop rule: `completed`, short runtime and no change trigger one follow-up in the same session | 3 of 18 repeat runs and 1 of 15 first-wave runs stopped after 23–45 s. Correction: in a container writer the controller must not inspect the clone, so "no change" means no commit in the report **and** no new ref after `--collect`. | Sprint 10. |
+| K5 | Review stage per task with a capped fix loop, reviewer from another model family | Cross-family reviews found real defects in Sprints 5 and 6; Grok missed the verdict in `r-psm-smoke`. Collected refs already sit in the operator checkout as `refs/remotes/writer-<name>/…`. | Run as process from Sprint 10 on; write into the skill in Sprint 11 with the measured result. |
+| K6 | Routing per role | Matches the operator routing rules; the evidence is three runs per profile. | Sprint 10, worded as a default with its evidence level, not as a ranking. |
+| K7 | Background dispatcher subagent per Pi task | Unknown whether the wake reaches a subagent and whether it shares the registry. | Sprint 11, provider-free probe only. |
+| K8 | Wake gaps: hook timeout covers the task budget, wake after `PostToolUseFailure`, one long-turn L4 pair | Ledger evaluation S6 lists the long turn as not measured. | Sprint 11; the L4 pair needs a live approval. |
+| K9 | `Stop` hook that blocks only on a read but unverified turn | Depends on K3's ledger. A `Stop` gate on open sessions is rejected because it collides with the wake. | Sprint 11, with K3. |
+| K10 | Guided profile setup skill and a Doctor check for profiles in container repositories | #139; the Doctor check also closes the gap #135 left (refusal only at provisioning). | Later; the Doctor check may move forward if Sprint 9 has room. |
+| K11 | Report extension for workers (`submit_report`) | Container writers refuse extensions in coding profiles (writer boundary). Needs either a boundary change or a result channel in the MCP contract. | Deferred; needs an ADR and a minor release. |
+
+Two further findings from the concept were checked in code:
+
+- **Worker system prompt.** `phase0ResourceLoaderOptions` in
+  `src/sdk-pi-adapter.ts` sets `systemPrompt: "phase-0-system-prompt-disabled"`
+  with no-op overrides. Whether workers therefore run without Pi's default
+  system prompt is not verified. It is a plausible contributor to early stops
+  and is cheap to check without a provider, so it is the first task of
+  Sprint 10.
+- **`AGENTS.md` as worker context.** Workers load context files
+  (`noContextFiles: false`). This repository's `AGENTS.md` holds rules but no
+  build or test commands. Adding the commands is a cheap change; its effect is
+  unmeasured.
+
+The concept's "not recommended" list agrees with recorded decisions (bounded
+wait #91, question channel ADR 0011 item 4, extensions and MCP grants in
+container coding profiles, pi-lens on `code`) and is added to the roadmap's
+deferred table.
+
+## Sprint 9 close-out
+
+Goal: finish #136 and #137 so the migration can continue. Until they ship, the
+migration uses the workarounds: reconnect the writer servers after each reset
+or finish, and pin Pi extensions exactly.
+
+| Task | Scope | Route |
+| --- | --- | --- |
+| S9-1 #136 | After `--reset`, `--finish` or `--recreate`, setup reports that the writer's servers must be reconnected (like `controllers_restart_required`) instead of failing later with `local_authentication_missing`. A refusal while a server runs is not chosen, because a connected client would block every finish. Skill section 11 names the reconnect. | `code` on `pi-session-mcp-w1` |
+| S9-2 #137 | Doctor warns when an extension that a profile pins is listed unpinned in Pi's settings. `doctor_failed` from the repository step names the blocking check ids. The gate's tolerance is not widened. | `code-deepseek` on `pi-session-mcp-w2` |
+| S9-3 #135 | Record on the issue that the fail-closed part shipped in #138; close it or narrow it to override copying (maintainer decision D4). | controller |
+
+Gate per task: tests for each new path, `npm run typecheck`, `npm test` and
+one cross-family review. Level 1 and the release procedure run once, for the
+whole branch (see "Delivery").
+
+## Sprint 10: controller reliability
+
+Goal: make the controller skill measurable and close the report and early-stop
+gaps (K1, K2, K4, K6 and the system-prompt probe).
+
+1. **S10-0 system-prompt probe.** A provider-free probe (faux provider, like
+   the registration probe) that records the system prompt a worker session
+   actually receives. If the placeholder replaces Pi's default, plan an A/B
+   with a short worker-context addition; otherwise record the result and stop.
+2. **S10-1 K1 baseline.** `eval/controller-skill/` with a plugin wrapper and
+   mocks for the six pi-session-mcp tools. Six cases: parallel starts before
+   the first wait, terminal turn read once, start error code without retry,
+   every session closed, worker claim "tests green" checked by the controller
+   (`tool_used` on Bash with `input_match`), early-stop mock. Graders without a
+   judge, `--runs 3`. Stop rule: if scores vary between runs, sharpen the
+   graders before measuring anything else.
+3. **S10-2 skill change (K2, K4, K6).** One change to
+   `pi-session-orchestration` and the two worker skills: exact status tokens
+   `DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT`, `BLOCKED`; the controller
+   checks the report format before verification; the early-stop rule with the
+   container-writer correction above; routing defaults with their evidence
+   level. Plus build and test commands in `AGENTS.md`.
+4. **S10-3 measurement.** The suite before and after. Then, only with an
+   approved budget (D2), `npm run eval:profiles` on the three implementation
+   tasks of the ablation, three runs each. Metrics: accepted runs, caught early
+   stops, cost per accepted run, or "unknown" where usage is missing.
+5. **S10-4 writer rollout check.** The skills ship in the package. Container
+   writers see the new worker skills only after the upgrade and a
+   `--repo … --apply`; verify that once after the release.
+
+K5 runs as process on every Sprint 10 task: review by `review-glm` for code by
+`code` or `code-deepseek`, by `review` for code by `code-glm`; rounds 1–3 as a
+follow-up in the same session, rounds 4–5 in a fresh session with a stronger
+coding profile, then a recorded decision. Record per task: findings only the
+review found, rounds, cost or "unknown".
+
+## Progress log
+
+Recorded as work lands on the branch; statements are verified by the
+controller unless marked otherwise.
+
+- S9-1 #136 and S9-2 #137: implemented by `pi-session-mcp-w2` (`code-deepseek`)
+  and `pi-session-mcp-w1` (`code`), reviewed by `review-glm`
+  (verdict non-blocking only; four low findings, three fixed on the branch,
+  the fourth is within the intended "applied and successful" scope). Controller
+  review changes: the Doctor loads the Pi SDK lazily, and gate findings report
+  the alias of `<profile>:<package>` and writer subjects. Full suite green on
+  the host (114 files).
+- Unverified hypothesis from the review: the writer wrapper rewrites the
+  projected credentials every 60 s, so after a reset a running server may
+  recover without a reconnect; after a recreate the server's mounts point at
+  replaced directories. The docs therefore say a start "can" fail.
+- S10-0: workers keep Pi's default system prompt; the placeholder has no
+  effect ([probe](../evaluation/worker-system-prompt-2026-10-26/README.md)).
+  No A/B needed.
+- S10-1: suite under `eval/controller-skill/`, built by agy, checked and
+  completed by the controller (real tool definitions as `_tools.json`). A
+  one-run smoke passed at USD 0.17.
+- S10-1 baseline: the first run scored 10/18; all failures traced to suite
+  defects (identical session IDs, a vague prompt, too narrow Bash grants).
+  After the fixes 17/18 on six cases. The current skill already sends a
+  follow-up after an early stop, so K4 mostly makes that rule explicit.
+- S10-2: the status contract, early-stop rule and routing defaults are in the
+  three skills, plus build and test commands in `AGENTS.md`. The new
+  `unstructured-report` case went from 0/3 to 3/3; all other cases stayed
+  within run-to-run noise ([eval README](../../eval/controller-skill/README.md)).
+  Rollout note: until writers run the new worker skills, the new controller
+  treats their reports as a format failure and asks once more.
+- S10-3, decided 2026-10-26: the planned live run does not fit the existing
+  harnesses. `eval/extensions` varies extensions, not worker skills, and
+  `eval:profiles --live` selects no skills; 18 runs could not show a change in
+  an early-stop rate of about 3 in 18 either. The live check moves to
+  observation after the release: tasks on the upgraded writers (provider
+  OpenAI, profile `code`) record status line, early stops and follow-ups.
+- Release 0.11.6 is prepared on this branch; the pre-release acceptance on
+  `a7781da` passed (record in `docs/acceptance.md`).
+- Decisions taken 2026-10-26: D1 outside the package first, D2 as above, D4
+  #135 closed, D5 the gate stays fail-closed. D3 is still open.
+- Operating findings for the controller skill and the preflight:
+  - A writer keeps the base it was last reset to; `--finish` resets to that
+    base, not to the current main. Both writers still stood on the 0.11.5
+    release commit. The preflight must compare each writer's base with the
+    intended base and use `--reset --base <branch> --apply` when they differ.
+  - A worker that finds a wrong base must stop; one worker fetched
+    `origin/main` inside the boundary instead. The brief now says "do not fetch
+    or change the base yourself".
+  - The full suite times out in 8 lock and hook tests inside the writer
+    containers but passes on the host; worker reports of those failures are
+    environmental until shown otherwise.
+  - `pi-session-mcp-setup` needs `PI_SESSION_MCP_CONFIG` set explicitly in the
+    controller's shell, otherwise it reports `config_required`.
+
+## Sprint 11: ledger, gates and wake gaps
+
+Entry: decision D1 and the Sprint 10 results.
+
+- K3 and K9 in the form D1 chooses. Test: one session with three running
+  tasks, then a manual `/compact`. Pass: no task is sent again, the ledger
+  matches `git log` and the collected refs, no turn ends without verification.
+  Stop if the hook context does not arrive after compaction.
+- K8: hook timeout at least the task budget, a wake after
+  `PostToolUseFailure`, and one L4 pair with a turn of several minutes (live
+  approval required).
+- K7: provider-free probe in the style of the L3 probe under `eval/bridge/`:
+  does `pi_session_list` in the main context see a subagent's sessions, and
+  does the wake reach the subagent? Stop if either answer is no.
+- K5 written into the controller skill with the Sprint 10 numbers.
+
+Hooks are Claude Code only. Codex keeps polling and the in-context ledger; the
+skill must say so.
+
+## Parallel track: migration
+
+Sprint 8 steps 2–7 continue after 0.11.6, one repository at a time with the
+existing gates and rollback. They need the operator (images, rootless Podman
+on the server) and can run alongside Sprint 10, which touches only skills,
+`eval/` and documentation. Each migrated repository is also a live check of
+the Sprint 10 skill.
+
+## Orchestration
+
+The controller (Claude Code, Opus) plans, writes briefs, integrates, verifies
+and owns Git, releases and every operator step.
+
+| Work | Route |
+| --- | --- |
+| Product code with a clear plan | Container writers via `pi-coding-pi-session-mcp-w1`/`-w2`: `code-deepseek` for fully specified mechanical tasks, `code` where judgement is needed; never two writers on overlapping files |
+| Cross-family review | Host alias `pi-session-mcp`, read-only: `review-glm` or `review` (see K5); `explore-fast` for cheap lookups |
+| Bulk work: eval cases and mocks, long transcript reads with a digest | agy, `gemini-3.8-flash-high`; no secrets or filled environment files |
+| Gates and long logs | Claude `runner` subagent |
+| Final diff review before the pull request | Claude `reviewer` subagent |
+| Skill and documentation text | the controller itself (small, judgement-heavy) |
+
+Rules for every run:
+
+- Preflight: `git worktree list`, `git status` per worktree, writer state; a
+  writer that is not clean on the base stays blocked.
+- Each brief carries goal, base commit, change area, checks and the exact
+  report fields (K2 already applies to the briefs before it ships in the
+  skill).
+- Worker and agy results are unverified until the controller has read the
+  collected diff and run the gates itself.
+- Finish each writer task with `--writer <name> --collect --apply`, review,
+  integrate, `--finish --apply`, then reconnect the writer servers (`/mcp`)
+  until S9-1 ships.
+- Do not plan xAI or Cursor routes until the operator restores them.
+
+## Delivery
+
+All of this plan travels on one branch, `feat/orchestration-reliability`, and
+one pull request, with one commit per issue or task. No separate pull requests
+for documentation or single fixes. The pull request opens once the planned
+work on the branch is complete and verified, so that CI runs on the final
+state; it is not edited or pushed again while CI runs unless that is required.
+
+It carries one patch release (0.11.6, MCP contract unchanged) with its version
+change and pre-release acceptance, per the release procedure: Level 1 except
+the known #120 finding, a final independent review of the whole diff, then
+merge, tag and publication as maintainer decisions. Sprint 11 items join the
+same branch only if D1 and the live approvals arrive before the Sprint 10 work
+is verified; otherwise they wait for the next consolidated branch.
+
+## Maintainer decisions
+
+| Id | Question | Recommendation |
+| --- | --- | --- |
+| D1 | K3/K9: ship the ledger and its hooks in the package (opt-in, installed by setup like the wake hook), or keep them as a documented operator hook outside the package? | Start outside the package; move it in only if the Sprint 11 test passes. |
+| D2 | Live budget for S10-3 (3 tasks × 3 runs × 2 arms) | Set a cap before S10-3 starts. |
+| D3 | K11: open an ADR for a worker result channel? | Not before the Sprint 10 numbers show that K2 is not enough. |
+| D4 | #135: close, or keep open for override copying? | Close and open a separate proposal issue if wanted. |
+| D5 | #137: should the repository step's Doctor gate ignore errors that concern only profiles the repository does not select? The fix on this branch warns earlier and names the blocking checks but keeps the tolerance, so a version mismatch in an unrelated profile still blocks `--repo … --apply`. | Keep fail-closed for 0.11.6; operators pin Pi extensions exactly. Revisit if the warning does not prevent a repeat. |