huddle-cli 0.1.0 → 0.1.3

package/dist/orchestrator/scheduler.js

@@ -4,14 +4,21 @@
 // (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 { userBrief } from "../room/user.js";
 import { launchAgent, stopChild } from "./launcher.js";
-import { prepareMerge, landMerge, removeWorktree, branchDiff, worktreeFor, createWorktree, beginConflictMerge, conflictBrief, finishConflictMerge, abortConflictMerge, } from "../sandbox/worktree.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 } from "./takeover.js";
-import { helpOffer, alongsideBrief } from "../room/progress.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, processTable } from "../platform.js";
+import { BusyWatch, silenceMaxMsFromEnv } from "./busy.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;
@@ -46,18 +53,20 @@ HOW:
    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) {
+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 the diff against the task: bugs, broken contracts, missing requirements, behavior that would fail.
+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.`;
 }
@@ -65,14 +74,19 @@ Style preferences and nice-to-haves are NOT blocking: APPROVE if that's all you
  * 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) {
+export 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()));
+    // "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)" };
-    return { approve: true, notes: lines.slice(i + 1, i + 3).join(" ") };
+    // 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;
@@ -90,6 +104,16 @@ export async function runBoard(opts) {
         }
         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;
@@ -112,11 +136,17 @@ export async function runBoard(opts) {
     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 });
         };
@@ -127,6 +157,10 @@ export async function runBoard(opts) {
         signal?.addEventListener("abort", killAll);
         // If Huddle itself exits, never leave orphaned agents working for nobody.
         process.once("exit", killAll);
+        // The token budget: past its soft line nothing new starts (tasks, takeovers, buddy checks, pairings);
+        // what's running finishes. Its hard line aborts the run's signal (the caller wires that, as Ctrl-C does).
+        const overBudget = () => !!opts.budget?.stopping;
+        const stoppedWhy = () => (opts.budget?.level === "hard" ? `stopped: the token budget ran over (${Math.round(opts.budget.used * 100)}%)` : "stopped by you");
         // 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
@@ -233,27 +267,22 @@ export async function runBoard(opts) {
                 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 })}`,
+                // 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 }),
             });
+            opts.budget?.track(h2.meter, r.id);
             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));
+            // 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;
@@ -266,7 +295,7 @@ export async function runBoard(opts) {
             // 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" }
+                ? { ok: false, reason: stoppedWhy() }
                 : code === 0
                     ? finishConflictMerge(wt, cs, h.excludes)
                     : { ok: false, reason: `resolver exited with code ${code}` };
@@ -293,10 +322,17 @@ export async function runBoard(opts) {
         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
+        // Quiet isn't stuck: a long test run prints nothing (busy.ts). Busy restarts the silence clock, up to a cap.
+        const silenceMaxMs = Math.max(silenceMs, opts.silenceMaxMs ?? silenceMaxMsFromEnv(silenceMs));
+        const busyWatch = new BusyWatch();
+        const lastBusy = new Map(); // agent id -> the last look that found it working
+        const busyTold = new Set(); // launches whose "busy, not silent" was reported
         /** Start listening for signs of life from a freshly launched agent. */
         const heard = (id, h) => {
             const bump = () => lastSeen.set(id, Date.now());
             bump();
+            lastBusy.delete(id);
+            busyWatch.forget(id);
             h.child?.stdout?.on("data", bump);
             h.child?.stderr?.on("data", bump);
         };
@@ -370,28 +406,383 @@ export async function runBoard(opts) {
             });
             start(r, task, brief, rc.from.id);
         };
-        /** Stop agents that have gone quiet; they're taken over in finish(). */
+        /**
+         * Stop agents that have gone quiet; they're taken over in finish(). Quiet =
+         * no output and no huddle_* call. Past half the window Huddle starts looking
+         * at what the agent is doing (busy.ts); a look that finds it working counts
+         * as a sign of life, so only an agent quiet AND idle for the whole window is
+         * silent — or one quiet past the cap, working or not.
+         */
+        const span = (ms) => (ms >= 60_000 ? `${Math.round(ms / 60_000)} min` : `${Math.round(ms / 1000)}s`);
         const watchSilence = () => {
+            let table; // one process snapshot per tick, only when someone is quiet
+            const now = Date.now();
             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)
+                const quiet = now - Math.max(lastSeen.get(id) ?? 0, h.startedAt);
+                if (quiet < silenceMs / 2) {
+                    busyWatch.forget(id); // it spoke: the next quiet spell compares from a fresh look
+                    continue;
+                }
+                let firstLook = false;
+                if (quiet < silenceMaxMs && h.child.pid) {
+                    if (table === undefined) {
+                        try {
+                            table = (opts.processTable ?? processTable)();
+                        }
+                        catch {
+                            table = null;
+                        }
+                    }
+                    const v = busyWatch.look(id, { pid: h.child.pid, worktree: h.worktree, logPath: h.logPath }, table, now);
+                    firstLook = v === null; // nothing to compare with yet: decide on the next tick
+                    if (v?.busy) {
+                        lastBusy.set(id, now);
+                        if (quiet >= silenceMs && !busyTold.has(h)) {
+                            busyTold.add(h);
+                            const t = db.getTask(h.taskId);
+                            onEvent({ type: "busy", agent: id, task: h.taskId, title: t?.title ?? h.taskId, quietMs: quiet, why: v.why });
+                        }
+                    }
+                }
+                const idle = now - Math.max(lastSeen.get(id) ?? 0, lastBusy.get(id) ?? 0, h.startedAt);
+                if (quiet >= silenceMaxMs)
+                    silenced.set(h.taskId, busyTold.has(h)
+                        ? `went silent — no output and no huddle_* call for ${span(quiet)}; it looked busy (a long command?), but that is past the ${span(silenceMaxMs)} cap`
+                        : `went silent — no output and no huddle_* call for ${span(quiet)}`);
+                else if (idle >= silenceMs && !firstLook)
+                    silenced.set(h.taskId, `went silent — no output and no huddle_* call for ${span(quiet)}, and nothing running (no child using CPU, no files changing)`);
+                else
+                    continue;
+                busyWatch.forget(id);
+                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) || overBudget())
+                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 || overBudget())
+                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;
-                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();
+                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
             }
         };
-        /** A free agent with nothing to do offers to take part of each long-running task, once. */
+        /**
+         * 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)
+            if (helpAfterMs === null || signal?.aborted || conflicts.length || rescues.length || overBudget())
                 return;
-            const helper = workers.find((x) => x.adapter && !running.has(x.id) && !reserved.has(x.id) && !db.nextBacklogTask(prefersOf(x)));
+            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;
@@ -404,7 +795,7 @@ export async function runBoard(opts) {
                 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) });
+                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 });
             }
         };
@@ -418,6 +809,16 @@ export async function runBoard(opts) {
                     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 = {};
@@ -430,17 +831,69 @@ export async function runBoard(opts) {
                     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(() => {
+                opts.budget?.check();
                 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);
@@ -449,14 +902,46 @@ export async function runBoard(opts) {
             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);
+                fail(w, h, task.title, stoppedWhy(), 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();
@@ -489,6 +974,7 @@ export async function runBoard(opts) {
             // 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);
@@ -499,7 +985,7 @@ export async function runBoard(opts) {
                 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, {
+                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
@@ -510,6 +996,7 @@ export async function runBoard(opts) {
                 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 });
@@ -553,7 +1040,7 @@ export async function runBoard(opts) {
                     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}` : "") +
+                        (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) });
                 }
@@ -576,6 +1063,7 @@ export async function runBoard(opts) {
                 startedAt: Date.now(),
                 meter: new UsageMeter(),
             };
+            opts.budget?.track(h.meter, h.agentId);
             db.setTaskStatus(task.id, "in_progress");
             db.setAgentStatus(w.id, "working");
             running.set(w.id, h);
@@ -622,8 +1110,13 @@ export async function runBoard(opts) {
                     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);
+            // What the user said mid-run (room/user.ts) outranks the plan and the contract.
+            const ub = userBrief(db);
+            const contract = (cb ? `\n\n${cb}` : "") + (ub ? `\n\n${ub}` : "");
             if (w.remote)
-                return void startRemote(w, { ...task, spec: task.spec + ho.text }, extra);
+                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) : "";
@@ -635,7 +1128,7 @@ export async function runBoard(opts) {
                 agentId: w.id,
                 role: "worker",
                 taskId: task.id,
-                taskSpec: `${task.title}\n\n${task.spec}${ho.text}${along}${extra}`,
+                taskSpec: `${task.title}\n\n${task.spec}${contract}${ho.text}${along}${extra}`,
                 roomUrl,
                 roomSecret: opts.roomSecret,
                 approvals: opts.approvals,
@@ -644,27 +1137,44 @@ export async function runBoard(opts) {
             });
             // 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])] };
+            opts.budget?.track(h.meter, h.agentId);
             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));
+            // 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, stoppedWhy(), 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");
+                    parkForYou(c, stoppedWhy());
                     continue;
                 }
                 const r = pickResolver(c.author, resolving.get(c.taskId)?.by ?? []);
@@ -680,13 +1190,17 @@ export async function runBoard(opts) {
                     fail(rc.from, rc.h, title, `${rc.reason} (stopped before another agent could take it over)`, 0);
                     continue;
                 }
+                if (overBudget()) {
+                    fail(rc.from, rc.h, title, `${rc.reason} (not taken over: the token budget is nearly spent)`, 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) {
+            if (!signal?.aborted && !overBudget()) {
                 // 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.
@@ -730,14 +1244,25 @@ export async function runBoard(opts) {
                     start(w, task);
             }
             offerHelp();
-            if (running.size === 0 && pending === 0) {
+            // 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)
+                const b = opts.budget;
+                if (b?.limit && b.level !== "ok")
+                    onEvent({ type: "budget", level: b.level === "hard" ? "hard" : "soft", tokens: b.tokens, limit: b.limit, left: blocked });
+                else if (blocked.length && !signal?.aborted)
                     onEvent({ type: "stuck", blocked });
                 done();
             }