huddle-cli 0.1.1 → 0.1.5

package/dist/orchestrator/qa.js

@@ -276,6 +276,7 @@ export async function runQa(o) {
                 approvals: o.approvals,
                 worktree: wt,
             });
+            o.budget?.track(h.meter, h.agentId);
         }
         catch (e) {
             db.setTaskStatus(task.id, "failed");
@@ -312,7 +313,7 @@ export async function runQa(o) {
                 finished++;
                 slowest = Math.max(slowest, ms);
             }
-            db.publish("qa.done", { agent_id: w.id, task_id: task.id, payload: { round, ok: code === 0, bugs, ms } });
+            db.publish("qa.done", { agent_id: w.id, task_id: task.id, payload: { round, ok: code === 0, bugs, ms, tokens: h.meter.tokens } });
             onEvent({ type: "checked", agent: w.id, round, ok: code === 0, bugs, ms, tokens: h.meter.tokens, reason, task: task.id });
             resolve();
         };
@@ -323,6 +324,13 @@ export async function runQa(o) {
     const prev = room.bugs;
     try {
         for (round = 1; round <= rounds && !signal?.aborted; round++) {
+            if (o.budget?.stopping) {
+                result.budget = true;
+                const reason = `the token budget is nearly spent — QA round ${round} not started`;
+                db.publish("qa.skipped", { payload: { round, reason } });
+                onEvent({ type: "skipped", reason });
+                break;
+            }
             roundBugs = 0;
             finished = 0;
             slowest = 0;

package/dist/orchestrator/scheduler.js

@@ -4,6 +4,7 @@
 // (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, wipDiff, worktreeFor, createWorktree, beginConflictMerge, conflictBrief, finishConflictMerge, abortConflictMerge, } from "../sandbox/worktree.js";
 import { fetchBranch, deleteRemoteBranch } from "../sandbox/sync.js";
@@ -15,7 +16,8 @@ import { helpOffer, alongsideBrief, addSplitPart, taskViews } from "../room/prog
 import { contractBrief, contractNames, getContract } from "../room/contract.js";
 import { notifyAgent } from "../room/mail.js";
 import { closeNotes, openNotes, resolveNotes, trackNote } from "../room/followup.js";
-import { onFinished } from "../platform.js";
+import { 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. */
@@ -51,12 +53,32 @@ 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, contract = "") {
+/** What a task's author read through connectors (a ticket, an issue), for a reviewer who has no tools. */
+export function outsideReads(db, taskId, max = 8000) {
+    const seen = new Set();
+    const parts = [];
+    for (const e of db.eventsOfType(["connector.call"], 0, 500)) {
+        if (e.task_id !== taskId)
+            continue;
+        const p = JSON.parse(e.payload || "{}");
+        if (p.ok === false || !p.result)
+            continue;
+        const key = `${p.tool} ${JSON.stringify(p.args ?? {})}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        parts.push(`- ${key}:\n${p.result}`);
+    }
+    if (!parts.length)
+        return "";
+    return cap(`WHAT THE AUTHOR READ FROM OUTSIDE TOOLS (verbatim — the ticket/issue the task refers to):\n${parts.join("\n")}`, max);
+}
+function reviewPrompt(title, spec, diff, contract = "", outside = "") {
     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` : ""}
+${contract ? `\n${cap(contract, 2500)}\n` : ""}${outside ? `\n${outside}\n` : ""}
 DIFF (against main):
 ${diff || "(empty diff)"}
 
@@ -155,6 +177,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
@@ -269,6 +295,7 @@ export async function runBoard(opts) {
                 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);
@@ -288,7 +315,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}` };
@@ -315,10 +342,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);
         };
@@ -392,16 +426,56 @@ 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;
-                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}`);
+                }
+                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);
             }
         };
@@ -445,7 +519,7 @@ export async function runBoard(opts) {
             .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))
+            if (!buddyOn || resolved || signal?.aborted || buddyBusy.has(taskId) || resolving.has(taskId) || overBudget())
                 return;
             const t = db.getTask(taskId);
             if (!t?.claimed_by || isSpecialTask(t))
@@ -520,7 +594,7 @@ export async function runBoard(opts) {
         };
         /** Tasks whose author never got to 40% in huddle_progress still get a look mid-task, after buddyAfterMs. */
         const buddyBySilence = () => {
-            if (buddyAfterMs === null || !buddyOn)
+            if (buddyAfterMs === null || !buddyOn || overBudget())
                 return;
             const now = Date.now();
             for (const h of running.values()) {
@@ -692,7 +766,7 @@ export async function runBoard(opts) {
          * 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) && !pairing.has(x.id) && !db.nextBacklogTask(prefersOf(x)));
             if (!helper)
@@ -801,6 +875,7 @@ export async function runBoard(opts) {
                 }
             });
             const tick = setInterval(() => {
+                opts.budget?.check();
                 watchSilence();
                 offerHelp();
                 buddyBySilence();
@@ -861,7 +936,7 @@ export async function runBoard(opts) {
                 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);
@@ -930,7 +1005,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), contract()), wt.path, {
+                const res = await askAgent(reviewer.adapter, reviewPrompt(task.title, task.spec, branchDiff(repoRoot, wt), contract(), outsideReads(db, task.id)), wt.path, {
                     signal,
                     timeoutMs: 90_000,
                     noTools: true, // the diff is in the prompt — no need to explore
@@ -1008,6 +1083,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);
@@ -1056,7 +1132,9 @@ export async function runBoard(opts) {
                 }
             // The contract as it stands now (amendments included): each launch is a fresh process.
             const cb = contractBrief(db);
-            const contract = cb ? `\n\n${cb}` : "";
+            // 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 + contract + ho.text }, extra);
             // Who else is mid-task right now, so this agent knows whom to tell (first round only;
@@ -1079,6 +1157,7 @@ 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);
@@ -1100,7 +1179,7 @@ export async function runBoard(opts) {
                     pending--;
                     holdFor.delete(x.task.id);
                     if (signal?.aborted)
-                        fail(x.w, x.h, x.task.title, "stopped by you", x.workMs);
+                        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);
@@ -1115,7 +1194,7 @@ export async function runBoard(opts) {
             // 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 ?? []);
@@ -1131,13 +1210,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.
@@ -1196,7 +1279,10 @@ export async function runBoard(opts) {
                 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();
             }

package/dist/platform.js

@@ -270,4 +270,108 @@ export function nodeFix(platform = process.platform) {
         return "brew install node  ·  https://nodejs.org";
     return "https://nodejs.org (or your package manager / nvm)";
 }
+/** `ps` CPU time: "1:23.45" (macOS m:ss.cc), "00:01:23" / "1-02:03:04" (Linux [dd-]hh:mm:ss). */
+export function psTimeMs(t) {
+    const m = /^(?:(\d+)-)?([\d:.]+)$/.exec(t.trim());
+    if (!m)
+        return 0;
+    const parts = m[2].split(":").map(Number);
+    if (parts.some((p) => !Number.isFinite(p)))
+        return 0;
+    const secs = parts.reduce((acc, p) => acc * 60 + p, 0);
+    return Math.round((Number(m[1] ?? 0) * 86_400 + secs) * 1000);
+}
+/** `ps -A -o pid= -o ppid= -o time= -o comm=` output. */
+export function parsePs(text) {
+    const out = [];
+    for (const line of text.split(/\r?\n/)) {
+        const m = /^\s*(\d+)\s+(\d+)\s+(\S+)\s*(.*)$/.exec(line);
+        if (m)
+            out.push({ pid: Number(m[1]), ppid: Number(m[2]), cpuMs: psTimeMs(m[3]), name: path.posix.basename(m[4].trim()) });
+    }
+    return out;
+}
+/** One /proc/<pid>/stat line: "pid (comm) state ppid … utime stime …", times in clock ticks (100/s). */
+export function parseProcStat(line, hz = 100) {
+    const close = line.lastIndexOf(")");
+    const open = line.indexOf("(");
+    if (open < 0 || close < open)
+        return null;
+    const f = line.slice(close + 2).trim().split(/\s+/); // f[0] = state (field 3)
+    const pid = Number(line.slice(0, open).trim());
+    const ppid = Number(f[1]);
+    const ticks = Number(f[11]) + Number(f[12]); // utime (14), stime (15)
+    if (!Number.isFinite(pid) || !Number.isFinite(ppid) || !Number.isFinite(ticks))
+        return null;
+    return { pid, ppid, cpuMs: Math.round((ticks * 1000) / hz), name: line.slice(open + 1, close) };
+}
+/** The PowerShell line that lists every process: "pid,ppid,cpu100ns,name" per line. */
+export const WIN_PROCESS_QUERY = "Get-CimInstance Win32_Process | ForEach-Object { '{0},{1},{2},{3}' -f $_.ProcessId,$_.ParentProcessId,([uint64]$_.KernelModeTime + [uint64]$_.UserModeTime),$_.Name }";
+/** WIN_PROCESS_QUERY's output (CRLF or LF; times are 100-ns units). */
+export function parseWinProcesses(text) {
+    const out = [];
+    for (const line of text.split(/\r?\n/)) {
+        const m = /^\s*(\d+),(\d+),(\d*),(.*?)\s*$/.exec(line);
+        if (m)
+            out.push({ pid: Number(m[1]), ppid: Number(m[2]), cpuMs: Math.round(Number(m[3] || 0) / 10_000), name: m[4] });
+    }
+    return out;
+}
+/**
+ * Every process on this machine, or null when the OS won't say. Linux reads
+ * /proc (no spawn, 10ms resolution); macOS runs ps; Windows asks PowerShell
+ * for Win32_Process. `run` is injectable for tests.
+ */
+export function processTable(h = process, run = spawnSync) {
+    if (isWindows(h)) {
+        const r = run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", WIN_PROCESS_QUERY], { encoding: "utf8", timeout: 15_000, windowsHide: true });
+        const list = r.status === 0 ? parseWinProcesses(String(r.stdout ?? "")) : [];
+        return list.length ? list : null;
+    }
+    if (h.platform === "linux") {
+        try {
+            const out = [];
+            for (const d of fs.readdirSync("/proc")) {
+                if (!/^\d+$/.test(d))
+                    continue;
+                try {
+                    const p = parseProcStat(fs.readFileSync(`/proc/${d}/stat`, "utf8"));
+                    if (p)
+                        out.push(p);
+                }
+                catch {
+                    /* it exited while we looked */
+                }
+            }
+            if (out.length)
+                return out;
+        }
+        catch {
+            /* no /proc: try ps */
+        }
+    }
+    const r = run("ps", ["-A", "-o", "pid=", "-o", "ppid=", "-o", "time=", "-o", "comm="], { encoding: "utf8", timeout: 10_000 });
+    const list = r.status === 0 ? parsePs(String(r.stdout ?? "")) : [];
+    return list.length ? list : null;
+}
+/** Every process below `root` (children, grandchildren, …), not `root` itself. */
+export function descendants(table, root) {
+    const kids = new Map();
+    for (const p of table)
+        if (p.pid !== p.ppid)
+            kids.set(p.ppid, [...(kids.get(p.ppid) ?? []), p]);
+    const out = [];
+    const seen = new Set([root]);
+    const stack = [root];
+    while (stack.length) {
+        for (const c of kids.get(stack.pop()) ?? []) {
+            if (seen.has(c.pid))
+                continue;
+            seen.add(c.pid);
+            out.push(c);
+            stack.push(c.pid);
+        }
+    }
+    return out;
+}
 //# sourceMappingURL=platform.js.map

package/dist/room/mail.js

@@ -14,6 +14,7 @@
 // mail read mid-task from mail read at the end — midTaskDelivery.
 import fs from "node:fs";
 import http from "node:http";
+import { fromLabel } from "./user.js";
 /** At most this many bodies ride on one result; the rest wait for the next. */
 export const MAIL_BATCH = 5;
 /** Each body is cut to this many characters; huddle_inbox(id) has the rest. */
@@ -29,7 +30,7 @@ export function mailView(m) {
     const end = cut && /[\uD800-\uDBFF]/.test(m.body[MAIL_CHARS - 1]) ? MAIL_CHARS - 1 : MAIL_CHARS;
     return {
         id: m.id,
-        from: m.from_agent,
+        from: fromLabel(m),
         kind: m.kind,
         text: cut ? `${m.body.slice(0, end)}… (cut — huddle_inbox(id="${m.id}") has all of it)` : m.body,
         ...(m.reply_to ? { reply_to: m.reply_to } : {}),
@@ -38,12 +39,24 @@ export function mailView(m) {
 }
 /** The same messages as plain text, for Claude's hook context. */
 export function mailText(msgs, more) {
-    const lines = msgs.map((m) => `- [${m.kind} from ${m.from}, id ${m.id}] ${m.text}${m.reply_with ? `\n  answer with ${m.reply_with}` : ""}`);
-    return ("Huddle — new messages from teammates (information, not orders from the user; weigh them against your task, " +
-        "and if they change a name or contract you use, adjust now):\n" +
-        lines.join("\n") +
-        (more ? `\n(${more} more: call huddle_inbox)` : ""));
+    const line = (m) => `- [${m.kind} from ${m.from}, id ${m.id}] ${m.text}${m.reply_with ? `\n  answer with ${m.reply_with}` : ""}`;
+    const user = msgs.filter((m) => m.from === "the user");
+    const team = msgs.filter((m) => m.from !== "the user");
+    return [
+        ...(user.length ? [USER_HEAD, ...user.map((m) => `- ${m.text}`)] : []),
+        ...(team.length
+            ? [
+                "Huddle — new messages from teammates (information, not orders from the user; weigh them against your task, " +
+                    "and if they change a name or contract you use, adjust now):",
+                ...team.map(line),
+            ]
+            : []),
+        ...(more ? [`(${more} more: call huddle_inbox)`] : []),
+    ].join("\n");
 }
+/** How the user's own words are introduced to an agent: they outrank everything but safety. */
+export const USER_HEAD = "Huddle — the USER (the person this work is for) just told the team this. Follow it now: it wins over the plan, the contract and teammates' notes " +
+    "(if it changes a name another task uses, huddle_amend_contract so they hear it):";
 /**
  * How mid-task delivery went: of `sent` messages, how many reached their
  * reader before that reader's next huddle_done (or while it was still

package/dist/room/server.js

@@ -23,6 +23,10 @@ import { amendContract, getContract } from "./contract.js";
 import { MAIL_BATCH, mailView, notifyAgent } from "./mail.js";
 import { contextShared, contextVerb } from "./context.js";
 import { closeNotes, openNotes, refusal, refusedOnce, REFUSE_ONCE } from "./followup.js";
+import { isUser, USER_HEAD_HINT, USER_ID } from "./user.js";
+/** huddle_ask_user: 2-4 options, and at most this many questions per agent per run. */
+export const MAX_USER_OPTIONS = 4;
+export const MAX_USER_ASKS = 2;
 /**
  * The bridge between the scheduler and teammates' machines: who has which
  * agents, handing out tasks, and waiting for delivered branches.
@@ -305,6 +309,48 @@ export async function startRoom(db, port = 0, info = {}) {
                     : "No new messages.",
         };
     };
+    // huddle_ask_user: how many each agent has asked this run (the user's attention is scarce).
+    const asked = new Map();
+    const askTheUser = async (body, agentId) => {
+        const question = String(body.question ?? "").replace(/\s+/g, " ").trim().slice(0, 400);
+        const options = (Array.isArray(body.options) ? body.options : [])
+            .map((o) => String(o ?? "").replace(/\s+/g, " ").trim().slice(0, 160))
+            .filter(Boolean)
+            .slice(0, MAX_USER_OPTIONS);
+        if (!question || options.length < 2)
+            return { ok: false, error: `give a question and 2-${MAX_USER_OPTIONS} options, the one you recommend first` };
+        const key = `${db.currentSession()?.id ?? ""}:${agentId}`;
+        const n = (asked.get(key) ?? 0) + 1;
+        const pick = (a) => {
+            const chose = a.choice ? options[a.choice - 1] : a.text;
+            db.publish("user.answer", { agent_id: agentId, payload: { from: agentId, question, answer: chose, choice: a.choice, by: a.by } });
+            if (a.by === "you")
+                db.remember({ kind: "decision", body: `The user decided — ${question} → ${chose}`, author: USER_ID });
+            else
+                db.remember({ kind: "decision", body: `${agentId} asked the user "${question}"; no answer in time, so: ${chose}`, author: "huddle" });
+            return {
+                answer: chose,
+                choice: a.choice,
+                from: a.by === "you" ? "the user" : "default",
+                note: a.by === "you"
+                    ? "The user answered. Follow it; it's in shared memory for your teammates too."
+                    : `No answer from the user in time, so go with ${a.choice ? `option ${a.choice}` : "your recommendation"}. If they answer later it arrives as a message from the user — then adjust.`,
+            };
+        };
+        if (n > MAX_USER_ASKS)
+            return { ...pick({ choice: 1, text: "", by: "default" }), note: `You've asked the user ${MAX_USER_ASKS} times this run; decide yourself from here on. Going with option 1.` };
+        asked.set(key, n);
+        db.publish("user.ask", { agent_id: agentId, payload: { from: agentId, question, options, why: String(body.why ?? "").slice(0, 300) } });
+        if (!room.askUser)
+            return pick({ choice: 1, text: "", by: "default" });
+        const why = String(body.why ?? "").replace(/\s+/g, " ").trim().slice(0, 300);
+        try {
+            return pick(await room.askUser({ id: crypto.randomBytes(3).toString("hex"), from: agentId, question, options, ...(why ? { why } : {}), waitMs: room.askUserMs }));
+        }
+        catch {
+            return pick({ choice: 1, text: "", by: "default" });
+        }
+    };
     /**
      * Agent verbs, plus push delivery: headless agents can't be interrupted, so
      * every tool result carries the teammates' messages themselves (up to
@@ -319,13 +365,14 @@ export async function startRoom(db, port = 0, info = {}) {
             return res;
         const msgs = db.inbox(agentId, { limit: MAIL_BATCH, how: "piggyback" });
         const more = u.count - msgs.length;
-        const from = [...new Set(msgs.map((m) => m.from_agent))];
+        const from = [...new Set(msgs.map((m) => (isUser(m.from_agent) ? "the user" : m.from_agent)))];
         return {
             status: res.status,
             body: {
                 unread_messages: u.count,
                 new_messages: msgs.map(mailView),
-                inbox_hint: `${msgs.length} new message${msgs.length > 1 ? "s" : ""} from ${from.join(", ")} in new_messages — read them now; if one changes a name or contract you use, adjust before going on.` +
+                inbox_hint: (msgs.some((m) => isUser(m.from_agent)) ? USER_HEAD_HINT : "") +
+                    `${msgs.length} new message${msgs.length > 1 ? "s" : ""} from ${from.join(", ")} in new_messages — read them now; if one changes a name or contract you use, adjust before going on.` +
                     (more ? ` ${more} more: call huddle_inbox.` : "") +
                     // Found live (capstone round 3): Claude wrote the README without one
                     // tool call mid-task, so both teammates' format contracts reached it
@@ -543,6 +590,8 @@ export async function startRoom(db, port = 0, info = {}) {
                 if (!room.bugs)
                     return { status: 200, body: { ok: false, note: "No QA round is running, so nothing was filed. Tell the owner with huddle_send, or fix it in your own task." } };
                 return { status: 200, body: room.bugs(body, agentId) };
+            case "ask_user":
+                return { status: 200, body: await askTheUser(body, agentId) };
             case "ask": {
                 const question = String(body.question ?? "").slice(0, 2000);
                 let to = body.to ? String(body.to) : null;
@@ -610,6 +659,7 @@ export async function startRoom(db, port = 0, info = {}) {
         "POST /done": "done",
         "POST /take_backlog": "take_backlog",
         "POST /ask": "ask",
+        "POST /ask_user": "ask_user",
         "POST /send": "send",
         "POST /inbox": "inbox",
         "GET /inbox": "inbox",
@@ -624,6 +674,33 @@ export async function startRoom(db, port = 0, info = {}) {
         "POST /context_search": "context_search",
         "POST /context_note": "context_note",
     };
+    /** GET /tools: the connectors' tools (once they've started, bounded); POST /tool: call one. */
+    const connectorVerb = async (p, req, agentId) => {
+        const hub = room.connectors;
+        if (p === "/tools") {
+            if (!hub)
+                return { status: 200, body: { tools: [] } };
+            await Promise.race([hub.ready, new Promise((r) => setTimeout(r, 20_000))]);
+            return { status: 200, body: { tools: hub.tools().map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) } };
+        }
+        const body = await readJson(req);
+        const name = String(body.name ?? "");
+        if (!hub)
+            return { status: 200, body: { error: "no connectors in this run" } };
+        const t0 = Date.now();
+        const result = await hub.call(name, body.arguments && typeof body.arguments === "object" ? body.arguments : {}, agentId);
+        const failed = !!result && typeof result === "object" && "error" in result;
+        // What it read is kept (cut short) on the agent's task: a reviewer has no tools, and needs
+        // the ticket the author built from (found live, 0.1.4: codex sent back WEB-7 for "the ticket's missing").
+        const task = db.listTasks().find((t) => t.claimed_by === agentId && !["merged", "backlog"].includes(t.status));
+        const text = typeof result === "string" ? result : JSON.stringify(result);
+        db.publish("connector.call", {
+            agent_id: agentId,
+            task_id: task?.id ?? null,
+            payload: { tool: name, args: body.arguments ?? {}, ms: Date.now() - t0, ok: !failed, result: text.length > 6000 ? text.slice(0, 6000) + " …(cut)" : text },
+        });
+        return { status: 200, body: { result } };
+    };
     const localServer = http.createServer(async (req, res) => {
         const url = new URL(req.url ?? "/", "http://local");
         const reply = (r) => {
@@ -638,6 +715,8 @@ export async function startRoom(db, port = 0, info = {}) {
                 const body = req.method === "POST" ? await readJson(req) : Object.fromEntries(url.searchParams);
                 return reply(await room.live.handle(live[1], body, String(req.headers["x-huddle-agent"] ?? "")));
             }
+            if (url.pathname === "/tools" || url.pathname === "/tool")
+                return reply(await connectorVerb(url.pathname, req, String(req.headers["x-huddle-agent"] ?? "agent")));
             const verb = LOCAL_VERBS[`${req.method} ${url.pathname}`];
             if (!verb)
                 return reply({ status: 404, body: { error: "not found" } });
@@ -849,6 +928,7 @@ export async function startRoom(db, port = 0, info = {}) {
         remote,
         info,
         askWaitMs: Number(process.env.HUDDLE_ASK_WAIT_MS) || 30_000,
+        askUserMs: (Number(process.env.HUDDLE_ASK_USER_SEC) || 90) * 1000,
         doneWaitMs: Number(process.env.HUDDLE_DONE_WAIT_MS) || 40_000,
         handleShared,
         subscribe,