Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

docs(mcp): rewrite mcp-channel.md for channel sessions in panes

Jack Rudenko00e1c3f30eeb
diff --git a/ai-docs/architecture/mcp-channel.md b/ai-docs/architecture/mcp-channel.md
index 2ee24cc6..5d97b26f 100644
--- a/ai-docs/architecture/mcp-channel.md
+++ b/ai-docs/architecture/mcp-channel.md
@@ -1,4 +1,4 @@
-> The 12-tool surface, the channel wire format, client-side gating conditions, and the progress keepalive.
+> The 14-tool MCP surface, the channel sessions behind it, the channel wire format, client-side gating conditions, and the progress keepalive.
>
> Extracted from `CLAUDE.md` (v7.64.0). Indexed in [`README.md`](./README.md).
@@ -12,145 +12,129 @@ Uses the low-level `Server` class (not `McpServer`) from `@modelcontextprotocol/
## Components (`packages/cli/src/channel/`)
-- **SessionManager** — spawns the child, tracks lifecycle, enforces timeouts, owns stdin
-- **StreamJsonReducer** — per-session state machine driven by the child's own NDJSON frames
-- **ScrollbackBuffer** — in-memory ring buffer (2000 lines), holding recovered PROSE
-
-### The transport: bidirectional stream-json over pipes
-
-The child is spawned with, in this exact order:
-
-```
-claudish --model X -y --verbose --quiet -p \
- --output-format stream-json --input-format stream-json \
- --include-partial-messages --include-hook-events --replay-user-messages \
- --session-id <uuid> [caller flags…]
-```
-
-which reaches `claude` as `-p --output-format stream-json --input-format stream-json
---include-partial-messages --include-hook-events --replay-user-messages --session-id <uuid>
---verbose --dangerously-skip-permissions` (measured 2026-08-22, claude 2.1.239).
-
-Three properties of that argv are load-bearing and each fails silently:
-
-- **`--verbose` BEFORE `--quiet`.** claudish consumes `--verbose` as its own log-verbosity
- flag AND separately forwards a copy to `claude`, which hard-errors on
- `--print --output-format stream-json` without it. Reversed, every child narrates onto
- stderr. Same rule as `team-orchestrator.ts:957` ("ORDER IS LOAD-BEARING").
-- **`-p` present, and followed by a FLAG.** Without it and without `--stdin`, `cli.ts:667`
- sees no positional prompt and launches the interactive picker. Unknown flags consume the
- next token as a value unless it starts with `-`.
-- **`--stdin` ABSENT.** That is what opens the channel: nothing in claudish consumes fd 0,
- and `claude` is spawned `stdio: "inherit"`, so `proc.stdin` in `SessionManager` lands
- directly on `claude`'s fd 0 with no relay code. This is what makes `send_input` work —
- it never worked before, because the bytes went into an already-satisfied `readStdin` drain.
-
-`RESERVED_CHILD_FLAGS` in `session-manager.ts` rejects a caller-supplied duplicate rather
-than appending it; `create_session`'s `claude_flags` are otherwise passed through verbatim.
-Two properties of that guard are themselves load-bearing:
-
-- **The set is DERIVED from `buildChannelSpawnArgs`**, plus `RESERVED_FLAG_ALIASES` and
- `--stdin`. The hand-listed version drifted immediately: it had `--verbose` but not `-v`,
- and no `--model` at all — so `-v` walked past a guard built specifically to stop the
- `--verbose` collision, and `--model` could silently run a different model than
- `SessionInfo.model` reports. Every alias in that map is a spelling `cli.ts`'s own parser
- accepts (`--model`/`-m`, `--auto-approve`/`-y`, `--quiet`/`-q`, `--verbose`/`-v`,
- `-p`/`--print`). Anything added to the spawn argv is reserved automatically.
-- **The match is EXACT-TOKEN, never a prefix** (long `--flag=value` is split first).
- `--print-argv`, `--model-opus`, `--model-sonnet` and `--agents` are all real, unrelated
- flags a `startsWith` guard would eat — and `--print-argv` is what the argv-ordering
- regression test uses.
-
-**Deltas are consumed and discarded.** `--include-partial-messages` produces 20–60 k
-`stream_event` frames per long session (5–14 MB). They reset a liveness watchdog and are
-then dropped: storing them would evict all 2000 scrollback lines in seconds. Semantic
-frames go to `<sessionDir>/events.jsonl`; recovered prose goes to the scrollback and
-`output.log`; `get_output` returns prose, never raw NDJSON.
-
-**Terminal state has to be earned.** `result.terminal_reason` / `is_error` /
-`api_error_status`, cross-checked with `classifyRunOutput`. Exit 0 with no `result` frame,
-or with zero output bytes, is `failed`. Terminal states are absorbing — a process exit can
-never upgrade a verdict the timeout or cancel handler already recorded.
-
-**The witness is scoped to the CURRENT turn.** `reducer.beginTurn()` runs on every frame
-written to the child's stdin and clears `sawResult` / `resultIsError` / `apiErrorStatus`
-(cumulative accounting is untouched). Without it the witness latches for the life of the
-session: turn 1 answers, `send_input` starts turn 2, the child dies mid-turn and exits 0 —
-and turn 1's `result` marks turn 2 completed. That is the original bug's shape, a session
-reporting success on evidence that does not belong to it.
-
-**Finalisation waits for the pipes, not for `exit`.** `exit` fires BEFORE stdout closes,
-and the `result` frame is by construction the LAST line the child writes — so it is exactly
-the frame still in flight at that moment. `handleExit` therefore only records
-code/signal/timestamp; `finalize()` runs when both stdio pipes have emitted `close`, or
-after `DRAIN_TIMEOUT_MS` (10 s), whichever comes first. That constant used to live in
-`team-orchestrator.ts` and be imported from here; it moved into `session-manager.ts` when
-`team` stopped terminating children and therefore stopped needing to drain them
-(see `team-lifecycle.md`). The channel is now its only user. Classifying on `exit` reported a
-complete, billed run as *"exited 0 without ever emitting a terminal `result` frame"*,
-nondeterministically. The stdio decoders are `StringDecoder`s for the same reason a chunk
-boundary must not be trusted: `Buffer.toString` turns a multi-byte character split across
-two reads into U+FFFD before the reducer ever sees the line.
-
-**Persistence is redacted and bounded.** `events.jsonl` is `redactSecrets`-filtered per line
-and capped at 4 MB (`{"type":"claudish_truncated"}` marks the cut); `stderr.log` is redacted
-at write time; the in-memory stderr keeps 32 KB of HEAD plus 32 KB of TAIL — both ends,
-because startup diagnostics like `[claude-code:unrecognized_model]` are at the head and the
-failure that killed a long run is at the end. These files carry `user` turns and
-`tool_result` blocks, and `get_diagnostics` names them for an agent to read.
+- **SessionManager** — the channel's policy and records: creates sessions, owns the queue of
+ `send_input`, decides a turn's verdict, writes the session records, enforces `timeout_seconds`
+- **PaneSession** (`packages/cli/src/pane/`) — the mechanism: one interactive Claude Code in its
+ own headless magmux pane, with the transcript as its turn oracle. Team uses the same driver
+- **ScrollbackBuffer** — in-memory ring buffer (2000 lines), holding each settled turn's answer prose
+
+### The transport: an interactive Claude Code in a headless magmux pane
+
+Each session is `claudish -i --model <spawnModel> -y --quiet --session-id <uuid> --add-dir
+<turnDir> [caller flags]` inside its own `magmux --headless` pane, driven over the pane's socket.
+There is no `-p`, no `--stdin`, no stream-json and no positional prompt. Until 10.4.0 the child was
+`claudish -p --output-format stream-json --input-format stream-json …` with its stdin held open for
+`send_input`; that transport and its reducer were deleted because print mode is not a faithful
+subset of the REPL (`headless-vs-interactive.md`): it skips `--agent` validation silently, and an
+interactive Claude Code is what users actually run.
+
+Everything about the pane — boot, the transcript turn oracle and its settle paths, prompt delivery
+by file with read coverage, the child's environment, the watcher and the identity-checked reap,
+the socket traps, the frozen mod contract — is in [`pane-session.md`](pane-session.md). This file
+covers what the channel adds on top.
+
+**`claude_flags` are checked before anything starts** (`checkChildFlags`, shared with `team`):
+claudish's own pane argv, transport breakers (`-p`, `--output-format`, `--input-format`, `--stdin`,
+`--bg`, …), session breakers (`--resume`, `--continue`, `-w`, `--no-session-persistence`, …),
+print-only Claude Code flags (`--max-turns`, `--max-budget-usd`, `--fallback-model`,
+`--json-schema`, `--permission-prompt-tool`, which an interactive child would silently ignore),
+claudish mode flags, claudish subcommand words, and any positional token or `--`. The match is
+exact-token after splitting `--flag=value`, and the positional rule is claudish's own
+value-consumption rule (`classifyPassthroughTokens`, pinned against `parseArgs` by a table test).
+A refusal is an `invalid_args` error before any credential work. `create_session`'s `agent`
+argument becomes `--agent <name>`; an unknown name is refused by the child itself (FAILED
+`agent_rejected`), so claudish runs no agent probe of its own.
+
+**A session is created in this order**: the flag check, `assertMagmuxAvailable` (magmux ≥ 0.14.0,
+else `Error: magmux_unavailable: …`), credential pre-hydration, the parent proof, a pane
+reservation (`Error: pane_limit: …` past 48 live panes per user), `prompt.md`, `spawn.json`, then the
+pane. `create_session` returns `{session_id, state}` once the pane exists, without waiting for boot.
+A pane that fails to start leaves a FAILED `pane_lost` session with its `meta.json`, and the call
+fails.
+
+**The verdict is the owner's (D8).** A one-shot session's settled turn is classified by
+`classifyRunOutput` with no byte floor and no pattern (`api_error`, `prompt_not_read`, `refused`,
+`empty_output`), and the session is terminal at that verdict, before its pane is reaped. An
+interactive session continues after each turn and fails only on an API-error turn (D20); a turn
+whose task file was not fully read records the anomaly and `meta.prompt_not_read` on the next
+frame. A question or a permission dialog waits for `send_input` (team fails it instead).
+Terminal states are absorbing: a late pane exit can never upgrade or overturn a CANCELLED or
+TIMEOUT already recorded.
+
+**The witness is scoped to the CURRENT turn**, by construction: the follower marks the transcript
+offset before each delivery and turn N owns only the records past its own offset. Turn 1's answer
+can therefore never mark turn 2 completed — the original bug's shape, a session reporting success on
+evidence that does not belong to it.
+
+**`send_input` is queued (D17).** It is accepted in every non-terminal state: STARTING and RUNNING
+queue it, AWAITING_INPUT delivers it at once, and during a question or permission dialog claudish
+presses Esc — which declines the dialog AND interrupts the turn — and delivers the text as the next
+prompt. Any accepted send makes a one-shot session interactive. The answer is
+`{success:true, queued}` or `{success:false, reason, state}` with `reason` one of `terminal`,
+`delivery_unavailable`, `unsupported_command`, `unknown_session`.
+
+**Persistence is redacted and bounded.** `output.log` holds each settled turn's answer prose, plus
+claudish's own `[claudish] <STATE> <reason>: <detail>` note on a session that did not complete.
+`events.jsonl` holds claudish's own records — `state` transitions, `tool` changes, `anomaly` keys and
+one `{type:"assistant", message:{id}, at}` line per main-chain message id — `redactSecrets`-filtered
+per line and capped at 4 MB (`{"type":"claudish_truncated"}` marks the cut); message content is not
+copied, because the transcript already holds it. `screen.txt` is the pane's final screen, redacted,
+written at the terminal transition. These files and the transcript are what `get_diagnostics`
+names for an agent to read.
**Terminal sessions are evicted.** `maxSessions` bounds only ACTIVE sessions, so finished
ones used to accumulate for the life of the MCP server. A terminal session leaves the map
after `terminalRetentionMs` (default 30 min), with a hard ceiling of 50 retained. On-disk
-artifacts are unaffected.
-
-**`shutdownAll` uses `terminateChildTree`, and never cancels an escalation it does not
-replace.** Liveness is `exitCode`/`signalCode`, not `proc.killed` — `signalProcessTree` sets
-`killed` the moment a signal is SENT, so a child that ignored SIGTERM (the only kind that
-needs escalating) read as already dead and was skipped, while the pending SIGKILL from a
-`cancel_session` five seconds earlier was cleared. The detached process GROUP kept running
-and billing. Non-terminal sessions are settled `cancelled` BEFORE their reducer is disposed,
-or the exit that follows writes a `meta.json` still claiming the session was running.
-
-**`"timeout"` is now a first-class wire event — the record and the channel agree.**
+artifacts are unaffected, and `getSession`, `get_output` and `get_diagnostics` fall back to the
+session directory (both generations of `meta.json`: 10.4.0's `status`-only record and the pane
+one). The mutators — `send_input`, `cancel_session`, `capture_session` — never do: a recovered
+record describes a process that is gone, and they answer `unknown_session`.
+
+**Shutdown ends the records, then reaps.** At startup the MCP server installs the pane shutdown
+hooks with `stdin: true`: stdin EOF or close (the host closed the transport), SIGINT, SIGTERM and
+SIGHUP first run `shutdownAllTeamRuns()` and `SessionManager.shutdownAll()` — every live session is
+cancelled and its terminal transition writes the closing wait line and `meta.json` — and only then
+reap every pane in parallel and exit (0 on stdin, 128 + n on a signal). `shutdownAll` waits for
+starts still in flight first; one that was skipped would run on unsettled. `stats-buffer.ts`'s
+module-load signal listeners used to exit synchronously before any record was ended;
+`signal-owner.ts` lets the pane registry claim the exit. After a SIGKILL no record ends, but the
+per-pane watchers still remove every process and file.
+
+**`cancel_session` is a synchronous transition with an asynchronous reap.** It returns
+`{session_id, state:"CANCELLED", changed}` at once; the pane close and the process-group reap finish
+in the background (worst case ≈ 12 s). A second call returns the same state with `changed:false`.
+
+**`"timeout"` is a first-class wire event — the record and the channel agree.**
They diverged until Phase 3: `EVENT_TO_TASK_STATUS` had no `"timeout"` key and fell
through to `?? "working"`, so emitting the real event reported a *dead* session as still
working. The timeout path therefore recorded `"timeout"` and emitted `"failed"`, and a
consumer watching only the channel could not tell "ran out of time" from "errored".
`["timeout", "failed"]` now exists in that map (SEP-1686 has no `timeout` member; `failed`
-is its only honest projection), so `ChannelEventType === SessionStatus`, `LEGAL_TRANSITIONS`
-has an absorbing `timeout` row, and `ReducerEvent.sessionStatus` — the override that carried
-the divergence — is gone. **Mutation-proven**: remove the map key and a timed-out session
-goes back to `status: "working"` on the wire.
-
-**Session shape follows the prompt.** `create_session` WITH a prompt is one-shot: stdin is
-closed on the first `result`, the session is `finishing` until the child exits 0, then
-`completed`. WITHOUT a prompt it is interactive: stdin stays open, the session is in
-`waiting_for_input` from creation and again between turns, and it ends on `send_input` → …
-→ `cancel_session` or the timeout. A `send_input` call converts a one-shot session to
-interactive.
-
-**`waiting_for_input` means a real wait, and nothing else.** It holds iff claudish holds the
-child's stdin open and the child has finished a turn no `send_input` has followed yet, or a
-promptless session has received no input yet. Before `finishing` existed, every `result` frame moved the
-reducer there, including a one-shot's last one, and `handleResult` closed stdin a moment
-later — so every one-shot session emitted an `input_required` nothing could answer. The turn
-end is now the OWNER's decision: `StreamJsonReducerOptions.onResult` is required and returns
-`TurnEnd` (`"stdin-open" | "stdin-closed"`), and `applyResultFrame` asks it BEFORE
-transitioning, to `waiting_for_input` or to `finishing`. `finishing` (non-terminal) admits
-only terminal successors; a late `assistant`/`user` frame there is refused and recorded as an
-anomaly (`get_diagnostics`). It projects to SEP-1686 `working`, and `checkStall` leaves it
-unwatched — the session timeout bounds it. `team` closes stdin at spawn, so its reducer
-always answers `"stdin-closed"`: a slot reads `finishing` between its `result` and its exit.
-A promptless session enters `waiting_for_input` through `awaitInput()` at creation; its
-`system:init` frame does not move it, and `beginTurn()` (every `writeFrame`) moves it to
-`running`.
+is its only honest projection). The map is now built from a `Record<ChannelEventType, TaskStatus>`
+over the runtime list `CHANNEL_EVENT_TYPES`, so an event type without a projection is a compile
+error, and `awaiting_permission` (a dialog only `send_input` can move on) projects to
+`input_required` instead of falling through to `working`. **Mutation-proven**: remove the timeout
+key and a timed-out session goes back to `status: "working"` on the wire.
+
+**Session shape follows the prompt.** `create_session` WITH a prompt is one-shot: it is terminal
+at the verdict of the turn that prompt started. WITHOUT a prompt it is interactive: it waits in
+`waiting_for_input` once Claude Code has booted and again after every turn, and it ends on
+`cancel_session`, the timeout, or the child exiting 0 after `/exit` or a settled turn. A
+`send_input` call converts a one-shot session to interactive.
+
+**`waiting_for_input` means a real wait, and nothing else.** It holds iff the session is idle at
+an empty input box between turns, or a turn is blocked on a question; `awaiting_permission` iff a
+permission or plan-approval dialog is open. A one-shot session is terminal at its verdict, so there
+is no "answered but still exiting" state for a wait to be confused with — 10.4.0's `finishing`
+channel event is gone with the transport (RB1). The wait for Claude Code's end-of-turn record after
+the model's message ends survives only as `activity:"finishing"` on a RUNNING session. A
+promptless session's first wait opens at boot-ready, not at creation: before boot a send is queued,
+not answered (RB2).
### `waits.jsonl` — the wait log
-`<sessionDir>/waits.jsonl` gets one line per transition INTO `waiting_for_input` and one per
-transition OUT of it (terminal states included), written in the reducer callback that changes
-the state:
+`<sessionDir>/waits.jsonl` gets one line per transition INTO a wait (`waiting_for_input` or
+`awaiting_permission`) and one per transition OUT of it (terminal states included):
```jsonc
{"wait":"open","since":"2026-10-02T10:03:12.000Z","turns":1}
@@ -158,20 +142,28 @@ the state:
```
`since` keys the wait (the `closed` line repeats it); `turns` is `turnsCompleted` at the
-open. It is append-only because an observer polling the directory (the magus `claudish`
-plugin monitor) must see a wait that opened and closed between two of its reads — a marker
-file that exists only during the wait cannot give it that. `finalize` settles before
-`writeArtifacts`, so a live writer never leaves an open wait beside a `meta.json`. One
-`appendFileSync` of < 200 bytes per line; a write failure goes to stderr and loses only that
-line; the file stops at 1 MB. A one-shot session never writes one.
+open; `to` is the channel event of the new state, never another wait (the phase table has no
+wait-to-wait edge). It is append-only because an observer polling the directory (the magus
+`claudish` plugin monitor) must see a wait that opened and closed between two of its reads — a
+marker file that exists only during the wait cannot give it that.
+
+The writer is the pane's `onTransition` hook: synchronous, every wire-state change, never
+coalesced, and called BEFORE the channel frame, so the line is on disk by the time anyone hears of
+the wait. It reports the net change of one event-processing step, so a turn that settles with a
+send already queued (RUNNING → IDLE → ADMITTING in one step) opens no wait. The terminal transition
+closes any open wait before `meta.json` is written, so a live writer never leaves an open wait
+beside a `meta.json`. One `appendFileSync` of < 200 bytes per line; a write failure goes to stderr
+and loses only that line; the file stops at 1 MB. Interactive sessions write one, and a one-shot
+session writes one only when it stops on a question or permission dialog (RB3) — in both cases the
+right action is `send_input`.
### `spawn.json` — the start-time record, and who started the run
-`createSession` writes `<sessionDir>/spawn.json` after `prompt.md` and BEFORE `spawn()`,
+`createSession` writes `<sessionDir>/spawn.json` after `prompt.md` and BEFORE the pane starts,
atomically (`spawn.json.tmp` + rename), one key per line, and NOT inside a `try`: a session
that cannot be recorded fails the tool call rather than run unrecorded. It exists before
-every runtime file (`output.log`, `events.jsonl`, `tokens.json`, `waits.jsonl`, `meta.json`)
-and is never removed.
+every runtime file (`output.log`, `events.jsonl`, `tokens.json`, `waits.jsonl`, `screen.txt`,
+`meta.json`) and is never removed.
```jsonc
{
@@ -191,6 +183,9 @@ and is never removed.
It exists for observers OUTSIDE this process — the magus `claudish` plugin monitor polls the
sessions directory and reports progress to the Claude Code window that started a run.
+`claudeSessionId` is the pane's `--session-id` uuid, the transcript's basename. For a pane session
+`mcpPid` is also the pane record's owner, and the watchers make the monitor's liveness inference
+sound: when the writer dies, its panes die with it.
**`hostPid` is structural, computed once at startup** (`hostPidFrom`, `channel/parent-proof.ts`).
A compiled binary or `bun src/index.ts` is the direct child of Claude Code, so `hostPid` is
@@ -198,7 +193,9 @@ A compiled binary or `bun src/index.ts` is the direct child of Claude Code, so `
dist/index.js`, so the launcher puts `CLAUDISH_LAUNCHER_PID` (itself) and
`CLAUDISH_LAUNCHER_PPID` (its parent) in the child's env, and the child believes the pair only
when `CLAUDISH_LAUNCHER_PID` is its real `ppid` — a pair leaked into a nested claudish is
-inert. `launcherPid` is recorded exactly when that branch ran. No `ps`, no tree walk.
+inert. `launcherPid` is recorded exactly when that branch ran. No `ps`, no tree walk. The pane
+environment strips the pair and `CLAUDE_CODE_SESSION_ID`, so a claudish MCP server nested inside a
+pane cannot inherit the host's identity either.
**`parentClaudeSessionId` is proven per call, or absent** (`proveCallingConversation`). The
environment's `CLAUDE_CODE_SESSION_ID` goes stale on `/clear`, on a resume, and whenever two
@@ -217,8 +214,30 @@ absent; a hit returns at once, so a call whose record is already on disk waits f
single 250 ms retry this replaced lost that race in 2 of 3 calls in one session. A tool-use id is unique and lives only in the transcript of the
conversation that issued it, so a hit is proof and every failure degrades to "absent". It is
`await`ed with `fs/promises` before `createSession`, so the server keeps pumping live sessions
-while it looks. `meta.json` (`SessionInfo.parentClaudeSessionId`) carries the same key with the
-same value exactly when `spawn.json` does.
+while it looks. `meta.json` carries the same key with the same value exactly when `spawn.json`
+does.
+
+### `meta.json` — the final record, and `events.jsonl`'s assistant lines
+
+`meta.json` is written once, at the terminal transition and before the pane is reaped, through
+`toMetaRecord`. It keeps every 10.4.0 key under its 10.4.0 name, because the monitor reads
+`status` (an unknown value reads as `failed`), `terminalReason`, `elapsedSeconds`,
+`turnsCompleted`, `toolCallCount`, `costUsd` and `exitCode`:
+
+- `status`: COMPLETED → `completed`; FAILED and EMPTY → `failed`; CANCELLED → `cancelled`;
+ TIMEOUT → `timeout`;
+- `terminalReason` is the contract's `FailureReason` (null on COMPLETED), not Claude Code's own
+ text; `costUsd` is null for native routes (no fictional spend, D12); `exitCode` is null when
+ claudish ended the pane — a pane's exit code exists only if the child exited on its own (RB4);
+- additive keys: `state` (tells EMPTY from FAILED), `detail`, `tokensIn`, `tokensOut`,
+ `lastActivityAt`, `shape`, `pane`, `provider`, `captureSource`, `turnSource`, `timeoutSeconds`,
+ and `cwd` (needed to re-derive a stored transcript path; a 10.4.0 record without it keeps its
+ stored path). A `SessionInfo` key that would repeat a pinned key (`toolCalls`, `reason`,
+ `panePid`) is written only under the pinned name, so the record never carries two names for one
+ fact.
+
+`events.jsonl` carries one `assistant` line per main-chain message id, first-seen order, each once,
+which is exactly what the monitor counts as replies (RB5).
### Diagnostics are captured unconditionally, and reachable from the API
@@ -227,39 +246,40 @@ tokens, 150 tool calls — and reported success with an empty output log. The wh
explanation was one line, written to `~/.claudish/sessions/<id>/stderr.log` and left there:
`[claude-code:unrecognized_model] {"model":"[email protected]"}`. No MCP tool returned it.
**A failure that has already happened cannot be re-run with `--debug`**, so nothing here is
-opt-in.
-
-- **`get_diagnostics(session_id, event_limit?)`** returns the redacted stderr, the upstream
- error bodies, the tail of the semantic-event ring, the token/cost record, `exitCode` /
- `terminalReason` / `outputBytes` / `elapsedSeconds` / `timeoutSeconds`, the resolved
- transcript path, **both halves of the model chain** (`model` as asked for, `spawnModel` as
- pinned), and the paths to the full records.
-- **stderr follows team's success/failure split, not one rule.** `meaningfulStderr` drops
- `[claude-code:unrecognized_model]` as benign boilerplate — and that line was the ENTIRE
- content of the incident. So it is applied only to a clean `completed`; every other status
- returns the RAW stderr, redacted. Same distinction `team-orchestrator.ts:532` already
- documents: the filter decides whether to write a SUCCESS-path log, a genuine failure keeps
- the boilerplate because there it is the context. `stderrFiltered` says which rule ran.
+opt-in. A pane child has no stderr pipe for claudish to keep; what a terminal shows a person is the
+screen, so that is what is captured.
+
+- **`get_diagnostics(session_id, event_limit?)`** returns `state`, `event`, `reason`, `detail`;
+ **both halves of the model chain** (`model` as asked for, `spawnModel` as pinned) and the
+ `provider`; `shape`, `exitCode`, `idleSeconds`, `elapsedSeconds`, `timeoutSeconds`,
+ `outputBytes`, turns, tokens, `costUsd`, `toolCalls`, `pendingInputs`; the pane facts — `phase`,
+ `connected`, the redacted `screenTail`, `sockPath`, the head of magmux's own stderr,
+ `preambleBytes`, the current turn's `readCoverage`, the child's `claudeCodeVersion`,
+ `anomalies`; the tail of the event ring; the upstream error bodies; and the paths: the
+ transcript, the session directory, `events.jsonl`, `upstream-errors.jsonl`. A session no longer in
+ memory answers from its directory, including `screen.txt`.
- **`outputBytes` counts the CHILD's prose only.** `recordNote` exists so claudish's own
`[claudish] …` failure annotation does not inflate the metric that proves a session
produced nothing — measured, it read 312 B for a 0-byte session before the split.
-- **The event ring is in memory, not read back off disk.** 200 frames × 800 chars, labelled
- `type:subtype`, redacted once and shared with `events.jsonl`. It keeps filling after the
- 4 MB file cap, because the frames just before a death are the ones a post-mortem wants.
+- **The event ring is in memory, not read back off disk.** 200 records × 800 chars, labelled by
+ `type`, redacted once and shared with `events.jsonl`. It keeps filling after the 4 MB file cap,
+ because the records just before a death are the ones a post-mortem wants.
### `transcriptPath` — realpath, or it is wrong
Claude Code writes an authoritative JSONL transcript at
-`~/.claude/projects/<slug of cwd>/<session-uuid>.jsonl`. claudish mints that uuid and passes
-it as `--session-id`, then confirms it from `system:init`, so the filename is derived, never
-searched for by mtime. `transcriptPathFor` (in `session/session-discovery.ts`, which owns
-the layout) is the only `realpathSync` in the repo and it is load-bearing: macOS `tmpdir()`
-is `/var/…` → `/private/var/…` and a worktree can be reached through a symlink too, so the
-slug of the path we *spawned* with names a directory that does not exist. That is literally
-how the incident's transcripts were declared missing — they were under the session's own
-`work_dir`, in a project directory nobody looked in. The child's `system:init.cwd` wins when
-present (Node has already resolved it); the spawn cwd is the pre-init fallback, which is
-exactly the window a startup failure lands in.
+`<CLAUDE_CONFIG_DIR or $HOME/.claude>/projects/<slug of cwd>/<session-uuid>.jsonl`. claudish
+mints that uuid and passes it as `--session-id`, so the filename is derived, never searched for by
+mtime. `transcriptPathFor` (in `session/session-discovery.ts`, which owns the layout) is the
+only `realpathSync` in the repo and it is load-bearing: macOS `tmpdir()` is `/var/…` →
+`/private/var/…` and a worktree can be reached through a symlink too, so the slug of the path we
+*spawned* with names a directory that does not exist. That is literally how the incident's
+transcripts were declared missing — they were under the session's own `work_dir`, in a project
+directory nobody looked in. The slug replaces EVERY non-alphanumeric character with `-`, the
+projects root follows the OWNER's `CLAUDE_CONFIG_DIR` (`projectsDir(parentEnv)`), and the pane's
+launcher `cd`s to the realpath before `exec`, so the directory Claude Code writes and the one
+claudish reads come from one rule. Now that the transcript is the turn oracle, a wrong path is not
+a missing diagnostic: it is a session that never sees its own witness.
### `CLAUDISH_UPSTREAM_ERROR_LOG` is set per session
@@ -273,12 +293,12 @@ into one unattributable file. The capture **redacts at write time** now that it
only a path a user opted into: a 401/403 body routinely echoes the credential that failed,
and `get_diagnostics` hands these records to an agent.
-## MCP Tools (13 total)
+## MCP Tools (14 total)
- **Low-level** (4): `run_prompt`, `list_models`, `search_models`, `compare_models`
- **Agentic** (3): `preflight`, `team`, `report_error`
-- **Channel** (6): `create_session`, `send_input`, `get_output`, `cancel_session`,
- `list_sessions`, `get_diagnostics`
+- **Channel** (7): `create_session`, `send_input`, `get_output`, `cancel_session`,
+ `list_sessions`, `get_diagnostics`, `capture_session`
`preflight` exists because `--probe` is CLI-ONLY. An MCP consumer had no way to
check its models before committing to them, so it either shelled out to the CLI or
@@ -291,6 +311,15 @@ of the PROVIDER, not the model, so the same bare name can be free through a plan
or billed per token depending on which credential is present — which is precisely
what a caller cannot see from the model id.
+**The polling verbs are the frozen mod contract v1** (`pane/contract.ts`, summarised in
+`pane-session.md`): `list_sessions` answers `{contract_version, capabilities, sessions}` with one
+`SessionRow` per session (state, reason, tokens, `cost_usd`, tool calls, turns, `idle_seconds`,
+`activity`, `pane`); `cancel_session` answers `{session_id, state, changed}`; `capture_session`
+answers the session's current 160×50 screen `{seq, cols, rows, cursor, lines, final, spans?}`, or
+`{unchanged:true, seq, final}` when `since_seq` is still current — a memory read, meant for polling
+at about 1 Hz. Their errors are a JSON `ContractError`. `team` gains the same verbs as modes
+(`list`, `status`, `capture`, `cancel`).
+
The tool list is pinned by an EXACT frozen array in `channel/e2e-channel.test.ts`, so
adding or removing a tool without updating that test fails CI. That is deliberate:
it is a wire contract, and an accidental change to the tool surface should be loud.
@@ -305,7 +334,7 @@ Uses a `ToolDefinition[]` registry with raw JSON Schema (not Zod). Two `setReque
## Channel Notifications
-`server.notification({ method: "notifications/claude/channel", params: { content, meta } })` — pushed by SessionManager's `onStateChange` callback on state transitions. The method, capability, and params shape match Anthropic's [Channels reference](https://code.claude.com/docs/en/channels-reference) byte-for-byte.
+`server.notification({ method: "notifications/claude/channel", params: { content, meta } })` — pushed by SessionManager's `onStateChange` callback when a session's channel event changes, plus a coalesced `tool_executing` repeat (at most one per second) when the tool or the tool count changes. The method, capability, and params shape match Anthropic's [Channels reference](https://code.claude.com/docs/en/channels-reference) byte-for-byte.
The wire format is contractually pinned by `channel-wire-format.test.ts`:
@@ -316,7 +345,7 @@ The wire format is contractually pinned by `channel-wire-format.test.ts`:
"content": "<string>",
"meta": {
"session_id": "<8-char hex>",
- "event": "starting|running|tool_executing|waiting_for_input|finishing|completed|failed|cancelled|timeout",
+ "event": "starting|running|tool_executing|waiting_for_input|awaiting_permission|completed|failed|cancelled|timeout",
"model": "<model-id>",
"elapsed_seconds": "<numeric string>",
"task_id": "<same as session_id>",
@@ -329,6 +358,14 @@ The wire format is contractually pinned by `channel-wire-format.test.ts`:
}
```
+The event is derived from the session's state by `channelEventFor` (`session-manager.ts`):
+STARTING → `starting`; RUNNING → `tool_executing` when its activity is a tool name, else `running`;
+AWAITING_INPUT → `waiting_for_input`; AWAITING_PERMISSION → `awaiting_permission`; COMPLETED,
+CANCELLED, TIMEOUT → their own event; FAILED and EMPTY → `failed`. Frames may add `tool` and
+`tool_count`, `activity` (whenever it is non-null), `prompt_not_read` and `send_rejected`. The
+content is claudish's own short text per event: the question or dialog text when the session is
+blocked, the reason and detail on `failed`.
+
When rendered by Claude Code, each notification arrives in the agent's context as:
```
@@ -337,9 +374,9 @@ When rendered by Claude Code, each notification arrives in the agent's context a
</channel>
```
-`meta` keys must match `[a-zA-Z0-9_]+` — Claude Code silently drops keys with hyphens or other characters. Our schema uses underscore-only keys (`session_id`, `elapsed_seconds`, etc.); when adding new `extraMeta` keys via `StreamJsonReducer`, keep this constraint.
+`meta` keys must match `[a-zA-Z0-9_]+` — Claude Code silently drops keys with hyphens or other characters. Our schema uses underscore-only keys (`session_id`, `elapsed_seconds`, etc.); when adding new `extraMeta` keys in `SessionManager.emitFrame`, keep this constraint.
-The `task_id` / `status` / `created_at` / `last_updated_at` fields are SEP-1686 (MCP Tasks) forward-compatibility — additive only, no current consumer behavior change. The 8-value `event` collapses to the 5-value `status` per `EVENT_TO_TASK_STATUS` in `mcp-server.ts`; **every member of `SessionStatus` must have a key there**, because `mapEventToTaskStatus` falls through to `?? "working"` and a missing key silently reports a finished session as running. When Claude Code ships `notifications/tasks/status` receiver support, the migration is a method-name swap + payload restructure; see `ROADMAP.md` (Channel notifications → Phase 2) and `ai-docs/sessions/dev-research-mcp-tool-progress-20260508-235612-8d9da3e8/sep-1686-migration-schema.md` (write-up lost — predates the ai-docs tracking fix) for the full plan.
+The `task_id` / `status` / `created_at` / `last_updated_at` fields are SEP-1686 (MCP Tasks) forward-compatibility — additive only, no current consumer behavior change. The 9-value `event` collapses to the 5-value `status` per `EVENT_TO_TASK_STATUS` in `mcp-server.ts`; **every member of `ChannelEventType` must have a key there** — enforced at compile time now, because `mapEventToTaskStatus` falls through to `?? "working"` and a missing key silently reports a finished session as running. When Claude Code ships `notifications/tasks/status` receiver support, the migration is a method-name swap + payload restructure; see `ROADMAP.md` (Channel notifications → Phase 2) and `ai-docs/sessions/dev-research-mcp-tool-progress-20260508-235612-8d9da3e8/sep-1686-migration-schema.md` (write-up lost — predates the ai-docs tracking fix) for the full plan.
## Enabling channel rendering in Claude Code
@@ -385,22 +422,42 @@ Off by default. Zero overhead in production.
When the MCP server is spawned by a host that captures stderr (e.g. Claude Code), set `CLAUDISH_CHANNEL_TRACE_FILE=/path/to/log` alongside `CLAUDISH_CHANNEL_TRACE=1` to mirror trace lines to a file you can `tail` from outside the host process. The file is opened with `appendFileSync` so multiple sessions append safely.
-Two diagnostic scripts:
+Diagnostic scripts:
- `packages/cli/src/channel/test-helpers/channel-diagnostic.ts` — drives the MCP server with raw JSON-RPC against the OpenRouter free model. Confirms the producer→bridge→wire pipeline.
- `packages/cli/src/channel/test-helpers/client-diagnostic.ts` — spawns `claude -p` against the instrumented MCP server and compares what the server sent vs. what the client surfaced. Useful for diagnosing client-side gating.
- `packages/cli/src/channel/test-helpers/claudish-mock.ts` — a standalone mock MCP server that exposes a single `start_mock_session` tool, then emits a scripted sequence of 6 channel notifications over ~9 seconds. Decouples channel-rendering tests from real-model behavior.
+- `scripts/pane-drive.ts` — drives one pane session from the command line (`--fake <scenario>` for the hermetic fake child).
## Testing
```bash
-bun test --cwd . ./packages/cli/src/channel/*.test.ts
+bun test ./packages/cli/src/channel/
```
-Five files: scrollback-buffer, session-manager, stream-json-reducer, e2e-channel, channel-wire-format. (`signal-watcher.test.ts` was deleted with the module it covered.) The wire-format tests run without an API key by using the fake-claudish PATH shim, so they execute on every CI run.
-
-`session-manager.test.ts` carries seven mutation-proven regression guards, G1–G7: the timeout's status, the module-load signal exit codes (143/130), the reserved-flag rejection, the `--verbose`-before-`--quiet` argv order with a valueless `-p`, the delta firehose never reaching scrollback, and a promptless session reaching a usable state. Its fixtures replay real captured Claude Code 2.1.239 frames (`test-helpers/captured-stream-json.ts`), and its child (`test-helpers/fake-channel-stream-json.ts`) speaks bidirectional stream-json.
-
-**The tool list is pinned twice, and adding a tool must break both.** `e2e-channel.test.ts` freezes the full 13-name list and the channel-only 6, deliberately: that list is a wire contract and an accidental change to it should be loud. `get_diagnostics` broke both pins on the way in, which is the guard working.
+Channel sessions are panes, so the suites that start one run a REAL headless magmux with the pane
+fake child (`pane/test-helpers/fake-interactive-child.ts`) as `CLAUDISH_BIN`, under a per-test
+`CLAUDISH_PANE_ROOT` and an allowlisted environment, and assert after each test that no process,
+socket, record or launcher directory is left. Without magmux they skip with "magmux not installed —
+not checked". `testing.md` has the rules.
+
+- `session-manager.test.ts` — the pure seams (`channelEventFor` over every `SlotState`,
+ `toMetaRecord`, `sessionRowOf`, `normaliseTimeoutSeconds`), the two-generation disk reader, the
+ hostile-id and bounded-read guards, live pane sessions (one-shot and promptless frames, a send
+ queued while STARTING (G7) or RUNNING, the timeout staying TIMEOUT in memory, `meta.json` and on
+ the wire (G1/G2), cancel, recovery from disk), and the module-load signal exit codes (G3). G4 is
+ the flag check.
+- `session-records.contract.test.ts`, `session-state-records.contract.test.ts`,
+ `spawn-record.contract.test.ts`, `host-pid.contract.test.ts`, `session-timeout.test.ts` — the
+ on-disk records the monitor reads. These were written blind from the 10.4.0 specification; the
+ pane port changed only the adapters and the fake, and every replaced assertion cites its RB/D
+ number.
+- `channel-wire-format.test.ts`, `event-task-status.test.ts` — the wire format and the SEP-1686
+ projection, including `awaiting_permission` and the absence of `finishing`.
+- `../mcp-contract.e2e.test.ts` — the mod contract v1 through a real MCP server over JSON-RPC;
+ `../mcp-shutdown.e2e.test.ts` — stdin EOF, SIGTERM and SIGKILL of a server holding a live session
+ and a live team run.
+
+**The tool list is pinned twice, and adding a tool must break both.** `e2e-channel.test.ts` freezes the full 14-name list and the channel-only 7, deliberately: that list is a wire contract and an accidental change to it should be loud. `get_diagnostics` and `capture_session` each broke both pins on the way in, which is the guard working.
E2E tests use `--strict-mcp-config --bare --dangerously-skip-permissions` for isolation. SessionManager tests point child spawns at the tree under test via `CLAUDISH_BIN` (`spawn-claudish.ts`), never at the installed binary.
@@ -413,7 +470,7 @@ E2E tests use `--strict-mcp-config --bare --dangerously-skip-permissions` for is
Under `--bare` the tools are not in the model's toolset when it decides what to do, so it improvises with `Bash` — with the real claudish server it answered *"I don't have access to a tool called `mcp__claudish__list_models`. My available tools are `Bash`, `Edit`, and `Read`."* Any test asserting that a tool was DISCOVERED or CALLED must drop `--bare`; `--strict-mcp-config` alone still restricts MCP to the temp config, which is the isolation that matters. Keep `--bare` for tests that only drive the server directly over JSON-RPC.
-Assert on the protocol, never on prose: `--output-format stream-json --verbose` exposes the `init` server status, the `tools` array, and the `tool_use`/`tool_result` pair. An assertion like `stdout.includes("Recommended Models")` passes for the wrong reason — it matched output the model produced via `Bash` while MCP discovery was silently broken. Also `proc.stdin.end()` on the spawned `claude`, or every run stalls 3s on "no stdin data received".
+Assert on the protocol, never on prose: `--output-format stream-json --verbose` exposes the `init` server status, the `tools` array, and the `tool_use`/`tool_result` pair. An assertion like `stdout.includes("Recommended Models")` passes for the wrong reason — it matched output the model produced via `Bash` while MCP discovery was silently broken. Also `proc.stdin.end()` on the spawned `claude`, or every run stalls 3s on "no stdin data received". (These are the e2e tests' OWN `claude -p` client; the sessions the server starts are panes.)
## The `notifications/progress` keepalive (`mcp/progress-heartbeat.ts`)
@@ -427,7 +484,7 @@ Claude Code aborts a tool call that puts nothing on the transport for its idle w
Channel and progress are **complementary, not alternatives**: channel is the visible surface with no keepalive, progress is the invisible keepalive — it still renders nowhere. A tool that blocks for minutes needs both.
-**`heartbeat: true` is set on exactly three tools**: `team`, `run_prompt`, `compare_models`. `create_session` deliberately does NOT carry it — it returns in milliseconds with `{session_id, status:"starting"}` and cannot reach the idle timer; the session's own long life is reported over channel frames, which is a different question.
+**`heartbeat: true` is set on exactly four tools**: `team`, `run_prompt`, `compare_models`, `preflight`. `team(mode:"run")` itself returns once every slot's prompt is accepted (at most 90 s + 30 s), but `run-and-judge` holds the call for the whole run. `create_session` deliberately does NOT carry it — it returns `{session_id, state}` as soon as the pane exists, without waiting for boot, and cannot reach the idle timer; the session's own long life is reported over channel frames, which is a different question.
**The emitter is TIME-driven, not event-driven**, and that is the load-bearing choice. `team` already emitted a channel frame on every state change and still died at exactly 1800s, because a model that thinks for 30 minutes produces no state changes — an event-driven emitter goes silent precisely while the idle timer is counting.