huddle-cli 0.1.0 → 0.1.3

package/dist/cli.js

@@ -8,96 +8,165 @@
 //     --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
+//   huddle agents               your agents: ready / not signed in / not installed, used or skipped
+//   huddle agents use|skip <ids>  choose who works with you (remembered)
 //   huddle --version            print the version
 //   huddle agents --all         every connector (built in + agents.json) and how to get it
 //   huddle agents install <id>  install one connector's CLI, after asking
 //   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 said what to whom, reviews, merges
+//   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
 //   huddle connect | disconnect wire your own claude/codex/cursor sessions into it
 //   huddle peers                who's live in this repo and which files they hold
+//   huddle add <file|dir|glob|->  put it on the live room's shared screen (- = stdin)
+//   huddle ctx [show|rm|note|clear]  what's on that screen; take things off, pin notes
 //   huddle attach <agent>       open an agent in its own worktree, connected
 //   huddle land [branch]        tests -> rebase -> merge an attach session's branch
 //   huddle plug                 (internal) the MCP server each agent talks to
 //   huddle guard                (internal) Claude's pre-edit hook in attach mode
+//   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 { runPlug } from "./mcp/server.js";
-import { C } from "./ui/term.js";
-import { connectAgents, ensureInit, huddleDir, printBoard, runApp, runGoal } from "./ui/app.js";
-import { INVITE_CODE, joinRoom } from "./ui/remote.js";
-import { startRelay } from "./relay/server.js";
-import { runDoctor } from "./ui/doctor.js";
+import { C, useAsciiOutput } from "./ui/term.js";
+import { asGoal } from "./args.js";
 import { SqliteUnavailableError } from "./room/sqlite.js";
-import { installConnector, printCatalog } from "./ui/catalog.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.
+const app = () => import("./ui/app.js");
+const B = C.bold;
+const F = C.faint;
+// Every line fits 80 columns.
 const USAGE = `${C.violet("huddle")} — your agents, in the same room
 
-  ${C.bold("huddle")}                      open Huddle
-  ${C.bold('huddle join "<goal>"')}        plan the goal and run your agents
-  ${C.bold('huddle join "<goal>" --plan')} dry run — show who'd do what
-  ${C.bold("  --approvals=safe|auto|yolo")}  what agents may do without asking (default auto)
-  ${C.bold("  --agents=claude,codex")}       only these agents work on this run
-  ${C.bold("  --council | --no-council")}    every agent brainstorms the design first ${C.faint("(default: big goals only)")}
-  ${C.bold("  --qa")} ${C.faint("/")} ${C.bold("--no-qa")}             agents re-check the build and fix what they find ${C.faint("(default: big goals)")}
-  ${C.bold("huddle join <address> <CODE>")} join someone's room from an invite
-  ${C.bold("huddle doctor")}               check this machine: node, git, your agents
-  ${C.bold("huddle agents --all")}         every connector Huddle knows, installed or not
-  ${C.bold("huddle agents install <id>")}  install one (asks first)
-  ${C.bold("huddle relay")} ${C.faint("[--port 8080]")}  run a relay so rooms work across networks
-  ${C.bold("huddle board")}                print the board
-  ${C.bold("huddle view")} ${C.faint("[repo]")}          watch a run live from another terminal ${C.faint("(read-only)")}
-  ${C.bold("huddle story")} ${C.faint("[--html f]")}     replay the last run: messages, reviews, merges ${C.faint("(--list, --run n)")}
-  ${C.bold("huddle --version")}            print the version
+  ${B("huddle")}                       open Huddle
+  ${B('huddle join "<goal>"')}         plan the goal and run your agents
+    ${B("--plan")}                     dry run: show who'd do what
+    ${B("--agents=claude,codex")}      only these agents work on this run
+    ${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
 
-  ${C.faint("run claude, codex and cursor yourself — in one repo, safely:")}
-  ${C.bold("huddle connect")}              wire your agents into this repo's live room ${C.faint("(asks first)")}
-  ${C.bold("huddle peers")}                who's live, what they're doing, which files they hold
-  ${C.bold("huddle attach <agent>")}       open an agent in its own worktree branch
-  ${C.bold("huddle land")} ${C.faint("[branch]")}         test + merge that session's work
-  ${C.bold("huddle up")} ${C.faint("/")} ${C.bold("down")} ${C.faint("/")} ${C.bold("disconnect")}  start · stop the live room · unwire
+  ${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)")}
+
+  ${F("your agents")}
+  ${B("huddle setup")}                 install + sign in to your agents ${F("(--yes)")}
+  ${B("huddle doctor")}                check this machine: node, git, your agents
+  ${B("huddle agents")}                your agents: ready or not, used or skipped
+  ${B("huddle agents use|skip <ids>")} choose who works with you ${F("(e.g. skip cursor)")}
+  ${B("huddle agents --all")}          every connector Huddle knows, installed or not
+  ${B("huddle agents install <id>")}   install one ${F("(asks first)")}
+  ${B("huddle relay")} ${F("[--port 8080]")}   run a relay so rooms work across networks
+  ${B("huddle --version")}             print the version
+
+  ${F("run claude, codex and cursor yourself — in one repo, safely")}
+  ${B("huddle connect")}               wire your agents into this repo's live room
+  ${B("huddle peers")}                 who's live, what they're on, their files
+  ${B("huddle add <file|->")}          put a file, folder, glob or stdin on the screen
+                               ${F("(cat err.log | huddle add -)")}
+  ${B("huddle ctx")} ${F("[show|rm|note|clear]")} what's on the screen every session reads
+  ${B("huddle attach <agent>")}        open an agent in its own worktree branch
+  ${B("huddle land")} ${F("[branch]")}         test + merge that session's work
+  ${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();
     switch (cmd) {
         case undefined:
             if (!process.stdin.isTTY)
                 return void console.log(USAGE);
-            return runApp();
+            return (await app()).runApp();
         case "plug":
-            return runPlug();
-        case "init":
+            return (await import("./mcp/server.js")).runPlug();
+        case "init": {
+            const { ensureInit, huddleDir } = await app();
             if (!ensureInit()) {
                 console.log(C.red("✗ Not a git repo.") + " Huddle sandboxes are git worktrees — run `git init` first.");
                 process.exit(1);
             }
             return void console.log(`${C.green("✓")} Huddle initialized in ${C.faint(huddleDir())}`);
-        case "doctor":
-        case "agents":
+        }
+        case "setup":
+            process.exitCode = await (await import("./ui/setup.js")).runSetup(rest);
+            return;
+        case "agents": {
+            const { chooseAgents, installConnector, printAgents, printCatalog } = await import("./ui/catalog.js");
             if (rest[0] === "install" && rest[1])
                 return void (await installConnector(rest[1]));
+            if ((rest[0] === "use" || rest[0] === "skip") && rest.length > 1)
+                return void (process.exitCode = chooseAgents(rest[0], rest.slice(1)) ? 0 : 1);
             if (rest.includes("--all"))
                 return printCatalog();
-            process.exitCode = await runDoctor();
+            if (!rest.length)
+                return printAgents();
+            process.exitCode = await (await import("./ui/doctor.js")).runDoctor();
+            return;
+        }
+        case "doctor":
+            process.exitCode = await (await import("./ui/doctor.js")).runDoctor();
             return;
         case "join": {
             // `huddle join <address> <CODE>` joins someone's room; anything else is a goal.
+            const { INVITE_CODE, joinRoom } = await import("./ui/remote.js");
             if (rest.length === 2 && INVITE_CODE.test(rest[1]))
                 return joinRoom(rest[0], rest[1]);
-            const goal = rest.filter((a) => !a.startsWith("--")).join(" ");
+            const { connectAgents, dbPath, ensureInit, runGoal } = await app();
+            const { addForRun, readPipedStdin, takeWith } = await import("./ui/paste.js");
+            const withs = takeWith(rest);
+            const goal = withs.rest.filter((a) => !a.startsWith("--")).join(" ");
             if (!goal) {
                 console.log(C.red("✗ Give a goal:") + ' huddle join "build the login page"');
                 process.exit(1);
             }
+            // The shared screen first (--with files, piped stdin), so the planner sees its index.
+            const piped = await readPipedStdin();
+            if (withs.files.length || piped.trim()) {
+                if (!ensureInit()) {
+                    console.log(C.red("✗ Not a git repo.") + " The shared screen lives in a repo's .huddle/ — run `git init` first.");
+                    process.exit(1);
+                }
+                if (await addForRun(dbPath(), withs.files, piped, (l = "") => console.log(l))) {
+                    console.log(C.red("✗ couldn't put everything on the shared screen (above) — nothing was run."));
+                    process.exit(1);
+                }
+            }
             const flag = rest.find((a) => a.startsWith("--approvals="))?.split("=")[1];
             const approvals = (["safe", "auto", "yolo"].includes(flag ?? "") ? flag : "auto");
-            const probed = await connectAgents();
+            let probed = await connectAgents();
             let results = probed;
-            // --agents=claude,codex: run with just these (the rest sit this one out).
+            // --agents=claude,codex: run with just these (the rest sit this one out) — even ones you skipped.
             const pick = rest.find((a) => a.startsWith("--agents="))?.split("=")[1];
             if (pick !== undefined) {
                 const ids = pick.split(",").map((s) => s.trim()).filter(Boolean);
+                results = probed = (await import("./adapters/index.js")).unskip(probed, ids);
                 const unknown = ids.filter((id) => !results.some((r) => r.adapter.id === id));
                 if (!ids.length || unknown.length) {
                     console.log(C.red(`✗ --agents: no agent called ${unknown.join(", ") || "(empty)"}.`) + ` Known: ${results.map((r) => r.adapter.id).join(", ")}`);
@@ -112,21 +181,38 @@ 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 printBoard();
+            return (await app()).printBoard();
         case "view":
         case "watch":
             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":
             return (await import("./attach/session.js")).runUp(rest);
         case "down":
             return (await import("./attach/session.js")).runDown();
         case "peers":
             return (await import("./attach/session.js")).runPeers();
+        case "add":
+            return (await import("./attach/screen.js")).runAdd(rest);
+        case "ctx":
+        case "context":
+            return (await import("./attach/screen.js")).runCtx(rest);
         case "attach":
             return (await import("./attach/session.js")).runAttach(rest);
         case "land":
@@ -137,6 +223,11 @@ async function main() {
             return (await import("./attach/connect.js")).runDisconnect();
         case "guard":
             return (await import("./attach/guard.js")).runGuard();
+        case "mail":
+            if (rest.includes("--hook"))
+                return (await import("./room/mail.js")).runMailHook(rest);
+            console.log(C.red("✗ huddle mail is internal:") + " agents read mail through the Plug (huddle_inbox).");
+            process.exit(1);
         case "relay": {
             // Run a relay so rooms work across networks. Host it anywhere Node runs.
             const i = rest.indexOf("--port");
@@ -145,6 +236,7 @@ async function main() {
                 console.log(C.red("✗ --port needs a number from 0 to 65535,") + " e.g. huddle relay --port 8080");
                 process.exit(1);
             }
+            const { startRelay } = await import("./relay/server.js");
             const r = await startRelay(port, (l) => console.log(C.faint(new Date().toISOString().slice(11, 19) + " " + l)));
             console.log(`${C.violet("huddle relay")} listening on :${r.port} ${C.faint("· people use it with: relay ws://<this-host>:" + r.port)}`);
             return;

package/dist/mcp/context-tools.js

@@ -0,0 +1,79 @@
+// The Plug's shared-screen verbs (src/room/context.ts is the Room side).
+// Kept out of server.ts so the screen is one file to read.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export function contextTools(room) {
+    return [
+        {
+            name: "huddle_context",
+            description: "The SHARED SCREEN: everything the user pasted, dropped or uploaded for the whole team (logs, docs, code, screenshots, PDFs) — one copy in the Room, not in your prompt. Lists each item's id, kind, title, size, summary, sections and the notes pinned on it.",
+            inputSchema: { type: "object", properties: {} },
+            handler: () => room("/context", "GET"),
+        },
+        {
+            name: "huddle_context_read",
+            description: "Read one item from the shared screen. Text comes back in chunks of up to 400 lines: pass from_line/to_line, or section (a number or title from huddle_context). Images and PDFs come back as a file path — open it with your image/file reading tool.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    id: { type: "string", description: "the item id, e.g. ctx-3" },
+                    from_line: { type: "number" },
+                    to_line: { type: "number" },
+                    section: { type: "string", description: "optional: a section number or title" },
+                },
+                required: ["id"],
+            },
+            handler: (a) => room("/context_read", "POST", { id: a.id, from_line: a.from_line, to_line: a.to_line, section: a.section }),
+        },
+        {
+            name: "huddle_context_search",
+            description: "Search every text item on the shared screen. Returns matching lines with the item id and line number, so you can huddle_context_read around them.",
+            inputSchema: {
+                type: "object",
+                properties: { query: { type: "string" }, regex: { type: "boolean", description: "treat query as a regular expression" } },
+                required: ["query"],
+            },
+            handler: (a) => room("/context_search", "POST", { query: a.query, regex: !!a.regex }),
+        },
+        {
+            name: "huddle_context_note",
+            description: "Pin a short comment on a shared-screen item — what it means, what you found in it, which part you're handling. Every agent and the user sees it next to the item. This is how the team talks about the same document.",
+            inputSchema: {
+                type: "object",
+                properties: { id: { type: "string" }, note: { type: "string" } },
+                required: ["id", "note"],
+            },
+            handler: (a) => room("/context_note", "POST", { id: a.id, note: a.note }),
+        },
+    ];
+}
+/**
+ * A Room result as MCP content. Screenshots also go as an image block (hosts
+ * that render MCP images show it to the model directly). Bytes sent across
+ * machines (a teammate's agent) are saved here and replaced by a local path.
+ */
+export function toContent(result) {
+    if (!result || typeof result !== "object" || Array.isArray(result))
+        return [{ type: "text", text: JSON.stringify(result, null, 2) }];
+    const { image, file, ...rest } = result;
+    if (file?.data_base64 && file?.name) {
+        try {
+            const dir = path.join(os.tmpdir(), "huddle-context");
+            fs.mkdirSync(dir, { recursive: true });
+            const p = path.join(dir, String(file.name).replace(/[^\w.-]/g, "_"));
+            fs.writeFileSync(p, Buffer.from(String(file.data_base64), "base64"));
+            rest.path = p;
+            rest.note = `Open this file with your image/file reading tool (e.g. Read ${p}).`;
+        }
+        catch (e) {
+            rest.note = `couldn't save the file here: ${e?.message ?? e}`;
+        }
+    }
+    const out = [{ type: "text", text: JSON.stringify(rest, null, 2) }];
+    // HUDDLE_CTX_MCP_IMAGES=0: path only, for a host that can't take image blocks.
+    if (image?.data_base64 && image?.mime && process.env.HUDDLE_CTX_MCP_IMAGES !== "0")
+        out.push({ type: "image", data: String(image.data_base64), mimeType: String(image.mime) });
+    return out;
+}
+//# sourceMappingURL=context-tools.js.map

package/dist/mcp/server.js

@@ -8,6 +8,8 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { contextTools, toContent } from "./context-tools.js";
+import { packageInfo } from "../preflight.js";
 const ROOM = process.env.HUDDLE_ROOM_URL ?? "http://localhost:4737";
 const AGENT = process.env.HUDDLE_AGENT_ID ?? "unknown-agent";
 // Proves to the Room that this call comes from one of this session's own agents.
@@ -105,11 +107,11 @@ const TOOLS = [
     },
     {
         name: "huddle_remember",
-        description: "Write to SHARED MEMORY so other agents learn from you. kind = decision | fact | gotcha. Always include 'why' — teammates need the reasoning, not just the what.",
+        description: "Write to SHARED MEMORY so other agents learn from you. kind = decision | fact | gotcha | lesson. Always include 'why' — teammates need the reasoning, not just the what. kind=lesson is also kept for FUTURE runs in this repo: one short, general rule you'd want next time (e.g. 'run npm run typecheck too: npm test doesn't type-check').",
         inputSchema: {
             type: "object",
             properties: {
-                kind: { type: "string", enum: ["decision", "fact", "gotcha"] },
+                kind: { type: "string", enum: ["decision", "fact", "gotcha", "lesson"] },
                 body: { type: "string" },
                 why: { type: "string" },
             },
@@ -139,9 +141,27 @@ 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, or \"all\" for everyone working now. They see it the next time they call any huddle tool.",
+        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.",
         inputSchema: {
             type: "object",
             properties: {
@@ -154,10 +174,30 @@ const TOOLS = [
         handler: (a) => room("/send", "POST", { to: a.to, message: a.message, reply_to: a.reply_to }),
     },
     {
-        name: "huddle_inbox",
-        description: "Read messages and questions teammates sent you (marks them read). Any huddle tool result that says 'unread_messages' means: call this now. Answer questions with huddle_send(reply_to=…).",
+        name: "huddle_contract",
+        description: "Read the team's CONTRACT: the exact cross-task names everyone codes to (files and owners, function signatures, data fields, CLI flags, routes, error strings), its version, and every amendment since. Check it before you name anything another task uses.",
         inputSchema: { type: "object", properties: {} },
-        handler: () => room("/inbox", "GET"),
+        handler: () => room("/contract", "GET"),
+    },
+    {
+        name: "huddle_amend_contract",
+        description: "Change or add a name in the CONTRACT (a signature, a field, a file owner, an error string) when your task needs one that isn't there or is wrong. Bumps the version and messages every teammate working now. Never invent a name another task depends on without this.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                section: { type: "string", description: "what part it changes, e.g. 'store.js exports' or 'error strings'" },
+                change: { type: "string", description: "the exact new name/signature/shape" },
+                why: { type: "string" },
+            },
+            required: ["section", "change", "why"],
+        },
+        handler: (a) => room("/amend_contract", "POST", { section: a.section, change: a.change, why: a.why }),
+    },
+    {
+        name: "huddle_inbox",
+        description: "Read messages and questions teammates sent you (marks them read). Huddle tool results already carry new ones (new_messages); call this for more, or with id for a message shown cut short. Answer questions with huddle_send(reply_to=…).",
+        inputSchema: { type: "object", properties: { id: { type: "string", description: "optional: one message's id" } } },
+        handler: (a) => room(a?.id ? `/inbox?id=${encodeURIComponent(String(a.id))}` : "/inbox", "GET"),
     },
     {
         name: "huddle_report_bug",
@@ -196,7 +236,9 @@ const TOOLS = [
     },
     {
         name: "huddle_done",
-        description: "Mark your task ready. This triggers the test-gate and, if green, the merge into main. Include a short summary of what you did.",
+        description: "Mark your task ready. This triggers the test-gate and, if green, the merge into main. Include a short summary of what you did. " +
+            "If a teammate's buddy note or a radar finding on your task has no answer yet, it is refused once with the list: fix each one, or reply " +
+            "huddle_send(to=<who sent it>, reply_to=<its id>, message=\"won't fix: <why>\"), then call huddle_done again.",
         inputSchema: {
             type: "object",
             properties: { task_id: { type: "string" }, summary: { type: "string" } },
@@ -204,6 +246,7 @@ const TOOLS = [
         },
         handler: (a) => room("/done", "POST", { task_id: a.task_id, summary: a.summary }),
     },
+    ...contextTools(room),
 ];
 /**
  * What an MCP host shows the model about the Plug as a whole: the verbs by
@@ -212,10 +255,13 @@ const TOOLS = [
  */
 export const PLUG_INSTRUCTIONS = `Huddle: you are one of several AI coding agents working on one repo at once, each in its own git worktree. These tools are how the team talks.
 - 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).
-- While working: huddle_progress (a short note; the reply shows the team's in-flight work), huddle_remember (a decision or contract others need), huddle_send (message one teammate), huddle_ask (ask a teammate or the brain a question), huddle_inbox (read replies).
+- 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.
+- The shared screen (what the user pasted, dropped or uploaded — logs, docs, screenshots): huddle_context lists it, huddle_context_read opens one item in chunks (images/PDFs as a file path), huddle_context_search finds text in it, huddle_context_note pins a comment on an item for everyone.
 - Finish: huddle_done with a short summary. Huddle tests and merges it.`;
 /** The Plug's verb names, in the order listed to agents. */
 export const PLUG_VERBS = TOOLS.map((t) => t.name);
@@ -223,7 +269,7 @@ export async function runPlug() {
     // Attach mode (`huddle connect`): a session you started yourself, no scheduler.
     if (process.env.HUDDLE_LIVE)
         return (await import("../attach/plug.js")).runLivePlug();
-    const server = new Server({ name: "huddle", version: "0.1.0" }, { capabilities: { tools: {} }, instructions: PLUG_INSTRUCTIONS });
+    const server = new Server({ name: "huddle", version: packageInfo().version }, { capabilities: { tools: {} }, instructions: PLUG_INSTRUCTIONS });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: TOOLS.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })),
     }));
@@ -232,7 +278,7 @@ export async function runPlug() {
         if (!tool)
             throw new Error(`unknown tool: ${req.params.name}`);
         const result = await tool.handler((req.params.arguments ?? {}));
-        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        return { content: toContent(result) };
     });
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/orchestrator/ask.js

@@ -1,11 +1,12 @@
 // One-shot, read-only questions to an agent: answering "where are we with
 // this project?" and planning a goal. Runs in the repo itself (no worktree),
 // with each vendor's read-only / plan mode, so nothing can be edited.
-import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { stopChild } from "./launcher.js";
+import { onFinished, spawnTool } from "../platform.js";
 /** Preference order for who answers questions and plans. */
 const ASK_ORDER = ["claude", "codex", "antigravity", "cursor", "gemini"];
 export function pickAsker(ready) {
@@ -16,21 +17,20 @@ export function askAgent(adapter, prompt, cwd, opts = {}) {
     const outFile = path.join(os.tmpdir(), `huddle-ask-${process.pid}-${Date.now()}-${randomUUID().slice(0, 8)}.txt`);
     const spec = adapter.ask({ prompt, cwd, outFile, model: opts.model, noTools: opts.noTools, quick: opts.quick });
     return new Promise((resolve) => {
-        const child = spawn(spec.cmd[0], spec.cmd.slice(1), { cwd: spec.cwd, stdio: ["ignore", "pipe", "pipe"] });
+        const child = spawnTool(spec.cmd, { cwd: spec.cwd, stdio: ["ignore", "pipe", "pipe"] }, { prompt, stdinPrompt: adapter.stdinPrompt });
         let out = "";
         let err = "";
         child.stdout.on("data", (d) => (out += d));
         child.stderr.on("data", (d) => (err += d));
         // SIGKILL after a grace period: a stalled CLI can ignore SIGTERM (seen live with cursor-agent).
-        const stop = () => {
-            if (child.exitCode !== null || child.signalCode !== null)
-                return;
-            child.kill("SIGTERM");
-            setTimeout(() => child.exitCode === null && child.signalCode === null && child.kill("SIGKILL"), 5000).unref();
-        };
+        const stop = () => stopChild(child);
         const timer = setTimeout(stop, opts.timeoutMs ?? 5 * 60_000);
         opts.signal?.addEventListener("abort", stop);
+        let over = false;
         const finish = (code) => {
+            if (over)
+                return;
+            over = true;
             clearTimeout(timer);
             let text = out;
             if (spec.usesOutFile) {
@@ -44,8 +44,11 @@ export function askAgent(adapter, prompt, cwd, opts = {}) {
             }
             resolve({ ok: code === 0 && text.trim().length > 0, text: text.trim() || err.trim() });
         };
-        child.on("exit", finish);
-        child.on("error", () => finish(-1));
+        // "exit" can arrive before the last of stdout has been read — when our event
+        // loop was busy (a merge's test run blocks it) the answer was lost and the
+        // review counted as timed out (found on CI). onFinished waits for the pipes
+        // to drain, but not forever: a CLI's leftover child can hold them open.
+        onFinished(child, finish);
     });
 }
 //# sourceMappingURL=ask.js.map

package/dist/orchestrator/brain.js

@@ -15,6 +15,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { ADAPTERS } from "../adapters/index.js";
 import { askAgent } from "./ask.js";
+import { lessonsBrief } from "../room/lessons.js";
+import { screenForPlanner } from "../room/context.js";
 const OLLAMA = process.env.OLLAMA_HOST?.replace(/\/$/, "") || "http://127.0.0.1:11434";
 /** Models a local Ollama has pulled, or [] if Ollama isn't running. */
 export async function ollamaModels() {
@@ -100,8 +102,8 @@ export async function brainOptions(readyAgents) {
         out.push({ spec: "cursor:grok-4.7-low-fast", note: "cheap + fast, via your Cursor plan" });
     if (readyAgents.includes("claude")) {
         out.push({ spec: "claude:haiku", note: "smallest Claude — cheapest hosted option" });
-        out.push({ spec: "claude:sonnet", note: "default — plans in ~15s, a fraction of Opus's tokens" });
-        out.push({ spec: "claude", note: "Opus — strongest plans, most tokens" });
+        out.push({ spec: "claude:sonnet", note: "fast — plans in ~15s, a fraction of Opus's tokens" });
+        out.push({ spec: "claude:opus", note: "default — Opus, strongest plans, most tokens" });
     }
     if (readyAgents.includes("codex"))
         out.push({ spec: "codex", note: "your Codex default model" });
@@ -112,7 +114,7 @@ export async function brainOptions(readyAgents) {
  * manifest. ~a few thousand tokens; lets even a local model plan sensibly.
  */
 export function repoContext(cwd, maxFiles = 250) {
-    const files = (spawnSync("git", ["ls-files"], { cwd, encoding: "utf8" }).stdout ?? "").split("\n").filter(Boolean);
+    const files = (spawnSync("git", ["ls-files"], { cwd, encoding: "utf8" }).stdout ?? "").split(/\r?\n/).filter(Boolean);
     const head = (f, lines) => {
         try {
             return fs.readFileSync(path.join(cwd, f), "utf8").split("\n").slice(0, lines).join("\n");
@@ -121,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)
@@ -159,6 +163,14 @@ export function repoContext(cwd, maxFiles = 250) {
             parts.push(`${f}:\n${body.trimEnd()}`);
         }
     }
+    // The planner and the council plan from this snapshot: what earlier runs taught goes with it.
+    const lessons = lessonsBrief({ repo: cwd }).trim();
+    if (lessons)
+        parts.push(lessons);
+    // What the user pasted / dropped: the index (+ small items), not N full copies.
+    const screen = screenForPlanner(cwd);
+    if (screen)
+        parts.push(screen);
     return parts.join("\n\n");
 }
 //# sourceMappingURL=brain.js.map