huddle-cli 0.1.1 → 0.1.3

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. */
@@ -155,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
@@ -269,6 +275,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 +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}` };
@@ -315,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);
         };
@@ -392,16 +406,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;
+                }
+                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;
-                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}`);
+                busyWatch.forget(id);
                 stopChild(h.child);
             }
         };
@@ -445,7 +499,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 +574,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 +746,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 +855,7 @@ export async function runBoard(opts) {
                 }
             });
             const tick = setInterval(() => {
+                opts.budget?.check();
                 watchSilence();
                 offerHelp();
                 buddyBySilence();
@@ -861,7 +916,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);
@@ -1008,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);
@@ -1056,7 +1112,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 +1137,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 +1159,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 +1174,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 +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.
@@ -1196,7 +1259,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",
@@ -849,6 +899,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,

package/dist/room/user.js

@@ -0,0 +1,54 @@
+// The person at the keyboard, as a member of the room.
+//
+// Found live (0.1.2 test): mid-run there was no way to tell the agents
+// anything; a typed line only queued the next goal. Now a line typed during a
+// run reaches every agent that's working, sent as "you", and it outranks
+// teammates' notes: they are information; this is the person the work is for.
+// Agents that start later get every such note in their launch prompt.
+/** The user's id in messages and shared memory. Never an agent's id. */
+export const USER_ID = "you";
+export const isUser = (from) => from === USER_ID;
+/** The prefix of a note from the user in shared memory. */
+const SAID = "The user said: ";
+/**
+ * Send what the user typed to the agents working now (or to `to`, an agent
+ * id), and keep it in shared memory so every task that starts later gets it.
+ * Returns who got it now.
+ */
+export function sayToAgents(db, text, to) {
+    const body = text.trim();
+    if (!body)
+        return { now: [], saved: false };
+    const working = db.listAgents().filter((a) => a.status === "working").map((a) => a.id);
+    const want = to?.trim().replace(/^@/, "").toLowerCase();
+    const now = want ? working.filter((id) => id.toLowerCase() === want || id.toLowerCase().split("#")[0] === want) : working;
+    for (const id of now)
+        db.sendMessage({ from: USER_ID, to: id, body, kind: "note" });
+    // Addressed to one agent: it's for that agent's task, not every later one.
+    if (!want)
+        db.remember({ kind: "decision", body: SAID + body, author: USER_ID });
+    return { now, saved: !want };
+}
+/** Everything the user said this run, for the launch prompt of a task that starts now. */
+export function userBrief(db) {
+    const since = db.currentSession()?.created_at ?? 0;
+    const said = db
+        .recall()
+        .filter((m) => m.author === USER_ID && m.created_at >= since)
+        .reverse()
+        .map((m) => `- ${m.body.startsWith(SAID) ? m.body.slice(SAID.length) : m.body}`);
+    if (!said.length)
+        return "";
+    return [
+        "FROM THE USER — the person this work is for said this during the run. Follow it: it wins over the plan and the contract",
+        "(if it changes a name another task uses, huddle_amend_contract so they hear it too):",
+        ...said.slice(-10),
+    ].join("\n");
+}
+/** How a message reads in an agent's tool result: the user's are marked as theirs. */
+export function fromLabel(m) {
+    return isUser(m.from_agent) ? "the user" : m.from_agent;
+}
+/** Leads a tool result's inbox hint when the user wrote. */
+export const USER_HEAD_HINT = 'The USER (the person this work is for) wrote to the team — see new_messages sent by "the user". Follow it now: it wins over the plan, the contract and teammates\' notes. ';
+//# sourceMappingURL=user.js.map