huddle-cli 0.1.1 → 0.1.5

package/dist/app/qr.js

@@ -0,0 +1,47 @@
+// A QR code in the terminal, for `huddle app --phone`: point the phone's
+// camera at it instead of typing a 70-character link.
+//
+// The encoder is the one qrcode-terminal ships (Kazuhiko Arase's, MIT); the
+// drawing is ours: two rows of the code per line of text (▀ with a top and a
+// bottom color), so a phone link fits in about 20 lines. In color it paints
+// black on bright white itself, so it scans on a light or a dark terminal.
+// Without color it draws the light parts with blocks, which reads right on a
+// dark terminal (phone cameras also read the inverted code a light one shows).
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+const QRCode = require("qrcode-terminal/vendor/QRCode/index.js");
+const LEVEL = require("qrcode-terminal/vendor/QRCode/QRErrorCorrectLevel.js");
+/** Light space around the code: scanners need some to find its corners. */
+export const QUIET = 2;
+/** The code's modules, true = dark, with the quiet zone around them. */
+export function qrMatrix(text, level = "L") {
+    const q = new QRCode(-1, LEVEL[level]); // -1: the smallest size that fits
+    q.addData(text);
+    q.make();
+    const n = q.getModuleCount();
+    const size = n + QUIET * 2;
+    return Array.from({ length: size }, (_, r) => Array.from({ length: size }, (_, c) => {
+        const y = r - QUIET;
+        const x = c - QUIET;
+        return y >= 0 && x >= 0 && y < n && x < n && q.isDark(y, x);
+    }));
+}
+/** The code as lines of text, two rows per line. */
+export function qrLines(text, opts) {
+    const m = qrMatrix(text);
+    const lines = [];
+    for (let r = 0; r < m.length; r += 2) {
+        let line = "";
+        for (let c = 0; c < m.length; c++) {
+            const top = m[r][c];
+            const bottom = r + 1 < m.length ? m[r + 1][c] : false;
+            if (opts.color)
+                line += `\x1b[${top ? 30 : 97};${bottom ? 40 : 107}m▀`;
+            else
+                line += !top && !bottom ? "█" : !top ? "▀" : !bottom ? "▄" : " ";
+        }
+        lines.push(opts.color ? line + "\x1b[0m" : line);
+    }
+    return lines;
+}
+//# sourceMappingURL=qr.js.map

package/dist/app/server.js

@@ -0,0 +1,433 @@
+// `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).
+//
+// `--phone` opens it to your Wi-Fi too, to run things from your phone: it
+// also listens on this machine's network addresses, and accepts those as the
+// Host (plus the tunnel's name with `--anywhere`). The token is still needed
+// for everything, and it's longer then, since the network can see the door.
+import { spawn } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import http from "node:http";
+import os from "node:os";
+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 { readConfig, githubReady } from "../connectors/hub.js";
+import { runAsync } from "../connectors/github.js";
+import { undoPlan, undoRun } from "../ui/undo.js";
+import { clearAppInfo, postCommand, readLive, readReport, writeAppInfo } from "./live.js";
+import { appPage } from "./page.js";
+import { qrLines } from "./qr.js";
+import { C } from "../ui/term.js";
+const CLI = fileURLToPath(new URL("../cli.js", import.meta.url));
+/**
+ * This machine's IPv4 addresses on its networks, the likeliest one for a
+ * phone first: Wi-Fi and Ethernet before VPNs and virtual machines' bridges
+ * (a Mac running a VM has a 192.168.x bridge no phone can reach).
+ */
+export function lanAddresses() {
+    const out = [];
+    for (const [name, list] of Object.entries(os.networkInterfaces())) {
+        const rank = /^(en|eth|wl|wlan|wi-?fi|ethernet)/i.test(name) ? 0 : /^(bridge|vmnet|vboxnet|virbr|docker|br-|veth|utun|tun|tap|tailscale|zt|ham|vethernet)/i.test(name) ? 2 : 1;
+        for (const a of list ?? []) {
+            if ((a.family === "IPv4" || a.family === 4) && !a.internal && !a.address.startsWith("169.254."))
+                out.push({ ip: a.address, rank });
+        }
+    }
+    const home = (ip) => /^(192\.168\.|10\.|172\.(1[6-9]|2\d|3[01])\.)/.test(ip);
+    out.sort((a, b) => a.rank - b.rank || Number(home(b.ip)) - Number(home(a.ip)));
+    return [...new Set(out.map((a) => a.ip))];
+}
+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);
+    // On the network, a longer key: 192 bits, still short enough for a small QR code.
+    const token = crypto.randomBytes(opts.phone ? 24 : 18).toString("base64url");
+    const tokenBuf = Buffer.from(token);
+    const keyOk = (given) => typeof given === "string" && given.length === token.length && crypto.timingSafeEqual(Buffer.from(given), tokenBuf);
+    const addresses = opts.addresses ?? lanAddresses;
+    const extraHosts = new Set();
+    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(),
+            // Changes when a run is undone (from here or `huddle undo`), so its view refetches.
+            undone: runs.reduce((n, r) => n + r.events.filter((e) => e.type === "git.undone").length, 0),
+            connectors: connectorsNow(),
+        };
+    };
+    /** What's configured, from ~/.huddle/connectors.json: shown, not started. */
+    const connectorsNow = () => {
+        const cfg = readConfig();
+        return {
+            github: cfg.github?.off ? "off" : cfg.github?.write ? "write" : "read",
+            others: Object.entries(cfg.connectors ?? {})
+                .filter(([, c]) => !c?.off)
+                .map(([name, c]) => ({ name, write: !!c?.write })),
+        };
+    };
+    // Open issues for the start screen. gh is slow (a network call), so the
+    // answer is kept a minute, and every page asking at once shares one call.
+    let github = null;
+    const githubView = () => {
+        if (github && Date.now() - github.at < 60_000)
+            return github.view;
+        const view = (async () => {
+            if (readConfig().github?.off)
+                return { ready: false, note: "GitHub is off (huddle connectors github on)", issues: [] };
+            const g = await githubReady(root);
+            if (!g.ok)
+                return { ready: false, note: g.note, issues: [] };
+            const r = await runAsync(["gh", "issue", "list", "--state", "open", "--limit", "20", "--json", "number,title"], { cwd: root, timeoutMs: 20_000 });
+            if (r.code !== 0)
+                return { ready: false, note: (r.stderr || r.stdout).trim().split("\n")[0].slice(0, 160) || "gh failed", issues: [] };
+            try {
+                const list = JSON.parse(r.stdout);
+                const issues = list
+                    .map((i) => ({ number: Number(i.number), title: String(i.title ?? "").slice(0, 200) }))
+                    .filter((i) => Number.isInteger(i.number) && i.number > 0)
+                    .slice(0, 20);
+                return { ready: true, note: g.note, issues };
+            }
+            catch {
+                return { ready: false, note: "couldn't read gh's answer", issues: [] };
+            }
+        })();
+        github = { at: Date.now(), view };
+        return view;
+    };
+    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;
+        // Whether this run can be taken back, and what that would revert (ui/undo.ts).
+        const undo = undoPlan(root, db.allEvents(), String(run.index));
+        return { ...doc, plain, report: readReport(root, run.id), undo: { ok: undo.ok, why: undo.why ?? "", commits: undo.commits ?? [], end: undo.end ?? "" } };
+    };
+    const allowedHost = (h, port) => {
+        if (h === `127.0.0.1:${port}` || h === `localhost:${port}`)
+            return true;
+        if (!opts.phone || !h)
+            return false;
+        // Checked on every request: the Wi-Fi can change while the dashboard is open.
+        return extraHosts.has(h.toLowerCase()) || addresses().some((ip) => h === `${ip}:${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 (!keyOk(url.searchParams.get("t"))) {
+                    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 (!keyOk(given))
+                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 === "GET /api/github")
+                return json(res, 200, await githubView());
+            if (route === "POST /api/undo") {
+                const body = await readBody(req);
+                // Never while a run is going: it's merging onto the branch this would revert on.
+                if (readLive(root))
+                    return json(res, 409, { error: "a run is going — undo once it's finished" });
+                const plan = undoPlan(root, db.allEvents(), String(body.n ?? ""));
+                if (!plan.ok)
+                    return json(res, 409, { error: plan.why });
+                // The commits you were shown are the ones reverted, or nothing is.
+                if (body.end && body.end !== plan.end)
+                    return json(res, 409, { error: "this run changed since you looked — look again" });
+                const done = undoRun(root, db, plan);
+                return done.ok ? json(res, 200, done) : json(res, 409, { error: done.why });
+            }
+            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, opts.phone ? "0.0.0.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();
+    };
+    const lanUrls = () => (opts.phone ? addresses().map((ip) => `http://${ip}:${port}/?t=${token}`) : []);
+    const allowHost = (h) => void extraHosts.add(h.toLowerCase());
+    return { url, port, token, lanUrls, allowHost, close };
+}
+/** `huddle app [--port n] [--no-open]` */
+export async function runApp(args) {
+    // Found live (0.1.5): `huddle app --help` opened a dashboard. A flag it doesn't know prints this instead.
+    const known = new Set(["--port", "--no-open", "--phone", "--anywhere"]);
+    const odd = args.find((a, k) => a.startsWith("-") && !known.has(a) && args[k - 1] !== "--port");
+    if (odd) {
+        console.log(`${C.bold("huddle app")}              the dashboard in your browser, for the repo you're in
+  --phone               open it on your phone too (same Wi-Fi): scan the QR code
+  --anywhere            on your phone from any network (needs cloudflared)
+  --no-open             don't open the browser   --port <n>  pick the port`);
+        if (odd !== "--help" && odd !== "-h") {
+            console.log(C.red(`✗ unknown: ${odd}`));
+            process.exitCode = 1;
+        }
+        return;
+    }
+    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 anywhere = args.includes("--anywhere");
+    const phone = anywhere || args.includes("--phone");
+    const app = await startApp({ root: repoRoot(), port, phone });
+    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"));
+    let tunnel = null;
+    if (phone) {
+        let link = app.lanUrls()[0] ?? null;
+        let how = "on the same Wi-Fi as this computer";
+        if (anywhere) {
+            const { hasCloudflared, openTunnel } = await import("../room/tunnel.js");
+            if (!hasCloudflared()) {
+                console.log(`  ${C.yellow("!")} --anywhere needs cloudflared (free, no account): ${cloudflaredHint()}`);
+                console.log(C.faint("    using your Wi-Fi for now"));
+            }
+            else {
+                const t = await openTunnel(app.port, (l) => console.log(C.faint(l)));
+                if (t) {
+                    tunnel = t;
+                    app.allowHost(new URL(t.url).host);
+                    link = `${t.url}/?t=${app.token}`;
+                    how = "from anywhere";
+                }
+            }
+        }
+        console.log("");
+        const also = link === app.lanUrls()[0] ? app.lanUrls().slice(1).map((u) => new URL(u).hostname) : [];
+        for (const l of phoneLines(link, how, process.stdout.isTTY === true && !process.env.NO_COLOR, also))
+            console.log(l);
+    }
+    if (!args.includes("--no-open"))
+        openBrowser(app.url);
+    const bye = () => {
+        tunnel?.close();
+        app.close();
+        process.exit(0);
+    };
+    process.on("SIGINT", bye);
+    process.on("SIGTERM", bye);
+}
+/**
+ * What `huddle app --phone` prints: the code to scan, the link under it, and
+ * what sharing it means. `link` is null when this machine has no network.
+ */
+export function phoneLines(link, how, color, also = []) {
+    if (!link)
+        return [`  ${C.yellow("!")} This computer is on no network, so a phone can't reach it. Join Wi-Fi, try again.`];
+    return [
+        `  ${C.bold("On your phone")} ${C.faint(`(${how})`)}: point the camera at this code`,
+        "",
+        ...qrLines(link, { color }).map((l) => "  " + l),
+        "",
+        `  or open ${C.bold(link)}`,
+        ...(also.length ? [C.faint(`    not working? try the same link with ${also.slice(0, 3).join(" or ")} in it`)] : []),
+        `  ${C.yellow("!")} Anyone with this link can control this run. Ctrl-C stops sharing.`,
+        ...(link.startsWith("http:") ? [C.faint("    Plain http on your Wi-Fi: fine on a network you trust. --anywhere is https.")] : []),
+    ];
+}
+/** How to get cloudflared here, in one line. */
+function cloudflaredHint() {
+    if (process.platform === "darwin")
+        return "brew install cloudflared";
+    if (process.platform === "win32")
+        return "winget install --id Cloudflare.cloudflared";
+    return "https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/";
+}
+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 update upgrade connectors connector undo 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" || (cmd === "fix" && rest.length > 0) || words.length >= 3 || /\s/.test(cmd))
+        return ["join", ...(cmd === "build" ? rest : args)];
+    return null;
+}
+//# sourceMappingURL=args.js.map

package/dist/attach/connect.js

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

package/dist/attach/plug.js

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