huddle-cli 0.0.0-stage → 0.1.1

package/dist/orchestrator/scheduler.js

@@ -0,0 +1,1207 @@
+// The scheduler: keeps every ready agent busy until the board is empty.
+//
+// Loop: any idle agent takes the best unblocked backlog task for its strengths
+// (dependencies must be merged first). When its process exits, the merge engine
+// runs the test gate; in manual mode you approve the merge; landing it can
+// unblock more tasks, so we fill again. Nobody idles while there's work.
+import { launchAgent, stopChild } from "./launcher.js";
+import { prepareMerge, landMerge, removeWorktree, branchDiff, wipDiff, worktreeFor, createWorktree, beginConflictMerge, conflictBrief, finishConflictMerge, abortConflictMerge, } from "../sandbox/worktree.js";
+import { fetchBranch, deleteRemoteBranch } from "../sandbox/sync.js";
+import { UsageMeter } from "../adapters/usage.js";
+import { askAgent } from "./ask.js";
+import { handoffsFor, headSha, recordHandoff } from "./handoff.js";
+import { takeoverBrief, silenceMsFromEnv, helpAfterMsFromEnv, pairWaitMsFromEnv, buddyAfterMsFromEnv, isSpecialTask, buddyPrompt, parseBuddy, pairPrompt, parsePart, testsPart, pairNote, BUDDY_AT, pairEligible, } from "./takeover.js";
+import { helpOffer, alongsideBrief, addSplitPart, taskViews } from "../room/progress.js";
+import { contractBrief, contractNames, getContract } from "../room/contract.js";
+import { notifyAgent } from "../room/mail.js";
+import { closeNotes, openNotes, resolveNotes, trackNote } from "../room/followup.js";
+import { onFinished } from "../platform.js";
+import { startRadar } from "./radar.js";
+const prefersOf = (w) => w.adapter?.prefers ?? w.remote?.prefers ?? [];
+/** No help offers on a task whose reported progress is this far along. */
+export const OFFER_MAX_PCT = 60;
+/** Resolver runs per conflicted task before it's parked for you. */
+export const MAX_RESOLVE_ATTEMPTS = 2;
+const cap = (s, n) => (s.length > n ? s.slice(0, n) + "…" : s);
+function resolvePrompt(o) {
+    return `Your branch for this task is finished, but another agent's change landed on main touching the same lines.
+Huddle is merging main INTO this task's branch in your current directory, and git stopped on conflicts.
+Your job is ONLY to resolve them so that BOTH changes survive and work together.
+
+THIS TASK (its change is "this task" below): ${o.title}
+${cap(o.spec, 1500)}
+
+CONFLICTED FILES, with git's markers (<<<<<<< this task · ||||||| common base · ======= · >>>>>>> main):
+${o.brief.marked}
+
+WHAT THIS TASK CHANGED (base → this task):
+${o.brief.oursDiff || "(no diff)"}
+
+WHAT LANDED ON MAIN MEANWHILE (base → main):
+${o.brief.theirsDiff || "(no diff)"}
+
+THE OTHER WORK ON MAIN, and what its agents noted:
+${o.others || "(no notes)"}
+${o.retry ? `\nA previous attempt was rejected: ${o.retry}\n` : ""}
+HOW:
+1. Edit each conflicted file: remove every marker line and write ONE version in which both changes work together.
+2. Never take one side wholesale (no "git checkout --ours/--theirs", no copying one version over the other):
+   Huddle rejects a file identical to either side, because that silently drops a teammate's work.
+3. Change only what the combination needs. Don't commit, merge, rebase or reset — Huddle commits the
+   resolution and re-runs the tests before anything lands.
+4. huddle_remember(kind="decision", body=<how you combined them>, why=...), then huddle_done(task_id, summary).`;
+}
+function reviewPrompt(title, spec, diff, contract = "") {
+    return `You are reviewing a teammate's change before Huddle merges it. Another AI agent wrote it.
+
+TASK: ${title}
+${spec}
+${contract ? `\n${cap(contract, 2500)}\n` : ""}
+DIFF (against main):
+${diff || "(empty diff)"}
+
+You have NO tools — you can't run commands or open files, and you don't need to: the task and the full diff are above.
+Check, in order: (1) names and shapes match the ${contract ? "contract and the " : ""}task (functions, fields, routes, messages);
+(2) each acceptance point in the task is actually done; (3) error paths (bad input, missing data) behave; (4) the tests actually exercise this change.
+Reply with the first line exactly APPROVE or CHANGES.
+If APPROVE, add one line "Verified: <what you checked and found working>".
+If CHANGES, add up to 6 short lines, each one concrete blocking problem and where it is.
+Style preferences and nice-to-haves are NOT blocking: APPROVE if that's all you have. Do not edit anything.`;
+}
+/**
+ * The first APPROVE/CHANGES line decides. Anything else is "skipped" — shown
+ * honestly, and it never blocks a merge (a reviewer can't block by accident).
+ */
+export function parseVerdict(text) {
+    const lines = text.split("\n").map((l) => l.trim()).filter(Boolean);
+    // "APPROVED" is an approve too (it used to read as no verdict at all).
+    const i = lines.findIndex((l) => /^(APPROVED?|CHANGES)\b/.test(l.replace(/[*`#_]/g, "").toUpperCase()));
+    if (i < 0)
+        return { approve: true, skipped: true, notes: "no verdict" };
+    if (lines[i].replace(/[*`#_]/g, "").toUpperCase().startsWith("CHANGES"))
+        return { approve: false, notes: lines.slice(i + 1, i + 7).join("\n") || "(no details given)" };
+    // Found live: ~9s bare APPROVEs. An approve that says nothing about what was verified is shown as shallow.
+    const said = [lines[i].replace(/[*`#_]/g, "").replace(/^\s*APPROVE[D]?\b[\s:.,!—-]*/i, ""), ...lines.slice(i + 1, i + 3)].join(" ").trim();
+    // "Verified: ok" / "LGTM" say nothing either: what's left after the label has to name something.
+    const what = said.replace(/^(verified|checked)\s*:?\s*/i, "").replace(/^(lgtm|looks good|ok|fine)\b[\s.!,]*/i, "");
+    return what.length >= 10 ? { approve: true, notes: said } : { approve: true, shallow: true, notes: "approve (shallow)" };
+}
+export async function runBoard(opts) {
+    const { db, repoRoot, roomUrl, workers, testCmd, signal } = opts;
+    // Every scheduler event (but the per-tick token meter) is also kept in the
+    // Room db as "run.<type>", so `huddle story` can replay a run afterwards.
+    const onEvent = (e) => {
+        if (e.type !== "tokens") {
+            try {
+                const ev = e;
+                db.publish(`run.${e.type}`, { agent_id: ev.agent ?? null, task_id: ev.task ?? null, payload: e });
+            }
+            catch {
+                /* a closed db never breaks a run */
+            }
+        }
+        opts.onEvent(e);
+    };
+    // The shared contract, when the Council wrote one ("" when there is none).
+    const contractOf = opts.contractBrief ?? contractBrief;
+    const contract = () => {
+        try {
+            return contractOf(db) || "";
+        }
+        catch {
+            return "";
+        }
+    };
+    const running = new Map(); // agent id -> handle
+    let merged = 0;
+    let failed = 0;
+    let pending = 0; // merges awaiting approval
+    const all = () => [...workers, ...(opts.remoteWorkers?.() ?? [])];
+    const known = new Set();
+    const register = (w) => {
+        if (known.has(w.id))
+            return;
+        known.add(w.id);
+        db.upsertAgent({
+            id: w.id,
+            vendor: w.adapter?.vendor ?? `${w.remote?.member}'s`,
+            model: w.adapter?.models.worker || "default",
+            role: "worker",
+        });
+    };
+    workers.forEach(register);
+    const unavailable = new Set(); // teammates' agents that declined this run
+    return new Promise((resolve) => {
+        let resolved = false;
+        let stopWatch = () => { }; // the silence watchdog + help offers (set up below)
+        let stopRadar = () => { }; // the integration radar (set up below)
+        // Buddy checks and pairing asks end with the run (or with you): no ask outlives it.
+        const sideAsks = new AbortController();
+        signal?.addEventListener("abort", () => sideAsks.abort());
+        const done = () => {
+            if (resolved)
+                return;
+            resolved = true;
+            sideAsks.abort();
+            stopWatch();
+            stopRadar();
+            process.off("exit", killAll);
+            resolve({ merged, failed, stopped: !!signal?.aborted });
+        };
+        const killAll = () => {
+            for (const h of running.values())
+                stopChild(h.child);
+        };
+        signal?.addEventListener("abort", killAll);
+        // If Huddle itself exits, never leave orphaned agents working for nobody.
+        process.once("exit", killAll);
+        // Agents held out of fill(): an author waiting on review, a reviewer reviewing.
+        const reserved = new Set();
+        const reviewed = new Set(); // task ids that already had their one review round
+        const testFixed = new Set(); // task ids that already had their one red-tests fix round
+        const carry = new Map(); // earlier rounds
+        const taken = new Map(); // agent id -> backlog tasks it has claimed this run (fairness in fill)
+        const firstStart = new Map(); // task id -> when its first round began (handoff notes window)
+        const totals = (taskId, h, ms) => {
+            const c = carry.get(taskId) ?? { ms: 0, tokens: 0, cached: 0 };
+            return { ms: c.ms + ms, tokens: c.tokens + h.meter.tokens, cached: c.cached + h.meter.cached };
+        };
+        const fail = (w, h, title, reason, ms) => {
+            db.setTaskStatus(h.taskId, "failed");
+            db.remember({ kind: "gotcha", body: `Task "${title}" didn't merge: ${reason}`, author: "huddle" });
+            failed++;
+            onEvent({ type: "failed", agent: w.id, task: h.taskId, title, reason, log: h.logPath, ...totals(h.taskId, h, ms) });
+        };
+        const reviewsBy = new Map(); // agent id -> reviews it gave this run
+        /**
+         * An agent with nothing else it could do right now — the no-idle rule's
+         * reviewer (local only). Fewest reviews given so far goes first, roster
+         * order breaks ties. Found live (capstone round 2): roster-first claude was
+         * the idle one at almost every merge and did 4 of the 6 reviews.
+         */
+        const idleReviewer = (authorId) => workers
+            .filter((w) => w.id !== authorId &&
+            !running.has(w.id) &&
+            !reserved.has(w.id) &&
+            w.adapter?.ask &&
+            !db.nextBacklogTask(prefersOf(w)))
+            .map((w, i) => ({ w, i }))
+            .sort((a, b) => (reviewsBy.get(a.w.id) ?? 0) - (reviewsBy.get(b.w.id) ?? 0) || a.i - b.i)[0]?.w;
+        // --- merge conflicts -----------------------------------------------------
+        // A branch that can't rebase onto main goes to a resolver: the author if
+        // it's free (it knows the change), else any free agent, fresh eyes on a
+        // retry. Its work is checked (no markers, neither side dropped), the tests
+        // re-run, and it lands. After MAX_RESOLVE_ATTEMPTS it's parked for you —
+        // main untouched, the branch exactly as the author left it.
+        const conflicts = []; // waiting for a free agent
+        const resolving = new Map(); // task id -> attempts
+        const resolveConflict = (w, h, taskId, ms) => {
+            carry.set(taskId, totals(taskId, h, ms));
+            db.setTaskStatus(taskId, "review");
+            conflicts.push({ author: w, h: { ...h, meter: new UsageMeter() }, taskId }); // its tokens are in carry now
+        };
+        const parkForYou = (c, reason) => {
+            const task = db.getTask(c.taskId);
+            db.setTaskStatus(task.id, "needs_you");
+            db.remember({
+                kind: "gotcha",
+                body: `Task "${task.title}" conflicts with main and needs you: ${reason}. Nothing landed; the work is on branch ${c.h.branch}.`,
+                author: "huddle",
+            });
+            failed++;
+            const t = carry.get(task.id) ?? { ms: 0, tokens: 0, cached: 0 };
+            onEvent({
+                type: "failed",
+                needsYou: true,
+                agent: c.author.id,
+                task: task.id,
+                title: task.title,
+                reason: `merge conflict needs you — ${reason}; main untouched, work kept on branch ${c.h.branch} (${c.h.worktree})`,
+                log: c.h.logPath,
+                ...t,
+            });
+        };
+        const pickResolver = (author, tried) => {
+            const free = workers.filter((x) => x.adapter && !running.has(x.id) && !reserved.has(x.id));
+            return (free.find((x) => x.id === author.id && !tried.includes(x.id)) ??
+                free.find((x) => !tried.includes(x.id)) ??
+                free.find((x) => x.id === author.id) ??
+                free[0]);
+        };
+        const startResolve = (r, c) => {
+            const task = db.getTask(c.taskId);
+            const wt = { branch: c.h.branch, path: c.h.worktree };
+            const st = resolving.get(task.id) ?? { n: 0, by: [] };
+            if (st.n >= MAX_RESOLVE_ATTEMPTS)
+                return parkForYou(c, `${st.n} resolver attempts didn't hold (last: ${st.last})`);
+            const cs = beginConflictMerge(repoRoot, wt, `huddle: merge main into "${task.title}"`);
+            if ("error" in cs)
+                return parkForYou(c, cs.error);
+            if (!cs.files.length)
+                return void mergeTask(c.author, c.h, task, 0); // main moved on and it now merges cleanly
+            st.n++;
+            st.by.push(r.id);
+            resolving.set(task.id, st);
+            const brief = conflictBrief(wt, cs);
+            const others = brief.theirCommits
+                .map((subject) => {
+                const title = /^huddle\(([^)]*)\): (.*)$/.exec(subject)?.[2];
+                const t = title ? db.listTasks().find((x) => x.title === title) : undefined;
+                if (!t)
+                    return `- ${subject}`;
+                // Its done-summary, then what its agent wrote down (decisions say WHY the lines changed).
+                const done = db.recall(`Task ${t.id} done:`);
+                const notes = [...done, ...db.recall().filter((m) => m.author === t.claimed_by && !done.some((d) => d.id === m.id))];
+                return [`- "${t.title}" (${t.claimed_by ?? "?"}): ${cap(t.spec, 600)}`, ...notes.slice(0, 4).map((m) => `    note (${m.author}): ${cap(m.body, 300)}`)].join("\n");
+            })
+                .join("\n");
+            const h2 = launchAgent({
+                repoRoot,
+                adapter: r.adapter,
+                agentId: r.id,
+                role: "worker",
+                taskId: task.id,
+                // The contract decides a name clash: both sides code to it.
+                taskSpec: `Resolve merge conflict: ${task.title}\n\n${resolvePrompt({ title: task.title, spec: task.spec, brief, others, retry: st.last })}${contractBrief(db) ? `\n\n${contractBrief(db)}` : ""}`,
+                roomUrl,
+                roomSecret: opts.roomSecret,
+                approvals: opts.approvals,
+                worktree: wt,
+                onTokens: (tokens) => onEvent({ type: "tokens", agent: r.id, task: task.id, tokens }),
+            });
+            db.setTaskStatus(task.id, "in_progress");
+            db.setAgentStatus(r.id, "working", wt.path);
+            running.set(r.id, h2);
+            heard(r.id, h2);
+            onEvent({ type: "conflict", agent: r.id, author: c.author.id, task: task.id, title: task.title, files: cs.files, attempt: st.n, log: h2.logPath });
+            // On 'close' (capped): its last stdout lines (token usage) can still be in the pipe at 'exit'.
+            onFinished(h2.child, (code) => void endResolve(r, c, h2, cs, code));
+        };
+        const endResolve = async (r, c, h2, cs, code) => {
+            const ms = Date.now() - h2.startedAt;
+            running.delete(r.id);
+            db.releaseClaims(r.id);
+            db.setAgentStatus(r.id, "idle");
+            const task = db.getTask(c.taskId);
+            silenced.delete(task.id); // a silent resolver is just a failed attempt
+            const wt = { branch: c.h.branch, path: c.h.worktree };
+            // Both agents' Plug wiring may sit in this worktree; neither may be committed.
+            const h = { ...h2, excludes: [...new Set([...c.h.excludes, ...h2.excludes])] };
+            const res = signal?.aborted
+                ? { ok: false, reason: "stopped by you" }
+                : code === 0
+                    ? finishConflictMerge(wt, cs, h.excludes)
+                    : { ok: false, reason: `resolver exited with code ${code}` };
+            onEvent({ type: "resolved", agent: r.id, author: c.author.id, task: task.id, title: task.title, ok: res.ok, reason: res.reason, ms });
+            if (res.ok) {
+                db.remember({ kind: "decision", body: `Merge conflict in "${task.title}" (${cs.files.join(", ")}) resolved by ${r.id}; tests re-run before it lands`, author: "huddle" });
+                db.setTaskStatus(task.id, "review");
+                return mergeTask(c.author, h, task, ms); // tests again → review → land
+            }
+            abortConflictMerge(wt, cs); // the branch is the author's own commits again
+            resolving.get(task.id).last = res.reason;
+            db.remember({ kind: "gotcha", body: `Resolving the conflict in "${task.title}" (${r.id}) didn't hold: ${res.reason}`, author: "huddle" });
+            resolveConflict(c.author, h, task.id, ms);
+            fill();
+        };
+        // --- takeovers ------------------------------------------------------------
+        // Rescue: a task whose agent crashed, stayed red after its fix round, or
+        // went silent goes to a DIFFERENT free agent, which continues in the same
+        // worktree with a brief (takeover.ts). One takeover per task; a rescuer
+        // that can't land it either parks it for you, branch kept. Split: a busy
+        // agent's huddle_split puts a part on the board and a free agent takes it.
+        const silenceMs = opts.silenceMs ?? silenceMsFromEnv();
+        const helpAfterMs = opts.helpAfterMs !== undefined ? opts.helpAfterMs : helpAfterMsFromEnv();
+        const taskWt = new Map(); // task id -> its worktree, whoever works it
+        const lastSeen = new Map(); // agent id -> its last output or huddle_* call
+        const silenced = new Map(); // task id -> why we stopped its agent
+        /** Start listening for signs of life from a freshly launched agent. */
+        const heard = (id, h) => {
+            const bump = () => lastSeen.set(id, Date.now());
+            bump();
+            h.child?.stdout?.on("data", bump);
+            h.child?.stderr?.on("data", bump);
+        };
+        const rescues = []; // waiting for a free agent other than the author
+        const takenOver = new Map(); // task id -> its one takeover
+        const offered = new Set(); // task ids a free agent already offered to help with
+        const splitFrom = new Map(); // part task id -> who split it off what
+        /** Fail it — or, the first time, hand it to another agent to finish from the same branch. */
+        const failOrRescue = (w, h, task, reason, ms, testOutput) => {
+            const prior = takenOver.get(task.id);
+            if (prior)
+                return parkTakeover(w, h, task, reason, ms, prior.from);
+            const someoneElse = workers.some((x) => x.adapter && x.id !== w.id);
+            if (signal?.aborted || w.remote || !someoneElse)
+                return fail(w, h, task.title, reason, ms);
+            carry.set(task.id, totals(task.id, h, ms));
+            db.setTaskStatus(task.id, "claimed"); // held (files stay busy) until a rescuer starts
+            db.remember({ kind: "gotcha", body: `"${task.title}" (${w.id}) stopped: ${reason} — another agent takes it over from its branch`, author: "huddle" });
+            rescues.push({ from: w, h: { ...h, meter: new UsageMeter() }, taskId: task.id, reason, testOutput }); // its tokens are in carry now
+        };
+        const parkTakeover = (w, h, task, reason, ms, from) => {
+            db.setTaskStatus(task.id, "needs_you");
+            db.remember({
+                kind: "gotcha",
+                body: `Task "${task.title}" needs you: ${from} and then ${w.id} couldn't land it (last: ${reason}). Nothing landed; the work is on branch ${h.branch}.`,
+                author: "huddle",
+            });
+            failed++;
+            onEvent({
+                type: "failed",
+                needsYou: true,
+                agent: w.id,
+                task: task.id,
+                title: task.title,
+                reason: `needs you — taken over from ${from}, still not landing: ${reason}; main untouched, work kept on branch ${h.branch} (${h.worktree})`,
+                log: h.logPath,
+                ...totals(task.id, h, ms),
+            });
+        };
+        /** A different free local agent: another vendor first (fresh eyes), then one with nothing else to do. */
+        const pickRescuer = (rc) => {
+            const vendor = rc.from.adapter?.vendor;
+            const score = (x) => (x.adapter.vendor === vendor ? 2 : 0) + (db.nextBacklogTask(prefersOf(x)) ? 1 : 0) + (taken.get(x.id) ?? 0) / 100;
+            return workers
+                .filter((x) => x.adapter && x.id !== rc.from.id && !running.has(x.id) && !reserved.has(x.id))
+                .sort((a, b) => score(a) - score(b))[0];
+        };
+        const startRescue = (r, rc) => {
+            const task = db.getTask(rc.taskId);
+            takenOver.set(task.id, { from: rc.from.id, by: r.id });
+            db.reassignTask(task.id, r.id);
+            // The author's rounds are reported here: no merged/failed event will carry them.
+            const t = carry.get(task.id) ?? { ms: 0, tokens: 0, cached: 0 };
+            carry.delete(task.id);
+            db.publish("task.takeover", {
+                task_id: task.id,
+                agent_id: r.id,
+                payload: { kind: "rescue", from: rc.from.id, to: r.id, title: task.title, reason: rc.reason, branch: rc.h.branch },
+            });
+            db.remember({ kind: "decision", body: `${r.id} took over ${rc.from.id}'s "${task.title}" (${rc.reason}) and continues on its branch`, author: "huddle" });
+            onEvent({ type: "takeover", kind: "rescue", agent: r.id, from: rc.from.id, task: task.id, title: task.title, reason: rc.reason, ...t });
+            taken.set(r.id, (taken.get(r.id) ?? 0) + 1);
+            const brief = takeoverBrief(db, {
+                taskId: task.id,
+                from: rc.from.id,
+                reason: rc.reason,
+                branch: rc.h.branch,
+                since: firstStart.get(task.id) ?? rc.h.startedAt,
+                testOutput: rc.testOutput,
+                logPath: rc.h.logPath,
+            });
+            start(r, task, brief, rc.from.id);
+        };
+        /** Stop agents that have gone quiet; they're taken over in finish(). */
+        const watchSilence = () => {
+            for (const [id, h] of running) {
+                if (!h.child || silenced.has(h.taskId) || h.child.exitCode !== null || h.child.signalCode !== null)
+                    continue;
+                const quiet = Date.now() - Math.max(lastSeen.get(id) ?? 0, h.startedAt);
+                if (quiet < silenceMs)
+                    continue;
+                const span = quiet >= 60_000 ? `${Math.round(quiet / 60_000)} min` : `${Math.round(quiet / 1000)}s`;
+                silenced.set(h.taskId, `went silent — no output and no huddle_* call for ${span}`);
+                stopChild(h.child);
+            }
+        };
+        // --- teamwork mid-task --------------------------------------------------
+        // Found live (3 capstone runs): every help offer was declined, no split
+        // ever happened, and reviews came only after huddle_done. So Huddle acts:
+        // buddy checks put a second agent's eyes on work in progress, and pairing
+        // hands a part of the slowest task to a free agent unless its author says no.
+        const buddyOn = opts.buddyChecks ?? !/^(off|no|0|false)$/i.test(process.env.HUDDLE_BUDDY ?? "");
+        const pairWaitMs = opts.pairWaitMs ?? pairWaitMsFromEnv();
+        const buddyAfterMs = opts.buddyAfterMs !== undefined ? opts.buddyAfterMs : buddyAfterMsFromEnv();
+        const buddyBy = new Map(); // agent id -> buddy checks it gave
+        const buddyDone = new Map(); // task id -> its checks so far (and the first one's pct)
+        const buddyBusy = new Set(); // task ids with a check in flight
+        const buddyRuns = new Map(); // task id -> its check in flight, for finish() to wait on
+        const buddyWaitMs = opts.buddyWaitMs ?? 60_000;
+        const followedUp = new Set(); // task ids that had their one round for notes that came too late
+        const paired = new Set(); // task ids that had their one pairing (or attempt)
+        const pairing = new Set(); // helper ids mid-pairing (asking, or waiting for a no)
+        const holdFor = new Map(); // task id -> the partner task that must land first
+        const testsOf = new Set(); // tests-part task ids (they test their partner's code)
+        const held = []; // finished, waiting for their partner to land
+        const settled = (id) => {
+            const st = db.getTask(id)?.status;
+            return !st || st === "merged" || st === "failed" || st === "needs_you";
+        };
+        /** The other tasks in flight, with their work so far (capped): where a buddy spots XYZ vs ABC. */
+        const othersInFlight = (taskId) => [...running.values()]
+            .filter((x) => x.taskId !== taskId && x.child)
+            .slice(0, 3)
+            .map((x) => {
+            const t = db.getTask(x.taskId);
+            const wip = wipDiff(repoRoot, x.worktree, x.excludes, 2500);
+            return `- ${x.agentId}: “${t?.title ?? x.taskId}” (${x.taskId}) · files so far: ${wip.files.slice(0, 10).join(", ") || "(none yet)"}${wip.diff ? `\n${wip.diff}` : ""}`;
+        })
+            .join("\n");
+        /** Never the author; a free agent first, then the one that gave the fewest buddy checks. */
+        const pickBuddy = (authorId) => workers
+            .filter((x) => x.id !== authorId && x.adapter?.ask)
+            .map((w, i) => ({ w, i, busy: running.has(w.id) || reserved.has(w.id) ? 1 : 0 }))
+            .sort((a, b) => a.busy - b.busy || (buddyBy.get(a.w.id) ?? 0) - (buddyBy.get(b.w.id) ?? 0) || a.i - b.i)[0]?.w;
+        /** A teammate reads the work in progress and its notes land in the author's inbox now. Never blocks the author. */
+        const buddyCheck = async (taskId, pct, silentMs = 0) => {
+            if (!buddyOn || resolved || signal?.aborted || buddyBusy.has(taskId) || resolving.has(taskId))
+                return;
+            const t = db.getTask(taskId);
+            if (!t?.claimed_by || isSpecialTask(t))
+                return;
+            const author = t.claimed_by;
+            const h = running.get(author);
+            if (!h || h.taskId !== taskId || !h.child)
+                return; // local, and mid-task
+            const st = buddyDone.get(taskId) ?? { n: 0, notes: false, at: 0 };
+            // The second look is a follow-up on the first one's notes; a first look at 80% already was the late one.
+            // silentMs: the author never reported progress (found live: Claude called
+            // huddle_progress twice in 4 tasks), so the first look goes by time instead.
+            const due = st.n === 0 ? pct >= BUDDY_AT[0] || silentMs > 0 : st.n === 1 && st.notes && st.at < BUDDY_AT[1] && pct >= BUDDY_AT[1];
+            if (!due)
+                return;
+            const buddy = pickBuddy(author);
+            if (!buddy)
+                return;
+            // Nothing written yet: nothing to look at, and not worth a teammate's tokens. The next report tries again.
+            const wip = wipDiff(repoRoot, h.worktree, h.excludes, 16_000);
+            if (!wip.diff)
+                return;
+            st.n++;
+            if (st.n === 1)
+                st.at = pct;
+            buddyDone.set(taskId, st);
+            buddyBusy.add(taskId);
+            buddyBy.set(buddy.id, (buddyBy.get(buddy.id) ?? 0) + 1);
+            const t0 = Date.now();
+            let landed = () => { };
+            buddyRuns.set(taskId, { landed: new Promise((r) => (landed = r)), at: t0 });
+            try {
+                // The Room's huddle_done waits on this pair (server.ts), so the notes reach the author before it exits.
+                db.publish("buddy.start", { task_id: taskId, agent_id: buddy.id, payload: { author, pct } });
+                const when = silentMs ? `${Math.round(silentMs / 60_000) || 1} min in` : `${pct}%`;
+                const prompt = buddyPrompt({ author, when, title: t.title, spec: t.spec, contract: contract(), others: othersInFlight(taskId), diff: wip.diff });
+                // Its own signal, tied to the run's: askAgent never unhooks, and a long run would pile listeners on one signal.
+                const stop = new AbortController();
+                const off = () => stop.abort();
+                sideAsks.signal.addEventListener("abort", off);
+                const res = await askAgent(buddy.adapter, prompt, repoRoot, { signal: stop.signal, timeoutMs: 90_000, noTools: true, quick: true }).finally(() => sideAsks.signal.removeEventListener("abort", off));
+                if (resolved || !res.ok)
+                    return; // no answer: the author never knew it was asked
+                const notes = parseBuddy(res.text);
+                st.notes = !!notes;
+                // Its author is past it (finish() waited buddyWaitMs; it's merging or landed): the notes would only reach the
+                // author's NEXT task, where they mean nothing. Shared memory keeps them for QA and later tasks.
+                const st2 = db.getTask(taskId)?.status;
+                const late = !!notes && !!st2 && !["claimed", "in_progress"].includes(st2);
+                if (notes && late)
+                    db.remember({ kind: "gotcha", body: `Buddy note on "${t.title}" from ${buddy.id} (came back after it landed; nobody acted on it): ${notes}`.slice(0, 1500), author: buddy.id });
+                else if (notes) {
+                    const m = notifyAgent(db, author, `buddy check from ${buddy.id} ${silentMs ? when : `at ${when}`}:\n${notes}`, "huddle", taskId);
+                    trackNote(db, m, { by: buddy.id, kind: "buddy", worktree: h.worktree });
+                }
+                onEvent({ type: "checkpoint", agent: buddy.id, author, task: taskId, title: t.title, pct, notes: notes ?? "LOOKS GOOD", ms: Date.now() - t0, ...(late ? { late } : {}) });
+            }
+            catch {
+                /* a buddy check never breaks a run */
+            }
+            finally {
+                buddyBusy.delete(taskId);
+                buddyRuns.delete(taskId);
+                try {
+                    db.publish("buddy.end", { task_id: taskId, agent_id: buddy.id });
+                }
+                catch {
+                    /* closed db */
+                }
+                landed();
+            }
+        };
+        /** Tasks whose author never got to 40% in huddle_progress still get a look mid-task, after buddyAfterMs. */
+        const buddyBySilence = () => {
+            if (buddyAfterMs === null || !buddyOn)
+                return;
+            const now = Date.now();
+            for (const h of running.values()) {
+                if (!h.child || buddyDone.has(h.taskId) || buddyBusy.has(h.taskId) || now - h.startedAt < buddyAfterMs)
+                    continue;
+                // Reached 40%: that report triggers it. One early "10%" and then quiet still counts as quiet.
+                const pct = db.getTask(h.taskId)?.progress_pct ?? 0;
+                if (pct >= BUDDY_AT[0])
+                    continue;
+                void buddyCheck(h.taskId, pct, now - h.startedAt).catch(() => { });
+            }
+        };
+        /** Resolves with the author's "no: …" reason, or null when the window closes (or it says yes, or stops mattering). */
+        const waitForNo = (author, helper, since, ms, still) => new Promise((resolve) => {
+            let over = false;
+            const end = (v) => {
+                if (over)
+                    return;
+                over = true;
+                clearTimeout(timer);
+                clearInterval(poll);
+                unsub();
+                resolve(v);
+            };
+            const look = () => {
+                if (over)
+                    return;
+                for (const m of db.inbox("huddle", { peek: true })) {
+                    if (m.from_agent !== author || m.created_at < since)
+                        continue;
+                    db.markRead(m.id);
+                    const body = m.body.replace(/[*`_]/g, "").trim();
+                    if (/^(yes|y|ok|okay|go|sure|fine|sounds good|go ahead)\b/i.test(body))
+                        return end(null);
+                    // Anything else the author sends Huddle in the window is an objection: it was asked for a no, not a chat.
+                    return end(body.replace(/^(no|nope|nah|don't|do not)\b[\s:,.!—-]*/i, "").trim() || "no reason given");
+                }
+                // Models mix up recipients: a "no" sent to the helper itself counts too (left unread for the helper).
+                for (const m of db.inbox(helper, { peek: true })) {
+                    if (m.from_agent !== author || m.created_at < since)
+                        continue;
+                    const body = m.body.replace(/[*`_]/g, "").trim();
+                    if (/^(no|nope|nah)\b/i.test(body))
+                        return end(body.replace(/^(no|nope|nah)\b[\s:,.!—-]*/i, "").trim() || "no reason given");
+                }
+            };
+            const unsub = db.onEvent((e) => {
+                if (e.type !== "agent.message")
+                    return;
+                try {
+                    look();
+                }
+                catch {
+                    /* a read that fails is just no reply yet */
+                }
+            });
+            const timer = setTimeout(() => end(null), ms);
+            const poll = setInterval(() => {
+                try {
+                    if (!still() || resolved || signal?.aborted)
+                        end(null);
+                }
+                catch {
+                    end(null);
+                }
+            }, 500);
+            timer.unref?.();
+            poll.unref?.();
+            look();
+        });
+        /**
+         * Pairing: a free agent proposes one separable part of the task furthest
+         * behind (or, if nothing is cleanly separable, its tests); the author is
+         * told and has pairWaitMs to say no; then the part goes on the board for
+         * the helper. Merge order makes landing safe: a code part lands before the
+         * parent (the parent is written to use it, so its tests need it on main);
+         * a tests part lands after the parent (its tests run against the parent's
+         * code at the gate, so they verify something). Either way they're
+         * disjoint files, so neither order conflicts; it's about green gates.
+         */
+        const pairUp = async (helper, author, h, t) => {
+            paired.add(t.id);
+            pairing.add(helper.id);
+            // Found live (round 4): 0 pairs, and nothing said whether one was ever tried. A dropped pairing says why.
+            const dropped = (reason) => {
+                try {
+                    db.publish("pair.dropped", { task_id: t.id, agent_id: helper.id, payload: { with: author, title: t.title, reason } });
+                }
+                catch {
+                    /* closed db */
+                }
+            };
+            try {
+                const still = () => running.get(author)?.taskId === t.id && (db.getTask(t.id)?.progress_pct ?? 0) < OFFER_MAX_PCT && !resolved && !signal?.aborted;
+                const wip = wipDiff(repoRoot, h.worktree, h.excludes, 12_000);
+                const files = JSON.parse(t.files ?? "[]");
+                let part = null;
+                if (helper.adapter?.ask) {
+                    // The run waits for a pairing, so its ask ends as soon as the pairing stops mattering (the author finished, say).
+                    const stop = new AbortController();
+                    const off = () => stop.abort();
+                    sideAsks.signal.addEventListener("abort", off);
+                    const watch = setInterval(() => {
+                        try {
+                            if (!still())
+                                stop.abort();
+                        }
+                        catch {
+                            stop.abort();
+                        }
+                    }, 500);
+                    watch.unref?.();
+                    const res = await askAgent(helper.adapter, pairPrompt({ helper: helper.id, author, title: t.title, spec: t.spec, files, contract: contract(), diff: wip.diff }), repoRoot, { signal: stop.signal, timeoutMs: 90_000, noTools: true, quick: true }).finally(() => {
+                        clearInterval(watch);
+                        sideAsks.signal.removeEventListener("abort", off);
+                    });
+                    if (res.ok && !stop.signal.aborted)
+                        part = parsePart(res.text, wip.files, files);
+                }
+                part ??= testsPart(t.title, t.spec);
+                if (!still())
+                    return dropped(`${author} got past ${OFFER_MAX_PCT}% or finished while ${helper.id} was proposing a part`);
+                const note = notifyAgent(db, author, pairNote(helper.id, part, pairWaitMs), "huddle", t.id);
+                const no = await waitForNo(author, helper.id, note.created_at, pairWaitMs, still);
+                if (no !== null) {
+                    db.remember({ kind: "fact", body: `${author} kept "${t.title}" whole (declined ${helper.id} taking “${part.title}”): ${no}`.slice(0, 600), author: "huddle" });
+                    return dropped(`${author} said no: ${no}`.slice(0, 300));
+                }
+                const parent = db.getTask(t.id);
+                if (!parent || !still() || !["claimed", "in_progress"].includes(parent.status))
+                    return dropped(`${author} got past ${OFFER_MAX_PCT}% or finished during the no-window`);
+                const pct = parent.progress_pct;
+                const secs = Math.round((Date.now() - h.startedAt) / 1000);
+                const spec = `${part.spec}\n\n${author} keeps the rest of “${t.title}” and was told not to edit ${part.files.length ? part.files.join(", ") : "your test file"}. ` +
+                    `Match their names exactly; unsure? huddle_ask(…, to="${author}").` +
+                    (wip.diff ? `\n\nTHEIR WORK SO FAR (when you were paired):\n${cap(wip.diff, 6000)}` : "");
+                const prefers = [`@${helper.id}`, ...JSON.parse(parent.prefers)];
+                const { task: pt } = addSplitPart(db, parent, author, { title: part.title, spec, files: part.files, prefers });
+                if (!pt)
+                    return;
+                if (part.tests) {
+                    holdFor.set(pt.id, parent.id);
+                    testsOf.add(pt.id);
+                }
+                else
+                    holdFor.set(parent.id, pt.id);
+                onEvent({
+                    type: "pair",
+                    agent: helper.id,
+                    with: author,
+                    task: parent.id,
+                    title: parent.title,
+                    part: part.tests ? `tests: ${pt.title}` : `${pt.title} (${part.files.join(", ")})`,
+                    reason: `${parent.title} at ${pct}% after ${secs}s; ${helper.id} was free`,
+                });
+            }
+            catch {
+                /* pairing never breaks a run */
+            }
+            finally {
+                pairing.delete(helper.id);
+                if (!resolved)
+                    fill(); // the part (if any) goes to the helper now
+            }
+        };
+        /**
+         * Every tick: a free agent with nothing to do pairs up with the task
+         * furthest behind. A helper that can't be asked (no read-only mode) only
+         * sends the old help offer, which leaves the split to the busy agent.
+         */
+        const offerHelp = () => {
+            if (helpAfterMs === null || signal?.aborted || conflicts.length || rescues.length)
+                return;
+            const helper = workers.find((x) => x.adapter && !running.has(x.id) && !reserved.has(x.id) && !pairing.has(x.id) && !db.nextBacklogTask(prefersOf(x)));
+            if (!helper)
+                return;
+            if (helper.adapter.ask) {
+                const now = Date.now();
+                const left = (t, h) => ((now - h.startedAt) * (100 - t.progress_pct)) / Math.max(t.progress_pct, 5);
+                // A task that never called huddle_progress isn't at 0%: it has no number (see pairEligible).
+                const reported = new Set(taskViews(db, now).filter((v) => v.reported).map((v) => v.id));
+                const best = [...running]
+                    .map(([id, h]) => ({ id, h, t: db.getTask(h.taskId) }))
+                    .filter((c) => !!c.t &&
+                    !!c.h.child &&
+                    c.id !== helper.id &&
+                    c.t.claimed_by === c.id &&
+                    ["claimed", "in_progress"].includes(c.t.status) &&
+                    !paired.has(c.t.id) &&
+                    !resolving.has(c.t.id) &&
+                    !testFixed.has(c.t.id) &&
+                    !reviewed.has(c.t.id) &&
+                    !splitFrom.has(c.t.id) && // a part isn't split again
+                    !isSpecialTask(c.t) &&
+                    now - c.h.startedAt >= helpAfterMs &&
+                    pairEligible({
+                        reported: reported.has(c.t.id),
+                        pct: c.t.progress_pct,
+                        ranMs: now - c.h.startedAt,
+                        helpAfterMs,
+                        planned: JSON.parse(c.t.files ?? "[]").length,
+                        touched: () => wipDiff(repoRoot, c.h.worktree, c.h.excludes, 0).files.length,
+                    }))
+                    .sort((a, b) => left(b.t, b.h) - left(a.t, a.h))[0];
+                if (best)
+                    void pairUp(helper, best.id, best.h, best.t);
+                return;
+            }
+            for (const [id, h] of running) {
+                if (id === helper.id || offered.has(h.taskId) || resolving.has(h.taskId) || Date.now() - h.startedAt < helpAfterMs)
+                    continue;
+                const t = db.getTask(h.taskId);
+                if (!t || t.claimed_by !== id)
+                    continue;
+                // Nearly done (its own huddle_progress says so): nothing left worth
+                // splitting. Found live (capstone round 2): offers landed on tasks at
+                // 70-100%, every one was ignored, and they were most of the inbox traffic.
+                if ((t.progress_pct ?? 0) >= OFFER_MAX_PCT)
+                    continue;
+                offered.add(t.id);
+                notifyAgent(db, id, helpOffer(helper.id, t.id, t.title), helper.id, t.id);
+                onEvent({ type: "offer", agent: helper.id, to: id, task: t.id, title: t.title });
+            }
+        };
+        {
+            const unwatch = db.onEvent((e) => {
+                if (resolved)
+                    return;
+                if (e.type === "plug.call" && e.agent_id && running.has(e.agent_id))
+                    lastSeen.set(e.agent_id, Date.now());
+                else if (e.type === "task.progress" && e.task_id) {
+                    const by = db.getTask(e.task_id)?.claimed_by;
+                    if (by && running.has(by))
+                        lastSeen.set(by, Date.now());
+                    let pct = 0;
+                    try {
+                        pct = Number(JSON.parse(e.payload || "{}").pct) || 0;
+                    }
+                    catch {
+                        /* keep 0 */
+                    }
+                    const id = e.task_id;
+                    if (pct >= BUDDY_AT[0])
+                        setImmediate(() => void buddyCheck(id, pct).catch(() => { })); // never an unhandled rejection
+                }
+                else if (e.type === "task.split" && e.task_id) {
+                    let p = {};
+                    try {
+                        p = JSON.parse(e.payload || "{}");
+                    }
+                    catch {
+                        /* keep {} */
+                    }
+                    splitFrom.set(e.task_id, { from: String(p.from ?? e.agent_id ?? ""), parentTitle: String(p.parent_title ?? "") });
+                    setImmediate(() => !resolved && fill()); // a free agent may take it right away
+                }
+                else if (e.type === "note.closed" && e.task_id) {
+                    // A note that needed an answer, settled at huddle_done (server.ts) or as its task finished.
+                    let p = {};
+                    try {
+                        p = JSON.parse(e.payload || "{}");
+                    }
+                    catch {
+                        /* keep {} */
+                    }
+                    const how = p.how === "replied" || p.how === "fixed" ? p.how : "ignored";
+                    onEvent({ type: "followup", agent: String(p.to ?? e.agent_id ?? ""), by: String(p.by ?? ""), task: e.task_id, title: db.getTask(e.task_id)?.title ?? e.task_id, kind: p.kind === "radar" ? "radar" : "buddy", how, note: String(p.body ?? "") });
+                }
+                else if (e.type === "contract.amended") {
+                    let p = {};
+                    try {
+                        p = JSON.parse(e.payload || "{}");
+                    }
+                    catch {
+                        /* keep {} */
+                    }
+                    onEvent({ type: "contract", agent: String(p.by ?? e.agent_id ?? ""), version: Number(p.version) || 0, section: String(p.section ?? ""), change: String(p.change ?? "") });
+                }
+            });
+            const tick = setInterval(() => {
+                watchSilence();
+                offerHelp();
+                buddyBySilence();
+            }, Math.max(50, Math.min(10_000, Math.floor(silenceMs / 4))));
+            tick.unref();
+            stopWatch = () => {
+                clearInterval(tick);
+                unwatch();
+            };
+            // Integration radar: compare in-flight agents' uncommitted work for
+            // conflicts and name mismatches while they can still fix them (radar.ts).
+            // Local agents only — a teammate's work lives on their machine.
+            if (opts.radarMs !== null)
+                stopRadar = startRadar({
+                    db,
+                    repoRoot,
+                    intervalMs: opts.radarMs,
+                    inFlight: () => [...running.values()]
+                        // Still working: an exited agent's worktree is being committed and rebased by finish().
+                        .filter((h) => h.child && h.child.exitCode === null && h.child.signalCode === null && !resolving.has(h.taskId))
+                        .map((h) => ({ agentId: h.agentId, taskId: h.taskId, title: db.getTask(h.taskId)?.title ?? h.taskId, worktree: h.worktree, excludes: taskWt.get(h.taskId)?.excludes ?? h.excludes })),
+                    // A finding is a note its reader must answer (fix it, or say why not) before huddle_done.
+                    notify: (to, message, key) => {
+                        const h = running.get(to);
+                        const m = notifyAgent(db, to, message, "huddle", h?.taskId ?? null);
+                        if (h)
+                            trackNote(db, m, { by: "huddle", kind: "radar", worktree: h.worktree, key });
+                    },
+                    // The radar no longer sees it: whoever fixed it, every note about it is answered.
+                    resolved: (key) => resolveNotes(db, key),
+                    contractNames: () => contractNames(getContract(db)),
+                    onEvent,
+                });
+        }
+        /** Notes that came back after the author exited: one more round to answer them, before anything merges. */
+        const followUpBrief = (notes) => `\n\nWhile you were finishing, a teammate looked over your work and these notes reached Huddle after you exited — nothing is merged yet. ` +
+            `Address each one: fix it, or reply huddle_send(to="<who>", reply_to="<id>", message="won't fix: <why>"). Then huddle_done.\n` +
+            notes.map((n) => `- [id ${n.id}, from ${n.kind === "radar" ? "huddle" : n.by}] ${cap(n.body, 800)}`).join("\n");
+        const finish = async (w, h, exitCode, why) => {
+            const workMs = Date.now() - h.startedAt; // agent time, not test/merge/approval time
+            running.delete(w.id);
+            db.releaseClaims(w.id);
+            db.setAgentStatus(w.id, "idle");
+            const task = db.getTask(h.taskId);
+            const quiet = silenced.get(task.id);
+            silenced.delete(task.id);
+            // A buddy check still being written is about THIS work. Found live (capstone
+            // round 4): 3 of 4 buddy notes came back after the author finished, and
+            // reached its next task instead. Hold the author (and its merge) for it, bounded.
+            const check = buddyRuns.get(task.id);
+            if (check && exitCode === 0 && !signal?.aborted) {
+                reserved.add(w.id);
+                pending++; // the run isn't over while this waits
+                let timer;
+                await Promise.race([check.landed, new Promise((r) => (timer = setTimeout(r, Math.max(0, check.at + buddyWaitMs - Date.now()))))]);
+                clearTimeout(timer);
+                pending--;
+                reserved.delete(w.id);
+            }
+            if (signal?.aborted) {
+                fail(w, h, task.title, "stopped by you", workMs);
+            }
+            else if (exitCode !== 0) {
+                failOrRescue(w, h, task, quiet ?? why ?? `agent exited with code ${exitCode}`, workMs);
+            }
+            else {
+                // Notes it never saw (they came back after it exited). One it saw and didn't answer is just ignored.
+                const late = w.adapter ? openNotes(db, task.id).filter((n) => n.to === w.id && !db.getMessage(n.id)?.read_at) : [];
+                if (late.length && !followedUp.has(task.id)) {
+                    followedUp.add(task.id);
+                    for (const n of late)
+                        db.markRead(n.id, "prompt"); // delivered in the brief, not the inbox
+                    carry.set(task.id, totals(task.id, h, workMs));
+                    db.remember({ kind: "gotcha", body: `"${task.title}" (${w.id}) got ${late.length} teammate note(s) after it finished; one more round to answer them`, author: "huddle" });
+                    start(w, task, followUpBrief(late));
+                    return fill();
+                }
+                closeNotes(db, task.id); // each note: addressed or ignored (the note.closed watcher reports it)
+                db.setTaskStatus(task.id, "review");
+                // A paired task lands in a safe order (see pairUp): wait for its partner first.
+                const first = holdFor.get(task.id);
+                if (first && !settled(first)) {
+                    held.push({ w, h, task, workMs, after: first });
+                    pending++;
+                    return fill();
+                }
+                return mergeTask(w, h, task, workMs);
+            }
+            fill();
+        };
+        /** Test gate → cross-review → your approval → land. Re-entered after a conflict is resolved. */
+        const mergeTask = async (w, h, task, workMs) => {
+            const wt = { branch: h.branch, path: h.worktree };
+            const prep = prepareMerge(repoRoot, wt, testCmd(wt.path), h.excludes, `huddle(${w.id}): ${task.title}`);
+            if (!prep.ok) {
+                // Another agent's change landed on the same lines: hand it to a resolver, never drop it.
+                if (prep.conflict)
+                    resolveConflict(w, h, task.id, workMs);
+                else if (prep.testOutput !== undefined && !testFixed.has(task.id) && !w.remote && !resolving.has(task.id) && !signal?.aborted) {
+                    // Red test gate: one fix round for the author, in the same worktree,
+                    // with the failing output in hand (found live: an agent finished with
+                    // a test it hadn't been told it could fix). A second red gate fails it.
+                    testFixed.add(task.id);
+                    carry.set(task.id, totals(task.id, h, workMs));
+                    db.remember({ kind: "gotcha", body: `"${task.title}" (${w.id}) hit a red test gate; one fix round`, author: "huddle" });
+                    start(w, task, `\n\nHuddle's merge gate ran the full test suite (\`${testCmd(wt.path)}\`) on your work and it FAILED — nothing was merged. ` +
+                        `Make the whole suite pass, including tests you didn't write; if that needs a file outside your planned list, ` +
+                        `huddle_announce_plan it and edit it. Then huddle_done. Test output (tail):\n${prep.testOutput || "(no output)"}`);
+                }
+                else if (prep.testOutput !== undefined)
+                    failOrRescue(w, h, task, prep.reason, workMs, prep.testOutput);
+                else
+                    fail(w, h, task.title, prep.reason, workMs);
+                return fill();
+            }
+            // Cross-review by an otherwise-idle agent: one round, never blocks on its own.
+            const reviewer = reviewed.has(task.id) ? undefined : idleReviewer(w.id);
+            let skippedReview = false;
+            let shallowReview = false;
+            if (reviewer) {
+                reviewed.add(task.id);
+                reviewsBy.set(reviewer.id, (reviewsBy.get(reviewer.id) ?? 0) + 1);
+                reserved.add(w.id);
+                reserved.add(reviewer.id);
+                pending++;
+                db.setAgentStatus(reviewer.id, "working");
+                onEvent({ type: "review", agent: reviewer.id, author: w.id, task: task.id, title: task.title });
+                fill(); // everyone else keeps going
+                const t0 = Date.now();
+                const res = await askAgent(reviewer.adapter, reviewPrompt(task.title, task.spec, branchDiff(repoRoot, wt), contract()), wt.path, {
+                    signal,
+                    timeoutMs: 90_000,
+                    noTools: true, // the diff is in the prompt — no need to explore
+                    quick: true, // 90s box: an adapter may use its fast model
+                });
+                const verdict = res.ok ? parseVerdict(res.text) : { approve: true, skipped: true, notes: "timed out" };
+                reserved.delete(reviewer.id);
+                db.setAgentStatus(reviewer.id, "idle");
+                pending--;
+                skippedReview = !!verdict.skipped;
+                shallowReview = !!verdict.shallow;
+                onEvent({ type: "reviewed", agent: reviewer.id, author: w.id, task: task.id, title: task.title, ...verdict, ms: Date.now() - t0 });
+                if (!verdict.approve && !signal?.aborted) {
+                    db.remember({ kind: "gotcha", body: `Review of "${task.title}" by ${reviewer.id}: ${verdict.notes}`, author: reviewer.id });
+                    carry.set(task.id, totals(task.id, h, workMs));
+                    reserved.delete(w.id);
+                    // The author fixes it in the same worktree, with the review in hand.
+                    start(w, task, `\n\nA reviewer (${reviewer.id}) asked for these changes before merge — fix them:\n${verdict.notes}`);
+                    return fill();
+                }
+                reserved.delete(w.id);
+            }
+            let approved = true;
+            if (opts.approveMerge) {
+                pending++;
+                fill(); // keep the other agents busy while you decide
+                approved = await opts.approveMerge({ agent: w.id, title: task.title, diffstat: prep.diffstat });
+                pending--;
+            }
+            if (!approved)
+                fail(w, h, task.title, `you declined — work kept on branch ${h.branch}`, workMs);
+            else {
+                const base = headSha(repoRoot); // main before this lands — the handoff's diff base
+                let land = landMerge(repoRoot, wt);
+                if (!land.merged) {
+                    // main moved while this waited (on review, or on you): rebase + re-test once, then land.
+                    const again = prepareMerge(repoRoot, wt, testCmd(wt.path), h.excludes, `huddle(${w.id}): ${task.title}`);
+                    if (again.conflict) {
+                        resolveConflict(w, h, task.id, workMs);
+                        return fill();
+                    }
+                    land = again.ok ? landMerge(repoRoot, wt) : { merged: false, reason: again.reason };
+                }
+                if (land.merged) {
+                    db.setProgress(task.id, 100);
+                    db.setTaskStatus(task.id, "merged");
+                    removeWorktree(repoRoot, h.worktree);
+                    if (w.remote)
+                        deleteRemoteBranch(repoRoot, h.branch); // delivered branch is merged now
+                    merged++;
+                    // What dependents will be told: files, exported signatures, the author's notes.
+                    recordHandoff(db, repoRoot, { taskId: task.id, agentId: w.id, title: task.title, base, since: firstStart.get(task.id) ?? h.startedAt });
+                    const resolvedBy = resolving.get(task.id)?.by.at(-1);
+                    const reason = prep.reason +
+                        (reviewer && !skippedReview ? ` · reviewed by ${reviewer.id}${shallowReview ? " (shallow approve)" : ""}` : "") +
+                        (resolvedBy ? ` · conflict resolved by ${resolvedBy}` : "");
+                    onEvent({ type: "merged", agent: w.id, task: task.id, title: task.title, reason, ...totals(task.id, h, workMs) });
+                }
+                else
+                    fail(w, h, task.title, land.reason, workMs);
+            }
+            fill();
+        };
+        /** Hand a task to a teammate's agent; their machine does the work, a branch comes back. */
+        const startRemote = async (w, task, extra) => {
+            const { branch, path: wtPath } = worktreeFor(repoRoot, w.id, task.id);
+            const h = {
+                agentId: w.id,
+                taskId: task.id,
+                worktree: wtPath,
+                branch,
+                cmd: [],
+                logPath: `(on ${w.remote.member}'s machine)`,
+                excludes: [],
+                startedAt: Date.now(),
+                meter: new UsageMeter(),
+            };
+            db.setTaskStatus(task.id, "in_progress");
+            db.setAgentStatus(w.id, "working");
+            running.set(w.id, h);
+            onEvent({ type: "start", agent: w.id, task: task.id, title: task.title, log: h.logPath, fixing: !!extra, remote: w.remote.member });
+            const base = opts.publish?.();
+            if (!base)
+                return void finish(w, h, 1, "can't delegate: main isn't pushed to the shared remote (turn on `sync`)");
+            const accepted = await opts.bridge.assign(w.remote, { ...task, spec: task.spec + extra }, base, branch);
+            if (!accepted) {
+                running.delete(w.id);
+                db.setAgentStatus(w.id, "idle");
+                db.releaseTask(task.id);
+                unavailable.add(w.id);
+                onEvent({ type: "declined", agent: w.id, task: task.id, title: task.title });
+                return fill();
+            }
+            const d = await opts.bridge.delivered(task.id);
+            h.meter.add({ tokens: d.tokens, cached: d.cached, total: true });
+            if (d.ms)
+                h.startedAt = Date.now() - d.ms;
+            if (!d.ok)
+                return void finish(w, h, 1, d.reason ?? "teammate's agent failed");
+            const f = fetchBranch(repoRoot, branch);
+            if (!f.ok)
+                return void finish(w, h, 1, `couldn't fetch ${branch}: ${f.note}`);
+            createWorktree(repoRoot, w.id, task.id); // checks out the delivered branch
+            void finish(w, h, 0);
+        };
+        const start = (w, task, extra = "", takeoverFrom) => {
+            const first = !firstStart.has(task.id);
+            if (first)
+                firstStart.set(task.id, Date.now());
+            const part = first ? splitFrom.get(task.id) : undefined;
+            if (part && part.from !== w.id) {
+                // "cursor took part of codex's task": a huddle_split part, picked up by a free agent.
+                const reason = `split off “${part.parentTitle}”`;
+                db.publish("task.takeover", { task_id: task.id, agent_id: w.id, payload: { kind: "split", from: part.from, to: w.id, title: task.title, reason } });
+                onEvent({ type: "takeover", kind: "split", agent: w.id, from: part.from, task: task.id, title: task.title, reason, ms: 0, tokens: 0, cached: 0 });
+            }
+            // Upstream handoffs ride in the prompt — every round, since each launch is a fresh process.
+            const ho = handoffsFor(db, task.id);
+            if (first)
+                for (const h of ho.from) {
+                    db.publish("handoff", { task_id: task.id, agent_id: h.agent_id, payload: { from: h.agent_id, to: w.id, task: h.task_id, title: h.title, files: h.files, symbols: h.symbols } });
+                    onEvent({ type: "handoff", agent: w.id, from: h.agent_id, task: task.id, title: h.title, files: h.files.length, symbols: h.symbols.length });
+                }
+            // The contract as it stands now (amendments included): each launch is a fresh process.
+            const cb = contractBrief(db);
+            const contract = cb ? `\n\n${cb}` : "";
+            if (w.remote)
+                return void startRemote(w, { ...task, spec: task.spec + contract + ho.text }, extra);
+            // Who else is mid-task right now, so this agent knows whom to tell (first round only;
+            // fill() claims a whole wave before launching any of it, so siblings see each other).
+            const along = first && !takeoverFrom ? alongsideBrief(db, task.id, w.id) : "";
+            // Every round of a task runs in its first worktree — a rescuer continues there too.
+            const prior = taskWt.get(task.id);
+            const launched = launchAgent({
+                repoRoot,
+                adapter: w.adapter,
+                agentId: w.id,
+                role: "worker",
+                taskId: task.id,
+                taskSpec: `${task.title}\n\n${task.spec}${contract}${ho.text}${along}${extra}`,
+                roomUrl,
+                roomSecret: opts.roomSecret,
+                approvals: opts.approvals,
+                worktree: prior ? { branch: prior.branch, path: prior.path } : undefined,
+                onTokens: (tokens) => onEvent({ type: "tokens", agent: w.id, task: task.id, tokens }),
+            });
+            // Every agent's Plug wiring that sat in this worktree stays out of the commit.
+            const h = { ...launched, excludes: [...new Set([...(prior?.excludes ?? []), ...launched.excludes])] };
+            taskWt.set(task.id, { branch: h.branch, path: h.worktree, excludes: h.excludes });
+            db.setTaskStatus(task.id, "in_progress");
+            db.setAgentStatus(w.id, "working", h.worktree);
+            running.set(w.id, h);
+            heard(w.id, h);
+            onEvent({ type: "start", agent: w.id, task: task.id, title: task.title, log: h.logPath, fixing: !!extra && !takeoverFrom, ...(takeoverFrom ? { takeover: takeoverFrom } : {}) });
+            // On 'close', capped at 2s after 'exit': found live, an agent's final stdout
+            // lines (its token usage, the log's tail) were lost when finish() ran on 'exit'.
+            onFinished(h.child, (code) => void finish(w, h, code));
+        };
+        const fill = () => {
+            // Paired tasks whose partner has landed (or failed: then nothing to wait for) merge now.
+            // Every ready one is taken out before any merge starts: a merge re-enters fill().
+            const ready = held.filter((x) => signal?.aborted || settled(x.after));
+            if (ready.length) {
+                held.splice(0, held.length, ...held.filter((x) => !ready.includes(x)));
+                let merging = 0;
+                for (const x of ready) {
+                    pending--;
+                    holdFor.delete(x.task.id);
+                    if (signal?.aborted)
+                        fail(x.w, x.h, x.task.title, "stopped by you", x.workMs);
+                    // Tests for code that never landed would only go red at the gate and burn a fix round.
+                    else if (testsOf.has(x.task.id) && db.getTask(x.after)?.status !== "merged")
+                        fail(x.w, x.h, x.task.title, `the task it tests (“${db.getTask(x.after)?.title ?? x.after}”) didn't land — work kept on branch ${x.h.branch}`, x.workMs);
+                    else {
+                        merging++;
+                        void mergeTask(x.w, x.h, x.task, x.workMs);
+                    }
+                }
+                if (merging)
+                    return; // each merge fills again when it's done
+            }
+            // Conflicts first: they hold finished work, and the author is usually free.
+            for (const c of conflicts.splice(0)) {
+                if (signal?.aborted) {
+                    parkForYou(c, "stopped by you");
+                    continue;
+                }
+                const r = pickResolver(c.author, resolving.get(c.taskId)?.by ?? []);
+                if (r)
+                    startResolve(r, c);
+                else
+                    conflicts.push(c); // everyone's busy: the next agent to finish takes it
+            }
+            // Then takeovers: half-done work beats a fresh task.
+            for (const rc of rescues.splice(0)) {
+                const title = db.getTask(rc.taskId).title;
+                if (signal?.aborted) {
+                    fail(rc.from, rc.h, title, `${rc.reason} (stopped before another agent could take it over)`, 0);
+                    continue;
+                }
+                const r = pickRescuer(rc);
+                if (r)
+                    startRescue(r, rc);
+                else
+                    rescues.push(rc); // the next other agent to finish takes it
+            }
+            if (!signal?.aborted) {
+                // Fairness: the free agent that has taken the fewest tasks goes first
+                // (roster order breaks ties), so one agent doesn't take every task that
+                // unblocks just because it's listed first.
+                const free = all().map((w, i) => ({ w, i })).sort((a, b) => (taken.get(a.w.id) ?? 0) - (taken.get(b.w.id) ?? 0) || a.i - b.i);
+                // The whole wave is claimed first and launched after, so every task in
+                // it is told who else is starting alongside it (alongsideBrief).
+                const wave = [];
+                const picked = new Set();
+                // A task tagged "@<agent>" (a QA bug's fix, routed to whoever wrote
+                // those files) goes to that agent first when it's free; if it's busy
+                // or absent, the loop below lets any free agent take it.
+                for (const { w } of free) {
+                    if (running.has(w.id) || reserved.has(w.id) || unavailable.has(w.id) || (w.remote && !opts.bridge))
+                        continue;
+                    const mine = db.nextBacklogTask([`@${w.id}`]);
+                    if (!mine || !JSON.parse(mine.prefers).includes(`@${w.id}`))
+                        continue;
+                    register(w);
+                    if (!db.claimTask(mine.id, w.id).ok)
+                        continue;
+                    taken.set(w.id, (taken.get(w.id) ?? 0) + 1);
+                    picked.add(w.id);
+                    wave.push({ w, task: mine });
+                }
+                for (const { w } of free) {
+                    if (picked.has(w.id) || running.has(w.id) || reserved.has(w.id) || unavailable.has(w.id))
+                        continue;
+                    if (w.remote && !opts.bridge)
+                        continue;
+                    register(w);
+                    const next = db.nextBacklogTask(prefersOf(w));
+                    if (!next)
+                        continue;
+                    if (!db.claimTask(next.id, w.id).ok)
+                        continue;
+                    taken.set(w.id, (taken.get(w.id) ?? 0) + 1);
+                    picked.add(w.id);
+                    wave.push({ w, task: next });
+                }
+                for (const { w, task } of wave)
+                    start(w, task);
+            }
+            offerHelp();
+            // Nobody is working and only paired merges wait: their partner can't land now, so don't wait for it.
+            if (running.size === 0 && held.length && pending === held.length && !pairing.size) {
+                const x = held.shift();
+                pending--;
+                holdFor.delete(x.task.id);
+                void mergeTask(x.w, x.h, x.task, x.workMs);
+                return;
+            }
+            if (running.size === 0 && pending === 0 && !pairing.size) {
+                // Nobody is running yet a conflict still waits: no agent on this machine can resolve it.
+                for (const c of conflicts.splice(0))
+                    parkForYou(c, "no agent on this machine could take the resolution");
+                for (const rc of rescues.splice(0))
+                    fail(rc.from, rc.h, db.getTask(rc.taskId).title, `${rc.reason} (no other agent could take it over)`, 0);
+                const blocked = db.listTasks().filter((t) => t.status === "backlog").map((t) => t.title);
+                if (blocked.length && !signal?.aborted)
+                    onEvent({ type: "stuck", blocked });
+                done();
+            }
+        };
+        fill();
+    });
+}
+//# sourceMappingURL=scheduler.js.map