@gr8ful/spf 0.7.0 → 0.8.1

package/dist/cli/commands/watch.js

@@ -22,6 +22,7 @@ import { findChain, resolveRequiredAgents, runChain as runChainDef } from "../..
 import { ReviewOutput } from "../../core/data_types.js";
 import { SfDb } from "../../ui/server/db.js";
 import { parseCli } from "../../core/utils.js";
+import { isInteractive } from "../ask.js";
 /** Kept well under Slack's own 2900-char slice on `detail` (see `slack_channel.ts`) — a reviewer can emit a lot of findings, but the PR body/notification only needs enough to tell a human whether to look closer. */
 const MAX_REVIEW_DIGEST_CHARS = 1200;
 /**
@@ -456,6 +457,18 @@ export async function watchCommand(argv) {
         catch {
             // best-effort, same as above — no questions file means this run wasn't an escalation
         }
+        // Defense in depth: `steps.publishIssues()` now clears whichever of
+        // these two files it's NOT about to write, so both should never be
+        // non-empty here — but if some future change (or an older worktree's
+        // leftover files, before that fix existed) ever produces both, a real
+        // completed publish must never be silently overridden by a stale
+        // question. `runSpec` checks `questions.length > 0` first, so without
+        // this it would re-escalate over issues that already landed on the
+        // tracker seconds earlier.
+        if (created.length > 0 && questions.length > 0) {
+            console.error(`watch: ${opts.adwId}: refine_publish.json AND refine_questions.json both had content — treating the ${created.length} published issue(s) as authoritative and discarding the stale question(s)`);
+            questions = [];
+        }
         return { accepted: true, adwId: opts.adwId, detail: "", created, questions };
     };
     // `IssueAuthoringProvider`'s read-back half — `isAuthoringProvider()` is a
@@ -469,6 +482,23 @@ export async function watchCommand(argv) {
     // Not a second `resolveAuthoringProvider()` call: that helper's own config
     // validation already ran to produce `provider` itself.
     const authoringProvider = isAuthoringProvider(provider) ? provider : null;
+    // Only for the one dispatch a human is actually watching a terminal for —
+    // `core/watch.ts` itself is untouched; this only ever swaps `deps.log`
+    // below and reads `state.inflight`/`state.refining` sizes after each
+    // `tick()`, exactly the seam the plan called for.
+    let dashboard;
+    if (isInteractive()) {
+        const { mountWatchDashboard } = await import("../ui/watch_dashboard.js");
+        dashboard = mountWatchDashboard({
+            repo: `${cfg.watch.issue_provider}+${cfg.watch.code_host}  ${cfg.watch.repo}`,
+            labelPrefix: cfg.watch.label_prefix,
+            chain: cfg.watch.chain,
+            concurrency: cfg.watch.concurrency,
+            refineChain: cfg.watch.refine.enabled ? cfg.watch.refine.chain : undefined,
+            refineConcurrency: cfg.watch.refine.enabled ? cfg.watch.refine.concurrency : undefined,
+            dryRun: Boolean(flags["dry-run"]),
+        });
+    }
     const deps = {
         provider,
         codeHost,
@@ -488,8 +518,11 @@ export async function watchCommand(argv) {
         dryRun: Boolean(flags["dry-run"]),
         runChain,
         listChildren: authoringProvider ? (parent) => authoringProvider.listChildren(parent) : undefined,
-        log: (message) => console.log(message),
-        notify: (event) => notifier?.send(event),
+        log: (message) => (dashboard ? dashboard.log(message) : console.log(message)),
+        notify: (event) => {
+            notifier?.send(event); // unaffected either way — see mountWatchDashboard's own doc comment
+            dashboard?.mirrorNotify(event);
+        },
     };
     const state = createWatchState();
     let stopping = false;
@@ -513,6 +546,7 @@ export async function watchCommand(argv) {
         interrupt?.();
         sigints++;
         if (sigints >= 2) {
+            dashboard?.unmountNow(); // best-effort cursor-visibility restore before the abrupt exit — see WatchDashboard.unmountNow's own comment
             console.error("\n[spf] watch     second interrupt — exiting immediately, without draining");
             releaseLock(lockPath);
             process.exit(130);
@@ -523,9 +557,15 @@ export async function watchCommand(argv) {
     };
     process.on("SIGINT", stop);
     process.on("SIGTERM", stop);
-    console.log(`[spf] watch     ${cfg.watch.issue_provider}+${cfg.watch.code_host}  ${cfg.watch.repo}  label "${cfg.watch.label_prefix}:*"  chain "${cfg.watch.chain}"  concurrency ${cfg.watch.concurrency}` +
-        (cfg.watch.refine.enabled ? `  refine "${cfg.watch.refine.chain}" concurrency ${cfg.watch.refine.concurrency}` : "") +
-        (flags["dry-run"] ? "  (dry run)" : ""));
+    // The dashboard already renders this exact information as its own live
+    // header (repo/label/chain/concurrency/dry-run) — printing it again here
+    // would both duplicate it and interleave a raw console.log with an
+    // active Ink region.
+    if (!dashboard) {
+        console.log(`[spf] watch     ${cfg.watch.issue_provider}+${cfg.watch.code_host}  ${cfg.watch.repo}  label "${cfg.watch.label_prefix}:*"  chain "${cfg.watch.chain}"  concurrency ${cfg.watch.concurrency}` +
+            (cfg.watch.refine.enabled ? `  refine "${cfg.watch.refine.chain}" concurrency ${cfg.watch.refine.concurrency}` : "") +
+            (flags["dry-run"] ? "  (dry run)" : ""));
+    }
     deps.notify({
         kind: "watch_started",
         level: "info",
@@ -538,15 +578,18 @@ export async function watchCommand(argv) {
     });
     try {
         for (;;) {
+            dashboard?.setNextPollAt(null); // clears any stale countdown while a tick is actually running
             await tick(deps, state);
+            dashboard?.setCounts(state.inflight.size, state.refining.size);
             if (flags["once"] || stopping)
                 break;
+            dashboard?.setNextPollAt(Date.now() + cfg.watch.poll_ms);
             await interruptibleSleep(cfg.watch.poll_ms);
             if (stopping)
                 break;
         }
         while (state.inflight.size > 0) {
-            console.log(`[spf] watch     draining ${state.inflight.size} in-flight issue(s)...`);
+            deps.log(`[spf] watch     draining ${state.inflight.size} in-flight issue(s)...`); // deps.log already routes to the dashboard when one is mounted, console.log otherwise
             await interruptibleSleep(1000);
             if (stopping && sigints >= 2)
                 break; // stop() itself already exits on the 2nd signal; this is belt-and-suspenders
@@ -559,5 +602,6 @@ export async function watchCommand(argv) {
         process.off("SIGINT", stop);
         process.off("SIGTERM", stop);
         releaseLock(lockPath);
+        await dashboard?.close();
     }
 }

package/dist/cli/index.js

@@ -151,7 +151,7 @@ export async function main() {
                 process.exitCode = await estimateCommand(rest);
                 return;
             case "list":
-                process.exitCode = listCommand();
+                process.exitCode = await listCommand();
                 return;
             case "init":
                 process.exitCode = await initCommand(rest);
@@ -177,10 +177,10 @@ export async function main() {
                 return;
             }
             case "sessions":
-                process.exitCode = sessionsCommand(rest);
+                process.exitCode = await sessionsCommand(rest);
                 return;
             case "phases":
-                process.exitCode = phasesCommand(rest);
+                process.exitCode = await phasesCommand(rest);
                 return;
             case "events":
                 process.exitCode = await eventsCommand(rest);

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;