huddle-cli 0.1.1 → 0.1.3

package/dist/app/server.js

@@ -0,0 +1,262 @@
+// `huddle app` — the dashboard: a local web page for a repo's runs.
+//
+// It shows the run going on now (from .huddle/live.json, whoever started
+// it), every past run as a conversation (the same records `huddle export`
+// reads), and lets you start a run, answer an agent's question, talk to the
+// agents and stop them (through .huddle/inbox/, app/live.ts).
+//
+// Local only: it listens on 127.0.0.1, every API call needs the token from
+// the URL it prints, and a Host other than localhost is refused (so a web
+// page you visit can't reach it through DNS rebinding).
+import { spawn } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ADAPTERS, LEGACY, applySkips, probeAsync } from "../adapters/index.js";
+import { RoomDB } from "../room/db.js";
+import { splitRuns } from "../ui/story.js";
+import { buildExport, findRun, renderExport, runRows, EXPORT_FORMATS, EXPORT_LEVELS } from "../ui/export.js";
+import { packageInfo } from "../preflight.js";
+import { clearAppInfo, postCommand, readLive, readReport, writeAppInfo } from "./live.js";
+import { appPage } from "./page.js";
+const CLI = fileURLToPath(new URL("../cli.js", import.meta.url));
+const json = (res, status, body) => {
+    res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store" });
+    res.end(JSON.stringify(body));
+};
+function readBody(req, max = 200_000) {
+    return new Promise((resolve, reject) => {
+        let raw = "";
+        req.on("data", (d) => {
+            raw += d;
+            if (raw.length > max)
+                reject(new Error("too large"));
+        });
+        req.on("end", () => {
+            try {
+                resolve(raw ? JSON.parse(raw) : {});
+            }
+            catch {
+                reject(new Error("bad json"));
+            }
+        });
+        req.on("error", reject);
+    });
+}
+/** The default way a run starts from the dashboard: its own process, so closing the page (or the app) doesn't stop it. */
+function spawnRun(root, goal) {
+    const logs = path.join(root, ".huddle", "logs");
+    fs.mkdirSync(logs, { recursive: true });
+    const fd = fs.openSync(path.join(logs, `app-run-${new Date().toISOString().replace(/[:.]/g, "-")}.log`), "a");
+    const child = spawn(process.execPath, [CLI, "join", goal], {
+        cwd: root,
+        detached: true,
+        stdio: ["ignore", fd, fd],
+        env: { ...process.env, NO_COLOR: "1", FORCE_COLOR: undefined },
+        windowsHide: true,
+    });
+    child.unref();
+    fs.closeSync(fd);
+}
+/** Every agent Huddle knows, probed quietly (no spinner rows): who's ready, signed out, skipped. */
+async function probeAgents() {
+    const { skippedAgents } = await import("../ui/app.js");
+    const all = applySkips(await Promise.all(ADAPTERS.map((a) => probeAsync(a))), skippedAgents());
+    return all.filter((r) => !LEGACY.has(r.adapter.id) || r.state === "ready");
+}
+export async function startApp(opts) {
+    const root = opts.root;
+    const dbFile = path.join(root, ".huddle", "huddle.db");
+    fs.mkdirSync(path.dirname(dbFile), { recursive: true });
+    const db = new RoomDB(dbFile);
+    const token = crypto.randomBytes(18).toString("base64url");
+    const startRun = opts.startRun ?? ((goal) => spawnRun(root, goal));
+    let agents = opts.agents ?? null;
+    let probing = null;
+    const probe = () => {
+        probing ??= probeAgents()
+            .then((r) => void (agents = r))
+            .catch(() => void (agents = []))
+            .finally(() => (probing = null));
+        return probing;
+    };
+    if (!agents)
+        void probe();
+    const runsNow = () => splitRuns(db.allEvents());
+    /** Changes whenever the run or the history does: the page refetches on it. */
+    const signature = () => {
+        let live = 0;
+        try {
+            live = fs.statSync(path.join(root, ".huddle", "live.json")).mtimeMs;
+        }
+        catch {
+            /* no run yet */
+        }
+        const last = db.recentEvents(1)[0];
+        return `${live}:${last?.id ?? ""}`;
+    };
+    const state = () => {
+        const runs = runsNow();
+        const live = readLive(root);
+        return {
+            version: packageInfo().version,
+            repo: { name: path.basename(root), root },
+            agents: (agents ?? []).map((r) => ({ id: r.adapter.id, vendor: r.adapter.vendor, state: r.state, detail: r.detail ?? "" })),
+            probing: !agents,
+            live,
+            runs: runRows(runs).reverse(),
+        };
+    };
+    const runDoc = (which) => {
+        const runs = runsNow();
+        const run = findRun(runs, which ?? undefined);
+        if (!run)
+            return null;
+        const doc = buildExport(run, runs.length, { level: "chat", logsDir: path.join(root, ".huddle", "logs"), repoRoot: root });
+        const made = run.events.find((e) => e.type === "plan.made");
+        const plain = made?.p?.plain && typeof made.p.plain === "object" ? made.p.plain : null;
+        return { ...doc, plain, report: readReport(root, run.id) };
+    };
+    const allowedHost = (h, port) => h === `127.0.0.1:${port}` || h === `localhost:${port}`;
+    const server = http.createServer(async (req, res) => {
+        const url = new URL(req.url ?? "/", "http://local");
+        const port = server.address().port;
+        if (!allowedHost(req.headers.host, port))
+            return json(res, 403, { error: "local only" });
+        try {
+            if (req.method === "GET" && url.pathname === "/") {
+                if (url.searchParams.get("t") !== token) {
+                    res.writeHead(403, { "content-type": "text/plain; charset=utf-8" });
+                    return res.end("Open the link `huddle app` printed (it carries a key for this session).");
+                }
+                res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store", "referrer-policy": "no-referrer" });
+                return res.end(appPage(token));
+            }
+            if (!url.pathname.startsWith("/api/"))
+                return json(res, 404, { error: "not found" });
+            // The token: a header for fetches, ?t= for the event stream and downloads.
+            const given = req.headers["x-huddle-token"] ?? url.searchParams.get("t");
+            if (given !== token)
+                return json(res, 401, { error: "no key" });
+            const route = `${req.method} ${url.pathname}`;
+            if (route === "GET /api/state")
+                return json(res, 200, state());
+            if (route === "GET /api/run") {
+                const doc = runDoc(url.searchParams.get("n"));
+                return doc ? json(res, 200, doc) : json(res, 404, { error: "no such run" });
+            }
+            if (route === "GET /api/export") {
+                const runs = runsNow();
+                const run = findRun(runs, url.searchParams.get("n") ?? undefined);
+                if (!run)
+                    return json(res, 404, { error: "no such run" });
+                const format = EXPORT_FORMATS.includes(url.searchParams.get("format") ?? "") ? url.searchParams.get("format") : "html";
+                const level = EXPORT_LEVELS.includes(url.searchParams.get("level") ?? "") ? url.searchParams.get("level") : "chat";
+                const doc = buildExport(run, runs.length, { level, logsDir: path.join(root, ".huddle", "logs"), repoRoot: root });
+                const type = format === "json" ? "application/json" : format === "html" ? "text/html" : "text/markdown";
+                res.writeHead(200, {
+                    "content-type": `${type}; charset=utf-8`,
+                    "content-disposition": `attachment; filename="huddle-run-${run.index}-${level}.${format}"`,
+                });
+                return res.end(renderExport(doc, format));
+            }
+            if (route === "GET /api/events") {
+                res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-store", connection: "keep-alive" });
+                let last = "";
+                const tick = () => {
+                    const sig = signature();
+                    if (sig !== last)
+                        res.write(`data: ${JSON.stringify({ sig: (last = sig) })}\n\n`);
+                    else
+                        res.write(": ping\n\n");
+                };
+                tick();
+                const t = setInterval(tick, 1000);
+                req.on("close", () => clearInterval(t));
+                return;
+            }
+            if (route === "POST /api/agents") {
+                agents = null;
+                await probe();
+                return json(res, 200, state());
+            }
+            if (route === "POST /api/goal") {
+                const body = await readBody(req);
+                const goal = String(body.goal ?? "").trim();
+                if (!goal)
+                    return json(res, 400, { error: "say what to build" });
+                if (readLive(root))
+                    return json(res, 409, { error: "a run is already going — talk to it, or stop it first" });
+                startRun(goal);
+                return json(res, 200, { ok: true });
+            }
+            if (route === "POST /api/say" || route === "POST /api/answer" || route === "POST /api/stop") {
+                const body = await readBody(req);
+                if (!readLive(root))
+                    return json(res, 409, { error: "nothing is running" });
+                const c = route === "POST /api/stop"
+                    ? { type: "stop" }
+                    : route === "POST /api/say"
+                        ? { type: "say", text: String(body.text ?? "").slice(0, 4000) }
+                        : { type: "answer", id: String(body.id ?? ""), line: String(body.line ?? "").slice(0, 2000) };
+                if (c.type === "say" && !c.text.trim())
+                    return json(res, 400, { error: "empty" });
+                postCommand(root, c);
+                return json(res, 200, { ok: true });
+            }
+            return json(res, 404, { error: "not found" });
+        }
+        catch (e) {
+            return json(res, 500, { error: e?.message ?? String(e) });
+        }
+    });
+    const port = await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(opts.port ?? 0, "127.0.0.1", () => resolve(server.address().port));
+    });
+    const url = `http://127.0.0.1:${port}/?t=${token}`;
+    writeAppInfo(root, { pid: process.pid, url });
+    const close = () => {
+        server.closeAllConnections?.();
+        server.close();
+        clearAppInfo(root);
+        db.close();
+    };
+    return { url, port, token, close };
+}
+/** `huddle app [--port n] [--no-open]` */
+export async function runApp(args) {
+    const { C } = await import("../ui/term.js");
+    const { isGitRepo } = await import("../sandbox/worktree.js");
+    const { ensureInit, repoRoot } = await import("../ui/app.js");
+    if (!isGitRepo(process.cwd()) || !ensureInit()) {
+        console.log(C.red("✗ Not a git repo.") + " Run `huddle app` inside a project (`git init` makes one).");
+        process.exitCode = 1;
+        return;
+    }
+    const i = args.indexOf("--port");
+    const port = i >= 0 ? Number(args[i + 1]) : undefined;
+    const app = await startApp({ root: repoRoot(), port });
+    console.log(`${C.green("✓")} Huddle is open at ${C.bold(app.url)}`);
+    console.log(C.faint("  runs keep going if you close the page · ctrl-c closes the dashboard"));
+    if (!args.includes("--no-open"))
+        openBrowser(app.url);
+    const bye = () => {
+        app.close();
+        process.exit(0);
+    };
+    process.on("SIGINT", bye);
+    process.on("SIGTERM", bye);
+}
+function openBrowser(url) {
+    const [cmd, ...a] = process.platform === "darwin" ? ["open", url] : process.platform === "win32" ? ["cmd", "/c", "start", "", url] : ["xdg-open", url];
+    try {
+        spawn(cmd, a, { stdio: "ignore", detached: true, windowsHide: true }).on("error", () => { }).unref();
+    }
+    catch {
+        /* no browser: the URL is printed */
+    }
+}
+//# sourceMappingURL=server.js.map

package/dist/args.js

@@ -0,0 +1,18 @@
+// What `huddle <words>` means.
+const COMMANDS = new Set("app dashboard plug init setup agents doctor join board view watch story brief runs export lessons up down peers add ctx context attach land connect disconnect guard mail relay version help".split(" "));
+/**
+ * `huddle build a temperature converter` / `huddle "fix the login bug"`: a goal
+ * in plain words, without `join` or quotes. Found live (0.1.2 test): "as a
+ * normal user, I would never write it like that". A command name, a flag or a
+ * single unknown word stays what it was (an unknown command is still an error).
+ */
+export function asGoal(args) {
+    const [cmd, ...rest] = args;
+    if (!cmd || cmd.startsWith("-") || COMMANDS.has(cmd))
+        return null;
+    const words = [cmd, ...rest.filter((a) => !a.startsWith("--"))].join(" ").trim().split(/\s+/);
+    if (cmd === "build" || cmd === "make" || words.length >= 3 || /\s/.test(cmd))
+        return ["join", ...(cmd === "build" ? rest : args)];
+    return null;
+}
+//# sourceMappingURL=args.js.map

package/dist/attach/connect.js

@@ -19,7 +19,7 @@ import readline from "node:readline";
 import { ADAPTERS } from "../adapters/index.js";
 import { C } from "../ui/term.js";
 import { CLI_PATH, ensureLive, liveFiles, mainRoot } from "./live.js";
-import { LIVE_INSTRUCTIONS } from "./plug.js";
+import { liveInstructions } from "./plug.js";
 const TOML_START = "# >>> huddle connect (remove with `huddle disconnect`) >>>";
 const TOML_END = "# <<< huddle connect <<<";
 // Codex's top-level keys must come before any [table], so the instructions get
@@ -73,7 +73,7 @@ export function wiresFor(adapter, repo, opts = {}) {
                 file: ".cursor/rules/huddle.mdc",
                 kind: "rule",
                 why: "tells Cursor to check in with Huddle before editing",
-                content: `---\ndescription: Coordinate with the other AI sessions in this repo through Huddle\nalwaysApply: true\n---\n\n${LIVE_INSTRUCTIONS}\n`,
+                content: `---\ndescription: Coordinate with the other AI sessions in this repo through Huddle\nalwaysApply: true\n---\n\n${liveInstructions(repo)}\n`,
             });
         return out;
     }
@@ -152,7 +152,7 @@ export function applyWire(w, current, repo) {
             // config-reference). A user's own top-level value wins (TOML forbids two).
             const top = base.split(/^\s*\[/m)[0];
             const own = /^\s*developer_instructions\s*=/m.test(top);
-            const head = own ? "" : `${TOML_TOP_START}\ndeveloper_instructions = ${tomlStr(LIVE_INSTRUCTIONS)}\n${TOML_TOP_END}\n\n`;
+            const head = own ? "" : `${TOML_TOP_START}\ndeveloper_instructions = ${tomlStr(liveInstructions(repo))}\n${TOML_TOP_END}\n\n`;
             return { text: head + (base.trim() ? base.replace(/\n*$/, "\n\n") : "") + codexBlock(livePlug(repo, w.agent)) + "\n" };
         }
         case "claude-hook": {

package/dist/attach/plug.js

@@ -4,6 +4,7 @@
 // no task id: the session says hello to the repo's live room (starting it if
 // needed), and its tools are about sharing the repo safely with the others.
 import { execFileSync } from "node:child_process";
+import path from "node:path";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
@@ -20,6 +21,12 @@ Before you edit ANY file:
 Notes from other sessions arrive in "notes_for_you" on any huddle_* reply — read them and answer with huddle_note. Record lasting decisions with huddle_remember.
 The shared screen holds what your user put up for everyone (logs, docs, screenshots): huddle_context lists it, huddle_context_read / huddle_context_search open it, huddle_context_note pins what you found.
 `.trim();
+/**
+ * LIVE_INSTRUCTIONS plus where the last team run's hand-off brief is
+ * (ui/brief.ts). An attach session may sit in a worktree, so the path is the
+ * main checkout's, absolute.
+ */
+export const liveInstructions = (repo) => `${LIVE_INSTRUCTIONS}\nIf ${path.join(repo, ".huddle", "BRIEF.md")} exists, read it before changing code: the hand-off from the last Huddle team run in this repo (goal, decisions, contract, open issues).`;
 const tools = [
     {
         name: "huddle_peers",
@@ -147,7 +154,7 @@ export async function runLivePlug() {
         }
         throw new Error(`unknown tool: ${name}`);
     };
-    const server = new Server({ name: "huddle", version: packageInfo().version }, { capabilities: { tools: {} }, instructions: LIVE_INSTRUCTIONS });
+    const server = new Server({ name: "huddle", version: packageInfo().version }, { capabilities: { tools: {} }, instructions: liveInstructions(repo) });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: [...tools.map((t) => ({ ...t })), ...screen.map(({ handler: _h, ...t }) => t)],
     }));

package/dist/cli.js

@@ -8,6 +8,7 @@
 //     --agents=claude,codex       only these agents work on this run
 //     --council / --no-council    every agent brainstorms the design first (default: big goals)
 //     --qa / --no-qa              a QA round after the build (default: on for big goals)
+//     --budget=5M                 tokens this run may use: new work stops at 90%, agents at 120%
 //     --with <file|dir|glob>      put files on the shared screen first (repeatable); piped stdin too
 //   huddle setup                install + sign in to the agents you pick (asks first)
 //   huddle doctor               is this machine ready: node, git, room db, your agents
@@ -19,6 +20,9 @@
 //   huddle board                print the board + shared memory
 //   huddle view [repo]          the live view (ctrl-t) from another terminal, read-only
 //   huddle story [--html f]     replay the latest run: who built on whose idea, who said what to whom, merges
+//   huddle brief [--run n]      the hand-off brief a solo agent reads after a run (off|on: the CLAUDE.md/AGENTS.md pointer)
+//   huddle runs                 every run in this repo: goal, agents, result, cost
+//   huddle export [run]         a run as summary / chat / full transcript (md, html, json)
 //   huddle lessons              what Huddle learned across runs (--forget <id>, --clear)
 //   huddle init                 set up .huddle/ in this repo (automatic on first run)
 //   huddle up | down            attach mode: start/stop this repo's live room
@@ -33,6 +37,7 @@
 //   huddle mail --hook          (internal) Claude's post-tool hook: teammates' new messages
 import { packageInfo } from "./preflight.js"; // first: refuses old Node before anything else loads
 import { C, useAsciiOutput } from "./ui/term.js";
+import { asGoal } from "./args.js";
 import { SqliteUnavailableError } from "./room/sqlite.js";
 // Everything heavier loads per command: `huddle mail --hook` runs after every
 // one of Claude's tool calls and has to start in well under 300ms.
@@ -49,14 +54,22 @@ const USAGE = `${C.violet("huddle")} — your agents, in the same room
     ${B("--approvals=safe|auto|yolo")} what agents may do unasked ${F("(default auto)")}
     ${B("--council")} ${F("/")} ${B("--no-council")}   design council first ${F("(default: big goals)")}
     ${B("--qa")} ${F("/")} ${B("--no-qa")}             agents re-check the build ${F("(default: big goals)")}
+    ${B("--budget=5M")}                tokens it may use ${F("(stops new work at 90%)")}
     ${B("--with <file>")}              put a file, folder or glob on the shared screen
                                ${F("(repeatable; or pipe: cat log | huddle join …)")}
+  ${B("huddle app")}                   the dashboard: live run, history, talk to agents
   ${B("huddle join <address> <CODE>")} join someone's room from an invite
 
   ${F("watch and replay")}
   ${B("huddle view")} ${F("[repo]")}           watch a run live, read-only, from a 2nd terminal
   ${B("huddle story")} ${F("[--html f]")}      replay the last run: ideas, contract, merges
                                ${F("(--list, --run n)")}
+  ${B("huddle brief")} ${F("[--run n]")}       what the last run left for your next solo agent
+                               ${F("(off / on: its pointer in CLAUDE.md, AGENTS.md)")}
+  ${B("huddle runs")}                  every run here: goal, agents, result, cost
+  ${B("huddle export")} ${F("[run]")}         a run as a chat you can read or share
+                               ${F("(--level summary|chat|full, --out <path>,")}
+                               ${F(" --format md|html|json, --no-redact)")}
   ${B("huddle board")}                 print the board
   ${B("huddle lessons")} ${F("[--forget id]")} what earlier runs taught your agents ${F("(--clear)")}
 
@@ -81,7 +94,8 @@ const USAGE = `${C.violet("huddle")} — your agents, in the same room
   ${B("huddle up")} ${F("/")} ${B("down")} ${F("/")} ${B("disconnect")} start · stop the live room · unwire
 `;
 async function main() {
-    const [cmd, ...rest] = process.argv.slice(2);
+    const argv = process.argv.slice(2);
+    const [cmd, ...rest] = asGoal(argv) ?? argv;
     // Legacy Windows consoles get ASCII glyphs. Not for the machine-read channels: the Plug's JSON-RPC and Claude's hooks.
     if (!["plug", "guard", "mail"].includes(cmd ?? ""))
         useAsciiOutput();
@@ -167,8 +181,12 @@ async function main() {
             // --council: every agent brainstorms the design first; --no-council: the brain plans alone.
             const council = rest.includes("--no-council") ? false : rest.includes("--council") ? true : undefined;
             const qa = rest.includes("--no-qa") ? false : rest.includes("--qa") ? true : undefined;
-            return runGoal(goal, { results, probed, mode: rest.includes("--plan") ? "plan" : "auto", approvals, council, qa });
+            const budget = rest.find((a) => a.startsWith("--budget="))?.split("=")[1];
+            return runGoal(goal, { results, probed, mode: rest.includes("--plan") ? "plan" : "auto", approvals, council, qa, budget });
         }
+        case "app":
+        case "dashboard":
+            return (await import("./app/server.js")).runApp(rest);
         case "board":
             return (await app()).printBoard();
         case "view":
@@ -176,6 +194,12 @@ async function main() {
             return (await import("./ui/watch.js")).runView(rest);
         case "story":
             return (await import("./ui/story.js")).runStory(rest);
+        case "brief":
+            return (await import("./ui/brief.js")).runBrief(rest);
+        case "runs":
+            return (await import("./ui/export.js")).runRuns(rest);
+        case "export":
+            return (await import("./ui/export.js")).runExport(rest);
         case "lessons":
             return (await import("./ui/lessons.js")).runLessons(rest);
         case "up":

package/dist/mcp/server.js

@@ -141,6 +141,24 @@ const TOOLS = [
         },
         handler: (a) => room("/ask", "POST", { question: a.question, to: a.to }),
     },
+    {
+        name: "huddle_ask_user",
+        description: "Ask the USER (the person this work is for) to decide something BIG that the goal doesn't settle: a choice that changes what they get " +
+            "(scope, a feature in or out, a user-visible behavior, an irreversible step, real money or data). NOT for names, file layout, code style " +
+            "or anything you or a teammate can decide — the user isn't an engineer and sees many agents. Give 2-4 short options in plain words " +
+            "(no jargon), the one you recommend FIRST; they may also answer in their own words. Waits a short while; with no answer, go with option 1. " +
+            "At most 2 per run.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                question: { type: "string", description: "one plain sentence, e.g. 'Should it also convert Rankine?'" },
+                options: { type: "array", items: { type: "string" }, description: "2-4 plain-words options, your recommendation first" },
+                why: { type: "string", description: "optional: one line on what changes for them either way" },
+            },
+            required: ["question", "options"],
+        },
+        handler: (a) => room("/ask_user", "POST", { question: a.question, options: a.options, why: a.why }),
+    },
     {
         name: "huddle_send",
         description: "Message a teammate agent directly: a heads-up ('I renamed X to Y'), an interface you're exposing, or an answer to their question (pass reply_to = the question's id). `to` = an agent id from huddle_peers, a task id, \"all\" for everyone working now, or \"huddle\" to answer Huddle itself. They see it the next time they call any huddle tool.",
@@ -239,6 +257,7 @@ export const PLUG_INSTRUCTIONS = `Huddle: you are one of several AI coding agent
 - Start: huddle_board (the plan and who is doing what), huddle_recall (shared memory: decisions, contracts, the design council's notes: huddle_recall "council"), huddle_peers, huddle_inbox.
 - Before editing: huddle_announce_plan (what you will touch), huddle_check_overlap (is someone else in that file), huddle_contract (the exact names tasks share).
 - Names other tasks use: code to the contract verbatim. Never invent one that isn't in it — huddle_amend_contract(section, change, why) first; it tells every teammate.
+- The user: messages whose sender is "the user" come from the person this work is for — they win over the plan and the contract. A big decision the goal doesn't settle (scope, user-visible behavior, anything irreversible): huddle_ask_user with 2-4 plain options, your pick first. Never for names or code style.
 - While working: huddle_progress (a short note; the reply shows the team's in-flight work), huddle_remember (a decision or contract others need; kind "lesson" is kept for future runs), huddle_send (message one teammate), huddle_ask (ask a teammate or the brain a question), huddle_inbox (read replies).
 - Sharing work: when huddle_offer_help reaches you, huddle_split hands part of your task to a free agent; huddle_take_backlog picks up the next task; huddle_claim takes a specific one.
 - QA rounds: huddle_report_bug files one reproducible bug in the merged build; it becomes a fix task for the file's author.

package/dist/orchestrator/brain.js

@@ -123,7 +123,9 @@ export function repoContext(cwd, maxFiles = 250) {
             return null;
         }
     };
-    const parts = [`FILES (${files.length}${files.length > maxFiles ? `, first ${maxFiles}` : ""}):\n${files.slice(0, maxFiles).join("\n") || "(empty repo)"}`];
+    // Found live (0.1.2): agents set "engines": {"node": ">=22"} on a machine with Node 20.
+    const machine = `MACHINE: ${process.platform === "darwin" ? "macOS" : process.platform === "win32" ? "Windows" : "Linux"}, Node ${process.version}. Target what runs here: never require a newer Node (engines, syntax, built-in APIs) than this.`;
+    const parts = [machine, `FILES (${files.length}${files.length > maxFiles ? `, first ${maxFiles}` : ""}):\n${files.slice(0, maxFiles).join("\n") || "(empty repo)"}`];
     for (const f of ["package.json", "pyproject.toml", "Cargo.toml", "go.mod"]) {
         const h = head(f, 40);
         if (h)