@os-eco/overstory-cli 0.8.6 → 0.8.7

package/README.md

@@ -19,6 +19,7 @@ Requires [Bun](https://bun.sh) v1.0+, git, and tmux. At least one supported agen
 - [GitHub Copilot](https://github.com/features/copilot) (`copilot` CLI)
 - [Codex](https://github.com/openai/codex) (`codex` CLI)
 - [Gemini CLI](https://github.com/google-gemini/gemini-cli) (`gemini` CLI)
+- [Cursor CLI](https://cursor.com/docs/cli/overview) (`agent` CLI)
 - [Sapling](https://github.com/jayminwest/sapling) (`sp` CLI)
 - [OpenCode](https://opencode.ai) (`opencode` CLI)
 
@@ -177,14 +178,16 @@ Overstory uses instruction overlays and tool-call guards to turn agent sessions
 
 Overstory is runtime-agnostic. The `AgentRuntime` interface (`src/runtimes/types.ts`) defines the contract — each adapter handles spawning, config deployment, guard enforcement, readiness detection, and transcript parsing for its runtime. Set the default in `config.yaml` or override per-agent with `ov sling --runtime <name>`.
 
-| Runtime | CLI | Guard Mechanism | Status |
-|---------|-----|-----------------|--------|
+| Runtime | CLI | Guard Mechanism | Stability |
+|---------|-----|-----------------|-----------|
 | Claude Code | `claude` | `settings.local.json` hooks | Stable |
-| Pi | `pi` | `.pi/extensions/` guard extension | Active development |
-| Copilot | `copilot` | (none — `--allow-all-tools`) | Active development |
-| Codex | `codex` | OS-level sandbox (Seatbelt/Landlock) | Active development |
-| Gemini | `gemini` | `--sandbox` flag | Active development |
-| Sapling | `sp` | `.sapling/guards.json` | Active development |
+| Sapling | `sp` | `.sapling/guards.json` | Stable |
+| Pi | `pi` | `.pi/extensions/` guard extension | Experimental |
+| Copilot | `copilot` | (none — `--allow-all-tools`) | Experimental |
+| Cursor | `agent` | (none — `--yolo`) | Experimental |
+| Codex | `codex` | OS-level sandbox (Seatbelt/Landlock) | Experimental |
+| Gemini | `gemini` | `--sandbox` flag | Experimental |
+| OpenCode | `opencode` | (none) | Experimental |
 
 ## How It Works
 
@@ -284,7 +287,7 @@ overstory/
     metrics/                      SQLite metrics + pricing + transcript parsing
     doctor/                       Health check modules (11 checks)
     insights/                     Session insight analyzer for auto-expertise
-    runtimes/                     AgentRuntime abstraction (registry + adapters: Claude, Pi, Copilot, Codex, Gemini, Sapling, OpenCode)
+    runtimes/                     AgentRuntime abstraction (registry + adapters: Claude, Pi, Copilot, Codex, Gemini, Sapling, OpenCode, Cursor)
     tracker/                      Pluggable task tracker (beads + seeds backends)
     mulch/                        mulch client (programmatic API + CLI wrapper)
     e2e/                          End-to-end lifecycle tests

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@os-eco/overstory-cli",
-	"version": "0.8.6",
+	"version": "0.8.7",
 	"description": "Multi-agent orchestration for AI coding agents — spawn workers in git worktrees via tmux, coordinate through SQLite mail, merge with tiered conflict resolution. Pluggable runtime adapters for Claude Code, Pi, and more.",
 	"author": "Jaymin West",
 	"license": "MIT",

package/src/agents/hooks-deployer.test.ts

@@ -8,6 +8,7 @@ import {
 	buildBashFileGuardScript,
 	buildBashPathBoundaryScript,
 	buildPathBoundaryGuardScript,
+	buildTrackerCloseGuardScript,
 	deployHooks,
 	escapeForSingleQuotedShell,
 	extractQualityGatePrefixes,
@@ -15,6 +16,7 @@ import {
 	getCapabilityGuards,
 	getDangerGuards,
 	getPathBoundaryGuards,
+	getTrackerCloseGuards,
 	isOverstoryHookEntry,
 	PATH_PREFIX,
 } from "./hooks-deployer.ts";
@@ -468,9 +470,9 @@ describe("deployHooks", () => {
 		expect(writeBlockGuard).toBeDefined();
 		expect(writeBlockGuard.hooks[0].command).toContain('"decision":"block"');
 
-		// Should have multiple Bash guards: danger guard + file guard + universal push guard
+		// Should have multiple Bash guards: danger guard + file guard + tracker close guard + universal push guard
 		const bashGuards = preToolUse.filter((h: { matcher: string }) => h.matcher === "Bash");
-		expect(bashGuards.length).toBe(3); // danger guard + file guard + universal push guard
+		expect(bashGuards.length).toBe(4); // danger guard + file guard + tracker close guard + universal push guard
 	});
 
 	test("reviewer capability adds same guards as scout", async () => {
@@ -512,9 +514,9 @@ describe("deployHooks", () => {
 		expect(guardMatchers).toContain("NotebookEdit");
 		expect(guardMatchers).toContain("Bash");
 
-		// Should have 3 Bash guards: danger guard + file guard + universal push guard
+		// Should have 4 Bash guards: danger guard + file guard + tracker close guard + universal push guard
 		const bashGuards = preToolUse.filter((h: { matcher: string }) => h.matcher === "Bash");
-		expect(bashGuards.length).toBe(3);
+		expect(bashGuards.length).toBe(4);
 	});
 
 	test("builder capability gets path boundary + Bash danger + Bash path boundary guards + native team tool blocks", async () => {
@@ -544,9 +546,9 @@ describe("deployHooks", () => {
 		expect(writeGuards[0].hooks[0].command).toContain("OVERSTORY_WORKTREE_PATH");
 		expect(writeGuards[0].hooks[0].command).not.toContain("cannot modify files");
 
-		// Builder should have 3 Bash guards: danger guard + path boundary guard + universal push guard
+		// Builder should have 4 Bash guards: danger guard + path boundary guard + tracker close guard + universal push guard
 		const bashGuards = preToolUse.filter((h: { matcher: string }) => h.matcher === "Bash");
-		expect(bashGuards.length).toBe(3);
+		expect(bashGuards.length).toBe(4);
 		// One should be the danger guard (checks git push)
 		const dangerGuard = bashGuards.find(
 			(h: { hooks: Array<{ command: string }> }) =>
@@ -1607,7 +1609,7 @@ describe("structural enforcement integration", () => {
 
 		// Find the bash file guard (the second Bash entry, after the danger guard)
 		const bashGuards = preToolUse.filter((h: { matcher: string }) => h.matcher === "Bash");
-		expect(bashGuards.length).toBe(3);
+		expect(bashGuards.length).toBe(4);
 
 		// The file guard (second Bash guard) should whitelist git add/commit
 		const fileGuard = bashGuards[1];
@@ -2070,8 +2072,8 @@ describe("bash path boundary integration", () => {
 		const preToolUse = parsed.hooks.PreToolUse;
 
 		const bashGuards = preToolUse.filter((h: { matcher: string }) => h.matcher === "Bash");
-		// Should have 3 Bash guards: danger guard + path boundary guard + universal push guard
-		expect(bashGuards.length).toBe(3);
+		// Should have 4 Bash guards: danger guard + path boundary guard + tracker close guard + universal push guard
+		expect(bashGuards.length).toBe(4);
 
 		// Find the path boundary guard
 		const pathGuard = bashGuards.find((h: { hooks: Array<{ command: string }> }) =>
@@ -2092,7 +2094,7 @@ describe("bash path boundary integration", () => {
 		const preToolUse = parsed.hooks.PreToolUse;
 
 		const bashGuards = preToolUse.filter((h: { matcher: string }) => h.matcher === "Bash");
-		expect(bashGuards.length).toBe(3);
+		expect(bashGuards.length).toBe(4);
 
 		const pathGuard = bashGuards.find((h: { hooks: Array<{ command: string }> }) =>
 			h.hooks[0]?.command?.includes("Bash path boundary violation"),
@@ -2110,9 +2112,9 @@ describe("bash path boundary integration", () => {
 		const parsed = JSON.parse(content);
 		const preToolUse = parsed.hooks.PreToolUse;
 
-		// Scout gets danger guard + file guard + universal push guard (3 Bash guards), but NOT path boundary
+		// Scout gets danger guard + file guard + tracker close guard + universal push guard (4 Bash guards), but NOT path boundary
 		const bashGuards = preToolUse.filter((h: { matcher: string }) => h.matcher === "Bash");
-		expect(bashGuards.length).toBe(3);
+		expect(bashGuards.length).toBe(4);
 
 		const pathGuard = bashGuards.find((h: { hooks: Array<{ command: string }> }) =>
 			h.hooks[0]?.command?.includes("Bash path boundary violation"),
@@ -2401,6 +2403,177 @@ describe("PATH prefix in deployed hooks", () => {
 	});
 });
 
+describe("buildTrackerCloseGuardScript", () => {
+	test("returns a string containing key patterns", () => {
+		const script = buildTrackerCloseGuardScript();
+		expect(typeof script).toBe("string");
+		expect(script.length).toBeGreaterThan(0);
+		expect(script).toContain("sd");
+		expect(script).toContain("bd");
+		expect(script).toContain("close");
+		expect(script).toContain("update");
+	});
+
+	test("contains ENV_GUARD prefix", () => {
+		const script = buildTrackerCloseGuardScript();
+		expect(script).toContain('[ -z "$OVERSTORY_AGENT_NAME" ] && exit 0;');
+	});
+
+	test("contains OVERSTORY_TASK_ID early-exit check", () => {
+		const script = buildTrackerCloseGuardScript();
+		expect(script).toContain('[ -z "$OVERSTORY_TASK_ID" ] && exit 0;');
+	});
+
+	test("blocks sd close with wrong ID", async () => {
+		const script = buildTrackerCloseGuardScript();
+		const input = JSON.stringify({ command: "sd close other-task" });
+		const proc = Bun.spawn(["sh", "-c", script], {
+			stdin: new TextEncoder().encode(input),
+			stdout: "pipe",
+			stderr: "pipe",
+			env: { ...process.env, OVERSTORY_AGENT_NAME: "test-agent", OVERSTORY_TASK_ID: "my-task" },
+		});
+		const output = await new Response(proc.stdout).text();
+		await proc.exited;
+		const parsed = JSON.parse(output.trim());
+		expect(parsed.decision).toBe("block");
+		expect(parsed.reason).toContain("other-task");
+		expect(parsed.reason).toContain("my-task");
+	});
+
+	test("allows sd close with matching ID", async () => {
+		const script = buildTrackerCloseGuardScript();
+		const input = JSON.stringify({ command: "sd close my-task" });
+		const proc = Bun.spawn(["sh", "-c", script], {
+			stdin: new TextEncoder().encode(input),
+			stdout: "pipe",
+			stderr: "pipe",
+			env: { ...process.env, OVERSTORY_AGENT_NAME: "test-agent", OVERSTORY_TASK_ID: "my-task" },
+		});
+		const output = await new Response(proc.stdout).text();
+		await proc.exited;
+		expect(output.trim()).toBe("");
+	});
+
+	test("blocks bd close with wrong ID", async () => {
+		const script = buildTrackerCloseGuardScript();
+		const input = JSON.stringify({ command: "bd close other-task" });
+		const proc = Bun.spawn(["sh", "-c", script], {
+			stdin: new TextEncoder().encode(input),
+			stdout: "pipe",
+			stderr: "pipe",
+			env: { ...process.env, OVERSTORY_AGENT_NAME: "test-agent", OVERSTORY_TASK_ID: "my-task" },
+		});
+		const output = await new Response(proc.stdout).text();
+		await proc.exited;
+		const parsed = JSON.parse(output.trim());
+		expect(parsed.decision).toBe("block");
+		expect(parsed.reason).toContain("other-task");
+	});
+
+	test("blocks sd update --status with wrong ID", async () => {
+		const script = buildTrackerCloseGuardScript();
+		const input = JSON.stringify({ command: "sd update other-task --status in_progress" });
+		const proc = Bun.spawn(["sh", "-c", script], {
+			stdin: new TextEncoder().encode(input),
+			stdout: "pipe",
+			stderr: "pipe",
+			env: { ...process.env, OVERSTORY_AGENT_NAME: "test-agent", OVERSTORY_TASK_ID: "my-task" },
+		});
+		const output = await new Response(proc.stdout).text();
+		await proc.exited;
+		const parsed = JSON.parse(output.trim());
+		expect(parsed.decision).toBe("block");
+		expect(parsed.reason).toContain("other-task");
+	});
+
+	test("exits early when OVERSTORY_TASK_ID is empty (coordinator/monitor)", async () => {
+		const script = buildTrackerCloseGuardScript();
+		const input = JSON.stringify({ command: "sd close coordinator-task" });
+		const proc = Bun.spawn(["sh", "-c", script], {
+			stdin: new TextEncoder().encode(input),
+			stdout: "pipe",
+			stderr: "pipe",
+			env: { ...process.env, OVERSTORY_AGENT_NAME: "coordinator", OVERSTORY_TASK_ID: "" },
+		});
+		const output = await new Response(proc.stdout).text();
+		await proc.exited;
+		expect(output.trim()).toBe("");
+	});
+});
+
+describe("getTrackerCloseGuards", () => {
+	test("returns exactly 1 Bash guard entry", () => {
+		const guards = getTrackerCloseGuards();
+		expect(guards).toHaveLength(1);
+		expect(guards[0]?.matcher).toBe("Bash");
+	});
+
+	test("guard hook type is command", () => {
+		const guards = getTrackerCloseGuards();
+		expect(guards[0]?.hooks[0]?.type).toBe("command");
+	});
+
+	test("guard command contains OVERSTORY_TASK_ID check", () => {
+		const guards = getTrackerCloseGuards();
+		const command = guards[0]?.hooks[0]?.command ?? "";
+		expect(command).toContain("OVERSTORY_TASK_ID");
+	});
+
+	test("guard command includes ENV_GUARD prefix", () => {
+		const guards = getTrackerCloseGuards();
+		const command = guards[0]?.hooks[0]?.command ?? "";
+		expect(command).toContain('[ -z "$OVERSTORY_AGENT_NAME" ] && exit 0;');
+	});
+});
+
+describe("deployHooks tracker close guard integration", () => {
+	let tempDir: string;
+
+	beforeEach(async () => {
+		tempDir = await mkdtemp(join(tmpdir(), "overstory-tracker-close-test-"));
+	});
+
+	afterEach(async () => {
+		await cleanupTempDir(tempDir);
+	});
+
+	test("deployHooks includes tracker close guard in PreToolUse for builder", async () => {
+		const worktreePath = join(tempDir, "builder-tc-wt");
+		await deployHooks(worktreePath, "builder-tc", "builder");
+
+		const content = await Bun.file(join(worktreePath, ".claude", "settings.local.json")).text();
+		const parsed = JSON.parse(content);
+		const preToolUse = parsed.hooks.PreToolUse;
+
+		const trackerGuard = preToolUse.find(
+			(h: { matcher: string; hooks: Array<{ command: string }> }) =>
+				h.matcher === "Bash" && h.hooks[0]?.command?.includes("OVERSTORY_TASK_ID"),
+		);
+		expect(trackerGuard).toBeDefined();
+		expect(trackerGuard.hooks[0].command).toContain("OVERSTORY_TASK_ID");
+	});
+
+	test("deployHooks includes tracker close guard in PreToolUse for all capabilities", async () => {
+		const capabilities = ["builder", "scout", "reviewer", "lead", "merger", "coordinator"];
+
+		for (const cap of capabilities) {
+			const wt = join(tempDir, `${cap}-tc-wt`);
+			await deployHooks(wt, `${cap}-tc`, cap);
+
+			const content = await Bun.file(join(wt, ".claude", "settings.local.json")).text();
+			const parsed = JSON.parse(content);
+			const preToolUse = parsed.hooks.PreToolUse;
+
+			const trackerGuard = preToolUse.find(
+				(h: { matcher: string; hooks: Array<{ command: string }> }) =>
+					h.matcher === "Bash" && h.hooks[0]?.command?.includes("OVERSTORY_TASK_ID"),
+			);
+			expect(trackerGuard).toBeDefined();
+		}
+	});
+});
+
 describe("escapeForSingleQuotedShell", () => {
 	test("no single quotes: string passes through unchanged", () => {
 		expect(escapeForSingleQuotedShell("hello world")).toBe("hello world");

package/src/agents/hooks-deployer.ts

@@ -283,6 +283,61 @@ export function buildBashFileGuardScript(
 	return script;
 }
 
+/**
+ * Build a PreToolUse guard script that prevents agents from closing or updating
+ * issues they don't own.
+ *
+ * Guards against two patterns:
+ * - `sd/bd close <id>` — blocks if <id> != $OVERSTORY_TASK_ID
+ * - `sd/bd update <id> --status` — blocks if <id> != $OVERSTORY_TASK_ID
+ *
+ * Agents without OVERSTORY_TASK_ID (coordinator, monitor) exit early and are unaffected.
+ */
+export function buildTrackerCloseGuardScript(): string {
+	const script = [
+		// Only enforce for overstory agent sessions
+		ENV_GUARD,
+		// Skip if task ID is not set (coordinator/monitor have no task)
+		'[ -z "$OVERSTORY_TASK_ID" ] && exit 0;',
+		"read -r INPUT;",
+		// Extract command value from JSON
+		'CMD=$(echo "$INPUT" | sed \'s/.*"command": *"\\([^"]*\\)".*/\\1/\');',
+		// Check for sd/bd close <id>
+		"if echo \"$CMD\" | grep -qE '^\\s*(sd|bd)\\s+close\\s'; then",
+		"  ISSUE_ID=$(echo \"$CMD\" | sed -E 's/^[[:space:]]*(sd|bd)[[:space:]]+close[[:space:]]+([^ ]+).*/\\2/');",
+		'  if [ "$ISSUE_ID" != "$OVERSTORY_TASK_ID" ]; then',
+		'    echo "{\\"decision\\":\\"block\\",\\"reason\\":\\"Cannot close issue $ISSUE_ID — agents may only close their own task ($OVERSTORY_TASK_ID). Report completion via worker_done mail to your parent instead.\\"}";',
+		"    exit 0;",
+		"  fi;",
+		"fi;",
+		// Check for sd/bd update <id> --status
+		"if echo \"$CMD\" | grep -qE '^\\s*(sd|bd)\\s+update\\s.*--status'; then",
+		"  ISSUE_ID=$(echo \"$CMD\" | sed -E 's/^[[:space:]]*(sd|bd)[[:space:]]+update[[:space:]]+([^ ]+).*/\\2/');",
+		'  if [ "$ISSUE_ID" != "$OVERSTORY_TASK_ID" ]; then',
+		'    echo "{\\"decision\\":\\"block\\",\\"reason\\":\\"Cannot update issue $ISSUE_ID — agents may only update their own task ($OVERSTORY_TASK_ID).\\"}";',
+		"    exit 0;",
+		"  fi;",
+		"fi;",
+	].join(" ");
+	return script;
+}
+
+/**
+ * Generate a PreToolUse guard that blocks tracker close/update for foreign issues.
+ *
+ * Returns a single Bash matcher entry. Applied to ALL agent capabilities
+ * so that no agent can accidentally close the coordinator's dispatch issue.
+ * Agents without OVERSTORY_TASK_ID (coordinator, monitor) are unaffected.
+ */
+export function getTrackerCloseGuards(): HookEntry[] {
+	return [
+		{
+			matcher: "Bash",
+			hooks: [{ type: "command", command: buildTrackerCloseGuardScript() }],
+		},
+	];
+}
+
 /**
  * Capabilities that are allowed to modify files via Bash commands.
  * These get the Bash path boundary guard instead of a blanket file-modification block.
@@ -539,7 +594,8 @@ export async function deployHooks(
 	const pathGuards = getPathBoundaryGuards();
 	const dangerGuards = getDangerGuards(agentName);
 	const capabilityGuards = getCapabilityGuards(capability, qualityGates);
-	const allGuards = [...pathGuards, ...dangerGuards, ...capabilityGuards];
+	const trackerCloseGuards = getTrackerCloseGuards();
+	const allGuards = [...pathGuards, ...dangerGuards, ...capabilityGuards, ...trackerCloseGuards];
 
 	if (allGuards.length > 0) {
 		const preToolUse = config.hooks.PreToolUse ?? [];

package/src/commands/coordinator.test.ts

@@ -460,6 +460,10 @@ describe("startCoordinator", () => {
 		expect(session?.worktreePath).toBe(tempDir);
 		expect(session?.id).toMatch(/^session-\d+-coordinator$/);
 
+		// Verify the session has a runId set (not null)
+		expect(session?.runId).not.toBeNull();
+		expect(session?.runId).toMatch(/^run-/);
+
 		// Verify tmux createSession was called
 		expect(calls.createSession).toHaveLength(1);
 		expect(calls.createSession[0]?.name).toBe("overstory-test-project-coordinator");
@@ -469,6 +473,67 @@ describe("startCoordinator", () => {
 		expect(calls.sendKeys.length).toBeGreaterThanOrEqual(1);
 	});
 
+	test("creates a run record with coordinatorName set", async () => {
+		const { deps } = makeDeps();
+		const originalSleep = Bun.sleep;
+		Bun.sleep = (() => Promise.resolve()) as typeof Bun.sleep;
+
+		try {
+			await captureStdout(() => coordinatorCommand(["start", "--no-attach"], deps));
+		} finally {
+			Bun.sleep = originalSleep;
+		}
+
+		const runStore = createRunStore(join(overstoryDir, "sessions.db"));
+		try {
+			const run = runStore.getActiveRunForCoordinator("coordinator");
+			expect(run).not.toBeNull();
+			expect(run?.coordinatorName).toBe("coordinator");
+			expect(run?.status).toBe("active");
+			expect(run?.coordinatorSessionId).toMatch(/^session-\d+-coordinator$/);
+		} finally {
+			runStore.close();
+		}
+	});
+
+	test("writes current-run.txt for backward compatibility", async () => {
+		const { deps } = makeDeps();
+		const originalSleep = Bun.sleep;
+		Bun.sleep = (() => Promise.resolve()) as typeof Bun.sleep;
+
+		try {
+			await captureStdout(() => coordinatorCommand(["start", "--no-attach"], deps));
+		} finally {
+			Bun.sleep = originalSleep;
+		}
+
+		const currentRunFile = Bun.file(join(overstoryDir, "current-run.txt"));
+		expect(await currentRunFile.exists()).toBe(true);
+		const runId = (await currentRunFile.text()).trim();
+		expect(runId).toMatch(/^run-/);
+	});
+
+	test("run ID in current-run.txt matches session runId", async () => {
+		const { deps } = makeDeps();
+		const originalSleep = Bun.sleep;
+		Bun.sleep = (() => Promise.resolve()) as typeof Bun.sleep;
+
+		try {
+			await captureStdout(() => coordinatorCommand(["start", "--no-attach"], deps));
+		} finally {
+			Bun.sleep = originalSleep;
+		}
+
+		const sessions = loadSessionsFromDb();
+		const session = sessions[0];
+		expect(session?.runId).toBeDefined();
+
+		const currentRunFile = Bun.file(join(overstoryDir, "current-run.txt"));
+		const fileRunId = (await currentRunFile.text()).trim();
+
+		expect(session?.runId).toBe(fileRunId);
+	});
+
 	test("deploys hooks to project root .claude/settings.local.json", async () => {
 		const { deps } = makeDeps();
 		const originalSleep = Bun.sleep;
@@ -845,9 +910,10 @@ describe("startCoordinator", () => {
 		}
 	});
 
-	test("continues when waitForTuiReady times out but session is still alive", async () => {
-		// waitForTuiReady returns false (timeout) but session IS alive
-		const { deps } = makeDeps(
+	test("kills the coordinator and throws when waitForTuiReady times out but session is still alive", async () => {
+		// waitForTuiReady returns false (timeout) and the session is still alive,
+		// so startup should fail explicitly instead of sending the beacon blindly.
+		const { deps, calls } = makeDeps(
 			{ "overstory-test-project-coordinator": true },
 			undefined,
 			undefined,
@@ -866,8 +932,11 @@ describe("startCoordinator", () => {
 			Bun.sleep = originalSleep;
 		}
 
-		// Should NOT throw — session is alive, just slow TUI
-		expect(thrownError).toBeUndefined();
+		expect(thrownError).toBeInstanceOf(AgentError);
+		const agentErr = thrownError as AgentError;
+		expect(agentErr.message).toContain("did not become ready during startup");
+		expect(calls.killSession).toHaveLength(1);
+		expect(calls.killSession[0]?.name).toBe("overstory-test-project-coordinator");
 	});
 });
 

package/src/commands/coordinator.ts

@@ -424,12 +424,31 @@ async function startCoordinator(
 			OVERSTORY_AGENT_NAME: COORDINATOR_NAME,
 		});
 
+		// Create a run for this coordinator session BEFORE recording the session,
+		// so the session can reference the run ID from the start.
+		const sessionId = `session-${Date.now()}-${COORDINATOR_NAME}`;
+		const runId = `run-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+		const runStore = createRunStore(join(overstoryDir, "sessions.db"));
+		try {
+			runStore.createRun({
+				id: runId,
+				startedAt: new Date().toISOString(),
+				coordinatorSessionId: sessionId,
+				coordinatorName: COORDINATOR_NAME,
+				status: "active",
+			});
+		} finally {
+			runStore.close();
+		}
+		// Write current-run.txt for backward compatibility with ov sling and other consumers.
+		await Bun.write(join(overstoryDir, "current-run.txt"), runId);
+
 		// Record session BEFORE sending the beacon so that hook-triggered
 		// updateLastActivity() can find the entry and transition booting->working.
 		// Without this, a race exists: hooks fire before the session is persisted,
 		// leaving the coordinator stuck in "booting" (overstory-036f).
 		const session: AgentSession = {
-			id: `session-${Date.now()}-${COORDINATOR_NAME}`,
+			id: sessionId,
 			agentName: COORDINATOR_NAME,
 			capability: "coordinator",
 			worktreePath: projectRoot, // Coordinator uses project root, not a worktree
@@ -440,7 +459,7 @@ async function startCoordinator(
 			pid,
 			parentAgent: null, // Top of hierarchy
 			depth: 0,
-			runId: null,
+			runId,
 			startedAt: new Date().toISOString(),
 			lastActivity: new Date().toISOString(),
 			escalationLevel: 0,
@@ -476,7 +495,12 @@ async function startCoordinator(
 					{ agentName: COORDINATOR_NAME },
 				);
 			}
-			// Session is alive but TUI didn't render in time — proceed with warning
+			await tmux.killSession(tmuxSession);
+			store.updateState(COORDINATOR_NAME, "completed");
+			throw new AgentError(
+				`Coordinator tmux session "${tmuxSession}" did not become ready during startup. Claude Code may still be waiting on an interactive dialog or initializing too slowly.`,
+				{ agentName: COORDINATOR_NAME },
+			);
 		}
 		await Bun.sleep(1_000);