huddle-cli 0.1.0 → 0.1.3

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

@@ -33,7 +33,7 @@ const DECL = [
 export function exportedSymbols(diff) {
     const out = [];
     let file = "";
-    for (const line of diff.split("\n")) {
+    for (const line of diff.split(/\r?\n/)) {
         if (line.startsWith("+++ ")) {
             file = line.replace(/^\+\+\+ (b\/)?/, "");
             continue;
@@ -56,7 +56,7 @@ export function exportedSymbols(diff) {
 export function captureChanges(repoRoot, base) {
     try {
         const files = git(repoRoot, ["diff", "--name-status", "--no-renames", base, "HEAD"])
-            .split("\n")
+            .split(/\r?\n/)
             .filter(Boolean)
             .map((l) => l.replace(/\t/, " "))
             .slice(0, MAX_FILES);

package/dist/orchestrator/launcher.js

@@ -3,12 +3,14 @@
 // (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 { spawn } from "node:child_process";
 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:
@@ -18,11 +20,12 @@ RULES:
    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() after each meaningful step.
+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="…").
-   If a tool result shows unread_messages, call huddle_inbox() and answer questions with huddle_send(reply_to=…).
+   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.
@@ -64,14 +67,28 @@ export function launchAgent(opts) {
         if (!opts.dryRun)
             writeJsonMerged(mcpConfigPath, adapter.plug.entry(plug));
     }
-    const prompt = `${CHECKIN}\n\nYOUR TASK (task_id: ${taskId}): ${taskSpec}`;
+    // 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,
@@ -88,11 +105,9 @@ export function launchAgent(opts) {
         return handle;
     fs.mkdirSync(path.dirname(logPath), { recursive: true });
     const log = fs.createWriteStream(logPath, { flags: "a" });
-    handle.child = spawn(cmd[0], cmd.slice(1), {
-        cwd,
-        stdio: ["ignore", "pipe", "pipe"],
-        env: { ...process.env, ...env, ...plug.env },
-    });
+    handle.child = spawnTool(cmd, 
+    // MCP_TOOL_TIMEOUT: Claude's wait on one tool call; huddle_ask_user may wait 90s for the person.
+    { cwd, stdio: ["ignore", "pipe", "pipe"], env: { MCP_TOOL_TIMEOUT: "150000", ...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) => {
@@ -113,19 +128,22 @@ export function launchAgent(opts) {
             opts.onTokens?.(handle.meter.tokens);
     });
     handle.child.stderr.on("data", (chunk) => log.write(chunk));
-    handle.child.on("exit", () => log.end());
+    // '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.
+ * 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) {
+export function stopChild(child, graceMs = 5000, platform = process.platform) {
     if (!child || child.exitCode !== null || child.signalCode !== null)
         return;
-    child.kill("SIGTERM");
+    killTree(child, { platform });
     setTimeout(() => {
         if (child.exitCode === null && child.signalCode === null)
             child.kill("SIGKILL");

package/dist/orchestrator/learn.js

@@ -0,0 +1,101 @@
+// 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: not a lesson. Its notes are about that one task (found live,
+    // 0.1.2: "src/main.js: io.stdout.write() is outside the try/catch…" stored as a rule).
+    // A general rule from it is the agent's to write: huddle_remember(kind="lesson").
+    // 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

package/dist/orchestrator/planner.js

@@ -3,6 +3,31 @@
 // any reason we fall back to a small deterministic template so a run never
 // blocks on planning.
 import { brainFrom, repoContext } from "./brain.js";
+import { linkPlan, parseContextIds } from "../room/context.js";
+import { carryGoal } from "./goal.js";
+/** The JSON fields the planner asks for, in both plan shapes. */
+const PLAIN_FIELDS = `"plain":"one or two short sentences a non-programmer understands: what the finished thing is and what it lets them do (no jargon: no exit codes, modules, ESM)","example":"one concrete example of using it and what you'd see, e.g. todo add milk → added: milk (or \"\" if there's nothing to show)"`;
+/** The plain summary from a plan reply, if the planner wrote one. */
+export function parsePlain(text) {
+    for (const body of jsonCandidates(text)) {
+        let raw;
+        try {
+            raw = JSON.parse(body);
+        }
+        catch {
+            continue;
+        }
+        if (!Array.isArray(raw?.tasks))
+            continue;
+        const tidy = (x, n) => (typeof x === "string" ? x.replace(/\s+/g, " ").trim().slice(0, n) : "");
+        const what = tidy(raw.plain ?? raw.summary, 400);
+        if (!what)
+            return undefined;
+        const example = tidy(raw.example, 200);
+        return example ? { what, example } : { what };
+    }
+    return undefined;
+}
 /**
  * Fallback when no brain can plan: the whole goal as ONE task. (It used to be
  * a scaffold → UI → logic → tests → review spine; seen live, a planner hiccup
@@ -50,22 +75,24 @@ ${context}
 
 ${council ? `${council.notes}
 
-` : ""}Plan from this snapshot${council ? " and the council's proposals and critiques: keep the best ideas, fix the flaws they found, and cover what they said was missing" : ""}. Split the goal into tasks. Rules:
+` : ""}Plan from this snapshot${council ? " and the council's proposals and cross-reviews: build on the ideas teammates ADOPTed, fix every FLAW they found, and cover what they said was missing" : ""}. Split the goal into tasks. Rules:
 ${sizeRules(crew.length, opts.project ?? !!council)}
 - Avoid a "scaffold first" bottleneck: if tasks share an interface, define it in each task's spec (exact function names, file paths, data shapes) so they can be built in parallel against that contract.
 - Parallel tasks should own disjoint files. List each task's files — every file it will edit, including shared ones it must touch (an index/registry/router that re-exports modules, package.json, a config). If two tasks must edit the same file, list it on both: Huddle then runs them one after the other, or merges both edits safely.
 - Never write "do not edit/touch <file>" in a spec to keep tasks apart: if the repo's tests or structure need a shared file changed (e.g. a test that every module is re-exported from an index), the task needs it — an agent that obeys the ban leaves the tests red and the task fails. List the file on each task that needs it instead.
 - Use depends_on only when a task truly needs another task's merged code.
 - Each spec must be self-contained: what to build, where, the contract, and how to verify it.
+- Carry the goal's exact requirements VERBATIM into the spec of every task that implements them: each exact output line, error message, format, number and edge-case rule (quoting, blank lines, bad rows, defaults, exit codes, stdout vs stderr), word for word — never paraphrased or shortened. Never invent a different message or output for a case the goal already gives one: a missing required input gets the goal's own error (e.g. "<field> is required"), not a generic usage error.
 - Consistency: different agents write each task, so start EVERY spec with the same one-line "Conventions:" (language/module system, formatting such as semicolons and quotes, test runner and test file naming). Take them from the existing code; if the repo is empty, choose them once and repeat them verbatim.
 - prefers: 1-3 tags from: ${TAGS.join(", ")}.
-
+${council ? `- contract: the exact names tasks share — files/modules and the task that owns each, exported functions with signatures, data types with field names, CLI flags, routes, error strings (the goal's exact strings, copied), test helpers. Markdown, under 3000 characters. Every spec uses these names verbatim. The contract adds names the goal leaves open; it never overrides what the goal states.
+` : ""}
 You have no tools in this step and cannot read files: the snapshot above is everything. Do not try to call a tool — plan from what you see.
 Reply with ONLY this JSON, no prose, no code fences:
 ${council
-        ? `{"tasks":[{"title":"short imperative title","spec":"...","files":["path"],"prefers":["tag"],"depends_on":[0],"from":["agent id whose proposal or critique this task came from"]}],"decisions":["a key design decision every agent must follow (max 6)"],"risks":[{"risk":"a risk or flaw to watch while building (max 6)","by":"agent id that flagged it"}]}
-"from" uses only these ids: ${council.members.join(", ")}.`
-        : `{"tasks":[{"title":"short imperative title","spec":"...","files":["path"],"prefers":["tag"],"depends_on":[0]}]}`}`;
+        ? `{"tasks":[{"title":"short imperative title","spec":"...","files":["path"],"prefers":["tag"],"depends_on":[0],"from":"the ONE agent id whose idea this task mainly implements","with":["other agent ids whose ideas it also uses"]}],"decisions":["a key design decision every agent must follow (max 6)"],"risks":[{"risk":"a risk or flaw to watch while building (max 6)","by":"agent id that flagged it"}],"contract":"markdown",${PLAIN_FIELDS}}
+"from" and "with" use only these ids: ${council.members.join(", ")}.`
+        : `{"tasks":[{"title":"short imperative title","spec":"...","files":["path"],"prefers":["tag"],"depends_on":[0]}],${PLAIN_FIELDS}}`}`;
 }
 /** Candidate JSON bodies in a reply: fenced blocks first, then brace-to-brace. */
 export function jsonCandidates(text) {
@@ -79,6 +106,12 @@ export function jsonCandidates(text) {
 }
 /** The most tasks a plan may have; a longer reply is not a plan. */
 export const MAX_TASKS = 20;
+/** A council task's idea credit: "from" is one primary id (or, from older prompts, a list), "with" the contributors. */
+function ideaFrom(t) {
+    const primary = typeof t.from === "string" ? [t.from] : Array.isArray(t.from) ? t.from.map(String) : [];
+    const from = [...new Set([...primary, ...(Array.isArray(t.with) ? t.with.map(String) : [])].map((x) => x.trim()).filter(Boolean))];
+    return from.length ? { from } : {};
+}
 /** Pull a {"tasks": [...]} plan out of a model's reply, however it was wrapped. */
 export function parsePlan(text) {
     for (const body of jsonCandidates(text)) {
@@ -102,7 +135,8 @@ export function parsePlan(text) {
             spec: String(t.spec ?? ""),
             files: Array.isArray(t.files) ? t.files.map(String) : [],
             prefers: Array.isArray(t.prefers) ? t.prefers.map(String) : [],
-            ...(Array.isArray(t.from) && t.from.length ? { from: t.from.map(String) } : {}),
+            ...ideaFrom(t),
+            ...(parseContextIds(t.context).length ? { context: parseContextIds(t.context) } : {}),
             // only backward edges → guaranteed acyclic
             depends_on: (Array.isArray(t.depends_on) ? t.depends_on : []).map(toIndex).filter((d) => Number.isInteger(d) && d >= 0 && d < i),
         }));
@@ -120,8 +154,8 @@ export async function planGoal(goal, crew, repoRoot, opts = {}) {
             signal: opts.signal,
             // A plan takes ~6–15s on a cloud model; a call that hangs is retried
             // instead of eating the whole budget (seen live: 4m30s, then the
-            // fallback). Local models are slower (up to ~4 min, see STATUS).
-            timeoutMs: brain.spec.startsWith("ollama") ? 4 * 60_000 : 2 * 60_000,
+            // fallback). Local models and Opus (the default brain) are slower.
+            timeoutMs: brain.spec.startsWith("ollama") || brain.spec === "claude" || brain.spec.endsWith(":opus") ? 4 * 60_000 : 2 * 60_000,
             json: true,
             // The snapshot is in the prompt; exploring just costs time. If that
             // first answer isn't a plan, the retry may read the repo (read-only).
@@ -129,11 +163,20 @@ export async function planGoal(goal, crew, repoRoot, opts = {}) {
         });
         ms += res.ms;
         const tasks = res.ok ? parsePlan(res.text) : null;
+        if (tasks && opts.project && tasks.length > 1) {
+            // A project's specs carry the goal's exact requirements too, as the council's do (goal.ts).
+            const carried = carryGoal(goal, tasks);
+            return { tasks: carried.tasks, by: brain.label, ms, tokens: res.tokens, goalCheck: carried.check, ...withPlain(res.text) };
+        }
         if (tasks)
-            return { tasks, by: brain.label, ms, tokens: res.tokens };
+            return { tasks, by: brain.label, ms, tokens: res.tokens, ...withPlain(res.text) };
     }
     return { tasks: templatePlan(goal), by: "template", note: `${brain.label} didn't return a usable plan`, ms };
 }
+const withPlain = (text) => {
+    const plain = parsePlain(text);
+    return plain ? { plain } : {};
+};
 /** Materialize a plan into the Room, wiring up dependency ids correctly. */
 export function seedBoard(db, goal, planned) {
     db.createSession(goal);
@@ -149,6 +192,8 @@ export function seedBoard(db, goal, planned) {
         const task = db.addTask({ title: p.title, spec, prefers: p.prefers, depends_on: deps, files: p.files });
         ids.push(task.id);
     }
+    // Shared-screen items the planner tied to each task ride in that task's prompt.
+    linkPlan(db, ids, planned);
     return ids;
 }
 /** "(1) … (2) …", "1. … 2. …" or "three tasks": the user already split the work. */