huddle-cli 0.1.1 → 0.1.3

package/dist/ui/app.js

@@ -30,15 +30,21 @@ import { pickAsker } from "../orchestrator/ask.js";
 import { brainFrom, brainOptions, ollamaModels } from "../orchestrator/brain.js";
 import { fmtDuration, fmtTokens } from "../adapters/usage.js";
 import { runBoard } from "../orchestrator/scheduler.js";
-import { runQa, shouldQa } from "../orchestrator/qa.js";
+import { QA_ROUNDS, runQa, shouldQa } from "../orchestrator/qa.js";
+import { Budget, HARD_AT, SOFT_AT, budgetFlag, budgetNotes, budgetUse, costPreview, parseTokens, runHistory } from "../orchestrator/budget.js";
 import { commitFile, isGitRepo, listWorktrees, removeWorktree, worktreeFor } from "../sandbox/worktree.js";
 import { C, Dock, LiveLines, box, dot, fit, lineWidth, pad, truncate, width, wrap } from "./term.js";
 import { AGENTS_FILE_ERRORS, LEGACY } from "../adapters/index.js";
 import { logoLines } from "./logo.js";
-import { Dashboard } from "./dashboard.js";
+import { Dashboard, estHint, progressLine, taskCounts, taskMeter } from "./dashboard.js";
 import { learnFromRun } from "../orchestrator/learn.js";
+import { briefLines, liftPointers, placePointers, writeBrief } from "./brief.js";
 import { PasteCatcher, addPaths, asDrop, bracketedPaste, ctxCommand, flatten, interceptStdin, isLongPaste, looksLikePaths, pasteToScreen, screenEvent } from "./paste.js";
 import { splitPathTokens } from "../room/context.js";
+import { narration, narratorLine } from "./narrator.js";
+import { clearCommands, openApp, saveReport, takeCommands, writeLive } from "../app/live.js";
+import { KeyLine, Talk, addressee, questionLines, settledLine } from "./talk.js";
+import { sayToAgents, USER_ID } from "../room/user.js";
 // 0 = pick a free port per run, so sessions never collide.
 export const ROOM_PORT = Number(process.env.HUDDLE_ROOM_PORT ?? 0);
 // ---- paths & repo ----------------------------------------------------------
@@ -115,7 +121,7 @@ export function readPrefs() {
         return {};
     }
 }
-function writePrefs(p) {
+export function writePrefs(p) {
     fs.mkdirSync(path.dirname(prefsFile()), { recursive: true });
     fs.writeFileSync(prefsFile(), JSON.stringify(p, null, 2));
 }
@@ -321,9 +327,12 @@ export async function offerSetup(rl, results, force = false) {
 }
 /**
  * The live status block under the run's output, one line per agent:
- *   ● claude   60%  Build the CLI adapter          · note 20s ago · 1m12s
- *   ○ cursor   idle · 2 done
- * Every line fits `W` cells: the title gives way, never the numbers.
+ *   ● claude   ████░░  60%  Build the CLI adapter     · note 20s ago · 1m12s
+ *   ● codex    ······   —   Build the HTTP API        · no report yet · 3m20s
+ *   ○ cursor   idle · 2 merged
+ * The bar is the agent's own last huddle_progress %, never a guess. Every line
+ * fits `W` cells: the bar goes first on a narrow screen, then the title gives
+ * way, never the numbers.
  */
 export function statusLines(stats, W, now = Date.now()) {
     const idW = Math.min(12, Math.max(6, ...[...stats.agents.keys()].map((id) => id.length)));
@@ -333,15 +342,33 @@ export function statusLines(stats, W, now = Date.now()) {
             const done = a.tasks + a.reviews + (a.qa ?? 0);
             return head + C.faint(done ? `idle · ${a.tasks} merged${a.reviews ? `, ${a.reviews} reviewed` : ""}` : "idle");
         }
-        const pct = a.pct === undefined ? C.faint("  · ") : C.violet(`${String(a.pct).padStart(3)}%`);
         const quiet = a.noteAt === undefined ? now - a.busySince : now - a.noteAt;
-        const said = a.noteAt === undefined ? "no note yet" : `note ${fmtDuration(now - a.noteAt)} ago`;
-        const tail = (quiet > 120_000 ? C.yellow(` · ${said}`) : C.faint(` · ${said}`)) +
+        const said = a.noteAt === undefined ? "no report yet" : `note ${fmtDuration(now - a.noteAt)} ago`;
+        const est = estHint(a.est, now - a.busySince);
+        const meter = taskMeter(a.pct ?? null, W >= 100 ? 8 : W >= 70 ? 6 : 0);
+        const base = (quiet > 120_000 ? C.yellow(` · ${said}`) : C.faint(` · ${said}`)) +
             C.faint(` · ${fmtDuration(now - a.busySince)}${a.liveTokens > 0 ? ` · ${fmtTokens(a.liveTokens)} tok` : ""}`);
-        const room = Math.max(8, W - width(head) - 5 - width(tail));
-        return `${head}${pct} ${pad(truncate(a.doing ?? "working", room), Math.min(room, 34))}${tail}`;
+        // The estimate is a hint: it goes before the title would have to drop under 8 cells.
+        const withEst = est ? base + C.faint(" · ") + est : base;
+        const tail = W - width(head) - width(meter) - 1 - width(withEst) >= 8 ? withEst : base;
+        const room = Math.max(8, W - width(head) - width(meter) - 1 - width(tail));
+        return truncate(`${head}${meter} ${pad(truncate(a.doing ?? "working", room), Math.min(room, 34))}${tail}`, W);
     });
 }
+/**
+ * The pinned block during a run: the overall bar, then (once agents are on tasks) a status line each.
+ *   BUILD ███████░░░░░ 6/9 tasks · 12m03s
+ *   ● claude   ████░░  60%  Build the CLI adapter · note 20s ago · 1m12s
+ */
+export function runLines(stats, W, now = Date.now()) {
+    const r = stats.run;
+    const top = r ? `  ${progressLine(r, now - stats.startedAt, W - 2)}` : C.faint(`  ⏱ ${fmtDuration(now - stats.startedAt)}`);
+    return [top, ...(!r || r.phase === "BUILD" || r.phase === "QA" ? statusLines(stats, W, now) : [])];
+}
+/** The pinned block with the narrator on top: what's happening now in plain words, and whether you're needed. */
+export function liveLines(stats, W, now = Date.now()) {
+    return [narratorLine(stats, W, now), ...runLines(stats, W, now)];
+}
 export function newStats(workers) {
     return {
         startedAt: Date.now(),
@@ -441,6 +468,7 @@ async function prepareRepo(print, rl, goal = "") {
         print(`  ${C.green("✓")} git repo ready`);
     }
     ensureInit();
+    liftPointers(repoRoot()); // the brief's pointer is out of CLAUDE.md / AGENTS.md while the team works (ui/brief.ts)
     const dirty = git(["status", "--porcelain"]).out.split(/\r?\n/).filter((l) => l && !l.includes(".huddle/"));
     if (dirty.length) {
         if (!rl) {
@@ -519,28 +547,55 @@ function phase(print, name, sub = "") {
     const rest = sub ? " " + C.faint(lineWidth() ? oneLine(sub, space(head, " ")) : sub) : "";
     print(`\n${head}${rest}`);
 }
-function printPlan(print, goal, plan, workers) {
+const plural = (k, one) => `${k} ${k === 1 ? one : one + "s"}`;
+function printPlan(print, goal, plan, workers, verbose = process.env.HUDDLE_VERBOSE === "1", canType = false) {
     const took = plan.ms ? ` in ${fmtDuration(plan.ms)}` : "";
     phase(print, "PLAN", `${plan.tasks.length} task(s) · by ${plan.by}${took}${plan.note ? " — " + plan.note : ""}`);
-    print(`  ${C.faint("goal:")} ${oneLine(goal, space("  goal: "))}`);
+    // First, in plain words: what this run makes and what using it looks like (the planner's "plain").
+    for (const l of plainLines(goal, plan))
+        print(l);
+    print(C.faint("  who does what:"));
     const startable = plan.tasks.filter((t) => !t.depends_on?.length).length;
     const likely = likelyAgents(plan.tasks, workers);
     plan.tasks.forEach((t, i) => {
         const after = t.depends_on?.length ? C.faint(`  after ${t.depends_on.map((d) => d + 1).join(", ")}`) : "";
         const fit = likely[i];
-        const idea = t.from?.length ? C.faint(`  · idea: ${t.from.join(", ")}`) : "";
-        const who = fit ? `  ${C.faint("→ likely")} ${dot(fit)} ${fit}` : "";
+        // Whose idea it was is in TEAMWORK and huddle story; here it only pushed the title off the screen.
+        const idea = verbose && t.from?.length ? C.faint(`  · idea: ${t.from.join(", ")}`) : "";
+        const who = fit ? `  ${C.faint("→")} ${dot(fit)} ${fit}` : "";
         const num = `  ${C.faint(String(i + 1).padStart(2) + ".")} `;
         print(`${num}${oneLine(t.title, space(num, after, who, idea))}${after}${who}${idea}`);
     });
     print(C.faint(`  ${plan.tasks.length} task(s), ${Math.min(startable, workers.length)} of ${workers.length} agents can start right away`));
-    // The council's agreements, which every agent can huddle_recall mid-task.
+    // The council's agreements, which every agent can huddle_recall mid-task. For the
+    // person watching they're engineering detail: one line, the rest on request.
+    const d = plan.council?.decisions?.length ?? 0;
+    const r = plan.council?.risks?.length ?? 0;
+    if (verbose)
+        for (const l of planDetails(plan))
+            print(l);
+    else if (d || r)
+        print(`  ${C.violet("◆")} ${C.faint(`the agents agreed ${[d ? plural(d, "technical decision") : "", r ? `${plural(r, "risk")} to watch` : ""].filter(Boolean).join(" and ")} · `)}${canType ? `type ${C.bold("details")}` : C.bold("huddle story")}${C.faint(canType ? " to read them" : " has them")}`);
+}
+/** "  What you'll get: …" / "  For example: …" — the plan for someone who isn't a programmer. */
+export function plainLines(goal, plan) {
+    // No summary from the planner (a template plan, an older brain): the goal as you typed it.
+    if (!plan.plain?.what)
+        return [`  ${C.faint("goal:")} ${oneLine(goal, space("  goal: "))}`];
+    const label = (s) => `  ${C.bold(pad(s, 15))} `;
+    const out = [`${label("What you'll get")}${oneLine(plan.plain.what, space(label("What you'll get")))}`];
+    if (plan.plain?.example)
+        out.push(`${label("For example")}${oneLine(plan.plain.example, space(label("For example")))}`);
+    return out;
+}
+/** The council's decisions and risks in full, for `details` (and HUDDLE_VERBOSE=1). */
+export function planDetails(plan) {
+    const out = [];
     for (const d of plan.council?.decisions ?? [])
-        print(`  ${C.violet("◆")} ${C.faint("decided:")} ${oneLine(d, space("  ◆ decided: "))}`);
-    for (const r of plan.council?.risks ?? []) {
-        const label = `  ${C.yellow("!")} ${C.faint("risk" + (r.by ? ` (${r.by})` : "") + ":")} `;
-        print(`${label}${oneLine(r.body, space(label))}`);
-    }
+        out.push(`  ${C.violet("◆")} ${C.faint("decided:")} ${d}`);
+    for (const r of plan.council?.risks ?? [])
+        out.push(`  ${C.yellow("!")} ${C.faint("risk" + (r.by ? ` (${r.by})` : "") + ":")} ${r.body}`);
+    return out;
 }
 /** Show a spinner line while a promise settles (TTY only). */
 async function withSpinner(label, p) {
@@ -556,7 +611,21 @@ async function withSpinner(label, p) {
         process.stdout.write("\x1b[1A\x1b[2K"); // remove the spinner line
     }
 }
+/** A run, and the brief's pointers put back however it ended (plan mode, a stop, a crash). */
+/** The current run's typing line and open questions, closed however the run ends (a throw included). */
+let endTalkNow = null;
 export async function runGoal(goal, opts) {
+    try {
+        await runGoalOnce(goal, opts);
+    }
+    finally {
+        endTalkNow?.();
+        endTalkNow = null;
+        if (isGitRepo(process.cwd()))
+            placePointers(repoRoot(), { enabled: readPrefs().brief !== false });
+    }
+}
+async function runGoalOnce(goal, opts) {
     // Every line fits the terminal (logs keep everything). In a one-shot run on a
     // terminal, the per-agent status lines sit under the output (the Dock).
     let dock = null;
@@ -567,6 +636,13 @@ export async function runGoal(goal, opts) {
     if (flagIn)
         goal = goal.replace(flagIn[0], " ").replace(/\s+/g, " ").trim();
     const councilFlag = opts.council ?? (flagIn ? !flagIn[2] : undefined);
+    // --budget=5M, typed at the prompt too. Past 90% no new work starts; past 120% the agents stop (budget.ts).
+    const typedBudget = budgetFlag(goal);
+    goal = typedBudget.goal;
+    const budgetAsked = opts.budget ?? typedBudget.budget ?? readPrefs().budget;
+    const budget = new Budget(budgetAsked === undefined ? null : parseTokens(budgetAsked));
+    if (budgetAsked !== undefined && !budget.limit)
+        print(C.yellow(`  ! --budget=${budgetAsked} isn't a token count (try 5M or 800k) — no budget this run`));
     const workers = workersFrom(opts.results);
     // One-shot `huddle join` (no rl): a failure exits 1, and the hints name CLI commands.
     if (!workers.length && !opts.room?.server.remote.workers().length) {
@@ -586,6 +662,195 @@ export async function runGoal(goal, opts) {
     // Teammates' agents (from `huddle join` on their machines) work alongside yours.
     const bridge = opts.room?.server.remote;
     const remoteNow = () => (bridge?.workers() ?? []).map((r) => ({ id: r.id, remote: r }));
+    // The run's live numbers from its first step: the per-agent status lines and the overall bar.
+    const stats = newStats([...workers, ...remoteNow()].map((w) => w.id));
+    let board = null; // this run's Room, once its board is seeded: the bar counts its tasks
+    let logged = ""; // the last progress line a log got
+    const progress = (p) => {
+        let counts = {};
+        try {
+            if (board)
+                counts = taskCounts(board.listTasks());
+        }
+        catch {
+            /* a closed db: keep the last counts */
+        }
+        stats.run = { ...(stats.run ?? { phase: "PLAN", done: 0, total: 0, failed: 0 }), ...p, ...counts };
+        // A log (piped, no dock) gets one plain line each time the board's numbers move — never redraws.
+        const r = stats.run;
+        if (!opts.print && !process.stdout.isTTY && board && (r.phase === "BUILD" || r.phase === "QA")) {
+            const key = progressLine(r, null, 200, { on: false });
+            if (key !== logged)
+                print(C.faint(`  ${(logged = key)} · ${fmtDuration(Date.now() - stats.startedAt)}`));
+        }
+    };
+    // You, during the run: agents' questions for you and what you type to them. `huddle join`
+    // on a terminal gets a typing line under the pinned block (KeyLine); the app has its prompt.
+    const oneShotTty = !opts.rl && !opts.print && !!process.stdin.isTTY && !!process.stdout.isTTY;
+    // Every run has one: with no terminal to type in, the dashboard (huddle app) answers and talks.
+    const talk = opts.talk ?? new Talk();
+    let keys = null;
+    let interrupted = 0;
+    let stopNow = null; // set once the build can be stopped cleanly
+    let liveTick = null;
+    let sessionId;
+    let planNow = null;
+    const userNotes = []; // typed before the build starts: delivered when it does
+    // The whole run's off switch: the council, the plan, the build and QA all stop on it.
+    const life = new AbortController();
+    if (opts.signal?.aborted)
+        life.abort();
+    opts.signal?.addEventListener("abort", () => life.abort());
+    /** You asked it to stop (ctrl-c, `stop` in the dashboard): the build stops cleanly and still reports; before the build, everything stops. */
+    const requestStop = () => {
+        if (life.signal.aborted)
+            return;
+        print(C.yellow("  stopping agents…"));
+        if (stopNow)
+            stopNow();
+        else
+            life.abort();
+    };
+    if (talk) {
+        talk.onShow = (q, until) => {
+            stats.ask = { from: q.from, until };
+            print();
+            for (const l of questionLines(q, until))
+                print(l);
+            if (process.stdout.isTTY)
+                process.stdout.write("\x07"); // a bell: you may be in another window
+            act(q.from, `${C.yellow("⚑ asks you:")} ${q.question}`);
+        };
+        talk.onSettled = (q, a) => {
+            const next = talk.current();
+            stats.ask = next ? { from: next.q.from, until: next.until } : undefined;
+            print(settledLine(q, a));
+        };
+        talk.details = () => {
+            if (!planNow)
+                return print(C.faint("  no plan yet — the agents are still designing it"));
+            const d = planDetails(planNow);
+            if (!d.length)
+                return print(C.faint("  this plan has no separate decisions or risks"));
+            for (const l of d)
+                print(l);
+        };
+        talk.say = (line) => {
+            const { to, text } = addressee(line);
+            if (!text)
+                return;
+            if (!board) {
+                userNotes.push(text);
+                return print(`  ${C.violet("✉")} ${C.bold("you")}${C.faint(":")} ${oneLine(text, space("  ✉ you: ", " · noted, every agent gets it when building starts"))} ${C.faint("· noted, every agent gets it when building starts")}`);
+            }
+            const r = sayToAgents(board, text, to);
+            if (to && !r.now.length)
+                return print(C.yellow(`  ! ${to} isn't working on anything right now — say it without @ and every agent that starts next gets it`));
+            const who = r.now.length ? r.now.join(", ") : "every agent that starts next";
+            const head = `  ${C.violet("✉")} ${C.bold("you")} ${C.faint("→")} ${who}${C.faint(":")} `;
+            print(`${head}${oneLine(text, space(head))}`);
+        };
+    }
+    const act = (agent, text) => opts.onActivity?.({ agent, text });
+    /** The run is over: open questions go with option 1, the typing line goes away. */
+    const endTalk = () => {
+        if (liveTick)
+            clearInterval(liveTick);
+        liveTick = null;
+        writeLive(root, snapshot(true));
+        talk?.close();
+        if (talk)
+            talk.say = talk.details = null;
+        stats.ask = undefined;
+        keys?.stop();
+        keys = null;
+    };
+    endTalkNow = endTalk;
+    // The dashboard's view of this run (.huddle/live.json) and what it sends back (.huddle/inbox/): app/live.ts.
+    const councilSoFar = [];
+    const snapshot = (done = false) => {
+        const cur = talk.current();
+        return {
+            pid: process.pid,
+            goal,
+            startedAt: stats.startedAt,
+            updatedAt: Date.now(),
+            ...(sessionId ? { session: sessionId } : {}),
+            ...(planNow?.plain ? { plain: planNow.plain } : {}),
+            narrator: narration(stats),
+            ...(stats.run ? { run: stats.run } : {}),
+            agents: [...stats.agents].map(([id, a]) => ({
+                id,
+                busy: !!a.busySince,
+                ...(a.doing ? { doing: a.doing } : {}),
+                ...(a.pct !== undefined ? { pct: a.pct } : {}),
+                tokens: a.tokens + Math.max(0, a.liveTokens),
+                tasks: a.tasks,
+                reviews: a.reviews,
+            })),
+            council: councilSoFar,
+            ...(cur ? { ask: { id: cur.q.id, from: cur.q.from, question: cur.q.question, options: cur.q.options, ...(cur.q.why ? { why: cur.q.why } : {}), until: cur.until } } : {}),
+            tokens: [...stats.agents.values()].reduce((n, a) => n + a.tokens + Math.max(0, a.liveTokens), 0),
+            ...(budget.limit ? { budget: { limit: budget.limit, used: budget.tokens } } : {}),
+            ...(done ? { done } : {}),
+        };
+    };
+    const command = (c) => {
+        if (c.type === "stop")
+            return requestStop();
+        if (c.type === "say")
+            return talk.say?.(c.text);
+        const cur = talk.current();
+        if (cur && cur.q.id === c.id)
+            talk.answer(c.line);
+    };
+    clearCommands(root);
+    writeLive(root, snapshot());
+    liveTick = setInterval(() => {
+        for (const c of takeCommands(root))
+            command(c);
+        writeLive(root, snapshot());
+    }, 1000);
+    // A one-shot run on a terminal (huddle join): the overall bar and who's on what, pinned under
+    // the output (the prompt app draws the same lines in its footer). Up for the council, then the build.
+    const startDock = () => {
+        if (dock || opts.print || !process.stdout.isTTY)
+            return;
+        if (talk && oneShotTty && !keys)
+            keys = new KeyLine((l) => {
+                if (talk.answer(l))
+                    return;
+                const t = l.trim();
+                if (/^(details|decisions|risks)$/i.test(t))
+                    talk.details?.();
+                else if (t)
+                    talk.say?.(t);
+            }, () => dock?.redraw(), () => {
+                // First ctrl-c: stop the agents and still print what got done. Second: leave now.
+                if (interrupted++) {
+                    endTalk();
+                    stopDock();
+                    // What the terminal does on ctrl-c without raw mode: SIGINT to the whole
+                    // foreground group, agents included. Windows has no process groups.
+                    try {
+                        if (process.platform === "win32")
+                            throw new Error("no process groups");
+                        process.kill(0, "SIGINT");
+                    }
+                    catch {
+                        process.exit(130); // the scheduler's exit hook stops any running agents
+                    }
+                    return;
+                }
+                requestStop();
+                print(C.faint("  (ctrl-c again to quit right away)"));
+            }).start();
+        dock = new Dock(() => [...liveLines(stats, (process.stdout.columns || 80) - 1), ...(keys ? [keys.line()] : [])]).start();
+    };
+    const stopDock = () => {
+        dock?.stop();
+        dock = null;
+    };
     const brain = resolveBrain(opts.results, opts.probed);
     const crew = [...workers, ...remoteNow()].map((w) => ({ id: w.id, prefers: prefersOf(w) })); // one entry per agent, teammates' included
     const members = councilMembers(workers);
@@ -597,6 +862,9 @@ export async function runGoal(goal, opts) {
     let plan;
     if (wantCouncil.yes) {
         phase(print, "COUNCIL", `${members.map((m) => m.id).join(", ")} brainstorm before anyone codes · ${wantCouncil.why} (--no-council skips)`);
+        progress({ phase: "COUNCIL", step: 1 });
+        opts.onStats?.(stats);
+        startDock();
         /** "  ● codex        adopts claude's: <body, cut to fit> · 14s" */
         const say = (agent, label, body = "", took = "") => {
             const head = `  ${dot(agent)} ${pad(agent, 12)} ${label}${body ? " " : ""}`;
@@ -605,6 +873,20 @@ export async function runGoal(goal, opts) {
             opts.onActivity?.({ agent, text });
         };
         const onCouncil = (e) => {
+            if (e.type === "ratified")
+                councilSoFar.push({ agent: e.entry.agent, kind: e.entry.verdict === "object" ? "object" : e.entry.verdict === "skipped" ? "skipped" : "ok", text: e.entry.objections.join("\n") });
+            if (e.type === "entry" && e.entry.ok) {
+                const x = e.entry;
+                if (x.round === "proposal")
+                    councilSoFar.push({ agent: x.agent, kind: "proposal", text: x.text.slice(0, 2000) });
+                for (const a of x.adopts ?? [])
+                    councilSoFar.push({ agent: x.agent, kind: "adopt", of: a.of, text: a.text });
+                for (const f of x.flaws ?? [])
+                    councilSoFar.push({ agent: x.agent, kind: "flaw", of: f.of, text: f.text });
+            }
+            const step = e.type === "round" ? (e.round === "proposal" ? 1 : 2) : e.type === "synthesizing" ? 3 : e.type === "ratify" ? 4 : 0;
+            if (step)
+                progress({ phase: "COUNCIL", step });
             if (e.type === "round")
                 print(C.faint(`  ${e.round === "proposal" ? "1/4 each agent proposes a design…" : "2/4 each agent reviews the others: what to adopt, what's flawed…"}`));
             if (e.type === "synthesizing") {
@@ -660,20 +942,46 @@ export async function runGoal(goal, opts) {
         catch {
             /* no history: roster order */
         }
-        plan = await runCouncil(goal, crew, members, root, { brain, signal: opts.signal, onEvent: onCouncil, pastSyntheses: past });
+        try {
+            plan = await runCouncil(goal, crew, members, root, { brain, signal: life.signal, onEvent: onCouncil, pastSyntheses: past });
+        }
+        finally {
+            stopDock(); // the plan prints in full; the dock comes back for the build
+        }
     }
     else {
+        progress({ phase: "PLAN" });
+        opts.onStats?.(stats);
         // A big goal without a council (--no-council, or one agent) still gets a project-sized plan.
         const project = !listsOwnTasks(goal) && isBigGoal(goal, { repoFiles });
-        plan = await withSpinner(`planning with ${brain?.label ?? "template"}…`, planGoal(goal, crew, root, { brain, signal: opts.signal, project }));
+        plan = await withSpinner(`planning with ${brain?.label ?? "template"}…`, planGoal(goal, crew, root, { brain, signal: life.signal, project }));
+    }
+    if (life.signal.aborted)
+        return endTalk();
+    planNow = plan;
+    progress({ phase: "PLAN", step: undefined, total: plan.tasks.length });
+    printPlan(print, goal, plan, workers, undefined, !!talk);
+    {
+        let history = runHistory(null);
+        try {
+            if (opts.room?.db)
+                history = runHistory(opts.room.db);
+            else if (fs.existsSync(dbPath())) {
+                const d = new RoomDB(dbPath());
+                history = runHistory(d);
+                d.close();
+            }
+        }
+        catch {
+            /* no history: the defaults */
+        }
+        const qaRounds = shouldQa(goal, { flag: opts.qa, tasks: plan.tasks.length, repoFiles }) ? QA_ROUNDS : 0;
+        print(C.faint(`  ${costPreview({ tasks: plan.tasks.length, agents: workers.length + remoteNow().length, qaRounds, council: plan.council, history, budget })}`));
     }
-    if (opts.signal?.aborted)
-        return;
-    printPlan(print, goal, plan, workers);
     if (opts.mode === "plan") {
         print(C.faint("\n  plan mode — nothing created or spawned. " +
             (rl ? "shift+tab to switch mode and run it." : `Run it: huddle join ${JSON.stringify(goal)}`)));
-        return;
+        return endTalk();
     }
     if (opts.mode === "manual" && rl && !(await yes(rl, `\nStart with ${workers.map((w) => w.id).join(", ")}?`)))
         return;
@@ -703,7 +1011,7 @@ export async function runGoal(goal, opts) {
     const room = opts.room?.server ?? (await startRoom(db, ROOM_PORT));
     const taskIds = seedBoard(db, goal, plan.tasks);
     // Who planned it, for `huddle story` (the tasks themselves are task.added events).
-    db.publish("plan.made", { payload: { by: plan.by, note: plan.note ?? null, ms: plan.ms ?? null, tokens: plan.tokens ?? null, tasks: plan.tasks.length } });
+    db.publish("plan.made", { payload: { by: plan.by, note: plan.note ?? null, ms: plan.ms ?? null, tokens: plan.tokens ?? null, tasks: plan.tasks.length, plain: plan.plain ?? null } });
     // Before the live listener below, so the council's memories aren't printed twice.
     if (plan.council)
         recordCouncil(db, plan.council, plan.tasks, taskIds);
@@ -715,19 +1023,20 @@ export async function runGoal(goal, opts) {
         print(`  ${C.violet("◆")} ${C.faint("contract:")} ${ok ? "HUDDLE_CONTRACT.md on main" : "in the Room (couldn't commit HUDDLE_CONTRACT.md)"} ${C.faint(`· by ${by}` + (objected ? ` · ${plan.council.objections.filter((o) => o.taken).length}/${objected} objection(s) taken` : ""))}`);
     }
     const t0 = Date.now();
-    const stats = newStats([...workers, ...remoteNow()].map((w) => w.id));
+    board = db;
+    // What you said while they designed it, and their questions for you from here on.
+    for (const t of userNotes.splice(0))
+        sayToAgents(db, t);
+    sessionId = db.currentSession()?.id;
+    // Someone to ask: a terminal you type in, or the dashboard open on this repo. Nobody: the agent's own pick, at once.
+    room.askUser = (q) => (oneShotTty || opts.rl || openApp(root) ? talk.ask(q) : Promise.resolve({ choice: 1, text: "", by: "default" }));
+    progress({ phase: "BUILD" });
     opts.onStats?.(stats);
     phase(print, "BUILD", `${plan.tasks.length} task(s) · ${workers.length + remoteNow().length} agent(s) · each in its own worktree, merged when tests pass`);
     print(C.faint(`  room ${room.url} · tests: ${testCmd ?? "none yet"} · approvals: ${opts.approvals}`) +
         (rl ? C.faint(" · ctrl-t live view · ctrl-c stops") : ""));
     print();
-    // A one-shot run on a terminal (huddle join): who's on what, pinned under the output.
-    // (The prompt app draws the same lines in its footer.)
-    if (!opts.print && process.stdout.isTTY)
-        dock = new Dock(() => [
-            C.faint(`  ⏱ ${fmtDuration(Date.now() - t0)} · ${[...stats.agents.values()].reduce((n, a) => n + a.tasks, 0)} merged so far`),
-            ...statusLines(stats, (process.stdout.columns || 80) - 1),
-        ]).start();
+    startDock();
     const tag = (agent) => `${dot(agent)} ${pad(agent, 12)}`;
     /** "  ● codex        <label> <body, cut to fit><suffix>" */
     const line = (agent, label, body = "", suffix = "") => {
@@ -750,8 +1059,7 @@ export async function runGoal(goal, opts) {
         for (const l of notes.split("\n").map((x) => x.replace(/^\s*[-*•]\s*/, "").trim()).filter(Boolean).slice(0, n))
             print(C.faint(`      ${oneLine(l, space("      "))}`));
     };
-    let talk = 0; // agent-to-agent messages this run, for the teamwork summary
-    const act = (agent, text) => opts.onActivity?.({ agent, text });
+    let talk_ = 0; // agent-to-agent messages this run, for the teamwork summary
     const unsub = db.onEvent((e) => {
         const p = JSON.parse(e.payload || "{}");
         if (e.type === "task.progress" && p.note) {
@@ -762,7 +1070,8 @@ export async function runGoal(goal, opts) {
             sayOne(agent, C.faint(String(p.pct).padStart(3) + "%"), p.note);
             act(agent, `${C.faint(String(p.pct).padStart(3) + "%")} ${p.note}`);
         }
-        else if (e.type === "memory.added" && p.author !== "huddle") {
+        else if (e.type === "memory.added" && p.author !== "huddle" && p.author !== USER_ID) {
+            // (Your own words are on screen already, as the ✉ or → line.)
             act(undefined, `${C.violet("◆")} ${C.faint(p.author + " remembered:")} ${oneLine(p.body, 200)}`);
             // Already on screen as its own line: a task's done note (✓ merged), a QA bug (✗ found), a message (a → b).
             if (/^Task \S+ done:|^QA \(\S+\) found:|^\S+ → \S+:/.test(String(p.body)))
@@ -780,13 +1089,29 @@ export async function runGoal(goal, opts) {
             if (p.from === "huddle" && /^buddy check from/i.test(String(p.body)))
                 return;
             if (p.from !== "huddle")
-                talk++;
+                talk_++;
             const arrow = `${dot(p.from)} ${C.bold(p.from)} ${C.faint("→")} ${dot(p.to)} ${C.bold(p.to)}${C.faint(":")} `;
             const kind = p.kind === "answer" ? C.faint("  (answer)") : "";
             print(`  ${arrow}${oneLine(p.body, space("  ", arrow, kind))}${kind}`);
             act(undefined, `${arrow}${oneLine(p.body, 200)}`);
         }
     });
+    // The budget's hard line stops the run as Ctrl-C does: one signal for the board and QA.
+    const stopRun = new AbortController();
+    stopNow = () => stopRun.abort();
+    if (life.signal.aborted)
+        stopRun.abort();
+    life.signal.addEventListener("abort", () => stopRun.abort());
+    budget.add(plan.tokens ?? 0);
+    budget.onLevel((level, b) => {
+        if (level === "soft")
+            print(C.yellow(`  ! budget: ${budgetUse(b)}${b.used < SOFT_AT ? ", about 90% with the work still in flight" : ""} — no new tasks, QA rounds, buddy checks or pairings; running tasks finish`));
+        else {
+            print(C.yellow(`  ! budget: ${budgetUse(b)} — past ${Math.round(HARD_AT * 100)}%, stopping the running agents`));
+            stopRun.abort();
+        }
+    });
+    const unwatchBudget = budget.watch();
     const tok = (tokens, cached) => `${fmtTokens(tokens)} tok` + (cached > tokens / 2 ? ` (${fmtTokens(cached)} cached)` : "");
     const cost = (ms, tokens, cached) => C.faint(` · ${fmtDuration(ms)} · ${tok(tokens, cached)}`);
     if (remoteNow().length && !(remote && sync))
@@ -808,7 +1133,8 @@ export async function runGoal(goal, opts) {
         workers,
         testCmd: (worktree) => detectTestCmd(worktree),
         approvals: opts.approvals,
-        signal: opts.signal,
+        signal: stopRun.signal,
+        budget,
         approveMerge: opts.mode === "manual" && rl
             ? async ({ agent, title, diffstat }) => {
                 print(`\n  ${tag(agent)} ${C.violet("◎ ready")}  ${title}`);
@@ -826,7 +1152,7 @@ export async function runGoal(goal, opts) {
                 stats.agents.set(e.agent, { busySince: null, liveTokens: 0, tokens: 0, cached: 0, ms: 0, tasks: 0, reviews: 0 });
             const a = "agent" in e ? stats.agents.get(e.agent) : undefined;
             if (e.type === "start" && a)
-                Object.assign(a, { busySince: Date.now(), liveTokens: -1, doing: e.title, pct: undefined, noteAt: undefined }); // -1 = not reported yet
+                Object.assign(a, { busySince: Date.now(), liveTokens: -1, doing: e.title, pct: undefined, noteAt: undefined, est: db.getTask(e.task)?.est_seconds ?? undefined }); // -1 = not reported yet
             if (e.type === "tokens" && a)
                 a.liveTokens = e.tokens;
             if ((e.type === "merged" || e.type === "failed") && a)
@@ -931,6 +1257,13 @@ export async function runGoal(goal, opts) {
                 act(e.agent, `${C.violet("⇉")} pairs with ${e.with}: ${e.part}`);
                 sayOne(e.agent, `${C.violet("⇉ pairs with " + e.with)} on “${oneLine(e.title, 40)}”: takes`, e.part, C.faint(" · " + oneLine(e.reason, 50)));
             }
+            // Quiet past the silence window, but working (a long test run): not taken over (busy.ts).
+            if (e.type === "busy") {
+                act(e.agent, `${C.faint("⧗ running a long command")} ${C.faint("· " + e.why)}`);
+                sayOne(e.agent, C.faint("⧗ running a long command ·"), `quiet ${fmtDuration(e.quietMs)}, but busy: ${e.why}`);
+            }
+            if (e.type === "start" || e.type === "merged" || e.type === "failed")
+                progress({});
             if (e.type === "stuck")
                 print(C.yellow(`  ! ${e.blocked.length} task(s) blocked by failures: `) + C.faint(e.blocked.join(" · ")));
         },
@@ -940,11 +1273,17 @@ export async function runGoal(goal, opts) {
     // they file become routed fix tasks, run through this same board.
     let qaNote = "";
     let qaSum = ""; // the RESULT's checks line
+    let qaCut = false; // QA left undone by the budget
     if (!res.stopped && res.merged && shouldQa(goal, { flag: opts.qa, tasks: plan.tasks.length, repoFiles })) {
-        if (res.failed)
+        if (budget.stopping) {
+            qaCut = true;
+            print(C.faint("\n  QA skipped — the token budget is nearly spent"));
+        }
+        else if (res.failed)
             print(C.faint(`\n  QA skipped — ${res.failed} task(s) didn't merge; it checks finished builds only`));
         else {
             phase(print, "QA", "agents that didn't write it check the build · --no-qa skips");
+            progress({ phase: "QA" });
             const qa = await runQa({
                 db,
                 room,
@@ -954,18 +1293,24 @@ export async function runGoal(goal, opts) {
                 workers,
                 approvals: opts.approvals,
                 testCmd: (wt) => detectTestCmd(wt),
-                signal: opts.signal,
+                signal: stopRun.signal,
+                budget,
                 runFixes: () => runBoard(boardOpts),
                 onEvent: (e) => {
                     seen.push(e);
                     if (process.env.HUDDLE_EVENTS_FILE)
                         fs.appendFileSync(process.env.HUDDLE_EVENTS_FILE, JSON.stringify({ ts: Date.now(), qa: true, ...e }) + "\n");
                     qaLine(e, tag, print, act, stats);
+                    if (e.type === "round")
+                        progress({ round: e.round });
+                    else if (e.type === "bug" || e.type === "fixes")
+                        progress({});
                 },
             });
             res.merged += qa.fixed;
             res.failed += qa.failed;
             res.stopped ||= qa.stopped;
+            qaCut = !!qa.budget;
             qaSum = `${qa.rounds} round(s) · ${qa.bugs} bug(s) found, ${qa.fixed} fixed · ` + (qa.clean ? C.green("last round clean") : C.yellow("last round's fixes not re-checked"));
             qaNote = qa.clean
                 ? `QA: ${qa.rounds} round(s) by agents re-checking the integrated build; ${qa.bugs} bug(s) filed, ${qa.fixed} fix(es) merged, the last round came back clean.`
@@ -973,6 +1318,10 @@ export async function runGoal(goal, opts) {
         }
     }
     unsub();
+    unwatchBudget();
+    room.askUser = undefined;
+    endTalk();
+    const undone = budget.level === "ok" ? [] : db.listTasks().filter((t) => t.status === "backlog").map((t) => t.title);
     const doneNotes = db.recall().filter((m) => /^Task \S+ done:/.test(m.body)).map((m) => `- (${m.author}) ${m.body}`);
     const parked = db.listTasks().filter((t) => t.status === "needs_you");
     const takeovers = new Map(); // task id -> the branch a rescuer continued on
@@ -982,13 +1331,23 @@ export async function runGoal(goal, opts) {
             takeovers.set(ev.task_id, String(p.branch));
     }
     const learned = learnFromRun({ db, root, since: runStart, events: seen });
+    progress({ phase: "DONE" });
+    board = null;
+    // The hand-off brief for whoever works here next, solo (ui/brief.ts).
+    const brief = writeBrief({
+        root,
+        events: db.allEvents(),
+        getHandoff: (id) => db.getHandoff(id),
+        testCmd: detectTestCmd(root),
+        parked: parked.map((t) => ({ title: t.title, branch: takeovers.get(t.id) ?? worktreeFor(root, t.claimed_by ?? "", t.id).branch })),
+        enabled: readPrefs().brief !== false,
+    });
     if (ownRoom) {
         room.close();
         db.close();
     }
     opts.onStats?.(stats);
-    dock?.stop();
-    dock = null;
+    stopDock();
     // RESULT: what was built and how it was checked, then how the agents worked together, then what it cost.
     phase(print, "RESULT", "what got built, how it was checked, who did what");
     const head = res.stopped ? C.yellow("■ stopped") : res.failed ? C.yellow("◎") : C.green("✓");
@@ -1007,9 +1366,12 @@ export async function runGoal(goal, opts) {
         print(C.yellow(`  ! needs you: ${t.title}`) + C.faint(` — ${tk ? "two agents couldn't land it" : "conflicts with main"}; work kept on ${wt.branch}`));
         print(C.faint(`      to take it yourself: git merge ${wt.branch}   # resolve the markers, then commit`));
     }
-    if (res.merged)
-        await deliver(print, goal, root, startHead, doneNotes, brain, reportFacts(root, startHead, { ...res, testCmd: testsNow, qaNote }));
-    const team = teamworkLines(plan.council, seen, talk);
+    if (res.merged) {
+        const report = await deliver(print, goal, root, startHead, doneNotes, brain, reportFacts(root, startHead, { ...res, testCmd: testsNow, qaNote }));
+        if (sessionId && report.trim())
+            saveReport(root, sessionId, report);
+    }
+    const team = teamworkLines(plan.council, seen, talk_);
     if (team.length) {
         print(`\n${C.violet("TEAMWORK")} ${C.faint("· how the agents worked together · huddle story for all of it")}`);
         for (const t of team) {
@@ -1017,7 +1379,9 @@ export async function runGoal(goal, opts) {
             print(`${label}${oneLine(t.text, space(label))}`);
         }
     }
-    print(`\n${C.violet("COST")} ${C.faint(`· ${fmtDuration(Date.now() - t0)} · ${tok(total, totalCached)}`)}`);
+    print(`\n${C.violet("COST")} ${C.faint(`· ${fmtDuration(Date.now() - t0)} · ${tok(total, totalCached)}${budget.limit ? ` · ${budgetUse(budget)}` : ""}`)}`);
+    for (const l of budgetNotes(budget, { left: undone, qaCut }))
+        print(C.yellow(`  ! ${l}`));
     for (const [id, a] of stats.agents) {
         if (!a.tasks && !a.reviews && !a.qa) {
             print(`  ${tag(id)} ${C.faint("idle this run")}`);
@@ -1034,6 +1398,9 @@ export async function runGoal(goal, opts) {
     }
     if (learned.length)
         print(C.faint(`  ◆ learned ${learned.length} lesson(s) for next time · huddle lessons to see them`));
+    if (brief)
+        for (const l of briefLines(brief))
+            print(l);
     if (res.merged && remote && sync) {
         const p = pushMerged(root);
         print(p.ok ? `  ${C.green("↑")} git push · all in one go ${C.faint("→ " + p.note)}` : C.yellow(`  ! not pushed: ${p.note}`));
@@ -1185,6 +1552,7 @@ You run read-only because Huddle only asks you for this write-up; the run itself
  * built, how to run it, what's left. Written read-only by one agent from the
  * merged diff and the agents' done notes; falls back to the raw notes.
  */
+/** WHAT YOU GOT: the brain's write-up of the run (or the agents' notes). Returns the text, for the dashboard. */
 async function deliver(print, goal, root, startHead, notes, brain, facts = []) {
     const stat = git(["diff", "--stat", `${startHead}..HEAD`], root).out;
     let summary = "";
@@ -1212,6 +1580,7 @@ async function deliver(print, goal, root, startHead, notes, brain, facts = []) {
             say(n);
     if (stat)
         print(C.faint("\n  " + stat.split("\n").pop().trim() + C.faint("  ·  see it all: git log")));
+    return summary || notes.join("\n");
 }
 /** Answer a question about the repo, read-only. */
 async function answer(print, question, results, signal) {
@@ -1243,11 +1612,8 @@ export function printBoard(print = (l = "") => console.log(l)) {
     const s = db.currentSession();
     print(`\n${C.violet("BOARD")} ${C.faint("· " + (s?.goal ?? "(no goal yet)"))}`);
     for (const t of db.listTasks()) {
-        const w = 16;
-        const filled = Math.round((t.progress_pct / 100) * w);
-        const bar = C.violet("█".repeat(filled)) + C.faint("░".repeat(w - filled));
         const who = t.claimed_by ? `${dot(t.claimed_by)} ${t.claimed_by}` : C.faint("unclaimed");
-        print(`  ${statusLabel(t.status)} ${bar} ${String(t.progress_pct).padStart(3)}%  ${t.title}  ${who}`);
+        print(`  ${statusLabel(t.status)} ${taskMeter(t.progress_pct, 16, t.status)}  ${t.title}  ${who}`);
     }
     const mem = db.recall();
     if (mem.length) {
@@ -1304,7 +1670,8 @@ const HELP = `
   ${C.bold("ctrl-c")}              stop a run  ${C.faint("(or clear the line)")}
   ${C.bold("exit")}                leave  ${C.faint("(or ctrl-d)")}
 
-  ${C.faint("While agents work you can keep typing: board, approvals and questions work live; a new goal is queued.")}
+  ${C.faint("While agents work, what you type goes to them (@claude … for one); a question for you shows with numbered options.")}
+  ${C.faint("Questions? end with ? · details: the plan's technical decisions · next <goal>: queue another run.")}
 `;
 // Things people type out of habit that are shell commands, not goals.
 const SHELL_WORDS = new Set(["mkdir", "rm", "mv", "cp", "touch", "echo", "git", "ls", "pwd", "cat", "npm", "npx", "node", "pnpm", "yarn", "python", "python3", "code", "tree", "head", "tail"]);
@@ -1336,20 +1703,21 @@ export async function runApp() {
     const queue = [];
     let stats = null;
     let ticker = null;
-    /** "⏱ 1m12s · 3 merged so far" — the per-agent lines (statusLines) go under it. */
-    const liveStats = () => {
+    const talk = new Talk(); // agents' questions for you, your lines to them, during a run
+    // Footer under the prompt, like Claude Code's mode line; during a run, the overall bar
+    // ("BUILD ███░░ 6/9 tasks · 12m") and then one line per agent (runLines).
+    const footer = () => {
+        if (!run)
+            return idleFooter();
+        const W = (out.columns || 80) - 1;
+        const chip = `  ${MODE_INFO[state.mode].chip}  `;
+        const queued = queue.length ? C.faint(`  · ${queue.length} queued`) : "";
         if (!stats)
-            return C.violet("● planning…");
-        const merged = [...stats.agents.values()].reduce((n, a) => n + a.tasks, 0);
-        return `${C.faint("⏱")} ${fmtDuration(Date.now() - stats.startedAt)} ${C.faint(`· ${merged} merged so far`)}`;
+            return [`${chip}${C.violet("● planning…")}${queued}`];
+        const [top] = runLines(stats, W - width(chip) - width(queued) + 2);
+        return [narratorLine(stats, W), `${chip}${top.trimStart()}${queued}`, ...runLines(stats, W).slice(1)];
     };
-    // Footer under the prompt, like Claude Code's mode line; during a run, one more line per agent.
-    const footer = () => run
-        ? [
-            `  ${MODE_INFO[state.mode].chip}  ${liveStats()}${queue.length ? C.faint(`  · ${queue.length} queued`) : ""}`,
-            ...(stats ? statusLines(stats, (out.columns || 80) - 1) : []),
-        ]
-        : [`  ${MODE_INFO[state.mode].chip} ${C.faint("· " + MODE_INFO[state.mode].desc)}   ` + `${C.faint("approvals:")} ${state.approvals}   ${C.faint("shift+tab to switch")}`];
+    const idleFooter = () => [`  ${MODE_INFO[state.mode].chip} ${C.faint("· " + MODE_INFO[state.mode].desc)}   ` + `${C.faint("approvals:")} ${state.approvals}   ${C.faint("shift+tab to switch")}`];
     let reserved = 1; // footer lines reserved under the prompt
     const drawFooter = () => {
         if (!promptShown || asking || !out.isTTY)
@@ -1771,6 +2139,7 @@ export async function runApp() {
                 room: r ?? undefined,
                 onActivity: (a) => dash.push(a),
                 qa,
+                talk,
             });
         }
         catch (e) {
@@ -1797,6 +2166,11 @@ export async function runApp() {
         const line = raw.trim();
         promptShown = false;
         out.write("\x1b[2K"); // clear the footer line we just moved onto
+        // An agent asked you something: this line is the answer (Enter = the recommended option).
+        if (run && talk.current() && !/^(stop|exit|quit|view|help|\?|details)$/i.test(line)) {
+            talk.answer(line);
+            return showPrompt();
+        }
         if (!line)
             return showPrompt();
         const [cmd, ...rest] = line.split(/\s+/);
@@ -1925,11 +2299,20 @@ export async function runApp() {
                 shell(line);
                 print(C.faint(`  (ran as a shell command — say "build ${line}" if you meant a goal)`));
             }
-            else if (cmd === "ask" || (cmd !== "build" && cmd !== "join" && isQuestion(line))) {
+            else if (cmd === "details" && run)
+                talk.details?.();
+            else if (cmd === "ask" || (cmd !== "build" && cmd !== "join" && cmd !== "next" && isQuestion(line))) {
                 await answer(print, cmd === "ask" ? arg : line, results);
             }
+            else if (run && cmd !== "build" && cmd !== "join" && cmd !== "next") {
+                // During a run, what you type goes to the agents (room/user.ts). A new goal waits: "next <goal>".
+                if (talk.say)
+                    talk.say(line);
+                else
+                    print(C.faint("  the agents are wrapping up — say it again in a moment, or `next <goal>` for a new run"));
+            }
             else {
-                const goal = cmd === "build" || cmd === "join" ? arg : line;
+                const goal = cmd === "build" || cmd === "join" || cmd === "next" ? arg : line;
                 if (!goal)
                     print(C.faint("  usage: build <goal>"));
                 else if (run) {