Skip to content

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

feat(mcp): add the pane screen model and screen classifier

Jack Rudenkofb10f8f6c131
diff --git a/packages/cli/src/pane/screen-classifier.test.ts b/packages/cli/src/pane/screen-classifier.test.ts
new file mode 100644
index 00000000..1599b3d9
--- /dev/null
+++ b/packages/cli/src/pane/screen-classifier.test.ts
@@ -0,0 +1,284 @@
+import { describe, expect, test } from "bun:test";
+import {
+ agentRejectedLine,
+ choiceDialog,
+ hasChoiceDialog,
+ inputBox,
+ isWorking,
+ readBoot,
+ screenAnswer,
+ screenErrorRows,
+ stopHookRunning,
+ transcriptSavingOff,
+} from "./screen-classifier.js";
+import { loadScreen } from "./test-helpers/fixtures.js";
+
+/** Every fixture screen, all real 2.1.290 captures (phase2-captures.md §3). */
+const REPL_SCREENS = [
+ "repl-boot-empty",
+ "repl-boot-placeholder",
+ "repl-typed",
+ "repl-typed-multiline",
+ "menu-at-open",
+ "menu-slash-open",
+ "menu-slash-command",
+ "repl-just-submitted",
+ "repl-settled",
+ "long-bash-running",
+ "numbered-prose-bash-running",
+ "background-agent-wait",
+ "ask-user-question-declined",
+ "bash-running-tip",
+ "interrupted-tool",
+ "streaming-answer",
+ "interrupted-streaming",
+ "permission-write-declined",
+ "stop-hook-running",
+ "stop-hook-settled",
+ "prompt-hook-running",
+ "api-error",
+];
+const DIALOG_SCREENS = [
+ "ask-user-question",
+ "permission-write",
+ "permission-bash",
+ "plan-approval",
+];
+
+describe("readBoot", () => {
+ test("the empty REPL box reads repl", () => {
+ expect(readBoot(loadScreen("repl-boot-empty"))).toEqual({ kind: "repl" });
+ });
+
+ test("the fresh-boot placeholder (faint cells) reads as an empty box (X-M14)", () => {
+ const s = loadScreen("repl-boot-placeholder");
+ // the box prompt is ❯ + NO-BREAK SPACE (U+00A0); echo rows above the box use a plain space
+ expect(s.lines.some((l) => l.startsWith('❯\u00a0Try "how does <filepath> work?"'))).toBe(true);
+ expect(inputBox(s)?.text).toBe("");
+ expect(readBoot(s)).toEqual({ kind: "repl" });
+ });
+
+ test("typed text is not an empty box", () => {
+ expect(inputBox(loadScreen("repl-typed"))?.text).toBe("alpha");
+ expect(inputBox(loadScreen("repl-typed-multiline"))?.text).toBe("alpha\nbeta");
+ expect(readBoot(loadScreen("repl-typed")).kind).toBe("booting");
+ });
+
+ for (const [screen, name, marker] of [
+ ["dialog-onboarding", "onboarding", "Choose the text style"],
+ ["dialog-trust", "trust", "Is this a project you created or one you trust"],
+ ["dialog-bypass", "bypass", "running in Bypass Permissions mode"],
+ ] as const) {
+ test(`names the ${name} dialog from its verbatim capture`, () => {
+ const s = loadScreen(screen);
+ expect(s.alt).toBe(false); // 2.1.290 draws boot dialogs on the primary screen
+ const r = readBoot(s);
+ expect(r.kind).toBe("dialog");
+ if (r.kind === "dialog") {
+ expect(r.name).toBe(name);
+ expect(r.text).toContain(marker);
+ }
+ });
+ }
+
+ test("an unnumbered dialog outside the closed list reads as an unnamed choice", () => {
+ const r = readBoot(loadScreen("dialog-unnamed-mcp-server"));
+ expect(r.kind).toBe("choice");
+ if (r.kind === "choice") expect(r.text).toContain("New MCP server found in this project");
+ });
+
+ test("the agent-rejection screen is neither a REPL nor a dialog", () => {
+ expect(readBoot(loadScreen("agent-rejected"))).toEqual({ kind: "booting" });
+ });
+});
+
+describe("inputBox", () => {
+ test("every REPL screen has a box; every turn dialog replaces it", () => {
+ for (const n of REPL_SCREENS) expect(inputBox(loadScreen(n))).not.toBeNull();
+ for (const n of DIALOG_SCREENS) expect(inputBox(loadScreen(n))).toBeNull();
+ expect(inputBox(loadScreen("usage-panel"))).toBeNull();
+ });
+
+ test("the box sits on rows 45-47 of the 50-row pane", () => {
+ const b = inputBox(loadScreen("repl-settled"))!;
+ expect([b.top, b.bottom]).toEqual([45, 47]);
+ expect(b.text).toBe("");
+ });
+
+ test("menus open above the top rule: slash command, slash list, @ list", () => {
+ const pear = inputBox(loadScreen("menu-slash-command"))!;
+ expect(pear).toMatchObject({ text: "/pear", menuOpen: true, menuItem: "/pear" });
+ const slash = inputBox(loadScreen("menu-slash-open"))!;
+ expect(slash).toMatchObject({ text: "/", menuOpen: true, menuItem: "/add-dir" });
+ const at = inputBox(loadScreen("menu-at-open"))!;
+ expect(at.text).toBe("look at @");
+ expect(at.menuOpen).toBe(true);
+ expect(at.menuItem).toBeNull();
+ expect(inputBox(loadScreen("repl-settled"))!.menuOpen).toBe(false);
+ expect(inputBox(loadScreen("repl-typed"))!.menuOpen).toBe(false);
+ });
+});
+
+describe("hasChoiceDialog — the closed list (R3-H1)", () => {
+ test("permission dialogs (Write and Bash) are permission choices", () => {
+ expect(choiceDialog(loadScreen("permission-write"))).toMatchObject({ kind: "permission" });
+ expect(choiceDialog(loadScreen("permission-write"))!.text).toContain(
+ "Do you want to create hello.txt?"
+ );
+ expect(choiceDialog(loadScreen("permission-bash"))).toMatchObject({ kind: "permission" });
+ });
+
+ test("plan approval (no No row, no (esc) row) is a plan choice", () => {
+ const d = choiceDialog(loadScreen("plan-approval"))!;
+ expect(d.kind).toBe("plan");
+ expect(d.text).toContain("Would you like to proceed?");
+ });
+
+ test("AskUserQuestion is a question choice", () => {
+ const d = choiceDialog(loadScreen("ask-user-question"))!;
+ expect(d.kind).toBe("question");
+ expect(d.text).toContain("Which fruit do you prefer?");
+ });
+
+ test("NEGATIVE: numbered prose containing a No… row above a running Bash is not a dialog", () => {
+ const s = loadScreen("numbered-prose-bash-running");
+ expect(
+ s.lines.some((l) => l.includes("2. No, and tell Claude what to do differently (esc)"))
+ ).toBe(true);
+ expect(hasChoiceDialog(s)).toBe(false);
+ });
+
+ test("NEGATIVE: a working spinner row is not a dialog", () => {
+ for (const n of [
+ "long-bash-running",
+ "bash-running-tip",
+ "stop-hook-running",
+ "prompt-hook-running",
+ "streaming-answer",
+ ])
+ expect(hasChoiceDialog(loadScreen(n))).toBe(false);
+ });
+
+ test("NEGATIVE: no REPL screen, boot dialog or panel reads as a turn dialog", () => {
+ for (const n of REPL_SCREENS) expect(hasChoiceDialog(loadScreen(n))).toBe(false);
+ for (const n of [
+ "dialog-onboarding",
+ "dialog-trust",
+ "dialog-bypass",
+ "dialog-unnamed-mcp-server",
+ "usage-panel",
+ "agent-rejected",
+ ])
+ expect(hasChoiceDialog(loadScreen(n))).toBe(false);
+ });
+});
+
+describe("isWorking / stopHookRunning", () => {
+ test("the 2.1.290 working rows read as working", () => {
+ for (const n of [
+ "long-bash-running",
+ "numbered-prose-bash-running",
+ "bash-running-tip",
+ "stop-hook-running",
+ "prompt-hook-running",
+ ])
+ expect(isWorking(loadScreen(n))).toBe(true);
+ });
+
+ test("finished rows (no ellipsis) and idle screens do not", () => {
+ for (const n of [
+ "repl-boot-empty",
+ "repl-settled",
+ "stop-hook-settled",
+ "interrupted-tool",
+ "api-error",
+ "ask-user-question-declined",
+ ])
+ expect(isWorking(loadScreen(n))).toBe(false);
+ });
+
+ test("the Stop-hook working row is recognised", () => {
+ expect(stopHookRunning(loadScreen("stop-hook-running"))).toBe(true);
+ expect(stopHookRunning(loadScreen("stop-hook-settled"))).toBe(false);
+ expect(stopHookRunning(loadScreen("prompt-hook-running"))).toBe(false);
+ });
+});
+
+describe("screenErrorRows", () => {
+ test("the API error is a ⏺ row", () => {
+ expect(screenErrorRows(loadScreen("api-error"))).toEqual([
+ "⏺ Please run /login · API Error: 401 OAuth access token is invalid.",
+ ]);
+ });
+
+ test("no error rows on ordinary screens", () => {
+ for (const n of REPL_SCREENS.filter((x) => x !== "api-error"))
+ expect(screenErrorRows(loadScreen(n))).toEqual([]);
+ });
+});
+
+describe("screenAnswer (degraded mode)", () => {
+ test("the settled PEAR answer", () => {
+ expect(
+ screenAnswer(loadScreen("repl-settled"), "Reply with exactly PEAR and nothing else.")
+ ).toBe("PEAR");
+ });
+
+ test("a multi-line prose answer keeps its continuation rows and drops the running tool rows", () => {
+ const echo =
+ "First write, as plain text, a numbered list with exactly these three items: 1. Yes, it ran 2. No, and tell Claude what to do differently (esc) 3. Maybe";
+ expect(screenAnswer(loadScreen("numbered-prose-bash-running"), echo)).toBe(
+ "1. Yes, it ran\n2. No, and tell Claude what to do differently (esc)\n3. Maybe later"
+ );
+ });
+
+ test("tool header rows (Bash description, Agent, Background command) are not answer text", () => {
+ const s = loadScreen("long-bash-running");
+ expect(
+ screenAnswer(
+ s,
+ "Run this exact command with the Bash tool: sleep 12; echo LONGDONE — then reply with its output only."
+ )
+ ).toBe("");
+ const bg = loadScreen("background-agent-wait");
+ const echo =
+ "Use the Agent tool with run_in_background set to true, subagent_type general-purpose, description fruit, and prompt: Reply with the word OK and nothing else.";
+ expect(screenAnswer(bg, echo)).toBe("LAUNCHED");
+ });
+
+ test("an error row is not an answer", () => {
+ expect(screenAnswer(loadScreen("api-error"), "Reply with exactly PEAR and nothing else.")).toBe(
+ ""
+ );
+ });
+
+ test("no echo, no answer", () => {
+ expect(screenAnswer(loadScreen("repl-boot-empty"), "anything")).toBe("");
+ });
+});
+
+describe("agentRejectedLine", () => {
+ test("reads the full line from the final screen", () => {
+ const text = loadScreen("agent-rejected").lines.join("\n");
+ expect(agentRejectedLine(text)).toBe(
+ "--agent 'zzz-not-real' not found. Available agents: claude, claude-code-guide, Explore, general-purpose, Plan, statusline-setup"
+ );
+ });
+
+ test("matches magmux's truncated exit.lastLine (captured verbatim)", () => {
+ expect(agentRejectedLine("--agent 'zzz-not-real' not found. Avail…")).toBe(
+ "--agent 'zzz-not-real' not found."
+ );
+ });
+
+ test("no match on ordinary text", () => {
+ expect(agentRejectedLine("[claudish] Model: haiku")).toBeNull();
+ });
+});
+
+describe("transcriptSavingOff", () => {
+ test("is false on every captured screen (F4 strips its cause)", () => {
+ for (const n of [...REPL_SCREENS, ...DIALOG_SCREENS])
+ expect(transcriptSavingOff(loadScreen(n))).toBe(false);
+ });
+});
diff --git a/packages/cli/src/pane/screen-classifier.ts b/packages/cli/src/pane/screen-classifier.ts
new file mode 100644
index 00000000..33880250
--- /dev/null
+++ b/packages/cli/src/pane/screen-classifier.ts
@@ -0,0 +1,300 @@
+/**
+ * What Claude Code's screen says (architecture §2.6), with every marker taken from a
+ * verbatim capture of Claude Code 2.1.290 in a headless magmux pane
+ * (`ai-docs/reports/mcp-magmux-panes/phase2-captures.md`, fixtures in
+ * `test-fixtures/screens/`).
+ *
+ * The screen is never the turn oracle — the transcript is (D3). The screen decides boot
+ * readiness, names the dialogs that block boot, recognises the choice dialogs a turn can
+ * block on, and supplies the degraded-mode answer and error rows. Every rule below is a
+ * CLOSED list: an unrecognised layout reads as "not a dialog" (stay RUNNING, an honest
+ * unknown), never as `blocked` (R3-H1).
+ */
+
+import type { SpanRun } from "./contract.js";
+import { type ScreenState, boxTopRow, isBoxRule } from "./screen-model.js";
+
+export type NamedDialog = "onboarding" | "trust" | "bypass" | "api_key";
+
+export type BootReading =
+ | { kind: "repl" } // input box: rule / line starting "❯" / rule, nothing typed
+ | { kind: "dialog"; name: NamedDialog; text: string }
+ | { kind: "choice"; text: string } // unnamed blocking screen, no input box
+ | { kind: "booting" };
+
+/**
+ * The named first-run dialogs. They only NAME a dialog; whether boot is blocked is
+ * decided by "no input box". 2.1.290 draws all of them on the primary screen.
+ */
+export const NAMED_DIALOGS: ReadonlyArray<{ name: NamedDialog; marker: string }> = [
+ { name: "onboarding", marker: "Choose the text style" },
+ { name: "trust", marker: "Is this a project you created or one you trust" },
+ { name: "bypass", marker: "running in Bypass Permissions mode" },
+ // Not recaptured on 2.1.290 (needs a foreign route with ANTHROPIC_API_KEY set);
+ // verbatim 2.1.287 text from research-scratch/run-empty-config5-claudish-foreign.txt.
+ { name: "api_key", marker: "Detected a custom API key in your environment" },
+];
+
+export type ChoiceDialogKind = "permission" | "plan" | "question";
+
+/**
+ * The choice dialogs a RUNNING turn can block on (R3-H1's closed list). Each header is
+ * verbatim from a 2.1.290 capture. None of them has a `No, and tell Claude …(esc)` row
+ * any more: permission ends `3. No` / `Esc to cancel · Tab to amend`, plan approval has
+ * no No row at all, AskUserQuestion ends `Enter to select · ↑/↓ to navigate · Esc to cancel`.
+ */
+export const CHOICE_DIALOGS: ReadonlyArray<{ kind: ChoiceDialogKind; header: RegExp }> = [
+ { kind: "permission", header: /\bDo you want to proceed\?/ },
+ {
+ kind: "permission",
+ header: /\bDo you want to (create|make this edit to|overwrite|delete) .+\?/,
+ },
+ { kind: "plan", header: /\bWould you like to proceed\?/ },
+ { kind: "question", header: /Enter to select · ↑\/↓ to navigate/ },
+];
+
+/** A numbered option row, optionally under the `❯` cursor: `❯ 1. Yes`, ` 2. Pear`. */
+const NUMBERED_OPTION = /^\s*(❯\s*)?\d+\.\s+\S/;
+const FIRST_OPTION = /^\s*(❯\s*)?1\.\s+\S/;
+
+/** Footers of 2.1.290's selection dialogs (boot dialogs have no numbers). */
+const SELECT_FOOTER = /Enter to (confirm|select)\b.*Esc to cancel/;
+
+/** The working row: glyph, a capitalised word ending in `…`, an optional `(…)`. */
+const WORKING_ROW = /^\s*[·✢✳✶✻✽*●∗]\s+[A-Z][\w'-]*…(\s+\(.*\))?\s*$/;
+
+/** Bullet of an assistant message block. */
+const BULLET = /^⏺(\s|$)/;
+
+/** Error rows. 2.1.290 renders an API error as a `⏺` row. */
+const ERROR_ROW =
+ /^⏺\s.*(API Error\b|Please run \/login|Not logged in|You've hit your|session limit)|^\s*⎿\s+API Error\b/;
+
+/** Attribute bit magmux passes through for faint (placeholder / ghost text). */
+export const ATTR_FAINT = 2;
+
+export function screenText(s: ScreenState): string {
+ const lines = [...s.lines];
+ while (lines.length && !lines[lines.length - 1]?.trim()) lines.pop();
+ return lines.join("\n");
+}
+
+/** Characters of `line` whose cell is NOT faint. Columns are code-point indexes. */
+function visibleText(line: string, spans: readonly SpanRun[] | undefined): string {
+ if (!spans?.length) return line;
+ const chars = Array.from(line);
+ for (const [col, len, , , attr] of spans) {
+ if ((attr & ATTR_FAINT) === 0) continue;
+ for (let c = col; c < col + len && c < chars.length; c++) chars[c] = " ";
+ }
+ return chars.join("");
+}
+
+export interface InputBox {
+ top: number; // row of the top rule
+ bottom: number; // row of the bottom rule
+ text: string; // typed text, placeholder (faint) cells excluded, trimmed
+ menuOpen: boolean;
+ menuItem: string | null;
+}
+
+const MENU_ROW = /^\s{2}❯ \/\S|^\s{4}\/\S|^\s{4}[*+] \S/;
+
+/**
+ * The REPL input box, or null when none is drawn. `text` is built from the box rows'
+ * cells minus faint styling, so the fresh-boot placeholder (`❯ Try "how does <filepath>
+ * work?"`, attr 2) reads as empty while typed text (no span) does not (X-M14).
+ */
+export function inputBox(s: ScreenState): InputBox | null {
+ const top = boxTopRow(s.lines, s.cols);
+ if (top < 0) return null;
+ const bottom = boxBottomRow(s, top);
+ if (bottom < 0) return null;
+ return { top, bottom, text: boxText(s, top, bottom), ...menuAbove(s.lines, top) };
+}
+
+function boxBottomRow(s: ScreenState, top: number): number {
+ for (let i = top + 1; i < s.lines.length && i <= top + 40; i++)
+ if (isBoxRule(s.lines[i], s.cols)) return i;
+ return -1;
+}
+
+/** The box prompt is `❯` + NO-BREAK SPACE; continuation rows are indented two spaces. */
+function boxText(s: ScreenState, top: number, bottom: number): string {
+ const parts: string[] = [];
+ for (let i = top + 1; i < bottom; i++) {
+ const raw = visibleText(s.lines[i] ?? "", s.spans[i]);
+ const body = i === top + 1 ? raw.replace(/^❯\s?/, "") : raw.replace(/^ {2}/, "");
+ parts.push(body.replace(/\s+$/, ""));
+ }
+ return parts.join("\n").trim();
+}
+
+/** Menus (`/` commands, `@` files and agents) are drawn directly above the top rule. */
+function menuAbove(
+ lines: readonly string[],
+ top: number
+): { menuOpen: boolean; menuItem: string | null } {
+ let menuOpen = false;
+ let menuItem: string | null = null;
+ for (let i = top - 1; i >= 0 && i >= top - 12; i--) {
+ const l = lines[i] ?? "";
+ if (!l.trim()) break;
+ if (!MENU_ROW.test(l)) continue;
+ menuOpen = true;
+ menuItem = l.match(/^\s{2}❯ (\S+)/)?.[1] ?? menuItem;
+ }
+ return { menuOpen, menuItem };
+}
+
+/** Index of the last `⏺` block row, or -1. */
+function lastBulletRow(lines: readonly string[]): number {
+ for (let i = lines.length - 1; i >= 0; i--) if (BULLET.test(lines[i] ?? "")) return i;
+ return -1;
+}
+
+export interface ChoiceDialog {
+ kind: ChoiceDialogKind;
+ text: string;
+}
+
+/**
+ * A choice dialog a turn is blocked on — the closed list of R3-H1. True only when ALL
+ * hold: (a) a named header from CHOICE_DIALOGS is on screen, (b) no input box is drawn,
+ * (c) a numbered `1.` option row sits below the last `⏺` block. Numbered prose with a
+ * `No…` row above a running Bash fails (a) and (b); the working row fails all three.
+ */
+export function choiceDialog(s: ScreenState): ChoiceDialog | null {
+ if (inputBox(s)) return null;
+ const lines = s.lines;
+ const start = lastBulletRow(lines) + 1;
+ const below = lines.slice(start);
+ const kind = CHOICE_DIALOGS.find((d) => below.some((l) => d.header.test(l)))?.kind;
+ if (!kind) return null;
+ if (!below.some((l) => FIRST_OPTION.test(l))) return null;
+ return { kind, text: below.filter((l) => l.trim()).join("\n") };
+}
+
+export function hasChoiceDialog(s: ScreenState): boolean {
+ return choiceDialog(s) !== null;
+}
+
+/**
+ * "Claude Code is working" — defence in depth only (never required by any rule, M20).
+ * 2.1.290 shows no `esc to interrupt`; the working row is `✶ Simmering… (3s · ↓ 154 tokens)`,
+ * and the finished row (`✻ Baked for 15s · done 12:08 PM`) has no `…`.
+ */
+export function isWorking(s: ScreenState): boolean {
+ const top = boxTopRow(s.lines, s.cols);
+ const region = top >= 0 ? s.lines.slice(0, top) : s.lines;
+ return region.some((l) => WORKING_ROW.test(l));
+}
+
+/** A Stop hook is running: `· Processing… (running Stop hook · 2s …)`. */
+export function stopHookRunning(s: ScreenState): boolean {
+ return s.lines.some((l) => /\(running Stop hook\b/.test(l));
+}
+
+export function transcriptSavingOff(s: ScreenState): boolean {
+ return s.lines.some((l) => l.includes("Transcript saving is off"));
+}
+
+export function screenErrorRows(s: ScreenState): string[] {
+ return s.lines.filter((l) => ERROR_ROW.test(l)).map((l) => l.trim());
+}
+
+function isToolHeader(lines: readonly string[], i: number): boolean {
+ const l = lines[i] ?? "";
+ if (/^⏺ [A-Z][A-Za-z0-9_:-]*\(/.test(l)) return true; // ⏺ Write(hello.txt), ⏺ Agent(fruit)
+ if (/^⏺ Agent "[^"]*" (finished|failed)/.test(l)) return true;
+ if (/^⏺ Background command /.test(l)) return true;
+ if (/^⏺ User declined to answer questions/.test(l)) return true;
+ // A Bash description row: the next non-empty row is its `⎿ $ command` row.
+ for (let j = i + 1; j < lines.length && j <= i + 2; j++) {
+ const n = lines[j] ?? "";
+ if (!n.trim()) continue;
+ return /^\s+⎿\s+\$ /.test(n);
+ }
+ return false;
+}
+
+const NON_ANSWER_ROW =
+ /^\s+⎿|^\s{2}(Ran|Read|Searched|Wrote|Edited|Listed|Updated) \d+ |^\s*[·✢✳✶✻✽*●∗]\s|^\s*\(ctrl\+/;
+
+/**
+ * Degraded-mode answer (C4): the `⏺` prose rows after the LAST echo of `echo` and
+ * their indented continuations, minus tool rows, sub-result rows (` ⎿ …`), collapsed
+ * tool summaries (` Ran 1 shell command`), working/finished rows and error rows (L14).
+ */
+export function screenAnswer(s: ScreenState, echo: string): string {
+ const lines = s.lines;
+ const top = boxTopRow(lines, s.cols);
+ const end = top >= 0 ? top : lines.length;
+ const start = echoRow(lines, end, `❯ ${echo.slice(0, 40)}`) + 1;
+ if (start <= 0) return "";
+ const out: string[] = [];
+ let inProse = false;
+ for (let i = start; i < end; i++) {
+ const row = answerRow(lines, i, inProse);
+ inProse = row.inProse;
+ if (row.text !== null) out.push(row.text);
+ }
+ return out.join("\n").trim();
+}
+
+/** The LAST row above `end` starting with `head`, or -1. */
+function echoRow(lines: readonly string[], end: number, head: string): number {
+ for (let i = end - 1; i >= 0; i--) if ((lines[i] ?? "").startsWith(head)) return i;
+ return -1;
+}
+
+/** One row of the degraded answer: its text (or null) and whether a prose block continues. */
+function answerRow(
+ lines: readonly string[],
+ i: number,
+ inProse: boolean
+): { text: string | null; inProse: boolean } {
+ const l = lines[i] ?? "";
+ if (BULLET.test(l)) {
+ const prose = !isToolHeader(lines, i) && !ERROR_ROW.test(l);
+ return { text: prose ? l.replace(/^⏺\s?/, "") : null, inProse: prose };
+ }
+ if (!l.trim()) return { text: inProse ? "" : null, inProse };
+ if (NON_ANSWER_ROW.test(l) || isToolHeader(lines, i)) return { text: null, inProse: false };
+ if (inProse && /^ {2}/.test(l)) return { text: l.slice(2), inProse: true };
+ return { text: null, inProse: false };
+}
+
+/**
+ * The child's own `--agent` refusal. magmux's `exit.lastLine` truncates long lines
+ * (`--agent 'zzz-not-real' not found. Avail…`, captured), so the agent list is optional
+ * here; read the full line from the final screen when it is needed.
+ */
+export function agentRejectedLine(text: string): string | null {
+ const m = text.match(/--agent '([^']+)' not found\.(?: Available agents:[^\n]*)?/);
+ return m ? m[0] : null;
+}
+
+function namedDialog(text: string): NamedDialog | null {
+ for (const d of NAMED_DIALOGS) if (text.includes(d.marker)) return d.name;
+ return null;
+}
+
+/** An unnamed static non-REPL screen with choice markers (M2). */
+function isUnnamedChoice(lines: readonly string[]): boolean {
+ const numbered = lines.some((l) => NUMBERED_OPTION.test(l));
+ const yesNo = lines.some((l) => /^\s*(❯\s*)?(\d+\.\s+)?(Yes|No)\b|\(esc\)/.test(l));
+ if (numbered && yesNo) return true;
+ return lines.some((l) => /Press Enter to continue/.test(l) || SELECT_FOOTER.test(l));
+}
+
+/** Boot reading: alt and primary screens both read (2.1.290's dialogs are on the primary one). */
+export function readBoot(s: ScreenState): BootReading {
+ const text = screenText(s);
+ const box = inputBox(s);
+ const named = namedDialog(text);
+ if (box && !named) return box.text === "" ? { kind: "repl" } : { kind: "booting" };
+ if (named) return { kind: "dialog", name: named, text };
+ if (isUnnamedChoice(s.lines)) return { kind: "choice", text };
+ return { kind: "booting" };
+}
diff --git a/packages/cli/src/pane/screen-model.test.ts b/packages/cli/src/pane/screen-model.test.ts
new file mode 100644
index 00000000..66f5d0b2
--- /dev/null
+++ b/packages/cli/src/pane/screen-model.test.ts
@@ -0,0 +1,152 @@
+import { describe, expect, test } from "bun:test";
+import {
+ type MagmuxFrame,
+ applyCapture,
+ applyFrame,
+ boxTopRow,
+ emptyScreen,
+} from "./screen-model.js";
+import { loadFrames, loadScreen } from "./test-helpers/fixtures.js";
+
+function replayFrames(frames: MagmuxFrame[]) {
+ let s = emptyScreen(160, 50);
+ let t = 1000;
+ for (const f of frames) {
+ t += 250;
+ s = applyFrame(s, f, t);
+ }
+ return s;
+}
+
+describe("screen-model over real magmux frames (phase-2 s01)", () => {
+ const frames = loadFrames("boot-keylog-turn");
+
+ test("seq is 0 before the first frame and 1 after the first keyframe", () => {
+ const s0 = emptyScreen(160, 50);
+ expect(s0.seq).toBe(0);
+ expect(s0.lines).toHaveLength(50);
+ expect(frames[0]?.key).toBe(true);
+ const s1 = applyFrame(s0, frames[0]!, 5);
+ expect(s1.seq).toBe(1);
+ expect(s1.changedAt).toBe(5);
+ });
+
+ test("re-applying the same frame is not a visible change", () => {
+ const s1 = applyFrame(emptyScreen(160, 50), frames[0]!, 5);
+ const s2 = applyFrame(s1, frames[0]!, 9);
+ expect(s2.seq).toBe(1);
+ expect(s2.changedAt).toBe(5);
+ });
+
+ test("the replayed frames reproduce the captured settled screen", () => {
+ const s = replayFrames(frames);
+ const settled = loadScreen("repl-settled");
+ expect(s.lines).toHaveLength(50);
+ // The settled snapshot was taken mid-run; the last frame is the idle screen after it.
+ expect(s.lines.slice(0, 11)).toEqual(settled.lines.slice(0, 11));
+ expect(s.lines[46]).toBe("❯");
+ expect(boxTopRow(s.lines, s.cols)).toBe(45);
+ expect(s.seq).toBeGreaterThan(5);
+ expect(s.seq).toBeLessThanOrEqual(frames.length);
+ });
+
+ test("a spans-only change bumps seq; a cursor move bumps seq", () => {
+ const base = replayFrames(frames);
+ const row = 46;
+ const styled: MagmuxFrame = {
+ rows: 50,
+ cols: 160,
+ alt: base.alt,
+ cur: { y: base.cursor.y, x: base.cursor.x },
+ key: false,
+ lines: [{ y: row, t: base.lines[row], r: [[0, 1, 1, -1, 1]] }],
+ };
+ const s1 = applyFrame(base, styled, 1);
+ expect(s1.lines[row]).toBe(base.lines[row]);
+ expect(s1.seq).toBe(base.seq + 1);
+ const moved = applyFrame(
+ s1,
+ { rows: 50, cols: 160, alt: base.alt, cur: { y: 0, x: 0 }, key: false, lines: [] },
+ 2
+ );
+ expect(moved.seq).toBe(s1.seq + 1);
+ });
+
+ test("an alt-screen flip alone bumps seq", () => {
+ const base = replayFrames(frames);
+ const flipped = applyFrame(
+ base,
+ { rows: 50, cols: 160, alt: !base.alt, cur: base.cursor, key: false, lines: [] },
+ 3
+ );
+ expect(flipped.seq).toBe(base.seq + 1);
+ });
+});
+
+describe("aboveBoxChangedAt", () => {
+ test("ignores the status rows under the box but moves for the working row above it", () => {
+ let s = emptyScreen(160, 50);
+ const screen = loadScreen("stop-hook-running");
+ s = applyFrame(
+ s,
+ {
+ rows: 50,
+ cols: 160,
+ alt: true,
+ key: true,
+ cur: screen.cursor,
+ lines: screen.lines.map((t, y) => ({ y, t, r: screen.spans[y] })),
+ },
+ 100
+ );
+ expect(s.aboveBoxChangedAt).toBe(100);
+ const top = boxTopRow(s.lines, s.cols);
+ expect(top).toBeGreaterThan(0);
+ // status line under the box ticks
+ const status = applyFrame(
+ s,
+ {
+ rows: 50,
+ cols: 160,
+ alt: true,
+ key: false,
+ cur: s.cursor,
+ lines: [{ y: 48, t: " cwd • haiku • $0.001 • N/A" }],
+ },
+ 200
+ );
+ expect(status.seq).toBe(s.seq + 1);
+ expect(status.aboveBoxChangedAt).toBe(100);
+ // the working row above the box ticks (captured every second during a Stop hook)
+ const workingRow = s.lines.findIndex((l) => l.includes("running Stop hook"));
+ expect(workingRow).toBeGreaterThan(-1);
+ expect(workingRow).toBeLessThan(top);
+ const tick = applyFrame(
+ status,
+ {
+ rows: 50,
+ cols: 160,
+ alt: true,
+ key: false,
+ cur: s.cursor,
+ lines: [{ y: workingRow, t: s.lines[workingRow]!.replace("· Processing", "✽ Processing") }],
+ },
+ 300
+ );
+ expect(tick.aboveBoxChangedAt).toBe(300);
+ });
+});
+
+describe("applyCapture", () => {
+ test("pads a capture's text back to rows and keeps seq monotonic", () => {
+ const s0 = applyFrame(emptyScreen(160, 50), loadFrames("agent-rejected")[0]!, 1);
+ const s1 = applyCapture(
+ s0,
+ { rows: 50, cols: 160, alt: false, cursor: { x: 0, y: 4 }, text: "a\nb" },
+ 2
+ );
+ expect(s1.lines).toHaveLength(50);
+ expect(s1.lines.slice(0, 3)).toEqual(["a", "b", ""]);
+ expect(s1.seq).toBe(s0.seq + 1);
+ });
+});
diff --git a/packages/cli/src/pane/screen-model.ts b/packages/cli/src/pane/screen-model.ts
new file mode 100644
index 00000000..3313f8d7
--- /dev/null
+++ b/packages/cli/src/pane/screen-model.ts
@@ -0,0 +1,189 @@
+/**
+ * magmux `watch` frames → an in-memory screen with claudish's OWN monotonic `seq`
+ * (architecture §2.5, D6).
+ *
+ * magmux's frame `seq` restarts at 1 whenever its framer is recreated (every reconnect),
+ * so it cannot back `capture(since_seq)`. Ours is 0 until the first frame is applied and
+ * then grows by one on every VISIBLE change — row text, spans, cursor, alt screen, rows
+ * or cols — for the pane's whole life.
+ *
+ * `aboveBoxChangedAt` moves only when a row ABOVE the input box's top rule changes, so a
+ * status line ticking under the box never holds a settle quiet window open (M3). In
+ * Claude Code 2.1.290 the working row (`· Processing… (running Stop hook · 2s …)`) sits
+ * above the box and is rewritten every second while anything runs, which is what keeps
+ * that window closed during a Stop hook (phase-2 capture s04).
+ */
+
+import type { SpanRun } from "./contract.js";
+
+export interface ScreenState {
+ seq: number;
+ cols: number;
+ rows: number;
+ cursor: { x: number; y: number };
+ lines: string[];
+ spans: SpanRun[][];
+ alt: boolean;
+ changedAt: number;
+ aboveBoxChangedAt: number;
+}
+
+/** One magmux `frame` event (protocol/frame.go), as it arrives on the socket. */
+export interface MagmuxFrame {
+ type?: "frame";
+ pane?: number;
+ seq?: number;
+ rows: number;
+ cols: number;
+ alt?: boolean;
+ sb?: number;
+ scrolled?: boolean;
+ cur?: { y: number; x: number; vis?: boolean };
+ key?: boolean;
+ lines?: Array<{ y: number; t?: string; r?: SpanRun[]; wd?: number[] }>;
+}
+
+/** A magmux `capture` reply's `result`. */
+export interface MagmuxCapture {
+ rows: number;
+ cols: number;
+ alt?: boolean;
+ cursor?: { y: number; x: number };
+ text: string;
+}
+
+export function emptyScreen(cols: number, rows: number): ScreenState {
+ return {
+ seq: 0,
+ cols,
+ rows,
+ cursor: { x: 0, y: 0 },
+ lines: Array.from({ length: rows }, () => ""),
+ spans: Array.from({ length: rows }, () => []),
+ alt: false,
+ changedAt: 0,
+ aboveBoxChangedAt: 0,
+ };
+}
+
+/** A full-width box rule: only `─`, at least 20 of them and at least cols−1 wide. */
+export function isBoxRule(line: string | undefined, cols: number): boolean {
+ if (!line || !/^─+$/.test(line)) return false;
+ return line.length >= Math.max(20, Math.min(cols, 160) - 1);
+}
+
+/**
+ * Row index of the input box's top rule: the LAST full-width rule whose next row starts
+ * with `❯`. -1 when no input box is drawn (a dialog replaced it, or boot).
+ */
+export function boxTopRow(lines: readonly string[], cols: number): number {
+ for (let i = lines.length - 2; i >= 0; i--) {
+ if (isBoxRule(lines[i], cols) && /^❯/.test(lines[i + 1] ?? "")) return i;
+ }
+ return -1;
+}
+
+function rightTrim(s: string): string {
+ return s.replace(/\s+$/, "");
+}
+
+function sameSpans(a: SpanRun[] | undefined, b: SpanRun[] | undefined): boolean {
+ return JSON.stringify(a ?? []) === JSON.stringify(b ?? []);
+}
+
+function withSize(s: ScreenState, rows: number): { lines: string[]; spans: SpanRun[][] } {
+ const lines = s.lines.slice(0, rows);
+ const spans = s.spans.slice(0, rows);
+ while (lines.length < rows) lines.push("");
+ while (spans.length < rows) spans.push([]);
+ return { lines, spans };
+}
+
+function aboveBoxText(lines: readonly string[], cols: number): string {
+ const top = boxTopRow(lines, cols);
+ return (top >= 0 ? lines.slice(0, top) : lines).join("\n");
+}
+
+function finish(
+ prev: ScreenState,
+ next: Omit<ScreenState, "seq" | "changedAt" | "aboveBoxChangedAt">,
+ now: number
+): ScreenState {
+ const visible =
+ prev.seq === 0 ||
+ prev.cols !== next.cols ||
+ prev.rows !== next.rows ||
+ prev.alt !== next.alt ||
+ prev.cursor.x !== next.cursor.x ||
+ prev.cursor.y !== next.cursor.y ||
+ next.lines.some((l, i) => l !== prev.lines[i]) ||
+ next.spans.some((r, i) => !sameSpans(r, prev.spans[i]));
+ if (!visible) return prev;
+ const aboveChanged =
+ prev.seq === 0 || aboveBoxText(prev.lines, prev.cols) !== aboveBoxText(next.lines, next.cols);
+ return {
+ ...next,
+ seq: prev.seq + 1,
+ changedAt: now,
+ aboveBoxChangedAt: aboveChanged ? now : prev.aboveBoxChangedAt,
+ };
+}
+
+/** Apply one watch frame. A keyframe replaces every row; a delta replaces the rows it names. */
+export function applyFrame(
+ s: ScreenState,
+ frame: MagmuxFrame,
+ now: number = Date.now()
+): ScreenState {
+ const rows = frame.rows;
+ const cols = frame.cols;
+ let { lines, spans } = withSize(s, rows);
+ if (frame.key) {
+ lines = Array.from({ length: rows }, () => "");
+ spans = Array.from({ length: rows }, () => []);
+ }
+ for (const row of frame.lines ?? []) {
+ if (row.y < 0 || row.y >= rows) continue;
+ lines[row.y] = rightTrim(row.t ?? "");
+ spans[row.y] = row.r ?? [];
+ }
+ return finish(
+ s,
+ {
+ cols,
+ rows,
+ cursor: { x: frame.cur?.x ?? s.cursor.x, y: frame.cur?.y ?? s.cursor.y },
+ lines,
+ spans,
+ alt: frame.alt ?? s.alt,
+ },
+ now
+ );
+}
+
+/**
+ * Apply a `capture` reply (the finalisation path, e.g. the dead pane's last screen).
+ * magmux strips trailing blank rows from `text`; this pads back to `rows`. A capture has
+ * no colours, so spans are cleared.
+ */
+export function applyCapture(
+ s: ScreenState,
+ cap: MagmuxCapture,
+ now: number = Date.now()
+): ScreenState {
+ const rows = cap.rows;
+ const lines = cap.text.split("\n").slice(0, rows).map(rightTrim);
+ while (lines.length < rows) lines.push("");
+ return finish(
+ s,
+ {
+ cols: cap.cols,
+ rows,
+ cursor: { x: cap.cursor?.x ?? s.cursor.x, y: cap.cursor?.y ?? s.cursor.y },
+ lines,
+ spans: Array.from({ length: rows }, () => []),
+ alt: cap.alt ?? s.alt,
+ },
+ now
+ );
+}
diff --git a/packages/cli/src/pane/test-helpers/fixtures.ts b/packages/cli/src/pane/test-helpers/fixtures.ts
new file mode 100644
index 00000000..a616773c
--- /dev/null
+++ b/packages/cli/src/pane/test-helpers/fixtures.ts
@@ -0,0 +1,39 @@
+/**
+ * Loaders for the phase-2 real-capture fixtures (`pane/test-fixtures/`): screens and frames. Test-only.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { SpanRun } from "../contract.js";
+import type { MagmuxFrame, ScreenState } from "../screen-model.js";
+
+export const FIXTURES = join(import.meta.dir, "..", "test-fixtures");
+
+export function loadScreen(name: string): ScreenState {
+ const j = JSON.parse(readFileSync(join(FIXTURES, "screens", `${name}.json`), "utf8")) as {
+ rows: number;
+ cols: number;
+ alt: boolean;
+ cursor: { x: number; y: number };
+ lines: string[];
+ spans: SpanRun[][];
+ };
+ return {
+ seq: 1,
+ cols: j.cols,
+ rows: j.rows,
+ cursor: { x: j.cursor.x, y: j.cursor.y },
+ lines: j.lines,
+ spans: j.spans,
+ alt: j.alt,
+ changedAt: 0,
+ aboveBoxChangedAt: 0,
+ };
+}
+
+export function loadFrames(name: string): MagmuxFrame[] {
+ return readFileSync(join(FIXTURES, "frames", `${name}.ndjson`), "utf8")
+ .split("\n")
+ .filter(Boolean)
+ .map((l) => JSON.parse(l) as MagmuxFrame);
+}