huddle-cli 0.1.1 → 0.1.5

package/dist/mcp/context-tools.js

@@ -54,6 +54,8 @@ export function contextTools(room) {
  * machines (a teammate's agent) are saved here and replaced by a local path.
  */
 export function toContent(result) {
+    if (typeof result === "string")
+        return [{ type: "text", text: result }];
     if (!result || typeof result !== "object" || Array.isArray(result))
         return [{ type: "text", text: JSON.stringify(result, null, 2) }];
     const { image, file, ...rest } = result;

package/dist/mcp/server.js

@@ -141,6 +141,24 @@ const TOOLS = [
         },
         handler: (a) => room("/ask", "POST", { question: a.question, to: a.to }),
     },
+    {
+        name: "huddle_ask_user",
+        description: "Ask the USER (the person this work is for) to decide something BIG that the goal doesn't settle: a choice that changes what they get " +
+            "(scope, a feature in or out, a user-visible behavior, an irreversible step, real money or data). NOT for names, file layout, code style " +
+            "or anything you or a teammate can decide — the user isn't an engineer and sees many agents. Give 2-4 short options in plain words " +
+            "(no jargon), the one you recommend FIRST; they may also answer in their own words. Waits a short while; with no answer, go with option 1. " +
+            "At most 2 per run.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                question: { type: "string", description: "one plain sentence, e.g. 'Should it also convert Rankine?'" },
+                options: { type: "array", items: { type: "string" }, description: "2-4 plain-words options, your recommendation first" },
+                why: { type: "string", description: "optional: one line on what changes for them either way" },
+            },
+            required: ["question", "options"],
+        },
+        handler: (a) => room("/ask_user", "POST", { question: a.question, options: a.options, why: a.why }),
+    },
     {
         name: "huddle_send",
         description: "Message a teammate agent directly: a heads-up ('I renamed X to Y'), an interface you're exposing, or an answer to their question (pass reply_to = the question's id). `to` = an agent id from huddle_peers, a task id, \"all\" for everyone working now, or \"huddle\" to answer Huddle itself. They see it the next time they call any huddle tool.",
@@ -239,10 +257,12 @@ export const PLUG_INSTRUCTIONS = `Huddle: you are one of several AI coding agent
 - Start: huddle_board (the plan and who is doing what), huddle_recall (shared memory: decisions, contracts, the design council's notes: huddle_recall "council"), huddle_peers, huddle_inbox.
 - Before editing: huddle_announce_plan (what you will touch), huddle_check_overlap (is someone else in that file), huddle_contract (the exact names tasks share).
 - Names other tasks use: code to the contract verbatim. Never invent one that isn't in it — huddle_amend_contract(section, change, why) first; it tells every teammate.
+- The user: messages whose sender is "the user" come from the person this work is for — they win over the plan and the contract. A big decision the goal doesn't settle (scope, user-visible behavior, anything irreversible): huddle_ask_user with 2-4 plain options, your pick first. Never for names or code style.
 - While working: huddle_progress (a short note; the reply shows the team's in-flight work), huddle_remember (a decision or contract others need; kind "lesson" is kept for future runs), huddle_send (message one teammate), huddle_ask (ask a teammate or the brain a question), huddle_inbox (read replies).
 - Sharing work: when huddle_offer_help reaches you, huddle_split hands part of your task to a free agent; huddle_take_backlog picks up the next task; huddle_claim takes a specific one.
 - QA rounds: huddle_report_bug files one reproducible bug in the merged build; it becomes a fix task for the file's author.
 - The shared screen (what the user pasted, dropped or uploaded — logs, docs, screenshots): huddle_context lists it, huddle_context_read opens one item in chunks (images/PDFs as a file path), huddle_context_search finds text in it, huddle_context_note pins a comment on an item for everyone.
+- Connectors: tools named github_*, atlassian_*, linear_*… (when listed) reach the team's outside tools — issues, tickets, docs, CI. When the goal names an issue or ticket, read it (and its comments) before you start. Post or change things there only when your task asks for it.
 - Finish: huddle_done with a short summary. Huddle tests and merges it.`;
 /** The Plug's verb names, in the order listed to agents. */
 export const PLUG_VERBS = TOOLS.map((t) => t.name);
@@ -251,13 +271,32 @@ export async function runPlug() {
     if (process.env.HUDDLE_LIVE)
         return (await import("../attach/plug.js")).runLivePlug();
     const server = new Server({ name: "huddle", version: packageInfo().version }, { capabilities: { tools: {} }, instructions: PLUG_INSTRUCTIONS });
+    // Connectors (GitHub, Jira, …) the Room runs for this session, after Huddle's own verbs.
+    let extra = null;
+    const connectorTools = async () => {
+        if (extra)
+            return extra;
+        try {
+            const r = await room("/tools", "GET");
+            extra = Array.isArray(r?.tools) ? r.tools : [];
+        }
+        catch {
+            extra = [];
+        }
+        return extra;
+    };
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: TOOLS.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })),
+        tools: [...TOOLS.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })), ...(await connectorTools())],
     }));
     server.setRequestHandler(CallToolRequestSchema, async (req) => {
         const tool = TOOLS.find((t) => t.name === req.params.name);
-        if (!tool)
-            throw new Error(`unknown tool: ${req.params.name}`);
+        if (!tool) {
+            if (!(await connectorTools()).some((t) => t.name === req.params.name))
+                throw new Error(`unknown tool: ${req.params.name}`);
+            const r = await room("/tool", "POST", { name: req.params.name, arguments: req.params.arguments ?? {} });
+            const result = r?.result ?? r;
+            return { content: toContent(result), isError: !!(result && typeof result === "object" && "error" in result) };
+        }
         const result = await tool.handler((req.params.arguments ?? {}));
         return { content: toContent(result) };
     });

package/dist/orchestrator/brain.js

@@ -123,7 +123,9 @@ export function repoContext(cwd, maxFiles = 250) {
             return null;
         }
     };
-    const parts = [`FILES (${files.length}${files.length > maxFiles ? `, first ${maxFiles}` : ""}):\n${files.slice(0, maxFiles).join("\n") || "(empty repo)"}`];
+    // Found live (0.1.2): agents set "engines": {"node": ">=22"} on a machine with Node 20.
+    const machine = `MACHINE: ${process.platform === "darwin" ? "macOS" : process.platform === "win32" ? "Windows" : "Linux"}, Node ${process.version}. Target what runs here: never require a newer Node (engines, syntax, built-in APIs) than this.`;
+    const parts = [machine, `FILES (${files.length}${files.length > maxFiles ? `, first ${maxFiles}` : ""}):\n${files.slice(0, maxFiles).join("\n") || "(empty repo)"}`];
     for (const f of ["package.json", "pyproject.toml", "Cargo.toml", "go.mod"]) {
         const h = head(f, 40);
         if (h)

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,8 +368,11 @@ 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 context = repoContext(repoRoot, 150) + (opts.outside ? `\n\n${opts.outside}` : "");
     const ids = members.map((m) => m.id);
     const result = (extra) => ({
         members: ids,
@@ -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) {
@@ -124,7 +147,7 @@ export async function planGoal(goal, crew, repoRoot, opts = {}) {
     const brain = opts.brain ?? brainFrom("claude");
     if (!brain)
         return { tasks: templatePlan(goal), by: "template", note: "no brain available" };
-    const prompt = plannerPrompt(goal, crew, repoContext(repoRoot), undefined, { project: opts.project });
+    const prompt = plannerPrompt(goal, crew, repoContext(repoRoot) + (opts.outside ? `\n\n${opts.outside}` : ""), undefined, { project: opts.project });
     let ms = 0;
     for (let attempt = 0; attempt < 2 && !opts.signal?.aborted; attempt++) {
         const res = await brain.think(prompt, repoRoot, {
@@ -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);