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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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);+}