@gr8ful/spf 0.7.0 → 0.8.1

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}`)}`);

package/dist/core/fanout.d.ts

@@ -214,6 +214,15 @@ export interface FanoutDeps {
      * ABORT GRANULARITY note.
      */
     firstSuccess?: boolean;
+    /**
+     * Fires once per attempt the moment it settles (success, fail, error, or
+     * skipped) — the same record that lands in the final `attempts` array, just
+     * as it happens instead of only once every worker has finished. Purely
+     * observational: nothing here changes selection or cleanup. `cli/commands/
+     * fanout.ts` uses it to update a live results table row by row on a TTY;
+     * omitted (the default) everywhere else, including every test.
+     */
+    onAttempt?: (attempt: FanoutAttempt) => void;
 }
 /**
  * Run `n` attempts of one prompt, select deterministically, clean up the

package/dist/core/fanout.js

@@ -284,10 +284,14 @@ export async function runBestOf(deps) {
                 return;
             if (decided) {
                 deps.log(`fanout: attempt ${index} skipped — an earlier attempt already succeeded`);
-                attempts.push(skipped(index));
+                const attempt = skipped(index);
+                attempts.push(attempt);
+                deps.onAttempt?.(attempt);
                 continue;
             }
-            attempts.push(await runOne(index));
+            const attempt = await runOne(index);
+            attempts.push(attempt);
+            deps.onAttempt?.(attempt);
         }
     };
     const workers = Array.from({ length: Math.max(1, Math.min(deps.concurrency, deps.n)) }, () => worker());

package/dist/core/issues/github_provider.js

@@ -12,7 +12,22 @@ const STATES = [
     "continue-refinement",
     "spec-in-progress",
 ];
-const MARKER_RE = /<!--\s*spf-watch:\s*(\{.*?\})\s*-->/s;
+/**
+ * GREEDY capture, not lazy: `WatchMarker.feedback` nests its own object
+ * (`{rounds, asked_at}`), so a lazy `\{.*?\}` stops at the FIRST `}` it
+ * finds — which is `feedback`'s own closing brace, not the marker's outer
+ * one — capturing an unbalanced, unparseable fragment the instant a spec
+ * escalates even once. `JSON.parse` then throws, is silently caught, and
+ * `readMarker` returns `null` forever after that point: the round counter
+ * can never advance past 1, a fresh marker comment gets posted every tick
+ * instead of the existing one being edited in place, and — worst of all —
+ * `buildSpecPrompt` never receives a valid `asked_at`, so a human's answer
+ * is never recognized as one, just dumped into undifferentiated "earlier
+ * discussion." A greedy match backtracks from the END of the string to find
+ * the LAST `}` — the marker's own outer brace — which is exactly right
+ * here since nothing meaningful follows it but the closing `-->`.
+ */
+const MARKER_RE = /<!--\s*spf-watch:\s*(\{.*\})\s*-->/s;
 /** `listByLabel`'s pagination bound — see its own doc comment. */
 const MAX_LIST_PAGES = 5;
 /** The refine lane's leaf/container taxonomy — see `data_types.ts`'s `RefinedIssueSchema.kind`. Not a `WatchState`: these never appear on the left of a `transition()` call, so `transition()` never strips them. */

package/dist/core/issues/jira_provider.js

@@ -11,7 +11,19 @@ const STATES = [
     "continue-refinement",
     "spec-in-progress",
 ];
-const MARKER_RE = /\[spf-watch-marker\]\s*(\{.*?\})/s;
+/**
+ * GREEDY capture, not lazy — same fix and same reasoning as
+ * `github_provider.ts`'s own `MARKER_RE`: `WatchMarker.feedback` nests its
+ * own object, so a lazy `\{.*?\}` stops at `feedback`'s own closing brace
+ * instead of the marker's outer one, producing unparseable JSON the moment
+ * a spec escalates even once — `readMarker` then returns `null` forever,
+ * `writeMarker` can never find the existing marker to edit in place (a new
+ * one gets posted every tick instead), and `buildSpecPrompt` never sees a
+ * valid `asked_at`, so a human's answer never gets flagged as one. Greedy
+ * backtracks from the end of the comment body to the true last `}` — safe
+ * here because nothing follows the JSON in this format at all.
+ */
+const MARKER_RE = /\[spf-watch-marker\]\s*(\{.*\})/s;
 function toAdf(text) {
     return {
         type: "doc",

package/dist/core/runner.d.ts

@@ -9,7 +9,7 @@
  * parsed envelope + green gates, enforced inside ph.call).
  */
 import { type GitHandle } from "./git_helper.ts";
-import { Console } from "./console.ts";
+import { Console, type RunObserver } from "./console.ts";
 import { Tracer } from "./tracer.ts";
 import { type AgentCall, type EnvelopeBase, type Phase, type PhaseParams, type SFConfig } from "./data_types.ts";
 import type { TierResolution } from "./tiering.ts";
@@ -38,6 +38,10 @@ export interface RunInit {
     chainName?: string;
     /** `null`/omitted when notifications are off (the default) or no channel resolved. */
     notifier?: Notifier | null;
+    /** Where a printed line goes — see `Console`'s own constructor doc. Omitted everywhere except an interactive `cli/commands/run.ts` dispatch. */
+    sink?: (line: string) => void;
+    /** See `RunObserver`'s doc comment (`core/console.ts`). `null`/omitted outside an interactive dispatch. */
+    observer?: RunObserver | null;
 }
 export declare class Run {
     cfg: SFConfig;

package/dist/core/runner.js

@@ -78,7 +78,7 @@ export class Run {
         this.adw_id = init.adwId;
         this.tracer = init.tracer;
         this.notify = init.notifier ?? null;
-        this.console = new Console(init.tracer, init.adwId, this.notify, init.chainName || "adw");
+        this.console = new Console(init.tracer, init.adwId, this.notify, init.chainName || "adw", init.sink, init.observer);
         this.engineer = init.engineer;
         this.seq = init.tracer.maxPhaseSeq(init.adwId);
         this.repo_root = init.repoRoot;
@@ -100,6 +100,7 @@ export class Run {
         this.tokens += tokens;
         this.cost += cost;
         this.tracer.sessionAddUsage(this.adw_id, tokens, cost);
+        this.console.notifyUsage(this.tokens, this.cost);
     }
     // ── the phase primitive ─────────────────────────────────────────────────
     async phase(params, fn) {

package/dist/core/session.d.ts

@@ -6,6 +6,7 @@
  * minted and printed so the next ADW can pick it up.
  */
 import { Run } from "./runner.ts";
+import type { RunObserver } from "./console.ts";
 import type { SFConfig } from "./data_types.ts";
 /**
  * The symmetric teardown for `finalizeWhenKilled()` above: drop `adwId` from
@@ -43,4 +44,9 @@ export declare function activeRunIdsForTest(): string[];
  * longer a `process.argv[1]` basename that means anything. Direct callers
  * that have no chain of their own fall back to `"adw"`.
  */
-export declare function ensure(cfg: SFConfig, adwId?: string | null, cwd?: string, chainName?: string): Run;
+export declare function ensure(cfg: SFConfig, adwId?: string | null, cwd?: string, chainName?: string, 
+/** See `RunObserver`'s doc comment (`core/console.ts`). Omitted for every caller except an interactive `cli/commands/run.ts` dispatch — a `spf watch` per-issue run, `spf fanout`'s per-attempt runs, and every test all continue to build a plain, unobserved `Console`. */
+renderHooks?: {
+    sink?: (line: string) => void;
+    observer?: RunObserver | null;
+}): Run;

package/dist/core/session.js

@@ -138,7 +138,9 @@ export function activeRunIdsForTest() {
  * longer a `process.argv[1]` basename that means anything. Direct callers
  * that have no chain of their own fall back to `"adw"`.
  */
-export function ensure(cfg, adwId, cwd, chainName) {
+export function ensure(cfg, adwId, cwd, chainName, 
+/** See `RunObserver`'s doc comment (`core/console.ts`). Omitted for every caller except an interactive `cli/commands/run.ts` dispatch — a `spf watch` per-issue run, `spf fanout`'s per-attempt runs, and every test all continue to build a plain, unobserved `Console`. */
+renderHooks) {
     const id = adwId || newId(8);
     const anchor = paths.resolveAnchor(cwd);
     const dataPaths = paths.resolveDataPaths(anchor, cfg.defaults.data_dir, cfg.observability.db);
@@ -161,6 +163,8 @@ export function ensure(cfg, adwId, cwd, chainName) {
         dataDir: dataPaths.data_dir,
         chainName: chainName || "adw",
         notifier: resolveNotifier(cfg),
+        sink: renderHooks?.sink,
+        observer: renderHooks?.observer,
     });
     const scriptPath = process.argv[1] || "adw";
     tracer.sessionStart(id, run.engineer, chainName || "adw");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gr8ful/spf",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Super Portable Factory — a global CLI for repeatable agents-plus-code workflows (ADWs)",
   "type": "module",
   "license": "MIT",
@@ -44,8 +44,11 @@
     "@earendil-works/pi-ai": "0.83.0",
     "@flue/runtime": "2.0.3",
     "@hono/node-server": "^2.1.1",
+    "@inkjs/ui": "^2.0.0",
     "@valibot/to-json-schema": "^1.7.1",
     "hono": "^4.13.3",
+    "ink": "^7.1.1",
+    "react": "^19.2.8",
     "valibot": "^1.4.2",
     "yaml": "^2.5.1"
   },
@@ -54,6 +57,8 @@
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
+    "@types/react": "^19.2.18",
+    "ink-testing-library": "^4.0.0",
     "lefthook": "^2.1.10",
     "typescript": "^7.0.2"
   }