Skip to content

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

feat(mcp): add PaneSession, the live interactive pane, and pane/index.ts

Jack Rudenko3cc48205d13f
diff --git a/packages/cli/src/pane/accounting.test.ts b/packages/cli/src/pane/accounting.test.ts
index b81e8e43..1580515e 100644
--- a/packages/cli/src/pane/accounting.test.ts
+++ b/packages/cli/src/pane/accounting.test.ts
@@ -50,6 +50,8 @@ function snap(over: Partial<PaneSnapshot> = {}): PaneSnapshot {
panePid: 1,
screenTail: "",
anomalies: [],
+ claudeCodeVersion: null,
+ shape: "one-shot",
...over,
};
}
diff --git a/packages/cli/src/pane/index.ts b/packages/cli/src/pane/index.ts
new file mode 100644
index 00000000..3dda4c30
--- /dev/null
+++ b/packages/cli/src/pane/index.ts
@@ -0,0 +1,44 @@
+/**
+ * The pane module's public surface (architecture §2, D1). Team and the channel import
+ * from here only; internal files are imported directly only by their own tests.
+ * `child-env.ts` runs in the pane child and is imported by the CLI entry, not here.
+ */
+
+export * from "./contract.js";
+export { toSlotRow } from "./slot-row.js";
+export {
+ type Accounting,
+ mergeAccounting,
+ readTokenFileCached,
+ resolveProvider,
+ type TokenFileStats,
+} from "./accounting.js";
+export {
+ buildClaudishPaneArgv,
+ checkChildFlags,
+ assertMagmuxAvailable,
+ flagsRemoveRead,
+ MagmuxUnavailableError,
+ SOCK_ROOT,
+ sockRootFor,
+} from "./pane-launch.js";
+export {
+ installPaneShutdownHooks,
+ livePaneCount,
+ MAX_LIVE_PANES,
+ PaneLimitError,
+ reapAllPanes,
+ releasePaneReservations,
+ reservePanes,
+ sweepOrphanPanes,
+} from "./pane-registry.js";
+export {
+ type PaneBlock,
+ type PaneSession,
+ type PaneSessionOptions,
+ PaneStartError,
+ type SendResult,
+ startPaneSession,
+} from "./pane-session.js";
+export type { FinalVerdict, PaneSnapshot, SettledTurn } from "./types.js";
+export type { Phase } from "./slot-state.js";
diff --git a/packages/cli/src/pane/pane-session.ts b/packages/cli/src/pane/pane-session.ts
new file mode 100644
index 00000000..cdadfaea
--- /dev/null
+++ b/packages/cli/src/pane/pane-session.ts
@@ -0,0 +1,1626 @@
+/**
+ * `PaneSession` — one interactive Claude Code, launched through claudish, in its own
+ * headless magmux pane, driven over the socket (architecture §2.9–§2.10).
+ *
+ * The transcript decides turn state (D3): acceptance, settle, answer and accounting.
+ * magmux supplies liveness (`exit`, pids), the screen (`watch` frames) and input
+ * (`send`). The lifecycle is the phase table of `slot-state.ts`; this class is the only
+ * thing that fires its events. Policy stays with the owner (D8): `decide(turn)` and
+ * `onBlocked(block)` are the owner's, never ours.
+ *
+ * Every event handler runs inside `step()`, which reports the NET wire-state change of
+ * one event-processing step to `onTransition` (so RUNNING → IDLE → ADMITTING in one step
+ * reports nothing) and coalesces `onChange` to at most 4 per second.
+ *
+ * No claudish timer ends a turn after its prompt was accepted (D10). The only bounds are
+ * boot (90 s) and admission of the CREATED prompt (30 s), before any work exists, and a
+ * channel session's own `timeoutMs`.
+ */
+
+import type { ChildProcess } from "node:child_process";
+import { readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { waitForExit } from "../process-tree.js";
+import type { CaptureResult, CaptureUnchanged, FailureReason, SlotState } from "./contract.js";
+import { MagmuxClient, type MagmuxConnectError } from "./magmux-client.js";
+import {
+ type ClaudishLaunch,
+ FATAL_MAGMUX_STDERR,
+ MIN_MAGMUX_VERSION,
+ SUBCOMMAND_WORDS,
+ assertMagmuxAvailable,
+ buildClaudishPaneArgv,
+ buildPaneEnv,
+ createLaunchDirs,
+ ensureSockRoot,
+ launcherScript,
+ mintPaneId,
+ resolveClaudishLaunch,
+ sockPathFor,
+ sockRootFor,
+ spawnPaneMagmux,
+ spawnPaneWatcher,
+ versionAtLeast,
+ writeLauncherFiles,
+} from "./pane-launch.js";
+import {
+ type RegisteredPane,
+ ensureSwept,
+ installPaneShutdownHooks,
+ ownerStartOfSelf,
+ paneShutdownHooksInstalled,
+ refreshGroupOf,
+ registerPane,
+ removePaneFiles,
+ reservePanes,
+ takePaneReservation,
+ unregisterPane,
+ updateRecord,
+ writeRecord,
+} from "./pane-registry.js";
+import {
+ type GroupSnapshot,
+ type PaneIdentity,
+ groupCheck,
+ isLaunchDirPath,
+ readProcessTableAsync,
+ recordPathOf,
+ verifiedGroupSnapshot,
+} from "./process-identity.js";
+import { type Delivery, planDelivery, writeTurnFile } from "./prompt-delivery.js";
+import {
+ agentRejectedLine,
+ choiceDialog,
+ hasChoiceDialog,
+ inputBox,
+ isWorking,
+ readBoot,
+ screenAnswer,
+ screenErrorRows,
+ screenText,
+ stopHookRunning,
+ transcriptSavingOff,
+} from "./screen-classifier.js";
+import {
+ type MagmuxCapture,
+ type MagmuxFrame,
+ type ScreenState,
+ applyFrame,
+ emptyScreen,
+} from "./screen-model.js";
+import {
+ CORROBORATION_MS,
+ SECONDARY_QUIET_MS,
+ type ScreenFacts,
+ type SettleDecision,
+ decideSettle,
+} from "./settle-rule.js";
+import {
+ type Phase,
+ type PhaseEvent,
+ isTerminalPhase,
+ nextPhase,
+ wireState,
+} from "./slot-state.js";
+import { TranscriptFollower, type TranscriptView, type TurnView } from "./transcript-follower.js";
+import type { FinalVerdict, PaneSnapshot, SettledTurn } from "./types.js";
+
+export type { FinalVerdict, PaneSnapshot, SettledTurn } from "./types.js";
+
+export const BOOT_TIMEOUT_MS = 90_000;
+export const ADMIT_TIMEOUT_MS = 30_000;
+/** Without a witness this long after delivery: re-press Enter, or enter degraded mode. */
+export const RESEND_AFTER_MS = 10_000;
+export const DEGRADED_ENTRY_MS = 10_000;
+/** Degraded settle: no change above the box for 2 × this. */
+export const SCREEN_SETTLE_QUIET_MS = 3_000;
+/** The REPL box must read empty this long before boot is ready. */
+const REPL_STABLE_MS = 500;
+/** A dialog or choice screen static this long blocks boot. */
+const BOOT_STATIC_MS = 5_000;
+const TICK_MS = 250;
+/** research-magmux §6 recommends 2–4; 4 halves boot/witness latency at no idle cost. */
+const WATCH_FPS = 4;
+const POLL_BACKSTOP_MS = 1_000;
+/** R3-M4: a `finishing` turn with a static screen for this many secondary windows. */
+const TURN_END_MISSING_FACTOR = 3;
+const MAX_ANOMALY_KEYS = 64;
+
+export interface PaneBlock {
+ kind: "question" | "permission";
+ tool: string;
+ text: string;
+}
+
+export interface PaneSessionOptions {
+ kind: "t" | "s";
+ label: string;
+ /** already checked by checkChildFlags */
+ callerFlags: string[];
+ spawnModel: string;
+ cwd: string;
+ sessionUuid: string;
+ /** transcriptPathFor(realpath cwd, sessionUuid, projectsDir(parentEnv)) — the caller derives it */
+ transcriptPath: string;
+ slotEnv: Record<string, string>;
+ shape: "one-shot" | "interactive";
+ /** enqueued before boot; delivered on boot_ready */
+ initialPrompt?: string;
+ /** false when callerFlags remove Read (§2.3 rule 4) */
+ readAvailable: boolean;
+ decide: (turn: SettledTurn) => FinalVerdict | "continue";
+ onBlocked: (b: PaneBlock) => FinalVerdict | "wait";
+ bootTimeoutMs?: number;
+ /** initialDelivery only */
+ admitTimeoutMs?: number;
+ /** whole-session deadline → TIMEOUT (channel only; team never passes it) */
+ timeoutMs?: number;
+ /** coalesced ≤ 4/s */
+ onChange?: (snap: PaneSnapshot, prev: SlotState) => void;
+ /** every wire-state change, synchronously, never coalesced, NET of one event-processing step */
+ onTransition?: (t: { from: SlotState; to: SlotState; at: string; snap: PaneSnapshot }) => void;
+ magmuxBinary?: string;
+ sockRoot?: string;
+ claudishSpawn?: ClaudishLaunch;
+ parentEnv?: Record<string, string | undefined>;
+ /** @internal test-only timing seams (X-M7); production never passes them */
+ timings?: {
+ secondaryQuietMs?: number;
+ screenSettleQuietMs?: number;
+ degradedEntryMs?: number;
+ resendAfterMs?: number;
+ corroborationMs?: number;
+ bootStaticMs?: number;
+ replStableMs?: number;
+ };
+}
+
+export type SendResult =
+ | { ok: true; queued: number }
+ | { ok: false; reason: "terminal" | "delivery_unavailable" | "unsupported_command" };
+
+export interface PaneSession {
+ readonly paneId: string;
+ readonly sockPath: string;
+ /** resolves when the wire state leaves STARTING: RUNNING, AWAITING_INPUT (promptless), or terminal */
+ readonly ready: Promise<void>;
+ readonly terminal: Promise<PaneSnapshot>;
+ snapshot(): PaneSnapshot;
+ capture(sinceSeq?: number, opts?: { spans?: boolean }): CaptureResult | CaptureUnchanged;
+ send(text: string): SendResult;
+ turnAnswer(index: number): string;
+ cancel(): { changed: boolean; state: SlotState };
+ expire(): { changed: boolean; state: SlotState };
+ reaped(): Promise<void>;
+}
+
+interface Admission {
+ index: number;
+ text: string;
+ plan: Delivery;
+ initial: boolean;
+ startedAt: number;
+ deliveredAt: number | null;
+ resent: boolean;
+ panelEscaped: boolean;
+ /** degraded acceptance armed (no transcript evidence after the entry delay) */
+ degraded: boolean;
+}
+
+interface ScreenTurn {
+ echo: string;
+ acceptedAt: number;
+ errorLogSize: number;
+}
+
+const EVENT_REASON: Partial<Record<PhaseEvent, FailureReason>> = {
+ boot_dialog: "first_run_dialog",
+ boot_blocked: "boot_blocked",
+ admit_deadline: "prompt_not_accepted",
+ pane_lost: "pane_lost",
+ cancel: "cancelled",
+ timeout: "timeout",
+};
+
+const VERDICT_EVENT: Record<FinalVerdict["state"], PhaseEvent> = {
+ COMPLETED: "verdict_completed",
+ EMPTY: "verdict_empty",
+ FAILED: "verdict_failed",
+};
+
+function iso(ms: number): string {
+ return new Date(ms).toISOString();
+}
+
+function alive(p: ChildProcess | null): boolean {
+ return !!p && p.exitCode === null && p.signalCode === null;
+}
+
+function screenTailOf(s: ScreenState, n = 12): string {
+ const lines = s.lines.filter((l) => l.trim());
+ return lines.slice(-n).join("\n");
+}
+
+export class PaneSessionImpl implements PaneSession, RegisteredPane {
+ readonly paneId: string;
+ readonly sockPath: string;
+ readonly root: string;
+ readonly identity: PaneIdentity;
+ readonly ready: Promise<void>;
+ readonly terminal: Promise<PaneSnapshot>;
+ group: GroupSnapshot | null = null;
+ reapFailed = false;
+
+ private readonly o: PaneSessionOptions;
+ private readonly turnDir: string;
+ private readonly ctlDir: string;
+ private readonly follower: TranscriptFollower;
+ private readonly startedAtMs = Date.now();
+ private readonly secondaryQuietMs: number;
+ private readonly corroborationMs: number;
+
+ private resolveReady!: () => void;
+ private resolveTerminal!: (s: PaneSnapshot) => void;
+ private readySettled = false;
+
+ private phase: Phase = "BOOTING";
+ private initialDelivery = false;
+ private initialPending: boolean;
+ private shape: "one-shot" | "interactive";
+ private queue: string[] = [];
+ private screen: ScreenState = emptyScreen(160, 50);
+ private final = false;
+ private turnIndex = 0;
+ private admission: Admission | null = null;
+ private screenTurn: ScreenTurn | null = null;
+ private turnSource: "transcript" | "screen" = "transcript";
+ private turnsCompleted = 0;
+ private rewakeOfSettled = false;
+ private settledChatOffset: number | null = null;
+ private lastChatOffset: number | null = null;
+ private lastChatSeenAt = 0;
+ private currentDelivery: Delivery | null = null;
+ private answers = new Map<number, string>();
+ private lastCaptureSource: SettledTurn["captureSource"] | null = null;
+ private exitRequested = false;
+ private escapeArmed = false;
+ private escapeSentAt: number | null = null;
+ private blockedToolId: string | null = null;
+ private reason: FailureReason | null = null;
+ private detail: string | null = null;
+ private activity: string | null = null;
+ private exitCode: number | null = null;
+ private endedAtMs: number | null = null;
+ private claudeCodeVersion: string | null = null;
+ private anomalies = new Map<string, number>();
+ private exitScrollback = "";
+ private exitLastLine = "";
+
+ private bootKind: string | null = null;
+ private bootKindSince = 0;
+
+ private magmux: ChildProcess | null = null;
+ private watcher: ChildProcess | null = null;
+ private client: MagmuxClient | null = null;
+ private panePidValue: number | null = null;
+ private stderrHead = "";
+ private paneClosed = false;
+ private paneExited = false;
+ private reaping = false;
+ private fastReap = false;
+ private reapPromise: Promise<void> | null = null;
+ private reconnecting = false;
+
+ private depth = 0;
+ private stepFrom: SlotState | null = null;
+ private lastPollAt = 0;
+ private framePending = false;
+ private lastLivenessAt = 0;
+ private ticker: ReturnType<typeof setInterval> | null = null;
+ private timeoutTimer: ReturnType<typeof setTimeout> | null = null;
+ private changeTimer: ReturnType<typeof setTimeout> | null = null;
+ private lastChangeAt = 0;
+ private lastChangeState: SlotState = "STARTING";
+
+ constructor(
+ o: PaneSessionOptions,
+ ids: { paneId: string; sockPath: string; root: string; ctlDir: string; turnDir: string }
+ ) {
+ this.o = o;
+ this.paneId = ids.paneId;
+ this.sockPath = ids.sockPath;
+ this.root = ids.root;
+ this.ctlDir = ids.ctlDir;
+ this.turnDir = ids.turnDir;
+ this.identity = { paneId: ids.paneId, sessionUuid: o.sessionUuid, ctlDir: ids.ctlDir };
+ this.shape = o.shape;
+ this.initialPending = !!o.initialPrompt;
+ if (o.initialPrompt) this.queue.push(o.initialPrompt);
+ this.secondaryQuietMs = o.timings?.secondaryQuietMs ?? SECONDARY_QUIET_MS;
+ this.corroborationMs = o.timings?.corroborationMs ?? CORROBORATION_MS;
+ this.follower = new TranscriptFollower(
+ o.transcriptPath,
+ join(o.transcriptPath.replace(/\.jsonl$/, ""), "subagents")
+ );
+ this.ready = new Promise((r) => {
+ this.resolveReady = r;
+ });
+ this.terminal = new Promise((r) => {
+ this.resolveTerminal = r;
+ });
+ }
+
+ /* ───────────────────────────── start ───────────────────────────── */
+
+ /** Spawn order (X-L4): record → watcher → magmux → magmux.pid/record → dial → watch. */
+ async start(input: {
+ magmuxBinary: string;
+ env: Record<string, string>;
+ cwd: string;
+ }): Promise<void> {
+ const recordPath = recordPathOf(this.root, this.paneId);
+ this.watcher = spawnPaneWatcher({
+ paneId: this.paneId,
+ sessionUuid: this.o.sessionUuid,
+ ctlDir: this.ctlDir,
+ sockPath: this.sockPath,
+ recordPath,
+ turnDir: this.turnDir,
+ sockRoot: this.root,
+ });
+ updateRecord(this.root, this.paneId, { watcherPid: this.watcher.pid ?? null });
+ let proc: ChildProcess | null = null;
+ try {
+ proc = spawnPaneMagmux({
+ binary: input.magmuxBinary,
+ paneId: this.paneId,
+ sockRoot: this.root,
+ ctlDir: this.ctlDir,
+ cwd: input.cwd,
+ env: input.env,
+ });
+ } catch (e) {
+ return this.spawnFailed(e);
+ }
+ if (!proc.pid) return this.spawnFailed(new Error("magmux did not start"));
+ this.magmux = proc;
+ try {
+ writeFileSync(join(this.ctlDir, "magmux.pid"), `${proc.pid}\n`, { mode: 0o600 });
+ } catch {
+ // the record carries it too
+ }
+ updateRecord(this.root, this.paneId, { magmuxPid: proc.pid });
+ proc.stderr?.setEncoding("utf8");
+ proc.stderr?.on("data", (d: string) => this.onStderr(d));
+ proc.on("exit", (code, sig) => this.onMagmuxExit(code, sig));
+ this.ticker = setInterval(() => this.step(() => this.evaluate()), TICK_MS);
+ if (this.o.timeoutMs !== undefined)
+ this.timeoutTimer = setTimeout(
+ () => this.step(() => this.fire("timeout")),
+ Math.max(0, this.o.timeoutMs)
+ );
+ await this.connectFirst();
+ }
+
+ /**
+ * R3-M1: magmux could not be spawned. The terminal transition's reap does the "spawn
+ * failed" reap: no magmux and no group to signal, so it removes the record and the dirs
+ * and ends the watcher with `done`.
+ */
+ private spawnFailed(e: unknown): void {
+ const msg = e instanceof Error ? e.message : String(e);
+ this.step(() => this.fire("pane_lost", { detail: `magmux spawn failed: ${msg}` }));
+ }
+
+ private async connectFirst(): Promise<void> {
+ let client: MagmuxClient;
+ try {
+ client = await MagmuxClient.connect(this.sockPath, {
+ timeoutMs: 5000,
+ alive: () => alive(this.magmux),
+ });
+ } catch (e) {
+ const err = e as MagmuxConnectError;
+ this.step(() =>
+ this.fire("pane_lost", {
+ detail: `cannot connect to ${this.sockPath}: ${err.message}${this.stderrHead ? `; magmux: ${this.stderrHead.trim()}` : ""}`,
+ })
+ );
+ return;
+ }
+ await this.attach(client, false);
+ }
+
+ /** Subscribe a fresh connection: capabilities, list (dead pane?), watch. */
+ private async attach(client: MagmuxClient, reconnect: boolean): Promise<void> {
+ if (isTerminalPhase(this.phase) && this.reaping) {
+ client.close();
+ return;
+ }
+ this.client = client;
+ client.on("snapshot", (e) => this.onSnapshot(e));
+ client.on("frame", (f: MagmuxFrame) => this.onFrame(f));
+ client.on("exit", (e) => void this.onPaneExit(e));
+ client.on("pane_closed", (e) => {
+ if (e?.pane === 0) this.paneClosed = true;
+ });
+ client.on("disconnected", () => this.onDisconnected(client));
+ const caps = await client.request<{ version?: string; protocol?: number }>({
+ type: "capabilities",
+ });
+ if (caps.ok) {
+ const v = String(caps.result.version ?? "");
+ if (caps.result.protocol !== 1 || !versionAtLeast(v, MIN_MAGMUX_VERSION)) {
+ this.step(() =>
+ this.fire("pane_lost", {
+ detail: `magmux_unavailable: magmux ${v || "?"} protocol ${caps.result.protocol ?? "?"}; panes need >= ${MIN_MAGMUX_VERSION}, protocol 1`,
+ })
+ );
+ return;
+ }
+ }
+ await client.request({ type: "watch", pane: 0, mode: "frames", fps: WATCH_FPS });
+ // An `exit` pushed before this connection subscribed (a child that dies in its first
+ // milliseconds, or one that exited in a reconnect gap) is only visible in `list`.
+ const list = await client.request<{ panes?: Array<Record<string, unknown>> }>({ type: "list" });
+ const p0 = list.ok ? list.result.panes?.find((p) => p.pane === 0) : undefined;
+ if (typeof p0?.pid === "number" && !this.panePidValue) this.setPanePid(p0.pid);
+ if (p0?.dead === true && !this.paneExited) {
+ if (!reconnect) await this.nextFrame(500); // let the keyframe land: the final screen decides agent_rejected
+ void this.onPaneExit({ exitCode: p0.exitCode ?? null, lastLine: "" });
+ }
+ }
+
+ /* ───────────────────────────── magmux events ───────────────────────────── */
+
+ private onStderr(d: string): void {
+ if (this.stderrHead.length < 8192) this.stderrHead += d.slice(0, 8192 - this.stderrHead.length);
+ const fatal = d.split("\n").find((l) => FATAL_MAGMUX_STDERR.test(l));
+ if (fatal) this.step(() => this.fire("pane_lost", { detail: fatal.trim() }));
+ }
+
+ private onSnapshot(e: { panes?: Array<{ pane?: number; pid?: number }> }): void {
+ const p0 = e?.panes?.find((p) => p.pane === 0);
+ if (p0?.pid && !this.panePidValue) this.setPanePid(p0.pid);
+ }
+
+ private setPanePid(pid: number): void {
+ this.panePidValue = pid;
+ updateRecord(this.root, this.paneId, { panePid: pid });
+ // never a synchronous ps on the event loop: a stalled loop gets our socket dropped as a slow consumer
+ void readProcessTableAsync().then((t) => refreshGroupOf(this, t));
+ }
+
+ private onFrame(f: MagmuxFrame): void {
+ if (f.pane !== undefined && f.pane !== 0) return;
+ this.screen = applyFrame(this.screen, f);
+ this.framePending = true;
+ if (!this.claudeCodeVersion) {
+ const m = this.screen.lines.join("\n").match(/Claude Code v(\d+\.\d+\.\d+)/);
+ if (m) this.claudeCodeVersion = m[1] ?? null;
+ }
+ this.step(() => this.evaluate());
+ }
+
+ private onDisconnected(client: MagmuxClient): void {
+ if (this.client === client) this.client = null;
+ if (this.reaping || !alive(this.magmux)) return;
+ if (isTerminalPhase(this.phase)) return;
+ void this.reconnect();
+ }
+
+ /** magmux is alive (it keeps panes when a client leaves): redial with backoff while it lives. */
+ private async reconnect(): Promise<void> {
+ if (this.reconnecting) return;
+ this.reconnecting = true;
+ let delay = 50;
+ let enoent = 0;
+ try {
+ while (alive(this.magmux) && !this.reaping && !isTerminalPhase(this.phase)) {
+ try {
+ const c = await MagmuxClient.dial(this.sockPath);
+ this.anomaly("socket_reconnected");
+ await this.attach(c, true);
+ return;
+ } catch (e) {
+ enoent = (e as MagmuxConnectError).errno === "ENOENT" ? enoent + 1 : 0;
+ if (enoent >= 20) {
+ this.anomaly("socket_lost");
+ return;
+ }
+ }
+ await Bun.sleep(delay);
+ delay = Math.min(1000, delay * 2);
+ }
+ } finally {
+ this.reconnecting = false;
+ }
+ }
+
+ private onMagmuxExit(code: number | null, sig: NodeJS.Signals | null): void {
+ if (this.reaping || isTerminalPhase(this.phase)) return;
+ this.step(() => {
+ this.pollFollower(true);
+ if (this.phase === "RUNNING" && this.exitSettle()) {
+ this.applyExitPath(null);
+ return;
+ }
+ this.fire("pane_lost", {
+ detail: `magmux exited (${sig ?? `code ${code}`}) without reporting the pane's exit${this.stderrHead ? `; stderr: ${this.stderrHead.trim().slice(0, 500)}` : ""}`,
+ });
+ });
+ }
+
+ /** The pane child exited (magmux `exit` event, or a dead pane found on reconnect). */
+ private async onPaneExit(e: { exitCode?: unknown; lastLine?: unknown }): Promise<void> {
+ if (this.paneExited || isTerminalPhase(this.phase)) return;
+ this.paneExited = true;
+ const code = typeof e?.exitCode === "number" ? e.exitCode : null;
+ const lastLine = typeof e?.lastLine === "string" ? e.lastLine : "";
+ // The final screen, with scrollback, so a long agent list cannot hide the refusal (L8).
+ if (this.client) {
+ const cap = await this.client.request<MagmuxCapture>(
+ { type: "capture", pane: 0, offset: 200 },
+ 1000
+ );
+ if (
+ cap.ok &&
+ agentRejectedLine(cap.result.text ?? "") &&
+ !agentRejectedLine(screenText(this.screen))
+ )
+ this.exitScrollback = cap.result.text ?? "";
+ }
+ this.step(() => {
+ this.exitCode = code;
+ this.exitLastLine = lastLine;
+ this.applyExitPath(code);
+ });
+ }
+
+ /* ───────────────────────────── the step ───────────────────────────── */
+
+ private wire(): SlotState {
+ return wireState(this.phase, this.initialDelivery);
+ }
+
+ /** Run one event-processing step; report the NET wire change once. */
+ private step(fn: () => void): void {
+ if (this.depth === 0) this.stepFrom = this.wire();
+ this.depth++;
+ try {
+ fn();
+ } finally {
+ this.depth--;
+ }
+ if (this.depth > 0) return;
+ const from = this.stepFrom as SlotState;
+ const to = this.wire();
+ if (from !== to) {
+ try {
+ this.o.onTransition?.({ from, to, at: iso(Date.now()), snap: this.snapshot() });
+ } catch {
+ // an owner's callback must not break the session
+ }
+ }
+ if (to !== "STARTING" && !this.readySettled) {
+ this.readySettled = true;
+ this.resolveReady();
+ }
+ this.scheduleChange();
+ }
+
+ private scheduleChange(): void {
+ if (!this.o.onChange || this.changeTimer) return;
+ const wait = Math.max(0, this.lastChangeAt + 250 - Date.now());
+ this.changeTimer = setTimeout(() => {
+ this.changeTimer = null;
+ this.lastChangeAt = Date.now();
+ const prev = this.lastChangeState;
+ const snap = this.snapshot();
+ this.lastChangeState = snap.state;
+ try {
+ this.o.onChange?.(snap, prev);
+ } catch {
+ // ignore
+ }
+ }, wait);
+ }
+
+ private fire(ev: PhaseEvent, info: { reason?: FailureReason; detail?: string } = {}): boolean {
+ const next = nextPhase(this.phase, ev);
+ if (!next) {
+ this.anomaly(`illegal_transition:${this.phase}:${ev}`);
+ return false;
+ }
+ this.phase = next;
+ const reason = info.reason ?? EVENT_REASON[ev];
+ if (isTerminalPhase(next)) {
+ this.reason = next === "COMPLETED" ? null : (reason ?? this.reason);
+ if (info.detail !== undefined) this.detail = info.detail;
+ this.onTerminal();
+ } else if (info.detail !== undefined) this.detail = info.detail;
+ return true;
+ }
+
+ private anomaly(key: string): void {
+ const n = this.anomalies.get(key);
+ if (n !== undefined) this.anomalies.set(key, n + 1);
+ else if (this.anomalies.size < MAX_ANOMALY_KEYS) this.anomalies.set(key, 1);
+ }
+
+ /* ───────────────────────────── evaluation ───────────────────────────── */
+
+ /** Poll on a frame (debounced 250 ms) and on a 1 s backstop (FR4). */
+ private pollFollower(force = false): TranscriptView {
+ const now = Date.now();
+ const since = now - this.lastPollAt;
+ if (force || (this.framePending && since >= TICK_MS) || since >= POLL_BACKSTOP_MS) {
+ this.follower.poll();
+ this.lastPollAt = now;
+ this.framePending = false;
+ }
+ const view = this.follower.view();
+ const off = view.current?.lastChatOffset ?? null;
+ if (off !== this.lastChatOffset) {
+ this.lastChatOffset = off;
+ this.lastChatSeenAt = now;
+ }
+ return view;
+ }
+
+ private evaluate(): void {
+ if (isTerminalPhase(this.phase)) return;
+ if (transcriptSavingOff(this.screen)) this.follower.markSavingOff();
+ const view = this.pollFollower();
+ this.checkLiveness();
+ switch (this.phase) {
+ case "BOOTING":
+ this.evalBoot();
+ break;
+ case "ADMITTING":
+ this.evalAdmission(view);
+ break;
+ case "RUNNING":
+ case "QUESTION":
+ case "PERMISSION":
+ this.evalRunning(view);
+ break;
+ case "IDLE":
+ this.evalIdle(view);
+ break;
+ }
+ this.pump();
+ }
+
+ /** While disconnected, the pane's liveness is `kill(panePid, 0)` every second (X-M12). */
+ private checkLiveness(): void {
+ if (this.client || !this.panePidValue || this.paneExited) return;
+ const now = Date.now();
+ if (now - this.lastLivenessAt < 1000) return;
+ this.lastLivenessAt = now;
+ try {
+ process.kill(this.panePidValue, 0);
+ } catch (e) {
+ if ((e as NodeJS.ErrnoException).code === "ESRCH") {
+ this.paneExited = true;
+ this.applyExitPath(null);
+ }
+ }
+ }
+
+ private t(key: keyof NonNullable<PaneSessionOptions["timings"]>, dflt: number): number {
+ return this.o.timings?.[key] ?? dflt;
+ }
+
+ private evalBoot(): void {
+ const now = Date.now();
+ const r = readBoot(this.screen);
+ if (r.kind !== this.bootKind) {
+ this.bootKind = r.kind;
+ this.bootKindSince = now;
+ }
+ const staticFor = this.screen.seq === 0 ? 0 : now - this.screen.changedAt;
+ const staticMs = this.t("bootStaticMs", BOOT_STATIC_MS);
+ if (r.kind === "repl" && now - this.bootKindSince >= this.t("replStableMs", REPL_STABLE_MS)) {
+ this.bootReady();
+ return;
+ }
+ if (r.kind === "dialog" && staticFor >= staticMs) {
+ this.fire("boot_dialog", { detail: r.text });
+ return;
+ }
+ if (r.kind === "choice" && staticFor >= staticMs) {
+ this.fire("boot_blocked", { detail: r.text });
+ return;
+ }
+ if (now - this.startedAtMs >= (this.o.bootTimeoutMs ?? BOOT_TIMEOUT_MS)) {
+ const blocked = this.screen.seq > 0 && staticFor >= staticMs && r.kind !== "booting";
+ this.fire("boot_deadline", {
+ reason: blocked ? "boot_blocked" : "boot_timeout",
+ detail: screenTailOf(this.screen),
+ });
+ }
+ }
+
+ private bootReady(): void {
+ if (this.queue.length === 0) {
+ this.fire("boot_ready_idle");
+ return;
+ }
+ const head = this.queue[0] as string;
+ if (isControl(head)) {
+ this.fire("boot_ready_idle");
+ return;
+ }
+ const initial = this.initialPending;
+ this.initialPending = false;
+ this.initialDelivery = initial;
+ this.queue.shift();
+ this.fire("boot_ready_admit");
+ this.startAdmission(head, initial);
+ }
+
+ /** IDLE (or boot-ready) with a queued item: admit synchronously, then deliver. */
+ private pump(): void {
+ if (isTerminalPhase(this.phase) || this.admission) return;
+ if (this.phase === "IDLE" && this.queue.length > 0) {
+ const head = this.queue.shift() as string;
+ if (isControl(head)) {
+ this.exitRequested = true;
+ void this.typeLine(head.trim(), true);
+ return;
+ }
+ this.fire("admit");
+ this.startAdmission(head, false);
+ return;
+ }
+ if (
+ (this.phase === "QUESTION" || this.phase === "PERMISSION") &&
+ this.queue.length > 0 &&
+ this.escapeArmed &&
+ this.escapeSentAt === null
+ ) {
+ // Esc declines the dialog AND interrupts the turn; it settles through path I (D17).
+ this.escapeArmed = false;
+ this.escapeSentAt = Date.now();
+ void this.key("escape");
+ }
+ }
+
+ private startAdmission(text: string, initial: boolean): void {
+ this.follower.poll();
+ this.lastPollAt = Date.now();
+ const offset = this.follower.size(); // mark BEFORE deliver: the single turn boundary
+ const index = ++this.turnIndex;
+ const plan = planDelivery(text, this.turnDir, index, this.o.readAvailable);
+ this.currentDelivery = plan;
+ this.turnSource = "transcript";
+ this.screenTurn = null;
+ this.rewakeOfSettled = false;
+ this.settledChatOffset = null;
+ if (plan.mode === "refused" || plan.mode === "control") {
+ this.anomaly(`delivery_refused:${plan.mode === "refused" ? plan.reason : "control"}`);
+ this.admission = null;
+ this.fire(initial ? "admit_deadline" : "admit_abandoned", {
+ detail: plan.mode === "refused" ? plan.reason : undefined,
+ });
+ return;
+ }
+ try {
+ writeTurnFile(plan);
+ } catch (e) {
+ this.anomaly(`turn_file_failed:${e instanceof Error ? e.message : String(e)}`);
+ }
+ const delivery =
+ (plan.mode === "file" || plan.mode === "command") &&
+ plan.file &&
+ plan.fileContent !== undefined
+ ? { file: plan.file, text: plan.fileContent }
+ : null;
+ this.follower.openTurn({ index, offset, witness: plan.witness, delivery });
+ this.admission = {
+ index,
+ text,
+ plan,
+ initial,
+ startedAt: Date.now(),
+ deliveredAt: null,
+ resent: false,
+ panelEscaped: false,
+ degraded: false,
+ };
+ void this.deliver(this.admission);
+ }
+
+ private async deliver(adm: Admission): Promise<void> {
+ const plan = adm.plan;
+ if (plan.mode !== "typed" && plan.mode !== "file" && plan.mode !== "command") return;
+ if (plan.mode === "command") {
+ await this.typeLine(plan.line, false);
+ await this.nextFrame(500);
+ const box = inputBox(this.screen);
+ const name = plan.line.match(/^\/\S+/)?.[0] ?? "";
+ if (box?.menuOpen && box.menuItem !== name) await this.key("escape");
+ await this.key("enter");
+ } else {
+ await this.typeLine(plan.line, true);
+ }
+ adm.deliveredAt = Date.now();
+ }
+
+ private async typeLine(text: string, enter: boolean): Promise<boolean> {
+ let why = "disconnected";
+ for (let attempt = 0; attempt < 2; attempt++) {
+ const c = this.client;
+ if (c) {
+ const r = await c.request({ type: "send", pane: 0, text, typed: true, enter }, 10_000);
+ if (r.ok) return true;
+ why = r.code;
+ }
+ await Bun.sleep(500);
+ }
+ this.anomaly(`delivery_failed:${why}`);
+ return false;
+ }
+
+ private async key(k: string): Promise<boolean> {
+ const c = this.client;
+ if (!c) return false;
+ const r = await c.request({ type: "send", pane: 0, keys: [k], enter: false }, 10_000);
+ return r.ok;
+ }
+
+ private nextFrame(ms: number): Promise<void> {
+ const seq = this.screen.seq;
+ const end = Date.now() + ms;
+ return new Promise((resolve) => {
+ const check = () => {
+ if (this.screen.seq !== seq || Date.now() >= end) resolve();
+ else setTimeout(check, 25);
+ };
+ check();
+ });
+ }
+
+ private evalAdmission(view: TranscriptView): void {
+ const adm = this.admission;
+ if (!adm) return;
+ const cur = view.current;
+ if (cur && cur.index === adm.index && cur.acceptedAt !== null) {
+ this.accept();
+ return;
+ }
+ const now = Date.now();
+ const since = adm.deliveredAt ? now - adm.deliveredAt : 0;
+ if (adm.deliveredAt && since >= this.t("resendAfterMs", RESEND_AFTER_MS)) this.nudge(adm);
+ if (
+ adm.deliveredAt &&
+ (view.availability === "off" || since >= this.t("degradedEntryMs", DEGRADED_ENTRY_MS))
+ )
+ this.maybeDegradedAccept(adm, view);
+ if (this.phase !== "ADMITTING") return;
+ if (now - adm.startedAt >= (this.o.admitTimeoutMs ?? ADMIT_TIMEOUT_MS)) this.admitExpired(adm);
+ }
+
+ /** +10 s without a witness: the line still in the box → Enter again; a panel → Esc. */
+ private nudge(adm: Admission): void {
+ const box = inputBox(this.screen);
+ const line = adm.plan.mode === "control" || adm.plan.mode === "refused" ? "" : adm.plan.line;
+ if (!adm.resent && box && line && box.text.startsWith(line.slice(0, 40))) {
+ adm.resent = true;
+ this.anomaly("resent_enter");
+ void (async () => {
+ if (box.menuOpen) await this.key("escape");
+ await this.key("enter");
+ })();
+ return;
+ }
+ if (
+ !adm.panelEscaped &&
+ !box &&
+ !hasChoiceDialog(this.screen) &&
+ /Esc to cancel/.test(screenText(this.screen))
+ ) {
+ // A panel command (`/cost`, `/usage`, …) writes no record and swallows input until Esc.
+ adm.panelEscaped = true;
+ this.anomaly("panel_dismissed");
+ void this.key("escape");
+ }
+ }
+
+ /** Degraded acceptance (§2.8): the box emptied of the line, and an echo or a change above it. */
+ private maybeDegradedAccept(adm: Admission, view: TranscriptView): void {
+ if (view.availability === "ok") return;
+ const box = inputBox(this.screen);
+ if (!box || box.text !== "") return;
+ const line = adm.plan.mode === "control" || adm.plan.mode === "refused" ? "" : adm.plan.line;
+ const echo = this.screen.lines.some((l) => l.startsWith(`❯ ${line.slice(0, 40)}`));
+ const changed = adm.deliveredAt !== null && this.screen.aboveBoxChangedAt > adm.deliveredAt;
+ if (!echo && !changed) return;
+ this.turnSource = "screen";
+ this.anomaly("degraded_mode");
+ this.screenTurn = { echo: line, acceptedAt: Date.now(), errorLogSize: this.errorLogSize() };
+ this.accept();
+ }
+
+ private accept(): void {
+ this.admission = null;
+ this.initialDelivery = false;
+ this.lastChatSeenAt = Date.now();
+ this.fire("prompt_accepted");
+ }
+
+ private admitExpired(adm: Admission): void {
+ this.admission = null;
+ if (adm.initial) {
+ this.fire("admit_deadline", { detail: screenTailOf(this.screen) });
+ return;
+ }
+ this.anomaly("send_not_accepted");
+ this.fire("admit_abandoned");
+ }
+
+ private screenFacts(): ScreenFacts | null {
+ if (!this.client) return null;
+ const box = inputBox(this.screen);
+ return {
+ boxEmpty: !!box && box.text === "",
+ choiceDialog: hasChoiceDialog(this.screen),
+ working: isWorking(this.screen),
+ aboveBoxQuietMs: Date.now() - this.screen.aboveBoxChangedAt,
+ };
+ }
+
+ private evalRunning(view: TranscriptView): void {
+ if (this.turnSource === "screen") {
+ this.evalScreenTurn(view);
+ return;
+ }
+ const t = view.current;
+ if (!t) return;
+ if (this.phase === "QUESTION" || this.phase === "PERMISSION") {
+ if (t.pendingTool && t.pendingTool.id === this.blockedToolId) {
+ this.checkEscape();
+ return;
+ }
+ this.blockedToolId = null;
+ this.escapeSentAt = null;
+ this.fire("unblocked");
+ }
+ if (this.detectBlocked(t)) return;
+ const now = Date.now();
+ const decision = decideSettle({
+ turn: t,
+ session: view.session,
+ transcriptQuietMs: now - (view.lastAppendAt ?? this.startedAtMs),
+ chatQuietMs: now - this.lastChatSeenAt,
+ screen: this.screenFacts(),
+ paneExited: false,
+ secondaryQuietMs: this.secondaryQuietMs,
+ corroborationMs: this.corroborationMs,
+ });
+ if (decision.settled) {
+ this.settle(t, decision, null);
+ return;
+ }
+ this.activity = decision.activity;
+ this.checkTurnEndMissing();
+ }
+
+ private checkEscape(): void {
+ if (this.escapeSentAt === null) return;
+ if (Date.now() - this.escapeSentAt < (this.o.admitTimeoutMs ?? ADMIT_TIMEOUT_MS)) return;
+ this.anomaly("escape_not_effective");
+ this.escapeSentAt = null;
+ }
+
+ /** R3-M4: `finishing` with a static screen and no Stop-hook UI for N secondary windows. */
+ private checkTurnEndMissing(): void {
+ if (this.activity !== "finishing" || !this.client) return;
+ const quiet = Date.now() - this.screen.aboveBoxChangedAt;
+ if (quiet >= TURN_END_MISSING_FACTOR * this.secondaryQuietMs && !stopHookRunning(this.screen))
+ if (!this.anomalies.has("turn_end_record_missing")) this.anomaly("turn_end_record_missing");
+ }
+
+ /** Blocked detection (H7): AskUserQuestion from the transcript; permission needs the dialog too. */
+ private detectBlocked(t: TurnView): boolean {
+ const pending = t.pendingTool;
+ if (!pending || this.phase !== "RUNNING") return false;
+ let kind: PaneBlock["kind"] | null = null;
+ if (pending.name === "AskUserQuestion") kind = "question";
+ else if (this.client && hasChoiceDialog(this.screen)) kind = "permission";
+ if (!kind) return false;
+ this.blockedToolId = pending.id;
+ this.fire(kind === "question" ? "blocked_question" : "blocked_permission");
+ this.activity = pending.name;
+ const text = blockText(pending, choiceDialog(this.screen)?.text ?? null);
+ let v: FinalVerdict | "wait";
+ try {
+ v = this.o.onBlocked({ kind, tool: pending.name, text });
+ } catch {
+ v = "wait";
+ }
+ if (v !== "wait") this.applyVerdict(v);
+ return true;
+ }
+
+ private evalIdle(view: TranscriptView): void {
+ const t = view.current;
+ if (!t || this.settledChatOffset === null) return;
+ // A background notification woke the model with no prompt of ours (D23): same turn.
+ if (t.lastChatOffset !== null && t.lastChatOffset > this.settledChatOffset) {
+ this.rewakeOfSettled = true;
+ this.fire("rewake");
+ this.activity = "thinking";
+ }
+ }
+
+ /* ───────────────────────────── settle ───────────────────────────── */
+
+ private settledTurnOf(t: TurnView, decision: SettleDecision & { settled: true }): SettledTurn {
+ const d = this.currentDelivery;
+ return {
+ index: t.index,
+ answer: t.assistantText.join("\n\n"),
+ apiError: t.apiError,
+ stopReason: decision.stopReason,
+ captureSource: "transcript",
+ settledBy: decision.by,
+ delivery: {
+ mode: d && d.mode !== "refused" ? d.mode : "typed",
+ linesTotal: t.delivery ? t.delivery.lines : null,
+ linesRead: t.delivery ? t.readCoverage.linesReturned : null,
+ complete: t.delivery ? t.readCoverage.complete : null,
+ preambleBytes: t.preambleBytes,
+ },
+ };
+ }
+
+ private settle(
+ t: TurnView,
+ decision: SettleDecision & { settled: true },
+ exitCode: number | null
+ ): void {
+ for (const a of decision.anomalies) this.anomaly(a);
+ for (const cmd of t.backgroundShellsOpen) this.anomaly(`background_shell_open: ${cmd}`);
+ this.finishTurn(this.settledTurnOf(t, decision), t.lastChatOffset, exitCode);
+ }
+
+ private finishTurn(turn: SettledTurn, chatOffset: number | null, exitCode: number | null): void {
+ this.answers.set(turn.index, turn.answer);
+ this.lastCaptureSource = turn.captureSource;
+ this.activity = null;
+ let verdict: FinalVerdict | "continue";
+ try {
+ verdict = this.o.decide(turn);
+ } catch (e) {
+ verdict = { state: "FAILED", reason: "child_exited", detail: `decide() threw: ${String(e)}` };
+ }
+ if (!this.rewakeOfSettled) {
+ this.turnsCompleted++;
+ this.follower.markSettled();
+ }
+ if (verdict === "continue") {
+ if (turn.delivery.complete === false) this.anomaly("prompt_not_read");
+ this.settledChatOffset = chatOffset ?? -1;
+ this.fire("turn_continue");
+ return;
+ }
+ if (exitCode !== null || this.paneExited) {
+ const note = `pane child exited${exitCode === null ? "" : ` ${exitCode}`}`;
+ verdict = { ...verdict, detail: verdict.detail ? `${verdict.detail} · ${note}` : note };
+ }
+ this.applyVerdict(verdict);
+ }
+
+ private applyVerdict(v: FinalVerdict): void {
+ this.fire(VERDICT_EVENT[v.state], { reason: v.reason, detail: v.detail });
+ }
+
+ /* ───────────────────────────── degraded (screen) turn ───────────────────────────── */
+
+ /** The current turn's witness is in the transcript. */
+ private witnessed(t: TurnView | null): boolean {
+ return !!t && t.index === this.turnIndex && t.acceptedAt !== null;
+ }
+
+ /** Degraded settle (§2.8): empty box, no dialog, not working, and an answer or error row gone quiet. */
+ private screenSettleReady(view: TranscriptView, answer: string, apiError: unknown): boolean {
+ const box = inputBox(this.screen);
+ if (!box || box.text !== "" || hasChoiceDialog(this.screen) || isWorking(this.screen))
+ return false;
+ const quiet = Date.now() - this.screen.aboveBoxChangedAt;
+ if (view.availability === "off" && quiet >= this.secondaryQuietMs) return true;
+ return (
+ (!!answer || !!apiError) && quiet >= 2 * this.t("screenSettleQuietMs", SCREEN_SETTLE_QUIET_MS)
+ );
+ }
+
+ private evalScreenTurn(view: TranscriptView): void {
+ if (this.witnessed(view.current)) {
+ // A late witness (slow UserPromptSubmit hook): back to the transcript, at once.
+ this.turnSource = "transcript";
+ this.screenTurn = null;
+ this.anomaly("degraded_reverted");
+ this.evalRunning(view);
+ return;
+ }
+ const st = this.screenTurn;
+ if (!st || !this.client) return;
+ const answer = screenAnswer(this.screen, st.echo);
+ const apiError = this.screenApiError(st, answer);
+ this.activity = "thinking";
+ if (!this.screenSettleReady(view, answer, apiError)) return;
+ // one last poll before a screen-mode settle, with the same reversion
+ this.follower.poll();
+ if (this.witnessed(this.follower.view().current)) return;
+ this.anomaly("screen_answer_may_be_truncated");
+ if (this.currentDelivery?.mode === "file") this.anomaly("read_coverage_unverified");
+ const d = this.currentDelivery;
+ this.finishTurn(
+ {
+ index: this.turnIndex,
+ answer,
+ apiError,
+ stopReason: null,
+ captureSource: "screen",
+ settledBy: "screen",
+ delivery: {
+ mode: d && d.mode !== "refused" ? d.mode : "typed",
+ linesTotal: null,
+ linesRead: null,
+ complete: null,
+ preambleBytes: 0,
+ },
+ },
+ null,
+ null
+ );
+ }
+
+ private errorLogPath(): string | null {
+ return this.o.slotEnv.CLAUDISH_UPSTREAM_ERROR_LOG ?? null;
+ }
+
+ private errorLogSize(): number {
+ const p = this.errorLogPath();
+ if (!p) return 0;
+ try {
+ return statSync(p).size;
+ } catch {
+ return 0;
+ }
+ }
+
+ private screenApiError(st: ScreenTurn, answer: string): TurnView["apiError"] {
+ const p = this.errorLogPath();
+ if (p && this.errorLogSize() > st.errorLogSize) {
+ try {
+ const text = readFileSync(p, "utf8").slice(st.errorLogSize).trim();
+ return { status: null, category: "upstream_error_log", text };
+ } catch {
+ // fall through to the screen
+ }
+ }
+ const rows = screenErrorRows(this.screen);
+ if (rows.length > 0 && !answer)
+ return { status: null, category: "screen", text: rows.join("\n") };
+ return null;
+ }
+
+ /* ───────────────────────────── the exit path ───────────────────────────── */
+
+ /** Settle evidence for the current turn on the exit path (paths P, I, S without screen, X). */
+ private exitSettle(): (SettleDecision & { settled: true }) | null {
+ const view = this.follower.view();
+ const d = decideSettle({
+ turn: view.current,
+ session: view.session,
+ transcriptQuietMs: Number.MAX_SAFE_INTEGER,
+ chatQuietMs: Number.MAX_SAFE_INTEGER,
+ screen: null,
+ paneExited: true,
+ secondaryQuietMs: this.secondaryQuietMs,
+ corroborationMs: 0,
+ });
+ if (!d.settled) return null;
+ return { ...d, anomalies: d.anomalies.filter((a) => a !== "screen_unverified") };
+ }
+
+ /** §2.2: the exit is decided against the CURRENT turn only. */
+ private applyExitPath(code: number | null): void {
+ if (isTerminalPhase(this.phase)) return;
+ const view = this.pollFollower(true);
+ // a witness written just before the exit is still an acceptance
+ if (this.phase === "ADMITTING" && this.admission && this.witnessed(view.current)) this.accept();
+ if (this.phase === "RUNNING") {
+ const d = this.exitSettle();
+ const t = this.follower.view().current;
+ if (d && t) this.settle(t, d, code);
+ }
+ if (isTerminalPhase(this.phase)) return;
+ if (this.cleanIdleExit(code)) {
+ this.fire("exit_clean");
+ return;
+ }
+ this.firePaneExit(code);
+ }
+
+ /** §2.2 rule 2: interactive, IDLE, exit 0, after /exit or ≥ 1 settled turn, nothing admitted. */
+ private cleanIdleExit(code: number | null): boolean {
+ if (this.phase !== "IDLE" || code !== 0 || this.shape !== "interactive") return false;
+ return (this.exitRequested || this.turnsCompleted >= 1) && this.admission === null;
+ }
+
+ /** §2.2 rule 3: agent_rejected when the child's own refusal is on screen, else child_exited. */
+ private firePaneExit(code: number | null): void {
+ const text = `${this.exitLastLine}\n${this.exitScrollback}\n${screenText(this.screen)}`;
+ const rejected =
+ agentRejectedLine(screenText(this.screen)) ??
+ agentRejectedLine(this.exitScrollback) ??
+ agentRejectedLine(text);
+ this.fire("pane_exit", {
+ reason: rejected ? "agent_rejected" : "child_exited",
+ detail: rejected
+ ? rejected
+ : `pane child exited ${code === null ? "(code unknown)" : `with code ${code}`}${this.exitLastLine ? `; last line: ${this.exitLastLine}` : ""}\n${screenTailOf(this.screen)}`,
+ });
+ }
+
+ /* ───────────────────────────── public verbs ───────────────────────────── */
+
+ snapshot(): PaneSnapshot {
+ const view = this.follower.view();
+ const terminal = isTerminalPhase(this.phase);
+ const lastAct = Math.max(this.screen.changedAt, view.lastAppendAt ?? 0);
+ const cur = view.current;
+ const hasTranscript =
+ view.availability === "ok" && view.usage.tokensIn + view.usage.tokensOut > 0;
+ return {
+ paneId: this.paneId,
+ phase: this.phase,
+ state: this.wire(),
+ reason: this.phase === "COMPLETED" || !terminal ? null : this.reason,
+ detail: this.detail,
+ activity: terminal ? null : this.phaseActivity(),
+ lastActivityAt: lastAct > 0 ? iso(lastAct) : null,
+ idleSeconds:
+ terminal || lastAct === 0 ? null : Math.max(0, Math.floor((Date.now() - lastAct) / 1000)),
+ turnsCompleted: this.turnsCompleted,
+ tokensIn: hasTranscript ? view.usage.tokensIn : null,
+ tokensOut: hasTranscript ? view.usage.tokensOut : null,
+ toolCalls: view.toolCalls,
+ liveAnswerBytes: cur ? Buffer.byteLength(cur.assistantText.join("\n\n")) : 0,
+ exitCode: this.exitCode,
+ captureSource: this.lastCaptureSource,
+ turnSource: this.turnSource,
+ pendingInputs: this.queue.length,
+ connected: this.client !== null,
+ startedAt: iso(this.startedAtMs),
+ endedAt: this.endedAtMs ? iso(this.endedAtMs) : null,
+ transcriptPath: this.o.transcriptPath,
+ panePid: this.panePidValue,
+ screenTail: screenTailOf(this.screen),
+ anomalies: [...this.anomalies].map(([k, n]) => (n > 1 ? `${k} ×${n}` : k)),
+ claudeCodeVersion: this.claudeCodeVersion,
+ shape: this.shape,
+ };
+ }
+
+ private phaseActivity(): string | null {
+ switch (this.phase) {
+ case "RUNNING":
+ return this.activity ?? "thinking";
+ case "QUESTION":
+ return "AskUserQuestion";
+ case "PERMISSION":
+ return this.activity;
+ default:
+ return null;
+ }
+ }
+
+ capture(sinceSeq?: number, opts: { spans?: boolean } = {}): CaptureResult | CaptureUnchanged {
+ const s = this.screen;
+ if (sinceSeq !== undefined && sinceSeq === s.seq)
+ return { unchanged: true, seq: s.seq, final: this.final };
+ const out: CaptureResult = {
+ seq: s.seq,
+ cols: s.cols,
+ rows: s.rows,
+ cursor: { ...s.cursor },
+ lines: [...s.lines],
+ final: this.final,
+ };
+ if (opts.spans) out.spans = s.spans.map((r) => r.map((x) => [...x] as typeof x));
+ return out;
+ }
+
+ send(text: string): SendResult {
+ if (isTerminalPhase(this.phase)) return { ok: false, reason: "terminal" };
+ if (/^\/(clear|resume)(\s|$)/.test(text.trim()))
+ return { ok: false, reason: "unsupported_command" };
+ const plan = planDelivery(text, this.turnDir, 0, this.o.readAvailable);
+ if (plan.mode === "refused") return { ok: false, reason: "delivery_unavailable" };
+ if (this.shape === "one-shot") this.shape = "interactive";
+ this.queue.push(text);
+ this.escapeArmed = true;
+ this.step(() => this.evaluate());
+ return { ok: true, queued: this.queue.length };
+ }
+
+ turnAnswer(index: number): string {
+ const done = this.answers.get(index);
+ if (done !== undefined) return done;
+ const cur = this.follower.view().current;
+ return cur && cur.index === index ? cur.assistantText.join("\n\n") : "";
+ }
+
+ cancel(): { changed: boolean; state: SlotState } {
+ return this.endBy("cancel");
+ }
+
+ expire(): { changed: boolean; state: SlotState } {
+ return this.endBy("timeout");
+ }
+
+ private endBy(ev: "cancel" | "timeout"): { changed: boolean; state: SlotState } {
+ if (isTerminalPhase(this.phase)) return { changed: false, state: this.wire() };
+ this.step(() => this.fire(ev));
+ return { changed: true, state: this.wire() };
+ }
+
+ reaped(): Promise<void> {
+ return this.reapPromise ?? this.terminal.then(() => this.reapPromise ?? Promise.resolve());
+ }
+
+ panePid(): number | null {
+ return this.panePidValue;
+ }
+
+ /* ───────────────────────────── terminal and reap ───────────────────────────── */
+
+ private onTerminal(): void {
+ this.endedAtMs = Date.now();
+ this.final = true;
+ this.admission = null;
+ if (this.timeoutTimer) clearTimeout(this.timeoutTimer);
+ if (!this.readySettled) {
+ this.readySettled = true;
+ this.resolveReady();
+ }
+ // after the step that made it terminal has finished (onTransition first)
+ queueMicrotask(() => this.resolveTerminal(this.snapshot()));
+ if (!this.reapPromise) this.reapPromise = this.reap();
+ }
+
+ private files(): { paneId: string; sockPath: string; launcherDir: string; turnDir: string } {
+ return {
+ paneId: this.paneId,
+ sockPath: this.sockPath,
+ launcherDir: this.ctlDir,
+ turnDir: this.turnDir,
+ };
+ }
+
+ private ms(normal: number, fast: number): number {
+ return this.fastReap ? fast : normal;
+ }
+
+ private async waitFor(pred: () => boolean, ms: number): Promise<void> {
+ const end = Date.now() + ms;
+ while (!pred() && Date.now() < end) await Bun.sleep(25);
+ }
+
+ /** §2.10 — close_pane, magmux by its handle, the verified group backstop, verify, clean, watcher. */
+ private async reap(): Promise<void> {
+ await Promise.resolve(); // let the terminal step finish first
+ this.reaping = true;
+ if (this.ticker) clearInterval(this.ticker);
+ this.ticker = null;
+ await this.captureGroupBeforeReap();
+ const c = this.client;
+ if (c && !c.isClosed && !this.paneClosed) {
+ const r = await c.request({ type: "close_pane", pane: 0, force: true }, this.ms(1000, 500));
+ if (r.ok || r.code === "no_such_pane")
+ await this.waitFor(() => this.paneClosed || c.isClosed, this.ms(3000, 1000));
+ }
+ if (this.magmux) await waitForExit(this.magmux, this.ms(3000, 1000));
+ if (alive(this.magmux)) {
+ this.magmux?.kill("SIGTERM");
+ if (this.magmux) await waitForExit(this.magmux, this.ms(2000, 500));
+ if (alive(this.magmux)) this.magmux?.kill("SIGKILL");
+ if (this.magmux) await waitForExit(this.magmux, 1000);
+ }
+ await this.groupBackstop();
+ await this.verifyAndClean();
+ }
+
+ /** Step 0: refresh the verified group while its members still carry their identity. */
+ private async captureGroupBeforeReap(): Promise<void> {
+ const table = await readProcessTableAsync();
+ if (!this.panePidValue && this.magmux?.pid) {
+ const lead = table.find((r) => r.ppid === this.magmux?.pid && r.pgid === r.pid);
+ if (lead) {
+ const snap = verifiedGroupSnapshot(table, lead.pgid, this.identity);
+ if (snap) this.panePidValue = lead.pid;
+ }
+ }
+ refreshGroupOf(this, table);
+ }
+
+ private async groupAlive(): Promise<boolean> {
+ return !!this.group && groupCheck(await readProcessTableAsync(), this.group);
+ }
+
+ private async groupBackstop(): Promise<void> {
+ for (const sig of ["SIGTERM", "SIGKILL"] as const) {
+ if (!this.group || !(await this.groupAlive())) return;
+ try {
+ process.kill(-this.group.pgid, sig);
+ } catch {
+ return;
+ }
+ const end = Date.now() + (sig === "SIGTERM" ? this.ms(2000, 500) : 1000);
+ while (Date.now() < end && (await this.groupAlive())) await Bun.sleep(150);
+ }
+ }
+
+ private async verifyAndClean(): Promise<void> {
+ const groupGone = !(await this.groupAlive());
+ const magGone = !alive(this.magmux);
+ this.client?.close();
+ if (groupGone && magGone) {
+ removePaneFiles(this.root, this.files());
+ this.reapFailed = false;
+ await this.endWatcher();
+ unregisterPane(this.paneId);
+ return;
+ }
+ this.reapFailed = true;
+ this.anomaly("reap_unverified");
+ updateRecord(this.root, this.paneId, { reapFailed: true });
+ }
+
+ /** Re-run steps 4–6 (the registry's 2 s tick, after an unverified reap). */
+ async retryReap(): Promise<boolean> {
+ if (alive(this.magmux)) this.magmux?.kill("SIGKILL");
+ await this.groupBackstop();
+ await this.verifyAndClean();
+ return !this.reapFailed;
+ }
+
+ /** Step 6, only after a verified reap: `done`, end stdin, then SIGKILL through the handle. */
+ private async endWatcher(): Promise<void> {
+ const w = this.watcher;
+ if (!w || !alive(w)) return;
+ try {
+ w.stdin?.write("done\n");
+ w.stdin?.end();
+ } catch {
+ // EPIPE: the watcher is already gone (R3-M1)
+ }
+ await waitForExit(w, 1000);
+ if (alive(w)) w.kill("SIGKILL");
+ }
+
+ async shutdownReap(_reason: string): Promise<void> {
+ this.fastReap = true;
+ if (!isTerminalPhase(this.phase)) this.step(() => this.fire("cancel"));
+ await (this.reapPromise ?? Promise.resolve());
+ }
+
+ killMagmuxSync(): void {
+ if (alive(this.magmux)) this.magmux?.kill("SIGKILL");
+ }
+}
+
+function isControl(text: string): boolean {
+ const t = text.trim();
+ return t === "/exit" || t === "/quit";
+}
+
+/** The question or dialog text a block reports to the owner. */
+function blockText(pending: { name: string; input?: unknown }, dialog: string | null): string {
+ if (pending.name === "AskUserQuestion") {
+ const qs = (pending.input as { questions?: Array<{ question?: unknown }> } | undefined)
+ ?.questions;
+ const text = (qs ?? [])
+ .map((q) => (typeof q.question === "string" ? q.question : ""))
+ .filter(Boolean);
+ if (text.length) return text.join("\n");
+ }
+ return dialog ?? pending.name;
+}
+
+/* ───────────────────────────── the entry point ───────────────────────────── */
+
+export class PaneStartError extends Error {
+ constructor(
+ readonly code: string,
+ message: string
+ ) {
+ super(message);
+ }
+}
+
+interface PreparedPane {
+ paneId: string;
+ sockPath: string;
+ cwd: string;
+ ctlDir: string;
+ turnDir: string;
+ magmuxEnv: Record<string, string>;
+}
+
+/** Ids, dirs, launcher and environment. Nothing is spawned; on a throw the dirs are removed. */
+function preparePane(
+ o: PaneSessionOptions,
+ root: string,
+ parentEnv: Record<string, string | undefined>
+): PreparedPane {
+ let dirs: { ctlDir: string; turnDir: string } | null = null;
+ try {
+ const paneId = mintPaneId(o.kind, o.label);
+ const sockPath = sockPathFor(root, paneId);
+ const cwd = realpathSync(o.cwd);
+ const launch = o.claudishSpawn ?? resolveClaudishLaunch(parentEnv);
+ dirs = createLaunchDirs(root);
+ const argv = buildClaudishPaneArgv(o.spawnModel, o.sessionUuid, dirs.turnDir, o.callerFlags);
+ writeLauncherFiles(dirs.ctlDir, launcherScript(cwd, launch, argv));
+ const { magmuxEnv } = buildPaneEnv({ parentEnv, slotEnv: o.slotEnv, cwd, ctlDir: dirs.ctlDir });
+ return { paneId, sockPath, cwd, ...dirs, magmuxEnv };
+ } catch (e) {
+ for (const d of dirs ? [dirs.ctlDir, dirs.turnDir] : [])
+ if (isLaunchDirPath(root, d)) rmSync(d, { recursive: true, force: true });
+ if ((e as { code?: string }).code) throw e;
+ throw new PaneStartError("pane_lost", e instanceof Error ? e.message : String(e));
+ }
+}
+
+/**
+ * Start a pane session. Throws `MagmuxUnavailableError`, `PaneLimitError` or
+ * `PaneStartError` BEFORE anything is spawned; installs the shutdown hooks (idempotent).
+ */
+export async function startPaneSession(o: PaneSessionOptions): Promise<PaneSession> {
+ if (SUBCOMMAND_WORDS.includes(o.spawnModel))
+ throw new PaneStartError(
+ "invalid_args",
+ `model "${o.spawnModel}" is a claudish subcommand name`
+ );
+ const parentEnv = o.parentEnv ?? process.env;
+ const magmux = await assertMagmuxAvailable(o.magmuxBinary);
+ const root = ensureSockRoot(o.sockRoot ?? sockRootFor(parentEnv));
+ await ensureSwept(root);
+ if (!paneShutdownHooksInstalled()) installPaneShutdownHooks();
+ // a reservation the owner made for this run, else our own (which checks the limit); the
+ // record is written before the next await, so the pane is never uncounted
+ if (!takePaneReservation()) {
+ reservePanes(1, root);
+ takePaneReservation();
+ }
+ const p = preparePane(o, root, parentEnv);
+ writeRecord(root, {
+ paneId: p.paneId,
+ ownerPid: process.pid,
+ ownerStart: ownerStartOfSelf(),
+ watcherPid: null,
+ magmuxPid: null,
+ panePid: null,
+ sessionUuid: o.sessionUuid,
+ sockPath: p.sockPath,
+ launcherDir: p.ctlDir,
+ turnDir: p.turnDir,
+ createdAt: new Date().toISOString(),
+ });
+ const session = new PaneSessionImpl(o, {
+ paneId: p.paneId,
+ sockPath: p.sockPath,
+ root,
+ ctlDir: p.ctlDir,
+ turnDir: p.turnDir,
+ });
+ registerPane(session);
+ await session.start({ magmuxBinary: magmux.binary, env: p.magmuxEnv, cwd: p.cwd });
+ return session;
+}
diff --git a/packages/cli/src/pane/transcript-follower.ts b/packages/cli/src/pane/transcript-follower.ts
index a7b70376..2cab1143 100644
--- a/packages/cli/src/pane/transcript-follower.ts
+++ b/packages/cli/src/pane/transcript-follower.ts
@@ -71,7 +71,8 @@ export interface TurnView {
/** a main-chain user record that wakes the model (task notification, Stop-hook feedback, an isMeta
* continuation) arrived after the last assistant record, and no assistant record followed it yet */
wakingAfterLast: boolean;
- pendingTool: { id: string; name: string } | null;
+ /** the latest unresolved tool_use; `input` is the tool's raw input (the question text of an AskUserQuestion) */
+ pendingTool: { id: string; name: string; input?: unknown } | null;
agentsLaunched: number;
agentsCompleted: number;
backgroundShellsOpen: string[];
@@ -130,6 +131,7 @@ interface TurnState {
interrupt: { forToolUse: boolean } | null;
waking: boolean;
pending: Map<string, string>; // tool_use id → name
+ pendingInput: Map<string, unknown>; // tool_use id → input
agents: Set<string>;
agentsDone: Set<string>;
shells: Map<string, string>; // backgroundTaskId → command
@@ -363,6 +365,7 @@ function applyAssistantBlock(state: FollowerState, t: TurnState, b: Rec, offset:
}
if (b?.type !== "tool_use" || typeof b.id !== "string") return;
t.pending.set(b.id, String(b.name ?? ""));
+ t.pendingInput.set(b.id, b.input);
if (b.name === "Bash" && b.input?.run_in_background)
t.shellToolIds.set(b.id, String(b.input?.command ?? ""));
applyReadUse(state, t, b);
@@ -373,6 +376,7 @@ function applyToolResults(t: TurnState, r: Rec, blocks: Rec[], offset: number):
for (const b of blocks) {
if (b?.type !== "tool_result") continue;
t.pending.delete(b.tool_use_id);
+ t.pendingInput.delete(b.tool_use_id);
// A background agent is recognised by its result, not by run_in_background in its input.
if (tur?.isAsync === true && typeof tur.agentId === "string") t.agents.add(tur.agentId);
if (typeof tur?.backgroundTaskId === "string")
@@ -402,6 +406,7 @@ function applyUser(t: TurnState, r: Rec, offset: number): void {
if (text.startsWith("[Request interrupted by user")) {
t.interrupt = { forToolUse: text.includes("for tool use") };
t.pending.clear();
+ t.pendingInput.clear();
return;
}
if (isTaskNotification(r)) applyNotification(t, text);
@@ -494,6 +499,7 @@ export function openTurnState(
interrupt: null,
waking: false,
pending: new Map(),
+ pendingInput: new Map(),
agents: new Set(),
agentsDone: new Set(),
shells: new Map(),
@@ -535,7 +541,9 @@ export function turnView(t: TurnState): TurnView {
stopHookSummaryAfterLast: t.stopHookAfterLast,
interruptAfterLast: t.interrupt,
wakingAfterLast: t.waking,
- pendingTool: pendingEntry ? { id: pendingEntry[0], name: pendingEntry[1] } : null,
+ pendingTool: pendingEntry
+ ? { id: pendingEntry[0], name: pendingEntry[1], input: t.pendingInput.get(pendingEntry[0]) }
+ : null,
agentsLaunched: t.agents.size,
agentsCompleted: [...t.agents].filter((a) => t.agentsDone.has(a)).length,
backgroundShellsOpen: [...t.shells.values()],
diff --git a/packages/cli/src/pane/types.ts b/packages/cli/src/pane/types.ts
index 5ecee7a5..0aee37f3 100644
--- a/packages/cli/src/pane/types.ts
+++ b/packages/cli/src/pane/types.ts
@@ -59,4 +59,8 @@ export interface PaneSnapshot {
panePid: number | null;
screenTail: string;
anomalies: string[];
+ /** the child's Claude Code version, read from its boot banner (R3-M4); null until seen */
+ claudeCodeVersion: string | null;
+ /** the session's shape now: a send to a one-shot session converts it to interactive */
+ shape: "one-shot" | "interactive";
}