huddle-cli 0.1.0 → 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
@@ -35,7 +35,10 @@ const CLAUDE_ALLOW = "mcp__huddle";
 export function livePlug(repo, agent) {
     return { command: process.execPath, args: [CLI_PATH, "plug"], env: { HUDDLE_LIVE: "1", HUDDLE_AGENT_ID: agent, HUDDLE_REPO: repo } };
 }
-export const guardCommand = () => `"${process.execPath}" "${CLI_PATH}" guard`;
+// Quoted (paths with spaces: C:\Users\Some Name\…) and with forward slashes on
+// Windows, which node accepts and which survive both bash and cmd/PowerShell.
+const hookPath = (p) => (process.platform === "win32" ? p.replace(/\\/g, "/") : p);
+export const guardCommand = () => `"${hookPath(process.execPath)}" "${hookPath(CLI_PATH)}" guard`;
 /** What `huddle connect` would write for one agent. */
 export function wiresFor(adapter, repo, opts = {}) {
     const plug = livePlug(repo, adapter.id);
@@ -70,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;
     }
@@ -149,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/guard.js

@@ -14,13 +14,17 @@
 import { execFileSync } from "node:child_process";
 import { liveCall, mainRoot, readLive } from "./live.js";
 /** This process's ancestors (the hook's shell, then Claude itself, …). */
-export function ancestors(max = 8) {
+export function ancestors(max = 8, platform = process.platform) {
     const out = [];
+    // Windows has no `ps`: one PowerShell call lists every process's parent.
+    const parents = platform === "win32" ? windowsParents() : null;
     let pid = process.ppid;
     for (let i = 0; i < max && pid > 1; i++) {
         out.push(pid);
         try {
-            pid = Number(execFileSync("ps", ["-o", "ppid=", "-p", String(pid)], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim());
+            pid = parents
+                ? (parents.get(pid) ?? 0)
+                : Number(execFileSync("ps", ["-o", "ppid=", "-p", String(pid)], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim());
         }
         catch {
             break;
@@ -28,6 +32,21 @@ export function ancestors(max = 8) {
     }
     return out;
 }
+/** pid → parent pid, from `Get-CimInstance Win32_Process`. Empty if that fails. */
+export function windowsParents(run = () => execFileSync("powershell.exe", ["-NoProfile", "-Command", "Get-CimInstance Win32_Process | ForEach-Object { \"$($_.ProcessId) $($_.ParentProcessId)\" }"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 4000, windowsHide: true })) {
+    const m = new Map();
+    try {
+        for (const l of run().split(/\r?\n/)) {
+            const [a, b] = l.trim().split(/\s+/).map(Number);
+            if (a > 0 && b >= 0)
+                m.set(a, b);
+        }
+    }
+    catch {
+        /* no PowerShell: the guard still works, just without pid matching */
+    }
+    return m;
+}
 async function readStdin() {
     let s = "";
     for await (const c of process.stdin)

package/dist/attach/live.js

@@ -103,7 +103,7 @@ export async function pingLive(st) {
         return false;
     }
 }
-function ensureHuddleDir(root) {
+export function ensureHuddleDir(root) {
     const f = liveFiles(root);
     fs.mkdirSync(path.dirname(f.log), { recursive: true });
     const gi = path.join(f.dir, ".gitignore");
@@ -142,6 +142,7 @@ export async function ensureLive(root, timeoutMs = 8000) {
         const child = spawn(process.execPath, [CLI_PATH, "up", "--serve"], {
             cwd: root,
             detached: true,
+            windowsHide: true, // detached on Windows = a new console window, unless hidden
             stdio: ["ignore", out, out],
             env: { ...process.env, HUDDLE_LIVE_ROOT: root },
         });
@@ -217,6 +218,9 @@ export async function stopLive(root) {
     process.kill(st.pid, "SIGTERM");
     for (let i = 0; i < 50 && alive(st.pid); i++)
         await new Promise((r) => setTimeout(r, 100));
+    // On Windows "SIGTERM" is TerminateProcess: the daemon's handler never runs, so tidy up for it.
+    if (!alive(st.pid))
+        fs.rmSync(liveFiles(root).state, { force: true });
     return true;
 }
 //# sourceMappingURL=live.js.map

package/dist/attach/plug.js

@@ -4,9 +4,12 @@
 // 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";
+import { contextTools, toContent } from "../mcp/context-tools.js";
+import { packageInfo } from "../preflight.js";
 import { checkoutRoot, ensureLive, liveCall, mainRoot, roomCall } from "./live.js";
 /** What every attached agent is told, via the MCP `instructions` field. */
 export const LIVE_INSTRUCTIONS = `
@@ -16,7 +19,14 @@ Before you edit ANY file:
 2. huddle_announce_plan(intent, touches) with every file (or "dir/") you'll change. If it returns conflicts, DO NOT edit those files: huddle_note the holder or pick other work, and tell your user.
 3. When you finish a change, huddle_release so the others can proceed.
 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",
@@ -119,7 +129,12 @@ export async function runLivePlug() {
             await sayHello();
         return roomCall(st, method, p, body, sid);
     };
+    // The shared screen: the same tools (and Room routes) as a `huddle join` agent's Plug.
+    const screen = contextTools((p, method, body) => plain(method, p, body ?? {}));
     const call = (name, a) => {
+        const ctx = screen.find((t) => t.name === name);
+        if (ctx)
+            return ctx.handler(a);
         switch (name) {
             case "huddle_peers":
                 return live("peers", {});
@@ -139,12 +154,15 @@ export async function runLivePlug() {
         }
         throw new Error(`unknown tool: ${name}`);
     };
-    const server = new Server({ name: "huddle", version: "0.1.0" }, { capabilities: { tools: {} }, instructions: LIVE_INSTRUCTIONS });
-    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: tools.map((t) => ({ ...t })) }));
+    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)],
+    }));
     server.setRequestHandler(CallToolRequestSchema, async (req) => {
         try {
             const result = await call(req.params.name, req.params.arguments ?? {});
-            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+            // toContent: JSON text, plus an MCP image block for a screenshot.
+            return { content: toContent(result) };
         }
         catch (e) {
             // Never wedge the agent: say what's wrong and let it carry on.

package/dist/attach/screen.js

@@ -0,0 +1,150 @@
+// Attach mode, the human's side of the shared screen: `huddle add` and
+// `huddle ctx`, typed in any terminal while your own claude / codex / cursor
+// sessions run in theirs.
+//
+//   huddle add err.log src/auth/ "*.png"   files, folders (one bundle), globs
+//   cat err.log | huddle add -              stdin (pbpaste | huddle add - too)
+//   huddle ctx [show <id>|rm <id>|note <id> <text>|clear]
+//
+// Same store, same commands as the `huddle` prompt (src/ui/paste.ts on
+// src/room/context.ts) — only the db differs: the live room's .huddle/live.db.
+// The room reads that db on every call, so writing it here is the same whether
+// the room is up or not; when it's up, each session hears about a new item (or
+// a pinned note) in notes_for_you on its next huddle_* call — the path
+// huddle_note takes (src/room/live.ts, inbox).
+import fs from "node:fs";
+import path from "node:path";
+import { getAdapter } from "../adapters/index.js";
+import { ContextStore, normalizePathToken } from "../room/context.js";
+import { RoomDB } from "../room/db.js";
+import { addPaths, addPiped, ctxCommand } from "../ui/paste.js";
+import { C } from "../ui/term.js";
+import { confirm } from "./connect.js";
+import { ensureHuddleDir, liveCall, liveFiles, mainRoot, pingLive, readLive } from "./live.js";
+/** The sessions in the live room right now (agent names), or null when it's down. */
+async function liveAgents(repo) {
+    const st = readLive(repo);
+    if (!st || !(await pingLive(st)))
+        return null;
+    try {
+        const r = await liveCall(st, "peers", {}, "", 2000);
+        return (r.body.sessions ?? []).map((s) => String(s.agent));
+    }
+    catch {
+        return null;
+    }
+}
+/** A ScreenUI on the live room's store. `interactive` = a person can answer the secrets question. */
+function screenUI(repo, agents, interactive) {
+    let db = null;
+    const ui = {
+        print: (l = "") => console.log(l),
+        yes: (q, def = true) => confirm(q, def),
+        db: async () => {
+            if (!db) {
+                ensureHuddleDir(repo); // .huddle/ with its own .gitignore
+                db = new RoomDB(liveFiles(repo).db);
+            }
+            return db;
+        },
+        audience: () => {
+            const list = [...new Set(agents ?? [])];
+            return { agents: list, companies: new Set(list.map((a) => getAdapter(a)?.vendor ?? a)).size };
+        },
+        root: () => repo,
+        interactive,
+        announce: false, // the live room delivers it with each session's notes
+    };
+    return { ui, close: () => db?.close() };
+}
+function needRepo() {
+    const repo = mainRoot();
+    if (!repo)
+        console.log(C.red("✗ Not a git repo.") + " The shared screen belongs to a repo — cd into the one your agents work in.");
+    return repo;
+}
+/**
+ * A path as typed: file:// URLs and ~ resolved (cmd.exe expands neither), and
+ * Windows separators read as "/" where "\" isn't one (logs\err.log on macOS).
+ */
+export function cliPath(arg, cwd = process.cwd()) {
+    const p = normalizePathToken(arg);
+    if (path.sep === "\\" || !p.includes("\\") || fs.existsSync(path.resolve(cwd, p)))
+        return p;
+    return p.replace(/\\/g, "/");
+}
+async function readAllStdin(stdin = process.stdin) {
+    let s = "";
+    for await (const c of stdin)
+        s += c.toString();
+    return s;
+}
+/** `huddle add <file|folder|glob|->…` — `--title <t>` names a stdin item. */
+export async function runAdd(args) {
+    const repo = needRepo();
+    if (!repo)
+        return void (process.exitCode = 1);
+    let title;
+    const paths = [];
+    let piped = false;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--title" && i + 1 < args.length)
+            title = args[++i];
+        else if (a.startsWith("--title="))
+            title = a.slice(8);
+        else if (a === "-")
+            piped = true;
+        else
+            paths.push(cliPath(a));
+    }
+    if (!paths.length && !piped) {
+        console.log(`usage: ${C.bold("huddle add <file|folder|glob>")} … ${C.faint("· or pipe it:")} ${C.bold("cat err.log | huddle add -")}`);
+        return void (process.exitCode = 1);
+    }
+    if (piped && process.stdin.isTTY) {
+        console.log(C.red("  ✗ nothing piped in") + C.faint(" — e.g. pbpaste | huddle add -   ·   cat err.log | huddle add -"));
+        return void (process.exitCode = 1);
+    }
+    const agents = await liveAgents(repo);
+    // Stdin is the pipe with `-`, so nobody can answer: secrets are redacted.
+    const { ui, close } = screenUI(repo, agents, !piped && !!process.stdin.isTTY && !!process.stdout.isTTY);
+    let failed = 0;
+    let before = 0;
+    try {
+        const store = ContextStore.open((await ui.db()));
+        before = store.list().length;
+        if (piped && !(await addPiped(store, await readAllStdin(), ui, { title })))
+            failed++;
+        if (paths.length)
+            failed += await addPaths(paths, ui);
+        const added = store.list().length - before;
+        if (added > 0)
+            console.log(C.faint(agents === null
+                ? "     no live room right now — sessions find it with huddle_context when they're up"
+                : agents.length
+                    ? `     ${[...new Set(agents)].join(", ")} see it on their next huddle_* call`
+                    : "     live room is up; sessions that join find it with huddle_context"));
+    }
+    finally {
+        close();
+    }
+    if (failed)
+        process.exitCode = 1;
+}
+/** `huddle ctx [list|show <id>|rm <id…>|note <id> <text>|clear|add <path…>]` */
+export async function runCtx(args) {
+    const repo = needRepo();
+    if (!repo)
+        return void (process.exitCode = 1);
+    const { ui, close } = screenUI(repo, await liveAgents(repo), !!process.stdin.isTTY && !!process.stdout.isTTY);
+    try {
+        if (args[0] === "add")
+            return void (await addPaths(args.slice(1).map((a) => cliPath(a)), ui));
+        await ctxCommand(args.join(" "), ui);
+    }
+    finally {
+        close();
+    }
+}
+//# sourceMappingURL=screen.js.map

package/dist/attach/session.js

@@ -4,11 +4,13 @@
 // other's files mid-edit; `huddle land` brings a session's branch home through
 // the merge engine (commit → tests → rebase → fast-forward), after you say so.
 //
-// Plus `huddle up` / `huddle down` / `huddle peers`, the human's view of the room.
+// Plus `huddle up` / `huddle down` / `huddle peers`, the human's view of the room
+// (`huddle add` / `huddle ctx`, its shared screen, are in screen.ts).
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { getAdapter } from "../adapters/index.js";
+import { spawnToolSync } from "../platform.js";
 import { createWorktree, landMerge, prepareMerge, removeWorktree } from "../sandbox/worktree.js";
 import { C, dot } from "../ui/term.js";
 import { detectTestCmd } from "../ui/app.js";
@@ -78,7 +80,7 @@ export async function runAttach(args) {
     const { wt, cmd } = prepareAttach(repo, agentId);
     console.log(`${dot(agentId)} ${C.bold(agentId)} in its own worktree ${C.faint(path.relative(repo, wt.path))} on ${C.bold(wt.branch)}`);
     console.log(C.faint(`  live room ${state.url} · the others see it in huddle_peers · when it's done: huddle land ${wt.branch}\n`));
-    const r = spawnSync(cmd[0], [...cmd.slice(1), ...passthrough], { cwd: wt.path, stdio: "inherit" });
+    const r = spawnToolSync([...cmd, ...passthrough], { cwd: wt.path, stdio: "inherit" });
     if (r.error)
         console.log(C.red(`✗ couldn't start ${cmd[0]}: ${r.error.message}`));
     const changed = spawnSync("git", ["status", "--porcelain"], { cwd: wt.path, encoding: "utf8" }).stdout.trim();
@@ -162,6 +164,9 @@ export async function runPeers() {
         console.log(`  ${dot(s.agent)} ${C.bold(s.id.padEnd(12))} ${s.doing}`);
         console.log(C.faint(`      ${s.branch || "?"} · ${s.worktree} · holds ${s.holds.length ? s.holds.join(", ") : "nothing"} · seen ${s.seen_s_ago}s ago`));
     }
+    const sc = r.body.screen;
+    if (sc?.items)
+        console.log(`\n  ${C.bold("screen")} ${sc.items} item${sc.items === 1 ? "" : "s"}${sc.latest_note ? ` · latest note: ${sc.latest_note}` : ""} ${C.faint("· huddle ctx")}`);
     const notes = r.body.notes ?? [];
     if (notes.length) {
         console.log(`\n  ${C.bold("notes")}`);