@gr8ful/spf 0.7.0 → 0.8.0

package/dist/cli/ui/fanout_dashboard.d.ts

@@ -0,0 +1,22 @@
+import { type FanoutAttempt } from "../../core/fanout.ts";
+export interface FanoutDashboard {
+    onAttempt: (attempt: FanoutAttempt) => void;
+    /** Routes `FanoutDeps.log()` here instead of `console.log` while this is mounted — see the module header for why a raw console write can't share the terminal with an active Ink instance. */
+    log: (message: string) => void;
+    /** Tears the Ink instance down. Call exactly once, after `runBestOf()` settles — the plain-text winner/basis lines after it are unaffected; only the redundant header + final table are skipped when a dashboard was used (see `cli/commands/fanout.ts`'s call site). */
+    close(): Promise<void>;
+    /**
+     * Synchronous, no flush-wait — for a signal handler, which stays
+     * synchronous by design and gets cut off by `process.exit()` immediately
+     * after: an `await` here would never get a chance to resume. Only
+     * restores terminal state (cursor visibility) on a best-effort basis; the
+     * final frame may not have caught up to the last attempt yet.
+     */
+    unmountNow(): void;
+}
+export declare function mountFanoutDashboard(opts: {
+    n: number;
+    chainName: string;
+    baseBranch: string;
+    baseAdwId: string;
+}): FanoutDashboard;

package/dist/cli/ui/fanout_dashboard.js

@@ -0,0 +1,102 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * A live results table for `spf fanout` — the same columns
+ * `cli/commands/fanout.ts`'s `printTable()` prints once at the end, updated
+ * row by row as each attempt settles instead. Reached only through a
+ * dynamic `import()` and only when `isInteractive()`; non-TTY keeps the
+ * exact one-shot `printTable()` path, byte for byte (`fanout_cli.test.ts`
+ * runs with no TTY, so it never touches this file).
+ *
+ * One persistent Ink instance for the whole `runBestOf()` call — same shape
+ * as `run_dashboard.tsx`: a `<Static>` history for `deps.log()`'s own
+ * lines (the "chain X x3 off main" opener, an "attempt N skipped" line —
+ * `cli/commands/fanout.ts` routes these here instead of straight to
+ * `console.log` specifically so nothing writes to stdout outside Ink while
+ * this is mounted; interleaving a raw `console.log` with an active Ink
+ * live region corrupts the redraw) plus a LIVE section below it — here,
+ * the whole results table, not one line, since every row can still change
+ * until the very last attempt settles and there's no "this phase is done"
+ * moment to freeze one into history the way `run_dashboard.tsx` does per
+ * phase. Nothing here calls `useInput`, so raw mode never engages.
+ */
+import { useState, useRef } from "react";
+import { render, Static, Box, Text } from "ink";
+import * as agents from "../../core/agents.js";
+import { attemptAdwId, attemptBranch } from "../../core/fanout.js";
+function statusLabel(row) {
+    if (!row)
+        return "running…";
+    return row.status;
+}
+function gatesLabel(row) {
+    if (!row || row.status === "skipped")
+        return "-";
+    return `${row.gate_passes}p/${row.gate_failures}f`;
+}
+function timeLabel(row) {
+    if (!row || row.status === "skipped")
+        return "-";
+    const seconds = row.wall_ms / 1000;
+    return seconds < 90 ? `${seconds.toFixed(1)}s` : `${Math.floor(seconds / 60)}m ${String(Math.round(seconds % 60)).padStart(2, "0")}s`;
+}
+function rowColor(row) {
+    if (!row)
+        return "dim";
+    if (row.status === "success")
+        return "green";
+    if (row.status === "fail" || row.status === "error")
+        return "red";
+    return undefined;
+}
+function FanoutRoot(props) {
+    const [rows, setRows] = useState(new Map());
+    const [log, setLog] = useState([]);
+    const keyRef = useRef(0); // a ref, not state — see ink_asker.tsx's identical comment on why two pushes in one tick must not collide
+    props.handleRef.current = {
+        setAttempt(attempt) {
+            setRows((prev) => {
+                const next = new Map(prev);
+                next.set(attempt.index, attempt);
+                return next;
+            });
+        },
+        pushLog(text) {
+            const key = keyRef.current++;
+            setLog((prev) => [...prev, { key, text }]);
+        },
+    };
+    const indices = Array.from({ length: props.n }, (_, i) => i + 1);
+    const widths = {
+        adw: Math.max(6, ...indices.map((i) => attemptAdwId(props.baseAdwId, i).length)),
+        branch: Math.max(6, ...indices.map((i) => attemptBranch(props.baseAdwId, i).length)),
+    };
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Static, { items: log, children: (line) => _jsx(Text, { children: line.text }, line.key) }), _jsxs(Text, { children: ["fanout ", props.chainName, " \u2014 ", props.n, " attempt(s), base ", props.baseBranch] }), _jsxs(Box, { children: [_jsx(Box, { width: 3, children: _jsx(Text, { dimColor: true, children: "#" }) }), _jsx(Box, { width: widths.adw, marginRight: 2, children: _jsx(Text, { dimColor: true, children: "adw_id" }) }), _jsx(Box, { width: widths.branch, marginRight: 2, children: _jsx(Text, { dimColor: true, children: "branch" }) }), _jsx(Box, { width: 9, children: _jsx(Text, { dimColor: true, children: "status" }) }), _jsx(Box, { width: 9, children: _jsx(Text, { dimColor: true, children: "gates" }) }), _jsx(Box, { width: 10, children: _jsx(Text, { dimColor: true, children: "cost" }) }), _jsx(Text, { dimColor: true, children: "time" })] }), indices.map((i) => {
+                const row = rows.get(i) ?? null;
+                const color = rowColor(row);
+                return (_jsxs(Box, { children: [_jsx(Box, { width: 3, children: _jsx(Text, { color: color, children: i }) }), _jsx(Box, { width: widths.adw, marginRight: 2, children: _jsx(Text, { color: color, children: attemptAdwId(props.baseAdwId, i) }) }), _jsx(Box, { width: widths.branch, marginRight: 2, children: _jsx(Text, { color: color, children: attemptBranch(props.baseAdwId, i) }) }), _jsx(Box, { width: 9, children: _jsx(Text, { color: color, children: statusLabel(row) }) }), _jsx(Box, { width: 9, children: _jsx(Text, { color: color, children: gatesLabel(row) }) }), _jsx(Box, { width: 10, children: _jsx(Text, { color: color, children: row ? agents.formatUsd(row.cost) : "-" }) }), _jsx(Text, { color: color, children: timeLabel(row) })] }, i));
+            })] }));
+}
+export function mountFanoutDashboard(opts) {
+    const handleRef = { current: null };
+    const app = render(_jsx(FanoutRoot, { n: opts.n, chainName: opts.chainName, baseBranch: opts.baseBranch, baseAdwId: opts.baseAdwId, handleRef: handleRef }), 
+    // `interactive: true` overrides Ink's own CI auto-detection — see
+    // `ink_asker.tsx`'s identical `render()` call for why: the caller
+    // (`commands/fanout.ts`) only reaches this file after its own
+    // `isInteractive()` check has already passed.
+    { patchConsole: false, interactive: true });
+    return {
+        onAttempt(attempt) {
+            handleRef.current?.setAttempt(attempt);
+        },
+        log(message) {
+            handleRef.current?.pushLog(message);
+        },
+        async close() {
+            await app.waitUntilRenderFlush();
+            app.unmount();
+        },
+        unmountNow() {
+            app.unmount();
+        },
+    };
+}

package/dist/cli/ui/ink_asker.d.ts

@@ -0,0 +1,13 @@
+import type { Asker } from "../ask.ts";
+/**
+ * The real `stdin`/`stdout` pair the interview reads/writes — defaults to
+ * the process's own. `src/test/ink_asker.test.ts` passes a fake TTY pair
+ * instead (`node --test` has neither a real terminal nor raw-mode
+ * support), the same seam Ink's own render options already expose; this
+ * is not new surface, just threaded through so a test can reach it.
+ */
+export interface RenderStreams {
+    stdin?: NodeJS.ReadStream;
+    stdout?: NodeJS.WriteStream;
+}
+export declare function createInkAsker(streams?: RenderStreams): Asker;

package/dist/cli/ui/ink_asker.js

@@ -0,0 +1,247 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Ink-backed implementation of the `Asker` interface (`cli/ask.ts`) — a
+ * drop-in replacement for `createAsker()`'s readline prompts, used only
+ * when `inkAvailable()` says raw-mode stdin is there to drive it.
+ * `runInterview()` (`cli/interview.ts`) never sees this file: it only ever
+ * imports the `Asker` type, so it is byte-for-byte unchanged by this
+ * module existing, and every `createFakeAsker`-driven test still exercises
+ * it exactly as before.
+ *
+ * This file is reached only through a dynamic `import()` (see
+ * `commands/init.ts`) so the ~150-300ms cost of loading `ink`+`react` is
+ * never paid on a non-interactive run.
+ *
+ * ONE Ink instance is mounted lazily on the first prompt and kept alive for
+ * the whole interview, torn down only in `close()`. An earlier version
+ * mounted a fresh instance per question instead — that toggled raw mode
+ * off (on unmount) and back on (on the next mount) between every single
+ * question, and empirically, over a real pty, a keystroke landing in that
+ * gap got echoed to the screen instead of consumed, and could be lost or
+ * misrouted entirely (arrow-key-then-Enter on the second question the
+ * default readline-vs-Ink smoke test tried was the one that caught it —
+ * the model select accepted the arrow move but the following Enter never
+ * registered). Keeping raw mode continuously enabled for the interview's
+ * entire lifetime removes the gap outright, and is also just the correct
+ * Ink pattern for a multi-step wizard: finished questions accumulate in an
+ * `<Static>` list (rendered once, never touched again — exactly the
+ * "leaves the final frame in scrollback" transcript this asker owes
+ * `runInterview()`) while the current question lives in one live slot
+ * below it, both children of the SAME root, updated by `rerender()`.
+ *
+ * `exitOnCtrlC: false`: `spf watch` and `core/session.ts` own SIGINT/
+ * SIGTERM handling, and Ink's default Ctrl-C behavior would call
+ * `process.exit()` out from under both. Ctrl-C (and Ctrl-D, treated the
+ * same way the readline asker treats EOF) is instead caught once, at the
+ * root, and turned into the same `InterviewAborted` the readline asker
+ * throws — `initCommand` catches it and exits 130, writing nothing.
+ */
+import { useRef, useState } from "react";
+import { render, Static, Box, Text, useInput } from "ink";
+import { ConfirmInput, PasswordInput, TextInput } from "@inkjs/ui";
+import { InterviewAborted, maskForPrompt } from "../ask.js";
+import { paint } from "../../core/console.js";
+function InterviewRoot(props) {
+    const [history, setHistory] = useState([]);
+    const [prompt, setPrompt] = useState(null);
+    // A ref, not `useState` — two `pushHistory` calls can happen back to back
+    // synchronously (e.g. `heading()` immediately followed by `note()`, exactly
+    // how `runInterview()` opens each section) with no re-render in between to
+    // flush a `nextKey` state update, so both would read the same stale value
+    // and mint duplicate keys. A ref's mutation is immediate or it wouldn't be
+    // safe as a counter at all.
+    const keyRef = useRef(0);
+    props.handleRef.current = {
+        pushHistory(node) {
+            const key = keyRef.current++;
+            setHistory((h) => [...h, { key, node }]);
+        },
+        setPrompt,
+    };
+    useInput((input, key) => {
+        if (key.ctrl && (input === "c" || input === "d"))
+            props.onAbort();
+    });
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Static, { items: history, children: (line) => _jsx(Box, { children: line.node }, line.key) }), prompt] }));
+}
+function TextPromptView(props) {
+    const [error, setError] = useState(null);
+    // `TextInput` is uncontrolled — `defaultValue` only seeds its FIRST value,
+    // so a rejected submit otherwise leaves the rejected text sitting in the
+    // box and whatever's typed next appends onto it instead of replacing it.
+    // Changing `key` forces React to unmount and remount a fresh instance
+    // (starting empty again) on every rejection, which is the standard way
+    // to "reset" an uncontrolled component.
+    const [attempt, setAttempt] = useState(0);
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Text, { children: props.label }), props.defaultValue ? _jsxs(Text, { dimColor: true, children: [" [", props.defaultValue, "]"] }) : null, _jsx(Text, { children: ": " }), _jsx(TextInput, { defaultValue: props.defaultValue, onSubmit: (value) => {
+                            const resolved = value || props.defaultValue || "";
+                            const problem = props.validate?.(resolved) ?? null;
+                            if (problem) {
+                                setError(problem);
+                                setAttempt((n) => n + 1);
+                                return;
+                            }
+                            props.onSubmit(resolved);
+                        } }, attempt)] }), error ? _jsxs(Text, { color: "red", children: ["  ", error] }) : null] }));
+}
+/**
+ * Hand-rolled instead of `@inkjs/ui`'s `Select` — that component's
+ * `onChange` only fires when its internal `value` differs from
+ * `previousValue` (`use-select-state.js`'s reducer + effect), and accepting
+ * the already-highlighted default via an immediate Enter, with no arrow
+ * key pressed first, never changes that value. That's the single most
+ * common interaction with any select prompt (take the default), so the
+ * bug isn't an edge case: every `select()` call whose first keypress is
+ * Enter would hang forever. Confirmed empirically before writing this —
+ * the same prompt resolves instantly the moment an arrow key precedes
+ * Enter. `ConfirmInput`/`TextInput`/`PasswordInput` call their callbacks
+ * unconditionally from their own input handlers and don't share this bug,
+ * so they're untouched.
+ */
+function SelectPromptView(props) {
+    const dfltIndex = props.choices.findIndex((c) => c.value === props.dflt);
+    const [index, setIndex] = useState(dfltIndex === -1 ? 0 : dfltIndex);
+    useInput((_input, key) => {
+        if (key.downArrow)
+            setIndex((i) => Math.min(props.choices.length - 1, i + 1));
+        if (key.upArrow)
+            setIndex((i) => Math.max(0, i - 1));
+        if (key.return)
+            props.onSubmit(props.choices[index].value);
+    });
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { children: props.label }), props.choices.map((c, i) => {
+                const focused = i === index;
+                const hint = c.hint ? paint("dim", ` — ${c.hint}`) : "";
+                return (_jsxs(Text, { color: focused ? "cyan" : undefined, children: [focused ? "❯ " : "  ", c.label ?? c.value, hint] }, c.value));
+            })] }));
+}
+function ConfirmPromptView(props) {
+    return (_jsxs(Box, { children: [_jsxs(Text, { children: [props.label, " "] }), _jsx(ConfirmInput, { defaultChoice: props.dflt ? "confirm" : "cancel", onConfirm: () => props.onSubmit(true), onCancel: () => props.onSubmit(false) })] }));
+}
+function SecretPromptView(props) {
+    return (_jsxs(Box, { children: [_jsx(Text, { children: props.label }), props.current ? _jsxs(Text, { dimColor: true, children: [" [keep current: ", maskForPrompt(props.current), "]"] }) : null, _jsx(Text, { children: ": " }), _jsx(PasswordInput, { onSubmit: props.onSubmit })] }));
+}
+export function createInkAsker(streams = {}) {
+    // Mirrors `createAsker()`'s own `aborted` flag: once a Ctrl-C/Ctrl-D fires,
+    // every later call throws immediately instead of showing a prompt that
+    // would just get torn down again.
+    let aborted = false;
+    // Whichever prompt is currently live — `InterviewRoot`'s single Ctrl-C/
+    // Ctrl-D handler rejects THIS, whatever it is, since only one prompt is
+    // ever showing at a time.
+    let currentReject = null;
+    let app;
+    const handleRef = { current: null };
+    function handle() {
+        if (!app) {
+            app = render(_jsx(InterviewRoot, { handleRef: handleRef, onAbort: () => {
+                    aborted = true;
+                    currentReject?.(new InterviewAborted());
+                } }), 
+            // `interactive: true` overrides Ink's own auto-detection
+            // (`stdout.isTTY` + the `is-in-ci` package) rather than relying on
+            // it: the caller here is `commands/init.ts`, which only ever
+            // reaches this file after `inkAvailable()` has ALREADY confirmed a
+            // real interactive terminal — that check is the one source of
+            // truth, and Ink's own CI detection is redundant at best. At
+            // worst it actively lies: GitHub Actions sets `CI=true`
+            // unconditionally, and `node --test` running there is exactly
+            // where this file's own test suite (`ink_asker.test.ts`) drives a
+            // real Ink instance against a fake TTY that reports `isTTY: true`
+            // — Ink's non-interactive mode then writes NOTHING incrementally
+            // (only the final frame, at unmount), so `stdout.frames` never
+            // grows and every keystroke-driven test hangs until its own
+            // timeout. Confirmed by reproducing the exact CI failure locally
+            // with `CI=1 node --test ...` before this fix, and confirming it
+            // disappears after.
+            { ...streams, exitOnCtrlC: false, patchConsole: false, interactive: true });
+        }
+        // `InterviewRoot` populates this synchronously during its first render,
+        // which `render()` above has already forced to happen by the time it
+        // returns.
+        return handleRef.current;
+    }
+    async function guarded(run) {
+        if (aborted)
+            throw new InterviewAborted();
+        try {
+            return await run(handle());
+        }
+        catch (error) {
+            if (error instanceof InterviewAborted)
+                aborted = true;
+            throw error;
+        }
+        finally {
+            currentReject = null;
+        }
+    }
+    return {
+        text(label, opts) {
+            return guarded((h) => new Promise((resolve, reject) => {
+                currentReject = reject;
+                h.setPrompt(_jsx(TextPromptView, { label: label, defaultValue: opts?.default, validate: opts?.validate, onSubmit: (value) => {
+                        h.setPrompt(null);
+                        h.pushHistory(_jsxs(Text, { children: [label, ": ", value] }));
+                        resolve(value);
+                    } }));
+            }));
+        },
+        select(label, choices, dflt) {
+            return guarded((h) => new Promise((resolve, reject) => {
+                currentReject = reject;
+                h.setPrompt(_jsx(SelectPromptView, { label: label, choices: choices, dflt: dflt, onSubmit: (value) => {
+                        const chosen = choices.find((c) => c.value === value);
+                        h.setPrompt(null);
+                        h.pushHistory(_jsxs(Text, { children: [label, " ", _jsxs(Text, { color: "cyan", children: ["\u276F ", chosen?.label ?? value] })] }));
+                        resolve(value);
+                    } }));
+            }));
+        },
+        confirm(label, dflt, opts) {
+            return guarded((h) => new Promise((resolve, reject) => {
+                let settled = false;
+                let timer;
+                currentReject = reject;
+                const finish = (value, note) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    if (timer)
+                        clearTimeout(timer);
+                    h.setPrompt(null);
+                    h.pushHistory(_jsxs(Text, { children: [label, " ", value ? "yes" : "no", note ? _jsxs(Text, { color: "yellow", children: [" (", note, ")"] }) : null] }));
+                    resolve(value);
+                };
+                if (opts?.timeoutMs !== undefined) {
+                    timer = setTimeout(() => finish(dflt, `timed out — using default (${dflt ? "yes" : "no"})`), opts.timeoutMs);
+                    timer.unref?.();
+                }
+                h.setPrompt(_jsx(ConfirmPromptView, { label: label, dflt: dflt, onSubmit: (value) => finish(value) }));
+            }));
+        },
+        secret(label, opts) {
+            return guarded((h) => new Promise((resolve, reject) => {
+                currentReject = reject;
+                h.setPrompt(_jsx(SecretPromptView, { label: label, current: opts?.current, onSubmit: (value) => {
+                        h.setPrompt(null);
+                        h.pushHistory(_jsxs(Text, { children: [label, ": ", value ? maskForPrompt(value) : "(unchanged)"] }));
+                        resolve(value);
+                    } }));
+            }));
+        },
+        note(text) {
+            if (aborted)
+                return;
+            handle().pushHistory(_jsxs(Text, { dimColor: true, children: ["  ", text] }));
+        },
+        heading(text) {
+            if (aborted)
+                return;
+            handle().pushHistory(_jsxs(Text, { bold: true, color: "cyan", children: ["\u2500\u2500 ", text, " \u2500\u2500"] }));
+        },
+        close() {
+            app?.unmount();
+        },
+    };
+}

package/dist/cli/ui/reports.d.ts

@@ -0,0 +1,30 @@
+export type CheckIcon = "ok" | "fail" | "warn" | "info";
+export interface CheckLine {
+    icon: CheckIcon;
+    name: string;
+    detail: string;
+}
+/** `spf doctor`'s check list — same one line per check as the plain-text path, just with the icon colored instead of a bare glyph. */
+export declare function renderChecklist(lines: CheckLine[], footer: {
+    ok: boolean;
+    message: string;
+}): Promise<void>;
+/**
+ * A column-aligned table from pre-formatted string cells — callers still own
+ * field selection/truncation (same as the `.padEnd()` code this replaces);
+ * this only owns column width and alignment, via Ink's own box layout
+ * instead of hand-computed pad strings. `rowColor(i)` colors an entire row
+ * (e.g. red for a failed phase) — `undefined` leaves the terminal default.
+ */
+export declare function renderTable(rows: string[][], opts?: {
+    rowColor?: (rowIndex: number) => string | undefined;
+}): Promise<void>;
+export interface ChainListEntry {
+    name: string;
+    phases: string;
+    describe: string;
+    agentsLine: string;
+    repoLabel?: string;
+}
+/** `spf list` — one styled block per chain (bold name, dimmed description) instead of the plain-text path's hand-padded columns. */
+export declare function renderChainList(entries: ChainListEntry[], footer: string[]): Promise<void>;

package/dist/cli/ui/reports.js

@@ -0,0 +1,61 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { render, Box, Text } from "ink";
+/**
+ * Mounts, waits for the frame to actually flush, then unmounts — the frame
+ * it just wrote stays in scrollback exactly like `console.log` output
+ * would.
+ *
+ * A long, line-wrapping tree (doctor's ~25-line checklist reliably does
+ * this) makes Ink emit an initial paint, then a corrective full
+ * `clear-screen + clear-scrollback + home` repaint once it recalculates the
+ * content's true height — the raw byte stream this writes really does
+ * contain the whole tree twice, which reads as a bug if you inspect it
+ * with `grep`/`wc` the way a naive capture would. It isn't one: replayed
+ * through an actual terminal emulator (verified with `pyte`, not just
+ * eyeballed), the erase sequence takes effect exactly as a real terminal
+ * would apply it, and only the corrected repaint remains on screen —
+ * confirmed for both `render()`'s default mode and `incrementalRendering:
+ * true` (neither changes the outcome; this file uses the default).
+ * `waitUntilRenderFlush()` before `unmount()` is still worth keeping: it's
+ * the correct way to let that settle before tearing the instance down,
+ * even though skipping it turned out not to be the duplicate's actual
+ * cause.
+ */
+async function paint(node) {
+    // `interactive: true` overrides Ink's own `stdout.isTTY`/`is-in-ci`
+    // auto-detection — every caller here already reached this file only
+    // after its own `isInteractive()` check passed (which itself checks
+    // `!process.env["CI"]`), so Ink's redundant CI detection can only ever
+    // disagree by mistake. See `ink_asker.tsx`'s identical `render()` call
+    // for where disagreeing actually broke something (a CI-run test hung).
+    const app = render(node, { patchConsole: false, interactive: true });
+    await app.waitUntilRenderFlush();
+    app.unmount();
+}
+const ICON_GLYPH = { ok: "✓", fail: "✗", warn: "⚠", info: "ℹ" };
+const ICON_COLOR = { ok: "green", fail: "red", warn: "yellow", info: "cyan" };
+/** `spf doctor`'s check list — same one line per check as the plain-text path, just with the icon colored instead of a bare glyph. */
+export async function renderChecklist(lines, footer) {
+    await paint(_jsxs(Box, { flexDirection: "column", children: [lines.map((line, i) => (_jsxs(Text, { children: [_jsx(Text, { color: ICON_COLOR[line.icon], children: ICON_GLYPH[line.icon] }), " ", line.name, ": ", line.detail] }, i))), _jsx(Text, { children: " " }), _jsx(Text, { color: footer.ok ? "green" : "red", children: footer.message })] }));
+}
+/**
+ * A column-aligned table from pre-formatted string cells — callers still own
+ * field selection/truncation (same as the `.padEnd()` code this replaces);
+ * this only owns column width and alignment, via Ink's own box layout
+ * instead of hand-computed pad strings. `rowColor(i)` colors an entire row
+ * (e.g. red for a failed phase) — `undefined` leaves the terminal default.
+ */
+export async function renderTable(rows, opts) {
+    if (rows.length === 0)
+        return;
+    const colCount = Math.max(...rows.map((r) => r.length));
+    const widths = Array.from({ length: colCount }, (_, c) => Math.max(...rows.map((r) => (r[c] ?? "").length)));
+    await paint(_jsx(Box, { flexDirection: "column", children: rows.map((row, i) => (_jsx(Box, { children: row.map((cell, c) => {
+                const isLast = c === row.length - 1;
+                return (_jsx(Box, { width: isLast ? undefined : widths[c], marginRight: isLast ? 0 : 2, children: _jsx(Text, { color: opts?.rowColor?.(i), children: cell }) }, c));
+            }) }, i))) }));
+}
+/** `spf list` — one styled block per chain (bold name, dimmed description) instead of the plain-text path's hand-padded columns. */
+export async function renderChainList(entries, footer) {
+    await paint(_jsxs(Box, { flexDirection: "column", children: [entries.map((entry, i) => (_jsxs(Box, { flexDirection: "column", marginBottom: 1, children: [_jsxs(Text, { children: [_jsx(Text, { bold: true, color: "cyan", children: entry.name }), " ", entry.phases] }), _jsxs(Text, { dimColor: true, children: ["  ", entry.describe] }), _jsxs(Text, { dimColor: true, children: ["  ", entry.agentsLine] }), entry.repoLabel ? _jsxs(Text, { dimColor: true, children: ["  (repo: ", entry.repoLabel, ")"] }) : null] }, i))), footer.map((line, i) => (_jsx(Text, { children: line }, i)))] }));
+}

package/dist/cli/ui/run_dashboard.d.ts

@@ -0,0 +1,15 @@
+import type { RunObserver } from "../../core/console.ts";
+export interface RunDashboard {
+    sink: (line: string) => void;
+    observer: RunObserver;
+    /** Detaches the live phase/spend slot and stops the elapsed-time ticker, then tears the Ink instance down entirely — call around a nested prompt (the sign-off gate) that needs the terminal to itself. Awaits the pending frame flush first: unmounting before Ink's initial commit for a fresh/updated tree has actually flushed can drop the whole accumulated `<Static>` history instead of leaving it in scrollback (confirmed empirically — the exact failure mode `reports.tsx`'s `paint()` guards against, just worse here: nothing printed at all instead of printing twice). */
+    pause(): Promise<void>;
+    /** Re-attaches after `pause()`. */
+    resume(): void;
+    /** Tears the Ink instance down. Call exactly once, when the run finishes (success or error) — same "call this in both the try and the catch" discipline `asker.close()` already follows in `commands/init.ts`. Same flush-before-unmount reasoning as `pause()`. */
+    close(): Promise<void>;
+}
+export declare function mountRunDashboard(opts: {
+    maxCost?: number;
+    maxTokens?: number;
+}): RunDashboard;

package/dist/cli/ui/run_dashboard.js

@@ -0,0 +1,131 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * A live TTY view for `spf <chain>` / `spf run <chain>` — the phase-by-phase
+ * transcript `core/console.ts` already prints, in a `<Static>` history
+ * exactly as it always read, plus one live line below it: the currently
+ * running phase, an elapsed timer, and spend so far (against a ceiling,
+ * when `defaults.max_run_cost`/`max_run_tokens` configure one).
+ *
+ * Reached only through a dynamic `import()` from `cli/commands/run.ts`, and
+ * only when `isInteractive()` — a CI log or a piped `spf <chain>` never
+ * imports this file, and `core/console.ts`'s default `sink`
+ * (`console.log`) and `observer` (`null`) reproduce today's plain-line
+ * behavior exactly. `RunObserver`'s hooks are deliberately the only signal
+ * this reads — never a re-parse of the printed lines themselves (see its
+ * doc comment in `core/console.ts`).
+ *
+ * One persistent Ink instance for the whole run, same reasoning as
+ * `ink_asker.tsx`: nothing here calls `useInput`, so raw mode never
+ * engages and there's no per-line mount/unmount race to worry about — but
+ * `simple_sdlc.ts`'s human sign-off prompt DOES call `useInput` (through
+ * `createInkAsker()`/`createAsker()`) mid-run, and two live Ink instances
+ * cannot share one stdout. `pause()`/`resume()` exist for exactly that
+ * handoff — `cli/commands/run.ts` calls `pause()` before the chain can
+ * reach a sign-off prompt... except it can't know when that will happen
+ * either, so instead this dashboard is paused/resumed by the same
+ * `unattended`/interactive gate `decideSignoff` already uses: see
+ * `run.ts`'s comment at its mount site.
+ */
+import { useEffect, useRef, useState } from "react";
+import { render, Static, Box, Text } from "ink";
+function formatUsd(n) {
+    return `$${n.toFixed(4)}`;
+}
+function Elapsed({ sinceMs }) {
+    const [now, setNow] = useState(() => Date.now());
+    useEffect(() => {
+        const id = setInterval(() => setNow(Date.now()), 1000);
+        return () => clearInterval(id);
+    }, []);
+    const seconds = Math.max(0, (now - sinceMs) / 1000);
+    return _jsxs(Text, { dimColor: true, children: [seconds.toFixed(0), "s"] });
+}
+function DashboardRoot(props) {
+    const [history, setHistory] = useState([]);
+    const [live, setLive] = useState(props.initialLive);
+    const [usage, setUsage] = useState(props.initialUsage);
+    const keyRef = useRef(0); // see ink_asker.tsx's identical comment — a ref, not state, so two pushes in one tick never collide
+    props.handleRef.current = {
+        pushHistory(text) {
+            const key = keyRef.current++;
+            setHistory((h) => [...h, { key, text }]);
+        },
+        setLivePhase: setLive,
+        setUsage: (tokens, cost) => setUsage({ tokens, cost }),
+    };
+    const overCost = props.maxCost !== undefined && usage.cost >= props.maxCost * 0.8;
+    const overTokens = props.maxTokens !== undefined && usage.tokens >= props.maxTokens * 0.8;
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Static, { items: history, children: (line) => _jsx(Text, { children: line.text }, line.key) }), live ? (_jsxs(Box, { children: [_jsx(Text, { color: "magenta", children: "\u25B8 running: " }), _jsx(Text, { bold: true, children: live.name }), _jsxs(Text, { dimColor: true, children: [" (", live.kind, " \u00B7 ", live.owner, ") "] }), _jsx(Elapsed, { sinceMs: live.startedAtMs })] })) : null, _jsxs(Box, { children: [_jsxs(Text, { dimColor: true, children: ["spend: ", usage.tokens.toLocaleString(), " tokens \u00B7 ", formatUsd(usage.cost), props.maxCost !== undefined ? ` / ${formatUsd(props.maxCost)}` : "", props.maxTokens !== undefined ? ` (of ${props.maxTokens.toLocaleString()} tokens)` : ""] }), overCost || overTokens ? _jsx(Text, { color: "yellow", children: " \u2014 approaching ceiling" }) : null] })] }));
+}
+export function mountRunDashboard(opts) {
+    const handleRef = { current: null };
+    let currentPhase = null;
+    let currentUsage = { tokens: 0, cost: 0 };
+    // `undefined` while paused: Ink refuses a second `render()` on the same
+    // stdout while a prior instance is still live (the same restriction
+    // `ink_asker.tsx`'s confirm-timeout comment names), and the sign-off
+    // prompt's own Ink instance needs the terminal to itself. `pause()`
+    // fully unmounts rather than just hiding state; `resume()` mounts a
+    // fresh instance seeded with whatever `currentPhase`/`currentUsage`
+    // were at the moment of the handoff, so the live line picks up exactly
+    // where it left off instead of resetting to "nothing running".
+    let app;
+    function mount() {
+        app = render(_jsx(DashboardRoot, { maxCost: opts.maxCost, maxTokens: opts.maxTokens, handleRef: handleRef, initialLive: currentPhase, initialUsage: currentUsage }), 
+        // `interactive: true` overrides Ink's own CI auto-detection — see
+        // `ink_asker.tsx`'s identical `render()` call for why: the caller
+        // (`commands/run.ts`) only reaches this file after its own
+        // `isInteractive()` check has already passed.
+        { patchConsole: false, interactive: true });
+    }
+    mount();
+    const sink = (line) => {
+        // Never silently dropped, even while paused: falls back to the exact
+        // default `Console` would use on its own (`console.log`) rather than
+        // lose the printed half of "one narrative, two destinations" during
+        // the handoff window.
+        if (!app) {
+            console.log(line);
+            return;
+        }
+        handleRef.current?.pushHistory(line);
+    };
+    const observer = {
+        onPhaseStart(phase) {
+            currentPhase = { name: phase.params.name, kind: phase.params.kind, owner: phase.params.owner, startedAtMs: Date.now() };
+            // `currentPhase`/`currentUsage` above are updated regardless of `app`
+            // so a `resume()` after this always seeds the fresh mount correctly,
+            // even if the phase/usage change itself happened while paused.
+            if (app)
+                handleRef.current?.setLivePhase(currentPhase);
+        },
+        onPhaseEnd() {
+            currentPhase = null;
+            if (app)
+                handleRef.current?.setLivePhase(null);
+        },
+        onUsage(tokens, cost) {
+            currentUsage = { tokens, cost };
+            if (app)
+                handleRef.current?.setUsage(tokens, cost);
+        },
+    };
+    async function unmount() {
+        if (!app)
+            return;
+        const current = app;
+        await current.waitUntilRenderFlush();
+        current.unmount();
+        app = undefined;
+    }
+    return {
+        sink,
+        observer,
+        pause: unmount,
+        resume() {
+            if (!app)
+                mount();
+        },
+        close: unmount,
+    };
+}

package/dist/cli/ui/watch_dashboard.d.ts

@@ -0,0 +1,22 @@
+import type { NotifyEvent } from "../../core/notify/channel.ts";
+export interface WatchDashboard {
+    log: (message: string) => void;
+    /** Mirrors a one-line summary into the same log history — delivery to the real `Notifier` is unaffected; call this alongside it, never instead of it. */
+    mirrorNotify: (event: NotifyEvent) => void;
+    setCounts: (inflight: number, refining: number) => void;
+    /** `null` while a tick is running or the daemon is draining — clears the countdown instead of showing a stale or negative one. */
+    setNextPollAt: (deadlineMs: number | null) => void;
+    /** Tears the Ink instance down. Call once, in the same `finally` `commands/watch.ts` already releases its lockfile in. */
+    close(): Promise<void>;
+    /** Synchronous, no flush-wait — for `stop()`'s second-Ctrl-C `process.exit(130)` path, same reasoning as `fanout_dashboard.tsx`'s `unmountNow()`. */
+    unmountNow(): void;
+}
+export declare function mountWatchDashboard(opts: {
+    repo: string;
+    labelPrefix: string;
+    chain: string;
+    concurrency: number;
+    refineChain?: string;
+    refineConcurrency?: number;
+    dryRun: boolean;
+}): WatchDashboard;