huddle-cli 0.0.0-stage → 0.1.1

package/dist/orchestrator/planner.js

@@ -0,0 +1,212 @@
+// The planner turns one goal into a task graph sized to the goal and to the
+// crew. An agent (read-only, in the repo) writes the plan; if that fails for
+// any reason we fall back to a small deterministic template so a run never
+// blocks on planning.
+import { brainFrom, repoContext } from "./brain.js";
+import { linkPlan, parseContextIds } from "../room/context.js";
+import { carryGoal } from "./goal.js";
+/**
+ * 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
+ * turned "add two shape modules" into five tasks, and an agent built a UI
+ * nobody asked for. One honest task beats an invented plan.)
+ */
+export function templatePlan(goal) {
+    const title = goal.length > 72 ? goal.slice(0, 71).replace(/\s+\S*$/, "") + "…" : goal;
+    return [{ title, spec: goal, prefers: [] }];
+}
+const TAGS = ["frontend", "design", "product", "refactor", "systems", "algorithms", "backend", "research", "breadth", "docs", "data", "quickfix"];
+/**
+ * How big the plan should be. A change: as few tasks as it takes. A project
+ * (a big goal, see goalSize): enough tasks to keep every agent busy for the
+ * whole run. Found live on the capstone: with only "size the plan to the
+ * goal" and "up to <crew> tasks at once", the council's plan for a whole app
+ * was 5 big tasks, 2 of them startable, so one of three agents sat idle at the
+ * start and nobody could merge more than two.
+ */
+export function sizeRules(crew, project) {
+    if (!project)
+        return `- Size the plan to the goal. A one-line change is ONE task. Never pad.
+- Maximize parallelism: as many tasks as possible (up to ${crew}) should be startable immediately, with no depends_on.`;
+    const lo = Math.max(2, crew * 2);
+    const hi = Math.min(MAX_TASKS, Math.max(lo + 2, crew * 4));
+    return `- This is a whole project for ${crew} agent${crew === 1 ? "" : "s"}, not a change: plan ${lo}-${hi} tasks, so every agent keeps working for the whole run and finishes 2+ tasks. Each task is one coherent module or feature with its own tests, small enough for one agent in about 10 minutes. Don't bundle two modules into one task, and don't pad.
+- At least ${crew} tasks must be startable immediately, with no depends_on: a module whose contract is written into the specs (exports, data shapes, exact messages) can be built and tested in parallel with its consumers.`;
+}
+export function plannerPrompt(goal, crew, context, council, opts = {}) {
+    return `You are the planner for Huddle, which runs several AI coding agents on one repo at the same time.
+Each task runs in its own git worktree; finished tasks are tested and merged into main.
+
+GOAL: ${goal}
+
+CREW (${crew.length} agents, all available now): ${[...new Set(crew.map((c) => c.id.split("#")[0]))]
+        .map((id) => {
+        const n = crew.filter((c) => c.id.split("#")[0] === id).length;
+        const a = crew.find((c) => c.id.split("#")[0] === id);
+        return `${id}${n > 1 ? ` ×${n}` : ""} (good at: ${a.prefers.join(", ")})`;
+    })
+        .join("; ")}
+
+REPO SNAPSHOT:
+${context}
+
+${council ? `${council.notes}
+
+` : ""}Plan from this snapshot${council ? " and the council's proposals and cross-reviews: build on the ideas teammates ADOPTed, fix every FLAW they found, and cover what they said was missing" : ""}. Split the goal into tasks. Rules:
+${sizeRules(crew.length, opts.project ?? !!council)}
+- Avoid a "scaffold first" bottleneck: if tasks share an interface, define it in each task's spec (exact function names, file paths, data shapes) so they can be built in parallel against that contract.
+- Parallel tasks should own disjoint files. List each task's files — every file it will edit, including shared ones it must touch (an index/registry/router that re-exports modules, package.json, a config). If two tasks must edit the same file, list it on both: Huddle then runs them one after the other, or merges both edits safely.
+- Never write "do not edit/touch <file>" in a spec to keep tasks apart: if the repo's tests or structure need a shared file changed (e.g. a test that every module is re-exported from an index), the task needs it — an agent that obeys the ban leaves the tests red and the task fails. List the file on each task that needs it instead.
+- Use depends_on only when a task truly needs another task's merged code.
+- Each spec must be self-contained: what to build, where, the contract, and how to verify it.
+- Carry the goal's exact requirements VERBATIM into the spec of every task that implements them: each exact output line, error message, format, number and edge-case rule (quoting, blank lines, bad rows, defaults, exit codes, stdout vs stderr), word for word — never paraphrased or shortened. Never invent a different message or output for a case the goal already gives one: a missing required input gets the goal's own error (e.g. "<field> is required"), not a generic usage error.
+- Consistency: different agents write each task, so start EVERY spec with the same one-line "Conventions:" (language/module system, formatting such as semicolons and quotes, test runner and test file naming). Take them from the existing code; if the repo is empty, choose them once and repeat them verbatim.
+- prefers: 1-3 tags from: ${TAGS.join(", ")}.
+${council ? `- contract: the exact names tasks share — files/modules and the task that owns each, exported functions with signatures, data types with field names, CLI flags, routes, error strings (the goal's exact strings, copied), test helpers. Markdown, under 3000 characters. Every spec uses these names verbatim. The contract adds names the goal leaves open; it never overrides what the goal states.
+` : ""}
+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"}
+"from" and "with" use only these ids: ${council.members.join(", ")}.`
+        : `{"tasks":[{"title":"short imperative title","spec":"...","files":["path"],"prefers":["tag"],"depends_on":[0]}]}`}`;
+}
+/** Candidate JSON bodies in a reply: fenced blocks first, then brace-to-brace. */
+export function jsonCandidates(text) {
+    const out = [];
+    for (const m of text.matchAll(/```(?:json)?\s*([\s\S]*?)```/g))
+        out.push(m[1]);
+    const end = text.lastIndexOf("}");
+    for (let i = text.indexOf("{"); i >= 0 && i < end; i = text.indexOf("{", i + 1))
+        out.push(text.slice(i, end + 1));
+    return out;
+}
+/** The most tasks a plan may have; a longer reply is not a plan. */
+export const MAX_TASKS = 20;
+/** A council task's idea credit: "from" is one primary id (or, from older prompts, a list), "with" the contributors. */
+function ideaFrom(t) {
+    const primary = typeof t.from === "string" ? [t.from] : Array.isArray(t.from) ? t.from.map(String) : [];
+    const from = [...new Set([...primary, ...(Array.isArray(t.with) ? t.with.map(String) : [])].map((x) => x.trim()).filter(Boolean))];
+    return from.length ? { from } : {};
+}
+/** Pull a {"tasks": [...]} plan out of a model's reply, however it was wrapped. */
+export function parsePlan(text) {
+    for (const body of jsonCandidates(text)) {
+        let raw;
+        try {
+            raw = JSON.parse(body);
+        }
+        catch {
+            continue;
+        }
+        // A from-scratch project (the capstone's brief) honestly needs 10-14 tasks; 12 used to throw such a plan away.
+        if (!Array.isArray(raw?.tasks) || raw.tasks.length === 0 || raw.tasks.length > MAX_TASKS)
+            continue;
+        const titles = raw.tasks.map((t) => String(t?.title ?? "").trim());
+        if (titles.some((t) => !t))
+            continue;
+        // depends_on may come back as indices (0- or 1-based is ambiguous, we use 0) or as titles.
+        const toIndex = (d) => (typeof d === "number" ? d : titles.indexOf(String(d).trim()));
+        return raw.tasks.map((t, i) => ({
+            title: titles[i].slice(0, 120),
+            spec: String(t.spec ?? ""),
+            files: Array.isArray(t.files) ? t.files.map(String) : [],
+            prefers: Array.isArray(t.prefers) ? t.prefers.map(String) : [],
+            ...ideaFrom(t),
+            ...(parseContextIds(t.context).length ? { context: parseContextIds(t.context) } : {}),
+            // only backward edges → guaranteed acyclic
+            depends_on: (Array.isArray(t.depends_on) ? t.depends_on : []).map(toIndex).filter((d) => Number.isInteger(d) && d >= 0 && d < i),
+        }));
+    }
+    return null;
+}
+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 });
+    let ms = 0;
+    for (let attempt = 0; attempt < 2 && !opts.signal?.aborted; attempt++) {
+        const res = await brain.think(prompt, repoRoot, {
+            signal: opts.signal,
+            // A plan takes ~6–15s on a cloud model; a call that hangs is retried
+            // instead of eating the whole budget (seen live: 4m30s, then the
+            // fallback). Local models and Opus (the default brain) are slower.
+            timeoutMs: brain.spec.startsWith("ollama") || brain.spec === "claude" || brain.spec.endsWith(":opus") ? 4 * 60_000 : 2 * 60_000,
+            json: true,
+            // The snapshot is in the prompt; exploring just costs time. If that
+            // first answer isn't a plan, the retry may read the repo (read-only).
+            selfContained: attempt === 0,
+        });
+        ms += res.ms;
+        const tasks = res.ok ? parsePlan(res.text) : null;
+        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 };
+        }
+        if (tasks)
+            return { tasks, by: brain.label, ms, tokens: res.tokens };
+    }
+    return { tasks: templatePlan(goal), by: "template", note: `${brain.label} didn't return a usable plan`, ms };
+}
+/** Materialize a plan into the Room, wiring up dependency ids correctly. */
+export function seedBoard(db, goal, planned) {
+    db.createSession(goal);
+    const ids = [];
+    for (const p of planned) {
+        const deps = (p.depends_on ?? []).map((i) => ids[i]).filter(Boolean);
+        // Found live (registry eval): "Files you own" read as a fence — two agents
+        // left npm test red rather than add their line to an unlisted src/index.js.
+        const spec = p.files?.length
+            ? `${p.spec}\n\nPlanned files: ${p.files.join(", ")} (if the work needs another file too, announce it with huddle_announce_plan and edit it — a passing test suite beats any "don't touch" above)`
+            : p.spec;
+        // files also go to the scheduler: two tasks that share one never run at once.
+        const task = db.addTask({ title: p.title, spec, prefers: p.prefers, depends_on: deps, files: p.files });
+        ids.push(task.id);
+    }
+    // Shared-screen items the planner tied to each task ride in that task's prompt.
+    linkPlan(db, ids, planned);
+    return ids;
+}
+/** "(1) … (2) …", "1. … 2. …" or "three tasks": the user already split the work. */
+const LISTS_TASKS = /\b(one|two|three|four|five|six|\d+) (separate |independent )?tasks?\b|\btask \d\b/i;
+export function listsOwnTasks(goal) {
+    const numbered = (goal.match(/\(\d+\)|(^|\n)\s*\d+[.)]\s/g) ?? []).length;
+    return numbered >= 2 || LISTS_TASKS.test(goal);
+}
+const FROM_SCRATCH = /\bfrom (scratch|the ground up|zero)\b|\bgreenfield\b|\bnew (project|app|application|product)\b|\bend[- ]to[- ]end\b|\bfull[- ]stack\b|\b(an? )?mvp\b|\bwhole (app|project|product|system)\b/i;
+const NOUNS = "app|application|game|website|web ?app|site|service|backend|frontend|api|cli|tool|platform|dashboard|project|system|clone|bot|server|compiler|interpreter|engine";
+const BUILD_A = new RegExp(`\\b(?:(?:build|develop)\\s+(?:me\\s+)?(?:an?|the)|(?:create|make|write)\\s+(?:me\\s+)?an?)\\s+(?:[\\w-]+\\s+){0,4}?(?:${NOUNS})\\b`, "i");
+/**
+ * Is this a big goal — a project, not a change? Big goals get the heavier team
+ * phases (a design council before, a QA round after); small goals keep the
+ * fast path. ONE heuristic so the phases agree. Big: "from scratch / end to
+ * end / full-stack / MVP", "build a <something> app/game/site/API/CLI…", 5+
+ * listed items, or a plan of 5+ tasks. Then, unless the goal already spells
+ * out its own few tasks (the eval goals: "Three tasks. (1) … (2) …"), a long
+ * goal (600+ chars) or a real goal (120+ chars) in a (nearly) empty repo.
+ */
+export function goalSize(goal, opts = {}) {
+    if (FROM_SCRATCH.test(goal))
+        return { big: true, why: "a from-scratch project" };
+    if (BUILD_A.test(goal))
+        return { big: true, why: "a new project to build" };
+    const items = goal.split("\n").filter((l) => /^\s*([-*•]|\d+[.)])\s+\S/.test(l)).length;
+    const inline = (goal.match(/\(\d+\)/g) ?? []).length;
+    if (Math.max(items, inline) >= 5)
+        return { big: true, why: "a spec of 5+ items" };
+    if ((opts.tasks ?? 0) >= 5)
+        return { big: true, why: `a plan of ${opts.tasks} tasks` };
+    if (listsOwnTasks(goal))
+        return { big: false, why: "the goal already lists its tasks" };
+    if (goal.length >= 600)
+        return { big: true, why: "a long goal" };
+    if ((opts.repoFiles ?? Infinity) <= 3 && goal.length >= 120)
+        return { big: true, why: "a new project in an empty repo" };
+    return { big: false, why: "a small goal" };
+}
+export function isBigGoal(goal, opts = {}) {
+    return goalSize(goal, opts).big;
+}
+//# sourceMappingURL=planner.js.map

package/dist/orchestrator/qa.js

@@ -0,0 +1,398 @@
+// QA: the team re-checks its own build. After every planned task has merged,
+// an agent that did NOT write the code (rotating between rounds) checks the
+// integrated main in a fresh worktree: runs the whole test suite, uses the
+// thing the way the goal says a user would, and reads the diff for flaws.
+// Every concrete bug it files with huddle_report_bug becomes a fix task on
+// the board, routed to the agent that wrote those files ("@<agent>" in its
+// prefers — the scheduler gives it to them first, else to anyone free), with
+// the repro (and a regression test, when the QA agent wrote one) in the spec.
+// Fixes go through the normal pipeline: worktree, tests, cross-review, merge.
+// Then QA runs again — up to `rounds` times, or until a round comes back clean.
+//
+// QA agents never land anything themselves: their worktree is thrown away.
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { launchAgent, stopChild } from "./launcher.js";
+import { createWorktree, removeWorktree } from "../sandbox/worktree.js";
+import { onFinished } from "../platform.js";
+import { isBigGoal } from "./planner.js";
+import { acceptanceList } from "./goal.js";
+export const QA_ROUNDS = 2;
+/** Bugs one round may file — QA should report the serious ones, not a wishlist. */
+export const QA_MAX_BUGS = 6;
+const QA_TIMEOUT_MS = 15 * 60_000;
+/**
+ * A first clean round ends QA only if its check took at least this long
+ * (HUDDLE_QA_MIN_CLEAN_S overrides); a quicker one gets a second opinion from
+ * another agent. Found live (capstone round 5): cursor's round-1 check came
+ * back clean in 90s, QA stopped there, and 2 of the hidden checks failed
+ * on bugs a goal-by-goal check would have hit at once.
+ */
+export function qaMinCleanMs() {
+    const s = Number(process.env.HUDDLE_QA_MIN_CLEAN_S);
+    return Number.isFinite(s) && s >= 0 ? s * 1000 : 5 * 60_000;
+}
+/**
+ * QA on or off for this goal: an explicit --qa / --no-qa wins; otherwise on
+ * for big goals (the same heuristic as the design council), off for small
+ * ones, and never in plan-only mode.
+ */
+export function shouldQa(goal, o = {}) {
+    if (o.planOnly)
+        return false;
+    if (o.flag !== undefined)
+        return o.flag;
+    return isBigGoal(goal, { tasks: o.tasks, repoFiles: o.repoFiles });
+}
+function git(cwd, args) {
+    try {
+        return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 32 * 1024 * 1024 }).trim();
+    }
+    catch {
+        return "";
+    }
+}
+const cap = (s, n) => (s.length > n ? s.slice(0, n) + "…" : s);
+const str = (v, n) => cap(String(v ?? "").trim(), n);
+/** A title cut at a word, not mid-word (found live: "… and counts i…"). */
+const capWords = (s, n) => {
+    if (s.length <= n)
+        return s;
+    const cut = s.slice(0, n);
+    const sp = cut.lastIndexOf(" ");
+    return (sp > n * 0.6 ? cut.slice(0, sp) : cut).replace(/[\s,;:—-]+$/, "") + "…";
+};
+/** Who wrote each file since `since`: the newest `huddle(<agent>): …` commit that touched it. */
+export function authorsOf(repoRoot, since, files) {
+    const out = new Map();
+    for (const f of files) {
+        const subjects = git(repoRoot, ["log", "--format=%s", `${since}..HEAD`, "--", f]).split(/\r?\n/);
+        const who = subjects.map((s) => /^huddle\(([^)]+)\): /.exec(s)?.[1]).find(Boolean);
+        if (who)
+            out.set(f, who);
+    }
+    return out;
+}
+/** Every agent with a merged commit since `since`. */
+function authorsSince(repoRoot, since) {
+    const n = new Map();
+    for (const s of git(repoRoot, ["log", "--format=%s", `${since}..HEAD`]).split(/\r?\n/)) {
+        const who = /^huddle\(([^)]+)\): /.exec(s)?.[1];
+        if (who)
+            n.set(who, (n.get(who) ?? 0) + 1);
+    }
+    return n;
+}
+const STOP = new Set(["the", "a", "an", "is", "are", "of", "in", "on", "to", "for", "and", "or", "with", "when", "it", "its", "not", "no", "does", "doesn't", "dont", "don't", "be", "by", "at", "fails", "fail", "bug", "broken", "wrong"]);
+const words = (s) => new Set(s.toLowerCase().replace(/[^\w\s.-]/g, " ").split(/\s+/).filter((w) => w.length > 1 && !STOP.has(w)));
+/** Same bug, reported twice? Close titles in the same place (or no place given). Same words in different files = two bugs. */
+export function sameBug(a, b) {
+    const x = words(a.title);
+    const y = words(b.title);
+    const inter = [...x].filter((w) => y.has(w)).length;
+    const jac = inter / Math.max(1, new Set([...x, ...y]).size);
+    const sharedFiles = a.files.some((f) => b.files.includes(f));
+    const noPlace = !a.files.length || !b.files.length;
+    return jac >= 0.4 && (sharedFiles || noPlace);
+}
+/**
+ * Task id -> who cross-reviewed it (a review that ran, not one skipped on a
+ * time-out), from the scheduler's run.reviewed events. Found live (capstone
+ * round 3): 4 of 10 tasks merged unreviewed because no agent was free at the
+ * time, and QA's brief didn't say which — so QA read all of it equally.
+ */
+function reviewersOf(db) {
+    const out = new Map();
+    for (const ev of db.eventsOfType(["run.reviewed"], 0, 1000)) {
+        try {
+            const p = JSON.parse(ev.payload || "{}");
+            const task = p.task ?? ev.task_id;
+            if (task && p.agent && !p.skipped)
+                out.set(task, p.agent);
+        }
+        catch {
+            /* a malformed event never breaks QA */
+        }
+    }
+    return out;
+}
+function qaPrompt(o) {
+    return `QA CHECK — round ${o.round}. This task is a check, not a change: nothing you edit here lands.
+The team just built this goal, and every planned task has merged into main:
+GOAL: ${o.goal}
+
+Your current directory is a fresh checkout of the integrated main.${o.author ? "" : " You did NOT write this code — look at it with fresh eyes."}
+
+WHAT WAS MERGED (task · agent):
+${o.tasks || "(none)"}
+
+FILES CHANGED:
+${o.stat || "(none)"}
+
+THE DIFF (capped):
+${o.diff || "(empty)"}
+${o.checklist ? `\nACCEPTANCE CHECKLIST — the GOAL's requirements, one by one:\n${o.checklist}\n` : ""}${o.earlier.length ? `\nALREADY REPORTED in earlier rounds (their fixes merged or are in flight) — report one again only if it is STILL broken:\n${o.earlier.map((b) => `- ${b.title}${b.files.length ? ` (${b.files.join(", ")})` : ""}`).join("\n")}\n` : ""}
+The GOAL is the spec you check against. The team's contract (HUDDLE_CONTRACT.md), README, task specs and tests are NOT: where any of them says something the goal doesn't, the goal wins, and code that follows them instead is a bug (e.g. a generic "invalid arguments" error where the goal gives an exact message for that case). Passing tests prove only what their authors thought of.
+
+DO, in order (huddle_progress after each step):
+1. Run the full test suite: ${o.testCmd ? `\`${o.testCmd}\`` : "(no test command detected — look for one, or skip)"}.
+2. Go through the ACCEPTANCE CHECKLIST item by item: run the app / CLI / API the way a user would and compare the output with the goal byte for byte. For each item use the smallest input that triggers it, and its edge cases:
+   - every exact error message: trigger it with the input left out entirely (no argument, no flag, no field) AND given but empty or invalid; check the stream (stdout vs stderr), the exit code and the HTTP status
+   - every parser / import rule: special characters inside a quoted field AND inside an unquoted one, escapes, blank lines, extra or missing fields, rows that must be skipped, and the exact counts
+   - every exact output format: spacing, ordering, the empty case, the final newline
+3. Read the diff for flaws: bugs, modules from different agents that don't fit together, missing requirements, crashes.
+   Start with the tasks marked NOT reviewed above: nobody but their author has read that code.
+4. For EACH concrete, reproducible defect: huddle_report_bug(title, repro, expected, actual, files).
+   - When a test can show it, write a regression test in this repo's test style that FAILS now (and will pass once fixed),
+     then pass its path as test_file — the fix task gets it. Don't fix the bug yourself.
+   - Only real defects, at most ${o.maxBugs}, most serious first. No style nits, no "nice to have".
+5. huddle_done(task_id, summary): which checklist items you ran, and "N bugs filed" or "clean".
+Don't commit. If everything works, say so — but only after every checklist item was run.`;
+}
+export async function runQa(o) {
+    const { db, room, repoRoot, signal, onEvent } = o;
+    const rounds = o.rounds ?? QA_ROUNDS;
+    const maxBugs = o.maxBugs ?? QA_MAX_BUGS;
+    const result = { rounds: 0, bugs: 0, fixed: 0, failed: 0, clean: false, stopped: false };
+    const filed = [];
+    const used = new Map(); // QA agent -> rounds it checked (rotation)
+    const qaTasks = new Set(); // QA's own board tasks, never fix tasks
+    const local = o.workers.filter((w) => w.adapter);
+    if (!local.length) {
+        onEvent({ type: "skipped", reason: "no agent on this machine can run QA" });
+        return result;
+    }
+    // Who checks this round: someone who didn't write the code, rotating; an
+    // author only when everyone wrote some (fewest commits first).
+    // After a quick clean round, the second opinion comes from someone else (when there is anyone).
+    let secondOpinion = new Set();
+    const pick = () => {
+        const wrote = authorsSince(repoRoot, o.startHead);
+        const others = local.filter((w) => !secondOpinion.has(w.id));
+        return (others.length ? others : local)
+            .map((w, i) => ({ w, i, author: wrote.has(w.id), n: wrote.get(w.id) ?? 0, u: used.get(w.id) ?? 0 }))
+            .sort((a, b) => Number(a.author) - Number(b.author) || a.u - b.u || a.n - b.n || a.i - b.i)
+            .slice(0, Math.max(1, o.perRound ?? 1))
+            .map(({ w, author }) => ({ w, author }));
+    };
+    const worktrees = new Map(); // QA agent -> its worktree (to read a test_file)
+    const checklist = acceptanceList(o.goal);
+    const minCleanMs = o.minCleanMs ?? qaMinCleanMs();
+    let cleanRounds = 0;
+    let slowest = 0; // the longest finished check in this round
+    let round = 0;
+    let roundBugs = 0;
+    let finished = 0; // checks in this round that ran to the end
+    /** huddle_report_bug while a round runs: validate, dedupe, cap, file a routed fix task. */
+    const onBug = (raw, from) => {
+        const title = capWords(String(raw.title ?? "").trim().replace(/\s+/g, " "), 120);
+        const repro = str(raw.repro, 2000);
+        if (!title || !repro)
+            return { ok: false, error: "title and repro are required — exact steps or a command that shows the bug" };
+        const files = (Array.isArray(raw.files) ? raw.files : []).map((f) => str(f, 300).replace(/^\.\//, "")).filter(Boolean).slice(0, 20);
+        const me = { title, files };
+        // Same as one already filed: in this round, or an earlier one whose fix hasn't landed.
+        const dup = filed.find((b) => sameBug(b, me) && (b.round === round || db.getTask(b.task)?.status !== "merged"));
+        if (dup) {
+            db.publish("qa.duplicate", { agent_id: from, task_id: dup.task, payload: { round, by: from, title, of: dup.task } });
+            onEvent({ type: "duplicate", agent: from, round, title, of: dup.title });
+            return { ok: true, duplicate_of: dup.task, note: `Already filed as "${dup.title}" — not filed again.` };
+        }
+        if (roundBugs >= maxBugs)
+            return { ok: false, error: `this round already filed ${maxBugs} bugs (the cap) — finish with huddle_done` };
+        const reopened = filed.find((b) => sameBug(b, me));
+        // Regression test: the code, or the file the QA agent wrote in its worktree.
+        let testFile = raw.test_file ? str(raw.test_file, 300).replace(/^\.\//, "") : "";
+        let testCode = raw.test_code ? String(raw.test_code).slice(0, 20_000) : "";
+        const wt = worktrees.get(from);
+        if (testFile && !testCode && wt) {
+            const abs = path.resolve(wt, testFile);
+            if (abs.startsWith(wt + path.sep) && fs.existsSync(abs))
+                testCode = fs.readFileSync(abs, "utf8").slice(0, 20_000);
+        }
+        if (testCode && !testFile)
+            testFile = "(pick a path in this repo's test style)";
+        // Route to the author of most of these files; nobody known = any free agent.
+        const counts = new Map();
+        for (const a of authorsOf(repoRoot, o.startHead, files).values())
+            counts.set(a, (counts.get(a) ?? 0) + 1);
+        const assignee = [...counts].sort((a, b) => b[1] - a[1])[0]?.[0] ?? null;
+        const spec = [
+            `Bug found by ${from} in QA round ${round} of the goal: ${cap(o.goal.replace(/\s+/g, " "), 300)}`,
+            reopened ? `(Reported again after the earlier fix "${reopened.title}" merged — it is still broken.)` : "",
+            `REPRO: ${repro}`,
+            `EXPECTED: ${str(raw.expected, 1000)}`,
+            `ACTUAL: ${str(raw.actual, 1500)}`,
+            files.length ? `WHERE: ${files.join(", ")}` : "",
+            testCode
+                ? `REGRESSION TEST (from QA — it fails on main today): add it as ${testFile} first, then fix the code so it and the whole suite pass:\n${testCode}`
+                : "Add a regression test that fails before your fix and passes after it, in this repo's test style.",
+            "Fix the root cause, not the symptom. If the report is wrong (it already works), show that with a passing test and say so in huddle_done.",
+        ]
+            .filter(Boolean)
+            .join("\n");
+        const task = db.addTask({
+            title: capWords(`Fix: ${title}`, 120),
+            spec,
+            prefers: ["quickfix", ...(assignee ? [`@${assignee}`] : [])],
+            files: [...files, ...(testCode && !testFile.startsWith("(") ? [testFile] : [])],
+        });
+        filed.push({ task: task.id, title, files, round, by: from });
+        roundBugs++;
+        result.bugs++;
+        db.remember({ kind: "gotcha", body: `QA (${from}) found: ${title} — repro: ${cap(repro, 300)}`, why: "filed as a fix task", author: from });
+        db.publish("qa.bug", {
+            agent_id: from,
+            task_id: task.id,
+            payload: { round, by: from, title, repro: cap(repro, 500), files, assigned_to: assignee, test: !!testCode, reopened: !!reopened },
+        });
+        onEvent({ type: "bug", agent: from, round, title, task: task.id, assignedTo: assignee, files, test: !!testCode });
+        return {
+            ok: true,
+            task_id: task.id,
+            assigned_to: assignee ?? "any free agent",
+            note: `Filed as fix task ${task.id}${assignee ? `, routed to ${assignee} (wrote ${files.join(", ")})` : ""}. Keep checking; huddle_done when finished.`,
+        };
+    };
+    /** One QA agent checks main in a throwaway worktree. */
+    const check = (w, author, prompt) => new Promise((resolve) => {
+        const task = db.addTask({ title: `QA round ${round}: check the build`, spec: prompt, prefers: ["qa"] });
+        qaTasks.add(task.id);
+        db.claimTask(task.id, w.id); // claimed at once, so the fix board never picks it up
+        let wt;
+        let h;
+        try {
+            wt = createWorktree(repoRoot, w.id, task.id); // fresh off the integrated main
+            h = launchAgent({
+                repoRoot,
+                adapter: w.adapter,
+                agentId: w.id,
+                role: "worker", // it runs the suite and the app, not just reads
+                taskId: task.id,
+                taskSpec: `${task.title}\n\n${prompt}`,
+                roomUrl: room.url,
+                roomSecret: room.secret,
+                approvals: o.approvals,
+                worktree: wt,
+            });
+        }
+        catch (e) {
+            db.setTaskStatus(task.id, "failed");
+            db.setAgentStatus(w.id, "idle");
+            onEvent({ type: "checked", agent: w.id, round, ok: false, bugs: 0, ms: 0, tokens: 0, reason: `couldn't start: ${String(e?.message ?? e).slice(0, 200)}` });
+            return resolve();
+        }
+        worktrees.set(w.id, wt.path);
+        const before = roundBugsBy(w.id);
+        db.setTaskStatus(task.id, "in_progress");
+        db.setAgentStatus(w.id, "working", wt.path);
+        onEvent({ type: "start", agent: w.id, round, task: task.id, log: h.logPath, author });
+        let over = false;
+        const kill = () => stopChild(h.child);
+        const timer = setTimeout(kill, o.timeoutMs ?? QA_TIMEOUT_MS);
+        signal?.addEventListener("abort", kill);
+        const end = (code) => {
+            if (over)
+                return;
+            over = true;
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", kill);
+            const ms = Date.now() - h.startedAt;
+            db.releaseClaims(w.id);
+            db.setAgentStatus(w.id, "idle");
+            // "merged" = the check finished (a QA task lands nothing); "failed" = it didn't.
+            db.setTaskStatus(task.id, code === 0 ? "merged" : "failed");
+            removeWorktree(repoRoot, wt.path);
+            git(repoRoot, ["branch", "-D", wt.branch]);
+            worktrees.delete(w.id);
+            const bugs = roundBugsBy(w.id) - before;
+            const reason = code === 0 ? undefined : signal?.aborted ? "stopped by you" : `exited with code ${code}`;
+            if (code === 0) {
+                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 } });
+            onEvent({ type: "checked", agent: w.id, round, ok: code === 0, bugs, ms, tokens: h.meter.tokens, reason, task: task.id });
+            resolve();
+        };
+        // Its last stdout lines (token usage) can still be in the pipe at 'exit'.
+        onFinished(h.child, end);
+    });
+    const roundBugsBy = (id) => filed.filter((b) => b.round === round && b.by === id).length;
+    const prev = room.bugs;
+    try {
+        for (round = 1; round <= rounds && !signal?.aborted; round++) {
+            roundBugs = 0;
+            finished = 0;
+            slowest = 0;
+            result.rounds = round;
+            const who = pick();
+            secondOpinion = new Set();
+            who.forEach(({ w }) => used.set(w.id, (used.get(w.id) ?? 0) + 1));
+            // authors: checkers who also wrote some of it (everyone did), so the story doesn't claim fresh eyes.
+            db.publish("qa.round", { payload: { round, agents: who.map((x) => x.w.id), authors: who.filter((x) => x.author).map((x) => x.w.id) } });
+            onEvent({ type: "round", round, agents: who.map((x) => x.w.id) });
+            const reviewers = reviewersOf(db);
+            const tasks = db
+                .listTasks()
+                .filter((t) => t.status === "merged" && !qaTasks.has(t.id))
+                .map((t) => {
+                const by = reviewers.get(t.id);
+                return `- ${t.title} · ${t.claimed_by ?? "?"} · ${by ? `reviewed by ${by}` : "NOT reviewed (merged on tests alone)"}`;
+            })
+                .join("\n");
+            const stat = git(repoRoot, ["diff", "--stat", `${o.startHead}..HEAD`]);
+            const diff = cap(git(repoRoot, ["diff", "--no-color", `${o.startHead}..HEAD`]), 20_000);
+            room.bugs = onBug;
+            await Promise.all(who.map(({ w, author }) => check(w, author, qaPrompt({ goal: o.goal, round, testCmd: o.testCmd(repoRoot), tasks, stat, diff, earlier: filed.filter((b) => b.round < round), author, maxBugs, checklist }))));
+            room.bugs = prev;
+            if (signal?.aborted)
+                break;
+            // Found live: a QA agent that hung until it was killed filed no bugs, and
+            // the round was reported "clean". No finished check = not checked; the
+            // next round (another agent, by rotation) checks again.
+            if (!roundBugs && !finished) {
+                const reason = "no QA check finished";
+                db.publish("qa.unchecked", { payload: { round, reason } });
+                onEvent({ type: "unchecked", round, reason });
+                continue;
+            }
+            if (!roundBugs) {
+                // A first clean round, quick, with nothing ever filed: one agent's word isn't enough.
+                // Trusted: after fixes (it re-checked them), a second clean, the last round, or a long check.
+                const trusted = result.bugs > 0 || cleanRounds > 0 || round === rounds || slowest >= minCleanMs;
+                cleanRounds++;
+                if (!trusted) {
+                    secondOpinion = new Set(who.map(({ w }) => w.id));
+                    const reason = `clean in ${Math.round(slowest / 1000)}s on the first look — another agent checks again`;
+                    db.publish("qa.suspect", { payload: { round, ms: slowest, reason } });
+                    onEvent({ type: "suspect", round, ms: slowest, reason });
+                    continue;
+                }
+                db.publish("qa.clean", { payload: { round } });
+                onEvent({ type: "clean", round });
+                result.clean = true;
+                break;
+            }
+            const fx = await o.runFixes();
+            result.fixed += fx.merged;
+            result.failed += fx.failed;
+            db.publish("qa.fixes", { payload: { round, merged: fx.merged, failed: fx.failed } });
+            onEvent({ type: "fixes", round, merged: fx.merged, failed: fx.failed });
+            if (fx.stopped)
+                break;
+            if (round === rounds) {
+                const open = filed.filter((b) => db.getTask(b.task)?.status !== "merged").length;
+                db.publish("qa.capped", { payload: { round, open } });
+                onEvent({ type: "capped", round, open });
+            }
+        }
+    }
+    finally {
+        room.bugs = prev;
+    }
+    result.stopped = !!signal?.aborted;
+    return result;
+}
+//# sourceMappingURL=qa.js.map