huddle-cli 0.0.0-stage → 0.1.1

package/dist/orchestrator/goal.js

@@ -0,0 +1,196 @@
+// The goal's exact requirements, kept exact on their way to the agents.
+//
+// Found live (capstone round 5): the synthesizer paraphrased the brief. The
+// CSV rule "any field may be wrapped in double quotes" became "optional
+// double-quote wrapping", and the CSV task quoted fields mid-word, so
+// `The "Real" Thing` imported as `The Real Thing`. The CLI spec added
+// "invalid command syntax gives 'invalid arguments'", and `add --author X`
+// printed that instead of the brief's "title is required". The workers only
+// ever see their spec and the contract, never the goal, so nothing told them
+// the brief said otherwise; QA then judged the build against the contract.
+//
+// So, after any project plan is made (deterministic, no model call):
+//   - every task's spec carries the goal verbatim (or, for a very long goal,
+//     the goal lines relevant to it), with "the goal wins" over spec and contract
+//   - every exact string the goal quotes ("title is required", `no books`)
+//     that no spec and not the contract carries is assigned, with its whole
+//     goal line, to the task it fits best, so someone owns it
+//   - QA gets the same lines as a numbered acceptance checklist
+/** A bare heading line: "DATA", "TEXT FORMATS (CLI output and the markdown export)". */
+const HEADING = /^[A-Z][A-Z0-9 /&+-]{1,40}(\s*\([^)]*\))?:?$/;
+/** A heading with its body on the same line: "CSV IMPORT: the first line is…". */
+const HEAD_BODY = /^([A-Z][A-Z0-9 /&+-]{1,40}):\s+(.+)$/;
+const BULLET = /^(?:[-*•]|\d+[.)])\s+(.+)$/;
+/** The exact strings a line quotes. Very short ones ("id") say nothing about coverage. */
+export function goalAtoms(text) {
+    const out = [];
+    for (const m of text.matchAll(/`([^`\n]+)`|"([^"\n]+)"/g)) {
+        const a = (m[1] ?? m[2]).trim();
+        if (a.length >= 4 && /[\s<>#:,\[\]./-]/.test(a))
+            out.push(a);
+    }
+    return [...new Set(out)];
+}
+/** Split a paragraph into sentences without breaking "e.g." or a quoted span. */
+function sentences(p) {
+    const out = [];
+    let cur = "";
+    let quote = null;
+    for (let i = 0; i < p.length; i++) {
+        const c = p[i];
+        cur += c;
+        if (c === "`" || c === '"')
+            quote = quote === c ? null : quote ?? c;
+        if (!quote && /[.;!?]/.test(c) && /\s/.test(p[i + 1] ?? "") && /[A-Z`"]/.test(p.slice(i + 1).trimStart()[0] ?? "") && !/\b(e\.g|i\.e|etc|vs)\.$/i.test(cur)) {
+            out.push(cur.trim());
+            cur = "";
+        }
+    }
+    if (cur.trim())
+        out.push(cur.trim());
+    return out;
+}
+/** The goal as requirement lines: bullets, heading bodies, and the sentences of plain paragraphs. */
+export function goalItems(goal) {
+    const out = [];
+    let section = "";
+    const push = (text) => {
+        const t = text.trim();
+        if (t)
+            out.push({ text: t, section, atoms: goalAtoms(t) });
+    };
+    for (const raw of goal.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        if (HEADING.test(line) && !BULLET.test(line)) {
+            section = line.replace(/:$/, "").trim();
+            continue;
+        }
+        const b = BULLET.exec(line);
+        if (b) {
+            push(b[1]);
+            continue;
+        }
+        const h = HEAD_BODY.exec(line);
+        if (h) {
+            section = h[1].trim();
+            // A heading's body is one rule set ("CSV IMPORT: …; …; …"): keep it whole.
+            push(line);
+            continue;
+        }
+        for (const s of sentences(line))
+            push(s);
+    }
+    return out;
+}
+/** Lowercased, whitespace and quote style folded: what "the spec carries this string" compares. */
+const fold = (s) => s.toLowerCase().replace(/[`'"“”‘’\s]/g, "");
+const STOP = new Set("a an the and or of to in on at by for with from as is are be it its that this these those any every each one all no not only when then than into per via has have has use uses used must may can will shall should exactly e.g".split(" "));
+/** Words, plus the parts of a path ("src/cli.js" is also "src", "cli", "js"). */
+const wordsOf = (s) => new Set(s
+    .toLowerCase()
+    .replace(/[^\w/.#-]+/g, " ")
+    .split(/\s+/)
+    .map((w) => w.replace(/^[.#-]+|[.#-]+$/g, ""))
+    .flatMap((w) => (/[/.]/.test(w) ? [w, ...w.split(/[/.]+/)] : [w]))
+    .filter((w) => w.length > 1 && !STOP.has(w)));
+/**
+ * How much each task is about this goal line: shared words, weighted so a word
+ * every task uses ("book") counts little and a rare one ("csv", "stderr")
+ * counts a lot; a word of the line's heading counts triple, one in the task's
+ * title or file names double, and a file path
+ * the line names and the task owns counts most.
+ */
+function relevance(item, tasks) {
+    const docs = tasks.map((t) => wordsOf(`${t.title} ${t.spec} ${(t.files ?? []).join(" ")}`));
+    const titles = tasks.map((t) => wordsOf(`${t.title} ${(t.files ?? []).join(" ")}`));
+    const words = wordsOf(item.text);
+    // The goal's own heading ("CLI", "CSV IMPORT") says best which part a line is about.
+    const heading = wordsOf(item.section);
+    const paths = item.text.match(/\b[\w./-]+\.\w{1,5}\b/g) ?? [];
+    return tasks.map((t, i) => {
+        let s = 0;
+        for (const w of new Set([...words, ...heading])) {
+            if (!docs[i].has(w))
+                continue;
+            const df = docs.filter((d) => d.has(w)).length;
+            s += Math.log((tasks.length + 1) / df) * (heading.has(w) ? 3 : 1) * (titles[i].has(w) ? 2 : 1);
+        }
+        for (const p of paths)
+            if ((t.files ?? []).some((f) => f === p || f.endsWith("/" + p)))
+                s += 5;
+        return s;
+    });
+}
+/** Above this, a spec carries the goal lines relevant to it instead of the whole goal. */
+export const GOAL_VERBATIM_CAP = 8000;
+const RELEVANT_CAP = 4000;
+/**
+ * Make sure the goal reaches every worker exactly as written (see the top of
+ * this file). Pure: returns new tasks and what the check found.
+ */
+export function carryGoal(goal, tasks, contract = "") {
+    const items = goalItems(goal);
+    const atoms = [...new Set(items.flatMap((i) => i.atoms))];
+    const hay = fold([...tasks.map((t) => t.spec), contract].join("\n"));
+    const missing = atoms.filter((a) => !hay.includes(fold(a)));
+    const check = { atoms: atoms.length, missing, carried: {} };
+    if (!tasks.length || !goal.trim())
+        return { tasks, check };
+    const scores = items.map((it) => relevance(it, tasks));
+    // Each line with a missing string goes to the task it fits best (ties: the earlier task).
+    const carry = tasks.map(() => []);
+    items.forEach((it, k) => {
+        if (!it.atoms.some((a) => missing.includes(a)))
+            return;
+        const best = scores[k].reduce((bi, s, i, arr) => (s > arr[bi] ? i : bi), 0);
+        carry[best].push(it.text);
+    });
+    const whole = goal.trim().length <= GOAL_VERBATIM_CAP;
+    const out = tasks.map((t, i) => {
+        const parts = [t.spec];
+        if (carry[i].length) {
+            check.carried[t.title] = carry[i];
+            parts.push(`EXACT REQUIREMENTS no task spec or the contract carried — this task owns them; meet each exactly as written:\n${carry[i].map((l) => `- ${l}`).join("\n")}`);
+        }
+        if (whole && !fold(t.spec).includes(fold(goal).slice(0, 200))) {
+            parts.push(`THE GOAL, verbatim (the whole team's; your task is one part of it). Where your spec or the contract differs from an exact output, error message, format or rule here, the goal wins — code to the goal and tell the team (huddle_amend_contract):\n${goal.trim()}`);
+        }
+        else if (!whole) {
+            // Lines that matter to this task: its best-fitting ones, capped.
+            const mine = items
+                .map((it, k) => ({ it, s: scores[k][i], top: Math.max(...scores[k]) }))
+                .filter((x) => x.s > 0 && x.s >= x.top * 0.5)
+                .sort((a, b) => b.it.atoms.length - a.it.atoms.length || b.s - a.s);
+            const lines = [];
+            let n = 0;
+            for (const x of mine) {
+                if (n + x.it.text.length > RELEVANT_CAP)
+                    continue;
+                lines.push(`- ${x.it.section ? `${x.it.section}: ` : ""}${x.it.text}`);
+                n += x.it.text.length;
+            }
+            if (lines.length)
+                parts.push(`THE GOAL's lines for this task, verbatim. Where your spec or the contract differs from them, the goal wins:\n${lines.join("\n")}`);
+        }
+        return { ...t, spec: parts.join("\n\n") };
+    });
+    return { tasks: out, check };
+}
+/** The goal as QA's numbered acceptance checklist (capped). */
+export function acceptanceList(goal, cap = 8000) {
+    const lines = [];
+    let n = 0;
+    for (const [i, it] of goalItems(goal).entries()) {
+        const l = `${i + 1}. ${it.section ? `[${it.section}] ` : ""}${it.text}`;
+        if (n + l.length > cap) {
+            lines.push(`… (${goalItems(goal).length - i} more in the GOAL above)`);
+            break;
+        }
+        lines.push(l);
+        n += l.length;
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=goal.js.map

package/dist/orchestrator/handoff.js

@@ -0,0 +1,117 @@
+// Handoffs: when a task merges, the agents whose tasks depended on it start
+// with a compact brief from the author — what changed, the exact signatures it
+// exports, and the notes it left — instead of rediscovering it from the code.
+//
+// Captured right after the merge lands (base = main before the fast-forward),
+// stored in the Room, and injected into each dependent's launch prompt.
+import { execFileSync } from "node:child_process";
+const MAX_FILES = 30;
+const MAX_SYMBOLS = 25;
+const MAX_NOTES = 8;
+function git(cwd, args) {
+    return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 32 * 1024 * 1024 }).trim();
+}
+export function headSha(repoRoot) {
+    try {
+        return git(repoRoot, ["rev-parse", "HEAD"]);
+    }
+    catch {
+        return null;
+    }
+}
+// Lines that declare something other code can use. Deliberately simple: the
+// signature line is what a dependent needs, not a parse tree.
+const DECL = [
+    /^\s*export\s+(default\s+)?(declare\s+)?(async\s+)?(function\*?|class|interface|type|enum|const|let|var|abstract\s+class)\s+[\w$]+/, // TS / JS
+    /^\s*export\s*\{[^}]+\}/, // export { a, b }
+    /^module\.exports\b|^exports\.[\w$]+\s*=/, // CommonJS
+    /^(async\s+)?def\s+[A-Za-z]\w*\s*\(|^class\s+[A-Za-z]\w*/, // Python (top level, public)
+    /^func\s+(\([^)]*\)\s*)?[A-Z]\w*\s*\(|^type\s+[A-Z]\w*\s/, // Go (exported)
+    /^\s*pub\s+(async\s+)?(fn|struct|enum|trait|type|const|mod)\s+\w+/, // Rust
+];
+/** Exported signature lines added by a unified diff. */
+export function exportedSymbols(diff) {
+    const out = [];
+    let file = "";
+    for (const line of diff.split(/\r?\n/)) {
+        if (line.startsWith("+++ ")) {
+            file = line.replace(/^\+\+\+ (b\/)?/, "");
+            continue;
+        }
+        if (!line.startsWith("+") || line.startsWith("+++"))
+            continue;
+        const src = line.slice(1);
+        if (!DECL.some((r) => r.test(src)))
+            continue;
+        const sig = src.trim().replace(/\s*[{=]>?\s*$/, "").replace(/\s+/g, " ").slice(0, 160);
+        const entry = `${file}: ${sig}`;
+        if (!out.includes(entry))
+            out.push(entry);
+        if (out.length >= MAX_SYMBOLS)
+            break;
+    }
+    return out;
+}
+/** What a merge changed on main: name-status lines and exported signatures. */
+export function captureChanges(repoRoot, base) {
+    try {
+        const files = git(repoRoot, ["diff", "--name-status", "--no-renames", base, "HEAD"])
+            .split(/\r?\n/)
+            .filter(Boolean)
+            .map((l) => l.replace(/\t/, " "))
+            .slice(0, MAX_FILES);
+        const diff = git(repoRoot, ["diff", "--unified=0", "--no-color", base, "HEAD"]);
+        return { files, symbols: exportedSymbols(diff) };
+    }
+    catch {
+        return { files: [], symbols: [] };
+    }
+}
+/** Record the handoff for a just-merged task (base = main before it landed). */
+export function recordHandoff(db, repoRoot, opts) {
+    const { files, symbols } = opts.base ? captureChanges(repoRoot, opts.base) : { files: [], symbols: [] };
+    // The author's own notes from this task (its "Task … done" line is the summary).
+    const notes = db
+        .recall()
+        .filter((m) => m.author === opts.agentId && m.created_at >= opts.since && !m.body.startsWith(`Task ${opts.taskId} done:`))
+        .reverse()
+        .slice(0, MAX_NOTES)
+        .map((m) => `${m.kind}: ${m.body}${m.why ? ` (why: ${m.why})` : ""}`.slice(0, 400));
+    return db.saveHandoff({ task_id: opts.taskId, agent_id: opts.agentId, title: opts.title, files, symbols, notes });
+}
+export function handoffText(h) {
+    const lines = [`— from ${h.agent_id}, task "${h.title}" (${h.task_id}), merged into main:`];
+    if (h.summary)
+        lines.push(`  summary: ${h.summary}`);
+    if (h.files.length)
+        lines.push(`  files: ${h.files.join(", ")}`);
+    if (h.symbols.length) {
+        lines.push("  exports (use these exact names/signatures):");
+        for (const s of h.symbols)
+            lines.push(`    ${s}`);
+    }
+    if (h.notes.length) {
+        lines.push("  notes:");
+        for (const n of h.notes)
+            lines.push(`    - ${n}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * The handoff block for a task's launch prompt: one entry per merged
+ * dependency that has one. Empty string when there's nothing to hand off.
+ */
+export function handoffsFor(db, taskId) {
+    const task = db.getTask(taskId);
+    if (!task)
+        return { text: "", from: [] };
+    const deps = JSON.parse(task.depends_on || "[]");
+    const from = deps.map((d) => db.getHandoff(d)).filter((h) => !!h);
+    if (!from.length)
+        return { text: "", from };
+    return {
+        text: `\n\nHANDOFF — the tasks yours depends on are merged; their work is already in your directory:\n${from.map(handoffText).join("\n")}`,
+        from,
+    };
+}
+//# sourceMappingURL=handoff.js.map

package/dist/orchestrator/launcher.js

@@ -0,0 +1,171 @@
+// The launcher: for a scheduled task, it (1) makes the agent's sandbox worktree,
+// (2) hands the agent the Plug (MCP) in whatever way its vendor expects,
+// (3) spawns the agent CLI non-interactively with a prompt that tells it to use
+// the Room. Output goes to .huddle/logs/, not the user's terminal — the Huddle
+// screen shows progress from Room events instead.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createWorktree, worktreeFor } from "../sandbox/worktree.js";
+import { UsageMeter } from "../adapters/usage.js";
+import { hookCommand, killTree, spawnTool } from "../platform.js";
+import { lessonsBrief } from "../room/lessons.js";
+import { screenForTask } from "../room/context.js";
+const CHECKIN = `
+You are collaborating with other AI agents in a shared repo via the "huddle" MCP tools.
+RULES:
+1. Call huddle_recall() and huddle_board() BEFORE you start — inherit context, don't re-derive it.
+2. Your task below is already claimed for you — don't claim it again.
+3. Call huddle_announce_plan() with the files/symbols you'll touch BEFORE editing. If huddle_check_overlap flags a teammate, coordinate via huddle_remember instead of colliding.
+   Your task's file list is a plan, not a fence: if the work needs another file (e.g. a test wants your module registered in an index),
+   announce it and make the edit — Huddle lands same-file edits from different agents safely. Never finish with failing tests
+   because a file wasn't on your list; Huddle's merge gate runs the full test suite and rejects red work.
+4. Call huddle_progress() at about 25%, 50% and 75% done (and after big steps): its result is how teammates' contracts
+   and notes reach you mid-task. Read any new_messages in a result and adjust your work before going on.
+5. Record decisions with huddle_remember(kind="decision", ..., why=...) so teammates learn WHY.
+   Unsure about a shape or contract another task owns? huddle_ask("…", to="<agent>") before guessing — teammates may be on other machines.
+   Changing something a teammate relies on? Tell them: huddle_send(to="<agent>" or "all", message="…").
+   Answer a teammate's question with huddle_send(reply_to=…).
+   A teammate offers help and part of your task is separable? huddle_split it to them instead of doing it all yourself.
+   A HANDOFF section below (if any) is what the tasks you depend on built — use those exact names.
+6. Do the work by editing files in your current directory. Don't commit — Huddle tests and merges for you.
+7. When finished, call huddle_done(task_id, summary).
+`.trim();
+// dist/orchestrator/launcher.js -> dist/cli.js
+const CLI_PATH = fileURLToPath(new URL("../cli.js", import.meta.url));
+function modelFor(adapter, role) {
+    return role === "orchestrator"
+        ? adapter.models.orchestrator
+        : role === "fast"
+            ? adapter.models.fast
+            : role === "reviewer"
+                ? adapter.models.reviewer
+                : adapter.models.worker;
+}
+/**
+ * Launch `agentId` (an instance of `adapter`) on a task. `dryRun` returns the
+ * exact command without creating a worktree or spawning anything.
+ */
+export function launchAgent(opts) {
+    const { repoRoot, adapter, agentId, role, taskId, taskSpec, roomUrl } = opts;
+    const wt = opts.worktree ?? (opts.dryRun ? worktreeFor(repoRoot, agentId, taskId) : createWorktree(repoRoot, agentId, taskId));
+    const slug = `${agentId}-${taskId}`.replace(/[^\w.-]/g, "_");
+    const runDir = path.join(repoRoot, ".huddle", "run", slug);
+    const logPath = path.join(repoRoot, ".huddle", "logs", `${slug}.log`);
+    const plug = {
+        command: process.execPath,
+        args: [CLI_PATH, "plug"],
+        env: { HUDDLE_ROOM_URL: roomUrl, HUDDLE_AGENT_ID: agentId, HUDDLE_SECRET: opts.roomSecret ?? "" },
+    };
+    let mcpConfigPath = null;
+    const excludes = [];
+    if (adapter.plug.file && adapter.plug.entry) {
+        const inWorktree = adapter.plug.file.in === "worktree";
+        mcpConfigPath = path.join(inWorktree ? wt.path : runDir, adapter.plug.file.path);
+        if (inWorktree)
+            excludes.push(adapter.plug.file.path);
+        if (!opts.dryRun)
+            writeJsonMerged(mcpConfigPath, adapter.plug.entry(plug));
+    }
+    // Teammates' messages after every tool use, for CLIs that support a hook.
+    let hookSettingsPath = null;
+    if (adapter.mailHook) {
+        hookSettingsPath = path.join(runDir, "hooks.json");
+        const command = hookCommand([process.execPath, CLI_PATH, "mail", "--hook", "--stamp", path.join(runDir, "mail.stamp")]);
+        if (!opts.dryRun) {
+            fs.mkdirSync(runDir, { recursive: true });
+            fs.writeFileSync(hookSettingsPath, JSON.stringify(adapter.mailHook(command), null, 2));
+        }
+    }
+    // The shared screen's index (not its content) + this task's linked items.
+    const screen = screenForTask(repoRoot, taskId);
+    const prompt = `${CHECKIN}\n\n${lessonsBrief({ agentId, repo: repoRoot, dry: opts.dryRun })}YOUR TASK (task_id: ${taskId}): ${taskSpec}${screen.text ? "\n\n" + screen.text : ""}`;
+    const { cmd, cwd, env } = adapter.launch({
+        context: screen.dir ? { dir: screen.dir, images: screen.images } : undefined,
+        worktree: wt.path,
+        prompt,
+        model: modelFor(adapter, role),
+        mcpConfigPath,
+        plug,
+        approvals: opts.approvals,
+        hookSettingsPath,
+    });
+    const handle = {
+        agentId,
+        taskId,
+        worktree: wt.path,
+        branch: wt.branch,
+        cmd,
+        logPath,
+        excludes,
+        startedAt: Date.now(),
+        meter: new UsageMeter(),
+    };
+    if (opts.dryRun)
+        return handle;
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    const log = fs.createWriteStream(logPath, { flags: "a" });
+    handle.child = spawnTool(cmd, { cwd, stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, ...env, ...plug.env } }, { prompt, stdinPrompt: adapter.stdinPrompt });
+    // Everything still goes to the log; stdout is also scanned for token usage.
+    let partial = "";
+    handle.child.stdout.on("data", (chunk) => {
+        log.write(chunk);
+        if (!adapter.usage)
+            return;
+        const lines = (partial + chunk.toString("utf8")).split("\n");
+        partial = lines.pop() ?? "";
+        let changed = false;
+        for (const line of lines) {
+            const r = adapter.usage(line.trim());
+            if (r) {
+                handle.meter.add(r);
+                changed = true;
+            }
+        }
+        if (changed)
+            opts.onTokens?.(handle.meter.tokens);
+    });
+    handle.child.stderr.on("data", (chunk) => log.write(chunk));
+    // 'close', not 'exit': output can still arrive after the process exits (its pipes drain later),
+    // and a write after end() throws an unhandled stream error that takes the whole run down.
+    handle.child.on("close", () => log.end());
+    return handle;
+}
+/**
+ * Stop an agent's process: SIGTERM, then SIGKILL if it is still alive after
+ * `graceMs`. Found live on the capstone: a cursor-agent QA check whose
+ * connection stalled ignored SIGTERM, so QA's 15-minute time box did nothing
+ * and the run hung for 65 more minutes. On Windows the whole process tree goes
+ * at once (taskkill /T /F) — there is no SIGTERM, and the agent runs under a shim.
+ */
+export function stopChild(child, graceMs = 5000, platform = process.platform) {
+    if (!child || child.exitCode !== null || child.signalCode !== null)
+        return;
+    killTree(child, { platform });
+    setTimeout(() => {
+        if (child.exitCode === null && child.signalCode === null)
+            child.kill("SIGKILL");
+    }, graceMs).unref();
+}
+// --- tiny helpers ---------------------------------------------------------
+function writeJsonMerged(file, entry) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    let existing = {};
+    if (fs.existsSync(file)) {
+        try {
+            existing = JSON.parse(fs.readFileSync(file, "utf8"));
+        }
+        catch {
+            /* overwrite malformed */
+        }
+    }
+    fs.writeFileSync(file, JSON.stringify(deepMerge(existing, entry), null, 2));
+}
+function deepMerge(a, b) {
+    const out = { ...a };
+    for (const [k, v] of Object.entries(b)) {
+        out[k] = v && typeof v === "object" && !Array.isArray(v) ? deepMerge(a[k] ?? {}, v) : v;
+    }
+    return out;
+}
+//# sourceMappingURL=launcher.js.map

package/dist/orchestrator/learn.js

@@ -0,0 +1,105 @@
+// Learning at the end of a run: turn what Huddle itself saw — a council turn
+// that timed out, a task that stayed red through its fix round, two agents
+// colliding on a file, QA bugs, reviews sent back, a silent agent taken over —
+// into lessons for the next run (see room/lessons.ts). Deterministic: no model
+// call, only the run's own records, so a lesson always has evidence.
+import { addLesson, agentBase, lessonsOff, repoKey } from "../room/lessons.js";
+const MAX_PER_KIND = 3;
+const one = (s, n = 140) => {
+    const t = String(s ?? "").split("\n").map((l) => l.trim()).find(Boolean) ?? "";
+    return t.length <= n ? t : t.slice(0, n - 1) + "…";
+};
+/** The lessons a run teaches. `repo` is repoKey(root); `source` names the run. */
+export function deriveLessons(r, o) {
+    const out = [];
+    const repo = `repo:${o.repo}`;
+    const add = (d) => {
+        if (!out.some((x) => x.scope === d.scope && x.text === d.text))
+            out.push({ ...d, source: o.source });
+    };
+    // A council seat that timed out or never answered.
+    for (const e of r.room.filter((e) => e.type === "council.skipped").slice(0, MAX_PER_KIND * 2)) {
+        const who = agentBase(String(e.p.agent ?? e.agent ?? ""));
+        if (!who)
+            continue;
+        const reason = String(e.p.reason ?? "no answer");
+        add(/time/i.test(reason)
+            ? { scope: `agent:${who}`, text: `${who}: design-council turns time out on its default model — answer the council in far fewer words than the limit, sections only.`, evidence: `council ${e.p.round ?? ""} skipped: ${reason}` }
+            : { scope: `agent:${who}`, text: `${who}: its design-council turn came back empty — answer every council round, even briefly.`, evidence: `council ${e.p.round ?? ""} skipped: ${reason}` });
+    }
+    // Red through the fix round: the test gate rejected it twice.
+    const red = r.events.filter((e) => e.type === "failed" && /test/i.test(String(e.reason ?? "")) && !/stopped by you/.test(String(e.reason)));
+    for (const e of red.slice(0, MAX_PER_KIND))
+        add({
+            scope: `agent:${agentBase(String(e.agent))}`,
+            text: `Before huddle_done, run the repo's whole test suite yourself and make it pass: work of yours failed Huddle's test gate even after the fix round.`,
+            evidence: `${e.agent} · ${one(e.title)} · ${one(e.reason)}`,
+        });
+    // A rescue: the first agent crashed, went silent or stayed red.
+    for (const e of r.events.filter((e) => e.type === "takeover" && e.kind === "rescue").slice(0, MAX_PER_KIND)) {
+        const who = agentBase(String(e.from));
+        const why = String(e.reason ?? "");
+        add({
+            scope: `agent:${who}`,
+            text: /silent|quiet|progress|no output/i.test(why)
+                ? `Post huddle_progress after every step: ${who} went quiet mid-task and another agent took it over.`
+                : `${who} lost a task to a takeover (${one(why, 90)}): check in with huddle_progress and keep the tests green as you go.`,
+            evidence: `${e.agent} took over ${who}'s "${one(e.title, 60)}": ${one(why)}`,
+        });
+    }
+    // Two agents on the same lines of one file.
+    const collided = new Map();
+    for (const e of r.events.filter((e) => e.type === "conflict"))
+        for (const f of e.files ?? [])
+            collided.set(String(f), (collided.get(String(f)) ?? 0) + 1);
+    for (const [file, n] of [...collided].sort((a, b) => b[1] - a[1]).slice(0, MAX_PER_KIND))
+        add({ scope: repo, text: `Agents collide on ${file}: plan it as one owner — one task edits it, or every task that must is listed on it.`, evidence: `${n} merge conflict(s) in ${file}` });
+    // QA found it after merge: the authors' tests missed it.
+    const bugs = r.room.filter((e) => e.type === "qa.bug");
+    for (const e of bugs.slice(0, MAX_PER_KIND)) {
+        const files = (e.p.files ?? []);
+        add({
+            scope: repo,
+            text: `QA found "${one(e.p.title, 90)}"${files.length ? ` in ${files.slice(0, 2).join(", ")}` : ""} after it merged: test that kind of case before huddle_done.`,
+            evidence: `qa.bug by ${e.p.by ?? e.agent ?? "?"}: ${one(e.p.repro, 120)}`,
+        });
+    }
+    // A reviewer sent work back.
+    for (const e of r.events.filter((e) => e.type === "reviewed" && !e.approve && !e.skipped).slice(0, MAX_PER_KIND))
+        add({
+            scope: repo,
+            text: `A review sent "${one(e.title, 60)}" back: ${one(e.notes, 160)}`,
+            evidence: `${e.agent} reviewed ${e.author}'s work`,
+        });
+    // A reviewer that couldn't answer in time.
+    const slow = new Set(r.events.filter((e) => e.type === "reviewed" && e.skipped && /time/i.test(String(e.notes ?? ""))).map((e) => agentBase(String(e.agent))));
+    for (const who of slow)
+        add({ scope: `agent:${who}`, text: `${who}: reviews time out — read the diff in the prompt only and answer APPROVE or the changes in a few lines.`, evidence: "review skipped: timed out" });
+    return out;
+}
+/** The run's Room records learning reads. */
+export function roomRecords(db, since) {
+    return db.eventsOfType(["council.skipped", "qa.bug"], since, 200).map((e) => {
+        let p = {};
+        try {
+            p = JSON.parse(e.payload || "{}");
+        }
+        catch {
+            /* keep {} */
+        }
+        return { type: e.type, agent: e.agent_id ?? null, p };
+    });
+}
+/** Learn from a finished run and store it. Never throws: learning is a bonus, not a step that can fail a run. */
+export function learnFromRun(o) {
+    if (lessonsOff())
+        return [];
+    try {
+        const drafts = deriveLessons({ events: o.events, room: roomRecords(o.db, o.since) }, { repo: repoKey(o.root), source: `run:${new Date(o.since).toISOString().slice(0, 19)}` });
+        return drafts.map((d) => addLesson(d, o.home)?.lesson).filter((l) => !!l);
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=learn.js.map