huddle-cli 0.1.0 → 0.1.3

package/dist/ui/brief.js

@@ -0,0 +1,494 @@
+// The hand-off brief: memory that outlives the run. When the team leaves, a
+// solo `claude` / `codex` / `cursor` opened in the repo knew nothing about what
+// they built or agreed. Every run now ends with .huddle/BRIEF.md (and a copy
+// per run in .huddle/runs/<id>/), written from the Room's records alone — no
+// model call — and a short pointer to it in the files agents read on their own:
+// CLAUDE.md (claude), AGENTS.md (codex, cursor and others).
+//
+// The pointer is a marked block; nothing outside the markers is ever touched.
+// It is never committed. A file Huddle created goes in .git/info/exclude; a
+// file you own keeps the block as a working-tree change only between runs:
+// each run lifts it out first (so your checkout is as you left it, the
+// "uncommitted changes" check and merges into main never trip on it, and task
+// agents don't read a stale pointer), and puts it back at the end.
+//
+//   huddle brief              print the latest brief
+//   huddle brief --run <n|id> one run's brief (number from `huddle story --list`)
+//   huddle brief off | on     stop / resume the pointers in CLAUDE.md and AGENTS.md
+//   HUDDLE_NO_BRIEF=1         no brief at all
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { buildStory, goalTitle, pickRun, splitRuns } from "./story.js";
+import { C } from "./term.js";
+export const BRIEF_START = "<!-- huddle:brief start -->";
+export const BRIEF_END = "<!-- huddle:brief end -->";
+/** The files agents read by themselves. GEMINI.md only when it's already there. */
+export const POINTER_FILES = ["CLAUDE.md", "AGENTS.md"];
+const IF_PRESENT = ["GEMINI.md"];
+/** Big enough for the decisions and open issues, small enough that an agent reads it whole. */
+export const BRIEF_CAP = 6000;
+const EXCLUDE_START = "# >>> huddle brief >>>";
+const EXCLUDE_END = "# <<< huddle brief <<<";
+export const briefOff = () => !!process.env.HUDDLE_NO_BRIEF && process.env.HUDDLE_NO_BRIEF !== "0";
+const flat = (s, n = 200) => {
+    const l = String(s ?? "").replace(/\s+/g, " ").trim();
+    return l.length <= n ? l : l.slice(0, n - 1) + "…";
+};
+const str = (v) => (v === undefined || v === null ? "" : typeof v === "string" ? v : JSON.stringify(v));
+const arr = (v) => (Array.isArray(v) ? v.map(str).filter(Boolean) : []);
+/** Forward slashes, repo-relative where we can tell: a brief written on Windows reads the same everywhere. */
+export const slash = (f) => f.replace(/\\/g, "/").replace(/^\.\//, "");
+const date = (ts) => (ts ? new Date(ts).toISOString().slice(0, 16).replace("T", " ") + " UTC" : "");
+/** At most `n` lines, then how many more. */
+const capped = (lines, n, more = "more in `huddle story`") => (lines.length > n ? [...lines.slice(0, n), `- …and ${lines.length - n} ${more}`] : lines);
+/** The brief for one run. Deterministic: the same Room records give the same text. */
+export function buildBrief(s, x = {}) {
+    const ev = s.run.events;
+    const titleOf = new Map();
+    for (const e of ev)
+        if (e.type === "task.added")
+            titleOf.set(str(e.p.id) || e.task || "", str(e.p.title));
+    const tt = (task, p) => str(p.title) || (task ? titleOf.get(task) ?? task : "");
+    // Merged tasks, in order, with who landed them and what they said they did.
+    const merged = ev.filter((e) => e.type === "run.merged").map((e) => ({ task: e.task ?? "", agent: str(e.p.agent) || e.agent || "?", title: tt(e.task, e.p) }));
+    const landed = new Set(merged.map((m) => m.task));
+    const done = new Map();
+    for (const e of ev) {
+        const m = e.type === "memory.added" ? /^Task (\S+) done:\s*([\s\S]*)$/.exec(str(e.p.body)) : null;
+        if (m)
+            done.set(m[1], m[2]);
+    }
+    const planned = new Map(s.plan.tasks.map((t) => [t.id, t.files]));
+    const out = [];
+    const agents = s.agents.length ? s.agents.join(", ") : "no agents";
+    out.push(`# Huddle hand-off brief`);
+    out.push("");
+    out.push(`Run ${s.run.index}${s.run.id ? ` (${s.run.id})` : ""} · ${date(s.run.start)} · ${agents} · ${s.merged} merged, ${s.failed} failed`);
+    out.push("");
+    out.push("A team of AI agents worked on this repo together through Huddle. This is what they left for whoever works here next.");
+    out.push("");
+    out.push("## Goal");
+    out.push("");
+    const goal = s.run.goal.trim();
+    out.push(goal.length > 700 ? goal.slice(0, 699).trimEnd() + "… (full goal: `huddle story`)" : goal);
+    out.push("");
+    out.push("## What was built");
+    out.push("");
+    if (!merged.length)
+        out.push("Nothing was merged in this run.");
+    const built = merged.map((m) => {
+        const h = x.handoffs?.get(m.task);
+        const files = (h?.files?.length ? h.files : planned.get(m.task) ?? []).map(slash);
+        const fileNote = files.length ? ` — ${files.slice(0, 6).join(", ")}${files.length > 6 ? ` +${files.length - 6}` : ""}${h?.files?.length ? "" : " (planned)"}` : "";
+        const what = flat(h?.summary || done.get(m.task) || "", 160);
+        return `- ${m.title} (${m.agent})${fileNote}${what && what !== m.title ? `\n  ${what}` : ""}`;
+    });
+    out.push(...capped(built, 12));
+    out.push("");
+    out.push("## Who built what");
+    out.push("");
+    const crew = [];
+    for (const a of s.agents) {
+        const st = s.stats.get(a);
+        const mine = merged.filter((m) => m.agent === a).map((m) => m.title);
+        const extra = [st?.reviews ? `${st.reviews} review(s)` : "", st?.failed ? `${st.failed} failed` : "", st?.bugsFound ? `${st.bugsFound} QA bug(s) found` : "", st?.takeoversIn ? `took over ${st.takeoversIn}` : ""].filter(Boolean);
+        if (!mine.length && !extra.length)
+            continue;
+        crew.push(`- ${a}: ${mine.length ? mine.map((t) => flat(t, 70)).join("; ") : "no merged tasks"}${extra.length ? ` · ${extra.join(", ")}` : ""}`);
+    }
+    out.push(...(crew.length ? crew : ["No agent finished a task."]));
+    out.push("");
+    out.push("## Decisions and why");
+    out.push("");
+    const dec = [];
+    const cp = ev.filter((e) => e.type === "council.plan").at(-1)?.p;
+    const members = arr(cp?.members);
+    for (const d of arr(cp?.decisions))
+        dec.push(`- ${flat(d)} (design council${members.length ? `: ${members.join(", ")}` : ""})`);
+    for (const r of Array.isArray(cp?.risks) ? cp.risks : [])
+        if (r?.body)
+            dec.push(`- Risk: ${flat(r.body)}${r.by ? ` (flagged by ${r.by})` : ""}`);
+    const c = s.collab;
+    if (c.synthesizer?.why)
+        dec.push(`- Plan written by ${c.synthesizer.id}: ${flat(c.synthesizer.why, 160)}`);
+    for (const o of c.objections)
+        dec.push(`- ${o.taken ? "Changed the plan after" : "Kept the plan over"} ${o.by}'s objection: ${flat(o.objection, 160)}`);
+    // An agent's own decisions, with the reason it gave (huddle_remember kind=decision).
+    for (const e of ev) {
+        if (e.type !== "memory.added" || str(e.p.kind) !== "decision")
+            continue;
+        const by = str(e.p.author) || e.agent || "";
+        if (by === "council" || by === "huddle")
+            continue;
+        dec.push(`- ${flat(e.p.body)} (${by}${e.p.why ? `; why: ${flat(e.p.why, 140)}` : ""})`);
+    }
+    out.push(...(dec.length ? capped(dec, 14) : ["No decisions were recorded."]));
+    if (c.contract || c.amendments.length) {
+        const v = c.amendments.length ? Math.max(...c.amendments.map((a) => a.version)) : 1;
+        out.push("");
+        out.push(`Contract: HUDDLE_CONTRACT.md (v${v}${c.contract ? `, written by ${c.contract.by}` : ""}) fixes the names, files and messages every task coded to. Keep to it, or change it on purpose.`);
+        out.push(...capped(c.amendments.map((a) => `- v${a.version} by ${a.by}: ${flat(a.change, 160)}`), 6));
+    }
+    out.push("");
+    out.push("## Open issues");
+    out.push("");
+    const open = [];
+    const lastFail = new Map();
+    for (const e of ev)
+        if (e.type === "run.failed" && e.task)
+            lastFail.set(e.task, { agent: str(e.p.agent) || e.agent || "?", title: tt(e.task, e.p), reason: str(e.p.reason), needsYou: e.p.needsYou === true });
+    for (const [task, f] of lastFail)
+        if (!landed.has(task))
+            open.push(`- ${f.needsYou ? "Needs you" : "Failed"}: ${f.title} (${f.agent})${f.reason ? ` — ${flat(f.reason, 140)}` : ""}`);
+    for (const e of ev)
+        if (e.type === "run.stuck")
+            open.push(`- Blocked by those failures, never started: ${arr(e.p.blocked).map((b) => flat(b, 60)).join("; ")}`);
+    for (const b of c.bugs.filter((b) => !b.fixedBy))
+        open.push(`- QA bug not fixed: ${flat(b.title, 160)} (found by ${b.by}${b.to ? `, fix was ${b.to}'s` : ""})`);
+    for (const f of c.followups.filter((f) => f.how === "ignored"))
+        open.push(`- ${f.kind === "radar" ? "Radar finding" : `${f.by}'s buddy note`} on ${f.task ? `"${flat(f.task, 60)}"` : "a task"} was never answered: ${flat(f.note.replace(/^buddy check from [^:]*:\s*/i, ""), 160)}`);
+    for (const b of c.buddy.filter((b) => b.late))
+        open.push(`- ${b.agent}'s notes on ${b.author}'s work came back after it landed: ${flat(b.notes, 160)}`);
+    for (const e of ev) {
+        if (e.type === "qa.capped")
+            open.push(`- QA stopped after round ${str(e.p.round)}: the last fixes were not re-checked${Number(e.p.open) ? ` (${str(e.p.open)} still open)` : ""}.`);
+        if (e.type === "qa.unchecked")
+            open.push(`- QA round ${str(e.p.round)} did not check the build: ${flat(e.p.reason, 140) || "no check finished"}.`);
+    }
+    out.push(...(open.length ? capped(open, 14) : ["None recorded."]));
+    out.push("");
+    out.push("## How to continue");
+    out.push("");
+    const next = [];
+    if (x.testCmd)
+        next.push(`- Tests: \`${x.testCmd}\` (every merge passed it).`);
+    else
+        next.push("- No test command was found, so merges weren't gated on tests.");
+    for (const p of x.parked ?? [])
+        next.push(`- Parked work for "${flat(p.title, 60)}" is on \`${p.branch}\`: \`git merge ${p.branch}\`, resolve, commit.`);
+    for (const b of x.branches ?? [])
+        next.push(`- Unmerged work for "${flat(b.title, 60)}" is on \`${b.branch}\`.`);
+    if (c.contract || c.amendments.length)
+        next.push("- Read HUDDLE_CONTRACT.md before renaming anything it names.");
+    next.push("- Everything that happened: `huddle story` (timeline), `huddle story --html story.html`, `huddle export` (the full record).");
+    out.push(...next);
+    return capBrief(out.join("\n") + "\n");
+}
+/** Cut at a line, under the cap, saying where the rest is. */
+export function capBrief(text, cap = BRIEF_CAP) {
+    if (text.length <= cap)
+        return text;
+    const tail = "\n\n… (cut to fit; `huddle story` and `huddle export` have the rest)\n";
+    const cut = text.lastIndexOf("\n", cap - tail.length);
+    return text.slice(0, cut > 0 ? cut : cap - tail.length) + tail;
+}
+// ---- the pointer block (pure: text in, text out) -------------------------------
+const eolOf = (text) => (text.includes("\r\n") ? "\r\n" : "\n");
+/** The block's lines, in the file's own line endings. */
+export function pointerBlock(info, eol = "\n") {
+    return [
+        BRIEF_START,
+        `This repo was last worked on by a Huddle team run (${info.date}, "${goalTitle(info.goal, 80).replace(/"/g, "'")}"). Read .huddle/BRIEF.md before changing code; it lists the decisions, the contract and open issues.`,
+        "(Kept up to date by Huddle between the markers; `huddle brief off` removes it.)",
+        BRIEF_END,
+    ].join(eol);
+}
+/** [start, end) of the block in `text`, end past the end marker; null if none. */
+function span(text) {
+    const i = text.indexOf(BRIEF_START);
+    const j = i < 0 ? -1 : text.indexOf(BRIEF_END, i);
+    return i < 0 || j < 0 ? null : [i, j + BRIEF_END.length];
+}
+export const hasBlock = (text) => span(text) !== null;
+/** The block as it stands in `text` (markers included), or null. */
+export const blockOf = (text) => {
+    const s = span(text);
+    return s ? text.slice(s[0], s[1]) : null;
+};
+/**
+ * `text` with `block` in it: in place of the old one, or at the top (agents
+ * read top-down) with a blank line after it. Everything else, byte for byte.
+ */
+export function upsertBlock(text, block) {
+    const s = span(text);
+    if (s)
+        return text.slice(0, s[0]) + block + text.slice(s[1]);
+    const bom = text.startsWith("") ? "" : "";
+    const eol = eolOf(text);
+    const body = text.slice(bom.length);
+    return bom + block + eol + (body ? eol : "") + body;
+}
+/** `text` without the block — exactly what it was before upsertBlock added it. */
+export function stripBlock(text) {
+    const s = span(text);
+    if (!s)
+        return text;
+    let end = s[1];
+    for (let k = 0; k < 2; k++) {
+        if (text.startsWith("\r\n", end))
+            end += 2;
+        else if (text[end] === "\n")
+            end += 1;
+    }
+    return text.slice(0, s[0]) + text.slice(end);
+}
+const stateFile = (root) => path.join(root, ".huddle", "brief.json");
+function readState(root) {
+    try {
+        const j = JSON.parse(fs.readFileSync(stateFile(root), "utf8"));
+        return { created: arr(j.created), lifted: arr(j.lifted), declined: arr(j.declined), last: j.last };
+    }
+    catch {
+        return { created: [], lifted: [], declined: [] };
+    }
+}
+function writeState(root, s) {
+    fs.mkdirSync(path.dirname(stateFile(root)), { recursive: true });
+    fs.writeFileSync(stateFile(root), JSON.stringify(s, null, 2));
+}
+function git(root, args) {
+    try {
+        return { ok: true, out: execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }) };
+    }
+    catch {
+        return { ok: false, out: "" };
+    }
+}
+const tracked = (root, f) => git(root, ["ls-files", "--error-unmatch", "--", f]).ok;
+/** The committed text, or null if HEAD doesn't have the file. */
+const atHead = (root, f) => {
+    const r = git(root, ["show", `HEAD:${f}`]);
+    return r.ok ? r.out : null;
+};
+/** Keep the files Huddle created out of commits, in a marked block of .git/info/exclude (like `huddle connect`). */
+function setExcludes(root, files) {
+    const p = git(root, ["rev-parse", "--git-path", "info/exclude"]).out.trim() || ".git/info/exclude";
+    const ex = path.isAbsolute(p) ? p : path.join(root, p);
+    const cur = fs.existsSync(ex) ? fs.readFileSync(ex, "utf8") : "";
+    const i = cur.indexOf(EXCLUDE_START);
+    const j = cur.indexOf(EXCLUDE_END);
+    const base = i >= 0 && j > i ? cur.slice(0, i) + cur.slice(j + EXCLUDE_END.length).replace(/^\r?\n/, "") : cur;
+    const want = files.length ? `${EXCLUDE_START}\n${[...new Set(files)].sort().map((f) => "/" + f).join("\n")}\n${EXCLUDE_END}\n` : "";
+    const next = want ? base.replace(/([^\n])$/, "$1\n") + want : base;
+    if (next === cur)
+        return;
+    fs.mkdirSync(path.dirname(ex), { recursive: true });
+    fs.writeFileSync(ex, next);
+}
+const write = (abs, text) => {
+    if (!fs.existsSync(abs) || fs.readFileSync(abs, "utf8") !== text)
+        fs.writeFileSync(abs, text);
+};
+/**
+ * Before a run: take the pointer out, so the checkout is as the user left it.
+ * A file you committed with the block in keeps the committed block; a file
+ * Huddle created and nobody added to is removed (and comes back after).
+ */
+export function liftPointers(root) {
+    if (!fs.existsSync(path.join(root, ".huddle")))
+        return [];
+    const st = readState(root);
+    const lifted = [];
+    for (const f of [...POINTER_FILES, ...IF_PRESENT]) {
+        const abs = path.join(root, f);
+        if (!fs.existsSync(abs))
+            continue;
+        const cur = fs.readFileSync(abs, "utf8");
+        if (!hasBlock(cur))
+            continue;
+        const head = tracked(root, f) ? atHead(root, f) : null;
+        const committed = head !== null ? blockOf(head) : null;
+        const next = committed ? upsertBlock(cur, committed) : stripBlock(cur);
+        if (st.created.includes(f) && !next.replace(/^/, "").trim()) {
+            fs.rmSync(abs);
+            if (!st.lifted.includes(f))
+                st.lifted.push(f);
+        }
+        else {
+            write(abs, next);
+            // You wrote in a file Huddle made: it's yours now, and git should see it.
+            st.created = st.created.filter((x) => x !== f);
+        }
+        lifted.push(f);
+    }
+    if (lifted.length) {
+        writeState(root, st);
+        setExcludes(root, st.created);
+    }
+    return lifted;
+}
+/** After a run (or when it stopped early): point CLAUDE.md / AGENTS.md at the brief. Idempotent. */
+export function placePointers(root, opts) {
+    const res = { files: [], created: [], tracked: [] };
+    if (!fs.existsSync(path.join(root, ".huddle")))
+        return res;
+    const st = readState(root);
+    if (!opts.enabled || briefOff() || !st.last || !fs.existsSync(path.join(root, ".huddle", "BRIEF.md")))
+        return res;
+    for (const f of [...POINTER_FILES, ...IF_PRESENT]) {
+        const abs = path.join(root, f);
+        if (!fs.existsSync(abs)) {
+            if (IF_PRESENT.includes(f) || st.declined.includes(f))
+                continue;
+            // Huddle made it, it wasn't lifted, and it's gone: you deleted it. Don't make it again.
+            if (st.created.includes(f) && !st.lifted.includes(f)) {
+                st.created = st.created.filter((x) => x !== f);
+                st.declined.push(f);
+                continue;
+            }
+            fs.writeFileSync(abs, pointerBlock(st.last) + "\n");
+            if (!st.created.includes(f))
+                st.created.push(f);
+            res.files.push(f);
+            res.created.push(f);
+            continue;
+        }
+        const cur = fs.readFileSync(abs, "utf8");
+        if (st.created.includes(f) && stripBlock(cur).replace(/^/, "").trim())
+            st.created = st.created.filter((x) => x !== f); // yours now
+        write(abs, upsertBlock(cur, pointerBlock(st.last, eolOf(cur))));
+        res.files.push(f);
+        if (st.created.includes(f))
+            res.created.push(f);
+        else if (tracked(root, f))
+            res.tracked.push(f);
+    }
+    st.lifted = [];
+    writeState(root, st);
+    setExcludes(root, st.created);
+    return res;
+}
+/** `huddle brief off`: every pointer out now; files Huddle made (and nobody added to) removed. */
+export function removePointers(root) {
+    if (!fs.existsSync(path.join(root, ".huddle")))
+        return [];
+    const st = readState(root);
+    const touched = [];
+    for (const f of [...POINTER_FILES, ...IF_PRESENT]) {
+        const abs = path.join(root, f);
+        if (!fs.existsSync(abs))
+            continue;
+        const cur = fs.readFileSync(abs, "utf8");
+        if (!hasBlock(cur))
+            continue;
+        const left = stripBlock(cur);
+        if (st.created.includes(f) && !left.replace(/^/, "").trim())
+            fs.rmSync(abs);
+        else
+            write(abs, left);
+        touched.push(f);
+    }
+    st.created = st.created.filter((f) => fs.existsSync(path.join(root, f)));
+    st.lifted = [];
+    writeState(root, st);
+    setExcludes(root, st.created);
+    return touched;
+}
+// ---- end of a run --------------------------------------------------------------
+/** A run's folder name: its session id, made safe for every filesystem. */
+export const runDir = (r) => (r.id ? r.id.replace(/[^\w.-]/g, "_") : `run-${r.index}`);
+/**
+ * The end of every run: the latest run's brief to .huddle/runs/<id>/BRIEF.md
+ * and .huddle/BRIEF.md, then the pointers. Never throws — a brief that
+ * couldn't be written mustn't cost the run its RESULT.
+ */
+export function writeBrief(o) {
+    if (briefOff())
+        return null;
+    try {
+        const runs = splitRuns(o.events);
+        const run = runs.at(-1);
+        if (!run)
+            return null;
+        const story = buildStory(run, runs.length);
+        const handoffs = new Map();
+        for (const e of run.events)
+            if (e.type === "run.merged" && e.task && o.getHandoff) {
+                const h = o.getHandoff(e.task);
+                if (h)
+                    handoffs.set(e.task, h);
+            }
+        // Failed tasks whose branch is still there: the work isn't lost.
+        const parked = new Set((o.parked ?? []).map((p) => p.branch));
+        const branches = [];
+        const merged = new Set(run.events.filter((e) => e.type === "run.merged").map((e) => e.task));
+        for (const e of run.events) {
+            if (e.type !== "run.failed" || !e.task || merged.has(e.task))
+                continue;
+            const agent = String(e.p.agent ?? e.agent ?? "");
+            const branch = `huddle/${`${agent}-${e.task}`.replace(/[^\w.-]/g, "_")}`; // worktreeFor's naming
+            if (!parked.has(branch) && !branches.some((b) => b.branch === branch) && git(o.root, ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`]).ok)
+                branches.push({ title: String(e.p.title ?? e.task), branch });
+        }
+        const text = buildBrief(story, { handoffs, testCmd: o.testCmd, parked: o.parked, branches });
+        const dir = path.join(o.root, ".huddle", "runs", runDir(run));
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, "BRIEF.md"), text);
+        fs.writeFileSync(path.join(o.root, ".huddle", "BRIEF.md"), text);
+        const st = readState(o.root);
+        writeState(o.root, { ...st, last: { date: new Date(run.start || Date.now()).toISOString().slice(0, 10), goal: run.goal, run: runDir(run) } });
+        return { path: path.join(o.root, ".huddle", "BRIEF.md"), pointers: placePointers(o.root, { enabled: o.enabled }) };
+    }
+    catch {
+        return null;
+    }
+}
+/** The RESULT's line about it, and where the pointer change lives. */
+export function briefLines(w) {
+    const p = w.pointers;
+    const out = [`  ${C.violet("◆")} brief for your next solo session: .huddle/BRIEF.md${p.files.length ? ` (pointed to from ${p.files.join(", ")})` : ""}`];
+    const notes = [
+        p.tracked.length ? `${p.tracked.join(", ")}: block left uncommitted, lifted out while runs work` : "",
+        p.created.length ? `${p.created.join(", ")}: new, git-excluded` : "",
+    ].filter(Boolean);
+    if (notes.length)
+        out.push(C.faint(`      ${notes.join(" · ")} · huddle brief off to stop`));
+    return out;
+}
+// ---- CLI -----------------------------------------------------------------------
+/** `huddle brief [--run <n|id>] | off | on`. */
+export async function runBrief(args) {
+    const { dbPath, readPrefs, repoRoot, writePrefs } = await import("./app.js");
+    const root = repoRoot();
+    if (args[0] === "off" || args[0] === "on") {
+        const on = args[0] === "on";
+        writePrefs({ ...readPrefs(), brief: on });
+        if (!on) {
+            const gone = removePointers(root);
+            console.log(`${C.green("✓")} brief pointers off${gone.length ? ` · removed from ${gone.join(", ")}` : ""} ${C.faint("· .huddle/BRIEF.md is still written · huddle brief on to resume")}`);
+            return;
+        }
+        const r = placePointers(root, { enabled: true });
+        console.log(`${C.green("✓")} brief pointers on${r.files.length ? ` · ${r.files.join(", ")} point to .huddle/BRIEF.md` : C.faint(" · they appear after the next run")}`);
+        return;
+    }
+    const i = args.indexOf("--run");
+    const which = i >= 0 ? args[i + 1] : args.find((a) => a.startsWith("--run="))?.slice(6);
+    if (which === undefined) {
+        const f = path.join(root, ".huddle", "BRIEF.md");
+        if (fs.existsSync(f))
+            return void process.stdout.write(fs.readFileSync(f, "utf8"));
+    }
+    if (!fs.existsSync(dbPath()))
+        return void console.log(C.faint("  no runs yet — the brief is written at the end of each `huddle join` run."));
+    const { RoomDB } = await import("../room/db.js");
+    const db = new RoomDB(dbPath());
+    let runs;
+    try {
+        runs = splitRuns(db.allEvents());
+    }
+    finally {
+        db.close();
+    }
+    const run = pickRun(runs, which);
+    if (!run) {
+        console.log(C.red(`✗ no run ${which ?? ""}.`) + " See `huddle story --list`.");
+        process.exitCode = 1;
+        return;
+    }
+    // The saved one has the handoffs' files and parked branches; an older run gets one from its events.
+    const saved = path.join(root, ".huddle", "runs", runDir(run), "BRIEF.md");
+    process.stdout.write(fs.existsSync(saved) ? fs.readFileSync(saved, "utf8") : buildBrief(buildStory(run, runs.length)));
+}
+//# sourceMappingURL=brief.js.map

package/dist/ui/catalog.js

@@ -1,34 +1,45 @@
 // `huddle agents --all`: every connector Huddle knows — built in, or declared
 // in agents.json — with whether it's on this machine and how to get it.
 // `huddle agents install <id>` installs one, always after asking.
+import os from "node:os";
 import readline from "node:readline/promises";
-import { spawnSync } from "node:child_process";
-import { ADAPTERS, AGENTS_FILE_ERRORS, BUILTIN_ADAPTERS, probe } from "../adapters/index.js";
+import { ADAPTERS, AGENTS_FILE_ERRORS, BUILTIN_ADAPTERS, LEGACY, installCommand, noInstallHint, probe } from "../adapters/index.js";
 import { agentsFiles } from "../adapters/custom.js";
-import { C, dot, pad } from "./term.js";
+import { runInteractive, setAgentChoice, skippedAgents } from "./app.js";
+import { C, dot, lineWidth, pad, wrap } from "./term.js";
 function all() {
     const seen = new Map();
     for (const a of [...BUILTIN_ADAPTERS, ...ADAPTERS])
         seen.set(a.id, a); // the roster's version wins (agents.json overrides)
     return [...seen.values()];
 }
-const tilde = (p) => p.replace(process.env.HOME ?? "\0", "~");
+const tilde = (p) => p.replace(os.homedir(), "~");
+const stateText = (r) => r.state === "ready" ? C.green("ready") : r.state === "not_authed" ? C.yellow("not signed in") : C.faint("not installed");
+/** One agent's row: state, whether you use it, and the next command when there is one. */
+function printRow(a, r, skipped) {
+    const from = a.source ? C.faint(` · ${tilde(a.source)}`) : "";
+    const choice = skipped ? C.faint("skipped") : C.violet("used");
+    console.log(`  ${dot(a.id)} ${pad(C.bold(a.id), 13)} ${pad(C.faint(a.vendor), 13)} ${pad(stateText(r), 14)} ${from ? pad(choice, 8) + from : choice}`);
+    if (skipped)
+        return;
+    const cmd = installCommand(a);
+    // Hints wrap under the row (80 columns when piped), never past the edge.
+    const hint = (t) => wrap(t, (lineWidth() ?? 80) - 7, "  ").forEach((l) => console.log(`      ${C.faint(l)}`));
+    if (r.state === "not_installed")
+        hint(cmd ? "$ " + cmd : noInstallHint(a));
+    else if (r.state === "not_authed")
+        hint(r.detail);
+}
 export function printCatalog() {
     console.log(`\n${C.bold("Connectors")} ${C.faint("· any CLI that runs headless and speaks MCP can join")}\n`);
-    for (const a of all()) {
-        const r = probe(a);
-        const state = r.state === "ready" ? C.green("ready") : r.state === "not_authed" ? C.yellow("not signed in") : C.faint("not installed");
-        const from = a.source ? C.faint(` · ${tilde(a.source)}`) : "";
-        console.log(`  ${dot(a.id)} ${pad(C.bold(a.id), 13)} ${pad(C.faint(a.vendor), 13)} ${pad(state, 14)}${from}`);
-        if (r.state === "not_installed" && a.install.cmd)
-            console.log(`      ${C.faint("$ " + a.install.cmd)}`);
-        else if (r.state === "not_authed")
-            console.log(`      ${C.faint(r.detail)}`);
-    }
+    const skip = skippedAgents();
+    for (const a of all())
+        printRow(a, probe(a), skip.has(a.id));
     for (const e of AGENTS_FILE_ERRORS)
         console.log(`  ${C.yellow("!")} ${C.faint(e)}`);
     const f = agentsFiles(null);
     console.log(`\n  ${C.faint("install one:")} huddle agents install <id>`);
+    console.log(`  ${C.faint("choose:")}      huddle agents use <id>  ${C.faint("·")}  huddle agents skip <id>`);
     console.log(`  ${C.faint("add your own:")} ${tilde(f.user)} ${C.faint("(see docs/ADAPTERS.md)")}\n`);
 }
 /** Install a connector's CLI (and offer its sign-in) — only after a yes. */
@@ -38,32 +49,29 @@ export async function installConnector(id) {
         console.log(C.red(`✗ no connector called ${id}.`) + " See `huddle agents --all`.");
         return false;
     }
-    if (!a.install.cmd) {
-        console.log(`${a.id} has no install command — install ${a.bin} the way its docs say${a.homepage ? `: ${a.homepage}` : "."}`);
+    const cmd = installCommand(a);
+    if (!cmd) {
+        console.log(`${a.id}: ${noInstallHint(a)}`);
         return false;
     }
     if (!process.stdin.isTTY) {
-        console.log(`To install ${a.id}, run:\n  ${a.install.cmd}`);
+        console.log(`To install ${a.id}, run:\n  ${cmd}`);
         return false;
     }
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     try {
-        console.log(`\n  ${dot(a.id)} ${C.bold(a.id)}  ${C.faint("$ " + a.install.cmd)}`);
+        console.log(`\n  ${dot(a.id)} ${C.bold(a.id)}  ${C.faint("$ " + cmd)}`);
         const ans = (await rl.question(`Install ${a.id}? ${C.faint("[Y/n]")} `)).trim().toLowerCase();
         if (ans && !ans.startsWith("y"))
             return false;
-        rl.pause();
-        const ok = spawnSync("sh", ["-c", a.install.cmd], { stdio: "inherit" }).status === 0;
-        rl.resume();
+        const ok = runInteractive(rl, cmd);
         console.log(ok ? C.green(`✓ ${a.id} installed`) : C.red(`✗ ${a.id} install failed — see output above`));
         if (ok && a.install.login) {
             const go = (await rl.question(`Sign in to ${a.id} now? ${C.faint("[Y/n]")} `)).trim().toLowerCase();
             if (!go || go.startsWith("y")) {
                 if (a.install.loginNote)
                     console.log(C.faint(`  ${a.install.loginNote}`));
-                rl.pause();
-                spawnSync(a.install.login[0], a.install.login.slice(1), { stdio: "inherit" });
-                rl.resume();
+                runInteractive(rl, a.install.login);
             }
         }
         return ok;
@@ -72,4 +80,34 @@ export async function installConnector(id) {
         rl.close();
     }
 }
+/** `huddle agents`: the agents Huddle would use here, their state, and your use/skip choice. */
+export function printAgents() {
+    const skip = skippedAgents();
+    console.log(`\n${C.bold("Your agents")}\n`);
+    for (const a of ADAPTERS) {
+        const r = probe(a);
+        // Opt-in connectors stay out of the list until their CLI is on this machine.
+        if (LEGACY.has(a.id) && r.state === "not_installed")
+            continue;
+        printRow(a, r, skip.has(a.id));
+    }
+    console.log(`\n  ${C.faint("choose:")}          huddle agents use claude,codex  ${C.faint("·")}  huddle agents skip cursor`);
+    console.log(`  ${C.faint("set up the rest:")} huddle setup`);
+    console.log(`  ${C.faint("every connector:")} huddle agents --all\n`);
+}
+/** `huddle agents use|skip <ids>`: remembered in ~/.huddle/prefs.json. */
+export function chooseAgents(verb, list) {
+    const ids = list.flatMap((x) => x.split(",")).map((s) => s.trim()).filter(Boolean);
+    const known = new Set(all().map((a) => a.id));
+    const unknown = ids.filter((id) => !known.has(id));
+    if (!ids.length || unknown.length) {
+        console.log(C.red(`✗ no agent called ${unknown.join(", ") || "(none given)"}.`) + ` Known: ${[...known].join(", ")}`);
+        return false;
+    }
+    setAgentChoice(ids, verb === "use");
+    console.log(verb === "use"
+        ? `${C.green("✓")} using ${ids.join(", ")} ${C.faint("— `huddle setup` installs or signs in any that aren't ready")}`
+        : `${C.green("✓")} skipping ${ids.join(", ")} ${C.faint("— never installed, asked about, or put to work. Undo: huddle agents use " + ids.join(","))}`);
+    return true;
+}
 //# sourceMappingURL=catalog.js.map