@gr8ful/spf 0.6.0 → 0.8.0

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;

package/dist/cli/ui/watch_dashboard.js

@@ -0,0 +1,78 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * A live status line for `spf watch` — the exact same log lines
+ * `WatchDeps.log()` already prints (the daemon banner, each tick's
+ * claim/finish lines), in a `<Static>` history, plus one live line below
+ * it: how many issues are in flight, how many are being refined, and a
+ * countdown to the next poll.
+ *
+ * `core/watch.ts` is untouched — this only ever swaps `cli/commands/
+ * watch.ts`'s own `WatchDeps.log` callback and reads `WatchRunState`'s
+ * public `.size` after each `tick()` returns, exactly the seam the plan
+ * called for ("no core changes"). `notify` keeps going to the real
+ * `Notifier` unchanged (Slack/Teams/webhook delivery has nothing to do
+ * with terminal rendering); this only ALSO mirrors a one-line summary of
+ * each event into the same log history, for visibility.
+ *
+ * One persistent Ink instance for the whole `spf watch` invocation — same
+ * shape as `run_dashboard.tsx`/`fanout_dashboard.tsx`. `spf watch`'s own
+ * SIGINT handling exits immediately on a second Ctrl-C (`process.exit(130)`
+ * in `commands/watch.ts`'s `stop()`), so `unmountNow()` exists here for the
+ * same best-effort, no-flush-wait reason `fanout_dashboard.tsx`'s does.
+ */
+import { useEffect, useRef, useState } from "react";
+import { render, Static, Box, Text } from "ink";
+function Countdown({ deadlineMs }) {
+    const [now, setNow] = useState(() => Date.now());
+    useEffect(() => {
+        const id = setInterval(() => setNow(Date.now()), 1000);
+        return () => clearInterval(id);
+    }, []);
+    const remaining = Math.max(0, Math.round((deadlineMs - now) / 1000));
+    return _jsxs(Text, { dimColor: true, children: ["next poll in ", remaining, "s"] });
+}
+function WatchRoot(props) {
+    const [log, setLog] = useState([]);
+    const [counts, setCounts] = useState({ inflight: 0, refining: 0 });
+    const [nextPollAt, setNextPollAt] = useState(null);
+    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 = {
+        pushLog(text) {
+            const key = keyRef.current++;
+            setLog((prev) => [...prev, { key, text }]);
+        },
+        setCounts: (inflight, refining) => setCounts({ inflight, refining }),
+        setNextPollAt,
+    };
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Static, { items: log, children: (line) => _jsx(Text, { children: line.text }, line.key) }), _jsx(Box, { children: _jsxs(Text, { children: [props.repo, " ", _jsxs(Text, { dimColor: true, children: ["label \"", props.labelPrefix, ":*\" \u00B7 chain \"", props.chain, "\" \u00B7 concurrency ", props.concurrency] }), props.refineChain ? (_jsxs(Text, { dimColor: true, children: [" ", "\u00B7 refine \"", props.refineChain, "\" concurrency ", props.refineConcurrency] })) : null, props.dryRun ? _jsx(Text, { color: "yellow", children: " (dry run)" }) : null] }) }), _jsxs(Box, { children: [_jsxs(Text, { children: [_jsxs(Text, { color: counts.inflight > 0 ? "cyan" : undefined, children: [counts.inflight, " in flight"] }), counts.refining > 0 ? _jsxs(Text, { color: "magenta", children: [", ", counts.refining, " refining"] }) : null, " · "] }), nextPollAt !== null ? _jsx(Countdown, { deadlineMs: nextPollAt }) : _jsx(Text, { dimColor: true, children: "ticking\u2026" })] })] }));
+}
+export function mountWatchDashboard(opts) {
+    const handleRef = { current: null };
+    const app = render(_jsx(WatchRoot, { repo: opts.repo, labelPrefix: opts.labelPrefix, chain: opts.chain, concurrency: opts.concurrency, refineChain: opts.refineChain, refineConcurrency: opts.refineConcurrency, dryRun: opts.dryRun, handleRef: handleRef }), 
+    // `interactive: true` overrides Ink's own CI auto-detection — see
+    // `ink_asker.tsx`'s identical `render()` call for why: the caller
+    // (`commands/watch.ts`) only reaches this file after its own
+    // `isInteractive()` check has already passed.
+    { patchConsole: false, interactive: true });
+    return {
+        log(message) {
+            handleRef.current?.pushLog(message);
+        },
+        mirrorNotify(event) {
+            handleRef.current?.pushLog(`[notify] ${event.title}${event.detail ? ` — ${event.detail}` : ""}`);
+        },
+        setCounts(inflight, refining) {
+            handleRef.current?.setCounts(inflight, refining);
+        },
+        setNextPollAt(deadlineMs) {
+            handleRef.current?.setNextPollAt(deadlineMs);
+        },
+        async close() {
+            await app.waitUntilRenderFlush();
+            app.unmount();
+        },
+        unmountNow() {
+            app.unmount();
+        },
+    };
+}

package/dist/core/console.d.ts

@@ -15,6 +15,21 @@ export declare function paint(style: string, text: string): string;
 interface Tracer {
     event(record: EventRecord): string;
 }
+/**
+ * A run-scoped hook for a live TTY view (`cli/ui/run_dashboard.tsx`) to
+ * track phase state and spend without re-parsing `Console`'s formatted
+ * lines — deliberately narrow (phase transitions + usage, not every method
+ * below) since that's the whole surface a "which phase is running, how
+ * long, how much so far" dashboard needs. Every hook is optional and every
+ * `Console` call site that doesn't pass one behaves exactly as before this
+ * existed.
+ */
+export interface RunObserver {
+    onPhaseStart?(phase: Phase): void;
+    onPhaseEnd?(phase: Phase, seconds: number): void;
+    onUsage?(tokens: number, cost: number): void;
+    onSessionEnd?(ok: boolean): void;
+}
 /** Bound to one run's tracer. Reachable as `run.console` everywhere. */
 export declare class Console {
     private tracer;
@@ -23,6 +38,17 @@ export declare class Console {
     private notifier;
     /** The CLI chain name (`"plan-build-test"`), for a notification's title — see session.ts. */
     private chainName;
+    /**
+     * Where a printed line actually goes — defaults to `console.log`, exactly
+     * the prior behavior. `cli/commands/run.ts` is the only caller that ever
+     * passes something else: on a real TTY, a sink that feeds a live Ink
+     * dashboard's scrollback instead of writing straight to stdout. The
+     * tracer side of `emit()` below is UNCHANGED either way — this only
+     * repoints the print half of "one narrative, two destinations".
+     */
+    private sink;
+    /** See `RunObserver`'s own doc comment. `null` outside an interactive `cli/commands/run.ts` dispatch. */
+    private observer;
     private phaseId;
     private phaseName;
     private results;
@@ -31,7 +57,18 @@ export declare class Console {
     /** `null` when notifications are off — every call site below guards with `?.`. */
     notifier?: Notifier | null, 
     /** The CLI chain name (`"plan-build-test"`), for a notification's title — see session.ts. */
-    chainName?: string);
+    chainName?: string, 
+    /**
+     * Where a printed line actually goes — defaults to `console.log`, exactly
+     * the prior behavior. `cli/commands/run.ts` is the only caller that ever
+     * passes something else: on a real TTY, a sink that feeds a live Ink
+     * dashboard's scrollback instead of writing straight to stdout. The
+     * tracer side of `emit()` below is UNCHANGED either way — this only
+     * repoints the print half of "one narrative, two destinations".
+     */
+    sink?: (line: string) => void, 
+    /** See `RunObserver`'s own doc comment. `null` outside an interactive `cli/commands/run.ts` dispatch. */
+    observer?: RunObserver | null);
     private emit;
     sessionStarted(adwId: string, engineer: string): void;
     sessionFinished(ok: boolean, tokens: number, cost: number, dbPath: string): void;
@@ -39,6 +76,8 @@ export declare class Console {
     phaseEnded(phase: Phase, seconds: number): void;
     /** Free-form detail inside the current phase — what `ph.log()` recorded. */
     note(message: string): void;
+    /** `Run.addUsage()`'s only hook into `Console` — the running total lives on `Run`, not here, so this just forwards it to the observer. No line prints for this on its own; the totals already show up in `sessionFinished`'s panel. */
+    notifyUsage(tokens: number, cost: number): void;
     agentStarted(name: string, model: string, sessionId: string): void;
     agentFinished(name: string, tokens: number, cost: number): void;
     retry(name: string, attempt: number, limit: number, reason: string): void;

package/dist/core/console.js

@@ -47,6 +47,8 @@ export class Console {
     adwId;
     notifier;
     chainName;
+    sink;
+    observer;
     phaseId = ""; // current lane — log events attach to it
     phaseName = "";
     results = []; // phase statuses, for the summary
@@ -55,15 +57,28 @@ export class Console {
     /** `null` when notifications are off — every call site below guards with `?.`. */
     notifier = null, 
     /** The CLI chain name (`"plan-build-test"`), for a notification's title — see session.ts. */
-    chainName = "adw") {
+    chainName = "adw", 
+    /**
+     * Where a printed line actually goes — defaults to `console.log`, exactly
+     * the prior behavior. `cli/commands/run.ts` is the only caller that ever
+     * passes something else: on a real TTY, a sink that feeds a live Ink
+     * dashboard's scrollback instead of writing straight to stdout. The
+     * tracer side of `emit()` below is UNCHANGED either way — this only
+     * repoints the print half of "one narrative, two destinations".
+     */
+    sink = console.log, 
+    /** See `RunObserver`'s own doc comment. `null` outside an interactive `cli/commands/run.ts` dispatch. */
+    observer = null) {
         this.tracer = tracer;
         this.adwId = adwId;
         this.notifier = notifier;
         this.chainName = chainName;
+        this.sink = sink;
+        this.observer = observer;
     }
     // ── the one helper: print AND trace, always together ────────────────────
     emit(line, level = "info") {
-        console.log(line);
+        this.sink(line);
         this.tracer.event(makeEventRecord({
             adw_id: this.adwId,
             phase_id: this.phaseId,
@@ -101,7 +116,8 @@ export class Console {
             ` ${paint("dim", "next")}     ${paint("bold", `just phases ${this.adwId}`)}`,
         ];
         const rendered = panel(rows, "ADW complete", ok ? "green" : "red");
-        console.log(rendered);
+        this.sink(rendered);
+        this.observer?.onSessionEnd?.(ok);
         const plain = `session ${this.adwId} ${ok ? "success" : "fail"} · ${passed}/${this.results.length} phases · ${tokens.toLocaleString()} tokens · $${cost.toFixed(4)}`;
         this.tracer.event(makeEventRecord({
             adw_id: this.adwId,
@@ -133,10 +149,12 @@ export class Console {
         if (p.description)
             line += `  ${paint("dim", clip(p.description))}`;
         this.emit(line);
+        this.observer?.onPhaseStart?.(phase);
     }
     phaseEnded(phase, seconds) {
         const ok = phase.status === "success";
         this.results.push(phase.status);
+        this.observer?.onPhaseEnd?.(phase, seconds);
         let line = `  ${ok ? paint("green", "✓") : paint("red", "✗")} ${phase.params.name} ${paint("dim", `${seconds.toFixed(1)}s`)}`;
         if (!ok && phase.error)
             line += `  ${paint("red", clip(phase.error))}`;
@@ -161,6 +179,10 @@ export class Console {
     note(message) {
         this.emit(`  ${paint("dim", `· ${clip(message)}`)}`);
     }
+    /** `Run.addUsage()`'s only hook into `Console` — the running total lives on `Run`, not here, so this just forwards it to the observer. No line prints for this on its own; the totals already show up in `sessionFinished`'s panel. */
+    notifyUsage(tokens, cost) {
+        this.observer?.onUsage?.(tokens, cost);
+    }
     // ── agents ──────────────────────────────────────────────────────────────
     agentStarted(name, model, sessionId) {
         this.emit(`  ${paint("magenta", "▸")} ${name} ${paint("dim", model)}  ${paint("dim", `session ${sessionId}`)}`);