huddle-cli 0.1.1 → 0.1.3

package/dist/orchestrator/budget.js

@@ -0,0 +1,283 @@
+// The cost guard. A run costs real money on someone's subscriptions: the
+// round-6 capstone runs took ~4–6M tokens, an improve run once hit 13M. So:
+//
+//   - Before a run, an estimate printed with the plan: "≈ 4–6M tokens, ~15–20
+//     min with 3 agents", from the plan's size, the agent count and what past
+//     runs in this repo's Room cost (built-in defaults from the capstone data
+//     until there is history). It is an estimate, and says so.
+//   - --budget=5M (or prefs "budget"): at 90% Huddle starts no new work — no
+//     new tasks, takeovers, QA rounds, buddy checks or pairings — and lets the
+//     running tasks finish; at 120% it stops the running agents, as Ctrl-C does.
+//     Either way the RESULT says what was left undone.
+//
+// What counts: every token the agents' meters report (usage.ts), cached
+// context INCLUDED — the same number the live footer, the estimate and the
+// RESULT's COST line show, so "--budget=5M" means the 5M you see there. Cached
+// reads are billed at a fraction (~10%), so this is conservative: a
+// cache-heavy run reaches its budget before its bill does. The COST line shows
+// the cached share next to it. Read-only asks (reviews, buddy checks, council
+// turns) report no usage, so the budget can't see them; the estimate counts
+// council turns from its defaults.
+import { fmtDuration, fmtTokens } from "../adapters/usage.js";
+/** Stop new work at this share of the budget… */
+export const SOFT_AT = 0.9;
+/** …and stop the running agents at this one. */
+export const HARD_AT = 1.2;
+/** "5M", "800k", "1.5m", "250000", "2,000,000" → tokens; null if it isn't one. */
+export function parseTokens(v) {
+    if (typeof v === "number")
+        return Number.isFinite(v) && v > 0 ? Math.round(v) : null;
+    const m = /^\s*(\d+(?:\.\d+)?)\s*([kmb])?\s*(?:tok(?:ens)?)?\s*$/i.exec(String(v ?? "").replace(/[,_]/g, ""));
+    if (!m)
+        return null;
+    const n = Number(m[1]) * ({ k: 1e3, m: 1e6, b: 1e9 }[(m[2] ?? "").toLowerCase()] ?? 1);
+    return n > 0 ? Math.round(n) : null;
+}
+/** `--budget=5M` (or `--budget 5M`) anywhere in a typed goal: the goal without it, and the value. */
+export function budgetFlag(goal) {
+    const m = /(^|\s)--budget(?:=|\s+)(\S+)(?=\s|$)/.exec(goal);
+    if (!m)
+        return { goal };
+    return { goal: goal.replace(m[0], " ").replace(/\s+/g, " ").trim(), budget: m[2] };
+}
+export class Budget {
+    limit;
+    meters = new Map();
+    extra = { tokens: 0, cached: 0 };
+    listeners = [];
+    /** Only goes up: once new work stopped, it stays stopped for the run. */
+    level = "ok";
+    constructor(limit) {
+        this.limit = limit;
+    }
+    /** Count this agent launch's meter (read live, every check). `who`: the agent, for its pace. */
+    track(m, who = "", now = Date.now()) {
+        if (!this.meters.has(m))
+            this.meters.set(m, { who: who.split("#")[0], start: now, lastAt: now, last: 0 });
+    }
+    /** Tokens measured outside a meter (the planner's own). */
+    add(tokens, cached = 0) {
+        this.extra.tokens += Math.max(0, tokens || 0);
+        this.extra.cached += Math.max(0, cached || 0);
+    }
+    get tokens() {
+        let n = this.extra.tokens;
+        for (const m of this.meters.keys())
+            n += m.tokens;
+        return n;
+    }
+    get cached() {
+        let n = this.extra.cached;
+        for (const m of this.meters.keys())
+            n += m.cached;
+        return n;
+    }
+    /**
+     * Tokens used plus an estimate of what's in flight but not reported yet.
+     * Found live (0.1.2): Codex reports usage only when its whole turn ends, so
+     * a 1m45s task counted 0 and then 406k at once, and the 90% line fired at
+     * 108%. A launch that hasn't reported is estimated at its agent's own pace
+     * this run (tokens per second of its earlier launches), capped at twice
+     * that agent's average launch. Only the soft line reads this: stopping
+     * running agents (the hard line) waits for real numbers.
+     */
+    projected(now = Date.now()) {
+        this.note(now);
+        const pace = new Map();
+        for (const [m, t] of this.meters) {
+            if (!m.seen || m.tokens <= 0)
+                continue;
+            const p = pace.get(t.who) ?? { tokens: 0, ms: 0, n: 0 };
+            p.tokens += m.tokens;
+            p.ms += Math.max(1000, t.lastAt - t.start);
+            p.n++;
+            pace.set(t.who, p);
+        }
+        let guess = 0;
+        for (const [m, t] of this.meters) {
+            if (m.seen)
+                continue;
+            const p = pace.get(t.who);
+            if (!p)
+                continue;
+            guess += Math.min((p.tokens / p.ms) * (now - t.start), (2 * p.tokens) / p.n);
+        }
+        return this.tokens + Math.round(guess);
+    }
+    /** Each meter's count went up: when (its pace). */
+    note(now) {
+        for (const [m, t] of this.meters)
+            if (m.tokens > t.last) {
+                t.last = m.tokens;
+                t.lastAt = now;
+            }
+    }
+    /** Share of the budget used (0 with no budget). */
+    get used() {
+        return this.limit ? this.tokens / this.limit : 0;
+    }
+    /** Past the soft line: start nothing new. */
+    get stopping() {
+        return this.check() !== "ok";
+    }
+    /** Re-read the meters; tells the listeners when the level goes up. */
+    check() {
+        if (!this.limit)
+            return this.level;
+        const u = this.used;
+        const next = u >= HARD_AT ? "hard" : u >= SOFT_AT || this.projected() / this.limit >= SOFT_AT ? "soft" : "ok";
+        const rank = { ok: 0, soft: 1, hard: 2 };
+        if (rank[next] <= rank[this.level])
+            return this.level;
+        // Straight to hard: the soft listeners still hear "soft" first (stop new work, then stop agents).
+        if (this.level === "ok" && next === "hard") {
+            this.level = "soft";
+            for (const f of this.listeners)
+                f("soft", this);
+        }
+        this.level = next;
+        for (const f of this.listeners)
+            f(next, this);
+        return this.level;
+    }
+    onLevel(f) {
+        this.listeners.push(f);
+    }
+    /** Check every `ms` until the returned stop() (agents' meters move between scheduler ticks). */
+    watch(ms = 1000) {
+        if (!this.limit)
+            return () => { };
+        const t = setInterval(() => this.check(), ms);
+        t.unref?.();
+        return () => clearInterval(t);
+    }
+}
+/** "5.1M of 6M budget (85%)" — or "" with no budget. */
+export function budgetUse(b) {
+    if (!b.limit)
+        return "";
+    return `${fmtTokens(b.tokens)} of ${fmtTokens(b.limit)} budget (${Math.round(b.used * 100)}%)`;
+}
+/** From the capstone runs (round 6): ~350k tokens a task, ~550k a QA round, ~60k a council turn. */
+export const DEFAULT_COSTS = { perTask: 350_000, perQaRound: 550_000, perCouncilTurn: 60_000, taskMs: 4 * 60_000, qaRoundMs: 4 * 60_000 };
+const avg = (xs) => xs.reduce((a, b) => a + b, 0) / xs.length;
+/**
+ * What past runs in this Room cost: tokens and agent time per task (merged or
+ * failed, a takeover's first rounds included) and per QA check. Each number
+ * falls back to its default until there are enough samples (3 tasks, 2 checks).
+ */
+export function runHistory(db) {
+    const costs = { ...DEFAULT_COSTS };
+    if (!db)
+        return { costs, tasks: 0, checks: 0 };
+    let evs = [];
+    try {
+        evs = db.eventsOfType(["run.merged", "run.failed", "run.takeover", "qa.done"], 0, 1000);
+    }
+    catch {
+        return { costs, tasks: 0, checks: 0 };
+    }
+    const p = (e) => {
+        try {
+            return JSON.parse(e.payload || "{}");
+        }
+        catch {
+            return {};
+        }
+    };
+    const tasks = [];
+    let handedOver = 0; // a rescued task's first agent's rounds: no merged/failed event carries them
+    const checks = [];
+    for (const e of evs) {
+        const x = p(e);
+        if (e.type === "run.takeover")
+            handedOver += x.kind === "rescue" ? Number(x.tokens) || 0 : 0;
+        else if (e.type === "qa.done") {
+            if (x.ok && Number(x.tokens) > 0)
+                checks.push({ tokens: Number(x.tokens), ms: Number(x.ms) || 0, bugs: Number(x.bugs) || 0 });
+        }
+        else if (Number(x.tokens) > 0)
+            tasks.push({ tokens: Number(x.tokens), ms: Number(x.ms) || 0 });
+    }
+    if (tasks.length >= 3) {
+        costs.perTask = Math.round((tasks.reduce((n, t) => n + t.tokens, 0) + handedOver) / tasks.length);
+        const ms = tasks.map((t) => t.ms).filter((m) => m > 0);
+        if (ms.length)
+            costs.taskMs = Math.round(avg(ms));
+    }
+    if (checks.length >= 2) {
+        const bugs = avg(checks.map((c) => c.bugs));
+        costs.perQaRound = Math.round(avg(checks.map((c) => c.tokens)) + bugs * costs.perTask);
+        costs.qaRoundMs = Math.round(avg(checks.map((c) => c.ms)) + (bugs > 0 ? costs.taskMs : 0));
+    }
+    return { costs, tasks: tasks.length >= 3 ? tasks.length : 0, checks: checks.length >= 2 ? checks.length : 0 };
+}
+/**
+ * A range, not a promise: tasks × per-task cost (±15%), QA as 1 round (low)
+ * to all rounds (high), plus the council's turns. Time: the tasks in waves of
+ * `agents` at a time, then QA.
+ */
+export function estimateRun(o) {
+    const h = o.history ?? { costs: DEFAULT_COSTS, tasks: 0, checks: 0 };
+    const c = h.costs;
+    const agents = Math.max(1, o.agents);
+    const council = (o.councilTurns ?? 0) * c.perCouncilTurn;
+    const qaLow = o.qaRounds ? 1 : 0;
+    const low = o.tasks * c.perTask * 0.85 + qaLow * c.perQaRound + council;
+    const high = o.tasks * c.perTask * 1.15 + o.qaRounds * c.perQaRound + council;
+    const waves = Math.ceil(o.tasks / agents);
+    const lowMs = waves * c.taskMs * 0.85 + qaLow * c.qaRoundMs;
+    const highMs = waves * c.taskMs * 1.15 + o.qaRounds * c.qaRoundMs;
+    const from = [h.tasks ? `${h.tasks} past task(s)` : "", h.checks ? `${h.checks} past QA check(s)` : ""].filter(Boolean);
+    const basis = from.length ? `from this repo's ${from.join(" and ")}` : "from Huddle's defaults (no history in this repo yet)";
+    return { low, high, lowMs, highMs, agents, basis };
+}
+/** Round a token range outward to steps that read well: 4–6M, 1.5–2M, 350–500k. */
+export function fmtTokenRange(low, high) {
+    const step = high >= 3e6 ? 1e6 : high >= 1e6 ? 5e5 : high >= 1e5 ? 5e4 : 1e4;
+    const lo = Math.max(step, Math.floor(low / step) * step);
+    const hi = Math.max(lo + step, Math.ceil(high / step) * step);
+    const unit = (n) => (n >= 1e6 ? `${+(n / 1e6).toFixed(1)}` : `${Math.round(n / 1e3)}`);
+    const suffix = (n) => (n >= 1e6 ? "M" : "k");
+    return suffix(lo) === suffix(hi) ? `${unit(lo)}–${unit(hi)}${suffix(hi)}` : `${fmtTokens(lo)}–${fmtTokens(hi)}`;
+}
+/** "~15–20 min", "~1h05m–1h20m" */
+export function fmtMsRange(low, high) {
+    const lo = Math.max(1, Math.round(low / 60_000));
+    const hi = Math.max(lo + 1, Math.round(high / 60_000));
+    return hi < 60 ? `~${lo}–${hi} min` : `~${fmtDuration(lo * 60_000)}–${fmtDuration(hi * 60_000)}`;
+}
+/** "≈ 4–6M tokens, ~15–20 min with 3 agents" */
+export function estimateText(e) {
+    return `≈ ${fmtTokenRange(e.low, e.high)} tokens, ${fmtMsRange(e.lowMs, e.highMs)} with ${e.agents} agent${e.agents === 1 ? "" : "s"}`;
+}
+/**
+ * The line printed with the plan: "≈ 4–6M tokens, ~15–20 min with 3 agents ·
+ * an estimate, from …", plus what the budget will do.
+ */
+export function costPreview(o) {
+    const turns = o.council ? o.council.proposals.length + o.council.critiques.length + (o.council.ratify?.length ?? 0) : 0;
+    const e = estimateRun({ tasks: o.tasks, agents: o.agents, qaRounds: o.qaRounds, councilTurns: turns, history: o.history });
+    const lim = o.budget?.limit;
+    const over = lim && e.low > lim ? " — the low end is past it: expect a partial run" : "";
+    const b = lim ? ` · budget ${fmtTokens(lim)}: new work stops at ${fmtTokens(lim * SOFT_AT)}, agents at ${fmtTokens(lim * HARD_AT)}${over}` : "";
+    return `${estimateText(e)} · an estimate, ${e.basis}${b}`;
+}
+/** The RESULT's budget lines: why the run stopped short and what it left undone. [] when it didn't. */
+export function budgetNotes(b, o) {
+    if (!b.limit || b.level === "ok")
+        return [];
+    const out = [
+        b.level === "hard"
+            ? `budget: ${fmtTokens(b.tokens)} passed ${Math.round(HARD_AT * 100)}% of ${fmtTokens(b.limit)} — running agents were stopped`
+            : `budget: ${Math.round(SOFT_AT * 100)}% of ${fmtTokens(b.limit)} reached — no new work started after it; running tasks finished`,
+    ];
+    if (o.left.length)
+        out.push(`left undone (${o.left.length}): ${o.left.join(" · ")}`);
+    if (o.qaCut)
+        out.push("left undone: QA (no round started past the budget line)");
+    if (o.left.length || o.qaCut)
+        out.push("what merged stays on main; a bigger --budget (or a follow-up goal) finishes the rest");
+    return out;
+}
+//# sourceMappingURL=budget.js.map

package/dist/orchestrator/busy.js

@@ -0,0 +1,106 @@
+// Busy, or stuck? An agent that prints nothing and calls no huddle_* tool for
+// the silence window used to be taken over. Found live (evolve run,
+// 2026-10-16): claude was taken over by codex while it was running Huddle's
+// own 8-minute test suite — quiet, but working. So before an agent counts as
+// silent, Huddle looks at what it is doing:
+//
+//   - a child or grandchild process used CPU since the last look (the test
+//     suite, a build, an install), or
+//   - files in its worktree changed since the last look, or
+//   - its log grew.
+//
+// Any of those = busy: the silence clock restarts from that look, so a long
+// command gets its full window again once it ends. A hard cap (default 3× the
+// window, HUDDLE_SILENCE_MAX_MIN) since its last real output still takes it
+// over, so a runaway loop can't hold a task forever.
+import fs from "node:fs";
+import path from "node:path";
+import { descendants } from "../platform.js";
+/** Longest an agent may go without output or a huddle_* call, busy or not. HUDDLE_SILENCE_MAX_MIN overrides; default 3× the silence window. */
+export function silenceMaxMsFromEnv(silenceMs) {
+    const v = Number(process.env.HUDDLE_SILENCE_MAX_MIN);
+    return Math.max(silenceMs, v > 0 ? v * 60_000 : 3 * silenceMs);
+}
+/** CPU a process tree must use between two looks to count as working: 2% of the wall time, at least 50ms. */
+export const busyCpuMs = (elapsedMs) => Math.max(50, elapsedMs * 0.02);
+/** Folders never walked for changed files: git's own, and installs too big to walk every tick. */
+const SKIP_DIRS = new Set([".git", "node_modules"]);
+const MAX_WALK = 5000;
+/** A file under `dir` modified after `since`, or null. Bounded: at most MAX_WALK entries. */
+export function changedSince(dir, since) {
+    const stack = [dir];
+    let n = 0;
+    while (stack.length && n < MAX_WALK) {
+        const d = stack.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(d, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (++n > MAX_WALK)
+                break;
+            const p = path.join(d, e.name);
+            if (e.isDirectory()) {
+                if (!SKIP_DIRS.has(e.name))
+                    stack.push(p);
+                continue;
+            }
+            try {
+                if (fs.statSync(p).mtimeMs > since)
+                    return path.relative(dir, p);
+            }
+            catch {
+                /* gone while we looked */
+            }
+        }
+    }
+    return null;
+}
+const sizeOf = (f) => {
+    try {
+        return fs.statSync(f).size;
+    }
+    catch {
+        return 0;
+    }
+};
+/** Remembers each agent's last look and compares the next one with it. */
+export class BusyWatch {
+    looks = new Map();
+    /** Compare `t` (agent `id`) with its last look. `table` = one process snapshot (null: the OS wouldn't say). */
+    look(id, t, table, now = Date.now()) {
+        const kids = table ? descendants(table, t.pid) : [];
+        const cpu = new Map(kids.map((p) => [p.pid, p.cpuMs]));
+        const before = this.looks.get(id);
+        const log = sizeOf(t.logPath);
+        this.looks.set(id, { at: now, pid: t.pid, cpu, log });
+        if (!before || before.pid !== t.pid)
+            return null;
+        // A process born since the last look did all its work since then.
+        let used = 0;
+        let top = null;
+        for (const p of kids) {
+            const d = p.cpuMs - (before.cpu.get(p.pid) ?? 0);
+            if (d <= 0)
+                continue;
+            used += d;
+            if (!top || d > top.ms)
+                top = { name: p.name, ms: d };
+        }
+        if (used >= busyCpuMs(now - before.at))
+            return { busy: true, why: `${top?.name || "a child process"} is using CPU (${(used / 1000).toFixed(1)}s since the last look)` };
+        if (log > before.log)
+            return { busy: true, why: "its log is growing" };
+        const f = changedSince(t.worktree, before.at);
+        if (f)
+            return { busy: true, why: `files are changing (${f})` };
+        return { busy: false, why: kids.length ? `${kids.length} child process(es), none using CPU; no files changing` : "no child processes; no files changing" };
+    }
+    forget(id) {
+        this.looks.delete(id);
+    }
+}
+//# sourceMappingURL=busy.js.map

package/dist/orchestrator/council.js

@@ -20,7 +20,7 @@ import { setContract, capContract } from "../room/contract.js";
 import { askAgent } from "./ask.js";
 import { repoContext } from "./brain.js";
 import { carryGoal } from "./goal.js";
-import { goalSize, jsonCandidates, listsOwnTasks, parsePlan, planGoal, plannerPrompt } from "./planner.js";
+import { goalSize, jsonCandidates, listsOwnTasks, parsePlain, parsePlan, planGoal, plannerPrompt } from "./planner.js";
 const defaultAsk = (m, prompt, cwd, o) => askAgent(m.adapter, prompt, cwd, { timeoutMs: o.timeoutMs, signal: o.signal, noTools: true, quick: o.quick ?? true });
 const PROPOSAL_CAP = 1500;
 const CRITIQUE_CAP = 1200;
@@ -357,7 +357,7 @@ YOUR PLAN:
 ${planText}
 
 Apply each objection that is right and reject the others. You have no tools in this step.
-Reply with ONLY the full revised JSON in the same shape (tasks, decisions, risks, contract), plus "objections":[{"by":"agent id","taken":true,"why":"short"}] — one entry per objection above. No prose, no code fences.`;
+Reply with ONLY the full revised JSON in the same shape (tasks, decisions, risks, contract, plain, example), plus "objections":[{"by":"agent id","taken":true,"why":"short"}] — one entry per objection above. No prose, no code fences.`;
 }
 /**
  * Brainstorm with every member, cross-review, then have the most-adopted
@@ -368,6 +368,9 @@ Reply with ONLY the full revised JSON in the same shape (tasks, decisions, risks
 export async function runCouncil(goal, crew, members, repoRoot, opts) {
     const t0 = Date.now();
     const timeoutMs = opts.timeoutMs ?? councilTimeoutMs();
+    // Ratifying is "OK" or up to 3 objections: it never needs a design's time box. Found live
+    // (0.1.2): the whole team waited 2 minutes on one agent's ratify that then timed out.
+    const ratifyMs = Math.min(timeoutMs, (Number(process.env.HUDDLE_RATIFY_TIMEOUT_S) || 75) * 1000);
     const ro = { ask: opts.ask ?? defaultAsk, cwd: repoRoot, timeoutMs, signal: opts.signal, onEvent: opts.onEvent };
     const context = repoContext(repoRoot, 150);
     const ids = members.map((m) => m.id);
@@ -449,6 +452,7 @@ export async function runCouncil(goal, crew, members, repoRoot, opts) {
     if (!synth || !tasks)
         return fallback(critiques, `council: ${missed.join(", then ") || "nobody"} didn't synthesize a plan`);
     let extras = parseExtras(synthText, speaking);
+    let plain = parsePlain(synthText);
     // Ratify: everyone else on the council checks the contract once, in parallel.
     // The brain's own CLI doesn't ratify the brain's plan (it would grade itself).
     const ratify = [];
@@ -458,10 +462,10 @@ export async function runCouncil(goal, crew, members, repoRoot, opts) {
     if (extras.contract && ratifiers.length && !opts.signal?.aborted) {
         opts.onEvent?.({ type: "ratify", by: synth.id, agents: ratifiers.map((m) => m.id) });
         const verdicts = await Promise.all(ratifiers.map(async (m) => {
-            const { res, ms } = await boxed(() => ro.ask(m, ratifyPrompt(goal, m, synth.id, tasks, extras.contract), repoRoot, { timeoutMs, signal: opts.signal }), timeoutMs);
+            const { res, ms } = await boxed(() => ro.ask(m, ratifyPrompt(goal, m, synth.id, tasks, extras.contract), repoRoot, { timeoutMs: ratifyMs, signal: opts.signal }), ratifyMs);
             const e = res.ok && res.text.trim()
                 ? { agent: m.id, ...parseRatify(res.text), ms }
-                : { agent: m.id, verdict: "skipped", objections: [], ms, skipped: res.late || ms >= timeoutMs ? "timed out" : "no answer" };
+                : { agent: m.id, verdict: "skipped", objections: [], ms, skipped: res.late || ms >= ratifyMs ? "timed out" : "no answer" };
             opts.onEvent?.({ type: "ratified", entry: e });
             return e;
         }));
@@ -489,6 +493,7 @@ export async function runCouncil(goal, crew, members, repoRoot, opts) {
                 if (res.tokens)
                     tokens = (tokens ?? 0) + res.tokens;
                 extras = { ...next, contract: next.contract || extras.contract };
+                plain = parsePlain(res.text) ?? plain;
             }
             else
                 for (const o of raised)
@@ -520,6 +525,7 @@ export async function runCouncil(goal, crew, members, repoRoot, opts) {
         ...(carried.check.missing.length ? { note: goalNote(carried.check) } : {}),
         ms: Date.now() - t0,
         tokens,
+        ...(plain ? { plain } : {}),
         council: result({
             proposals,
             critiques,

package/dist/orchestrator/launcher.js

@@ -105,7 +105,9 @@ export function launchAgent(opts) {
         return handle;
     fs.mkdirSync(path.dirname(logPath), { recursive: true });
     const log = fs.createWriteStream(logPath, { flags: "a" });
-    handle.child = spawnTool(cmd, { cwd, stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, ...env, ...plug.env } }, { prompt, stdinPrompt: adapter.stdinPrompt });
+    handle.child = spawnTool(cmd, 
+    // MCP_TOOL_TIMEOUT: Claude's wait on one tool call; huddle_ask_user may wait 90s for the person.
+    { cwd, stdio: ["ignore", "pipe", "pipe"], env: { MCP_TOOL_TIMEOUT: "150000", ...process.env, ...env, ...plug.env } }, { prompt, stdinPrompt: adapter.stdinPrompt });
     // Everything still goes to the log; stdout is also scanned for token usage.
     let partial = "";
     handle.child.stdout.on("data", (chunk) => {

package/dist/orchestrator/learn.js

@@ -64,13 +64,9 @@ export function deriveLessons(r, o) {
             evidence: `qa.bug by ${e.p.by ?? e.agent ?? "?"}: ${one(e.p.repro, 120)}`,
         });
     }
-    // A reviewer sent work back.
-    for (const e of r.events.filter((e) => e.type === "reviewed" && !e.approve && !e.skipped).slice(0, MAX_PER_KIND))
-        add({
-            scope: repo,
-            text: `A review sent "${one(e.title, 60)}" back: ${one(e.notes, 160)}`,
-            evidence: `${e.agent} reviewed ${e.author}'s work`,
-        });
+    // A reviewer sent work back: not a lesson. Its notes are about that one task (found live,
+    // 0.1.2: "src/main.js: io.stdout.write() is outside the try/catch…" stored as a rule).
+    // A general rule from it is the agent's to write: huddle_remember(kind="lesson").
     // A reviewer that couldn't answer in time.
     const slow = new Set(r.events.filter((e) => e.type === "reviewed" && e.skipped && /time/i.test(String(e.notes ?? ""))).map((e) => agentBase(String(e.agent))));
     for (const who of slow)

package/dist/orchestrator/planner.js

@@ -5,6 +5,29 @@
 import { brainFrom, repoContext } from "./brain.js";
 import { linkPlan, parseContextIds } from "../room/context.js";
 import { carryGoal } from "./goal.js";
+/** The JSON fields the planner asks for, in both plan shapes. */
+const PLAIN_FIELDS = `"plain":"one or two short sentences a non-programmer understands: what the finished thing is and what it lets them do (no jargon: no exit codes, modules, ESM)","example":"one concrete example of using it and what you'd see, e.g. todo add milk → added: milk (or \"\" if there's nothing to show)"`;
+/** The plain summary from a plan reply, if the planner wrote one. */
+export function parsePlain(text) {
+    for (const body of jsonCandidates(text)) {
+        let raw;
+        try {
+            raw = JSON.parse(body);
+        }
+        catch {
+            continue;
+        }
+        if (!Array.isArray(raw?.tasks))
+            continue;
+        const tidy = (x, n) => (typeof x === "string" ? x.replace(/\s+/g, " ").trim().slice(0, n) : "");
+        const what = tidy(raw.plain ?? raw.summary, 400);
+        if (!what)
+            return undefined;
+        const example = tidy(raw.example, 200);
+        return example ? { what, example } : { what };
+    }
+    return undefined;
+}
 /**
  * Fallback when no brain can plan: the whole goal as ONE task. (It used to be
  * a scaffold → UI → logic → tests → review spine; seen live, a planner hiccup
@@ -67,9 +90,9 @@ ${council ? `- contract: the exact names tasks share — files/modules and the t
 You have no tools in this step and cannot read files: the snapshot above is everything. Do not try to call a tool — plan from what you see.
 Reply with ONLY this JSON, no prose, no code fences:
 ${council
-        ? `{"tasks":[{"title":"short imperative title","spec":"...","files":["path"],"prefers":["tag"],"depends_on":[0],"from":"the ONE agent id whose idea this task mainly implements","with":["other agent ids whose ideas it also uses"]}],"decisions":["a key design decision every agent must follow (max 6)"],"risks":[{"risk":"a risk or flaw to watch while building (max 6)","by":"agent id that flagged it"}],"contract":"markdown"}
+        ? `{"tasks":[{"title":"short imperative title","spec":"...","files":["path"],"prefers":["tag"],"depends_on":[0],"from":"the ONE agent id whose idea this task mainly implements","with":["other agent ids whose ideas it also uses"]}],"decisions":["a key design decision every agent must follow (max 6)"],"risks":[{"risk":"a risk or flaw to watch while building (max 6)","by":"agent id that flagged it"}],"contract":"markdown",${PLAIN_FIELDS}}
 "from" and "with" use only these ids: ${council.members.join(", ")}.`
-        : `{"tasks":[{"title":"short imperative title","spec":"...","files":["path"],"prefers":["tag"],"depends_on":[0]}]}`}`;
+        : `{"tasks":[{"title":"short imperative title","spec":"...","files":["path"],"prefers":["tag"],"depends_on":[0]}],${PLAIN_FIELDS}}`}`;
 }
 /** Candidate JSON bodies in a reply: fenced blocks first, then brace-to-brace. */
 export function jsonCandidates(text) {
@@ -143,13 +166,17 @@ export async function planGoal(goal, crew, repoRoot, opts = {}) {
         if (tasks && opts.project && tasks.length > 1) {
             // A project's specs carry the goal's exact requirements too, as the council's do (goal.ts).
             const carried = carryGoal(goal, tasks);
-            return { tasks: carried.tasks, by: brain.label, ms, tokens: res.tokens, goalCheck: carried.check };
+            return { tasks: carried.tasks, by: brain.label, ms, tokens: res.tokens, goalCheck: carried.check, ...withPlain(res.text) };
         }
         if (tasks)
-            return { tasks, by: brain.label, ms, tokens: res.tokens };
+            return { tasks, by: brain.label, ms, tokens: res.tokens, ...withPlain(res.text) };
     }
     return { tasks: templatePlan(goal), by: "template", note: `${brain.label} didn't return a usable plan`, ms };
 }
+const withPlain = (text) => {
+    const plain = parsePlain(text);
+    return plain ? { plain } : {};
+};
 /** Materialize a plan into the Room, wiring up dependency ids correctly. */
 export function seedBoard(db, goal, planned) {
     db.createSession(goal);

package/dist/orchestrator/qa.js

@@ -276,6 +276,7 @@ export async function runQa(o) {
                 approvals: o.approvals,
                 worktree: wt,
             });
+            o.budget?.track(h.meter, h.agentId);
         }
         catch (e) {
             db.setTaskStatus(task.id, "failed");
@@ -312,7 +313,7 @@ export async function runQa(o) {
                 finished++;
                 slowest = Math.max(slowest, ms);
             }
-            db.publish("qa.done", { agent_id: w.id, task_id: task.id, payload: { round, ok: code === 0, bugs, ms } });
+            db.publish("qa.done", { agent_id: w.id, task_id: task.id, payload: { round, ok: code === 0, bugs, ms, tokens: h.meter.tokens } });
             onEvent({ type: "checked", agent: w.id, round, ok: code === 0, bugs, ms, tokens: h.meter.tokens, reason, task: task.id });
             resolve();
         };
@@ -323,6 +324,13 @@ export async function runQa(o) {
     const prev = room.bugs;
     try {
         for (round = 1; round <= rounds && !signal?.aborted; round++) {
+            if (o.budget?.stopping) {
+                result.budget = true;
+                const reason = `the token budget is nearly spent — QA round ${round} not started`;
+                db.publish("qa.skipped", { payload: { round, reason } });
+                onEvent({ type: "skipped", reason });
+                break;
+            }
             roundBugs = 0;
             finished = 0;
             slowest = 0;