huddle-cli 0.0.0-stage → 0.1.1

package/dist/orchestrator/takeover.js

@@ -0,0 +1,240 @@
+// Takeovers: agents take on other agents' tasks.
+//
+// Rescue (scheduler-driven): a task whose agent crashed, stayed red after its
+// fix round, or went silent is re-offered to a DIFFERENT agent, which continues
+// in the original worktree — the first agent's edits are already there — with
+// a brief: why it stopped, the test output, and what the first agent posted.
+// One takeover per task; if the rescuer can't land it either, it's parked for
+// you with the branch kept.
+//
+// Split (agent-driven): a busy agent hands a part of its task to the room
+// (huddle_split); a free agent picks it up like any backlog task. The
+// scheduler nudges busy agents when a teammate is free (huddle_offer_help).
+import fs from "node:fs";
+const cap = (s, n) => (s.length > n ? s.slice(0, n) + "…" : s);
+const parse = (s) => {
+    try {
+        return JSON.parse(s || "{}");
+    }
+    catch {
+        return {};
+    }
+};
+/** Minutes without output or a huddle_* call before an agent counts as silent. HUDDLE_SILENCE_MIN overrides. */
+export const DEFAULT_SILENCE_MS = 10 * 60_000;
+/** How long a task runs before a free agent offers to take part of it. HUDDLE_HELP_AFTER_SEC overrides; 0 = at once, "off" = never. */
+export const DEFAULT_HELP_AFTER_MS = 60_000;
+export function silenceMsFromEnv() {
+    const v = Number(process.env.HUDDLE_SILENCE_MIN);
+    return v > 0 ? v * 60_000 : DEFAULT_SILENCE_MS;
+}
+export function helpAfterMsFromEnv() {
+    const raw = process.env.HUDDLE_HELP_AFTER_SEC;
+    if (raw === undefined || raw === "")
+        return DEFAULT_HELP_AFTER_MS;
+    if (/^(off|no|never|-)/i.test(raw))
+        return null;
+    const v = Number(raw);
+    return Number.isFinite(v) && v >= 0 ? v * 1000 : DEFAULT_HELP_AFTER_MS;
+}
+function tail(file, bytes) {
+    try {
+        const st = fs.statSync(file);
+        const fd = fs.openSync(file, "r");
+        const n = Math.min(bytes, st.size);
+        const buf = Buffer.alloc(n);
+        fs.readSync(fd, buf, 0, n, st.size - n);
+        fs.closeSync(fd);
+        return buf.toString("utf8").trim();
+    }
+    catch {
+        return "";
+    }
+}
+/** What the rescuer is told: why the first agent stopped, and everything it left behind. */
+export function takeoverBrief(db, o) {
+    const evs = db.eventsOfType(["plan.announced", "task.progress"], o.since - 1, 400).filter((e) => e.task_id === o.taskId);
+    const posted = [];
+    for (const e of evs) {
+        const p = parse(e.payload);
+        if (e.type === "plan.announced" && e.agent_id === o.from)
+            posted.push(`  plan: ${cap(String(p.intent ?? ""), 300)}${Array.isArray(p.touches) && p.touches.length ? ` — touches ${p.touches.slice(0, 12).join(", ")}` : ""}`);
+        if (e.type === "task.progress" && p.note)
+            posted.push(`  progress ${p.pct}%: ${cap(String(p.note), 300)}`);
+    }
+    const notes = db
+        .recall()
+        .filter((m) => m.author === o.from && m.created_at >= o.since)
+        .reverse()
+        .slice(-6)
+        .map((m) => `  ${m.kind}: ${cap(m.body, 300)}${m.why ? ` (why: ${cap(m.why, 160)})` : ""}`);
+    const summary = db.getHandoff(o.taskId)?.summary;
+    const left = [...posted.slice(-10), ...notes, ...(summary ? [`  done summary: ${cap(summary, 400)}`] : [])];
+    const log = o.testOutput === undefined && o.logPath ? tail(o.logPath, 1200) : "";
+    return `
+
+TAKEOVER — ${o.from} started this task and couldn't finish it: ${o.reason}.
+You are taking it over. ${o.from}'s work is ALREADY in your current directory (branch ${o.branch}, uncommitted edits included):
+continue from it — don't start over. Look first (git status, git diff), keep what's right, fix what's wrong, finish the task,
+and make the whole test suite pass. There is one takeover per task: if this doesn't land, it goes to the user.
+
+WHAT ${o.from} POSTED:
+${left.length ? left.join("\n") : "  (nothing — it never called huddle_progress / huddle_remember)"}
+${o.testOutput !== undefined ? `\nLAST TEST OUTPUT (tail):\n${cap(o.testOutput || "(no output)", 3000)}\n` : ""}${log ? `\nEND OF ${o.from}'S LOG (tail):\n${log}\n` : ""}`;
+}
+// --- buddy checks and pairing ---------------------------------------------
+//
+// Found live (3 capstone runs): no takeover or split ever happened — every
+// help offer was declined — and the only reviews came after huddle_done
+// (~9s rubber-stamp APPROVEs). So Huddle now acts on its own, mid-task:
+// a buddy check (another agent reads the work in progress at ~40% and the
+// author gets its notes right away), and pairing (a free agent takes a part
+// of the slowest task unless its author says no).
+/** Progress at which a task's work in progress gets a buddy check; the second only if the first had notes. */
+export const BUDDY_AT = [40, 75];
+/** Pairing only helps a task that is this far behind. */
+export const PAIR_MAX_PCT = 50;
+/**
+ * Can pairing help this task? One that reports progress: while it is under
+ * PAIR_MAX_PCT. One that never reported has no percentage at all (it is not
+ * 0%: it may be nearly done), so only when it has run over twice the help
+ * threshold AND its work so far touches under half of its planned files.
+ * `touched` is lazy: it reads the worktree, only needed for a quiet task.
+ */
+export function pairEligible(t) {
+    if (t.reported)
+        return t.pct < PAIR_MAX_PCT;
+    if (t.ranMs <= 2 * t.helpAfterMs)
+        return false;
+    return t.touched() * 2 < Math.max(t.planned, 1);
+}
+/** How long an author has to say no to a pairing. HUDDLE_PAIR_WAIT_SEC overrides. */
+export const DEFAULT_PAIR_WAIT_MS = 60_000;
+/** First buddy check for a task that never reports progress. HUDDLE_BUDDY_AFTER_SEC overrides; "off" = never. */
+export const DEFAULT_BUDDY_AFTER_MS = 120_000;
+export function buddyAfterMsFromEnv() {
+    const raw = process.env.HUDDLE_BUDDY_AFTER_SEC;
+    if (raw === undefined || raw === "")
+        return DEFAULT_BUDDY_AFTER_MS;
+    if (/^(off|never|no)$/i.test(raw))
+        return null;
+    const v = Number(raw);
+    return Number.isFinite(v) && v >= 0 ? v * 1000 : DEFAULT_BUDDY_AFTER_MS;
+}
+export function pairWaitMsFromEnv() {
+    const v = Number(process.env.HUDDLE_PAIR_WAIT_SEC);
+    return process.env.HUDDLE_PAIR_WAIT_SEC !== undefined && Number.isFinite(v) && v >= 0 ? v * 1000 : DEFAULT_PAIR_WAIT_MS;
+}
+/** QA rounds, QA bug fixes and conflict resolutions are never buddy-checked or paired. */
+export function isSpecialTask(t) {
+    return /^(QA round \d+:|Fix: |Resolve merge conflict)/.test(t.title) || /"(qa|quickfix)"/.test(t.prefers ?? "");
+}
+const stripMd = (l) => l.replace(/[*`#_>]/g, "").trim();
+export function buddyPrompt(o) {
+    return `You're a teammate looking over ${o.author}'s shoulder ${o.when} into their task. Another AI agent is still writing it; nothing is merged.
+
+TASK: ${o.title}
+${cap(o.spec, 1500)}
+${o.contract ? `\n${cap(o.contract, 2500)}\n` : ""}
+OTHER TASKS IN FLIGHT (their work so far):
+${o.others || "(none)"}
+
+${o.author.toUpperCase()}'S WORK SO FAR (diff against main, uncommitted included):
+${o.diff || "(nothing yet)"}
+
+You have NO tools and don't need them. Reply with up to 5 short concrete lines: what will break, what contradicts the task/contract or another in-flight task (name it: function, field, file), what they should do differently.
+Nothing worth changing? Reply exactly LOOKS GOOD. Do not edit anything.`;
+}
+/** Replies that mean "nothing to change", however a model words or decorates them. */
+const ALL_CLEAR = /^(LOOKS (GOOD|FINE)|LGTM|APPROVED?|NO (ISSUES|PROBLEMS|CONCERNS|NOTES)( FOUND)?|NOTHING (TO CHANGE|WORTH CHANGING))( (SO FAR|OVERALL|TO ME))?\b[\s.!:]*$/i;
+/** The buddy's notes, or null for LOOKS GOOD / nothing usable. */
+export function parseBuddy(text) {
+    const lines = String(text ?? "")
+        .split("\n")
+        .map((l) => stripMd(l).replace(/^(?:[-•]|\d+[.)])\s+/, "").trim())
+        .filter(Boolean);
+    // Only a pure all-clear: "Looks good, but cli.js calls listItems" is a note
+    // (real models open with praise, then name the mismatch the check is for).
+    if (!lines.length || ALL_CLEAR.test(lines[0]))
+        return null;
+    // "Here's my take:\nLOOKS GOOD" — a preamble and the all-clear is still the all-clear.
+    if (lines.length <= 2 && lines.some((l) => ALL_CLEAR.test(l)))
+        return null;
+    return lines
+        .slice(0, 5)
+        .map((l) => cap(l, 300))
+        .join("\n");
+}
+export function pairPrompt(o) {
+    return `${o.author} is behind on a task and you (${o.helper}) are free. Propose ONE part of it you could do alongside them, in files they won't edit.
+
+TASK: ${o.title}
+${cap(o.spec, 1500)}
+FILES: ${o.files.join(", ") || "(none listed)"}
+${o.contract ? `\n${cap(o.contract, 2000)}\n` : ""}
+THEIR WORK SO FAR:
+${o.diff || "(nothing yet)"}
+
+You have NO tools. Reply in exactly this form:
+PART: <short title>
+FILES: <comma-separated files you'd own — none they've already edited>
+SPEC: <2-4 lines: what to build, the names/shapes it must match>
+If nothing is cleanly separable, reply exactly NONE.`;
+}
+/** A FILES list as models write it: commas, spaces, backticks or quotes (a quoted name may hold spaces). */
+function fileList(raw) {
+    const out = [];
+    for (const piece of raw.split(/[,;]/)) {
+        const quoted = /^\s*[`'"](.+)[`'"]\s*$/.exec(piece);
+        if (quoted)
+            out.push(quoted[1].trim());
+        else
+            out.push(...piece.split(/\s+/).map((f) => f.replace(/[`'"]/g, "")));
+    }
+    return out.map((f) => f.trim().replace(/^\.\//, "")).filter((f) => f && !/^(none|n\/a|-)$/i.test(f));
+}
+/**
+ * The helper's proposal, or null: NONE, unparseable, a path outside the repo,
+ * a file the author already edited, or the whole of the task's file list
+ * (that isn't a part, it's the task).
+ */
+export function parsePart(text, authorFiles, taskFiles = []) {
+    text = String(text ?? "");
+    const get = (k) => new RegExp(`^\\s*[*_]*${k}[*_]*\\s*:[*_]*\\s*(.+)$`, "im").exec(text)?.[1]?.replace(/[*_]+$/, "").trim();
+    const title = get("PART");
+    if (!title || /^NONE\b/i.test(stripMd(title)))
+        return null;
+    const files = fileList(get("FILES") ?? "");
+    const specAt = text.search(/^\s*[*_]*SPEC[*_]*\s*:/im);
+    const spec = specAt >= 0 ? text.slice(specAt).replace(/^\s*[*_]*SPEC[*_]*\s*:[*_]*\s*/i, "").trim() : "";
+    if (!files.length || !spec)
+        return null;
+    if (files.some((f) => f.startsWith("/") || /^[a-z]:[\\/]/i.test(f) || f.split(/[\\/]/).includes("..")))
+        return null;
+    const norm = (p) => p.replace(/^\.\//, "").replace(/\/+$/, "");
+    const covers = (a, f) => norm(a) === norm(f) || norm(a).startsWith(norm(f) + "/");
+    if (files.some((f) => authorFiles.some((a) => covers(a, f))))
+        return null;
+    if (taskFiles.length && taskFiles.every((t) => files.some((f) => covers(t, f))))
+        return null;
+    return { title: cap(stripMd(title), 120), spec: cap(spec, 2000), files: files.slice(0, 12), tests: false };
+}
+/** Always separable: tests/verification of the task against its spec (+ contract), in a test file of the helper's own. */
+export function testsPart(title, spec) {
+    return {
+        title: cap(`Tests for: ${title}`, 120),
+        spec: `Write the tests / verification for this task against its spec, in a NEW test file of your own (follow the repo's test layout and runner) — ` +
+            `don't edit the task's own files. Test what the spec promises (acceptance points, error paths), not the implementation's internals. ` +
+            `Your tests run against the task's code once it lands.\n\nTHE TASK'S SPEC: ${title}\n${cap(spec, 1500)}`,
+        files: [],
+        tests: true,
+    };
+}
+/** What the author is told: who takes which part, and how to say no. */
+export function pairNote(helper, part, waitMs) {
+    const secs = Math.round(waitMs / 1000);
+    const files = part.files.length ? part.files.join(", ") : "a new test file";
+    return (`${helper} is taking “${part.title}” (files ${files}) in ${secs}s unless you reply huddle_send(to="huddle", message="no: <why>"). ` +
+        (part.files.length ? `Don't edit ${files}; ${helper} owns ${part.files.length > 1 ? "them" : "it"}.` : `Keep building; ${helper} writes the tests against your spec.`));
+}
+//# sourceMappingURL=takeover.js.map

package/dist/platform.js

@@ -0,0 +1,273 @@
+// Running other programs on every OS. Huddle drives CLIs it didn't write, and
+// on Windows most of them aren't .exe files: npm installs `codex` as a
+// `codex.cmd` batch shim, which child_process.spawn can't find without a shell
+// (ENOENT) and refuses to run without one (EINVAL, Node's 2024 fix for
+// CVE-2024-27980). A shell is no answer either: cmd.exe re-parses the whole
+// command line, and prompts are full of quotes, &, %, ^ and newlines.
+//
+// So every agent/tool spawn goes through toolCommand():
+//   macOS / Linux       unchanged — spawn(cmd[0], args), no shell
+//   Windows .exe/.com   the resolved path, no shell
+//   Windows npm shim    node <the shim's script> args — exact argv, no cmd.exe
+//   other .cmd/.bat     cmd.exe /d /s /c with every argument escaped for cmd
+//   .ps1                powershell -File
+// The Windows paths are pure functions of a Host, so tests run them on macOS.
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+export function host() {
+    return {
+        platform: process.platform,
+        env: process.env,
+        isFile: (p) => {
+            try {
+                return fs.statSync(p).isFile();
+            }
+            catch {
+                return false;
+            }
+        },
+        read: (p) => fs.readFileSync(p, "utf8"),
+        execPath: process.execPath,
+    };
+}
+export const isWindows = (h = process) => h.platform === "win32";
+/** An env var by name, case-insensitively — Windows env names are ("Path" vs "PATH"). */
+function envGet(env, name) {
+    if (env[name] !== undefined)
+        return env[name];
+    const k = Object.keys(env).find((x) => x.toUpperCase() === name);
+    return k ? env[k] : undefined;
+}
+/**
+ * Where Windows would find `bin`: each PATH dir, trying each PATHEXT
+ * extension — what `where` does. The current directory is NOT searched (cmd
+ * does that; a repo could plant a codex.cmd). null = not found.
+ */
+export function findOnWindowsPath(bin, h = host()) {
+    const P = path.win32;
+    const exts = (envGet(h.env, "PATHEXT") || ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean);
+    const hasExt = exts.some((e) => bin.toLowerCase().endsWith(e.toLowerCase()));
+    const tries = (base) => (hasExt ? [base] : exts.map((e) => base + e.toLowerCase()));
+    if (/[\\/]/.test(bin))
+        return tries(bin).find(h.isFile) ?? null;
+    for (const raw of (envGet(h.env, "PATH") ?? "").split(";")) {
+        const dir = raw.trim().replace(/^"(.*)"$/, "$1");
+        if (!dir)
+            continue;
+        const hit = tries(P.join(dir, bin)).find(h.isFile);
+        if (hit)
+            return hit;
+    }
+    return null;
+}
+// Cursor's docs now name the CLI `agent` (https://cursor.com/docs/cli/installation);
+// macOS/Linux installs still add `cursor-agent`. If a Windows install only has
+// `agent`, use that.
+const WINDOWS_ALIASES = { "cursor-agent": ["agent"] };
+/** findOnWindowsPath, plus the known alternate names of a CLI. */
+export function resolveWindowsBin(bin, h = host()) {
+    for (const b of [bin, ...(WINDOWS_ALIASES[bin] ?? [])]) {
+        const hit = findOnWindowsPath(b, h);
+        if (hit)
+            return hit;
+    }
+    return null;
+}
+/**
+ * The JS file an npm/cmd-shim batch file runs, if it is one: the shim's
+ * last line is `"%_prog%"  "%dp0%\node_modules\@openai\codex\bin\codex.js" %*`
+ * (older shims: `"%~dp0\node.exe" "%~dp0\..\x.js" %*`).
+ */
+export function npmShimTarget(shim, h = host()) {
+    let text = "";
+    try {
+        text = h.read(shim);
+    }
+    catch {
+        return null;
+    }
+    const m = /"%~?dp0%?\\?([^"%]+\.[cm]?js)"\s+%\*/i.exec(text);
+    if (!m)
+        return null;
+    const target = path.win32.join(path.win32.dirname(shim), m[1]);
+    return h.isFile(target) ? target : null;
+}
+// cmd.exe's special characters. Escaping every one with ^ (the quote too) keeps
+// cmd's quote state from ever toggling, so it sees no operators anywhere.
+const CMD_META = /([()\][%!^"`<>&|;, *?])/g;
+/**
+ * One argument for a cmd.exe command line that runs a batch file. First the
+ * MSVCRT quoting every Windows program parses argv with (backslashes are only
+ * special before a quote), then ^-escape for cmd — twice, because cmd parses
+ * the line once and the batch file's %* expansion parses it again.
+ */
+export function quoteCmdArg(arg) {
+    // cmd can't carry a line break inside a command: it ends the command there.
+    // Only reached for batch files that aren't npm shims, and only a prompt has
+    // newlines, so they become spaces (adapters that can take the prompt on
+    // stdin avoid this path entirely).
+    let a = arg.replace(/\r?\n/g, " ");
+    a = a.replace(/(\\*)"/g, (_m, bs) => bs + bs + '\\"').replace(/(\\*)$/, (_m, bs) => bs + bs);
+    a = `"${a}"`;
+    return a.replace(CMD_META, "^$1").replace(CMD_META, "^$1");
+}
+/** The program itself on that command line (it is never re-parsed by %*). */
+export function quoteCmdProgram(file) {
+    return file.replace(CMD_META, "^$1");
+}
+/** How to spawn `cmd` (argv form) on this platform — see the header comment. */
+export function toolCommand(cmd, h = host()) {
+    const [bin, ...args] = cmd;
+    if (!isWindows(h))
+        return { file: bin, args };
+    const resolved = resolveWindowsBin(bin, h);
+    if (!resolved)
+        return { file: bin, args }; // spawn reports ENOENT, as it should
+    const ext = path.win32.extname(resolved).toLowerCase();
+    if (ext === ".cmd" || ext === ".bat") {
+        const script = npmShimTarget(resolved, h);
+        if (script) {
+            // The shim prefers a node.exe next to it, else node on PATH; Huddle's own node is that.
+            const local = path.win32.join(path.win32.dirname(resolved), "node.exe");
+            return { file: h.isFile(local) ? local : h.execPath, args: [script, ...args] };
+        }
+        const line = [quoteCmdProgram(resolved), ...args.map(quoteCmdArg)].join(" ");
+        return { file: envGet(h.env, "COMSPEC") || "cmd.exe", args: ["/d", "/s", "/c", `"${line}"`], verbatim: true };
+    }
+    if (ext === ".ps1")
+        return { file: "powershell.exe", args: ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", resolved, ...args] };
+    return { file: resolved, args };
+}
+/**
+ * Some CLIs read the prompt from stdin when it's left off the command line
+ * (`stdinPrompt`: what goes in its place — "" drops it, "-" for codex). On
+ * Windows Huddle always does that: no quoting, no 32K command-line limit.
+ */
+export function promptOnStdin(cmd, prompt, stdinPrompt, h = process) {
+    if (!isWindows(h) || prompt === undefined || stdinPrompt === undefined)
+        return { cmd };
+    const i = cmd.lastIndexOf(prompt);
+    if (i <= 0)
+        return { cmd };
+    const out = [...cmd];
+    if (stdinPrompt === "")
+        out.splice(i, 1);
+    else
+        out[i] = stdinPrompt;
+    return { cmd: out, stdin: prompt };
+}
+/** spawn() for an agent or tool CLI. `plan` lets the prompt travel on stdin (Windows). */
+export function spawnTool(cmd, opts = {}, plan = {}) {
+    const p = promptOnStdin(cmd, plan.prompt, plan.stdinPrompt);
+    const t = toolCommand(p.cmd);
+    const stdio = p.stdin === undefined ? opts.stdio : withStdinPipe(opts.stdio);
+    const child = spawn(t.file, t.args, { ...opts, stdio, windowsVerbatimArguments: t.verbatim || opts.windowsVerbatimArguments });
+    if (p.stdin !== undefined && child.stdin) {
+        child.stdin.on("error", () => { }); // the CLI may exit before reading it all
+        child.stdin.end(p.stdin);
+    }
+    return child;
+}
+function withStdinPipe(stdio) {
+    if (Array.isArray(stdio))
+        return ["pipe", ...stdio.slice(1)];
+    if (stdio === "inherit")
+        return ["pipe", "inherit", "inherit"];
+    return ["pipe", "pipe", "pipe"];
+}
+export function spawnToolSync(cmd, opts = {}) {
+    const t = toolCommand(cmd);
+    return spawnSync(t.file, t.args, { ...opts, windowsVerbatimArguments: t.verbatim || opts.windowsVerbatimArguments });
+}
+/** Is `bin` on PATH? (`which`, or the PATHEXT search on Windows.) */
+export function onPath(bin, h = host()) {
+    if (isWindows(h))
+        return resolveWindowsBin(bin, h) !== null;
+    return spawnSync("which", [bin], { stdio: "ignore" }).status === 0;
+}
+/**
+ * A shell command line, as [file, args, verbatim]. Installers are written for
+ * the platform's shell: sh on macOS/Linux, PowerShell on Windows
+ * (`irm … | iex`). `cmd.exe` is for project commands like `npm test`.
+ */
+export function shellCommand(line, shell = "default", h = process) {
+    if (!isWindows(h))
+        return { file: "sh", args: ["-c", line] };
+    if (shell === "cmd")
+        return { file: envGet(h.env, "COMSPEC") || "cmd.exe", args: ["/d", "/s", "/c", `"${line}"`], verbatim: true };
+    // Bypass: npm's own npm.ps1 is blocked under the default Restricted policy.
+    return { file: "powershell.exe", args: ["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", line] };
+}
+/** Run a shell command line with the terminal handed over. */
+export function runShell(line, opts = { stdio: "inherit" }, shell = "default") {
+    const t = shellCommand(line, shell);
+    return spawnSync(t.file, t.args, { ...opts, windowsVerbatimArguments: t.verbatim });
+}
+/**
+ * Stop a process and everything it started. POSIX: SIGTERM (the caller
+ * escalates to SIGKILL). Windows has no signals for a process tree —
+ * child.kill() would end only the node shim and orphan the real agent — so
+ * taskkill /T /F ends the whole tree at once.
+ */
+export function killTree(child, h = process, run = spawnSync) {
+    if (isWindows(h) && child.pid) {
+        const r = run("taskkill", ["/T", "/F", "/PID", String(child.pid)], { stdio: "ignore", windowsHide: true });
+        if (r.status === 0)
+            return;
+    }
+    child.kill("SIGTERM");
+}
+/** How long after 'exit' a child's pipes get to drain before we stop waiting for 'close'. */
+export const DRAIN_MS = 2000;
+/**
+ * Call `done` once, when `child` has exited AND its output is in. 'exit' can
+ * come before the last of stdout has been read — when our event loop is busy
+ * (a merge's test run blocks it) an agent's final lines (its token usage, the
+ * log's tail) were lost. So: on 'close' (every pipe drained), but at most
+ * `drainMs` after 'exit', since a CLI's leftover grandchild can hold the pipes
+ * open forever. 'error' (it never ran) is code -1.
+ */
+export function onFinished(child, done, drainMs = DRAIN_MS) {
+    let over = false;
+    const finish = (code) => {
+        if (over)
+            return;
+        over = true;
+        done(code);
+    };
+    child.once("close", (code) => finish(code));
+    child.once("exit", (code) => void setTimeout(() => finish(code), drainMs).unref());
+    child.once("error", () => finish(-1));
+}
+/** Repo-relative path with forward slashes, whatever the OS gave us ("src\\a.ts" → "src/a.ts"). */
+export const slash = (p) => p.replace(/\\/g, "/");
+/**
+ * A hook command line an agent CLI runs through its shell (Claude's
+ * PostToolUse mail hook). sh: single quotes, nothing expands. Windows: the
+ * hook may run under Git Bash, cmd or PowerShell, so every part is
+ * double-quoted with forward slashes (node takes them; C:\Users\Some Name\…
+ * survives all three) — what `huddle connect`'s guard hook does too.
+ */
+export function hookCommand(argv, h = process) {
+    if (!isWindows(h))
+        return argv.map((a) => `'${a.replace(/'/g, `'\\''`)}'`).join(" ");
+    return argv.map((a) => `"${slash(a)}"`).join(" ");
+}
+/** How to install git here, as one line for a message. */
+export function gitFix(platform = process.platform) {
+    if (platform === "win32")
+        return "winget install --id Git.Git -e --source winget  ·  https://git-scm.com/install/windows";
+    if (platform === "darwin")
+        return "xcode-select --install  ·  https://git-scm.com";
+    return "sudo apt install git (Debian/Ubuntu), or your package manager  ·  https://git-scm.com";
+}
+/** How to install (or upgrade to) Node.js LTS here. */
+export function nodeFix(platform = process.platform) {
+    if (platform === "win32")
+        return "winget install OpenJS.NodeJS.LTS  ·  https://nodejs.org";
+    if (platform === "darwin")
+        return "brew install node  ·  https://nodejs.org";
+    return "https://nodejs.org (or your package manager / nvm)";
+}
+//# sourceMappingURL=platform.js.map

package/dist/preflight.js

@@ -0,0 +1,31 @@
+// Runs before anything else in cli.ts (it's the first import, and ES modules
+// evaluate in import order): refuse old Node with a plain sentence instead of
+// a crash deep inside a dependency. No imports beyond node: builtins, so this
+// file works on any Node that can parse the CLI at all.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+export const MIN_NODE = 20;
+const major = Number(process.versions.node.split(".")[0]);
+if (major < MIN_NODE) {
+    console.error(`huddle needs Node.js ${MIN_NODE} or newer — this is ${process.version}.\n` +
+        `  Update Node (https://nodejs.org, or \`nvm install ${MIN_NODE}\`), then: npm install -g huddle-cli`);
+    process.exit(1);
+}
+/** Our own package.json — found by walking up, so it works from dist/ and from the test build. */
+export function packageInfo() {
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 5; i++) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+            if (pkg.name === "huddle-cli")
+                return { name: pkg.name, version: pkg.version };
+        }
+        catch {
+            /* not here — keep walking */
+        }
+        dir = path.dirname(dir);
+    }
+    return { name: "huddle-cli", version: "unknown" };
+}
+//# sourceMappingURL=preflight.js.map

package/dist/relay/server.js

@@ -0,0 +1,113 @@
+// The relay: a tiny, stateless switchboard so rooms work across any networks.
+//
+// Both sides dial OUT to it (which works through NAT, campus Wi-Fi, anything):
+//   host    wss://relay/host/<room>?key=<secret>   — one per room
+//   member  wss://relay/join/<room>                — anyone with the address
+// The relay only forwards frames between a room's members and its host. It
+// can't let anyone in: every request is checked by the host's Room (invite
+// codes, GitHub proofs, member tokens). Nothing is stored; when the host
+// disconnects, the room is gone.
+//
+// Run it anywhere Node runs:  huddle relay --port 8080
+import http from "node:http";
+import crypto from "node:crypto";
+import { WebSocketServer, WebSocket } from "ws";
+const MAX_FRAME = 512 * 1024;
+const MAX_MEMBERS = 64;
+const sha = (s) => crypto.createHash("sha256").update(s).digest("hex");
+export function startRelay(port, log = console.log) {
+    const rooms = new Map();
+    const server = http.createServer((req, res) => {
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify({ huddle: "relay", rooms: rooms.size }));
+    });
+    const wss = new WebSocketServer({ server, maxPayload: MAX_FRAME });
+    wss.on("connection", (ws, req) => {
+        const url = new URL(req.url ?? "/", "http://relay");
+        const [, kind, roomId] = url.pathname.split("/");
+        if (!roomId || !/^[\w-]{8,64}$/.test(roomId))
+            return ws.close(4400, "bad room id");
+        if (kind === "host") {
+            const key = url.searchParams.get("key") ?? "";
+            const existing = rooms.get(roomId);
+            if (existing && existing.keyHash !== sha(key))
+                return ws.close(4403, "room id taken");
+            if (existing)
+                existing.host.close(4409, "replaced by a new host connection");
+            const link = { host: ws, keyHash: sha(key), members: existing?.members ?? new Map() };
+            rooms.set(roomId, link);
+            log(`room ${roomId.slice(0, 6)}… host connected`);
+            ws.on("message", (raw) => {
+                let f;
+                try {
+                    f = JSON.parse(String(raw));
+                }
+                catch {
+                    return;
+                }
+                // host → one member
+                if (f.t === "to" && typeof f.cid === "string") {
+                    const m = link.members.get(f.cid);
+                    if (m?.readyState === WebSocket.OPEN)
+                        m.send(JSON.stringify(f.f));
+                    if (f.close)
+                        m?.close(f.close, "closed by room");
+                }
+            });
+            ws.on("close", () => {
+                if (rooms.get(roomId)?.host !== ws)
+                    return;
+                rooms.delete(roomId);
+                for (const m of link.members.values()) {
+                    if (m.readyState === WebSocket.OPEN)
+                        m.send(JSON.stringify({ t: "closed", code: 1001 }));
+                    m.close(1001, "room closed");
+                }
+                log(`room ${roomId.slice(0, 6)}… closed`);
+            });
+            return;
+        }
+        if (kind === "join") {
+            const link = rooms.get(roomId);
+            if (!link)
+                return ws.close(4404, "no such room (is the host's Huddle open?)");
+            if (link.members.size >= MAX_MEMBERS)
+                return ws.close(4429, "room is full");
+            const cid = crypto.randomBytes(8).toString("hex");
+            link.members.set(cid, ws);
+            ws.on("message", (raw) => {
+                let f;
+                try {
+                    f = JSON.parse(String(raw));
+                }
+                catch {
+                    return;
+                }
+                if (link.host.readyState === WebSocket.OPEN)
+                    link.host.send(JSON.stringify({ t: "from", cid, f }));
+            });
+            ws.on("close", () => {
+                link.members.delete(cid);
+                if (link.host.readyState === WebSocket.OPEN)
+                    link.host.send(JSON.stringify({ t: "gone", cid }));
+            });
+            return;
+        }
+        ws.close(4400, "unknown path");
+    });
+    wss.on("error", () => { }); // listen errors are reported below
+    return new Promise((resolve, reject) => {
+        server.once("error", (e) => reject(new Error(e?.code === "EADDRINUSE" ? `port ${port} is already in use — try --port <another>` : String(e?.message ?? e))));
+        server.listen(port, "0.0.0.0", () => {
+            const actual = server.address().port;
+            resolve({
+                port: actual,
+                close: () => {
+                    wss.close();
+                    server.close();
+                },
+            });
+        });
+    });
+}
+//# sourceMappingURL=server.js.map