@loompad/cli 0.1.0 → 1.1.1

package/dist/core/orchestra.js

@@ -0,0 +1,2120 @@
+/**
+ * Orchestra — one orchestrator agent, many worker agents, in parallel.
+ *
+ * A route passes one baton down a line; a subtask fans out but never reports
+ * back. Orchestra is the missing shape: an orchestrator agent (any adapter —
+ * Claude Code, Codex, Antigravity, Grok, OpenCode) turns a goal into a task
+ * graph, Loom runs every ready task at once on whichever worker agents the
+ * plan names, each in its own thread and its own git worktree, merges the
+ * finished work into one integration branch, and hands the orchestrator the
+ * results to review — accept, follow up, spawn more, or finish.
+ *
+ * Design lineage, credited: the orchestrator/worker split, the "coordinate,
+ * never implement" orchestrator rules and the worktree-per-worker isolation
+ * follow Agent Orchestrator (github.com/Untrivial-ai/agent-orchestrator,
+ * Apache-2.0). What differs, on purpose:
+ *
+ *  - **The orchestrator never needs a shell tool.** AO's orchestrator drives a
+ *    CLI (`ao spawn`, `ao send`) from its terminal, which fails for agents that
+ *    run sandboxed or can't execute commands headless. Here it answers in a
+ *    fenced ```loom block of JSON actions that Loom parses — so ANY agent can
+ *    orchestrate, including ones with no tools at all.
+ *  - **A real task graph.** Tasks declare `dependsOn`; a task starts only when
+ *    its dependencies merged, and it branches from the integration tip so it
+ *    sees their work.
+ *  - **Mixed fleets.** Each task names its worker; three Codex tasks and two
+ *    Antigravity tasks run side by side as separate CLI sessions.
+ *
+ * Everything is observable: every step is an `orchestra` event in the project
+ * log (so the web app, the phone and the CLI all watch the same run), and each
+ * task's agent output streams into that task's own chat.
+ */
+import { execFile } from "./process.js";
+import fs from "node:fs";
+import path from "node:path";
+import { createWorktree } from "./worktrees.js";
+import { loomHome } from "./registry.js";
+import { blockedBy } from "./goal-lanes.js";
+import { cutStack } from "./team-landing.js";
+/** How much of a goal's budget may go before it says something. */
+export const BUDGET_WARN_AT = 0.8;
+/**
+ * Pull the actions out of an orchestrator reply.
+ *
+ * Accepts the last ```loom fence (the documented form), falling back to the
+ * last ```json fence holding an `actions` array, then to a bare object — models
+ * drift, and a plan lost to a fence label is a wasted round. Returns null when
+ * nothing parses, so the caller can ask again rather than guess.
+ */
+/**
+ * How much of an agent's turn is kept in memory, and why cutting it is delicate.
+ *
+ * The orchestrator's answer is parsed from this text, and the part that matters
+ * — the ```loom block — sits at the END of a reply whose prose can be long. The
+ * old cap kept the last 20,000 characters, which on any real plan threw away
+ * the OPENING fence while keeping the closing one. The parser then saw an
+ * unterminated block, reported that the reply had no actions, and the whole
+ * plan was silently discarded (#104). Measured on one real run: seven
+ * consecutive plans of 6, 5, 5, 5, 5, 8 and 8 tasks, every one of them parsed
+ * perfectly from the logged event and every one destroyed by the cap. The
+ * better the orchestrator planned, the more certainly its plan was binned.
+ *
+ * So two changes. The budget is large enough that no plausible reply reaches
+ * it — a turn is bounded by the model's own output limit long before this.
+ * And when it IS reached, the cut is made at the start of the last actions
+ * block rather than blindly at a character offset, so the payload can never be
+ * decapitated by the thing that is meant to be protecting memory.
+ */
+export const TURN_TEXT_LIMIT = 400_000;
+export function capTurnText(text, limit = TURN_TEXT_LIMIT) {
+    if (text.length <= limit)
+        return text;
+    // Where the parseable payload begins. Keeping from here guarantees the
+    // opening fence survives, whatever that costs us in preceding prose.
+    const starts = [text.lastIndexOf("```loom"), text.lastIndexOf('{"actions"')].filter((i) => i >= 0);
+    const keepFrom = starts.length ? Math.min(...starts) : -1;
+    // Only honour it when it actually saves the block: a payload so large it
+    // exceeds the budget on its own is already lost, and falling back to the
+    // plain tail at least bounds memory rather than keeping everything.
+    if (keepFrom >= 0 && text.length - keepFrom <= limit)
+        return text.slice(keepFrom);
+    return text.slice(-limit);
+}
+export function parseOrchestraActions(text) {
+    const fences = [...text.matchAll(/```([a-zA-Z-]*)\s*\n([\s\S]*?)```/g)];
+    const candidates = [];
+    for (const f of fences.reverse()) {
+        if (f[1] === "loom")
+            candidates.push(f[2]);
+    }
+    for (const f of fences) {
+        if (f[1] !== "loom" && f[2].includes('"actions"'))
+            candidates.push(f[2]);
+    }
+    const bare = text.lastIndexOf('{"actions"');
+    if (bare >= 0)
+        candidates.push(text.slice(bare));
+    for (const raw of candidates) {
+        const parsed = tryJson(raw.trim());
+        const list = Array.isArray(parsed)
+            ? parsed
+            : parsed && typeof parsed === "object" && Array.isArray(parsed.actions)
+                ? parsed.actions
+                : null;
+        if (!list)
+            continue;
+        const actions = list.map(normalizeAction).filter((a) => a !== null);
+        if (actions.length || list.length === 0)
+            return actions;
+    }
+    return null;
+}
+function tryJson(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        // A bare object followed by prose: cut at the matching close brace.
+        let depth = 0;
+        let inStr = false;
+        for (let i = 0; i < raw.length; i++) {
+            const c = raw[i];
+            if (inStr) {
+                if (c === "\\")
+                    i++;
+                else if (c === '"')
+                    inStr = false;
+                continue;
+            }
+            if (c === '"')
+                inStr = true;
+            else if (c === "{" || c === "[")
+                depth++;
+            else if (c === "}" || c === "]") {
+                depth--;
+                if (depth === 0) {
+                    try {
+                        return JSON.parse(raw.slice(0, i + 1));
+                    }
+                    catch {
+                        return null;
+                    }
+                }
+            }
+        }
+        return null;
+    }
+}
+function str(v) {
+    return typeof v === "string" ? v.trim() : "";
+}
+function normalizeAction(v) {
+    if (!v || typeof v !== "object")
+        return null;
+    const a = v;
+    const type = str(a.type ?? a.action).toLowerCase();
+    switch (type) {
+        case "spawn":
+        case "task":
+        case "assign": {
+            const prompt = str(a.prompt ?? a.instructions ?? a.task);
+            const title = str(a.title ?? a.name) || prompt.slice(0, 60);
+            const agent = str(a.agent ?? a.worker);
+            if (!prompt || !agent)
+                return null;
+            const deps = Array.isArray(a.dependsOn ?? a.depends_on ?? a.after)
+                ? (a.dependsOn ?? a.depends_on ?? a.after).map(str).filter(Boolean)
+                : [];
+            const id = str(a.id);
+            const touches = Array.isArray(a.touches ?? a.files)
+                ? (a.touches ?? a.files).map(str).filter(Boolean).slice(0, 50)
+                : [];
+            const overlapDecision = str(a.overlap);
+            return {
+                type: "spawn",
+                ...(id ? { id } : {}),
+                title,
+                agent,
+                prompt,
+                dependsOn: deps,
+                ...(touches.length ? { touches } : {}),
+                ...(overlapDecision ? { overlap: overlapDecision } : {}),
+            };
+        }
+        case "send":
+        case "followup":
+        case "follow_up": {
+            const task = str(a.task ?? a.id);
+            const message = str(a.message ?? a.prompt);
+            return task && message ? { type: "send", task, message } : null;
+        }
+        case "cancel":
+        case "kill": {
+            const task = str(a.task ?? a.id);
+            return task ? { type: "cancel", task } : null;
+        }
+        case "ask":
+        case "question": {
+            const question = str(a.question ?? a.message);
+            return question ? { type: "ask", question } : null;
+        }
+        case "done":
+        case "finish":
+        case "complete": {
+            return { type: "done", summary: str(a.summary ?? a.message) || "Done." };
+        }
+        default:
+            return null;
+    }
+}
+/** The orchestrator's standing instructions, sent with its first turn. */
+export function orchestratorBriefing(opts) {
+    const roster = opts.workers
+        .map((w) => `- "${w.id}" — ${KIND_BLURBS[w.kind] ?? w.kind}${w.role && w.role !== w.id ? ` (role: ${w.role})` : ""}`)
+        .join("\n");
+    return [
+        `[Loom Orchestra] You are the ORCHESTRATOR for project "${opts.project}".`,
+        "Your job is to coordinate, not to implement. Break the goal into concrete, independently",
+        "verifiable tasks and assign each to a worker agent. Workers run IN PARALLEL, each in its own",
+        `git worktree; finished work is merged into the integration branch "${opts.branch}", which is`,
+        "the directory you are running in — read it to review results.",
+        "",
+        "Rules:",
+        "- Never edit files yourself. Every implementation, fix, or test goes to a worker.",
+        "- Ground every task in the real repository: look at the code first; never guess file names.",
+        "- Write each task prompt so a worker with NO other context can finish it: the outcome, the",
+        "  files involved, constraints, and how to verify.",
+        "- Prefer tasks that touch different files so parallel work merges cleanly. When one task needs",
+        "  another's output, list it in dependsOn — it will start from a branch that already has it.",
+        `- At most ${opts.maxParallel} tasks run at once; queue more and they start as slots free up.`,
+        "- Match tasks to agents' strengths, and spread work across agents when it helps.",
+        '- Give each task "touches": the file globs it will change. Teammates\' agents see them to avoid collisions.',
+        "",
+        "Available workers:",
+        roster,
+        "",
+        "End EVERY reply with exactly one fenced block tagged loom containing your actions:",
+        "```loom",
+        '{"actions": [',
+        '  {"type": "spawn", "id": "t1", "title": "short label", "agent": "<worker id>", "prompt": "full task", "dependsOn": [], "touches": ["src/auth/**"]},',
+        '  {"type": "send", "task": "t1", "message": "follow-up for a finished/failed task (same worker, same worktree)"},',
+        '  {"type": "cancel", "task": "t2"},',
+        '  {"type": "ask", "question": "only when a human decision is truly required"},',
+        '  {"type": "done", "summary": "what was delivered and how it was verified"}',
+        "]}",
+        "```",
+        "After you reply, Loom runs the tasks and comes back to you with each result. Review them:",
+        "send follow-ups for anything incomplete or wrong, spawn new tasks if needed, and emit done",
+        "only when the goal is met. An empty actions list means: keep waiting for running tasks.",
+        "",
+        ...(opts.planDir
+            ? [
+                "",
+                `PLAN MODE is on. Every task prompt you write becomes a durable spec file at ${opts.planDir}/<id>.md,`,
+                `and the whole plan is written to ${opts.planDir}/PLAN.md, committed to the integration branch. Other`,
+                "agents and teammates will pick these up without you, so write each task prompt as a complete spec",
+                "with these headings: Goal, Context (the files and code involved, by path), Steps, Acceptance criteria,",
+                "Verification (exact commands). Plan the whole goal up front in your first reply.",
+            ]
+            : []),
+        "",
+        `The goal: ${opts.goal}`,
+    ].join("\n");
+}
+// ---------------------------------------------------------------------------
+// Plan files — the plan as markdown other agents can read
+// ---------------------------------------------------------------------------
+function yamlStr(v) {
+    return JSON.stringify(v);
+}
+/** plans/<run>/PLAN.md — the index: goal, task table, how to use it, results. */
+export function renderPlanIndex(run) {
+    const rows = run.tasks
+        .map((t) => `| [${t.id}](${t.id}.md) | ${t.title.replace(/\|/g, "\\|")} | ${t.agent} | ${t.dependsOn.join(", ") || "—"} | ${t.status} |`)
+        .join("\n");
+    return [
+        "---",
+        "loom-plan: 1",
+        `run: ${run.id}`,
+        `goal: ${yamlStr(run.goal)}`,
+        `orchestrator: ${run.orchestrator.agent}`,
+        `workers: [${run.workers.join(", ")}]`,
+        `status: ${run.status}`,
+        `branch: ${run.branch}`,
+        `created: ${new Date(run.createdAt).toISOString()}`,
+        "---",
+        "",
+        `# ${run.goal.split("\n")[0].slice(0, 100)}`,
+        "",
+        "## Goal",
+        "",
+        run.goal,
+        "",
+        "## Tasks",
+        "",
+        "| id | task | agent | depends on | status |",
+        "|---|---|---|---|---|",
+        rows || "| — | (no tasks yet) | | | |",
+        "",
+        "## How to use this plan",
+        "",
+        "Each task file in this folder is a self-contained spec: any coding agent (Claude Code, Codex,",
+        "Antigravity, Grok, OpenCode…) or a teammate can pick one up by reading it. Tasks whose",
+        "`depends_on` are all `done` are ready. Loom keeps the `status` fields current; don't edit them by hand",
+        "while a run is live.",
+        "",
+        ...(run.summary || run.error
+            ? ["## Result", "", run.summary ?? `Stopped: ${run.error}`, "", `Integration branch: \`${run.branch}\``, ""]
+            : []),
+    ].join("\n");
+}
+/** plans/<run>/<task>.md — one task, readable by any agent with no other context. */
+export function renderTaskFile(run, t) {
+    return [
+        "---",
+        `id: ${t.id}`,
+        `title: ${yamlStr(t.title)}`,
+        `agent: ${t.agent}`,
+        `depends_on: [${t.dependsOn.join(", ")}]`,
+        `status: ${t.status}`,
+        `plan: PLAN.md`,
+        "---",
+        "",
+        `# ${t.id} · ${t.title}`,
+        "",
+        `Part of: ${run.goal.split("\n")[0].slice(0, 120)} (see [PLAN.md](PLAN.md))`,
+        "",
+        ...(t.dependsOn.length
+            ? ["## Depends on", "", ...t.dependsOn.map((d) => `- [${d}](${d}.md)`), ""]
+            : []),
+        "## Spec",
+        "",
+        t.prompt.trim(),
+        "",
+        "## Result",
+        "",
+        t.result && t.status !== "pending" && t.status !== "running"
+            ? [t.result.trim(), "", t.files?.length ? `Files changed: ${t.files.map((f) => `\`${f}\``).join(", ")}` : ""].join("\n")
+            : "_Filled in by Loom when the task finishes._",
+        "",
+    ].join("\n");
+}
+const KIND_BLURBS = {
+    "claude-code": "Claude Code (Anthropic): strong at multi-file changes, refactors, careful reasoning",
+    codex: "Codex (OpenAI / ChatGPT): strong at implementation and running tests",
+    "antigravity-cli": "Antigravity (Google Gemini): fast implementation, broad knowledge",
+    "grok-code": "Grok Code (xAI): quick edits and scripts",
+    opencode: "OpenCode: open-model agent, good for well-specified tasks",
+    echo: "Echo (test double — repeats the prompt)",
+};
+/** What a worker is told, alongside its task. */
+export function workerBriefing(opts) {
+    return [
+        `[Loom Orchestra] You are a WORKER in project "${opts.project}", running task ${opts.task.id}: ` +
+            `"${opts.task.title}".`,
+        `The overall goal (for context only — do just YOUR task): ${opts.runGoal}`,
+        `You are in your own git worktree on branch "${opts.branch}". Other workers are editing other`,
+        "worktrees at the same time; Loom merges your work when you finish.",
+        "- Inspect the relevant code before editing. Keep changes scoped to the task.",
+        "- Verify what you touched (run the relevant tests/build when there are any).",
+        "- Do not commit, push, or open PRs — Loom commits and merges for you.",
+        "- Finish with a short report: what you changed, how you verified it, anything left undone.",
+        "- If you cannot proceed without a decision, end your reply with the question.",
+        ...(opts.planFile
+            ? [
+                `- Your task's spec is ${opts.planFile} (the whole plan is next to it in PLAN.md). Read it first.`,
+                "  Don't edit files under plans/ — Loom updates them.",
+            ]
+            : []),
+        opts.brain,
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
+// ---------------------------------------------------------------------------
+// git
+// ---------------------------------------------------------------------------
+function git(args, cwd) {
+    return new Promise((resolve, reject) => {
+        execFile("git", args, { cwd, maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
+            if (err)
+                reject(new Error((stderr || `${err.message} (exit ${err.code ?? "unknown"}, signal ${err.signal ?? "none"})`).trim(), { cause: err }));
+            else
+                resolve(stdout);
+        });
+    });
+}
+const gitOk = (args, cwd) => git(args, cwd).then(() => true, () => false);
+/**
+ * Stage everything a worker changed, minus Loom's own files.
+ *
+ * Adapters keep session state in `<worktree>/.loom/`, which must never ride a
+ * commit into the project. An exclude pathspec looked right and wasn't: when
+ * the project already gitignores `.loom/` (most do), naming the ignored path
+ * makes `git add` exit 1 ("paths are ignored"), which failed every real Codex
+ * task. So: add all, then unstage `.loom` — a no-op when it's ignored.
+ */
+async function commitAll(dir, message) {
+    await git(["add", "-A"], dir);
+    await git(["rm", "-r", "-q", "--cached", "--ignore-unmatch", "--", ".loom"], dir).catch(() => { });
+    const staged = (await git(["diff", "--cached", "--name-only"], dir)).trim();
+    if (!staged)
+        return false;
+    await git(["-c", "user.name=Loom Orchestra", "-c", "user.email=orchestra@loom.local", "commit", "-q", "--no-verify", "-m", message], dir);
+    return true;
+}
+/**
+ * A worker's commit, traceable to its goal, task and agent from `git log`
+ * alone (docs/teams-architecture.md §7). GitHub reads Co-Authored-By; the
+ * Loom-* trailers are for people and tools (`git log --grep 'Loom-Goal: o7x'`).
+ */
+export function taskCommitMessage(run, task, member) {
+    return [
+        `${task.title}`.slice(0, 72),
+        "",
+        `Task ${task.id} of orchestra ${run.id}: ${run.goal.split("\n")[0].slice(0, 120)}`,
+        "",
+        `Co-Authored-By: ${task.agent} <${task.agent}@loom.local>`,
+        ...(member ? [`Loom-Member: ${member}`] : []),
+        `Loom-Goal: ${run.id}`,
+        `Loom-Task: ${task.id}`,
+        `Loom-Agent: ${task.kind}`,
+    ].join("\n");
+}
+/** Where a run's plan lives inside the repo. */
+export function planDir(run) {
+    return `plans/${run.id}`;
+}
+function gh(args, cwd) {
+    return new Promise((resolve, reject) => {
+        execFile("gh", args, { cwd, maxBuffer: 4 * 1024 * 1024 }, (err, stdout, stderr) => {
+            if (err)
+                reject(new Error((stderr || err.message).trim()));
+            else
+                resolve(stdout);
+        });
+    });
+}
+/** Serialize git mutations: worktree add/merge on one repo race on its locks. */
+class Mutex {
+    tail = Promise.resolve();
+    run(fn) {
+        const next = this.tail.then(fn, fn);
+        this.tail = next.catch(() => { });
+        return next;
+    }
+}
+// ---------------------------------------------------------------------------
+// The engine
+// ---------------------------------------------------------------------------
+const DEFAULT_MAX_PARALLEL = 4;
+const DEFAULT_MAX_ROUNDS = 10;
+const HARD_MAX_PARALLEL = 12;
+const RESULT_CHARS = 4000;
+/** How often a task waiting on the team (a PR, a zone, capacity) is re-admitted. */
+const RECHECK_MS = 15_000;
+const PICK_ONE = "compare them and pick one to apply.";
+/** A race's summary once you've picked: which take went in, not the instruction to pick. */
+function raceApplied(run) {
+    const done = run.tasks.filter((t) => t.status === "done").length;
+    const pick = run.tasks.find((t) => t.id === run.applied?.task);
+    return `${done} of ${run.tasks.length} finished — ${pick ? `${pick.agent}'s take` : "one take"} was applied.`;
+}
+export class OrchestraEngine {
+    host;
+    runs = new Map();
+    live = new Map(); // `${runId}/${taskId|orch}` → adapter
+    /** A worker's or orchestrator's live instance by its id, for answering its questions. */
+    liveAgent(instanceId) {
+        return [...this.live.values()].find((a) => a.id === instanceId);
+    }
+    gitLock = new Mutex();
+    turnText = new Map();
+    orchestratorBusy = new Set();
+    constructor(host) {
+        this.host = host;
+        for (const run of this.loadRuns())
+            this.runs.set(run.id, run);
+        // A daemon restart kills every CLI a run was driving. Say so honestly
+        // instead of showing tasks "running" that nothing runs.
+        for (const run of this.runs.values()) {
+            if (!isTerminal(run.status) && run.status !== "waiting_human") {
+                run.status = "failed";
+                run.error = "the daemon restarted while this run was active";
+                for (const t of run.tasks) {
+                    if (t.status === "running" || t.status === "pending") {
+                        t.status = "cancelled";
+                        t.error = "daemon restarted";
+                    }
+                }
+                this.save(run);
+            }
+        }
+    }
+    // ── persistence ──
+    runsDir() {
+        return path.join(this.host.projectDir, ".loom", "orchestra");
+    }
+    loadRuns() {
+        const dir = this.runsDir();
+        if (!fs.existsSync(dir))
+            return [];
+        const out = [];
+        for (const f of fs.readdirSync(dir)) {
+            if (!f.endsWith(".json"))
+                continue;
+            try {
+                const run = JSON.parse(fs.readFileSync(path.join(dir, f), "utf8"));
+                // a race applied before its summary was rewritten on apply still says "pick one"
+                if (run.race && run.applied?.task && run.summary?.endsWith(PICK_ONE))
+                    run.summary = raceApplied(run);
+                out.push(run);
+            }
+            catch {
+                /* a torn file is one lost run, not a dead project */
+            }
+        }
+        return out.sort((a, b) => a.createdAt - b.createdAt);
+    }
+    save(run) {
+        run.updatedAt = Date.now();
+        fs.mkdirSync(this.runsDir(), { recursive: true });
+        const file = path.join(this.runsDir(), `${run.id}.json`);
+        fs.writeFileSync(file + ".tmp", JSON.stringify(run, null, 2));
+        fs.renameSync(file + ".tmp", file);
+    }
+    list() {
+        return [...this.runs.values()].sort((a, b) => b.createdAt - a.createdAt);
+    }
+    get(id) {
+        return this.runs.get(id);
+    }
+    active() {
+        return this.list().find((r) => !isTerminal(r.status));
+    }
+    /** Every goal in flight, with the paths it expects to touch. */
+    runningScopes() {
+        return this.list()
+            .filter((r) => !isTerminal(r.status))
+            .map((r) => ({
+            runId: r.id,
+            goal: r.goal,
+            // A goal's scope is what it said it would touch, once it has planned.
+            // Before that it's unknown, which counts as everything.
+            paths: r.tasks.flatMap((t) => t.touches ?? []),
+        }));
+    }
+    emit(run, phase, extra = {}, chat) {
+        this.host.append({
+            kind: "orchestra",
+            chat: chat ?? run.chat,
+            payload: { phase, runId: run.id, status: run.status, ...extra },
+        });
+    }
+    // ── agents ──
+    /** Resolve a name the orchestrator (or user) gave into a runnable config. */
+    resolveAgent(name) {
+        const roster = this.host.roster();
+        const n = name.trim().toLowerCase();
+        const byId = roster.find((a) => a.id.toLowerCase() === n);
+        if (byId)
+            return byId;
+        const alias = {
+            claude: "claude-code",
+            "claude code": "claude-code",
+            chatgpt: "codex",
+            gpt: "codex",
+            openai: "codex",
+            antigravity: "antigravity-cli",
+            agy: "antigravity-cli",
+            gemini: "antigravity-cli",
+            grok: "grok-code",
+        };
+        const kind = alias[n] ?? n;
+        const byKind = roster.find((a) => a.kind === kind);
+        if (byKind)
+            return byKind;
+        if (this.host.installedKinds().includes(kind))
+            return { id: kind, kind, role: kind };
+        return null;
+    }
+    // ── lifecycle ──
+    async start(opts) {
+        const goal = opts.goal?.trim();
+        if (!goal)
+            throw new Error("an orchestra run needs a goal");
+        // One goal at a time unless the project says otherwise — and then only
+        // when the paths can't collide (core/goal-lanes.ts, D-lanes locally).
+        const running = this.runningScopes();
+        const allowed = Math.max(1, this.host.maxConcurrentGoals?.() ?? 1);
+        if (running.length) {
+            const blocked = blockedBy({ runId: "new", goal, paths: opts.touches ?? [] }, running, allowed);
+            if (blocked) {
+                const busy = this.active();
+                throw new Error(allowed === 1
+                    ? `orchestra run ${busy.id} is still ${busy.status} — abort it or wait`
+                    : blocked);
+            }
+        }
+        const roster = this.host.roster();
+        const orchCfg = opts.orchestrator
+            ? this.resolveAgent(opts.orchestrator)
+            : (roster.find((a) => a.kind === "claude-code") ?? roster[0] ?? null);
+        if (!orchCfg)
+            throw new Error(`no agent "${opts.orchestrator ?? ""}" can orchestrate here — add one first`);
+        const workerNames = opts.workers?.length ? opts.workers : roster.map((a) => a.id);
+        const workers = [];
+        for (const w of workerNames) {
+            const cfg = this.resolveAgent(w);
+            if (!cfg)
+                throw new Error(`unknown worker agent "${w}"`);
+            if (!workers.some((x) => x.id === cfg.id))
+                workers.push(cfg);
+        }
+        if (!workers.length)
+            throw new Error("an orchestra needs at least one worker agent");
+        if (opts.race && workers.length < 2)
+            throw new Error("a race needs at least two agents");
+        this.host.gate(orchCfg.id);
+        const blocked = this.host.coordinator?.()?.canStart?.();
+        if (blocked)
+            throw new Error(blocked);
+        const dir = this.host.projectDir;
+        if (!(await gitOk(["rev-parse", "--is-inside-work-tree"], dir))) {
+            throw new Error("orchestra runs need a git repository — initialise one (git init) first");
+        }
+        // Worktrees branch from a commit. A repo with none gets an empty root
+        // commit rather than a cryptic "invalid reference: HEAD".
+        if (!(await gitOk(["rev-parse", "--verify", "HEAD"], dir))) {
+            await git(["-c", "user.name=Loom", "-c", "user.email=loom@loom.local", "commit", "-q", "--allow-empty", "-m", "Initial commit"], dir);
+        }
+        let baseCommit = (await git(["rev-parse", "HEAD"], dir)).trim();
+        let baseBranch = (await git(["rev-parse", "--abbrev-ref", "HEAD"], dir).catch(() => "")).trim() || null;
+        if (opts.from) {
+            // Adopting a teammate's goal: work starts from their pushed branch (D63).
+            await git(["fetch", "-q", "origin", `+refs/heads/${opts.from.branch}:refs/remotes/origin/${opts.from.branch}`], dir);
+            baseCommit = (await git(["rev-parse", `origin/${opts.from.branch}`], dir)).trim();
+            baseBranch = null;
+        }
+        // Loom's own state (.loom/: the log, the brain, run files) changes on every
+        // turn and is never the user's work; counting it warned "uncommitted
+        // changes" on every run in a project that doesn't gitignore it.
+        const dirty = (await git(["status", "--porcelain", "--", ".", ":(exclude).loom"], dir)).trim().length > 0;
+        const id = `o${Date.now().toString(36)}`;
+        // Integration and task branches are siblings under one prefix: git can't
+        // hold both `a/b` and `a/b/c` as refs.
+        const branch = `loom/orchestra/${id}/main`;
+        const wtRoot = path.join(loomHome(), "orchestra", this.host.projectId, id);
+        const integration = path.join(wtRoot, "integration");
+        fs.mkdirSync(wtRoot, { recursive: true });
+        await this.gitLock.run(() => createWorktree(dir, integration, branch, baseCommit));
+        // Orchestrating from a thread used to abandon it: the run opened a thread
+        // of its own and the UI walked you into it, so the goal you typed in Main
+        // and every word of its answer lived somewhere else (#100). When the
+        // caller names the thread it was asked in, the orchestrator answers there.
+        const inPlace = opts.chat && (this.host.chatExists?.(opts.chat) ?? false) ? opts.chat : null;
+        const chat = inPlace ? { id: inPlace } : this.host.createChat(`🎼 ${goal.slice(0, 50)}`);
+        const run = {
+            id,
+            goal,
+            orchestrator: { agent: orchCfg.id, kind: orchCfg.kind },
+            workers: workers.map((w) => w.id),
+            status: "planning",
+            chat: chat.id,
+            ...(inPlace ? { inPlace: true } : {}),
+            baseBranch,
+            baseCommit,
+            branch,
+            dir: integration,
+            tasks: [],
+            round: 0,
+            maxRounds: clamp(opts.maxRounds ?? DEFAULT_MAX_ROUNDS, 1, 50),
+            maxParallel: Math.min(clamp(opts.maxParallel ?? DEFAULT_MAX_PARALLEL, 1, HARD_MAX_PARALLEL), this.host.coordinator?.()?.maxParallel?.() ?? HARD_MAX_PARALLEL),
+            ...(opts.plan ? { plan: true } : {}),
+            ...(opts.from ? { from: opts.from, landing: newLanding(opts.from.pr, opts.from.url) } : {}),
+            // A cap for this goal: what was asked for, else the project's default.
+            ...(opts.maxUsd && opts.maxUsd > 0 ? { budgetUsd: opts.maxUsd } : {}),
+            ...(opts.race ? { race: true } : {}),
+            costUsd: 0,
+            createdAt: Date.now(),
+            updatedAt: Date.now(),
+        };
+        this.workerCfgs.set(run.id, workers);
+        this.runs.set(id, run);
+        this.save(run);
+        // A new thread starts empty, so the goal is replayed into it. The thread
+        // you typed it in already has it — replaying would say it twice.
+        if (!inPlace)
+            this.host.append({ kind: "message", chat: run.chat, payload: { text: goal, author: "user" } });
+        this.emit(run, "started", {
+            goal,
+            orchestrator: run.orchestrator,
+            workers: run.workers,
+            branch,
+            maxParallel: run.maxParallel,
+            ...(run.race ? { race: true } : {}),
+            ...(dirty ? { note: "uncommitted changes in the project are not visible to workers — they start from the last commit" } : {}),
+        });
+        if (run.race) {
+            // No plan and no orchestrator: every entrant gets the goal as it was
+            // typed, in its own worktree off the same commit, all at once.
+            run.maxParallel = Math.max(run.maxParallel, workers.length);
+            for (const w of workers) {
+                const id = `race-${w.id}`.replace(/[^\w-]+/g, "-").slice(0, 40);
+                const chatInfo = this.host.createChat(`🏁 ${w.id} · ${goal}`.slice(0, 60), { agentId: w.id });
+                const task = {
+                    id,
+                    title: `${w.id}'s take`,
+                    prompt: goal,
+                    agent: w.id,
+                    kind: w.kind,
+                    dependsOn: [],
+                    status: "pending",
+                    chat: chatInfo.id,
+                    attempts: 0,
+                    queued: [],
+                };
+                run.tasks.push(task);
+                this.emit(run, "task", { task: taskSummary(task) });
+            }
+            run.status = "running";
+            this.save(run);
+            this.schedule(run);
+            return run;
+        }
+        const briefing = orchestratorBriefing({
+            project: this.host.projectName,
+            goal,
+            workers: workers.map((w) => ({ id: w.id, kind: w.kind, role: w.role })),
+            maxParallel: run.maxParallel,
+            branch,
+            ...(run.plan ? { planDir: planDir(run) } : {}),
+        });
+        void this.orchestratorTurn(run, "Plan the goal into tasks and spawn them now.", briefing);
+        return run;
+    }
+    workerCfgs = new Map();
+    workersFor(run) {
+        const cached = this.workerCfgs.get(run.id);
+        if (cached)
+            return cached;
+        const cfgs = run.workers.map((w) => this.resolveAgent(w)).filter((c) => !!c);
+        this.workerCfgs.set(run.id, cfgs);
+        return cfgs;
+    }
+    async abort(runId, reason = "aborted by the user") {
+        const run = this.mustGet(runId);
+        if (isTerminal(run.status))
+            return run;
+        run.status = "aborted";
+        run.error = reason;
+        for (const t of run.tasks) {
+            if (t.status === "running" || t.status === "pending") {
+                t.status = "cancelled";
+                t.error = reason;
+            }
+        }
+        this.save(run);
+        await this.stopAll(run);
+        this.forgetRun(run.id);
+        this.emit(run, "aborted", { reason });
+        this.host.coordinator?.()?.onRunEnd?.(run);
+        return run;
+    }
+    /** The human answers an orchestrator's question (or adds direction mid-run). */
+    async reply(runId, text) {
+        const run = this.mustGet(runId);
+        const msg = text.trim();
+        if (!msg)
+            throw new Error("empty reply");
+        if (isTerminal(run.status) && run.status !== "completed") {
+            throw new Error(`run ${run.id} is ${run.status}`);
+        }
+        this.host.append({ kind: "message", chat: run.chat, payload: { text: msg, author: "user" } });
+        run.question = undefined;
+        // Over its budget (D64): a human saying continue raises the cap by one more budget.
+        const cap = this.goalCap(run);
+        if (cap !== null && run.costUsd >= cap)
+            run.budgetUsd = run.costUsd + (this.host.coordinator?.()?.goalBudgetUsd?.() ?? cap);
+        if (run.status === "completed") {
+            // Reopen: more work on the same integration branch.
+            run.status = "reviewing";
+            run.summary = undefined;
+        }
+        else if (run.status === "waiting_human") {
+            // Answered: the orchestrator is working on it now. Leaving the status at
+            // waiting_human showed "waiting on you" for the whole turn, and any
+            // client polling for the next wait returned at once (found by e2e F5).
+            run.status = "reviewing";
+            this.emit(run, "reviewing", { round: run.round + 1 });
+        }
+        this.save(run);
+        if (this.orchestratorBusy.has(run.id)) {
+            this.pendingHuman.set(run.id, [...(this.pendingHuman.get(run.id) ?? []), msg]);
+            return run;
+        }
+        void this.orchestratorTurn(run, `The human says: ${msg}\n\n${this.statusReport(run)}`);
+        return run;
+    }
+    pendingHuman = new Map();
+    /**
+     * Put a completed goal back to work (Phase 4): a failed check, a high review
+     * finding, a conflict with fresh main. Same integration branch, same task
+     * worktrees; the orchestrator gets the problem and a fresh round budget.
+     * Whatever landed on the pushed branch meanwhile (an adopter's fix) comes in first.
+     */
+    async reopen(runId, text, why) {
+        const run = this.mustGet(runId);
+        if (run.status !== "completed")
+            throw new Error(`run ${run.id} is ${run.status} — only a completed goal can be reopened`);
+        run.status = "reviewing";
+        run.summary = undefined;
+        run.maxRounds = run.round + 10;
+        this.save(run);
+        this.emit(run, "reopened", { why });
+        await this.pullPushed(run).catch(() => { });
+        this.host.append({ kind: "message", chat: run.chat, payload: { text, author: "loom", orchestra: { runId: run.id, reopened: why } } });
+        void this.orchestratorTurn(run, `${text}\n\n${this.statusReport(run)}`, this.briefingOf(run));
+        return run;
+    }
+    /**
+     * Hand a goal to another machine (Phase 5, D75): stop starting anything,
+     * let running turns finish (interrupting them after `graceMs`), commit every
+     * worktree, and push the integration and task branches to hidden refs. The
+     * returned record is what the other side needs to rebuild the run; this
+     * copy becomes "moved" and read-only.
+     */
+    async moveOut(runId, where, opts = {}) {
+        const run = this.mustGet(runId);
+        if (run.status === "moved")
+            throw new Error(`run ${run.id} has already moved to ${run.movedTo?.where ?? "another machine"}`);
+        if (run.status === "failed" || run.status === "aborted")
+            throw new Error(`run ${run.id} is ${run.status} — nothing to move`);
+        run.moving = true;
+        this.save(run);
+        this.emit(run, "moving", { to: where });
+        const grace = opts.graceMs ?? 120_000;
+        const busy = () => this.orchestratorBusy.has(run.id) || run.tasks.some((t) => t.status === "running");
+        const deadline = Date.now() + grace;
+        while (busy() && Date.now() < deadline)
+            await new Promise((r) => setTimeout(r, 200));
+        // Out of patience: stop what's still going; each such task resumes where it left off.
+        for (const t of run.tasks) {
+            if (t.status !== "running")
+                continue;
+            t.status = "pending";
+            t.queued.unshift("You were moved to another machine mid-task. Your work so far is committed in this worktree — continue your task where you left off.");
+        }
+        await this.stopAll(run);
+        this.orchestratorBusy.delete(run.id);
+        const refs = [];
+        await this.gitLock.run(async () => {
+            await commitAll(run.dir, `orchestra ${run.id}: moved to ${where}`).catch(() => false);
+            await git(["push", "-q", "-f", "origin", `${run.branch}:${runRef(run.id, "main")}`], run.dir);
+            refs.push(runRef(run.id, "main"));
+            for (const t of run.tasks) {
+                if (!t.dir || !t.branch || !fs.existsSync(t.dir))
+                    continue;
+                await commitAll(t.dir, `orchestra ${run.id}/${t.id}: work in progress, moved to ${where}`).catch(() => false);
+                await git(["push", "-q", "-f", "origin", `${t.branch}:${runRef(run.id, t.id)}`], t.dir);
+                refs.push(runRef(run.id, t.id));
+            }
+        });
+        const record = JSON.parse(JSON.stringify({ ...run, moving: undefined, movedTo: undefined }));
+        run.moving = undefined;
+        run.status = "moved";
+        run.movedTo = { where, at: Date.now() };
+        this.save(run);
+        this.emit(run, "moved", { to: where, refs });
+        return { record, refs };
+    }
+    /**
+     * Rebuild a moved goal here (a runner taking it, or bringing it back):
+     * fetch its hidden refs, recreate the integration and task worktrees, and
+     * give the orchestrator a review turn to carry on (D75, D76).
+     */
+    async importRun(record, opts = {}) {
+        const dir = this.host.projectDir;
+        const id = record.id;
+        const existing = this.runs.get(id);
+        if (existing && !isTerminal(existing.status))
+            throw new Error(`run ${id} is active here already`);
+        await git(["fetch", "-q", "origin", `+refs/loom/run/${id}/*:refs/remotes/loom-run/${id}/*`], dir);
+        const wtRoot = path.join(loomHome(), "orchestra", this.host.projectId, id);
+        // a copy left here by an earlier move goes first
+        if (existing) {
+            const old = [existing.dir, ...existing.tasks.map((t) => t.dir).filter((d) => !!d)];
+            await this.gitLock.run(async () => {
+                for (const d of old)
+                    await git(["worktree", "remove", "--force", d], dir).catch(() => { });
+                await git(["worktree", "prune"], dir).catch(() => { });
+            });
+        }
+        fs.mkdirSync(wtRoot, { recursive: true });
+        const integration = path.join(wtRoot, "integration");
+        // The other machine's agents may not exist here: same name, else same kind,
+        // else this machine's own orchestrator / first worker — and say so.
+        const roster = this.host.roster();
+        const swaps = [];
+        const local = (agent, kind, fallback) => {
+            const cfg = this.resolveAgent(agent) ?? this.resolveAgent(kind) ?? fallback ?? null;
+            if (cfg && cfg.kind !== kind)
+                swaps.push(`${agent} (${kind}) → ${cfg.id} (${cfg.kind})`);
+            return cfg;
+        };
+        const orchCfg = local(record.orchestrator.agent, record.orchestrator.kind, roster.find((a) => a.role === "orchestrator") ?? roster[0]);
+        if (!orchCfg)
+            throw new Error("no agent here can orchestrate this goal");
+        const workerCfgs = record.workers.map((w) => this.resolveAgent(w)).filter((c) => !!c);
+        const firstWorker = workerCfgs[0] ?? roster.find((a) => a.role !== "orchestrator") ?? roster[0];
+        const tasks = [];
+        await this.gitLock.run(async () => {
+            await git(["worktree", "add", "-q", "-B", record.branch, integration, `refs/remotes/loom-run/${id}/main`], dir);
+            for (const t of record.tasks) {
+                const copy = { ...t, queued: [...t.queued] };
+                const wcfg = local(t.agent, t.kind, firstWorker);
+                if (wcfg) {
+                    copy.agent = wcfg.id;
+                    copy.kind = wcfg.kind;
+                    if (!workerCfgs.some((w) => w.id === wcfg.id))
+                        workerCfgs.push(wcfg);
+                }
+                const ref = `refs/remotes/loom-run/${id}/${t.id}`;
+                if (t.branch && (await gitOk(["rev-parse", "--verify", ref], dir))) {
+                    const tdir = path.join(wtRoot, t.id);
+                    await git(["worktree", "add", "-q", "-B", t.branch, tdir, ref], dir);
+                    copy.dir = tdir;
+                }
+                else {
+                    delete copy.dir;
+                    delete copy.branch;
+                }
+                if (copy.status === "running")
+                    copy.status = "pending";
+                copy.chat = this.host.createChat(`${t.id} · ${t.title}`.slice(0, 60)).id;
+                copy.reported = false;
+                tasks.push(copy);
+            }
+        });
+        if (!workerCfgs.length && firstWorker)
+            workerCfgs.push(firstWorker);
+        const run = {
+            ...record,
+            orchestrator: { agent: orchCfg.id, kind: orchCfg.kind },
+            workers: workerCfgs.map((w) => w.id),
+            ...(swaps.length ? { notes: [...(record.notes ?? []), `Agents changed on the move: ${[...new Set(swaps)].join("; ")}`] } : {}),
+            dir: integration,
+            tasks,
+            chat: this.host.createChat(`🎼 ${record.goal.slice(0, 50)}`).id,
+            status: isTerminal(record.status) || record.status === "waiting_human" ? record.status : "reviewing",
+            maxRounds: record.round + 20,
+            moving: undefined,
+            movedTo: undefined,
+            updatedAt: Date.now(),
+        };
+        this.runs.set(id, run);
+        this.workerCfgs.delete(id);
+        this.save(run);
+        this.host.append({ kind: "message", chat: run.chat, payload: { text: run.goal, author: "user" } });
+        this.emit(run, "imported", { from: opts.from ?? "another machine", tasks: run.tasks.length });
+        if (opts.resume !== false && run.status === "reviewing") {
+            void this.orchestratorTurn(run, `This goal was moved here from ${opts.from ?? "another machine"}. Every task's work so far is on its branch; interrupted tasks resume where they left off.\n\n${this.statusReport(run)}`, this.briefingOf(run));
+        }
+        return run;
+    }
+    /** The orchestrator's standing instructions, for a fresh orchestrator session. */
+    briefingOf(run) {
+        return orchestratorBriefing({
+            project: this.host.projectName,
+            goal: run.goal,
+            workers: this.workersFor(run).map((w) => ({ id: w.id, kind: w.kind, role: w.role })),
+            maxParallel: run.maxParallel,
+            branch: run.branch,
+            ...(run.plan ? { planDir: planDir(run) } : {}),
+        });
+    }
+    /** The branch this goal's PR is on. */
+    prBranch(run) {
+        return run.from?.branch ?? run.branch;
+    }
+    /** Bring commits pushed to the goal's PR branch by someone else into the integration branch. */
+    async pullPushed(run) {
+        if (!run.delivered?.prUrl && !run.from)
+            return;
+        const b = this.prBranch(run);
+        await this.gitLock.run(async () => {
+            await git(["fetch", "-q", "origin", `+refs/heads/${b}:refs/remotes/origin/${b}`], run.dir);
+            await commitAll(run.dir, `orchestra ${run.id}: orchestrator edits`).catch(() => false);
+            try {
+                await git(["-c", "user.name=Loom Orchestra", "-c", "user.email=orchestra@loom.local", "merge", "--no-edit", "-q", `origin/${b}`], run.dir);
+            }
+            catch (err) {
+                await git(["merge", "--abort"], run.dir).catch(() => { });
+                throw err;
+            }
+        });
+    }
+    /** Record where a goal's PR stands (the landing manager owns the transitions). */
+    setLanding(runId, patch) {
+        const run = this.runs.get(runId);
+        if (!run?.landing && !(patch.pr && patch.url))
+            return undefined;
+        if (!run)
+            return undefined;
+        run.landing = { ...(run.landing ?? newLanding(patch.pr, patch.url)), ...patch, updatedAt: Date.now() };
+        this.save(run);
+        this.emit(run, "landing", { landing: run.landing });
+        return run.landing;
+    }
+    goalCap(run) {
+        return run.budgetUsd ?? this.host.goalBudgetUsd?.() ?? this.host.coordinator?.()?.goalBudgetUsd?.() ?? null;
+    }
+    /**
+     * A word before the stop.
+     *
+     * Hearing about a budget for the first time when the goal halts is a bad way
+     * to learn it exists — especially now that a queue can start goals while
+     * you're elsewhere. Said once per goal.
+     */
+    warnNearBudget(run) {
+        const cap = this.goalCap(run);
+        if (cap === null || run.budgetWarned || run.costUsd < cap * BUDGET_WARN_AT)
+            return;
+        run.budgetWarned = true;
+        this.save(run);
+        this.emit(run, "alert", {
+            text: `this goal has spent $${run.costUsd.toFixed(2)} of its $${cap.toFixed(2)} budget`,
+            budget: { spent: run.costUsd, cap },
+        });
+    }
+    /** D64: a goal over its cap stops asking for more work until a human says continue. */
+    overBudget(run) {
+        const cap = this.goalCap(run);
+        this.warnNearBudget(run);
+        if (cap === null || run.costUsd < cap)
+            return false;
+        run.status = "waiting_human";
+        run.question =
+            `This goal has spent $${run.costUsd.toFixed(2)} of its $${cap.toFixed(2)} budget. ` +
+                "Running work finishes its turn; nothing new starts. Reply to continue — that allows one more budget's worth.";
+        this.save(run);
+        this.emit(run, "waiting", { question: run.question, budget: { spent: run.costUsd, cap } });
+        return true;
+    }
+    /**
+     * Merge the integration branch into the project's working tree.
+     *
+     * Explicit, never automatic: the run's work lands on its own branch, and the
+     * human decides when it reaches theirs.
+     */
+    async apply(runId, taskId) {
+        const run = this.mustGet(runId);
+        if (run.status !== "completed" && run.status !== "waiting_human" && run.status !== "failed" && run.status !== "aborted") {
+            throw new Error(`run ${run.id} is still ${run.status} — wait for it to finish`);
+        }
+        const dir = this.host.projectDir;
+        const into = (await git(["rev-parse", "--abbrev-ref", "HEAD"], dir)).trim();
+        if (run.race) {
+            // A race applies the one entrant you picked, never all of them.
+            const pick = run.tasks.find((t) => t.id === taskId);
+            if (!pick)
+                throw new Error(`pick an entrant to apply: ${run.tasks.map((t) => t.id).join(", ")}`);
+            if (pick.status !== "done" || !pick.branch)
+                throw new Error(`${pick.id} didn't finish, so there's nothing of it to apply`);
+            if (run.applied)
+                throw new Error(`${run.applied.task ?? "an entrant"} was already applied from this race`);
+            await this.gitLock.run(async () => {
+                try {
+                    await git(["-c", "user.name=Loom Orchestra", "-c", "user.email=orchestra@loom.local", "merge", "--no-ff", "--no-edit", "-m", `Race ${run.id}: ${pick.agent}'s take on ${run.goal.slice(0, 50)}`, pick.branch], dir);
+                }
+                catch (err) {
+                    await git(["merge", "--abort"], dir).catch(() => { });
+                    throw new Error(`merge into ${into} failed — ${err.message}`);
+                }
+            });
+            run.applied = { at: Date.now(), into, task: pick.id };
+            run.summary = raceApplied(run);
+            this.save(run);
+            this.emit(run, "applied", { into, task: pick.id, agent: pick.agent });
+            return { merged: pick.branch, into };
+        }
+        await this.gitLock.run(async () => {
+            await commitAll(run.dir, `orchestra ${run.id}: final edits`).catch(() => false);
+            try {
+                await git(["-c", "user.name=Loom Orchestra", "-c", "user.email=orchestra@loom.local", "merge", "--no-ff", "--no-edit", "-m", `Merge orchestra run ${run.id}: ${run.goal.slice(0, 60)}`, run.branch], dir);
+            }
+            catch (err) {
+                await git(["merge", "--abort"], dir).catch(() => { });
+                throw new Error(`merge into ${into} failed — ${err.message}`);
+            }
+        });
+        run.applied = { at: Date.now(), into };
+        this.save(run);
+        this.emit(run, "applied", { into });
+        return { merged: run.branch, into };
+    }
+    /** What one task changed on its branch since the run began — a race entrant's diff. */
+    async taskDiff(runId, taskId) {
+        const run = this.mustGet(runId);
+        const task = run.tasks.find((t) => t.id === taskId);
+        if (!task)
+            throw new Error(`no task "${taskId}" in run ${run.id}`);
+        if (!task.branch)
+            return "";
+        const patch = await git(["diff", `${run.baseCommit}...${task.branch}`], this.host.projectDir).catch(() => "");
+        return patch.length > 400_000 ? `${patch.slice(0, 400_000)}\n… (truncated)` : patch;
+    }
+    /** Remove a finished run's worktrees (the branch stays for the record). */
+    async cleanup(runId) {
+        const run = this.mustGet(runId);
+        if (!isTerminal(run.status) && run.status !== "waiting_human")
+            throw new Error("run is still active");
+        await this.stopAll(run);
+        const dirs = [run.dir, ...run.tasks.map((t) => t.dir).filter((d) => !!d)];
+        await this.gitLock.run(async () => {
+            for (const d of dirs)
+                await git(["worktree", "remove", "--force", d], this.host.projectDir).catch(() => { });
+            await git(["worktree", "prune"], this.host.projectDir).catch(() => { });
+        });
+        this.emit(run, "cleaned");
+    }
+    async shutdown() {
+        for (const run of this.runs.values()) {
+            if (isTerminal(run.status))
+                continue;
+            run.interrupted = {
+                at: Date.now(),
+                tasks: run.tasks.filter((t) => t.status === "running" || t.status === "pending").map((t) => t.id),
+                phase: run.status,
+            };
+            await this.abort(run.id, "Loom stopped while this run was going (a restart or shutdown) — what finished is on its branch, and Resume carries on from there");
+        }
+    }
+    /**
+     * Carry on a run Loom stopped by restarting. The tasks that were in flight
+     * go back to pending in the worktrees they left (their work so far is
+     * there); the orchestrator — a fresh session, so it's briefed again —
+     * picks up at review when nothing was in flight.
+     */
+    async resume(runId) {
+        const run = this.mustGet(runId);
+        if (run.status !== "aborted" || !run.interrupted) {
+            throw new Error(`run ${run.id} wasn't stopped by a restart — start the goal again instead`);
+        }
+        if (!run.dir || !fs.existsSync(run.dir))
+            throw new Error("its worktrees were cleaned up — start the goal again");
+        const again = new Set(run.interrupted.tasks);
+        let pending = 0;
+        for (const t of run.tasks) {
+            if (!again.has(t.id) || t.status !== "cancelled")
+                continue;
+            t.status = "pending";
+            delete t.error;
+            t.reported = false;
+            pending++;
+        }
+        delete run.interrupted;
+        delete run.error;
+        run.maxRounds = Math.max(run.maxRounds, run.round + 10);
+        run.updatedAt = Date.now();
+        this.rebrief.add(run.id);
+        this.emit(run, "resumed", { tasks: pending });
+        if (pending) {
+            run.status = "running";
+            this.save(run);
+            this.schedule(run);
+        }
+        else {
+            run.status = "reviewing";
+            this.save(run);
+            void this.orchestratorTurn(run, `Loom restarted while this run was going, and it's carrying on now.\n\n${this.statusReport(run)}`);
+        }
+        return run;
+    }
+    /** Runs whose orchestrator restarts as a fresh session (resume) and needs its brief again. */
+    rebrief = new Set();
+    mustGet(id) {
+        const run = this.runs.get(id);
+        if (!run)
+            throw new Error(`no orchestra run "${id}"`);
+        return run;
+    }
+    async stopAll(run) {
+        for (const [key, agent] of [...this.live.entries()]) {
+            if (!key.startsWith(`${run.id}/`))
+                continue;
+            this.live.delete(key);
+            if (agent.busy())
+                await agent.interrupt().catch(() => { });
+            await agent.stop().catch(() => { });
+        }
+    }
+    // ── the orchestrator ──
+    orchestratorAgent(run) {
+        const key = `${run.id}/orch`;
+        let agent = this.live.get(key);
+        if (agent)
+            return agent;
+        const cfg = this.resolveAgent(run.orchestrator.agent) ?? {
+            id: run.orchestrator.agent,
+            kind: run.orchestrator.kind,
+            role: "orchestrator",
+        };
+        agent = this.host.makeAgent({ ...cfg, role: "orchestrator", options: orchestratorOptions(cfg) }, run.dir);
+        this.live.set(key, agent);
+        this.wire(run, agent, cfg.id, run.chat, key);
+        return agent;
+    }
+    async orchestratorTurn(run, text, briefing, retry = 0) {
+        if (isTerminal(run.status) || run.moving)
+            return;
+        // a resumed run's orchestrator is a fresh session: its first turn carries the instructions again
+        if (!briefing && this.rebrief.delete(run.id))
+            briefing = this.briefingOf(run);
+        if (this.overBudget(run))
+            return;
+        if (run.round >= run.maxRounds) {
+            return this.finish(run, "failed", `stopped after ${run.maxRounds} orchestrator rounds without "done"`);
+        }
+        run.round++;
+        this.orchestratorBusy.add(run.id);
+        this.save(run);
+        const key = `${run.id}/orch`;
+        this.turnText.set(key, "");
+        let reply = "";
+        try {
+            this.host.gate(run.orchestrator.agent);
+            const agent = this.orchestratorAgent(run);
+            await agent.start();
+            this.host.append({
+                kind: "message",
+                chat: run.chat,
+                payload: { text, author: "loom", orchestra: { runId: run.id, to: "orchestrator" } },
+            });
+            await agent.send({ text, ...(briefing ? { briefing } : {}) });
+            reply = this.turnText.get(key) ?? "";
+            this.turnText.delete(key); // read once per turn; reset before the next
+        }
+        catch (err) {
+            this.orchestratorBusy.delete(run.id);
+            return this.finish(run, "failed", `orchestrator failed: ${err.message}`);
+        }
+        this.orchestratorBusy.delete(run.id);
+        if (isTerminal(run.status))
+            return;
+        const actions = parseOrchestraActions(reply);
+        if (actions === null) {
+            if (retry < 1) {
+                return this.orchestratorTurn(run, "Your reply had no ```loom actions block, so nothing ran. Reply again ending with exactly one " +
+                    '```loom {"actions": [...]} ``` block (see your instructions).', undefined, retry + 1);
+            }
+            run.status = "waiting_human";
+            run.question = "The orchestrator's reply had no actions Loom could read. Reply with direction to continue.";
+            this.save(run);
+            this.emit(run, "waiting", { question: run.question });
+            return;
+        }
+        const human = this.pendingHuman.get(run.id);
+        if (human?.length) {
+            this.pendingHuman.delete(run.id);
+            this.applyActions(run, actions);
+            return this.orchestratorTurn(run, `The human says: ${human.join("\n")}\n\n${this.statusReport(run)}`);
+        }
+        this.applyActions(run, actions);
+    }
+    applyActions(run, actions) {
+        const notes = [];
+        let finished = null;
+        let question = null;
+        for (const a of actions) {
+            try {
+                if (a.type === "spawn")
+                    this.addTask(run, a);
+                else if (a.type === "send")
+                    this.followUp(run, a.task, a.message);
+                else if (a.type === "cancel")
+                    this.cancelTask(run, a.task);
+                else if (a.type === "ask")
+                    question = a.question;
+                else if (a.type === "done")
+                    finished = { summary: a.summary };
+            }
+            catch (err) {
+                notes.push(`${a.type}: ${err.message}`);
+            }
+        }
+        this.save(run);
+        this.emit(run, "plan", {
+            round: run.round,
+            actions: actions.map((a) => a.type),
+            tasks: run.tasks.map(taskSummary),
+            ...(notes.length ? { rejected: notes } : {}),
+        });
+        if (question) {
+            run.status = "waiting_human";
+            run.question = question;
+            this.save(run);
+            this.emit(run, "waiting", { question });
+            return;
+        }
+        const outstanding = run.tasks.some((t) => t.status === "running" || t.status === "pending");
+        // Nothing running, nothing asked, nothing new: asking again would just loop
+        // to maxRounds (a scripted or real model that says "keep waiting" when there
+        // is nothing to wait for). Stop and let a human steer.
+        if (!actions.length && !outstanding) {
+            run.status = "waiting_human";
+            run.question = "Nothing is running and the orchestrator gave no next step. Reply to steer it, or tell it to finish.";
+            this.save(run);
+            this.emit(run, "waiting", { question: run.question });
+            return;
+        }
+        if (finished && !outstanding) {
+            return void this.finish(run, "completed", undefined, finished.summary);
+        }
+        if (finished && outstanding) {
+            notes.push("done ignored: tasks are still running — review their results first");
+        }
+        if (notes.length && !outstanding) {
+            // Nothing to wait for and something went wrong: tell the orchestrator now.
+            void this.orchestratorTurn(run, `Some actions were rejected:\n- ${notes.join("\n- ")}\n\n${this.statusReport(run)}`);
+            return;
+        }
+        run.status = "running";
+        this.save(run);
+        // Plan mode: the specs land on the integration branch BEFORE any task
+        // branches from it, so every worker's worktree already has its file.
+        if (run.plan && actions.some((a) => a.type === "spawn")) {
+            void this.writePlan(run, "plan").then(() => this.schedule(run));
+        }
+        else {
+            this.schedule(run);
+        }
+    }
+    /** Write (or refresh) plans/<run>/ on the integration branch and commit it. */
+    async writePlan(run, why) {
+        try {
+            await this.gitLock.run(async () => {
+                const dir = path.join(run.dir, planDir(run));
+                fs.mkdirSync(dir, { recursive: true });
+                fs.writeFileSync(path.join(dir, "PLAN.md"), renderPlanIndex(run));
+                for (const t of run.tasks)
+                    fs.writeFileSync(path.join(dir, `${t.id}.md`), renderTaskFile(run, t));
+                await git(["add", "--", planDir(run)], run.dir);
+                const staged = (await git(["diff", "--cached", "--name-only"], run.dir)).trim();
+                if (staged) {
+                    await git(["-c", "user.name=Loom Orchestra", "-c", "user.email=orchestra@loom.local", "commit", "-q", "--no-verify", "-m",
+                        why === "plan" ? `plan: ${run.goal.split("\n")[0].slice(0, 60)}` : `plan: results of orchestra ${run.id}`], run.dir);
+                }
+            });
+            this.emit(run, "plan_written", { dir: planDir(run), files: run.tasks.length + 1, final: why === "final" });
+        }
+        catch (err) {
+            this.emit(run, "plan_failed", { error: err.message.slice(0, 300) });
+        }
+    }
+    addTask(run, a) {
+        const allowed = this.workersFor(run);
+        const cfg = allowed.find((w) => w.id.toLowerCase() === a.agent.toLowerCase()) ??
+            allowed.find((w) => w.kind === this.resolveAgent(a.agent)?.kind);
+        if (!cfg) {
+            throw new Error(`agent "${a.agent}" is not one of this run's workers (${run.workers.join(", ")})`);
+        }
+        let id = (a.id || "").replace(/[^a-zA-Z0-9_-]/g, "").slice(0, 16);
+        // Re-sending a spawn for a task that hasn't started revises it: that's how
+        // the orchestrator answers a hold (an overlap decision, narrower touches,
+        // another agent) without inventing a new task.
+        const unstarted = run.tasks.find((t) => t.id === id && t.attempts === 0 && t.status === "pending");
+        if (unstarted) {
+            unstarted.title = a.title.slice(0, 120);
+            unstarted.prompt = a.prompt;
+            unstarted.agent = cfg.id;
+            unstarted.kind = cfg.kind;
+            if (a.touches?.length)
+                unstarted.touches = a.touches;
+            if (a.overlap)
+                unstarted.overlap = a.overlap;
+            if (a.dependsOn)
+                unstarted.dependsOn = a.dependsOn.filter((d) => d !== id && run.tasks.some((t) => t.id === d));
+            unstarted.hold = undefined;
+            this.emit(run, "task", { task: taskSummary(unstarted) });
+            return unstarted;
+        }
+        if (!id || run.tasks.some((t) => t.id === id))
+            id = `t${run.tasks.length + 1}`;
+        while (run.tasks.some((t) => t.id === id))
+            id = `${id}x`;
+        const deps = (a.dependsOn ?? []).filter((d) => run.tasks.some((t) => t.id === d));
+        const chat = this.host.createChat(`${id} · ${a.title}`.slice(0, 60), { agentId: cfg.id });
+        const task = {
+            id,
+            title: a.title.slice(0, 120),
+            prompt: a.prompt,
+            agent: cfg.id,
+            kind: cfg.kind,
+            dependsOn: deps,
+            ...(a.touches?.length ? { touches: a.touches } : {}),
+            ...(a.overlap ? { overlap: a.overlap } : {}),
+            status: "pending",
+            chat: chat.id,
+            attempts: 0,
+            queued: [],
+        };
+        run.tasks.push(task);
+        this.emit(run, "task", { task: taskSummary(task) });
+        return task;
+    }
+    followUp(run, taskId, message) {
+        const task = run.tasks.find((t) => t.id === taskId);
+        if (!task)
+            throw new Error(`no task "${taskId}"`);
+        if (task.status === "cancelled")
+            throw new Error(`task ${taskId} was cancelled`);
+        task.queued.push(message);
+        task.reported = false;
+        if (task.status !== "running")
+            task.status = "pending";
+    }
+    cancelTask(run, taskId) {
+        const task = run.tasks.find((t) => t.id === taskId);
+        if (!task)
+            throw new Error(`no task "${taskId}"`);
+        if (task.status === "done")
+            throw new Error(`task ${taskId} already merged`);
+        task.status = "cancelled";
+        task.reported = true;
+        const live = this.live.get(`${run.id}/${task.id}`);
+        if (live?.busy())
+            void live.interrupt().catch(() => { });
+        this.emit(run, "task", { task: taskSummary(task) });
+    }
+    // ── scheduling ──
+    admitting = new Set(); // `${run}/${task}` mid-admission
+    recheckTimers = new Map();
+    schedule(run) {
+        if (run.status !== "running" || run.moving)
+            return;
+        if (this.overBudget(run))
+            return;
+        const inFlight = run.tasks.filter((t) => t.status === "running" || this.admitting.has(`${run.id}/${t.id}`)).length;
+        let slots = run.maxParallel - inFlight;
+        let waiting = false;
+        for (const task of run.tasks) {
+            if (slots <= 0)
+                break;
+            if (task.status !== "pending")
+                continue;
+            if (this.admitting.has(`${run.id}/${task.id}`))
+                continue;
+            // "decide" holds wait for the orchestrator; the rest are re-checked, not hammered
+            if (task.hold?.kind === "decide")
+                continue;
+            if (task.hold && Date.now() - (task.hold.checkedAt ?? task.hold.since) < RECHECK_MS) {
+                waiting = true;
+                continue;
+            }
+            const deps = task.dependsOn.map((d) => run.tasks.find((t) => t.id === d));
+            if (deps.some((d) => d && (d.status === "failed" || d.status === "cancelled"))) {
+                task.status = "failed";
+                task.error = "a dependency failed or was cancelled";
+                task.reported = false;
+                this.emit(run, "task", { task: taskSummary(task) });
+                continue;
+            }
+            if (!deps.every((d) => !d || d.status === "done"))
+                continue;
+            slots--;
+            void this.admitAndRun(run, task);
+        }
+        this.save(run);
+        if (waiting || run.tasks.some((t) => t.status === "pending" && t.hold && t.hold.kind !== "decide"))
+            this.armRecheck(run);
+        this.maybeReview(run);
+    }
+    armRecheck(run) {
+        if (this.recheckTimers.has(run.id))
+            return;
+        const t = setTimeout(() => {
+            this.recheckTimers.delete(run.id);
+            if (!isTerminal(run.status))
+                this.schedule(run);
+        }, RECHECK_MS);
+        t.unref?.();
+        this.recheckTimers.set(run.id, t);
+    }
+    /** Something the team coordinator watches changed (a lease freed, a PR merged): look again now. */
+    recheck(runId) {
+        const run = this.runs.get(runId);
+        if (!run || run.status !== "running")
+            return;
+        for (const t of run.tasks)
+            if (t.hold && t.hold.kind !== "decide")
+                t.hold.checkedAt = 0;
+        this.schedule(run);
+    }
+    /**
+     * Stop a running task and hold it (D33: drift into someone's hard zone).
+     * It keeps its worktree and session; when the hold clears it resumes with a
+     * "continue" follow-up instead of starting over.
+     */
+    pauseTask(runId, taskId, hold) {
+        const run = this.runs.get(runId);
+        const task = run?.tasks.find((t) => t.id === taskId);
+        if (!run || !task || task.status !== "running")
+            return;
+        task.status = "pending";
+        task.hold = hold;
+        task.queued.unshift(`You were paused: ${hold.reason}. It's clear now — continue your task where you left off, and stay out of the area you were paused for unless you must.`);
+        const live = this.live.get(`${run.id}/${task.id}`);
+        if (live?.busy())
+            void live.interrupt().catch(() => { });
+        this.save(run);
+        this.emit(run, "task", { task: taskSummary(task) });
+        this.emit(run, "task_held", { taskId: task.id, hold }, task.chat);
+    }
+    /**
+     * The owner says stop waiting (D32): a `wait:` hold is released and the task
+     * proceeds alongside the other goal, with the reason on record.
+     */
+    stopWaiting(runId, taskId) {
+        const run = this.mustGet(runId);
+        const task = run.tasks.find((t) => t.id === taskId);
+        if (!task)
+            throw new Error(`no task "${taskId}"`);
+        if (task.hold?.kind !== "wait")
+            throw new Error(`task ${taskId} isn't waiting on another goal`);
+        task.overlap = `proceed:the owner stopped waiting on ${task.hold.runId ?? "the other goal"}`;
+        task.hold = undefined;
+        this.save(run);
+        this.emit(run, "task", { task: taskSummary(task) });
+        this.schedule(run);
+        return task;
+    }
+    /** A team fact for the orchestrator's next review (D33, D34). */
+    addNote(runId, note) {
+        const run = this.runs.get(runId);
+        if (!run || isTerminal(run.status))
+            return;
+        run.notes = [...(run.notes ?? []), note.slice(0, 1000)].slice(-20);
+        this.save(run);
+    }
+    /** Ask the team coordinator (if any) whether this task may start, then start it. */
+    async admitAndRun(run, task) {
+        const coord = this.host.coordinator?.();
+        if (!coord)
+            return this.runTask(run, task);
+        const key = `${run.id}/${task.id}`;
+        this.admitting.add(key);
+        let a;
+        try {
+            a = await coord.admit(run, task);
+        }
+        catch (err) {
+            a = { go: false, hold: { kind: "capacity", reason: `team hub unreachable: ${err.message}`, since: Date.now() } };
+        }
+        this.admitting.delete(key);
+        if (isTerminal(run.status) || task.status !== "pending")
+            return;
+        if (!a.go) {
+            const was = task.hold?.reason;
+            task.hold = { ...a.hold, since: task.hold?.since ?? a.hold.since, checkedAt: Date.now() };
+            task.reported = false;
+            this.save(run);
+            if (was !== task.hold.reason) {
+                this.emit(run, "task", { task: taskSummary(task) });
+                this.emit(run, "task_held", { taskId: task.id, hold: task.hold }, task.chat);
+            }
+            this.schedule(run);
+            return;
+        }
+        task.hold = undefined;
+        if (a.note)
+            this.addNote(run.id, a.note);
+        if (a.rebase) {
+            try {
+                await this.syncWithBase(run);
+            }
+            catch (err) {
+                task.hold = { kind: "decide", reason: `couldn't bring fresh ${run.baseBranch ?? "main"} into the goal before starting: ${err.message}`, since: Date.now() };
+                this.save(run);
+                this.emit(run, "task", { task: taskSummary(task) });
+                this.maybeReview(run);
+                return;
+            }
+        }
+        return this.runTask(run, task);
+    }
+    /**
+     * Bring the base branch's latest into the integration branch (D30): a task
+     * that waited for a teammate's PR must build on the merged code.
+     */
+    async syncWithBase(run) {
+        const base = run.baseBranch;
+        if (!base)
+            return;
+        await this.gitLock.run(async () => {
+            await git(["fetch", "-q", "origin", base], run.dir).catch(() => { });
+            const ref = (await gitOk(["rev-parse", "--verify", `origin/${base}`], run.dir)) ? `origin/${base}` : base;
+            await commitAll(run.dir, `orchestra ${run.id}: orchestrator edits`);
+            try {
+                await git(["-c", "user.name=Loom Orchestra", "-c", "user.email=orchestra@loom.local", "merge", "--no-edit", "-q", ref], run.dir);
+            }
+            catch (err) {
+                await git(["merge", "--abort"], run.dir).catch(() => { });
+                throw err;
+            }
+        });
+        this.emit(run, "synced", { with: base });
+    }
+    /** When nothing can move without the orchestrator, give it a turn. */
+    maybeReview(run) {
+        if (run.status !== "running" || this.orchestratorBusy.has(run.id))
+            return;
+        if (run.tasks.some((t) => t.status === "running" || this.admitting.has(`${run.id}/${t.id}`)))
+            return;
+        if (run.race) {
+            // A race has no reviewer: it's over when every entrant has finished.
+            if (run.tasks.some((t) => t.status === "pending"))
+                return;
+            const done = run.tasks.filter((t) => t.status === "done").length;
+            void this.finish(run, "completed", undefined, `${done} of ${run.tasks.length} finished — ${PICK_ONE}`);
+            return;
+        }
+        const ready = (t) => t.status === "pending" && t.dependsOn.every((d) => run.tasks.find((x) => x.id === d)?.status === "done");
+        if (run.tasks.some((t) => ready(t) && !t.hold))
+            return;
+        // Waiting on teammates (a PR, a zone, capacity) is not a reason to wake
+        // the orchestrator — unless something needs its decision.
+        const needsDecision = run.tasks.some((t) => ready(t) && t.hold?.kind === "decide");
+        if (!needsDecision && run.tasks.some((t) => ready(t) && t.hold))
+            return;
+        run.status = "reviewing";
+        this.save(run);
+        this.emit(run, "reviewing", { round: run.round + 1 });
+        void this.orchestratorTurn(run, this.statusReport(run));
+    }
+    /** The report the orchestrator reviews: every task's outcome since last time. */
+    statusReport(run) {
+        const lines = [`Status of orchestra run ${run.id} (integration branch ${run.branch}):`];
+        for (const t of run.tasks) {
+            const head = `\n### ${t.id} · ${t.title} — ${t.status.toUpperCase()} (worker: ${t.agent}, attempts: ${t.attempts})`;
+            lines.push(head);
+            if (t.reported && (t.status === "done" || t.status === "cancelled")) {
+                lines.push("(already reviewed)");
+                continue;
+            }
+            if (t.files?.length)
+                lines.push(`Files changed: ${t.files.slice(0, 30).join(", ")}${t.files.length > 30 ? " …" : ""}`);
+            if (t.status === "conflict") {
+                lines.push(`Its branch ${t.branch} conflicts with the integration branch. To fix, send it a follow-up asking it to ` +
+                    `run \`git merge ${run.branch}\` in its worktree, resolve the conflicts, and verify.`);
+            }
+            if (t.hold) {
+                lines.push(`On hold (${t.hold.kind}): ${t.hold.reason}`);
+                if (t.hold.kind === "decide") {
+                    lines.push(`Answer by re-sending the spawn for ${t.id} (same id) with "overlap": "wait:<goal id>" (start after that ` +
+                        `teammate's PR merges), "narrow" (with revised, non-overlapping "touches"), or "proceed:<why it's safe>"; ` +
+                        `or give it "touches" / another agent as the reason says.`);
+                }
+            }
+            if (t.status === "needs_input") {
+                lines.push(`${t.id} is waiting on an answer. Reply to it with a \`send\` action (task "${t.id}") — it resumes in the same worktree — ` +
+                    `or, if only the human can answer, use \`ask\`.`);
+            }
+            if (t.error)
+                lines.push(`Error: ${t.error}`);
+            if (t.result)
+                lines.push(`Worker report:\n${t.result}`);
+            t.reported = true;
+        }
+        if (run.notes?.length) {
+            lines.push("\n## From your team");
+            for (const n of run.notes)
+                lines.push(`- ${n}`);
+            run.notes = [];
+        }
+        lines.push("\nReview the results (the integration branch in your working directory has every merged task). " +
+            "Reply with your next actions — follow-ups, new tasks, or done.");
+        this.save(run);
+        return lines.join("\n");
+    }
+    async runTask(run, task) {
+        task.status = "running";
+        task.attempts++;
+        task.startedAt ??= Date.now();
+        task.error = undefined;
+        this.save(run);
+        this.emit(run, "task", { task: taskSummary(task) });
+        this.emit(run, "task_started", { taskId: task.id, agent: task.agent, title: task.title }, task.chat);
+        const key = `${run.id}/${task.id}`;
+        try {
+            this.host.gate(task.agent);
+            if (!task.dir) {
+                const slug = task.id;
+                const branch = `${run.branch.replace(/\/main$/, "")}/${slug}`;
+                const dir = path.join(path.dirname(run.dir), slug);
+                await this.gitLock.run(async () => {
+                    // Branch from the integration tip, so dependencies' work is there.
+                    const tip = (await git(["rev-parse", "HEAD"], run.dir)).trim();
+                    await createWorktree(this.host.projectDir, dir, branch, tip);
+                });
+                task.branch = branch;
+                task.dir = dir;
+                this.save(run);
+            }
+            let agent = this.live.get(key);
+            const freshSession = !agent;
+            if (!agent) {
+                const cfg = this.resolveAgent(task.agent) ?? { id: task.agent, kind: task.kind, role: "worker" };
+                agent = this.host.makeAgent({ ...cfg, role: "worker" }, task.dir);
+                this.live.set(key, agent);
+                this.wire(run, agent, cfg.id, task.chat, key);
+                await agent.start();
+            }
+            // The first attempt always sends the task itself — a follow-up the
+            // orchestrator queued in the same breath waits its turn behind it.
+            const first = task.attempts === 1;
+            // A later attempt sends the orchestrator's next follow-up. With none
+            // queued, this is a task picking back up after Loom restarted (resume,
+            // or a goal moved here): say so, and give it the task again — its
+            // session is new, its worktree still has everything it did.
+            const followUp = first ? undefined : task.queued.shift();
+            const text = first
+                ? task.prompt
+                : (followUp ??
+                    `Loom was restarted while you were on this task (${task.title}). Everything you'd done is still in this worktree. ` +
+                        `Check where it stands, finish the task, and report back.\n\nThe task, again:\n${task.prompt}`);
+            this.host.append({
+                kind: "message",
+                chat: task.chat,
+                payload: { text, author: first ? "orchestrator" : "orchestrator", orchestra: { runId: run.id, taskId: task.id } },
+            });
+            this.turnText.set(key, "");
+            const briefing = first || freshSession
+                ? workerBriefing({
+                    project: this.host.projectName,
+                    runGoal: run.goal,
+                    task,
+                    branch: task.branch,
+                    brain: await this.host.briefingFor(task.prompt, task.agent, task.touches ?? task.files ?? []),
+                    ...(run.plan ? { planFile: `${planDir(run)}/${task.id}.md` } : {}),
+                })
+                : undefined;
+            await agent.send({ text, ...(briefing ? { briefing } : {}) });
+            if (task.status === "cancelled" || isTerminal(run.status))
+                return;
+            // paused mid-turn (pauseTask): not finished, nothing to integrate yet
+            if (task.status === "pending") {
+                this.schedule(run);
+                return;
+            }
+            const reply = (this.turnText.get(key) ?? "").trim();
+            this.turnText.delete(key); // kept on the task (task.result), not here, once the turn is read
+            task.result = reply.length > RESULT_CHARS ? `${reply.slice(0, RESULT_CHARS)}\n… (truncated)` : reply || "(no report)";
+            const turnError = this.lastError.get(key);
+            this.lastError.delete(key);
+            const asked = this.workerQuestion.get(key);
+            this.workerQuestion.delete(key);
+            if (asked) {
+                // Its work so far stays in the worktree, unmerged; the orchestrator
+                // answers with a `send` (the task resumes there) or asks the human.
+                task.status = "needs_input";
+                task.result = `The worker stopped to ask: ${asked}${reply ? `\n\nWhat it said before asking:\n${task.result}` : ""}`;
+                task.finishedAt = Date.now();
+                task.reported = false;
+                this.save(run);
+                this.emit(run, "task", { task: taskSummary(task) });
+                this.emit(run, "task_finished", { taskId: task.id, status: task.status, files: task.files ?? [] }, task.chat);
+                this.schedule(run);
+                return;
+            }
+            if (turnError)
+                task.error = turnError;
+            // A turn that errored and said nothing died — it is not "done", and a
+            // task depending on it must not start on top of it. (An error event
+            // alongside a real report is a warning the orchestrator gets to read.)
+            if (turnError && !reply) {
+                task.status = "failed";
+            }
+            else if (task.queued.length) {
+                // The orchestrator already queued a follow-up: keep going on the same
+                // worktree before merging.
+                task.status = "pending";
+            }
+            else {
+                await this.integrate(run, task);
+            }
+        }
+        catch (err) {
+            if (task.status !== "cancelled") {
+                task.status = "failed";
+                task.error = err.message.slice(0, 1000);
+            }
+        }
+        task.finishedAt = Date.now();
+        task.reported = false;
+        this.save(run);
+        this.emit(run, "task", { task: taskSummary(task) });
+        this.emit(run, "task_finished", { taskId: task.id, status: task.status, files: task.files ?? [] }, task.chat);
+        if (task.status === "done")
+            this.host.coordinator?.()?.onTaskDone?.(run, task);
+        this.schedule(run);
+    }
+    lastError = new Map();
+    /** `${run}/${task}` → the question a worker stopped to ask mid-turn. */
+    workerQuestion = new Map();
+    async integrate(run, task) {
+        const dir = task.dir;
+        if (run.race) {
+            // An entrant's work stays on its own branch, to be compared, not merged.
+            await this.gitLock.run(async () => {
+                await commitAll(dir, taskCommitMessage(run, task, this.host.member?.() ?? null));
+                task.files = (await git(["diff", "--name-only", `${run.baseCommit}...HEAD`], dir).catch(() => "")).split("\n").filter(Boolean);
+                const stat = await git(["diff", "--shortstat", `${run.baseCommit}...HEAD`], dir).catch(() => "");
+                task.lines = [...stat.matchAll(/(\d+) (?:insertion|deletion)/g)].reduce((n, m) => n + Number(m[1]), 0);
+                task.status = "done";
+            });
+            return;
+        }
+        await this.gitLock.run(async () => {
+            await commitAll(dir, taskCommitMessage(run, task, this.host.member?.() ?? null));
+            const files = (await git(["diff", "--name-only", `${run.baseCommit}...HEAD`], dir).catch(() => ""))
+                .split("\n")
+                .filter(Boolean);
+            task.files = files;
+            // Anything the orchestrator left lying in the integration tree would
+            // block the merge; record it rather than lose it.
+            await commitAll(run.dir, `orchestra ${run.id}: orchestrator edits`);
+            try {
+                await git(["-c", "user.name=Loom Orchestra", "-c", "user.email=orchestra@loom.local", "merge", "--no-ff", "--no-edit", "-m", `orchestra ${task.id}: ${task.title}`, task.branch], run.dir);
+                task.status = "done";
+                task.mergeCommit = (await git(["rev-parse", "HEAD"], run.dir)).trim();
+                const stat = await git(["diff", "--shortstat", `${task.mergeCommit}^1`, task.mergeCommit], run.dir).catch(() => "");
+                task.lines = [...stat.matchAll(/(\d+) (?:insertion|deletion)/g)].reduce((n, m) => n + Number(m[1]), 0);
+            }
+            catch (err) {
+                await git(["merge", "--abort"], run.dir).catch(() => { });
+                task.status = "conflict";
+                task.error = `merge conflict: ${err.message.slice(0, 400)}`;
+            }
+        });
+        if (task.status === "needs_input")
+            return;
+        if (task.status === "done" && /\?\s*$/.test(task.result ?? "") && !task.files?.length) {
+            // Ended on a question and changed nothing: it's asking, not done.
+            task.status = "needs_input";
+        }
+    }
+    // ── event wiring ──
+    wire(run, agent, agentId, chat, key) {
+        agent.onStream?.((d) => this.host.stream?.({ agentId, chat, ...d }));
+        agent.onEvent((e) => {
+            const p = e.payload;
+            if (e.kind === "message" && !p.reasoning && p.role !== "user") {
+                const prev = this.turnText.get(key) ?? "";
+                this.turnText.set(key, capTurnText(`${prev}\n${String(p.text ?? "")}`));
+            }
+            if (e.kind === "error")
+                this.lastError.set(key, String(p.message ?? "error"));
+            // A worker that stops mid-turn to ask (opencode's question tool, a CLI's
+            // permission prompt) would wait forever for an answer nobody gives — the
+            // goal hung (found by the real-product e2e run). Take the question up to
+            // the orchestrator: stop the turn, and the task ends as needs_input.
+            if (e.kind === "needs_input" && !key.endsWith("/orch") && !this.workerQuestion.has(key)) {
+                this.workerQuestion.set(key, String(p.question ?? "the worker needs input").slice(0, 500));
+                void agent.interrupt().catch(() => { });
+            }
+            if (e.kind === "file_edit" && !key.endsWith("/orch") && typeof p.path === "string") {
+                const task = run.tasks.find((t) => `${run.id}/${t.id}` === key);
+                if (task)
+                    this.host.coordinator?.()?.onEdit?.(run, task, p.path);
+            }
+            const event = this.host.append({
+                kind: e.kind,
+                agentId,
+                chat,
+                payload: { ...p, orchestra: { runId: run.id, ...(key.endsWith("/orch") ? { role: "orchestrator" } : { taskId: key.split("/")[1] }) } },
+            });
+            if (e.kind === "status" && p.state === "turn_cost") {
+                const usd = Number(p.costUsd ?? 0);
+                if (usd > 0) {
+                    run.costUsd += usd;
+                    const task = run.tasks.find((t) => `${run.id}/${t.id}` === key);
+                    if (task)
+                        task.costUsd = (task.costUsd ?? 0) + usd;
+                }
+            }
+            this.host.observe(event);
+        });
+    }
+    /** A finished or aborted run's per-turn scratch (reply text, errors, questions) goes with it. */
+    forgetRun(runId) {
+        const prefix = `${runId}/`;
+        for (const map of [this.turnText, this.lastError, this.workerQuestion])
+            for (const k of [...map.keys()])
+                if (k.startsWith(prefix))
+                    map.delete(k);
+    }
+    async finish(run, status, error, summary) {
+        // Do the slow parts first, then flip the status and announce it in one
+        // synchronous step: a client that sees "completed" must also find the
+        // completed event (polling status in the gap raced this).
+        await this.stopAll(run);
+        this.forgetRun(run.id);
+        if (run.plan) {
+            // The plan's final state — statuses and results — rides the branch too.
+            const final = { ...run, status, ...(error ? { error } : {}), ...(summary ? { summary } : {}) };
+            await this.writePlan(final, "final");
+        }
+        const commits = await git(["rev-list", "--count", `${run.baseCommit}..${run.branch}`], this.host.projectDir).catch(() => "0");
+        // Aborted while we were finishing up: the human's abort stands.
+        if (run.status === "aborted")
+            return;
+        run.status = status;
+        if (error)
+            run.error = error;
+        if (summary)
+            run.summary = summary;
+        this.save(run);
+        this.emit(run, status, {
+            ...(summary ? { summary } : {}),
+            ...(error ? { error } : {}),
+            branch: run.branch,
+            commits: Number(commits.trim()) || 0,
+            tasks: run.tasks.map(taskSummary),
+            costUsd: run.costUsd,
+            ...(run.race ? { race: true } : {}),
+        });
+        if (summary && run.race) {
+            // nobody led a race, so Loom says how it ended
+            this.host.append({
+                kind: "message",
+                chat: run.chat,
+                payload: { text: `🏁 Race finished — ${summary} They're side by side in the Orchestra tab.`, author: "loom", orchestra: { runId: run.id, role: "summary" } },
+            });
+        }
+        else if (summary) {
+            this.host.append({
+                kind: "message",
+                agentId: run.orchestrator.agent,
+                chat: run.chat,
+                payload: { text: `**Orchestra complete.** ${summary}\n\nAll work is on branch \`${run.branch}\` — apply it to merge into your branch.`, orchestra: { runId: run.id, role: "summary" } },
+            });
+        }
+        this.host.coordinator?.()?.onRunEnd?.(run);
+        // A goal that already has a PR (a fix round, an adopted goal) always goes back to that PR.
+        // A race's integration branch is empty until you pick an entrant.
+        if (status === "completed" && !run.race)
+            await this.deliver(run, run.from || run.delivered?.prUrl ? "pr" : undefined);
+    }
+    /**
+     * Do what the project's git delivery policy says with a completed run:
+     * nothing, merge it in, merge and push, or push its branch and open a PR.
+     * A failure here never un-completes the run — the work is safe on its
+     * branch — it's reported, and the manual Apply is still there.
+     */
+    /**
+     * D59: where a big goal's stack is cut — tasks in the order they merged into
+     * the integration branch, sliced by size (cutStack). Null when unknowable.
+     */
+    async stackSlices(run) {
+        const order = (await git(["rev-list", "--first-parent", "--reverse", `${run.baseCommit}..${run.branch}`], run.dir).catch(() => ""))
+            .split("\n")
+            .filter(Boolean);
+        const merged = run.tasks
+            .filter((t) => t.status === "done" && t.mergeCommit && order.includes(t.mergeCommit))
+            .sort((a, b) => order.indexOf(a.mergeCommit) - order.indexOf(b.mergeCommit))
+            .map((t) => ({ id: t.id, commit: t.mergeCommit, lines: t.lines ?? 0, dependsOn: t.dependsOn }));
+        return merged.length ? cutStack(merged) : null;
+    }
+    /**
+     * Push one branch per slice and open a PR for each, each based on the one
+     * below; the top slice is the goal's own branch (so fixes land on it). The
+     * landing manager lands them bottom-up with the merge method.
+     */
+    async deliverStack(run, slices) {
+        const prefix = run.branch.replace(/\/main$/, "");
+        const base = run.baseBranch ?? "main";
+        const stack = [];
+        let below = base;
+        for (let i = 0; i < slices.length; i++) {
+            const top = i === slices.length - 1;
+            const branch = top ? run.branch : `${prefix}/stack-${i + 1}`;
+            if (!top)
+                await git(["push", "-q", "-f", "origin", `${slices[i].at(-1).commit}:refs/heads/${branch}`], run.dir);
+            const ids = slices[i].map((t) => t.id);
+            const out = await gh(["pr", "create", "--head", branch, "--base", below,
+                "--title", `${run.goal.split("\n")[0].slice(0, 60)} (${i + 1}/${slices.length})`,
+                "--body", prBody(run, [`Part ${i + 1} of ${slices.length} of a stacked goal — tasks ${ids.join(", ")}. Land bottom-up.`, ""])], this.host.projectDir);
+            const url = out.match(/https:\/\/\S+/)?.[0] ?? "";
+            stack.push({ pr: Number(/\/pull\/(\d+)/.exec(url)?.[1] ?? 0), url, branch, base: below });
+            below = branch;
+        }
+        const topPr = stack.at(-1);
+        run.landing = { ...newLanding(topPr.pr, topPr.url), stack };
+        this.emit(run, "stacked", { stack });
+        return topPr.url;
+    }
+    async deliver(run, mode = this.host.gitDelivery?.() ?? "none") {
+        if (mode === "none")
+            return;
+        // D38: a protected branch only receives PRs, whatever the project setting says.
+        const intoBranch = run.baseBranch ?? "";
+        if ((mode === "commit" || mode === "push") && intoBranch && this.host.coordinator?.()?.isProtected?.(intoBranch)) {
+            this.emit(run, "delivery_policy", { from: mode, to: "pr", branch: intoBranch });
+            mode = "pr";
+        }
+        try {
+            if (mode === "commit" || mode === "push") {
+                const { into } = await this.apply(run.id);
+                let pushed;
+                if (mode === "push") {
+                    const up = await git(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"], this.host.projectDir).catch(() => "");
+                    await git(up.trim() ? ["push", "-q"] : ["push", "-q", "-u", "origin", into], this.host.projectDir);
+                    pushed = into;
+                }
+                run.delivered = { mode, into, ...(pushed ? { pushed } : {}), at: Date.now() };
+            }
+            else if (mode === "pr") {
+                await this.gitLock.run(() => commitAll(run.dir, `orchestra ${run.id}: final edits`).catch(() => false));
+                const target = this.prBranch(run);
+                await git(["push", "-q", "-u", "origin", `${run.branch}:${target}`], run.dir);
+                if (run.delivered?.prUrl || run.from) {
+                    // A fix to a PR that already exists (Phase 4): the push is the delivery.
+                    const prUrl = run.delivered?.prUrl ?? run.from.url;
+                    run.delivered = { mode, pushed: target, prUrl, at: Date.now() };
+                }
+                else {
+                    const stack = this.host.coordinator?.()?.stackMode?.() === "auto" ? await this.stackSlices(run) : null;
+                    if (stack && stack.length > 1) {
+                        run.delivered = { mode, pushed: target, prUrl: await this.deliverStack(run, stack), at: Date.now() };
+                    }
+                    else {
+                        const out = await gh(["pr", "create", "--head", run.branch, ...(run.baseBranch ? ["--base", run.baseBranch] : []),
+                            "--title", run.goal.split("\n")[0].slice(0, 70), "--body", prBody(run)], this.host.projectDir);
+                        const prUrl = out.match(/https:\/\/\S+/)?.[0];
+                        run.delivered = { mode, pushed: run.branch, ...(prUrl ? { prUrl } : {}), at: Date.now() };
+                        const n = Number(/\/pull\/(\d+)/.exec(prUrl ?? "")?.[1]);
+                        if (prUrl && n)
+                            run.landing = newLanding(n, prUrl);
+                    }
+                }
+            }
+            run.deliveryError = undefined;
+            this.save(run);
+            this.emit(run, "delivered", { ...run.delivered });
+        }
+        catch (err) {
+            run.deliveryError = err.message.slice(0, 500);
+            this.save(run);
+            this.emit(run, "delivery_failed", { mode, error: run.deliveryError });
+        }
+    }
+}
+/** A new PR's landing record. */
+export function newLanding(pr, url) {
+    return { pr, url, state: "open", fixAttempts: 0, reruns: [], flaky: [], reviews: 0, updatedAt: Date.now() };
+}
+/** The goal PR's description: the summary, the task table, the plan. */
+export function prBody(run, extra = []) {
+    return [
+        run.summary ?? "",
+        "",
+        ...extra,
+        "| task | agent | status | files |",
+        "|---|---|---|---|",
+        ...run.tasks.map((t) => `| ${t.id} · ${t.title} | ${t.agent} | ${t.status} | ${t.files?.length ?? 0} |`),
+        "",
+        ...(run.plan ? [`Plan: \`${planDir(run)}/PLAN.md\``, ""] : []),
+        `Orchestrated by Loom · ${run.orchestrator.agent} with ${run.workers.join(", ")}`,
+    ].join("\n");
+}
+/**
+ * Verification commands a Claude orchestrator may run while reviewing.
+ *
+ * Headless Claude in acceptEdits mode can't run any shell command, so a Claude
+ * orchestrator could only read the workers' code and take their word that the
+ * tests passed (seen on a real run: "could not run node --test, approval not
+ * granted"). Codex, sandboxed, just ran them. These are the checks a reviewer
+ * runs — tests, typecheck, build, and read-only git — and nothing else.
+ */
+export const ORCHESTRATOR_VERIFY_TOOLS = [
+    "npm test", "npm run test", "npm run build", "npm run typecheck", "npm run lint",
+    "pnpm test", "yarn test", "bun test", "node --test", "npx vitest run", "npx tsc --noEmit",
+    "cargo test", "cargo check", "go test", "go build", "pytest", "python -m pytest",
+    "git log", "git diff", "git status", "git show",
+].map((c) => `Bash(${c}:*)`);
+function orchestratorOptions(cfg) {
+    if (cfg.kind !== "claude-code")
+        return cfg.options;
+    const extra = Array.isArray(cfg.options?.extraArgs) ? cfg.options.extraArgs : [];
+    return { ...(cfg.options ?? {}), extraArgs: [...extra, "--allowedTools", ORCHESTRATOR_VERIFY_TOOLS.join(",")] };
+}
+export function taskSummary(t) {
+    return {
+        id: t.id,
+        title: t.title,
+        agent: t.agent,
+        kind: t.kind,
+        status: t.status,
+        dependsOn: t.dependsOn,
+        chat: t.chat,
+        attempts: t.attempts,
+        files: t.files ?? [],
+        ...(t.touches?.length ? { touches: t.touches } : {}),
+        ...(t.overlap ? { overlap: t.overlap } : {}),
+        ...(t.hold ? { hold: t.hold } : {}),
+        ...(t.error ? { error: t.error } : {}),
+        ...(t.costUsd ? { costUsd: t.costUsd } : {}),
+    };
+}
+export function isTerminal(s) {
+    return s === "completed" || s === "failed" || s === "aborted" || s === "moved";
+}
+/** Where a moved goal's branches travel: hidden refs, like WIP refs (D11, D75). */
+export function runRef(runId, name) {
+    return `refs/loom/run/${runId}/${name}`;
+}
+function clamp(n, lo, hi) {
+    return Math.max(lo, Math.min(hi, Math.floor(Number(n) || lo)));
+}
+//# sourceMappingURL=orchestra.js.map