@os-eco/overstory-cli 0.6.1 → 0.6.5

package/src/commands/coordinator.test.ts

@@ -23,9 +23,9 @@ import {
 	buildCoordinatorBeacon,
 	type CoordinatorDeps,
 	coordinatorCommand,
+	createCoordinatorCommand,
 	resolveAttach,
 } from "./coordinator.ts";
-import { isRunningAsRoot } from "./sling.ts";
 
 // --- Fake Tmux ---
 
@@ -41,6 +41,7 @@ interface TmuxCallTracker {
 	killSession: Array<{ name: string }>;
 	sendKeys: Array<{ name: string; keys: string }>;
 	waitForTuiReady: Array<{ name: string }>;
+	ensureTmuxAvailable: number;
 }
 
 // --- Fake Watchdog ---
@@ -62,7 +63,13 @@ interface MonitorCallTracker {
 }
 
 /** Build a fake tmux DI object with configurable session liveness. */
-function makeFakeTmux(sessionAliveMap: Record<string, boolean> = {}): {
+function makeFakeTmux(
+	sessionAliveMap: Record<string, boolean> = {},
+	options: {
+		waitForTuiReadyResult?: boolean;
+		ensureTmuxAvailableError?: Error;
+	} = {},
+): {
 	tmux: NonNullable<CoordinatorDeps["_tmux"]>;
 	calls: TmuxCallTracker;
 } {
@@ -72,6 +79,7 @@ function makeFakeTmux(sessionAliveMap: Record<string, boolean> = {}): {
 		killSession: [],
 		sendKeys: [],
 		waitForTuiReady: [],
+		ensureTmuxAvailable: 0,
 	};
 
 	const tmux: NonNullable<CoordinatorDeps["_tmux"]> = {
@@ -97,7 +105,13 @@ function makeFakeTmux(sessionAliveMap: Record<string, boolean> = {}): {
 		},
 		waitForTuiReady: async (name: string): Promise<boolean> => {
 			calls.waitForTuiReady.push({ name });
-			return true;
+			return options.waitForTuiReadyResult ?? true;
+		},
+		ensureTmuxAvailable: async (): Promise<void> => {
+			calls.ensureTmuxAvailable++;
+			if (options.ensureTmuxAvailableError) {
+				throw options.ensureTmuxAvailableError;
+			}
 		},
 	};
 
@@ -272,7 +286,7 @@ function makeCoordinatorSession(overrides: Partial<AgentSession> = {}): AgentSes
 		capability: "coordinator",
 		worktreePath: tempDir,
 		branchName: "main",
-		beadId: "",
+		taskId: "",
 		tmuxSession: "overstory-test-project-coordinator",
 		state: "working",
 		pid: 99999,
@@ -310,13 +324,14 @@ function makeDeps(
 	sessionAliveMap: Record<string, boolean> = {},
 	watchdogConfig?: { running?: boolean; startSuccess?: boolean; stopSuccess?: boolean },
 	monitorConfig?: { running?: boolean; startSuccess?: boolean; stopSuccess?: boolean },
+	tmuxOptions?: { waitForTuiReadyResult?: boolean; ensureTmuxAvailableError?: Error },
 ): {
 	deps: CoordinatorDeps;
 	calls: TmuxCallTracker;
 	watchdogCalls: WatchdogCallTracker;
 	monitorCalls: MonitorCallTracker;
 } {
-	const { tmux, calls } = makeFakeTmux(sessionAliveMap);
+	const { tmux, calls } = makeFakeTmux(sessionAliveMap, tmuxOptions);
 	const { watchdog, calls: watchdogCalls } = makeFakeWatchdog(
 		watchdogConfig?.running,
 		watchdogConfig?.startSuccess,
@@ -347,27 +362,33 @@ function makeDeps(
 describe("coordinatorCommand help", () => {
 	test("--help outputs help text", async () => {
 		const output = await captureStdout(() => coordinatorCommand(["--help"]));
-		expect(output).toContain("overstory coordinator");
+		expect(output).toContain("coordinator");
 		expect(output).toContain("start");
 		expect(output).toContain("stop");
 		expect(output).toContain("status");
 	});
 
-	test("--help includes --attach and --no-attach flags", async () => {
-		const output = await captureStdout(() => coordinatorCommand(["--help"]));
+	test("start --help includes --attach and --no-attach flags", async () => {
+		const cmd = createCoordinatorCommand({});
+		for (const sub of cmd.commands) {
+			sub.exitOverride();
+		}
+		const output = await captureStdout(async () => {
+			await cmd.parseAsync(["start", "--help"], { from: "user" }).catch(() => {});
+		});
 		expect(output).toContain("--attach");
 		expect(output).toContain("--no-attach");
 	});
 
 	test("-h outputs help text", async () => {
 		const output = await captureStdout(() => coordinatorCommand(["-h"]));
-		expect(output).toContain("overstory coordinator");
+		expect(output).toContain("coordinator");
 	});
 
 	test("empty args outputs help text", async () => {
 		const output = await captureStdout(() => coordinatorCommand([]));
-		expect(output).toContain("overstory coordinator");
-		expect(output).toContain("Subcommands:");
+		expect(output).toContain("coordinator");
+		expect(output).toContain("Commands:");
 	});
 });
 
@@ -385,7 +406,6 @@ describe("coordinatorCommand unknown subcommand", () => {
 			const ve = err as ValidationError;
 			expect(ve.message).toContain("frobnicate");
 			expect(ve.field).toBe("subcommand");
-			expect(ve.value).toBe("frobnicate");
 		}
 	});
 });
@@ -417,7 +437,7 @@ describe("startCoordinator", () => {
 		expect(session?.pid).toBe(99999);
 		expect(session?.parentAgent).toBeNull();
 		expect(session?.depth).toBe(0);
-		expect(session?.beadId).toBe("");
+		expect(session?.taskId).toBe("");
 		expect(session?.branchName).toBe("main");
 		expect(session?.worktreePath).toBe(tempDir);
 		expect(session?.id).toMatch(/^session-\d+-coordinator$/);
@@ -630,6 +650,88 @@ describe("startCoordinator", () => {
 		// The new session should have a different ID than the dead one
 		expect(newSession?.id).not.toBe("session-dead-coordinator");
 	});
+
+	test("throws AgentError when tmux is not available", async () => {
+		const { deps } = makeDeps({}, undefined, undefined, {
+			ensureTmuxAvailableError: new AgentError(
+				"tmux is not installed or not on PATH. Install tmux to use overstory agent orchestration.",
+			),
+		});
+
+		await expect(coordinatorCommand(["start"], deps)).rejects.toThrow(AgentError);
+	});
+
+	test("AgentError message mentions tmux not installed when tmux unavailable", async () => {
+		const { deps } = makeDeps({}, undefined, undefined, {
+			ensureTmuxAvailableError: new AgentError(
+				"tmux is not installed or not on PATH. Install tmux to use overstory agent orchestration.",
+			),
+		});
+
+		try {
+			await coordinatorCommand(["start"], deps);
+			expect(true).toBe(false); // Should have thrown
+		} catch (err: unknown) {
+			expect(err).toBeInstanceOf(AgentError);
+			const agentErr = err as AgentError;
+			expect(agentErr.message).toContain("tmux is not installed");
+		}
+	});
+
+	test("throws AgentError when session dies during startup", async () => {
+		// waitForTuiReady returns false AND isSessionAlive returns false — session died
+		const { deps } = makeDeps(
+			{ "overstory-test-project-coordinator": false },
+			undefined,
+			undefined,
+			{ waitForTuiReadyResult: false },
+		);
+
+		await expect(coordinatorCommand(["start"], deps)).rejects.toThrow(AgentError);
+	});
+
+	test("AgentError message mentions session dying when session dies during startup", async () => {
+		const { deps } = makeDeps(
+			{ "overstory-test-project-coordinator": false },
+			undefined,
+			undefined,
+			{ waitForTuiReadyResult: false },
+		);
+
+		try {
+			await coordinatorCommand(["start"], deps);
+			expect(true).toBe(false); // Should have thrown
+		} catch (err: unknown) {
+			expect(err).toBeInstanceOf(AgentError);
+			const agentErr = err as AgentError;
+			expect(agentErr.message).toContain("died during startup");
+		}
+	});
+
+	test("continues when waitForTuiReady times out but session is still alive", async () => {
+		// waitForTuiReady returns false (timeout) but session IS alive
+		const { deps } = makeDeps(
+			{ "overstory-test-project-coordinator": true },
+			undefined,
+			undefined,
+			{ waitForTuiReadyResult: false },
+		);
+
+		const originalSleep = Bun.sleep;
+		Bun.sleep = (() => Promise.resolve()) as typeof Bun.sleep;
+
+		let thrownError: unknown;
+		try {
+			await captureStdout(() => coordinatorCommand(["start"], deps));
+		} catch (err: unknown) {
+			thrownError = err;
+		} finally {
+			Bun.sleep = originalSleep;
+		}
+
+		// Should NOT throw — session is alive, just slow TUI
+		expect(thrownError).toBeUndefined();
+	});
 });
 
 describe("stopCoordinator", () => {
@@ -1202,10 +1304,16 @@ describe("watchdog integration", () => {
 	});
 
 	describe("COORDINATOR_HELP", () => {
-		test("help text includes --watchdog flag", async () => {
-			const output = await captureStdout(() => coordinatorCommand(["--help"]));
+		test("start help text includes --watchdog flag", async () => {
+			const cmd = createCoordinatorCommand({});
+			for (const sub of cmd.commands) {
+				sub.exitOverride();
+			}
+			const output = await captureStdout(async () => {
+				await cmd.parseAsync(["start", "--help"], { from: "user" }).catch(() => {});
+			});
 			expect(output).toContain("--watchdog");
-			expect(output).toContain("Auto-start watchdog daemon with coordinator");
+			expect(output).toContain("watchdog");
 		});
 	});
 });
@@ -1490,10 +1598,16 @@ describe("monitor integration", () => {
 	});
 
 	describe("COORDINATOR_HELP", () => {
-		test("help text includes --monitor flag", async () => {
-			const output = await captureStdout(() => coordinatorCommand(["--help"]));
+		test("start help text includes --monitor flag", async () => {
+			const cmd = createCoordinatorCommand({});
+			for (const sub of cmd.commands) {
+				sub.exitOverride();
+			}
+			const output = await captureStdout(async () => {
+				await cmd.parseAsync(["start", "--help"], { from: "user" }).catch(() => {});
+			});
 			expect(output).toContain("--monitor");
-			expect(output).toContain("Auto-start monitor agent (Tier 2) with coordinator");
+			expect(output).toContain("monitor");
 		});
 	});
 });
@@ -1521,10 +1635,3 @@ describe("SessionStore round-trip", () => {
 		expect(exists).toBe(true);
 	});
 });
-
-describe("isRunningAsRoot (imported from sling)", () => {
-	test("is accessible from coordinator test file", () => {
-		expect(isRunningAsRoot(() => 0)).toBe(true);
-		expect(isRunningAsRoot(() => 1000)).toBe(false);
-	});
-});

package/src/commands/coordinator.ts

@@ -14,6 +14,7 @@
 
 import { mkdir, unlink } from "node:fs/promises";
 import { join } from "node:path";
+import { Command } from "commander";
 import { deployHooks } from "../agents/hooks-deployer.ts";
 import { createIdentity, loadIdentity } from "../agents/identity.ts";
 import { createManifestLoader, resolveModel } from "../agents/manifest.ts";
@@ -26,6 +27,7 @@ import type { AgentSession } from "../types.ts";
 import { isProcessRunning } from "../watchdog/health.ts";
 import {
 	createSession,
+	ensureTmuxAvailable,
 	isSessionAlive,
 	killSession,
 	sendKeys,
@@ -61,6 +63,7 @@ export interface CoordinatorDeps {
 			timeoutMs?: number,
 			pollIntervalMs?: number,
 		) => Promise<boolean>;
+		ensureTmuxAvailable: () => Promise<void>;
 	};
 	_watchdog?: {
 		start: () => Promise<{ pid: number } | null>;
@@ -252,17 +255,6 @@ export function buildCoordinatorBeacon(cliName = "bd"): string {
 	return parts.join(" — ");
 }
 
-/**
- * Start the coordinator agent.
- *
- * 1. Verify no coordinator is already running
- * 2. Load config
- * 3. Create agent identity (if first time)
- * 4. Deploy hooks to project root's .claude/settings.local.json
- * 5. Spawn tmux session at project root with Claude Code
- * 6. Send startup beacon
- * 7. Record session in SessionStore (sessions.db)
- */
 /**
  * Determine whether to auto-attach to the tmux session after starting.
  * Exported for testing.
@@ -273,19 +265,20 @@ export function resolveAttach(args: string[], isTTY: boolean): boolean {
 	return isTTY;
 }
 
-async function startCoordinator(args: string[], deps: CoordinatorDeps = {}): Promise<void> {
+async function startCoordinator(
+	opts: { json: boolean; attach: boolean; watchdog: boolean; monitor: boolean },
+	deps: CoordinatorDeps = {},
+): Promise<void> {
 	const tmux = deps._tmux ?? {
 		createSession,
 		isSessionAlive,
 		killSession,
 		sendKeys,
 		waitForTuiReady,
+		ensureTmuxAvailable,
 	};
 
-	const json = args.includes("--json");
-	const shouldAttach = resolveAttach(args, !!process.stdout.isTTY);
-	const watchdogFlag = args.includes("--watchdog");
-	const monitorFlag = args.includes("--monitor");
+	const { json, attach: shouldAttach, watchdog: watchdogFlag, monitor: monitorFlag } = opts;
 
 	if (isRunningAsRoot()) {
 		throw new AgentError(
@@ -354,6 +347,10 @@ async function startCoordinator(args: string[], deps: CoordinatorDeps = {}): Pro
 		const manifest = await manifestLoader.load();
 		const { model, env } = resolveModel(config, manifest, "coordinator", "opus");
 
+		// Preflight: verify tmux is installed before attempting to spawn.
+		// Without this check, a missing tmux leads to cryptic errors later.
+		await tmux.ensureTmuxAvailable();
+
 		// Spawn tmux session at project root with Claude Code (interactive mode).
 		// Inject the coordinator base definition via --append-system-prompt so the
 		// coordinator knows its role, hierarchy rules, and delegation patterns
@@ -382,7 +379,7 @@ async function startCoordinator(args: string[], deps: CoordinatorDeps = {}): Pro
 			capability: "coordinator",
 			worktreePath: projectRoot, // Coordinator uses project root, not a worktree
 			branchName: config.project.canonicalBranch, // Operates on canonical branch
-			beadId: "", // No specific bead assignment
+			taskId: "", // No specific bead assignment
 			tmuxSession,
 			state: "booting",
 			pid,
@@ -398,7 +395,20 @@ async function startCoordinator(args: string[], deps: CoordinatorDeps = {}): Pro
 		store.upsert(session);
 
 		// Wait for Claude Code TUI to render before sending input
-		await tmux.waitForTuiReady(tmuxSession);
+		const tuiReady = await tmux.waitForTuiReady(tmuxSession);
+		if (!tuiReady) {
+			// Session may have died — check liveness before proceeding
+			const alive = await tmux.isSessionAlive(tmuxSession);
+			if (!alive) {
+				// Clean up the stale session record
+				store.updateState(COORDINATOR_NAME, "completed");
+				throw new AgentError(
+					`Coordinator tmux session "${tmuxSession}" died during startup. The Claude Code process may have crashed or exited immediately. Check tmux logs or try running the claude command manually.`,
+					{ agentName: COORDINATOR_NAME },
+				);
+			}
+			// Session is alive but TUI didn't render in time — proceed with warning
+		}
 		await Bun.sleep(1_000);
 
 		const resolvedBackend = await resolveBackend(config.taskTracker.backend, config.project.root);
@@ -478,16 +488,17 @@ async function startCoordinator(args: string[], deps: CoordinatorDeps = {}): Pro
  * 3. Mark session as completed in SessionStore
  * 4. Auto-complete the active run (if current-run.txt exists)
  */
-async function stopCoordinator(args: string[], deps: CoordinatorDeps = {}): Promise<void> {
+async function stopCoordinator(opts: { json: boolean }, deps: CoordinatorDeps = {}): Promise<void> {
 	const tmux = deps._tmux ?? {
 		createSession,
 		isSessionAlive,
 		killSession,
 		sendKeys,
 		waitForTuiReady,
+		ensureTmuxAvailable,
 	};
 
-	const json = args.includes("--json");
+	const { json } = opts;
 	const cwd = process.cwd();
 	const config = await loadConfig(cwd);
 	const projectRoot = config.project.root;
@@ -584,16 +595,20 @@ async function stopCoordinator(args: string[], deps: CoordinatorDeps = {}): Prom
  *
  * Checks session registry and tmux liveness to report actual state.
  */
-async function statusCoordinator(args: string[], deps: CoordinatorDeps = {}): Promise<void> {
+async function statusCoordinator(
+	opts: { json: boolean },
+	deps: CoordinatorDeps = {},
+): Promise<void> {
 	const tmux = deps._tmux ?? {
 		createSession,
 		isSessionAlive,
 		killSession,
 		sendKeys,
 		waitForTuiReady,
+		ensureTmuxAvailable,
 	};
 
-	const json = args.includes("--json");
+	const { json } = opts;
 	const cwd = process.cwd();
 	const config = await loadConfig(cwd);
 	const projectRoot = config.project.root;
@@ -670,31 +685,54 @@ async function statusCoordinator(args: string[], deps: CoordinatorDeps = {}): Pr
 	}
 }
 
-const COORDINATOR_HELP = `overstory coordinator — Manage the persistent coordinator agent
-
-Usage: overstory coordinator <subcommand> [flags]
-
-Subcommands:
-  start                    Start the coordinator (spawns Claude Code at project root)
-  stop                     Stop the coordinator (kills tmux session)
-  status                   Show coordinator state
+/**
+ * Create the Commander command for `overstory coordinator`.
+ */
+export function createCoordinatorCommand(deps: CoordinatorDeps = {}): Command {
+	const cmd = new Command("coordinator").description("Manage the persistent coordinator agent");
+
+	cmd
+		.command("start")
+		.description("Start the coordinator (spawns Claude Code at project root)")
+		.option("--attach", "Always attach to tmux session after start")
+		.option("--no-attach", "Never attach to tmux session after start")
+		.option("--watchdog", "Auto-start watchdog daemon with coordinator")
+		.option("--monitor", "Auto-start Tier 2 monitor agent with coordinator")
+		.option("--json", "Output as JSON")
+		.action(
+			async (opts: { attach?: boolean; watchdog?: boolean; monitor?: boolean; json?: boolean }) => {
+				// opts.attach = true if --attach, false if --no-attach, undefined if neither
+				const shouldAttach = opts.attach !== undefined ? opts.attach : !!process.stdout.isTTY;
+				await startCoordinator(
+					{
+						json: opts.json ?? false,
+						attach: shouldAttach,
+						watchdog: opts.watchdog ?? false,
+						monitor: opts.monitor ?? false,
+					},
+					deps,
+				);
+			},
+		);
 
-Start options:
-  --attach                 Always attach to tmux session after start
-  --no-attach              Never attach to tmux session after start
-                           Default: attach when running in an interactive TTY
-  --watchdog               Auto-start watchdog daemon with coordinator
-  --monitor                Auto-start monitor agent (Tier 2) with coordinator
+	cmd
+		.command("stop")
+		.description("Stop the coordinator (kills tmux session)")
+		.option("--json", "Output as JSON")
+		.action(async (opts: { json?: boolean }) => {
+			await stopCoordinator({ json: opts.json ?? false }, deps);
+		});
 
-General options:
-  --json                   Output as JSON
-  --help, -h               Show this help
+	cmd
+		.command("status")
+		.description("Show coordinator state")
+		.option("--json", "Output as JSON")
+		.action(async (opts: { json?: boolean }) => {
+			await statusCoordinator({ json: opts.json ?? false }, deps);
+		});
 
-The coordinator runs at the project root and orchestrates work by:
-  - Decomposing objectives into beads issues
-  - Dispatching agents via overstory sling
-  - Tracking batches via task groups
-  - Handling escalations from agents and watchdog`;
+	return cmd;
+}
 
 /**
  * Entry point for `overstory coordinator <subcommand>`.
@@ -706,28 +744,27 @@ export async function coordinatorCommand(
 	args: string[],
 	deps: CoordinatorDeps = {},
 ): Promise<void> {
-	if (args.includes("--help") || args.includes("-h") || args.length === 0) {
-		process.stdout.write(`${COORDINATOR_HELP}\n`);
+	const cmd = createCoordinatorCommand(deps);
+	cmd.exitOverride();
+
+	if (args.length === 0) {
+		process.stdout.write(cmd.helpInformation());
 		return;
 	}
 
-	const subcommand = args[0];
-	const subArgs = args.slice(1);
-
-	switch (subcommand) {
-		case "start":
-			await startCoordinator(subArgs, deps);
-			break;
-		case "stop":
-			await stopCoordinator(subArgs, deps);
-			break;
-		case "status":
-			await statusCoordinator(subArgs, deps);
-			break;
-		default:
-			throw new ValidationError(
-				`Unknown coordinator subcommand: ${subcommand}. Run 'overstory coordinator --help' for usage.`,
-				{ field: "subcommand", value: subcommand },
-			);
+	try {
+		await cmd.parseAsync(args, { from: "user" });
+	} catch (err: unknown) {
+		if (err && typeof err === "object" && "code" in err) {
+			const code = (err as { code: string }).code;
+			if (code === "commander.helpDisplayed" || code === "commander.version") {
+				return;
+			}
+			if (code === "commander.unknownCommand") {
+				const message = err instanceof Error ? err.message : String(err);
+				throw new ValidationError(message, { field: "subcommand" });
+			}
+		}
+		throw err;
 	}
 }