tmux-ide 1.3.1 → 2.1.0

package/src/lib/orchestrator.test.ts

@@ -0,0 +1,2358 @@
+import { describe, it, beforeEach, afterEach, expect } from "bun:test";
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  dispatch,
+  detectStalls,
+  detectCompletions,
+  buildTaskPrompt,
+  buildGoalPrompt,
+  runHook,
+  createOrchestrator,
+  isAgentPane,
+  isAgentBusy,
+  isIdleForDispatch,
+  saveOrchestratorState,
+  loadOrchestratorState,
+  syncClaims,
+  gracefulShutdown,
+  reloadConfig,
+  reconcile,
+  agentIdentifier,
+  normalizePaneTitle,
+  getPaneSpecialties,
+  dispatchGoals,
+  findBestAgent,
+  getCurrentMilestone,
+  isMilestoneReady,
+  checkMilestoneCompletion,
+  checkValidationResults,
+  buildValidationPrompt,
+  dispatchPlanning,
+  buildPlanningPrompt,
+  handleMissionComplete,
+} from "./orchestrator.ts";
+import { readEvents } from "./event-log.ts";
+import { loadResearchState, saveResearchState } from "./research.ts";
+import {
+  ensureTasksDir,
+  saveMission,
+  loadMission,
+  saveGoal,
+  saveTask,
+  loadTask,
+  loadTasks,
+  loadGoal,
+  type Goal,
+  type Mission,
+} from "./task-store.ts";
+import { loadValidationState, saveValidationState } from "./validation.ts";
+import { _setExecutor, type PaneInfo } from "../widgets/lib/pane-comms.ts";
+import {
+  makeTask,
+  makePane,
+  makeOrchestratorConfig,
+  makeOrchestratorState,
+} from "../__tests__/support.ts";
+
+let tmpDir: string;
+let restoreTmux: () => void;
+let tmuxCalls: { args: string[] }[];
+let mockPanes: PaneInfo[];
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), "tmux-ide-orch-test-"));
+  ensureTasksDir(tmpDir);
+  tmuxCalls = [];
+  mockPanes = [];
+
+  restoreTmux = _setExecutor((_cmd: string, args: string[]) => {
+    tmuxCalls.push({ args });
+    // Mock list-panes to return mockPanes as tab-separated output
+    if (args[0] === "list-panes") {
+      return mockPanes
+        .map(
+          (p) =>
+            `${p.id}\t${p.index}\t${p.title}\t${p.currentCommand}\t${p.width}\t${p.height}\t${p.active ? "1" : "0"}\t${p.role ?? ""}\t${p.name ?? ""}\t${p.type ?? ""}`,
+        )
+        .join("\n");
+    }
+    return "";
+  });
+});
+
+afterEach(() => {
+  restoreTmux();
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe("dispatch", () => {
+  it("assigns highest-priority task to idle agent", () => {
+    const task1 = makeTask({ id: "001", title: "Low priority", priority: 2 });
+    const task2 = makeTask({ id: "002", title: "High priority", priority: 1 });
+    saveTask(tmpDir, task1);
+    saveTask(tmpDir, task2);
+
+    const pane = makePane({ id: "%1", index: 0, title: "Agent 1", currentCommand: "zsh" });
+    const expectedName = agentIdentifier(pane);
+    const panes: PaneInfo[] = [pane];
+    mockPanes = panes;
+
+    const config = makeOrchestratorConfig(tmpDir);
+    const state = makeOrchestratorState();
+
+    dispatch(config, state, [task1, task2], panes);
+
+    // Task 002 (higher priority) should be assigned first
+    const assigned = loadTask(tmpDir, "002");
+    expect(assigned?.assignee).toBe(expectedName);
+    expect(assigned?.status).toBe("in-progress");
+  });
+
+  it("skips master pane", () => {
+    const task = makeTask();
+    saveTask(tmpDir, task);
+
+    const agentPane = makePane({ id: "%1", index: 1, title: "Agent 1", currentCommand: "zsh" });
+    const expectedName = agentIdentifier(agentPane);
+    const panes: PaneInfo[] = [
+      makePane({ id: "%0", index: 0, title: "Master", currentCommand: "zsh", role: "lead" }),
+      agentPane,
+    ];
+    mockPanes = panes;
+
+    const config = makeOrchestratorConfig(tmpDir);
+    const state = makeOrchestratorState();
+
+    dispatch(config, state, [task], panes);
+
+    const assigned = loadTask(tmpDir, "001");
+    expect(assigned?.assignee).toBe(expectedName);
+  });
+
+  it("does not assign when no idle agents", () => {
+    const task = makeTask();
+    saveTask(tmpDir, task);
+
+    // Agent pane is busy (spinner in title indicates active work)
+    const panes: PaneInfo[] = [
+      makePane({ id: "%1", title: "⠙ Agent 1", currentCommand: "claude" }),
+    ];
+    mockPanes = panes;
+
+    const config = makeOrchestratorConfig(tmpDir);
+    const state = makeOrchestratorState();
+
+    dispatch(config, state, [task], panes);
+
+    const notAssigned = loadTask(tmpDir, "001");
+    expect(notAssigned?.assignee).toBe(null);
+  });
+
+  it("does not assign when no todo tasks", () => {
+    const task = makeTask({ status: "in-progress", assignee: "Agent 1" });
+    saveTask(tmpDir, task);
+
+    const panes: PaneInfo[] = [makePane({ id: "%2", title: "Agent 2", currentCommand: "zsh" })];
+    mockPanes = panes;
+
+    const config = makeOrchestratorConfig(tmpDir);
+    const state = makeOrchestratorState();
+
+    dispatch(config, state, [task], panes);
+
+    // No send-keys calls for Agent 2
+    const sendCalls = tmuxCalls.filter(
+      (c) => c.args.includes("send-keys") && c.args.includes("%2"),
+    );
+    expect(sendCalls.length).toBe(0);
+  });
+});
+
+describe("detectStalls", () => {
+  it("sends nudge after timeout", () => {
+    const pane = makePane({ id: "%1", index: 0, title: "Agent 1" });
+    const name = agentIdentifier(pane);
+    const task = makeTask({ status: "in-progress", assignee: name });
+
+    const panes: PaneInfo[] = [pane];
+
+    const config = makeOrchestratorConfig(tmpDir, { stallTimeout: 1000 });
+    const state = makeOrchestratorState({
+      lastActivity: new Map([["%1", Date.now() - 2000]]),
+    });
+
+    detectStalls(config, state, [task], panes);
+
+    // Should have sent a nudge via send-keys
+    const sendCalls = tmuxCalls.filter((c) => c.args.includes("send-keys"));
+    expect(sendCalls.length > 0).toBeTruthy();
+  });
+
+  it("does not nudge before timeout", () => {
+    const pane = makePane({ id: "%1", index: 0, title: "Agent 1" });
+    const name = agentIdentifier(pane);
+    const task = makeTask({ status: "in-progress", assignee: name });
+
+    const panes: PaneInfo[] = [pane];
+
+    const config = makeOrchestratorConfig(tmpDir, { stallTimeout: 300000 });
+    const state = makeOrchestratorState({
+      lastActivity: new Map([["%1", Date.now()]]),
+    });
+
+    detectStalls(config, state, [task], panes);
+
+    const sendCalls = tmuxCalls.filter((c) => c.args.includes("send-keys"));
+    expect(sendCalls.length).toBe(0);
+  });
+});
+
+describe("detectCompletions", () => {
+  it("notifies master when task goes from in-progress to done", () => {
+    const task = makeTask({ status: "done", assignee: "Agent 1", proof: { notes: "tests pass" } });
+
+    const panes: PaneInfo[] = [makePane({ id: "%0", title: "Master" })];
+
+    const config = makeOrchestratorConfig(tmpDir);
+    const state = makeOrchestratorState({
+      previousTasks: new Map([["001", "in-progress"]]),
+    });
+
+    detectCompletions(config, state, [task], panes);
+
+    // Should have sent notification to master
+    const sendCalls = tmuxCalls.filter(
+      (c) => c.args.includes("send-keys") && c.args.includes("%0"),
+    );
+    expect(sendCalls.length > 0).toBeTruthy();
+  });
+
+  it("does not notify when task was already done", () => {
+    const task = makeTask({ status: "done" });
+
+    const panes: PaneInfo[] = [makePane({ id: "%0", title: "Master" })];
+
+    const config = makeOrchestratorConfig(tmpDir);
+    const state = makeOrchestratorState({
+      previousTasks: new Map([["001", "done"]]),
+    });
+
+    detectCompletions(config, state, [task], panes);
+
+    const sendCalls = tmuxCalls.filter((c) => c.args.includes("send-keys"));
+    expect(sendCalls.length).toBe(0);
+  });
+
+  it("processes completed research tasks into the library and clears active state", () => {
+    const task = makeTask({
+      id: "099",
+      title: "Research: periodic",
+      status: "done",
+      assignee: "Researcher",
+      tags: ["research", "periodic"],
+      updated: "2026-01-03T00:00:00Z",
+      salientSummary: "Found a contract gap",
+    });
+    saveResearchState(tmpDir, {
+      lastResearchAt: {},
+      missionStartAnalyzed: false,
+      milestoneTaskCounts: {},
+      activeResearchTaskId: "099",
+      retryWindow: [],
+    });
+
+    const panes: PaneInfo[] = [makePane({ id: "%0", title: "Master" })];
+    const config = makeOrchestratorConfig(tmpDir);
+    const state = makeOrchestratorState({
+      previousTasks: new Map([["099", "in-progress"]]),
+    });
+    const researchState = loadResearchState(tmpDir);
+
+    detectCompletions(config, state, [task], panes, researchState);
+
+    expect(loadResearchState(tmpDir).activeResearchTaskId).toBe(null);
+    expect(existsSync(join(tmpDir, ".tmux-ide", "library", "research-findings.md"))).toBeTruthy();
+    expect(
+      readFileSync(join(tmpDir, ".tmux-ide", "library", "research-findings.md"), "utf-8"),
+    ).toContain("Found a contract gap");
+    expect(readEvents(tmpDir).some((event) => event.type === "research_finding")).toBeTruthy();
+  });
+});
+
+describe("buildTaskPrompt", () => {
+  it("includes mission + goal + task context", () => {
+    saveMission(tmpDir, {
+      title: "Build auth",
+      description: "Before Q2 audit",
+      status: "active",
+      branch: null,
+      milestones: [],
+      created: "2026-01-01T00:00:00Z",
+      updated: "2026-01-01T00:00:00Z",
+    });
+    saveGoal(tmpDir, {
+      id: "01",
+      title: "Token storage",
+      description: "",
+      status: "in-progress",
+      acceptance: "All tokens encrypted",
+      priority: 1,
+      created: "2026-01-01T00:00:00Z",
+      updated: "2026-01-01T00:00:00Z",
+      assignee: null,
+      specialty: null,
+      milestone: null,
+    });
+
+    const task = makeTask({
+      title: "Fix middleware",
+      goal: "01",
+      tags: ["security"],
+      priority: 1,
+    });
+
+    const prompt = buildTaskPrompt(tmpDir, task);
+
+    expect(prompt.includes("Mission: Build auth")).toBeTruthy();
+    expect(prompt.includes("Goal: Token storage")).toBeTruthy();
+    expect(prompt.includes("Acceptance: All tokens encrypted")).toBeTruthy();
+    expect(prompt.includes("Your Task: Fix middleware")).toBeTruthy();
+    expect(prompt.includes("Priority: P1")).toBeTruthy();
+    expect(prompt.includes("Tags: security")).toBeTruthy();
+    expect(prompt.includes(`Workspace: ${tmpDir}`)).toBeTruthy();
+    expect(prompt.includes("tmux-ide task done 001")).toBeTruthy();
+  });
+
+  it("works without mission or goal", () => {
+    const task = makeTask({ title: "Standalone task" });
+    const prompt = buildTaskPrompt(tmpDir, task);
+    expect(prompt.includes("Your Task: Standalone task")).toBeTruthy();
+    expect(!prompt.includes("Mission:")).toBeTruthy();
+    expect(!prompt.includes("Goal:")).toBeTruthy();
+  });
+});
+
+describe("runHook", () => {
+  it("returns ok:true for successful command", () => {
+    const result = runHook("true", tmpDir);
+    expect(result).toEqual({ ok: true });
+  });
+
+  it("returns ok:false with error for failing command", () => {
+    const result = runHook("false", tmpDir);
+    expect(result.ok).toBe(false);
+    expect("error" in result && result.error.length > 0).toBeTruthy();
+  });
+
+  it("runs command in the specified cwd", () => {
+    // Create a marker file, then check it exists via the hook
+    writeFileSync(join(tmpDir, "marker.txt"), "hello");
+    const result = runHook("test -f marker.txt", tmpDir);
+    expect(result).toEqual({ ok: true });
+  });
+
+  it("fails when cwd does not contain expected file", () => {
+    const result = runHook("test -f nonexistent.txt", tmpDir);
+    expect(result.ok).toBe(false);
+  });
+});
+
+describe("dispatch with hooks", () => {
+  it("skips task when before_run fails", () => {
+    const task = makeTask();
+    saveTask(tmpDir, task);
+
+    const panes: PaneInfo[] = [makePane({ id: "%1", title: "Agent 1", currentCommand: "zsh" })];
+    mockPanes = panes;
+
+    // before_run that always fails
+    const config = makeOrchestratorConfig(tmpDir, { beforeRun: "false" });
+    const state = makeOrchestratorState();
+
+    dispatch(config, state, [task], panes);
+
+    // Task should NOT be assigned
+    const loaded = loadTask(tmpDir, "001");
+    expect(loaded?.assignee).toBe(null);
+    expect(loaded?.status).toBe("todo");
+  });
+
+  it("dispatches task when before_run succeeds", () => {
+    const task = makeTask();
+    saveTask(tmpDir, task);
+
+    const pane = makePane({ id: "%1", index: 0, title: "Agent 1", currentCommand: "zsh" });
+    const expectedName = agentIdentifier(pane);
+    const panes: PaneInfo[] = [pane];
+    mockPanes = panes;
+
+    // before_run that always succeeds
+    const config = makeOrchestratorConfig(tmpDir, { beforeRun: "true" });
+    const state = makeOrchestratorState();
+
+    dispatch(config, state, [task], panes);
+
+    const loaded = loadTask(tmpDir, "001");
+    expect(loaded?.assignee).toBe(expectedName);
+    expect(loaded?.status).toBe("in-progress");
+  });
+});
+
+describe("detectCompletions with after_run", () => {
+  it("runs after_run hook when task completes", () => {
+    const task = makeTask({
+      status: "done",
+      assignee: "Agent 1",
+    });
+
+    const panes: PaneInfo[] = [makePane({ id: "%0", title: "Master" })];
+
+    // after_run creates a marker file — proves it ran in the project dir
+    const config = makeOrchestratorConfig(tmpDir, { afterRun: "touch after_run_marker" });
+    const state = makeOrchestratorState({
+      previousTasks: new Map([["001", "in-progress"]]),
+    });
+
+    detectCompletions(config, state, [task], panes);
+
+    expect(existsSync(join(tmpDir, "after_run_marker"))).toBeTruthy();
+  });
+
+  it("does not crash when after_run fails", () => {
+    const task = makeTask({
+      status: "done",
+      assignee: "Agent 1",
+    });
+
+    const panes: PaneInfo[] = [makePane({ id: "%0", title: "Master" })];
+
+    // after_run that fails — should not throw
+    const config = makeOrchestratorConfig(tmpDir, { afterRun: "false" });
+    const state = makeOrchestratorState({
+      previousTasks: new Map([["001", "in-progress"]]),
+    });
+
+    // Should not throw
+    detectCompletions(config, state, [task], panes);
+
+    // Master should still get notified despite hook failure
+    const sendCalls = tmuxCalls.filter(
+      (c) => c.args.includes("send-keys") && c.args.includes("%0"),
+    );
+    expect(sendCalls.length > 0).toBeTruthy();
+  });
+});
+
+describe("isAgentPane", () => {
+  it("detects claude command", () => {
+    expect(isAgentPane(makePane({ currentCommand: "claude" }))).toBeTruthy();
+  });
+
+  it("detects codex command", () => {
+    expect(isAgentPane(makePane({ currentCommand: "codex" }))).toBeTruthy();
+  });
+
+  it("detects Claude Code via version string + title", () => {
+    expect(isAgentPane(makePane({ currentCommand: "2.1.80", title: "Claude Code" }))).toBeTruthy();
+  });
+
+  it("detects Claude Code via title pattern", () => {
+    expect(isAgentPane(makePane({ currentCommand: "node", title: "Claude Code" }))).toBeTruthy();
+  });
+
+  it("does not match a plain shell", () => {
+    expect(!isAgentPane(makePane({ currentCommand: "zsh", title: "Shell" }))).toBeTruthy();
+  });
+
+  it("matches version string regardless of title (Claude Code reports version as command)", () => {
+    expect(isAgentPane(makePane({ currentCommand: "2.1.80", title: "Dev Server" }))).toBeTruthy();
+  });
+});
+
+describe("isAgentBusy", () => {
+  it("returns true when spinner in title", () => {
+    expect(isAgentBusy(makePane({ title: "⠙ Working..." }))).toBeTruthy();
+  });
+
+  it("returns false for normal title", () => {
+    expect(!isAgentBusy(makePane({ title: "Claude Code" }))).toBeTruthy();
+  });
+});
+
+describe("isIdleForDispatch", () => {
+  it("returns true for shell command", () => {
+    expect(isIdleForDispatch(makePane({ currentCommand: "zsh" }))).toBeTruthy();
+    expect(isIdleForDispatch(makePane({ currentCommand: "bash" }))).toBeTruthy();
+    expect(isIdleForDispatch(makePane({ currentCommand: "fish" }))).toBeTruthy();
+  });
+
+  it("returns true for agent pane without spinner", () => {
+    expect(
+      isIdleForDispatch(makePane({ currentCommand: "claude", title: "Agent 1" })),
+    ).toBeTruthy();
+  });
+
+  it("returns true for Claude with version command and no spinner", () => {
+    expect(
+      isIdleForDispatch(makePane({ currentCommand: "2.1.80", title: "Claude Code" })),
+    ).toBeTruthy();
+  });
+
+  it("returns false for agent pane with spinner", () => {
+    expect(
+      !isIdleForDispatch(makePane({ currentCommand: "claude", title: "⠹ Thinking..." })),
+    ).toBeTruthy();
+  });
+
+  it("returns false for non-agent non-shell command", () => {
+    expect(!isIdleForDispatch(makePane({ currentCommand: "vim", title: "Editor" }))).toBeTruthy();
+  });
+});
+
+describe("claim locking", () => {
+  it("prevents double-dispatch of same task across two calls", () => {
+    const task = makeTask();
+    saveTask(tmpDir, task);
+
+    const panes: PaneInfo[] = [
+      makePane({ id: "%1", title: "Agent 1", currentCommand: "zsh" }),
+      makePane({ id: "%2", title: "Agent 2", currentCommand: "zsh" }),
+    ];
+    mockPanes = panes;
+
+    const config = makeOrchestratorConfig(tmpDir);
+    const state = makeOrchestratorState();
+
+    // First dispatch claims the task
+    dispatch(config, state, [task], panes);
+    expect(state.claimedTasks.has("001")).toBeTruthy();
+
+    // Reset task to todo to simulate a race (file not yet updated)
+    const raceTask = makeTask({ status: "todo", assignee: null });
+
+    // Second dispatch should skip claimed task
+    dispatch(config, state, [raceTask], panes);
+
+    // Only one send-keys call with the task prompt (not two)
+    const sendCalls = tmuxCalls.filter((c) => c.args.includes("send-keys"));
+    // First dispatch: send-keys text + send-keys Enter = 2 calls
+    expect(sendCalls.length).toBe(2);
+  });
+
+  it("clears claim on task completion", () => {
+    const config = makeOrchestratorConfig(tmpDir);
+    const state = makeOrchestratorState({
+      previousTasks: new Map([["001", "in-progress"]]),
+      claimedTasks: new Set(["001"]),
+    });
+
+    const task = makeTask({
+      status: "done",
+      assignee: "Agent 1",
+    });
+
+    const panes: PaneInfo[] = [makePane({ id: "%0", title: "Master" })];
+
+    detectCompletions(config, state, [task], panes);
+
+    expect(!state.claimedTasks.has("001")).toBeTruthy();
+  });
+
+  it("releases claim when before_run hook fails", () => {
+    const task = makeTask();
+    saveTask(tmpDir, task);
+
+    const panes: PaneInfo[] = [makePane({ id: "%1", title: "Agent 1", currentCommand: "zsh" })];
+    mockPanes = panes;
+
+    const config = makeOrchestratorConfig(tmpDir, { beforeRun: "false" });
+    const state = makeOrchestratorState();
+
+    dispatch(config, state, [task], panes);
+
+    // Claim should be released so the task can be retried
+    expect(!state.claimedTasks.has("001")).toBeTruthy();
+  });
+});
+
+describe("createOrchestrator timer", () => {
+  it("auto-assigns a task within poll interval", async () => {
+    const task = makeTask();
+    saveTask(tmpDir, task);
+
+    const pane = makePane({ id: "%1", index: 0, title: "Agent 1", currentCommand: "zsh" });
+    const expectedName = agentIdentifier(pane);
+    mockPanes = [pane];
+
+    const config = makeOrchestratorConfig(tmpDir, { pollInterval: 50, masterPane: null });
+
+    const stop = createOrchestrator(config);
+
+    // Wait for a few ticks
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    stop();
+
+    const loaded = loadTask(tmpDir, "001");
+    expect(loaded?.status).toBe("in-progress");
+    expect(loaded?.assignee).toBe(expectedName);
+  });
+
+  it("stops polling when returned function is called", async () => {
+    mockPanes = [];
+
+    const config = makeOrchestratorConfig(tmpDir, { pollInterval: 50 });
+
+    const stop = createOrchestrator(config);
+    stop();
+
+    // Create a task after stopping — it should not be assigned
+    const task = makeTask();
+    saveTask(tmpDir, task);
+
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    const loaded = loadTask(tmpDir, "001");
+    expect(loaded?.status).toBe("todo");
+    expect(loaded?.assignee).toBe(null);
+  });
+});
+
+describe("dispatch with version-string agent", () => {
+  it("assigns task to agent reporting version string as command", () => {
+    const task = makeTask();
+    saveTask(tmpDir, task);
+
+    // Simulate Claude Code showing version as command
+    const pane = makePane({ id: "%1", index: 0, title: "Claude Code", currentCommand: "2.1.80" });
+    const expectedName = agentIdentifier(pane);
+    const panes: PaneInfo[] = [pane];
+    mockPanes = panes;
+
+    const config = makeOrchestratorConfig(tmpDir, { masterPane: null });
+    const state = makeOrchestratorState();
+
+    dispatch(config, state, [task], panes);
+
+    const loaded = loadTask(tmpDir, "001");
+    expect(loaded?.assignee).toBe(expectedName);
+    expect(loaded?.status).toBe("in-progress");
+  });
+
+  it("does not assign to busy agent with spinner", () => {
+    const task = makeTask();
+    saveTask(tmpDir, task);
+
+    const panes: PaneInfo[] = [
+      makePane({ id: "%1", title: "⠙ Thinking...", currentCommand: "2.1.80" }),
+    ];
+    mockPanes = panes;
+
+    const config = makeOrchestratorConfig(tmpDir, { masterPane: null });
+    const state = makeOrchestratorState();
+
+    dispatch(config, state, [task], panes);
+
+    const loaded = loadTask(tmpDir, "001");
+    expect(loaded?.assignee).toBe(null);
+    expect(loaded?.status).toBe("todo");
+  });
+});
+
+describe("reloadConfig", () => {
+  it("updates pollInterval", () => {
+    const config = makeOrchestratorConfig(tmpDir, { pollInterval: 5000 });
+    reloadConfig(config, { pollInterval: 1000 });
+    expect(config.pollInterval).toBe(1000);
+  });
+
+  it("updates stallTimeout", () => {
+    const config = makeOrchestratorConfig(tmpDir, { stallTimeout: 300000 });
+    reloadConfig(config, { stallTimeout: 60000 });
+    expect(config.stallTimeout).toBe(60000);
+  });
+
+  it("updates maxConcurrentAgents", () => {
+    const config = makeOrchestratorConfig(tmpDir);
+    reloadConfig(config, { maxConcurrentAgents: 3 });
+    expect(config.maxConcurrentAgents).toBe(3);
+  });
+
+  it("updates multiple fields at once", () => {
+    const config = makeOrchestratorConfig(tmpDir);
+    reloadConfig(config, {
+      pollInterval: 2000,
+      stallTimeout: 120000,
+      autoDispatch: false,
+    });
+    expect(config.pollInterval).toBe(2000);
+    expect(config.stallTimeout).toBe(120000);
+    expect(config.autoDispatch).toBe(false);
+  });
+
+  it("preserves fields not in the patch", () => {
+    const config = makeOrchestratorConfig(tmpDir, { pollInterval: 5000, stallTimeout: 300000 });
+    reloadConfig(config, { pollInterval: 1000 });
+    expect(config.stallTimeout).toBe(300000); // unchanged
+    expect(config.session).toBe("test"); // unchanged
+  });
+});
+
+describe("event logging integration", () => {
+  it("logs dispatch events", () => {
+    const task = makeTask();
+    saveTask(tmpDir, task);
+
+    const pane = makePane({ id: "%1", index: 0, title: "Agent 1", currentCommand: "zsh" });
+    const panes: PaneInfo[] = [pane];
+    mockPanes = panes;
+
+    const config = makeOrchestratorConfig(tmpDir, { masterPane: null });
+    const state = makeOrchestratorState();
+
+    dispatch(config, state, [task], panes);
+
+    const events = readEvents(tmpDir);
+    const dispatchEvent = events.find((e) => e.type === "dispatch");
+    expect(dispatchEvent).toBeTruthy();
+    expect(dispatchEvent!.taskId).toBe("001");
+    expect(dispatchEvent!.agent).toBe(pane.title);
+    expect(dispatchEvent!.message.includes("Test task")).toBeTruthy();
+  });
+
+  it("logs stall events", () => {
+    const pane = makePane({ id: "%1", index: 0, title: "Agent 1" });
+    const name = agentIdentifier(pane);
+    const task = makeTask({ status: "in-progress", assignee: name });
+    const panes: PaneInfo[] = [pane];
+
+    const config = makeOrchestratorConfig(tmpDir, { stallTimeout: 1000 });
+    const state = makeOrchestratorState({
+      lastActivity: new Map([["%1", Date.now() - 2000]]),
+    });
+
+    detectStalls(config, state, [task], panes);
+
+    const events = readEvents(tmpDir);
+    const stallEvent = events.find((e) => e.type === "stall");
+    expect(stallEvent).toBeTruthy();
+    expect(stallEvent!.taskId).toBe("001");
+    expect(stallEvent!.agent).toBe(name);
+  });
+
+  it("logs completion events", () => {
+    const task = makeTask({
+      status: "done",
+      assignee: "Agent 1",
+    });
+    const panes: PaneInfo[] = [makePane({ id: "%0", title: "Master" })];
+
+    const config = makeOrchestratorConfig(tmpDir);
+    const state = makeOrchestratorState({
+      previousTasks: new Map([["001", "in-progress"]]),
+    });
+
+    detectCompletions(config, state, [task], panes);
+
+    const events = readEvents(tmpDir);
+    const completionEvent = events.find((e) => e.type === "completion");
+    expect(completionEvent).toBeTruthy();
+    expect(completionEvent!.taskId).toBe("001");
+    expect(completionEvent!.agent).toBe("Agent 1");
+  });
+
+  it("logs reconcile events when agent vanishes", () => {
+    const task = makeTask({ status: "in-progress", assignee: "Agent 1" });
+    saveTask(tmpDir, task);
+
+    // No panes — agent has vanished
+    const panes: PaneInfo[] = [];
+
+    const config = makeOrchestratorConfig(tmpDir);
+    const state = makeOrchestratorState();
+
+    reconcile(config, state, [task], panes);
+
+    const events = readEvents(tmpDir);
+    const reconcileEvent = events.find((e) => e.type === "reconcile");
+    expect(reconcileEvent).toBeTruthy();
+    expect(reconcileEvent!.taskId).toBe("001");
+    expect(reconcileEvent!.agent).toBe("Agent 1");
+    expect(reconcileEvent!.message.includes("vanished")).toBeTruthy();
+  });
+});
+
+describe("saveOrchestratorState / loadOrchestratorState", () => {
+  it("round-trips claimed tasks and claim times", () => {
+    const state = makeOrchestratorState({
+      claimedTasks: new Set(["001", "003"]),
+      taskClaimTimes: new Map([
+        ["001", 1700000000000],
+        ["003", 1700000060000],
+      ]),
+    });
+
+    saveOrchestratorState(tmpDir, state);
+
+    const restored = makeOrchestratorState();
+    loadOrchestratorState(tmpDir, restored);
+
+    expect(restored.claimedTasks.has("001")).toBeTruthy();
+    expect(restored.claimedTasks.has("003")).toBeTruthy();
+    expect(restored.taskClaimTimes.get("001")).toBe(1700000000000);
+    expect(restored.taskClaimTimes.get("003")).toBe(1700000060000);
+  });
+
+  it("handles missing state file gracefully", () => {
+    const state = makeOrchestratorState();
+    loadOrchestratorState(tmpDir, state);
+    expect(state.claimedTasks.size).toBe(0);
+    expect(state.taskClaimTimes.size).toBe(0);
+  });
+
+  it("handles corrupted state file gracefully", () => {
+    mkdirSync(join(tmpDir, ".tasks"), { recursive: true });
+    writeFileSync(join(tmpDir, ".tasks", "orchestrator-state.json"), "not json");
+
+    const state = makeOrchestratorState();
+    loadOrchestratorState(tmpDir, state);
+    expect(state.claimedTasks.size).toBe(0);
+  });
+});
+
+describe("syncClaims", () => {
+  it("removes stale claims for tasks no longer in-progress", () => {
+    saveTask(tmpDir, makeTask({ id: "001", status: "done", assignee: "Agent 1" }));
+    saveTask(tmpDir, makeTask({ id: "002", status: "todo" }));
+    saveTask(tmpDir, makeTask({ id: "003", status: "in-progress", assignee: "Agent 2" }));
+
+    const state = makeOrchestratorState({
+      claimedTasks: new Set(["001", "002", "003"]),
+    });
+
+    syncClaims(tmpDir, state);
+
+    expect(!state.claimedTasks.has("001")).toBeTruthy();
+    expect(!state.claimedTasks.has("002")).toBeTruthy();
+    expect(state.claimedTasks.has("003")).toBeTruthy();
+  });
+
+  it("adds missing claims for in-progress tasks", () => {
+    saveTask(tmpDir, makeTask({ id: "001", status: "in-progress", assignee: "Agent 1" }));
+    saveTask(tmpDir, makeTask({ id: "002", status: "in-progress", assignee: "Agent 2" }));
+
+    const state = makeOrchestratorState({
+      claimedTasks: new Set(),
+    });
+
+    syncClaims(tmpDir, state);
+
+    expect(state.claimedTasks.has("001")).toBeTruthy();
+    expect(state.claimedTasks.has("002")).toBeTruthy();
+  });
+
+  it("rebuilds claims from mixed task statuses", () => {
+    saveTask(tmpDir, makeTask({ id: "001", status: "done", assignee: "Agent 1" }));
+    saveTask(tmpDir, makeTask({ id: "002", status: "in-progress", assignee: "Agent 2" }));
+    saveTask(tmpDir, makeTask({ id: "003", status: "todo" }));
+    saveTask(tmpDir, makeTask({ id: "004", status: "in-progress", assignee: "Agent 3" }));
+    saveTask(tmpDir, makeTask({ id: "005", status: "review", assignee: "Agent 1" }));
+
+    // Stale state: claims 001 (done) and 003 (todo), missing 004 (in-progress)
+    const state = makeOrchestratorState({
+      claimedTasks: new Set(["001", "003"]),
+    });
+
+    syncClaims(tmpDir, state);
+
+    expect(state.claimedTasks.size).toBe(2);
+    expect(state.claimedTasks.has("002")).toBeTruthy();
+    expect(state.claimedTasks.has("004")).toBeTruthy();
+    expect(!state.claimedTasks.has("001")).toBeTruthy();
+    expect(!state.claimedTasks.has("003")).toBeTruthy();
+    expect(!state.claimedTasks.has("005")).toBeTruthy();
+  });
+
+  it("handles empty task store", () => {
+    const state = makeOrchestratorState({
+      claimedTasks: new Set(["001", "002"]),
+    });
+
+    syncClaims(tmpDir, state);
+
+    expect(state.claimedTasks.size).toBe(0);
+  });
+});
+
+describe("gracefulShutdown", () => {
+  it("releases in-progress tasks back to todo", () => {
+    const task = makeTask({
+      status: "in-progress",
+      assignee: "Agent 1",
+    });
+    saveTask(tmpDir, task);
+
+    const config = makeOrchestratorConfig(tmpDir);
+    const state = makeOrchestratorState({
+      claimedTasks: new Set(["001"]),
+    });
+
+    gracefulShutdown(config, state);
+
+    const loaded = loadTask(tmpDir, "001")!;
+    expect(loaded.status).toBe("todo");
+    expect(loaded.assignee).toBe(null);
+  });
+
+  it("saves orchestrator state to disk", () => {
+    saveTask(tmpDir, makeTask());
+
+    const config = makeOrchestratorConfig(tmpDir);
+    const state = makeOrchestratorState({
+      claimedTasks: new Set(["002"]),
+      taskClaimTimes: new Map([["002", Date.now()]]),
+    });
+
+    gracefulShutdown(config, state);
+
+    expect(existsSync(join(tmpDir, ".tasks", "orchestrator-state.json"))).toBeTruthy();
+
+    const restored = makeOrchestratorState();
+    loadOrchestratorState(tmpDir, restored);
+    expect(restored.claimedTasks.has("002")).toBeTruthy();
+  });
+
+  it("leaves done and todo tasks untouched", () => {
+    const done = makeTask({ id: "001", status: "done", assignee: "Agent 1" });
+    const todo = makeTask({ id: "002", status: "todo", assignee: null });
+    saveTask(tmpDir, done);
+    saveTask(tmpDir, todo);
+
+    const config = makeOrchestratorConfig(tmpDir);
+    const state = makeOrchestratorState();
+
+    gracefulShutdown(config, state);
+
+    expect(loadTask(tmpDir, "001")!.status).toBe("done");
+    expect(loadTask(tmpDir, "002")!.status).toBe("todo");
+  });
+});
+
+describe("normalizePaneTitle", () => {
+  it("strips spinner prefix from pane title", () => {
+    expect(normalizePaneTitle("⠂ Claude Code")).toBe("Claude Code");
+    expect(normalizePaneTitle("⠋ Working...")).toBe("Working...");
+    expect(normalizePaneTitle("✳ Claude Code")).toBe("Claude Code");
+    expect(normalizePaneTitle("◐ Thinking")).toBe("Thinking");
+  });
+
+  it("returns title unchanged when no spinner prefix", () => {
+    expect(normalizePaneTitle("Agent 1")).toBe("Agent 1");
+    expect(normalizePaneTitle("Claude Code")).toBe("Claude Code");
+  });
+
+  it("handles empty string", () => {
+    expect(normalizePaneTitle("")).toBe("");
+  });
+});
+
+describe("getPaneSpecialties", () => {
+  it("returns specialties from config map", () => {
+    const config = makeOrchestratorConfig(tmpDir, {
+      paneSpecialties: new Map([["Frontend Agent", ["frontend", "css", "react"]]]),
+    });
+    const pane = makePane({ title: "Frontend Agent" });
+    const specs = getPaneSpecialties(config, pane);
+    expect(specs).toEqual(["frontend", "css", "react"]);
+  });
+
+  it("returns empty array for pane with no specialties", () => {
+    const config = makeOrchestratorConfig(tmpDir, { paneSpecialties: new Map() });
+    const pane = makePane({ title: "Generic Agent" });
+    const specs = getPaneSpecialties(config, pane);
+    expect(specs).toEqual([]);
+  });
+
+  it("matches by pane title", () => {
+    const config = makeOrchestratorConfig(tmpDir, {
+      paneSpecialties: new Map([
+        ["Backend", ["api", "database"]],
+        ["Frontend", ["ui", "css"]],
+      ]),
+    });
+    expect(getPaneSpecialties(config, makePane({ title: "Backend" }))).toEqual(["api", "database"]);
+    expect(getPaneSpecialties(config, makePane({ title: "Frontend" }))).toEqual(["ui", "css"]);
+    expect(getPaneSpecialties(config, makePane({ title: "Other" }))).toEqual([]);
+  });
+});
+
+describe("buildGoalPrompt", () => {
+  it("includes goal title, acceptance criteria, and planner name", () => {
+    saveMission(tmpDir, {
+      title: "Ship v2",
+      description: "Major release",
+      status: "active",
+      branch: null,
+      milestones: [],
+      created: "2026-01-01T00:00:00Z",
+      updated: "2026-01-01T00:00:00Z",
+    });
+
+    const goal: Goal = {
+      id: "01",
+      title: "Build REST API",
+      description: "Create CRUD endpoints",
+      status: "todo",
+      acceptance: "All endpoints return 200 with correct data",
+      priority: 1,
+      created: "2026-01-01T00:00:00Z",
+      updated: "2026-01-01T00:00:00Z",
+      assignee: null,
+      specialty: "backend",
+    };
+
+    const planner = makePane({ id: "%2", index: 1, title: "Backend Planner" });
+    const prompt = buildGoalPrompt(tmpDir, goal, planner);
+
+    expect(prompt.includes("Build REST API")).toBeTruthy();
+    expect(prompt.includes("All endpoints return 200 with correct data")).toBeTruthy();
+    expect(prompt.includes("backend planner")).toBeTruthy();
+    expect(prompt.includes("Ship v2")).toBeTruthy();
+    expect(prompt.includes(agentIdentifier(planner))).toBeTruthy();
+  });
+
+  it("works without mission", () => {
+    const goal: Goal = {
+      id: "01",
+      title: "Setup CI",
+      description: "",
+      status: "todo",
+      acceptance: "CI passes",
+      priority: 1,
+      created: "2026-01-01T00:00:00Z",
+      updated: "2026-01-01T00:00:00Z",
+      assignee: null,
+      specialty: null,
+      milestone: null,
+    };
+
+    const planner = makePane({ id: "%1", index: 0 });
+    const prompt = buildGoalPrompt(tmpDir, goal, planner);
+
+    expect(prompt.includes("Setup CI")).toBeTruthy();
+    expect(prompt.includes("general planner")).toBeTruthy();
+    expect(!prompt.includes("Mission:")).toBeTruthy();
+  });
+});
+
+describe("dispatchGoals", () => {
+  it("assigns goal to idle planner pane", () => {
+    const goal: Goal = {
+      id: "01",
+      title: "Build Frontend",
+      description: "React components",
+      status: "todo",
+      acceptance: "UI renders",
+      priority: 1,
+      created: "2026-01-01T00:00:00Z",
+      updated: "2026-01-01T00:00:00Z",
+      assignee: null,
+      specialty: null,
+      milestone: null,
+    };
+    saveGoal(tmpDir, goal);
+
+    const planner = makePane({ id: "%2", index: 1, title: "Planner", currentCommand: "claude" });
+    const config = makeOrchestratorConfig(tmpDir, {
+      paneSpecialties: new Map([["Planner", ["frontend"]]]),
+    });
+    const state = makeOrchestratorState();
+
+    dispatchGoals(config, state, [goal], [], [planner]);
+
+    const updated = loadGoal(tmpDir, "01")!;
+    expect(updated.status).toBe("in-progress");
+    expect(updated.assignee).toBe(agentIdentifier(planner));
+
+    const events = readEvents(tmpDir);
+    expect(events.length).toBe(1);
+    expect(events[0]!.type).toBe("dispatch");
+    expect(events[0]!.message.includes("Build Frontend")).toBeTruthy();
+  });
+
+  it("skips master pane", () => {
+    const goal: Goal = {
+      id: "01",
+      title: "Test Goal",
+      description: "",
+      status: "todo",
+      acceptance: "",
+      priority: 1,
+      created: "2026-01-01T00:00:00Z",
+      updated: "2026-01-01T00:00:00Z",
+      assignee: null,
+      specialty: null,
+      milestone: null,
+    };
+    saveGoal(tmpDir, goal);
+
+    // Only pane is the master — should not be used as planner
+    const masterPane = makePane({
+      id: "%1",
+      index: 0,
+      title: "Master",
+      currentCommand: "claude",
+      role: "lead",
+    });
+    const config = makeOrchestratorConfig(tmpDir, { masterPane: "Master" });
+    const state = makeOrchestratorState();
+
+    dispatchGoals(config, state, [goal], [], [masterPane]);
+
+    const unchanged = loadGoal(tmpDir, "01")!;
+    expect(unchanged.status).toBe("todo");
+    expect(unchanged.assignee).toBe(null);
+  });
+
+  it("does not assign already-assigned goals", () => {
+    const goal: Goal = {
+      id: "01",
+      title: "Already assigned",
+      description: "",
+      status: "todo",
+      acceptance: "",
+      priority: 1,
+      created: "2026-01-01T00:00:00Z",
+      updated: "2026-01-01T00:00:00Z",
+      assignee: "Someone",
+      specialty: null,
+      milestone: null,
+    };
+    saveGoal(tmpDir, goal);
+
+    const planner = makePane({ id: "%2", index: 1, title: "Planner", currentCommand: "claude" });
+    const config = makeOrchestratorConfig(tmpDir, {
+      paneSpecialties: new Map([["Planner", []]]),
+    });
+    const state = makeOrchestratorState();
+
+    dispatchGoals(config, state, [goal], [], [planner]);
+
+    // Goal should remain unchanged — assignee filter excludes it
+    const events = readEvents(tmpDir);
+    expect(events.length).toBe(0);
+  });
+});
+
+describe("findBestAgent", () => {
+  it("returns first agent when task has no specialty", () => {
+    const agents = [
+      makePane({ id: "%1", title: "Agent A", currentCommand: "zsh" }),
+      makePane({ id: "%2", title: "Agent B", currentCommand: "zsh" }),
+    ];
+    const config = makeOrchestratorConfig(tmpDir, {
+      paneSpecialties: new Map([["Agent A", ["frontend"]]]),
+    });
+    const task = makeTask({ specialty: null });
+    const result = findBestAgent(config, agents, task, new Set());
+    expect(result?.id).toBe("%1");
+  });
+
+  it("prefers specialist agent for matching specialty", () => {
+    const agents = [
+      makePane({ id: "%1", title: "Generalist", currentCommand: "zsh" }),
+      makePane({ id: "%2", title: "Frontend", currentCommand: "zsh" }),
+    ];
+    const config = makeOrchestratorConfig(tmpDir, {
+      paneSpecialties: new Map([["Frontend", ["frontend", "css"]]]),
+    });
+    const task = makeTask({ specialty: "frontend" });
+    const result = findBestAgent(config, agents, task, new Set());
+    expect(result?.id).toBe("%2");
+  });
+
+  it("falls back to generalist when no specialist matches", () => {
+    const agents = [
+      makePane({ id: "%1", title: "Generalist", currentCommand: "zsh" }),
+      makePane({ id: "%2", title: "Backend", currentCommand: "zsh" }),
+    ];
+    const config = makeOrchestratorConfig(tmpDir, {
+      paneSpecialties: new Map([["Backend", ["api", "database"]]]),
+    });
+    const task = makeTask({ specialty: "frontend" });
+    const result = findBestAgent(config, agents, task, new Set());
+    // Generalist has no specialties → takes anything
+    expect(result?.id).toBe("%1");
+  });
+
+  it("returns null when no suitable agent (all are wrong specialists)", () => {
+    const agents = [
+      makePane({ id: "%1", title: "Backend", currentCommand: "zsh" }),
+      makePane({ id: "%2", title: "DevOps", currentCommand: "zsh" }),
+    ];
+    const config = makeOrchestratorConfig(tmpDir, {
+      paneSpecialties: new Map([
+        ["Backend", ["api", "database"]],
+        ["DevOps", ["infra", "ci"]],
+      ]),
+    });
+    const task = makeTask({ specialty: "frontend" });
+    const result = findBestAgent(config, agents, task, new Set());
+    expect(result).toBeNull();
+  });
+
+  it("excludes agents in excludeIds set", () => {
+    const agents = [
+      makePane({ id: "%1", title: "Agent A", currentCommand: "zsh" }),
+      makePane({ id: "%2", title: "Agent B", currentCommand: "zsh" }),
+    ];
+    const config = makeOrchestratorConfig(tmpDir);
+    const task = makeTask({ specialty: null });
+    const result = findBestAgent(config, agents, task, new Set(["%1"]));
+    expect(result?.id).toBe("%2");
+  });
+});
+
+describe("skill-based dispatch integration", () => {
+  it("dispatches task with specialty to matching specialist agent", () => {
+    const task = makeTask({ id: "001", specialty: "frontend" });
+    saveTask(tmpDir, task);
+
+    const generalist = makePane({ id: "%1", index: 0, title: "Generalist", currentCommand: "zsh" });
+    const specialist = makePane({ id: "%2", index: 1, title: "Frontend", currentCommand: "zsh" });
+    const panes = [generalist, specialist];
+    mockPanes = panes;
+
+    const config = makeOrchestratorConfig(tmpDir, {
+      masterPane: null,
+      paneSpecialties: new Map([["Frontend", ["frontend", "css"]]]),
+    });
+    const state = makeOrchestratorState();
+
+    dispatch(config, state, [task], panes);
+
+    const loaded = loadTask(tmpDir, "001");
+    expect(loaded?.assignee).toBe(agentIdentifier(specialist));
+    expect(loaded?.status).toBe("in-progress");
+  });
+
+  it("dispatches task with no specialty to any idle agent", () => {
+    const task = makeTask({ id: "001", specialty: null });
+    saveTask(tmpDir, task);
+
+    const pane = makePane({ id: "%1", index: 0, title: "Agent 1", currentCommand: "zsh" });
+    const panes = [pane];
+    mockPanes = panes;
+
+    const config = makeOrchestratorConfig(tmpDir, {
+      masterPane: null,
+      paneSpecialties: new Map([["Agent 1", ["backend"]]]),
+    });
+    const state = makeOrchestratorState();
+
+    dispatch(config, state, [task], panes);
+
+    const loaded = loadTask(tmpDir, "001");
+    expect(loaded?.assignee).toBe(agentIdentifier(pane));
+    expect(loaded?.status).toBe("in-progress");
+  });
+
+  it("skips specialist task when no matching agent available", () => {
+    const task = makeTask({ id: "001", specialty: "frontend" });
+    saveTask(tmpDir, task);
+
+    // Only agent is a backend specialist — not a match and not a generalist
+    const panes = [makePane({ id: "%1", index: 0, title: "Backend", currentCommand: "zsh" })];
+    mockPanes = panes;
+
+    const config = makeOrchestratorConfig(tmpDir, {
+      masterPane: null,
+      paneSpecialties: new Map([["Backend", ["api", "database"]]]),
+    });
+    const state = makeOrchestratorState();
+
+    dispatch(config, state, [task], panes);
+
+    const loaded = loadTask(tmpDir, "001");
+    expect(loaded?.assignee).toBe(null);
+    expect(loaded?.status).toBe("todo");
+  });
+});
+
+describe("buildTaskPrompt with skill injection", () => {
+  it("includes skill body when task has specialty and skill file exists", () => {
+    // Create skill file
+    const skillsDir = join(tmpDir, ".tmux-ide", "skills");
+    mkdirSync(skillsDir, { recursive: true });
+    writeFileSync(
+      join(skillsDir, "frontend.md"),
+      `---
+name: frontend
+specialties: [frontend, css]
+role: teammate
+description: Frontend specialist
+---
+You are a frontend expert. Focus on React components and CSS.`,
+    );
+
+    const task = makeTask({ specialty: "frontend" });
+    const prompt = buildTaskPrompt(tmpDir, task);
+
+    expect(prompt.includes("Your Role: frontend")).toBeTruthy();
+    expect(prompt.includes("You are a frontend expert")).toBeTruthy();
+  });
+
+  it("does not include skill section when task has no specialty", () => {
+    const task = makeTask({ specialty: null });
+    const prompt = buildTaskPrompt(tmpDir, task);
+    expect(!prompt.includes("Your Role:")).toBeTruthy();
+  });
+
+  it("does not include skill section when skill file is missing", () => {
+    const task = makeTask({ specialty: "nonexistent" });
+    const prompt = buildTaskPrompt(tmpDir, task);
+    expect(!prompt.includes("Your Role:")).toBeTruthy();
+  });
+});
+
+describe("milestone gating", () => {
+  function setupMission(milestones: Mission["milestones"]): void {
+    saveMission(tmpDir, {
+      title: "Ship v2",
+      description: "",
+      status: "active",
+      branch: null,
+      milestones,
+      created: "2026-01-01T00:00:00Z",
+      updated: "2026-01-01T00:00:00Z",
+    });
+  }
+
+  it("getCurrentMilestone returns first non-done milestone by order", () => {
+    setupMission([
+      {
+        id: "M2",
+        title: "Phase 2",
+        description: "",
+        status: "locked",
+        order: 2,
+        created: "2026-01-01T00:00:00Z",
+        updated: "2026-01-01T00:00:00Z",
+      },
+      {
+        id: "M1",
+        title: "Phase 1",
+        description: "",
+        status: "active",
+        order: 1,
+        created: "2026-01-01T00:00:00Z",
+        updated: "2026-01-01T00:00:00Z",
+      },
+    ]);
+    const current = getCurrentMilestone(tmpDir);
+    expect(current?.id).toBe("M1");
+  });
+
+  it("isMilestoneReady returns true when all predecessors are done", () => {
+    setupMission([
+      {
+        id: "M1",
+        title: "Phase 1",
+        description: "",
+        status: "done",
+        order: 1,
+        created: "2026-01-01T00:00:00Z",
+        updated: "2026-01-01T00:00:00Z",
+      },
+      {
+        id: "M2",
+        title: "Phase 2",
+        description: "",
+        status: "active",
+        order: 2,
+        created: "2026-01-01T00:00:00Z",
+        updated: "2026-01-01T00:00:00Z",
+      },
+    ]);
+    expect(isMilestoneReady(tmpDir, "M2")).toBe(true);
+  });
+
+  it("isMilestoneReady returns false when predecessor is not done", () => {
+    setupMission([
+      {
+        id: "M1",
+        title: "Phase 1",
+        description: "",
+        status: "active",
+        order: 1,
+        created: "2026-01-01T00:00:00Z",
+        updated: "2026-01-01T00:00:00Z",
+      },
+      {
+        id: "M2",
+        title: "Phase 2",
+        description: "",
+        status: "locked",
+        order: 2,
+        created: "2026-01-01T00:00:00Z",
+        updated: "2026-01-01T00:00:00Z",
+      },
+    ]);
+    expect(isMilestoneReady(tmpDir, "M2")).toBe(false);
+  });
+
+  it("dispatches task with active milestone M1", () => {
+    setupMission([
+      {
+        id: "M1",
+        title: "Phase 1",
+        description: "",
+        status: "active",
+        order: 1,
+        created: "2026-01-01T00:00:00Z",
+        updated: "2026-01-01T00:00:00Z",
+      },
+      {
+        id: "M2",
+        title: "Phase 2",
+        description: "",
+        status: "locked",
+        order: 2,
+        created: "2026-01-01T00:00:00Z",
+        updated: "2026-01-01T00:00:00Z",
+      },
+    ]);
+
+    const task = makeTask({ id: "001", milestone: "M1" });
+    saveTask(tmpDir, task);
+
+    const pane = makePane({ id: "%1", index: 0, title: "Agent 1", currentCommand: "zsh" });
+    const panes = [pane];
+    mockPanes = panes;
+
+    const config = makeOrchestratorConfig(tmpDir, { masterPane: null, dispatchMode: "missions" });
+    const state = makeOrchestratorState();
+
+    dispatch(config, state, [task], panes);
+
+    const loaded = loadTask(tmpDir, "001");
+    expect(loaded?.status).toBe("in-progress");
+    expect(loaded?.assignee).toBe(agentIdentifier(pane));
+  });
+
+  it("skips task with locked milestone M2 when M1 is still active", () => {
+    setupMission([
+      {
+        id: "M1",
+        title: "Phase 1",
+        description: "",
+        status: "active",
+        order: 1,
+        created: "2026-01-01T00:00:00Z",
+        updated: "2026-01-01T00:00:00Z",
+      },
+      {
+        id: "M2",
+        title: "Phase 2",
+        description: "",
+        status: "locked",
+        order: 2,
+        created: "2026-01-01T00:00:00Z",
+        updated: "2026-01-01T00:00:00Z",
+      },
+    ]);
+
+    const task = makeTask({ id: "001", milestone: "M2" });
+    saveTask(tmpDir, task);
+
+    const pane = makePane({ id: "%1", index: 0, title: "Agent 1", currentCommand: "zsh" });
+    const panes = [pane];
+    mockPanes = panes;
+
+    const config = makeOrchestratorConfig(tmpDir, { masterPane: null, dispatchMode: "missions" });
+    const state = makeOrchestratorState();
+
+    dispatch(config, state, [task], panes);
+
+    const loaded = loadTask(tmpDir, "001");
+    expect(loaded?.status).toBe("todo");
+    expect(loaded?.assignee).toBe(null);
+  });
+
+  it("tasks without milestone field always dispatch in missions mode", () => {
+    setupMission([
+      {
+        id: "M1",
+        title: "Phase 1",
+        description: "",
+        status: "active",
+        order: 1,
+        created: "2026-01-01T00:00:00Z",
+        updated: "2026-01-01T00:00:00Z",
+      },
+    ]);
+
+    const task = makeTask({ id: "001", milestone: null });
+    saveTask(tmpDir, task);
+
+    const pane = makePane({ id: "%1", index: 0, title: "Agent 1", currentCommand: "zsh" });
+    const panes = [pane];
+    mockPanes = panes;
+
+    const config = makeOrchestratorConfig(tmpDir, { masterPane: null, dispatchMode: "missions" });
+    const state = makeOrchestratorState();
+
+    dispatch(config, state, [task], panes);
+
+    const loaded = loadTask(tmpDir, "001");
+    expect(loaded?.status).toBe("in-progress");
+  });
+
+  it("checkMilestoneCompletion marks M1 done and activates M2 when all M1 tasks complete (no contract)", () => {
+    setupMission([
+      {
+        id: "M1",
+        title: "Phase 1",
+        description: "",
+        status: "active",
+        order: 1,
+        created: "2026-01-01T00:00:00Z",
+        updated: "2026-01-01T00:00:00Z",
+      },
+      {
+        id: "M2",
+        title: "Phase 2",
+        description: "",
+        status: "locked",
+        order: 2,
+        created: "2026-01-01T00:00:00Z",
+        updated: "2026-01-01T00:00:00Z",
+      },
+    ]);
+
+    const task1 = makeTask({ id: "001", milestone: "M1", status: "done", assignee: "Agent 1" });
+    const task2 = makeTask({ id: "002", milestone: "M1", status: "done", assignee: "Agent 2" });
+    saveTask(tmpDir, task1);
+    saveTask(tmpDir, task2);
+
+    const config = makeOrchestratorConfig(tmpDir, { dispatchMode: "missions" });
+    const state = makeOrchestratorState();
+    mockPanes = [];
+    checkMilestoneCompletion(config, state, [task1, task2], []);
+
+    const mission = loadMission(tmpDir)!;
+    const m1 = mission.milestones.find((m) => m.id === "M1")!;
+    const m2 = mission.milestones.find((m) => m.id === "M2")!;
+    expect(m1.status).toBe("done");
+    expect(m2.status).toBe("active");
+
+    // Check event logged
+    const events = readEvents(tmpDir);
+    const milestoneEvent = events.find((e) => e.type === "milestone_complete");
+    expect(milestoneEvent).toBeTruthy();
+    expect(milestoneEvent!.message.includes("Phase 1")).toBeTruthy();
+  });
+
+  it("checkMilestoneCompletion does not advance when tasks are still in progress", () => {
+    setupMission([
+      {
+        id: "M1",
+        title: "Phase 1",
+        description: "",
+        status: "active",
+        order: 1,
+        created: "2026-01-01T00:00:00Z",
+        updated: "2026-01-01T00:00:00Z",
+      },
+      {
+        id: "M2",
+        title: "Phase 2",
+        description: "",
+        status: "locked",
+        order: 2,
+        created: "2026-01-01T00:00:00Z",
+        updated: "2026-01-01T00:00:00Z",
+      },
+    ]);
+
+    const task1 = makeTask({ id: "001", milestone: "M1", status: "done", assignee: "Agent 1" });
+    const task2 = makeTask({
+      id: "002",
+      milestone: "M1",
+      status: "in-progress",
+      assignee: "Agent 2",
+    });
+    saveTask(tmpDir, task1);
+    saveTask(tmpDir, task2);
+
+    const config = makeOrchestratorConfig(tmpDir, { dispatchMode: "missions" });
+    const state = makeOrchestratorState();
+    checkMilestoneCompletion(config, state, [task1, task2], []);
+
+    const mission = loadMission(tmpDir)!;
+    const m1 = mission.milestones.find((m) => m.id === "M1")!;
+    const m2 = mission.milestones.find((m) => m.id === "M2")!;
+    expect(m1.status).toBe("active");
+    expect(m2.status).toBe("locked");
+  });
+});
+
+describe("validation flow", () => {
+  function setupMission(milestones: Mission["milestones"]): void {
+    saveMission(tmpDir, {
+      title: "Ship v2",
+      description: "",
+      status: "active",
+      branch: null,
+      milestones,
+      created: "2026-01-01T00:00:00Z",
+      updated: "2026-01-01T00:00:00Z",
+    });
+  }
+
+  function writeContract(content: string): void {
+    mkdirSync(join(tmpDir, ".tasks"), { recursive: true });
+    writeFileSync(join(tmpDir, ".tasks", "validation-contract.md"), content);
+  }
+
+  it("milestone completion triggers validating state when contract exists", () => {
+    setupMission([
+      {
+        id: "M1",
+        title: "Phase 1",
+        description: "",
+        status: "active",
+        order: 1,
+        created: "2026-01-01T00:00:00Z",
+        updated: "2026-01-01T00:00:00Z",
+      },
+      {
+        id: "M2",
+        title: "Phase 2",
+        description: "",
+        status: "locked",
+        order: 2,
+        created: "2026-01-01T00:00:00Z",
+        updated: "2026-01-01T00:00:00Z",
+      },
+    ]);
+    writeContract("# Assertions\n- A1: Auth works\n- A2: Tests pass");
+
+    const task1 = makeTask({ id: "001", milestone: "M1", status: "done", fulfills: ["A1"] });
+    const task2 = makeTask({ id: "002", milestone: "M1", status: "done", fulfills: ["A2"] });
+    saveTask(tmpDir, task1);
+    saveTask(tmpDir, task2);
+
+    const validatorPane = makePane({
+      id: "%3",
+      index: 2,
+      title: "Validator",
+      currentCommand: "zsh",
+      role: "validator",
+    });
+    mockPanes = [validatorPane];
+
+    const config = makeOrchestratorConfig(tmpDir, { dispatchMode: "missions", masterPane: null });
+    const state = makeOrchestratorState();
+
+    checkMilestoneCompletion(config, state, [task1, task2], [validatorPane]);
+
+    // Milestone should be in validating, not done
+    const mission = loadMission(tmpDir)!;
+    const m1 = mission.milestones.find((m) => m.id === "M1")!;
+    expect(m1.status).toBe("validating");
+
+    // Validation state should have pending entries
+    const valState = loadValidationState(tmpDir)!;
+    expect(valState.assertions["A1"]?.status).toBe("pending");
+    expect(valState.assertions["A2"]?.status).toBe("pending");
+
+    // Should have dispatched to validator pane
+    const sendCalls = tmuxCalls.filter((c) => c.args.includes("send-keys"));
+    expect(sendCalls.length).toBeGreaterThan(0);
+
+    // Check event
+    const events = readEvents(tmpDir);
+    expect(events.find((e) => e.type === "milestone_validating")).toBeTruthy();
+    expect(events.find((e) => e.type === "validation_dispatch")).toBeTruthy();
+  });
+
+  it("all assertions passing marks milestone done and activates next", () => {
+    setupMission([
+      {
+        id: "M1",
+        title: "Phase 1",
+        description: "",
+        status: "validating",
+        order: 1,
+        created: "2026-01-01T00:00:00Z",
+        updated: "2026-01-01T00:00:00Z",
+      },
+      {
+        id: "M2",
+        title: "Phase 2",
+        description: "",
+        status: "locked",
+        order: 2,
+        created: "2026-01-01T00:00:00Z",
+        updated: "2026-01-01T00:00:00Z",
+      },
+    ]);
+
+    const task1 = makeTask({ id: "001", milestone: "M1", status: "done", fulfills: ["A1"] });
+    const task2 = makeTask({ id: "002", milestone: "M1", status: "done", fulfills: ["A2"] });
+    saveTask(tmpDir, task1);
+    saveTask(tmpDir, task2);
+
+    // All assertions passing
+    saveValidationState(tmpDir, {
+      assertions: {
+        A1: {
+          status: "passing",
+          verifiedBy: "Validator",
+          verifiedAt: "2026-01-01T00:00:00Z",
+          evidence: "works",
+          blockedBy: null,
+        },
+        A2: {
+          status: "passing",
+          verifiedBy: "Validator",
+          verifiedAt: "2026-01-01T00:00:00Z",
+          evidence: "tests pass",
+          blockedBy: null,
+        },
+      },
+      lastVerified: "2026-01-01T00:00:00Z",
+    });
+
+    const config = makeOrchestratorConfig(tmpDir, { dispatchMode: "missions" });
+    checkValidationResults(config, [task1, task2]);
+
+    const mission = loadMission(tmpDir)!;
+    const m1 = mission.milestones.find((m) => m.id === "M1")!;
+    const m2 = mission.milestones.find((m) => m.id === "M2")!;
+    expect(m1.status).toBe("done");
+    expect(m2.status).toBe("active");
+
+    const events = readEvents(tmpDir);
+    expect(events.find((e) => e.type === "milestone_complete")).toBeTruthy();
+  });
+
+  it("zero-assertion milestone advances to done", () => {
+    setupMission([
+      {
+        id: "M1",
+        title: "Phase 1",
+        description: "",
+        status: "validating",
+        order: 1,
+        created: "2026-01-01T00:00:00Z",
+        updated: "2026-01-01T00:00:00Z",
+      },
+      {
+        id: "M2",
+        title: "Phase 2",
+        description: "",
+        status: "locked",
+        order: 2,
+        created: "2026-01-01T00:00:00Z",
+        updated: "2026-01-01T00:00:00Z",
+      },
+    ]);
+
+    const task1 = makeTask({ id: "001", milestone: "M1", status: "done", fulfills: [] });
+    saveTask(tmpDir, task1);
+    saveValidationState(tmpDir, { assertions: {}, lastVerified: "2026-01-01T00:00:00Z" });
+
+    const config = makeOrchestratorConfig(tmpDir, { dispatchMode: "missions" });
+    checkValidationResults(config, [task1]);
+
+    const mission = loadMission(tmpDir)!;
+    expect(mission.milestones.find((m) => m.id === "M1")?.status).toBe("done");
+    expect(mission.milestones.find((m) => m.id === "M2")?.status).toBe("active");
+  });
+
+  it("failed assertion creates remediation task and resets milestone to active", () => {
+    setupMission([
+      {
+        id: "M1",
+        title: "Phase 1",
+        description: "",
+        status: "validating",
+        order: 1,
+        created: "2026-01-01T00:00:00Z",
+        updated: "2026-01-01T00:00:00Z",
+      },
+    ]);
+
+    const task1 = makeTask({ id: "001", milestone: "M1", status: "done", fulfills: ["A1", "A2"] });
+    saveTask(tmpDir, task1);
+
+    saveValidationState(tmpDir, {
+      assertions: {
+        A1: {
+          status: "passing",
+          verifiedBy: "V",
+          verifiedAt: "2026-01-01T00:00:00Z",
+          evidence: "ok",
+          blockedBy: null,
+        },
+        A2: {
+          status: "failing",
+          verifiedBy: "V",
+          verifiedAt: "2026-01-01T00:00:00Z",
+          evidence: "auth broken",
+          blockedBy: null,
+        },
+      },
+      lastVerified: "2026-01-01T00:00:00Z",
+    });
+
+    const config = makeOrchestratorConfig(tmpDir, { dispatchMode: "missions" });
+    checkValidationResults(config, [task1]);
+
+    // Milestone should be back to active
+    const mission = loadMission(tmpDir)!;
+    const m1 = mission.milestones.find((m) => m.id === "M1")!;
+    expect(m1.status).toBe("active");
+
+    // Remediation task should exist
+    const allTasks = loadTasks(tmpDir);
+    const remediation = allTasks.find((t) => t.tags.includes("remediation"));
+    expect(remediation).toBeTruthy();
+    expect(remediation!.milestone).toBe("M1");
+    expect(remediation!.fulfills).toContain("A2");
+    expect(remediation!.description).toContain("auth broken");
+
+    // Failed assertion should be reset to pending
+    const valState = loadValidationState(tmpDir)!;
+    expect(valState.assertions["A2"]?.status).toBe("pending");
+
+    // Events
+    const events = readEvents(tmpDir);
+    expect(events.find((e) => e.type === "remediation")).toBeTruthy();
+    expect(events.find((e) => e.type === "validation_failed")).toBeTruthy();
+  });
+
+  it("remediation skips missing assertion entries without crashing", () => {
+    setupMission([
+      {
+        id: "M1",
+        title: "Phase 1",
+        description: "",
+        status: "validating",
+        order: 1,
+        created: "2026-01-01T00:00:00Z",
+        updated: "2026-01-01T00:00:00Z",
+      },
+    ]);
+
+    const task1 = makeTask({ id: "001", milestone: "M1", status: "done", fulfills: ["A1", "A2"] });
+    saveTask(tmpDir, task1);
+    writeFileSync(
+      join(tmpDir, ".tasks", "validation-state.json"),
+      JSON.stringify({
+        assertions: {
+          A1: {
+            status: "failing",
+            verifiedBy: "V",
+            verifiedAt: "2026-01-01T00:00:00Z",
+            evidence: "broken",
+            blockedBy: null,
+          },
+          A2: null,
+        },
+        lastVerified: "2026-01-01T00:00:00Z",
+      }),
+    );
+
+    const config = makeOrchestratorConfig(tmpDir, { dispatchMode: "missions" });
+    expect(() => checkValidationResults(config, [task1])).not.toThrow();
+  });
+
+  it("buildValidationPrompt includes contract and task details", () => {
+    writeContract("# Assertions\n- A1: Auth endpoint returns 200");
+
+    const milestone = {
+      id: "M1",
+      title: "Phase 1",
+      description: "",
+      status: "validating" as const,
+      order: 1,
+      created: "2026-01-01T00:00:00Z",
+      updated: "2026-01-01T00:00:00Z",
+    };
+    const tasks = [
+      makeTask({
+        id: "001",
+        title: "Fix auth",
+        fulfills: ["A1"],
+        proof: { notes: "done" },
+        salientSummary: "Patched JWT",
+      }),
+    ];
+
+    const prompt = buildValidationPrompt(tmpDir, milestone, tasks);
+    expect(prompt.includes("Validation: Phase 1")).toBeTruthy();
+    expect(prompt.includes("Auth endpoint returns 200")).toBeTruthy();
+    expect(prompt.includes("Fix auth")).toBeTruthy();
+    expect(prompt.includes("A1")).toBeTruthy();
+    expect(prompt.includes("Patched JWT")).toBeTruthy();
+    expect(prompt.includes("tmux-ide validate assert")).toBeTruthy();
+  });
+});
+
+describe("structured handoff", () => {
+  it("logs salientSummary in completion event", () => {
+    const task = makeTask({
+      status: "done",
+      assignee: "Agent 1",
+      salientSummary: "Discovered JWT needs rotation",
+    });
+
+    const panes: PaneInfo[] = [makePane({ id: "%0", title: "Master" })];
+
+    const config = makeOrchestratorConfig(tmpDir);
+    const state = makeOrchestratorState({
+      previousTasks: new Map([["001", "in-progress"]]),
+    });
+
+    detectCompletions(config, state, [task], panes);
+
+    const events = readEvents(tmpDir);
+    const completionEvent = events.find((e) => e.type === "completion");
+    expect(completionEvent).toBeTruthy();
+    expect(completionEvent!.message.includes("Discovered JWT needs rotation")).toBeTruthy();
+  });
+
+  it("auto-creates follow-up tasks for discoveredIssues", () => {
+    const task = makeTask({
+      status: "done",
+      assignee: "Agent 1",
+      discoveredIssues: ["CSS z-index conflict in modal", "Missing rate limiting on /api/auth"],
+    });
+    saveTask(tmpDir, task);
+
+    const panes: PaneInfo[] = [makePane({ id: "%0", title: "Master" })];
+
+    const config = makeOrchestratorConfig(tmpDir);
+    const state = makeOrchestratorState({
+      previousTasks: new Map([["001", "in-progress"]]),
+    });
+
+    detectCompletions(config, state, [task], panes);
+
+    // Two follow-up tasks should be created
+    const allTasks = loadTasks(tmpDir);
+    const followUps = allTasks.filter((t) => t.tags.includes("discovered-issue"));
+    expect(followUps.length).toBe(2);
+    expect(followUps[0]!.description).toContain("CSS z-index");
+    expect(followUps[1]!.description).toContain("rate limiting");
+
+    // Events
+    const events = readEvents(tmpDir);
+    const issueEvents = events.filter((e) => e.type === "discovered_issue");
+    expect(issueEvents.length).toBe(2);
+  });
+});
+
+describe("rich dispatch prompts", () => {
+  it("includes milestone context when task has milestone", () => {
+    saveMission(tmpDir, {
+      title: "Ship v2",
+      description: "",
+      status: "active",
+      branch: null,
+      milestones: [
+        {
+          id: "M1",
+          title: "Foundation",
+          description: "Core infra setup",
+          status: "active",
+          order: 1,
+          created: "2026-01-01T00:00:00Z",
+          updated: "2026-01-01T00:00:00Z",
+        },
+      ],
+      created: "2026-01-01T00:00:00Z",
+      updated: "2026-01-01T00:00:00Z",
+    });
+
+    const task = makeTask({ milestone: "M1" });
+    const prompt = buildTaskPrompt(tmpDir, task);
+
+    expect(prompt.includes("Milestone: Foundation (M1)")).toBeTruthy();
+    expect(prompt.includes("Core infra setup")).toBeTruthy();
+  });
+
+  it("includes AGENTS.md content when file exists", () => {
+    writeFileSync(join(tmpDir, "AGENTS.md"), "Do not modify the auth module.\nStay in your lane.");
+
+    const task = makeTask();
+    const prompt = buildTaskPrompt(tmpDir, task);
+
+    expect(prompt.includes("Agent Guidelines")).toBeTruthy();
+    expect(prompt.includes("Do not modify the auth module")).toBeTruthy();
+  });
+
+  it("includes recent completions from same milestone", () => {
+    saveMission(tmpDir, {
+      title: "Ship v2",
+      description: "",
+      status: "active",
+      branch: null,
+      milestones: [
+        {
+          id: "M1",
+          title: "Phase 1",
+          description: "",
+          status: "active",
+          order: 1,
+          created: "2026-01-01T00:00:00Z",
+          updated: "2026-01-01T00:00:00Z",
+        },
+      ],
+      created: "2026-01-01T00:00:00Z",
+      updated: "2026-01-01T00:00:00Z",
+    });
+
+    // Save a completed task in the same milestone
+    saveTask(
+      tmpDir,
+      makeTask({
+        id: "099",
+        title: "Setup database",
+        milestone: "M1",
+        status: "done",
+        assignee: "Agent 1",
+        salientSummary: "Used Postgres with pgvector",
+      }),
+    );
+
+    const task = makeTask({ id: "100", milestone: "M1" });
+    const prompt = buildTaskPrompt(tmpDir, task);
+
+    expect(prompt.includes("Recent Completions")).toBeTruthy();
+    expect(prompt.includes("Setup database")).toBeTruthy();
+    expect(prompt.includes("Used Postgres with pgvector")).toBeTruthy();
+  });
+
+  it("includes library architecture.md when present", () => {
+    const libraryDir = join(tmpDir, ".tmux-ide", "library");
+    mkdirSync(libraryDir, { recursive: true });
+    writeFileSync(join(libraryDir, "architecture.md"), "Monorepo with pnpm workspaces");
+
+    const task = makeTask();
+    const prompt = buildTaskPrompt(tmpDir, task);
+
+    expect(prompt.includes("Architecture")).toBeTruthy();
+    expect(prompt.includes("Monorepo with pnpm workspaces")).toBeTruthy();
+  });
+
+  it("includes library files matching task tags", () => {
+    const libraryDir = join(tmpDir, ".tmux-ide", "library");
+    mkdirSync(libraryDir, { recursive: true });
+    writeFileSync(join(libraryDir, "security.md"), "Always sanitize inputs");
+
+    const task = makeTask({ tags: ["security"] });
+    const prompt = buildTaskPrompt(tmpDir, task);
+
+    expect(prompt.includes("Reference: security.md")).toBeTruthy();
+    expect(prompt.includes("Always sanitize inputs")).toBeTruthy();
+  });
+
+  it("truncates large library files", () => {
+    const libraryDir = join(tmpDir, ".tmux-ide", "library");
+    mkdirSync(libraryDir, { recursive: true });
+    writeFileSync(join(libraryDir, "architecture.md"), "x".repeat(600));
+
+    const task = makeTask();
+    const prompt = buildTaskPrompt(tmpDir, task);
+
+    expect(prompt.includes("... (see full file at")).toBeTruthy();
+  });
+
+  it("includes services when config provides them", () => {
+    const task = makeTask();
+    const config = makeOrchestratorConfig(tmpDir, {
+      services: {
+        dev: { command: "pnpm dev", port: 3000 },
+        test: { command: "pnpm test" },
+      },
+    });
+    const prompt = buildTaskPrompt(tmpDir, task, config);
+
+    expect(prompt.includes("Available Services")).toBeTruthy();
+    expect(prompt.includes("pnpm dev")).toBeTruthy();
+    expect(prompt.includes("port 3000")).toBeTruthy();
+    expect(prompt.includes("pnpm test")).toBeTruthy();
+  });
+
+  it("includes fulfills in task details", () => {
+    const task = makeTask({ fulfills: ["A1", "A2"] });
+    const prompt = buildTaskPrompt(tmpDir, task);
+    expect(prompt.includes("Fulfills assertions: A1, A2")).toBeTruthy();
+  });
+});
+
+describe("knowledge library", () => {
+  it("appends salientSummary to learnings.md on task completion", () => {
+    const task = makeTask({
+      status: "done",
+      assignee: "Agent 1",
+      salientSummary: "JWT refresh tokens need 15min expiry",
+    });
+
+    const panes: PaneInfo[] = [makePane({ id: "%0", title: "Master" })];
+
+    const config = makeOrchestratorConfig(tmpDir);
+    const state = makeOrchestratorState({
+      previousTasks: new Map([["001", "in-progress"]]),
+    });
+
+    detectCompletions(config, state, [task], panes);
+
+    const learningsPath = join(tmpDir, ".tmux-ide", "library", "learnings.md");
+    expect(existsSync(learningsPath)).toBeTruthy();
+    const content = readFileSync(learningsPath, "utf-8");
+    expect(content.includes("Task 001: Test task")).toBeTruthy();
+    expect(content.includes("JWT refresh tokens need 15min expiry")).toBeTruthy();
+  });
+
+  it("does not create learnings.md when no salientSummary", () => {
+    const task = makeTask({
+      status: "done",
+      assignee: "Agent 1",
+      salientSummary: null,
+    });
+
+    const panes: PaneInfo[] = [makePane({ id: "%0", title: "Master" })];
+
+    const config = makeOrchestratorConfig(tmpDir);
+    const state = makeOrchestratorState({
+      previousTasks: new Map([["001", "in-progress"]]),
+    });
+
+    detectCompletions(config, state, [task], panes);
+
+    const learningsPath = join(tmpDir, ".tmux-ide", "library", "learnings.md");
+    expect(existsSync(learningsPath)).toBe(false);
+  });
+});
+
+describe("mission lifecycle", () => {
+  it("dispatches planning when mission has no milestones", () => {
+    saveMission(tmpDir, {
+      title: "Ship v2",
+      description: "Major release",
+      status: "planning",
+      branch: null,
+      milestones: [],
+      created: "2026-01-01T00:00:00Z",
+      updated: "2026-01-01T00:00:00Z",
+    });
+
+    const leadPane = makePane({
+      id: "%0",
+      index: 0,
+      title: "Lead",
+      currentCommand: "zsh",
+      role: "lead",
+    });
+    mockPanes = [leadPane];
+
+    const config = makeOrchestratorConfig(tmpDir, { dispatchMode: "missions", masterPane: "Lead" });
+    const state = makeOrchestratorState();
+
+    dispatchPlanning(config, state, [leadPane]);
+
+    // Should have claimed __planning__
+    expect(state.claimedTasks.has("__planning__")).toBeTruthy();
+
+    // Should have sent command to lead pane
+    const sendCalls = tmuxCalls.filter((c) => c.args.includes("send-keys"));
+    expect(sendCalls.length).toBeGreaterThan(0);
+
+    // Dispatch file should exist
+    expect(existsSync(join(tmpDir, ".tasks", "dispatch", "planning.md"))).toBeTruthy();
+
+    // Event should be logged
+    const events = readEvents(tmpDir);
+    expect(events.find((e) => e.type === "planning")).toBeTruthy();
+  });
+
+  it("does not dispatch planning twice", () => {
+    saveMission(tmpDir, {
+      title: "Ship v2",
+      description: "",
+      status: "planning",
+      branch: null,
+      milestones: [],
+      created: "2026-01-01T00:00:00Z",
+      updated: "2026-01-01T00:00:00Z",
+    });
+
+    const leadPane = makePane({
+      id: "%0",
+      index: 0,
+      title: "Lead",
+      currentCommand: "zsh",
+      role: "lead",
+    });
+    mockPanes = [leadPane];
+
+    const config = makeOrchestratorConfig(tmpDir, { dispatchMode: "missions" });
+    const state = makeOrchestratorState();
+
+    dispatchPlanning(config, state, [leadPane]);
+    const callCount1 = tmuxCalls.filter((c) => c.args.includes("send-keys")).length;
+
+    dispatchPlanning(config, state, [leadPane]);
+    const callCount2 = tmuxCalls.filter((c) => c.args.includes("send-keys")).length;
+
+    // Second call should not generate additional send-keys
+    expect(callCount2).toBe(callCount1);
+  });
+
+  it("logs an error when planning cannot be dispatched", () => {
+    saveMission(tmpDir, {
+      title: "Ship v2",
+      description: "",
+      status: "planning",
+      branch: null,
+      milestones: [],
+      created: "2026-01-01T00:00:00Z",
+      updated: "2026-01-01T00:00:00Z",
+    });
+
+    const config = makeOrchestratorConfig(tmpDir, { dispatchMode: "missions" });
+    const state = makeOrchestratorState();
+
+    dispatchPlanning(config, state, []);
+
+    const events = readEvents(tmpDir);
+    const errorEvent = events.find((e) => e.type === "error");
+    expect(errorEvent).toBeTruthy();
+    expect(errorEvent?.message).toContain("no planner pane available");
+    expect(state.claimedTasks.has("__planning__")).toBe(false);
+  });
+
+  it("buildPlanningPrompt includes mission context and instructions", () => {
+    saveMission(tmpDir, {
+      title: "Ship v2",
+      description: "Complete rewrite of auth",
+      status: "planning",
+      branch: null,
+      milestones: [],
+      created: "2026-01-01T00:00:00Z",
+      updated: "2026-01-01T00:00:00Z",
+    });
+
+    const prompt = buildPlanningPrompt(tmpDir);
+
+    expect(prompt.includes("Mission Planning")).toBeTruthy();
+    expect(prompt.includes("Ship v2")).toBeTruthy();
+    expect(prompt.includes("Complete rewrite of auth")).toBeTruthy();
+    expect(prompt.includes("milestone create")).toBeTruthy();
+    expect(prompt.includes("validation-contract.md")).toBeTruthy();
+    expect(prompt.includes("plan-complete")).toBeTruthy();
+  });
+
+  it("handleMissionComplete sets status and logs event", () => {
+    const mission = {
+      title: "Ship v2",
+      description: "Major release",
+      status: "active" as const,
+      branch: null,
+      milestones: [
+        {
+          id: "M1",
+          title: "Phase 1",
+          description: "",
+          status: "done" as const,
+          order: 1,
+          created: "2026-01-01T00:00:00Z",
+          updated: "2026-01-01T00:00:00Z",
+        },
+      ],
+      created: "2026-01-01T00:00:00Z",
+      updated: "2026-01-01T00:00:00Z",
+    };
+    saveMission(tmpDir, mission);
+
+    const masterPane = makePane({ id: "%0", title: "Master", role: "lead" });
+    mockPanes = [masterPane];
+
+    const config = makeOrchestratorConfig(tmpDir, { dispatchMode: "missions" });
+    handleMissionComplete(config, mission, [masterPane]);
+
+    // Mission should be complete
+    const updated = loadMission(tmpDir)!;
+    expect(updated.status).toBe("complete");
+
+    // Dispatch file should exist
+    expect(existsSync(join(tmpDir, ".tasks", "dispatch", "mission-complete.md"))).toBeTruthy();
+
+    // Event should be logged
+    const events = readEvents(tmpDir);
+    const missionEvent = events.find((e) => e.type === "mission_complete");
+    expect(missionEvent).toBeTruthy();
+    expect(missionEvent!.message.includes("Ship v2")).toBeTruthy();
+
+    // Master pane should be notified
+    const sendCalls = tmuxCalls.filter(
+      (c) => c.args.includes("send-keys") && c.args.includes("%0"),
+    );
+    expect(sendCalls.length).toBeGreaterThan(0);
+  });
+
+  it("handleMissionComplete returns early when milestones are not done", () => {
+    const mission = {
+      title: "Ship v2",
+      description: "Major release",
+      status: "active" as const,
+      branch: null,
+      milestones: [
+        {
+          id: "M1",
+          title: "Phase 1",
+          description: "",
+          status: "active" as const,
+          order: 1,
+          created: "2026-01-01T00:00:00Z",
+          updated: "2026-01-01T00:00:00Z",
+        },
+      ],
+      created: "2026-01-01T00:00:00Z",
+      updated: "2026-01-01T00:00:00Z",
+    };
+    saveMission(tmpDir, mission);
+
+    const config = makeOrchestratorConfig(tmpDir, { dispatchMode: "missions" });
+    handleMissionComplete(config, mission, []);
+
+    expect(loadMission(tmpDir)?.status).toBe("active");
+    expect(existsSync(join(tmpDir, ".tasks", "dispatch", "mission-complete.md"))).toBe(false);
+  });
+
+  it("mission create sets status to planning", () => {
+    // This tests the data model — mission create in task.ts sets status: "planning"
+    // Verify via direct mission construction (CLI test would need process spawn)
+    const now = new Date().toISOString();
+    saveMission(tmpDir, {
+      title: "New Project",
+      description: "Big thing",
+      status: "planning",
+      branch: null,
+      milestones: [],
+      created: now,
+      updated: now,
+    });
+
+    const mission = loadMission(tmpDir)!;
+    expect(mission.status).toBe("planning");
+    expect(mission.milestones.length).toBe(0);
+  });
+});