pi-session-mcp 0.8.3 → 0.12.0

package/docs/skills.md

@@ -128,6 +128,16 @@ Edits to a skill file that already resolves reach new sessions, as described
 under [snapshot semantics](#snapshot-semantics). Deleting a resolved override
 leaves the catalog pointing at a missing file until the restart.
 
+A container writer has no override directory: inside its boundary
+`builtin:<name>` can only resolve to the shipped skill. Setup therefore refuses
+a coding profile for a container repository with `container_profile_unsupported`
+when it selects a `builtin:` skill that the package does not ship, or one that
+has an override, instead of letting the writer load the shipped text in place of
+yours or fail at session start
+([#135](https://github.com/plagor44-ux/pi-session-mcp/issues/135)). An override
+of a skill that no selected coding profile chooses does not matter to the
+writer. Keep customized skills on profiles that run on the host.
+
 The shipped example configuration registers the two worker skills with
 `builtin:`. After you copy the example, its skill entries need no path edits.
 
@@ -142,6 +152,19 @@ frontmatter with only `name` and `description`.
 | `pi-session-review` | A Pi worker | A review of a fixed target with findings and evidence. Register it as `builtin:pi-session-review` and select it on read-only profiles. |
 | `pi-session-orchestration` | The controlling Claude Code or Codex agent | How to run Pi worker sessions through this server. `setup --apply` installs it into the clients. It is not a Pi worker skill: do not select it in a profile. |
 
+The worker skills ask for concise final reports: status, actual changed paths,
+checks with exit codes, failures, blockers, risks and repository-relative
+evidence references, without full diffs or logs by default. A failed check,
+blocker or risk is never dropped to save space. `truncated: true` means the
+report the controller receives is incomplete; `truncated: false` does not prove
+that it is complete or correct.
+
+The orchestration skill is a small skill tree: `SKILL.md` plus
+`references/start-errors.md`, the classification of `pi_session_start` error
+codes, which the controller reads only after a start failure. Setup copies the
+whole tree and the tree fingerprint covers both files; a copy of only
+`SKILL.md` lacks the referenced file.
+
 A package update can change the shipped skills. Close affected sessions before
 you update, as for any skill change.
 

package/docs/sprints/2026-10-15-s4-decision.md

@@ -101,10 +101,12 @@ how. ADR 0008 (Proposed) must compare at least:
 3. moving Pi out of process per session, which would amend ADR 0002.
 
 Two facts constrain the options. `edit` and `write` run inside the server
-process and only `bash` runs as a child process, so confining `bash` alone
-would give false assurance. One server process serves every session of a
-client, so whole-process confinement can only allow the union of all
-workspaces plus Pi's agent directory and the provider network. The ADR also
+process, so confining the child processes (`bash`, and also `rg`, `fd`, MCP
+servers and extension children) alone would give false assurance. One server
+process serves every session of a client, so whole-process confinement can
+only allow the union of all workspaces plus what the process itself needs,
+such as Pi's agent directory and the provider network. (Corrected on
+2026-10-16: the first version said that only `bash` runs as a child process.) The ADR also
 names the threats each option addresses: model error, prompt injection from
 repository content or `AGENTS.md`, and trusted extension code. Filesystem
 confinement does nothing against extension code or exfiltration through the
@@ -126,6 +128,13 @@ are operator practice; the server enforces none of them.
 - Skill catalog and override directories outside every workspace.
 - Every worker diff is reviewed before it leaves the worktree.
 - Cursor-backed profiles only where a write would be uncritical.
+- Since 2026-10-18 ADR 0008 is accepted for Linux and its setup acceptance
+  passed for one writer; on Linux these rules end for coding work that runs
+  through an accepted wrapped registration, and they stay in force on macOS and
+  for every other coding route.
+- Since Sprint 5 (unreleased), Doctor warns with `workspace_gitfile` when a
+  workspace has a `.git` gitfile (possible linked worktree) and a coding
+  profile exists; advice only, session start is unchanged.
 
 These rules limit the damage of mistakes. They do not contain a misbehaving
 worker. Accepted residual risks, as the two reviews of this decision named
@@ -183,3 +192,63 @@ the rules above and the residual risks are recorded instead.
   read-only, 2026-10-15 (15:36 UTC).
 - The published-release acceptance of v0.8.2 and the reproduction of #78,
   recorded in [Acceptance](../acceptance.md#v082-post-release-evidence).
+
+## Appendix: Proposed ChatGPT project instructions (R22)
+
+This replaces the proposal in the
+[Sprint 2 file](2026-10-13-s2-evidence.md#appendix-proposed-chatgpt-project-instructions-r22)
+and describes the state on 2026-10-16. The operator pastes it into the ChatGPT
+project instructions; this repository does not apply it and cannot check that
+it was applied.
+
+```text
+Project: Pi Session MCP
+
+Current repository: plagor44-ux/pi-session-mcp. It is the successor of
+pi-control. pi-control is archived; its final pull request was #79 in that
+repository. Do not work in pi-control and do not treat its history as the
+current plan.
+
+Current release: 0.8.3 on npm (pi-session-mcp), released 2026-10-15. It uses
+Pi SDK 1.2.0 (@earendil-works/pi-coding-agent) and MCP SDK 2.3.1. The SDK's
+internal @earendil-works packages (pi-agent-core, pi-ai, pi-codemode, pi-mcp,
+pi-tui, pi-telemetry) are pinned exactly as direct dependencies, because a
+consumer install does not get the repository's lockfile (issue #78). Versions
+0.6.1 to 0.8.2 crash at startup on a fresh install; never recommend them. Local stdio, in-memory state, one trusted local peer.
+
+Decisions that bind current work (docs/adr, in this order):
+0001 stdio first; 0002 embedded Pi SDK; 0003 post-MVP maintenance; 0004 client
+contract, not client version; 0005 macOS setup platform; 0006 Pi extension
+allowlist (exact npm:<name>@<version> entries per execution profile); 0007
+profile-selected skills and the setup-installed controller skill. ADR 0008
+(isolation for coding profiles) is in preparation and not yet accepted.
+
+The project is in maintenance mode (ADR 0003): focused fixes and upstream
+drift, no new feature phase. A change to the public MCP contract needs a new
+minor release and its own decision. Sprints 1 to 4 are closed. Sprint 4
+(docs/sprints/2026-10-15-s4-decision.md) found that ADR 0003's isolation
+trigger fired, because coding profiles have written on non-disposable
+repositories; the one next investment is the isolation decision in issue #79
+(ADR 0008, options comparison first, no runtime change before acceptance).
+Until then the interim operating rules and residual risks in that Sprint 4
+file apply.
+
+Current priorities come only from docs/roadmap.md and the sprint files in
+docs/sprints/ (with docs/reviews/2026-10-13-post-0.8.1-audit.md for the
+R01-R23 backlog). Read them before proposing work. Open: #79. macOS
+acceptance on real hardware (R10, R11) was verified for Claude Code on
+2026-10-16; see docs/acceptance.md.
+
+Historical gates are not active priorities: the v0.3.0 release sequence and
+the former pi-control issues #11-#14 are historical. Bind any acceptance to
+the current build, not to those gates.
+
+Release practice (docs/releasing.md): version and pre-release acceptance
+travel in the change pull request; before publication a packed-tarball
+Level 2 run installs the package without the lockfile, like a consumer. CI
+and a nightly job run an install smoke against a lockfile-free install.
+
+Rules: state only what was run; provider-free tests do not establish live
+client or model behavior; targeted multi-session checks are not a Level 3
+cycle; no secrets, absolute paths or prompts in records.
+```

package/docs/sprints/2026-10-17-token-footprint.md

@@ -0,0 +1,130 @@
+# Bounded orchestrator token-footprint evaluation
+
+Date: 2026-10-17. Base: `d6f360926e26629f7b382583c077016daeb954ca`
+(PR #84), package 0.8.3, Pi SDK 1.2.0, MCP SDK 2.3.1. The explicit user
+assignment requests this development-only measurement. Maintenance continues;
+the isolation decision (#79, ADR 0008 Proposed) remains the next investment.
+No production optimization, registration, profile, credential, release or public
+contract change is authorized. #81 is unrelated and remains untouched.
+
+## Questions and hypotheses fixed before measurements
+
+- Measure discovery/schema, delegation, running-status and final-report UTF-8
+  bytes at the MCP boundary. Hypothesis: large final reports and repeated terminal
+  retrieval can dominate payload, but no savings target is assumed.
+- Count controller tool invocations per accepted task and worker turn, including
+  running polls, first terminal consumption and repeated terminal consumption.
+  Hypothesis: consuming a terminal result once removes duplicate bytes without
+  changing the independently verified task.
+- Distinguish transport duplication from actual client projection. Hypothesis:
+  `content` and `structuredContent` overlap on the wire; whether either client
+  injects both into the model is unknown until directly observed.
+- Characterize structured thinking, tool arguments/results, streaming, mixed
+  finals, late events, two sessions, errors, abort and timeout. Ordinary final
+  text echoing tool content or `<think>` tags is expected to pass the text filter.
+- Separate SDK `length` from registry truncation at 64 KiB. A compact 4 KiB report
+  is a candidate, not a token limit or secrecy boundary. Reject malformed,
+  truncated or incomplete reports even if the turn is technically completed.
+- Model usage and money stay null unless supported events expose reliable values
+  with documented semantics. Never infer tokens from bytes, treat missing usage
+  as zero, subtract cache indiscriminately, or sum overlapping usage fields.
+
+## Matrix and measurement boundaries
+
+M0 is provider-free: at least five repetitions of each deterministic case. Reuse
+the existing profile fixtures/oracles, owned temporary scopes and public MCP/SDK
+seams. Cover a short read, independently failing/repaired T2, two sessions and
+one follow-up, immediate/delayed/long turns, normal paused polling, a separately
+labelled repeated terminal fetch, Unicode around 64 KiB, domain error, provider
+error, abort, timeout and cleanup. No artificial polling storm is a baseline.
+
+Layer 1 observes complete newline-delimited JSON-RPC UTF-8 frames by direction,
+tool, state and monotonic time, and separately measures `content`,
+`structuredContent`, prompt, schema and final-text sizes. The whole frame is its
+own metric; component sizes are not added as a token count. Layer 2 requires a
+supported actual-client request/context boundary; UI or tool events alone do
+not prove injection. Layer 3 records available controller usage separately from
+worker usage and separates newly added context, request size and cumulative
+input usage. Unknowns include a reason and no invented tokenizer estimate.
+
+Freeze baseline evidence before testing two one-factor candidates: compact
+reports and consume-terminal-once polling. Compare payload, counts, runtime and
+independent task/report acceptance. Preserve status, changes, failed checks,
+blockers, risks and relative evidence references. Include adverse reports and
+oracle-negative controls; worker assertions never replace verification.
+
+M1 prepares L1 (one read), L2 (one T2 repair) and L3 (two reads plus one follow-up):
+four starts and five turns per repetition. First prepare one technical pilot;
+up to two additional repetitions need explicit current approval. Record exact
+available routes, effort, tools, skills, extensions, client versions, source and
+fixture/prompt/build digests, time/start/turn limits and unmetered cost decision.
+Fresh controller invocations per arm; alternate paired order for a subsequently
+approved A/B comparison (aim for three pairs). Historical approvals cannot apply.
+
+## Quality and completion gates
+
+### Additional provider-free client boundary calibration
+
+Before the final current-source measurements, add one bounded synthetic Codex
+client calibration. Declare a new **test-only loopback Responses provider**,
+without authentication, with fresh empty disposable HOME/CODEX_HOME, ignored user
+configuration, ephemeral sessions, no inherited credential/proxy variables and
+only the fake MCP fixture server. This is not a production model switch or a
+real provider run. First validate a single technical pilot; if it works, run five
+repetitions each for normal, domain-error and registry-truncated MCP replies.
+Bound every subprocess and request count, preserve failed attempts, close all
+scripted sessions and remove owned raw client state.
+
+Hypothesis (no assumed answer): inspect the next actual Codex HTTP request to
+determine whether synthetic result markers occur in one or two projected
+representations, including client truncation. Export only request/item byte sizes,
+marker counts/hits, safe labels/hashes and cleanup/authorization-header booleans.
+No body, transcript, prompt, tool data or header value persists. Any usage emitted
+by the scripted endpoint is synthetic and cannot count as model usage. Conclusions
+apply only to the observed Codex version and declared synthetic route; real cloud
+projection, token billing, cache behavior and general egress containment remain
+unestablished. Do not infer network isolation merely from a loopback listener.
+
+Persist field allowlists only: opaque IDs, hashes, approved version/alias labels,
+sizes, counters, times, exit codes, marker booleans and relative evidence links.
+No raw transcripts, paths, prompts, thinking, tool data or provider errors.
+Retain failed and blocked attempts. Bind uncommitted measurement sources and
+the build actually launched; do not transfer historical qualifications.
+
+Pass independent read invariance, T2 failing-baseline and repaired assertions,
+report rejection controls, channel filters and owned-session/process cleanup.
+Run targeted tests/typecheck and one relevant broad suite. Record native review
+and measurement/verification overhead outside the benchmark counts.
+
+## Status
+
+Current-source M0 passed 80 actual-stdio cases, 50 filter cases and ten adverse
+report controls, with five repetitions per deterministic case and a frozen
+baseline before candidates. The separate actual Codex client probe passed one
+pilot plus five repetitions each of success, domain error and registry truncation
+on its declared provider-free loopback route. It observed one selected marker
+occurrence per response despite two equal server representations. Large results
+were further shortened; completed/truncated metadata remained decodable.
+
+See the [dated report](../evaluation/token-footprint-2026-10-17/README.md) for exact
+bindings, whole/component/request sizes, independent acceptance, filter/plaintext
+limits, cleanup, failed attempts and measurement overhead. Earlier calibrations
+remain unchanged under their own bindings. The full suite passed 1,495 tests with
+six skipped; subsequent cleanup-plan metadata correction was separately verified
+and remeasured, without repeating the broad suite or transferring its binding.
+
+The dedicated fresh-controller M1 adapter is implemented and independently
+reviewed. It preserves the existing profile gate and requires an additional exact
+four-start/five-turn decision. The concrete current-source
+[approval package](../evaluation/token-footprint-2026-10-17/live-package.json) is
+ready for the operator: one pilot, declared routes, bounded work/case/wave times,
+separate cleanup observation phases and unknown model costs. Existing gates
+require an operator-selected positive advisory amount and acknowledgment of
+unmetered cost; all approval flags remain false and no amount was invented.
+On 2026-10-18 the operator approved the M1 pilot (10 USD advisory,
+unmetered use acknowledged). Two attempts failed on harness defects
+(controller SIGTERM forwarding; L2 coding default), both fixed with tests; the
+third [passed](../evaluation/token-footprint-2026-10-17/m1-pilot/README.md)
+with 4 starts, 5 turns and 0 retries. No live A/B, Claude comparison, token
+saving or Level-3 qualification is claimed. Production and maintenance/isolation priorities remain
+unchanged.

package/docs/sprints/2026-10-18-s5-maintenance-orchestration.md

@@ -0,0 +1,202 @@
+# Sprint 5: maintenance and orchestration friction
+
+Date: 2026-10-18. Base: main `612fbcb976d4563ea597e87be56123055b782c1a` (merge of
+PR #85), package 0.8.3, Pi SDK 1.2.0, MCP SDK 2.3.1. Maintenance under ADR 0003.
+The isolation decision (#79, ADR 0008 Proposed) stays the prioritized
+architecture work; this sprint does not accept ADR 0008 and implements no
+isolation. No merge, tag, version bump or npm publication is part of it.
+
+## Goal
+
+Reduce confirmed friction in diagnosis and orchestration, make the evidence
+summaries consistent, and prepare the next decisions with concrete inputs.
+
+## Preflight (2026-10-18)
+
+- `origin/main` = `612fbcb`; no open pull requests; main CI run 39121671820
+  green on Linux, macOS 15, macOS 26 and verify; latest release v0.8.3.
+- Open issues: #79, #81, #86, #87, #88, #89, #90, #91, #92, #93 (all read
+  with comments, including the 2026-10-18 comments on #88 and #89).
+- Local checkout: clean, 15 commits behind and fast-forwarded. Pre-existing
+  linked worktrees of earlier sprints (`docs/79-isolation-adr`,
+  `chore/release-v0.8.2`, `docs/s4-decision`) are left untouched.
+- The main checkout's `node_modules` held Pi SDK 1.1.0 although the lockfile
+  pins 1.2.0 (a stale local install, not a repository defect). All checks of
+  this sprint ran in fresh full clones after `npm ci`.
+- Installed clients: Claude Code 2.1.301, Codex 0.162.1. The provider-free
+  Codex projection probe pinned Codex 0.162.0 exactly; a follow-up pass let it
+  accept 0.162.1 explicitly (see the follow-up section).
+- #85's security summary binds `98a7dc4`, not its final head `132f48e`; no
+  review approval is derived from it.
+
+## Routes and ownership
+
+Discovered with `pi_capabilities_get` (once) and `agy models` / `agy --help`.
+
+| Route | Finding | Use in this sprint |
+| --- | --- | --- |
+| Pi coding profiles (`code`, `code-*`) | Only one workspace alias for this repository, pointing at the operator's main checkout; no dedicated writer alias exists | **Blocked** by the Sprint 4 interim rule (coding only on dedicated worktrees, one writer per alias). No MCP configuration was widened |
+| Pi read-only profiles | Available | `review` (Sol, high) for #92 |
+| agy (Gemini) headless | Models listed; without a permission grant headless agy denies shell and URL tools; `--yolo` was refused by the Claude Code auto-mode classifier and not worked around | File-read-only analysis for #79; web research blocked on this route |
+| Claude subagents | Available | Writers in separate full clones (own `.git`, base `612fbcb`); research and review |
+
+Writers never shared a clone, file ownership was disjoint, and the integrator
+serialized every change into one integration clone. Worktrees are not an OS
+sandbox, and neither are these clones.
+
+## Ledger
+
+Session and turn IDs were kept only transiently.
+
+| Task | Issue | Owner / route | Workspace | Scope | Status | Checks (by owner, then integrator) |
+| --- | --- | --- | --- | --- | --- | --- |
+| A | #81 | Claude implementer | clone `a` | `src/doctor.ts`, `test/doctor-gitfile.test.ts`, `docs/doctor-design.md` | implemented | typecheck, build:cli, 67 Doctor tests + 18 new; integrator fix: byte-based size cap |
+| B | #86 | Claude implementer | clone `b` | orchestration skill tree, start-code, skill-library, package and setup tests | implemented | typecheck, builds, 12 files / 235 tests + 2 files / 338 tests; integrator fix: no retry before a start code is classified |
+| C | #87 | Claude implementer | clone `c` | both worker skills, `test/skill-library.test.ts` | implemented | typecheck, 6 files / 122 tests |
+| D | #88, #90 | Claude implementer | clone `d` | `src/server.ts`, `test/mcp-contract.test.ts`, `docs/evaluation/tool-definitions-2026-10-18/` | implemented; Codex projection measured in the follow-up | typecheck, build, 5 files / 125 tests, 156 raw responses compared |
+| E1 | #79 | agy `gemini-3.8-flash-high`, file-read tools only | main checkout, read-only | decision brief | delivered, verified by integrator | — |
+| E2 | #92 | Pi `review`, read-only | alias `pi-session-mcp` | SDK usage semantics | delivered; rechecked against 1.2.0 | session closed |
+| E3 | #91 | Claude researcher (agy web route blocked) | read-only | decision inputs | delivered | — |
+| E4 | #89 | Claude researcher, then Claude implementer | clone `e` | provider-free Claude projection probe | q1–q3 answered on synthetic routes (q3 in the follow-up); q4 not measured | typecheck, 2 files / 9 tests, eval:schemas --check; probe attempt 1 inconclusive, attempt 2 PASS (base), attempt 3 PASS (Sprint 5 head, after review fixes) |
+| F | #93 | integrator | integration clone | A/B proposal | delivered, unapproved | — |
+| G | — | integrator | integration clone | roadmap, sprint, evaluation summaries, CHANGELOG, ADR facts, acceptance | delivered | relative-link check of all changed Markdown files |
+| R1 | all | agy `gemini-3.8-flash-high`, file-read tools only | frozen diff `612fbcb..87bde7a` | independent review | 5 findings, all fixed | — |
+| R2 | all | Pi `review-grok` (xAI), read-only | main checkout detached at `87bde7a` | independent review | 2 findings, fixed; turn budget extended once from 15 to 25 minutes, finished after 17 | session closed |
+
+## Results per issue
+
+- **#81 implemented.** Doctor warns `workspace_gitfile` (warning, exit 1, never
+  masking an error) when a workspace's `.git` is a regular file starting with
+  `gitdir:` and a coding profile exists. The detection is conservative: a
+  gitfile also marks submodules and separate Git directories, and the pointer is
+  never followed. Symbolic links, unreadable and malformed files yield `ok`,
+  meaning "not detected", not "verified clean". See
+  [Doctor design](../doctor-design.md).
+- **#86 implemented.** Terminal turns are recorded once; cadence 10 s then
+  15–30 s; fixed task and cleanup budgets; cost note as a Codex route
+  observation; the start-code classification lives in
+  `references/start-errors.md`. `SKILL.md` went from 9,025 to 9,112 bytes; the
+  reference adds 1,380 bytes, loaded only after a start failure. No token saving
+  is claimed. The test still checks complete, unique coverage of every
+  documented start code against `docs/tool-contracts.md`.
+- **#87 implemented.** Worker reports: concise, relative evidence, failing lines
+  only, nothing dropped for space, `truncated` semantics. Implementation skill
+  2,789 → 3,482 bytes, review skill 2,610 → 3,254 bytes. Live effect unmeasured.
+- **#88 implemented.** Four descriptions gained hints; `pi_session_start` is
+  unchanged. Patch under ADR 0003: descriptions are not tools, fields, states
+  or error codes.
+- **#90 implemented** after the compatibility check passed: input schemas use
+  `z.string().meta({ format: "uuid" }).pipe(z.string().uuid())` (public zod API),
+  so the JSON Schema keeps `format: "uuid"` without `pattern` and validation is
+  unchanged. 156 raw JSON-RPC responses (26 values for each of the six fields)
+  were byte-identical before and after, with no side effects. Patch under ADR
+  0003. Output schemas and `content`/`structuredContent` are unchanged.
+- **#79 open maintainer decision.** [Decision brief](../reviews/2026-10-18-adr-0008-decision-brief.md);
+  ADR 0008 facts updated (R10/R11 passed for Claude Code, macOS containment
+  unproven, #81 delivered); status stays Proposed.
+- **#89 partially delivered.** A provider-free Claude Code probe uses the
+  documented gateway route (`ANTHROPIC_BASE_URL` to a loopback fake, dummy key,
+  fresh config, `--bare`). On that route: output schema not observed; one
+  tool-result representation observed; deferred tool search unmeasurable
+  in bare mode, observed in the follow-up on a non-bare route; per-case
+  controller input not measured. The M1 frame proxy now forwards Claude Code's
+  `server/discover` (follow-up). See the
+  [probe](../evaluation/s5-decision-inputs-2026-10-18/claude-projection/README.md).
+- **#91 decision inputs delivered** ([note](../evaluation/s5-decision-inputs-2026-10-18/bounded-wait.md));
+  decision deferred until the A/B. No `waitMs`, no `pi_turn_wait`.
+- **#92 research delivered** ([note](../evaluation/s5-decision-inputs-2026-10-18/worker-usage.md));
+  usage is per assistant response, a per-turn aggregate is not provided by the
+  SDK. No contract change.
+- **#93 proposal delivered, unapproved** ([package](../evaluation/m1-ab-proposal-2026-10-18/README.md)):
+  3 pairs, order A/B, B/A, A/B; 18 fresh controller invocations, 24 worker
+  starts, 30 work turns, 0 retries. Prerequisites P1–P3 (skill tree binding,
+  worker skill selection, client version) were implemented in the follow-up,
+  provider-free only.
+
+## Measured bytes (not tokens)
+
+From the [tool-definition evidence](../evaluation/tool-definitions-2026-10-18/README.md):
+
+| Measure | Base | After #88 | After #90 |
+| --- | ---: | ---: | ---: |
+| `tools/list` frame | 19,962 | 20,217 | 19,143 |
+| `tools` array | 19,917 | 20,172 | 19,098 |
+| Eight pi definitions (name, description, input schema) | 3,616 | 3,871 | 2,797 |
+
+The 2,246 bytes quoted in #88/#90 were not reproduced and are bound by no
+committed evidence; the committed Codex figure of 21,412 bytes is the whole
+client tools array including Codex's own tools. The actual Codex projection
+before and after was an open gate at first; the follow-up measured it. On the provider-free Claude Code bare route (probe attempts 2 and 3)
+the request `tools[]` went from 7,144 to 6,325 bytes (−819) and the first
+request body from 11,608 to 9,004 bytes; the 1,785-byte remainder is
+unexplained. Bytes are not tokens. Live token effect of any change in this
+sprint: unmeasured.
+
+## Verification and review
+
+See [Acceptance](../acceptance.md#sprint-5-provider-free-checks-2026-10-18):
+full suite (67 files, 1,531 passed, 6 skipped), builds, evaluation plan,
+offline harness and schema checks, package listing, diff check and Level 2
+setup acceptance (160 of 160) ran once on the integrated head `87bde7a`. Seven
+review findings were fixed afterwards and only the affected checks were
+repeated on the final code.
+
+## Cleanup
+
+Two Pi sessions were started (`review` for #92, `review-grok` for the final
+review); both were closed and `pi_session_list` was checked at the end. agy
+runs end with their process. Writer clones and the probe's owned temporary
+directories live outside the repository; the probe verified its own removal.
+The main checkout was detached for the frozen review and returned to `main`.
+
+## Follow-up on the same day
+
+After the PR opened, the maintainer asked to close the open points; agy now runs
+with its auto agent mode and terminal sandbox from its own settings. Writers again
+used separate full clones from the PR head `08b40f2`.
+
+| Task | Issue | Owner / route | Result |
+| --- | --- | --- | --- |
+| Codex projection | #88, #90 | integrator | Probe accepts an explicit list of exact versions (0.162.0, 0.162.1) and sizes the projected pi entries. Codex 0.162.1, before/after, 16 of 16 each, `PASS`: whole `tools` 21,412 → 21,667 bytes, pi entries 2,266 → 2,521 bytes (+255 from #88). Codex already drops `pattern` and `format`, so #90 does not change the Codex projection |
+| Proxy `server/discover` | #89 | Claude implementer | The pinned MCP SDK defines `server/discover` (revision 2026-07-28); the M1 proxy forwards exactly that request form and counts it; other methods stay fatal. Not run end to end behind the proxy |
+| Tool search (q3) | #89 | Claude implementer | Non-bare route, same scrubbed environment, confirmed again inside a loopback-only network namespace: with tool search on, the fixture tool is deferred (`defer_loading`) and loaded by one extra search request; first `tools[]` 50,363 → 27,472 bytes. Bytes, not tokens |
+| A/B prerequisites P1–P3 | #93 | agy (Gemini 3.8 Flash), integrator fix | Whole controller skill tree bound and embedded; optional worker skills bound by tree digest and loaded from the verified source paths (integrator fix: the evaluation build has no `skills/`); controller version bound from the decision. Arm A needs its own commit with the final harness and the old skills and server |
+| Main checkout | — | integrator | `npm ci`: `node_modules` now holds Pi SDK 1.2.0 |
+| #79 decision | #79 | maintainer, integrator | ADR 0008 accepted for Linux (option 1); review point 2026-11-15; acceptance tooling and [runbook](../isolation-setup.md) added (uncontained control: 18 of 18 escapes detected, all canaries removed); Podman not installed, so no contained run yet; writer alias `pi-session-mcp-w1` on a full clone configured |
+| #93 probe | #93 | integrator | Option C approved (one pair, 10 USD advisory, unmetered acknowledged). [Attempt 1](../evaluation/m1-ab-proposal-2026-10-18/probe/attempt-1/README.md) failed: no `openai-codex` login here. Worker provider made a bound option; [attempt 2](../evaluation/m1-ab-proposal-2026-10-18/probe/attempt-2/README.md) on `openai`: arm A L1 passed, L2 repaired correctly without a JSON receipt; [attempt 3](../evaluation/m1-ab-proposal-2026-10-18/probe/attempt-3/README.md) without worker skills failed the same way, which falsified the skill explanation: the T2 implementer prompt asks for no JSON receipt, while the harness accepts only a JSON-only answer. Stopped; arm B never ran |
+
+After the operator approved fixing the receipt contract (the T2 implementer
+prompt now asks for one JSON object), [probe attempt 4](../evaluation/m1-ab-proposal-2026-10-18/probe/attempt-4/README.md)
+passed in both arms, and the approved four-pair wave ran: eight runs, all `PASS`
+([results](../evaluation/m1-ab-proposal-2026-10-18/results/README.md)). #91 now has
+a proposed decision: no bounded wait now, trigger C restated with the cost
+dimension.
+
+The new Doctor check ran on macOS 15 and macOS 26 in the PR's CI (its 18 tests
+are part of the suite); no run on a real Mac.
+
+## Gates for later sprints
+
+- #79 decision before any isolation work.
+- #93 approval (P1–P3 are implemented; the arm-A commit still has to be created)
+  before the A/B.
+- A/B results before the final #91 decision.
+- A public contract decision before any minor-release work (`waitMs`, usage
+  fields, compact results).
+
+## Prepared R22 text (not applied)
+
+The project instructions in the operator's ChatGPT project still describe 0.8.1
+and SDK 1.1. Replace them with the
+[Sprint 4 appendix text](2026-10-15-s4-decision.md#appendix-proposed-chatgpt-project-instructions-r22)
+plus this paragraph. This repository cannot apply or check that change.
+
+```text
+Sprint 5 (docs/sprints/2026-10-18-s5-maintenance-orchestration.md) added, unreleased
+on main after its PR merges: a Doctor gitfile warning (#81), consume-once polling and
+an on-demand start-error reference in the orchestration skill (#86), concise worker
+reports (#87), tool-description hints (#88) and slimmer input schemas (#90), all
+without a public contract change. Open decisions: #79 isolation (ADR 0008 Proposed),
+#93 A/B approval, then #91 bounded wait; #89 and #92 are research items. The M1 pilot
+measured Codex controller usage only; worker usage and money cost are unknown.
+```

package/docs/sprints/2026-10-21-s6-ledger-event-bridge.md

@@ -0,0 +1,120 @@
+# Sprint 6: ledger, event bridge and controller rewake (evaluation)
+
+Date: 2026-10-21. Base: main `0922d98f0fb33d3c493dc428dfef932443bfa4fa` (merge of
+PR #103), package 0.10.0, Pi SDK 1.3.0, MCP SDK 2.3.1. Tracking:
+[#104](https://github.com/plagor44-ux/pi-session-mcp/issues/104).
+
+A bounded, development-only evaluation added at the operator's explicit request
+of 2026-10-21. It does not replace the maintenance priorities: the isolation
+rollout and acceptance under #79 (ADR 0008, ADR 0009; review point 2026-11-15)
+stays the next investment, and the open #89 q4 item keeps its own gate.
+
+## Question
+
+How should a controller monitor one or more running Pi worker sessions and keep
+their state traceable? Does a ledger (`task.md`, `run.json`, OMO Boulder) help,
+and can repeated status polls by the controller model be reduced without a
+persistent workflow server? The outcome was open; "the current procedure is
+enough" was an admissible result.
+
+## Authorization and limits
+
+In scope: inventory and options comparison; a provider-free evaluation
+prototype outside the runtime path (`eval/bridge/`), including completion
+events and a structured question round trip; a ready-to-run live measurement
+plan; documentation and review.
+
+Not authorized and not done: public MCP contract changes, production
+persistence, changes to registrations, credentials or permissions, release, tag,
+publication or merge. Live provider runs were not part of the original scope.
+Later the same day the operator approved two L1 pairs, which ran (see
+*Gates*). The prototype writes only
+synthetic local state into temporary directories.
+
+## Preflight (2026-10-21)
+
+- `origin/main` = `0922d98`; latest release v0.10.0; no open pull requests; open
+  issues: #79 only. Issues #86, #89, #91, #92 and #93 were read with comments.
+- A parallel Claude Code session works on the unpushed branch
+  `eval/extension-ablation-design` in the main checkout (owner of
+  `eval/extensions/**` and `~/.cache/pi-session-mcp/extension-ablation/`). It
+  was asked first; file ownership is disjoint. This sprint ran in its own
+  worktree on branch `eval/ledger-event-bridge` and did not touch that checkout,
+  its cache directory or any running MCP server.
+- Installed clients: Claude Code CLI 2.1.303, VS Code extension 2.1.304, Codex
+  0.162.1; Node 26.11.1.
+
+## Routes and ownership
+
+| Package | Route | Scope | Result |
+| --- | --- | --- | --- |
+| A1 Pi SDK semantics | Claude general-purpose subagent, read-only | installed 1.3.0 sources and docs | delivered; key facts rechecked by the faux-provider test |
+| A2 registry and adapter | integrator | `src/` read-only | delivered |
+| B client capabilities | Claude researcher, official docs | hooks, MCP, channels, spec, Codex | delivered; the rewake edge rechecked by a spike and the probe |
+| C0 Boulder | Claude researcher | oh-my-openagent `dev` | delivered (summarized reads, marked) |
+| C1 ledger, store, CLI | Claude implementer | `eval/bridge/ledger*.ts`, `test/bridge-ledger.test.ts` | implemented; integrator fix for unconsumed results on connection loss |
+| C2 bridge, broker, scripted adapter, faux test | Claude implementer | `eval/bridge/{bridge,questions,ask-tool,scripted-adapter}.ts`, two tests | implemented |
+| C3 host adapter and client probe | Claude implementer | `eval/bridge/{server-main,hook-waiter,hook-ledger,claude-probe,cli}.ts`, hook tests | implemented; probe attempts 1–3 by the implementer and integrator, attempt 4 by the integrator after the review fixes |
+| A3 abort during a tool | Claude general-purpose, scratch test not committed | real `SdkPiSessionAdapter` | `aborted` in 60 of 60 runs per variant; order-dependent |
+| D pre-registration and live plan | integrator | `docs/evaluation/ledger-event-bridge-2026-10-21/` | fixed before comparative runs (commit `569c89f`) |
+| E1 independent review | Pi worker, `review-grok` (read-only), alias `pi-session-mcp` reading only this worktree | frozen head `1289137` | 5 findings; session closed |
+| E2 independent review | Claude reviewer (Opus 5.5) | frozen head `1289137` | 7 findings; two reproduced |
+| F review fixes | Claude implementer, then integrator | `eval/bridge`, tests, docs | fixed; 91 tests |
+
+No Pi worker wrote code: the only workspace alias for this repository points at
+the operator's main checkout, which the parallel session uses. Writers never
+shared files. Controller-side session and turn IDs were kept only transiently.
+One Pi session was started (E1) and closed; none is left open.
+
+The first worktree lived under the main checkout (`.claude/worktrees/`). The
+parallel session reported that its vitest run then collected this worktree's
+tests and one sub-run failed. The worktree was moved outside the repository
+once the reviewers had finished.
+
+## Results
+
+See the [evaluation report](../evaluation/ledger-event-bridge-2026-10-21/README.md).
+
+## Gates for later work
+
+- Any product change following this evaluation (a registry completion observer,
+  a local event spool or socket, a client hook installed by setup, a question
+  tool) needs its own decision record, and a public tool or field needs a
+  minor release.
+- Two approved L4 pairs ran on 2026-10-21 ([results](../evaluation/ledger-event-bridge-2026-10-21/live/README.md)).
+  Any further live run needs a new, explicit operator approval.
+- ADR 0011 was accepted by the maintainer on 2026-10-21, items 1–3. The
+  implementation is
+  [#108](https://github.com/plagor44-ux/pi-session-mcp/issues/108), gated by
+  approval of its plan.
+
+## Closure (status as of 2026-10-24)
+
+The sections above record the evaluation as it ran on 2026-10-21 and are not
+rewritten. What happened afterwards, kept apart:
+
+1. **The evaluation and its recommendation (2026-10-21).** The pre-registered
+   product rule was not met (requests 7/8 and 8/8, mixed uncached input and
+   cost). The evaluation recommended deferring ADR 0011: keep the current
+   procedure, no ledger, no supervisor. It measured one clear gain, reaction
+   time (about 2 s against 10-21 s). The sprint changed no product code.
+2. **The later maintainer decision (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 the gate and the recommendation.
+   Item 4 (structured question channel) is not decided.
+3. **What shipped (outside this sprint).** The completion bridge only: opt-in
+   spool delivery plus a setup-installed Claude Code wake hook, implemented in
+   [#110](https://github.com/plagor44-ux/pi-session-mcp/pull/110) for
+   [#108](https://github.com/plagor44-ux/pi-session-mcp/issues/108) and released
+   as 0.11.0 on 2026-10-22 (Linux only). Fixes: 0.11.1
+   ([#113](https://github.com/plagor44-ux/pi-session-mcp/issues/113), delivery
+   stays inactive without `XDG_RUNTIME_DIR`) and 0.11.2 (#109 and #117, not part
+   of this feature). A file ledger and a supervisor are not product features;
+   `eval/bridge/` stays an evaluation prototype. The token and cost saving for
+   long turns remains unmeasured.
+
+The isolation work under #79 kept its priority and its review point of
+2026-11-15. Operator checks that are still open (wake in the VS Code extension,
+whether a running session loads a newly installed hook, a wrapped container
+writer with delivery under rootless Podman including the extra-mount isolation
+check) are tracked in the [roadmap](../roadmap.md), not in this sprint.