@gr8ful/spf 0.7.0 → 0.8.1

package/dist/chains/context.d.ts

@@ -1,3 +1,4 @@
+import type { RunObserver } from "../core/console.ts";
 /**
  * What every chain's `main()` receives. The CLI (or, later, the chain
  * registry) resolves every path here — a chain never has its own opinion
@@ -57,4 +58,29 @@ export interface ChainContext {
      * edited by the time anyone reads the run back).
      */
     chain_source?: string;
+    /**
+     * A live TTY view's hook into this run's `Console` — see `RunObserver`'s
+     * doc comment (`core/console.ts`). Optional and omitted by every
+     * construction site except an interactive `cli/commands/run.ts`
+     * dispatch: `spf watch`'s per-issue runs, `spf fanout`'s per-attempt
+     * runs, the `refine` chain, and every test all continue to build a
+     * plain, unobserved `Console` exactly as before this field existed.
+     */
+    render_hooks?: {
+        sink?: (line: string) => void;
+        observer?: RunObserver | null;
+        /**
+         * The live dashboard's own handoff pair — call `pause()` before a
+         * chain shows its own competing prompt (today, only `simple_sdlc.ts`'s
+         * human sign-off gate) and `resume()` once it's done, symmetrically,
+         * in a `finally`. Ink refuses a second `render()` on the same stdout
+         * while a prior instance is still live, so this isn't optional
+         * politeness — skipping `pause()` before mounting another Ink surface
+         * (or even a plain `readline` prompt sharing the same stdin/stdout,
+         * given the dashboard's own live-updating timer keeps writing to it)
+         * corrupts both.
+         */
+        pause?: () => void | Promise<void>;
+        resume?: () => void;
+    };
 }

package/dist/chains/simple_sdlc.js

@@ -217,6 +217,13 @@ export async function main(ctx) {
         const canPrompt = isInteractive() && !ctx.unattended; // amendment: never infer this from TTY state alone
         identity = committerIdentity(run.repo_root);
         const asker = canPrompt ? createAsker() : null;
+        // A live run dashboard (cli/ui/run_dashboard.tsx) keeps writing to the
+        // same stdout/stdin on its own timer even though it never reads input
+        // itself — that alone is enough to corrupt this prompt's rendering if
+        // both are live at once. `pause()`/`resume()` are no-ops when no
+        // dashboard is mounted (every non-interactive dispatch, and any test).
+        if (canPrompt)
+            await ctx.render_hooks?.pause?.();
         try {
             const outcome = await run.phase(makePhaseParams({
                 name: "signoff",
@@ -238,6 +245,8 @@ export async function main(ctx) {
         }
         finally {
             asker?.close();
+            if (canPrompt)
+                ctx.render_hooks?.resume?.();
         }
     }
     if (verified) {

package/dist/chains/steps.d.ts

@@ -316,6 +316,23 @@ export declare function refine(opts?: {
     retries?: number;
     extraGates?: string[];
 }): Step;
+/**
+ * `cli/commands/watch.ts`'s `runRefine()` reads BOTH `refine_publish.json`
+ * and `refine_questions.json` back, unconditionally, after this chain
+ * exits — it has no other way to learn what THIS run did, since a chain's
+ * return value is just an exit code. A resumed spec (`continue-refinement`)
+ * reruns this entire chain from `request` on, into the SAME deterministic
+ * `context_handoff_dir` a PRIOR round already wrote into. Without clearing
+ * the file this run is NOT about to write, a stale `refine_questions.json`
+ * from an earlier escalation round survives a LATER round's successful
+ * publish — `runRefine` then reports those old questions as if raised
+ * again THIS round, so `runSpec` escalates a second time even though real
+ * issues were already created on the tracker seconds earlier. Called
+ * before EITHER branch writes, so exactly one of the two files reflects
+ * this run when the phase returns, never a leftover from a previous one.
+ * `force: true` — a first-ever run has neither file yet, which is fine.
+ */
+export declare function clearStaleRefineOutputFiles(contextHandoffDir: string): void;
 export declare function publishIssues(opts?: {
     description?: string;
 }): Step;

package/dist/chains/steps.js

@@ -40,7 +40,7 @@
  *    chain is a load-time problem the loader can report against a file and a
  *    line, never a phase that blows up ten minutes into an unattended run.
  */
-import { writeFileSync } from "node:fs";
+import { rmSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import * as changesLib from "../core/changes.js";
 import * as gates from "../core/gates.js";
@@ -73,7 +73,7 @@ function makeStep(fn, meta = {}) {
 export async function startRun(ctx, requiredAgents, requiredSuites) {
     const cfg = agentsCfg.loadConfig(ctx.config_paths);
     agentsCfg.validate(cfg, requiredAgents, requiredSuites, ctx.cwd);
-    const run = session.ensure(cfg, ctx.adw_id, ctx.cwd, ctx.chain_name);
+    const run = session.ensure(cfg, ctx.adw_id, ctx.cwd, ctx.chain_name, ctx.render_hooks);
     // Provenance, once per run, before any phase opens: a repo-local chain
     // (.spf/chains/*.yaml) records the file it came from. `chain_name` alone
     // stops being enough to reconstruct a run the moment a target repo can
@@ -723,6 +723,27 @@ function parsePriorityOption(raw) {
     }
     return raw;
 }
+/**
+ * `cli/commands/watch.ts`'s `runRefine()` reads BOTH `refine_publish.json`
+ * and `refine_questions.json` back, unconditionally, after this chain
+ * exits — it has no other way to learn what THIS run did, since a chain's
+ * return value is just an exit code. A resumed spec (`continue-refinement`)
+ * reruns this entire chain from `request` on, into the SAME deterministic
+ * `context_handoff_dir` a PRIOR round already wrote into. Without clearing
+ * the file this run is NOT about to write, a stale `refine_questions.json`
+ * from an earlier escalation round survives a LATER round's successful
+ * publish — `runRefine` then reports those old questions as if raised
+ * again THIS round, so `runSpec` escalates a second time even though real
+ * issues were already created on the tracker seconds earlier. Called
+ * before EITHER branch writes, so exactly one of the two files reflects
+ * this run when the phase returns, never a leftover from a previous one.
+ * `force: true` — a first-ever run has neither file yet, which is fine.
+ */
+export function clearStaleRefineOutputFiles(contextHandoffDir) {
+    for (const name of ["refine_questions.json", "refine_publish.json"]) {
+        rmSync(path.join(contextHandoffDir, name), { force: true });
+    }
+}
 export function publishIssues(opts = {}) {
     preflightDescription("publish", opts.description);
     const fn = async (run, state) => {
@@ -738,6 +759,7 @@ export function publishIssues(opts = {}) {
             owner: "tracker",
             description: opts.description ?? "Create the feature/story tree on the tracker, in dependency order, and link each to its parent",
         }), async (ph) => {
+            clearStaleRefineOutputFiles(run.context_handoff_dir);
             if (questions.length > 0) {
                 writeFileSync(path.join(run.context_handoff_dir, "refine_questions.json"), JSON.stringify(questions, null, 2));
                 ph.log({ escalated: questions.length });

package/dist/cli/ask.d.ts

@@ -33,8 +33,21 @@ export interface Asker {
 }
 /** `stdin.isTTY` is what actually matters (the interview reads it) — `stdout.isTTY` alone, this repo's only prior TTY check (`src/ui/server/serve.ts:88`), would let a piped-in `spf init` hang waiting on input that will never arrive. */
 export declare function isInteractive(): boolean;
+/**
+ * Whether `cli/ui/ink_asker.tsx`'s Ink-backed `Asker` can run instead of this
+ * file's plain readline one. Ink hard-requires raw-mode stdin — confirmed by
+ * testing: rendering an Ink app against a non-raw-mode-capable stdin throws
+ * before anything is drawn. `isInteractive()` already implies raw mode is
+ * available in every real case (a TTY stdin always exposes `setRawMode`);
+ * the extra `typeof` check is cheap insurance against whatever exotic
+ * terminal doesn't, so a caller falls back to `createAsker()` instead of
+ * crashing.
+ */
+export declare function inkAvailable(): boolean;
 /** Thrown when the user interrupts (Ctrl-C) or stdin closes (EOF) mid-interview. `initCommand` catches this and exits 130, writing nothing. */
 export declare class InterviewAborted extends Error {
     constructor();
 }
 export declare function createAsker(): Asker;
+/** Exported for `cli/ui/ink_asker.tsx`'s secret prompt, which renders the same "keep current" line and must mask it identically. */
+export declare function maskForPrompt(value: string): string;

package/dist/cli/ask.js

@@ -16,6 +16,19 @@ import { paint } from "../core/console.js";
 export function isInteractive() {
     return Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY) && !process.env["CI"];
 }
+/**
+ * Whether `cli/ui/ink_asker.tsx`'s Ink-backed `Asker` can run instead of this
+ * file's plain readline one. Ink hard-requires raw-mode stdin — confirmed by
+ * testing: rendering an Ink app against a non-raw-mode-capable stdin throws
+ * before anything is drawn. `isInteractive()` already implies raw mode is
+ * available in every real case (a TTY stdin always exposes `setRawMode`);
+ * the extra `typeof` check is cheap insurance against whatever exotic
+ * terminal doesn't, so a caller falls back to `createAsker()` instead of
+ * crashing.
+ */
+export function inkAvailable() {
+    return isInteractive() && typeof process.stdin.setRawMode === "function";
+}
 /** Thrown when the user interrupts (Ctrl-C) or stdin closes (EOF) mid-interview. `initCommand` catches this and exits 130, writing nothing. */
 export class InterviewAborted extends Error {
     constructor() {
@@ -148,7 +161,8 @@ export function createAsker() {
         },
     };
 }
-function maskForPrompt(value) {
+/** Exported for `cli/ui/ink_asker.tsx`'s secret prompt, which renders the same "keep current" line and must mask it identically. */
+export function maskForPrompt(value) {
     if (value.length <= 4)
         return "•".repeat(value.length);
     return `${"•".repeat(Math.max(0, value.length - 4))}${value.slice(-4)}`;

package/dist/cli/commands/doctor.js

@@ -22,6 +22,30 @@ import { PROVIDER_ENV_KEYS } from "../../core/providers.js";
 import { probeServedOllamaTags, resolveTiering } from "../../core/tiering.js";
 import { isRepoAt } from "../../core/git_helper.js";
 import { allChains, findChain, repoChainProblems, resolveRequiredAgents, resolveRequiredSuites } from "../../chains/index.js";
+import { isInteractive } from "../ask.js";
+import { paint as paintPlain } from "../../core/console.js";
+/**
+ * A transient "checking X..." status line around a network probe — real
+ * work only starts inside `run()`; this doesn't touch the promise's timing.
+ * TTY-only: `\r` + erase-to-end-of-line only makes sense against a real
+ * terminal, and a non-TTY/CI log should show nothing extra, matching
+ * doctor's output exactly as it always has when piped. Not Ink-based on
+ * purpose — this is a plain transient ANSI line, not a component tree, and
+ * doctor's checks accumulate into one report printed at the very end
+ * regardless, so there's no persistent live region for a probe status to
+ * join.
+ */
+async function withProbeStatus(label, run) {
+    if (!isInteractive())
+        return run();
+    process.stdout.write(paintPlain("dim", `  checking ${label}...`));
+    try {
+        return await run();
+    }
+    finally {
+        process.stdout.write("\r\x1b[2K");
+    }
+}
 /**
  * `severity` is a display-only axis, orthogonal to `ok`/`report.ok`: an
  * "info"/"warn" check still reports `ok: true` (it never fails `spf doctor`
@@ -174,7 +198,7 @@ export async function doctorCommand(argv) {
     }
     catch (error) {
         check(report, "config parses", false, error.message);
-        return finish(report, flags["json"]);
+        return await finish(report, flags["json"]);
     }
     const dataPaths = paths.resolveDataPaths(anchor, cfg.defaults.data_dir, cfg.observability.db);
     check(report, "data_dir", true, dataPaths.data_dir);
@@ -254,7 +278,7 @@ export async function doctorCommand(argv) {
             const probeBase = doubledPath ? trimmed.replace(/\/v1$/, "") : trimmed;
             const claudeCodeAgent = cfg.agents.find((a) => a.coding_agent === "claude_code");
             const probeModel = claudeCodeAgent?.model || "claude-sonnet-5";
-            const result = await probeAnthropicMessages(probeBase, probeModel);
+            const result = await withProbeStatus("ANTHROPIC_BASE_URL reachability", () => probeAnthropicMessages(probeBase, probeModel));
             check(report, "ANTHROPIC_BASE_URL reachability", true, (result.ok
                 ? `${doubledPath ? `dropping the trailing "/v1" makes it ` : ""}reachable: POST ${probeBase}/v1/messages -> HTTP ${result.status}${result.note ? ` (${result.note})` : ""}`
                 : `unreachable: POST ${probeBase}/v1/messages -> ${result.error}`) +
@@ -288,7 +312,7 @@ export async function doctorCommand(argv) {
         // latency either way — strictly cheaper for a pure reachability check,
         // and there's no live-server dependency in this choice: doctor's probe
         // itself tolerates either endpoint being down (see `probeGet`).
-        const result = await probeGet(`${ollamaBase}/models`);
+        const result = await withProbeStatus("OLLAMA_BASE_URL reachability", () => probeGet(`${ollamaBase}/models`));
         check(report, "OLLAMA_BASE_URL reachability", true, // informational/warning only — see the ANTHROPIC_BASE_URL check above for why
         result.ok ? `reachable: GET ${ollamaBase}/models -> HTTP ${result.status}` : `unreachable: GET ${ollamaBase}/models -> ${result.error}`, result.ok ? "info" : "warn");
     }
@@ -379,7 +403,7 @@ export async function doctorCommand(argv) {
         // chain+prompt is `spf estimate`'s job, not doctor's. `required` is the
         // WHOLE roster, matching the "roster + suites validate" call above —
         // every routed role doctor's job covers, not just what one chain needs.
-        const servedOllamaTags = flags["no-probe"] ? null : await probeServedOllamaTags(cfg);
+        const servedOllamaTags = flags["no-probe"] ? null : await withProbeStatus("served Ollama tags", () => probeServedOllamaTags(cfg));
         const resolution = resolveTiering({
             cfg,
             chainName: "",
@@ -559,7 +583,9 @@ export async function doctorCommand(argv) {
             `${cfg.observability.otel.headers ? `, headers: ${Object.keys(cfg.observability.otel.headers).join(", ")}` : ""})` +
             (insecure ? " — WARNING: plain http to a non-loopback host sends this telemetry in cleartext" : ""), insecure ? "warn" : "info");
         if (!flags["no-probe"]) {
-            const result = await probeOtel(url, cfg.observability.otel.headers);
+            // Captured into a local: TS narrowing from the outer `if (cfg.observability.otel)` doesn't survive into this closure.
+            const otelHeaders = cfg.observability.otel.headers;
+            const result = await withProbeStatus("observability.otel reachability", () => probeOtel(url, otelHeaders));
             check(report, "observability.otel reachability", true, // informational/warning only — same rule as the base-URL probes above
             result.ok
                 ? `reachable: POST ${endpointLabel(url)} (empty batch) -> HTTP ${result.status}${result.status >= 400 ? " — reachable but rejecting; check the path (/v1/traces) and headers" : ""}`
@@ -579,16 +605,26 @@ export async function doctorCommand(argv) {
     }
     return finish(report, flags["json"]);
 }
-function finish(report, json) {
+async function finish(report, json) {
     if (json) {
         console.log(JSON.stringify(report, null, 2));
+        return report.ok ? 0 : 1;
+    }
+    const footer = { ok: report.ok, message: report.ok ? "spf doctor: clean" : "spf doctor: problems found above" };
+    if (isInteractive()) {
+        const { renderChecklist } = await import("../ui/reports.js");
+        await renderChecklist(report.checks.map((c) => ({
+            icon: c.severity === "warn" ? "warn" : c.severity === "info" ? "info" : c.ok ? "ok" : "fail",
+            name: c.name,
+            detail: c.detail,
+        })), footer);
     }
     else {
         for (const c of report.checks) {
             const icon = c.severity === "warn" ? "⚠" : c.severity === "info" ? "ℹ" : c.ok ? "✓" : "✗";
             console.log(`${icon} ${c.name}: ${c.detail}`);
         }
-        console.log(report.ok ? "\nspf doctor: clean" : "\nspf doctor: problems found above");
+        console.log(`\n${footer.message}`);
     }
     return report.ok ? 0 : 1;
 }

package/dist/cli/commands/fanout.js

@@ -31,6 +31,7 @@ import { ABORTED_EXIT, attemptAdwId, runBestOf, ZERO_METRICS, } from "../../core
 import { findChain, runChain as runChainDef } from "../../chains/index.js";
 import { SfDb } from "../../ui/server/db.js";
 import { newId, parseCli, resolvePrompt } from "../../core/utils.js";
+import { isInteractive } from "../ask.js";
 /**
  * A ceiling on `--n`, not a recommendation. Each attempt is a full chain run
  * with its own agents, so `--n` multiplies spend directly — and the machine
@@ -62,9 +63,30 @@ function formatGates(attempt) {
 /**
  * The result table. Fixed column widths over a `console.table`: every other
  * `spf` listing (`sessions`, `phases`) prints plain padded columns, and this
- * output is read in a terminal beside them.
+ * output is read in a terminal beside them. On a TTY, routes through the
+ * same `renderTable()` (`cli/ui/reports.tsx`) those two now use instead —
+ * `fanout_cli.test.ts` runs with no TTY, so it keeps exercising this exact
+ * plain-text path unchanged.
  */
-function printTable(attempts) {
+async function printTable(attempts) {
+    const rows = attempts.map((a) => [
+        String(a.index),
+        a.adw_id,
+        a.branch,
+        a.status,
+        formatGates(a),
+        agents.formatUsd(a.cost),
+        a.status === "skipped" ? "-" : formatDuration(a.wall_ms),
+    ]);
+    if (isInteractive()) {
+        const { renderTable } = await import("../ui/reports.js");
+        await renderTable([["#", "adw_id", "branch", "status", "gates", "cost", "time"], ...rows], { rowColor: (i) => (i > 0 && attempts[i - 1].status === "fail" ? "red" : undefined) });
+        for (const a of attempts) {
+            if (a.error)
+                console.log(`      error: ${a.error}`);
+        }
+        return;
+    }
     const widths = {
         adw: Math.max(6, ...attempts.map((a) => a.adw_id.length)),
         branch: Math.max(6, ...attempts.map((a) => a.branch.length)),
@@ -343,11 +365,26 @@ export async function fanoutCommand(argv) {
     // this reliably buys, in the case it can't prevent, is telling the
     // operator the one thing the trace can't: which base adw_id to hand to
     // `--clean` afterwards.
+    // Mounted only on a real TTY — a live results table that updates row by
+    // row as each attempt settles, instead of the plain-text path's one-shot
+    // table at the very end. `dashboard` (not just its presence) is read by
+    // `onSignal` below, best-effort-unmounted before `process.exit()`: Ink's
+    // usual cleanup (restoring cursor visibility) never gets a chance to run
+    // on an abrupt exit otherwise, and this command's own SIGINT handler —
+    // unlike `spf watch`'s two-stage drain — already exits immediately by
+    // design (see its comment), so there's no "wait for it to finish" point
+    // to hook a graceful teardown into instead.
+    let dashboard;
+    if (isInteractive()) {
+        const { mountFanoutDashboard } = await import("../ui/fanout_dashboard.js");
+        dashboard = mountFanoutDashboard({ n, chainName: chain.name, baseBranch, baseAdwId });
+    }
     let interrupted = false;
     const onSignal = (signal) => {
         if (interrupted)
             return;
         interrupted = true;
+        dashboard?.unmountNow(); // best-effort cursor-visibility restore — see FanoutDashboard.unmountNow's own comment for why this isn't the awaited close()
         console.error(`\n[spf] fanout: ${signal} received — attempts already past their last checkpoint run to completion. ` +
             `Once everything has settled, clean up anything left under this base id with:\n` +
             `  spf fanout --clean ${baseAdwId}\n`);
@@ -370,10 +407,17 @@ export async function fanoutCommand(argv) {
             runAttempt,
             readMetrics,
             firstSuccess: flags["first-success"],
-            log: (message) => console.log(`[spf] ${message}`),
+            log: (message) => (dashboard ? dashboard.log(message) : console.log(`[spf] ${message}`)),
+            onAttempt: dashboard?.onAttempt,
         });
-        console.log(`\nfanout ${chain.name} — ${n} attempt(s), base ${baseBranch}`);
-        printTable(result.attempts);
+        await dashboard?.close();
+        // A dashboard already printed the header and kept the table live and
+        // in scrollback throughout the run — printing it again here would just
+        // duplicate what's already there. Only the non-TTY path needs both.
+        if (!dashboard) {
+            console.log(`\nfanout ${chain.name} — ${n} attempt(s), base ${baseBranch}`);
+            await printTable(result.attempts);
+        }
         if (!result.winner) {
             console.error(`\nno winner: ${result.basis}`);
             console.error(`Any attempt whose chain got far enough to open a session has its trace in the shared db — ` +

package/dist/cli/commands/init.js

@@ -27,7 +27,7 @@ import * as agents from "../../core/agents.js";
 import { ensureGitignore } from "../gitignore.js";
 import { parseCli } from "../../core/utils.js";
 import { paint } from "../../core/console.js";
-import { createAsker, isInteractive, InterviewAborted } from "../ask.js";
+import { createAsker, inkAvailable, isInteractive, InterviewAborted } from "../ask.js";
 import { gatherContext, runInterview } from "../interview.js";
 import { readEnvFile, upsertEnvFile, writeEnvExample } from "../env_file.js";
 import { installSkillCommand } from "./install-skill.js";
@@ -255,7 +255,12 @@ export async function initCommand(argv) {
         installSkill();
     }
     else {
-        const asker = createAsker();
+        // Ink needs raw-mode stdin to drive arrow-key selects and inline
+        // validation; `inkAvailable()` is `isInteractive()` plus one extra
+        // guard for the (practically never, but cheap to check) case where a
+        // TTY-reporting stdin still doesn't expose `setRawMode`. Either way
+        // falls back to the original readline asker, never to a hang.
+        const asker = inkAvailable() ? (await import("../ui/ink_asker.js")).createInkAsker() : createAsker();
         try {
             if (existsSync(configPath) && !flags["force"]) {
                 const overwrite = await asker.confirm(`${configPath} already exists — overwrite it?`, false);

package/dist/cli/commands/list.d.ts

@@ -1 +1 @@
-export declare function listCommand(): number;
+export declare function listCommand(): Promise<number>;

package/dist/cli/commands/list.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { allChains, repoChainProblems } from "../../chains/index.js";
+import { isInteractive } from "../ask.js";
 /**
  * A repo-defined chain's `source` is an absolute path into `.spf/chains/` by
  * construction (that's the one place `loadRepoChains` ever looks) — trim it
@@ -12,28 +13,46 @@ function repoChainLabel(source) {
     const idx = source.lastIndexOf(marker);
     return idx === -1 ? source : source.slice(idx);
 }
-export function listCommand() {
+export async function listCommand() {
     // Built-ins first, then repo chains — same order `allChains()` guarantees,
     // so this listing and `findChain`'s resolution order never disagree about
     // which chain wins on a name collision.
     const chains = allChains();
     const width = Math.max(...chains.map((c) => c.name.length));
-    for (const chain of chains) {
+    const entries = chains.map((chain) => {
         const agents = typeof chain.requiredAgents === "function" ? "(--agent picks who)" : chain.requiredAgents.join(", ") || "(none)";
         const suites = typeof chain.requiredSuites === "function" ? chain.requiredSuites({}) : chain.requiredSuites;
         const suiteNote = typeof chain.requiredSuites === "function" ? " (--suite overrides)" : "";
-        console.log(`${chain.name.padEnd(width)}  ${chain.phases}`);
-        console.log(`${"".padEnd(width)}  ${chain.describe}`);
-        console.log(`${"".padEnd(width)}  agents: ${agents}${suites.length ? `  ·  quality suites: ${suites.join(", ")}${suiteNote}` : ""}`);
-        // `source` is undefined for every built-in — only a chain loaded from a
-        // `.spf/chains/*.yaml` file carries one (see chains/repo_chains.ts).
-        if (chain.source) {
-            console.log(`${"".padEnd(width)}  (repo: ${repoChainLabel(chain.source)})`);
+        return {
+            name: chain.name,
+            phases: chain.phases,
+            describe: chain.describe,
+            agentsLine: `agents: ${agents}${suites.length ? `  ·  quality suites: ${suites.join(", ")}${suiteNote}` : ""}`,
+            // `source` is undefined for every built-in — only a chain loaded from a
+            // `.spf/chains/*.yaml` file carries one (see chains/repo_chains.ts).
+            repoLabel: chain.source ? repoChainLabel(chain.source) : undefined,
+        };
+    });
+    const usageLines = [
+        `spf <name> "<prompt>" [--config <path>] [--adw-id <id>] [--cwd <dir>] [--suite <name>]   (spf run <name> ... works identically)`,
+        `spf watch polls a tracker and runs one of these chains per issue — spf doctor shows the current config.`,
+    ];
+    if (isInteractive()) {
+        const { renderChainList } = await import("../ui/reports.js");
+        await renderChainList(entries, usageLines);
+    }
+    else {
+        for (const entry of entries) {
+            console.log(`${entry.name.padEnd(width)}  ${entry.phases}`);
+            console.log(`${"".padEnd(width)}  ${entry.describe}`);
+            console.log(`${"".padEnd(width)}  ${entry.agentsLine}`);
+            if (entry.repoLabel)
+                console.log(`${"".padEnd(width)}  (repo: ${entry.repoLabel})`);
+            console.log();
         }
-        console.log();
+        for (const line of usageLines)
+            console.log(line);
     }
-    console.log(`spf <name> "<prompt>" [--config <path>] [--adw-id <id>] [--cwd <dir>] [--suite <name>]   (spf run <name> ... works identically)`);
-    console.log(`spf watch polls a tracker and runs one of these chains per issue — spf doctor shows the current config.`);
     // Every malformed `.spf/chains/*.yaml` file (bad YAML, a schema/params
     // mismatch, a name naming a step factory that doesn't exist) becomes a
     // problem here instead of a chain in the list above — loadRepoChains()

package/dist/cli/commands/phases.d.ts

@@ -1 +1 @@
-export declare function phasesCommand(argv: string[]): number;
+export declare function phasesCommand(argv: string[]): Promise<number>;

package/dist/cli/commands/phases.js

@@ -1,6 +1,7 @@
 import { parseCli } from "../../core/utils.js";
 import { openTrace } from "./trace.js";
-export function phasesCommand(argv) {
+import { isInteractive } from "../ask.js";
+export async function phasesCommand(argv) {
     const { positionals, options, flags } = parseCli(argv, ["cwd", "config"], ["json"]);
     if (positionals.length < 1) {
         console.error("usage: spf phases <adw_id> [--cwd <dir>] [--config <path>] [--json]");
@@ -17,9 +18,22 @@ export function phasesCommand(argv) {
         console.log(`no phases recorded for ${adwId}`);
         return 1;
     }
-    for (const p of rows) {
-        const marker = p.status === "success" ? "✓" : p.status === "fail" ? "✗" : "…";
-        console.log(`${String(p.seq).padStart(2, "0")} ${marker} ${(p.name ?? "").padEnd(20)} ${(p.kind ?? "").padEnd(9)} ${(p.owner ?? "").padEnd(12)} ${p.error ?? ""}`);
+    const table = rows.map((p) => [
+        String(p.seq).padStart(2, "0"),
+        p.status === "success" ? "✓" : p.status === "fail" ? "✗" : "…",
+        p.name ?? "",
+        p.kind ?? "",
+        p.owner ?? "",
+        p.error ?? "",
+    ]);
+    if (isInteractive()) {
+        const { renderTable } = await import("../ui/reports.js");
+        await renderTable(table, { rowColor: (i) => (rows[i].status === "fail" ? "red" : undefined) });
+    }
+    else {
+        for (const [seq, marker, name, kind, owner, error] of table) {
+            console.log(`${seq} ${marker} ${name.padEnd(20)} ${kind.padEnd(9)} ${owner.padEnd(12)} ${error}`);
+        }
     }
     return 0;
 }

package/dist/cli/commands/run.js

@@ -1,5 +1,6 @@
 /** Shared by both `spf <chain> "..."` and `spf run <chain> "..."` — same dispatch. */
 import * as paths from "../../core/paths.js";
+import * as agents from "../../core/agents.js";
 import { parseCli, resolvePrompt } from "../../core/utils.js";
 import { runChain } from "../../chains/index.js";
 import { isInteractive } from "../ask.js";
@@ -59,5 +60,25 @@ export async function dispatchChain(chain, argv) {
     // rejecting anything but p0|p1|p2|p3 — so this stays a plain passthrough.
     if (options["priority"] !== undefined)
         chainOptions["priority"] = options["priority"];
+    // A live dashboard only ever makes sense for the one dispatch a human is
+    // actually watching — `spf watch`'s per-issue runs and `spf fanout`'s
+    // per-attempt runs go through `runChain`/`startRun` directly, never this
+    // function, so they're untouched. Loaded here (not left to `startRun`'s
+    // own `loadConfig` call moments later) purely to read the ceilings the
+    // dashboard displays — a second, cheap parse of the same small YAML, not
+    // a second source of truth: `startRun` still owns the real, validated
+    // config the run actually executes against.
+    if (isInteractive()) {
+        const { mountRunDashboard } = await import("../ui/run_dashboard.js");
+        const cfg = agents.loadConfig(ctx.config_paths);
+        const dashboard = mountRunDashboard({ maxCost: cfg.defaults.max_run_cost, maxTokens: cfg.defaults.max_run_tokens });
+        ctx.render_hooks = { sink: dashboard.sink, observer: dashboard.observer, pause: dashboard.pause, resume: dashboard.resume };
+        try {
+            return await runChain(chain, ctx, chainOptions);
+        }
+        finally {
+            await dashboard.close();
+        }
+    }
     return runChain(chain, ctx, chainOptions);
 }

package/dist/cli/commands/sessions.d.ts

@@ -1 +1 @@
-export declare function sessionsCommand(argv: string[]): number;
+export declare function sessionsCommand(argv: string[]): Promise<number>;

package/dist/cli/commands/sessions.js

@@ -1,6 +1,7 @@
 import { parseCli } from "../../core/utils.js";
 import { openTrace } from "./trace.js";
-export function sessionsCommand(argv) {
+import { isInteractive } from "../ask.js";
+export async function sessionsCommand(argv) {
     const { options, flags } = parseCli(argv, ["cwd", "config", "limit"], ["json"]);
     const { db } = openTrace(options);
     const limit = options["limit"] ? Number.parseInt(options["limit"], 10) : 20;
@@ -13,8 +14,15 @@ export function sessionsCommand(argv) {
         console.log("no sessions yet");
         return 0;
     }
-    for (const s of rows) {
-        console.log(`${s.adw_id}  ${(s.status ?? "").padEnd(8)}  ${s.started_at}  ${(s.request ?? "").slice(0, 60)}`);
+    const table = rows.map((s) => [s.adw_id, s.status ?? "", s.started_at ?? "", (s.request ?? "").slice(0, 60)]);
+    if (isInteractive()) {
+        const { renderTable } = await import("../ui/reports.js");
+        await renderTable(table);
+    }
+    else {
+        for (const [adwId, status, startedAt, request] of table) {
+            console.log(`${adwId}  ${status.padEnd(8)}  ${startedAt}  ${request}`);
+        }
     }
     return 0;
 }