huddle-cli 0.0.0-stage → 0.1.0

package/dist/orchestrator/scheduler.js

@@ -0,0 +1,748 @@
+// 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, 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 } from "./takeover.js";
+import { helpOffer, alongsideBrief } from "../room/progress.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) {
+    return `You are reviewing a teammate's change before Huddle merges it. Another AI agent wrote it.
+
+TASK: ${title}
+${spec}
+
+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 the diff against the task: bugs, broken contracts, missing requirements, behavior that would fail.
+Reply with the first line exactly APPROVE or CHANGES.
+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).
+ */
+function parseVerdict(text) {
+    const lines = text.split("\n").map((l) => l.trim()).filter(Boolean);
+    const i = lines.findIndex((l) => /^(APPROVE|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)" };
+    return { approve: true, notes: lines.slice(i + 1, i + 3).join(" ") };
+}
+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);
+    };
+    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)
+        const done = () => {
+            if (resolved)
+                return;
+            resolved = true;
+            stopWatch();
+            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,
+                taskSpec: `Resolve merge conflict: ${task.title}\n\n${resolvePrompt({ title: task.title, spec: task.spec, brief, others, retry: st.last })}`,
+                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 });
+            let exited = false;
+            const once = (code) => {
+                if (exited)
+                    return;
+                exited = true;
+                void endResolve(r, c, h2, cs, code);
+            };
+            h2.child.on("exit", once);
+            h2.child.on("error", () => once(-1));
+        };
+        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}`);
+                h.child.kill("SIGTERM");
+                const child = h.child;
+                setTimeout(() => child.exitCode === null && child.signalCode === null && child.kill("SIGKILL"), 5000).unref();
+            }
+        };
+        /** A free agent with nothing to do offers to take part of each long-running task, once. */
+        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) && !db.nextBacklogTask(prefersOf(x)));
+            if (!helper)
+                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);
+                db.sendMessage({ from: helper.id, to: id, kind: "note", task_id: t.id, body: helpOffer(helper.id, t.id, t.title) });
+                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());
+                }
+                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
+                }
+            });
+            const tick = setInterval(() => {
+                watchSilence();
+                offerHelp();
+            }, Math.max(50, Math.min(10_000, Math.floor(silenceMs / 4))));
+            tick.unref();
+            stopWatch = () => {
+                clearInterval(tick);
+                unwatch();
+            };
+        }
+        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);
+            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 {
+                db.setTaskStatus(task.id, "review");
+                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;
+            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)), 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;
+                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}` : "") +
+                        (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 });
+                }
+            if (w.remote)
+                return void startRemote(w, { ...task, spec: task.spec + 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}${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 } : {}) });
+            let exited = false; // 'error' and 'exit' can both fire
+            const once = (code) => {
+                if (exited)
+                    return;
+                exited = true;
+                void finish(w, h, code);
+            };
+            h.child.on("exit", once);
+            h.child.on("error", () => once(-1));
+        };
+        const fill = () => {
+            // 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();
+            if (running.size === 0 && pending === 0) {
+                // 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