@katyella/legio 0.1.0

package/src/commands/coordinator.ts

@@ -0,0 +1,880 @@
+/**
+ * CLI command: legio coordinator start|stop|status
+ *
+ * Manages the persistent coordinator agent lifecycle. The coordinator runs
+ * at the project root (NOT in a worktree), receives work via mail and beads,
+ * and dispatches agents via legio sling.
+ *
+ * Unlike regular agents spawned by sling, the coordinator:
+ * - Has no worktree (operates on the main working tree)
+ * - Has no bead assignment (it creates beads, not works on them)
+ * - Has no overlay CLAUDE.md (context comes via mail + beads + checkpoints)
+ * - Persists across work batches
+ */
+
+import { spawn, spawnSync } from "node:child_process";
+import { access, mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { deployHooks } from "../agents/hooks-deployer.ts";
+import { createIdentity, loadIdentity } from "../agents/identity.ts";
+import { createManifestLoader, resolveModel } from "../agents/manifest.ts";
+import { collectProviderEnv, loadConfig } from "../config.ts";
+import { AgentError, isRunningAsRoot, ValidationError } from "../errors.ts";
+import { HeadlessCoordinator } from "../server/headless.ts";
+import { openSessionStore } from "../sessions/compat.ts";
+import { createRunStore } from "../sessions/store.ts";
+import type { AgentSession, HeadlessCoordinatorConfig } from "../types.ts";
+import { isProcessRunning } from "../watchdog/health.ts";
+import {
+	createSession,
+	isSessionAlive,
+	killSession,
+	sendKeys,
+	waitForTuiReady,
+} from "../worktree/tmux.ts";
+
+/** Default coordinator agent name. */
+const COORDINATOR_NAME = "coordinator";
+
+/**
+ * Build the tmux session name for the coordinator.
+ * Includes the project name to prevent cross-project collisions (legio-pcef).
+ */
+function coordinatorTmuxSession(projectName: string): string {
+	return `legio-${projectName}-${COORDINATOR_NAME}`;
+}
+
+/**
+ * Run a subprocess and collect its output. Returns exit code, stdout, and stderr.
+ */
+function runProcess(
+	cmd: string[],
+	opts: { cwd?: string } = {},
+): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+	return new Promise((resolve, reject) => {
+		const [command, ...args] = cmd;
+		if (!command) {
+			reject(new Error("Empty command array"));
+			return;
+		}
+		const proc = spawn(command, args, {
+			cwd: opts.cwd,
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+		let stdout = "";
+		let stderr = "";
+		proc.stdout.on("data", (d: Buffer) => {
+			stdout += d.toString();
+		});
+		proc.stderr.on("data", (d: Buffer) => {
+			stderr += d.toString();
+		});
+		proc.on("close", (code) => resolve({ exitCode: code ?? 1, stdout, stderr }));
+		proc.on("error", reject);
+	});
+}
+
+/**
+ * Check if a file exists at the given path.
+ */
+async function fileExists(path: string): Promise<boolean> {
+	try {
+		await access(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** Minimal interface required from a HeadlessCoordinator for DI testing. */
+export interface HeadlessCoordinatorHandle {
+	start(): void;
+	write(input: string): void;
+	stop(): Promise<void>;
+	getPid(): number | null;
+	isRunning(): boolean;
+	on(event: "exit", listener: (code: number) => void): this;
+}
+
+/** Dependency injection for testing. Uses real implementations when omitted. */
+export interface CoordinatorDeps {
+	_tmux?: {
+		createSession: (
+			name: string,
+			cwd: string,
+			command: string,
+			env?: Record<string, string>,
+		) => Promise<number>;
+		isSessionAlive: (name: string) => Promise<boolean>;
+		killSession: (name: string) => Promise<void>;
+		sendKeys: (name: string, keys: string) => Promise<void>;
+		waitForTuiReady?: (
+			sessionName: string,
+			opts?: { timeout?: number; interval?: number },
+		) => Promise<void>;
+	};
+	_watchdog?: {
+		start: () => Promise<{ pid: number } | null>;
+		stop: () => Promise<boolean>;
+		isRunning: () => Promise<boolean>;
+	};
+	_monitor?: {
+		start: (args: string[]) => Promise<{ pid: number } | null>;
+		stop: () => Promise<boolean>;
+		isRunning: () => Promise<boolean>;
+	};
+	_headless?: {
+		create: (config: HeadlessCoordinatorConfig) => HeadlessCoordinatorHandle;
+	};
+	_sleep?: (ms: number) => Promise<void>;
+}
+
+/**
+ * Read the PID from the watchdog PID file.
+ * Returns null if the file doesn't exist or can't be parsed.
+ */
+async function readWatchdogPid(projectRoot: string): Promise<number | null> {
+	const pidFilePath = join(projectRoot, ".legio", "watchdog.pid");
+	if (!(await fileExists(pidFilePath))) {
+		return null;
+	}
+
+	try {
+		const text = await readFile(pidFilePath, "utf-8");
+		const pid = Number.parseInt(text.trim(), 10);
+		if (Number.isNaN(pid) || pid <= 0) {
+			return null;
+		}
+		return pid;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Remove the watchdog PID file.
+ */
+async function removeWatchdogPid(projectRoot: string): Promise<void> {
+	const pidFilePath = join(projectRoot, ".legio", "watchdog.pid");
+	try {
+		await unlink(pidFilePath);
+	} catch {
+		// File may already be gone — not an error
+	}
+}
+
+/**
+ * Default watchdog implementation for production use.
+ * Starts/stops the watchdog daemon via `legio watch --background`.
+ */
+function createDefaultWatchdog(projectRoot: string): NonNullable<CoordinatorDeps["_watchdog"]> {
+	return {
+		async start(): Promise<{ pid: number } | null> {
+			// Check if watchdog is already running
+			const existingPid = await readWatchdogPid(projectRoot);
+			if (existingPid !== null && isProcessRunning(existingPid)) {
+				return null; // Already running
+			}
+
+			// Clean up stale PID file
+			if (existingPid !== null) {
+				await removeWatchdogPid(projectRoot);
+			}
+
+			// Start watchdog in background
+			const { exitCode } = await runProcess(["legio", "watch", "--background"], {
+				cwd: projectRoot,
+			});
+			if (exitCode !== 0) {
+				return null; // Failed to start
+			}
+
+			// Read the PID file that was written by the background process
+			const pid = await readWatchdogPid(projectRoot);
+			if (pid === null) {
+				return null; // PID file wasn't created
+			}
+
+			return { pid };
+		},
+
+		async stop(): Promise<boolean> {
+			const pid = await readWatchdogPid(projectRoot);
+			if (pid === null) {
+				return false; // No PID file
+			}
+
+			// Check if process is running
+			if (!isProcessRunning(pid)) {
+				// Process is dead, clean up PID file
+				await removeWatchdogPid(projectRoot);
+				return false;
+			}
+
+			// Kill the process
+			try {
+				process.kill(pid, 15); // SIGTERM
+			} catch {
+				return false;
+			}
+
+			// Remove PID file
+			await removeWatchdogPid(projectRoot);
+			return true;
+		},
+
+		async isRunning(): Promise<boolean> {
+			const pid = await readWatchdogPid(projectRoot);
+			if (pid === null) {
+				return false;
+			}
+			return isProcessRunning(pid);
+		},
+	};
+}
+
+/**
+ * Default monitor implementation for production use.
+ * Starts/stops the monitor agent via `legio monitor start/stop`.
+ */
+function createDefaultMonitor(projectRoot: string): NonNullable<CoordinatorDeps["_monitor"]> {
+	return {
+		async start(): Promise<{ pid: number } | null> {
+			const { exitCode, stdout } = await runProcess(
+				["legio", "monitor", "start", "--no-attach", "--json"],
+				{ cwd: projectRoot },
+			);
+			if (exitCode !== 0) return null;
+			try {
+				const result = JSON.parse(stdout.trim()) as { pid?: number };
+				return result.pid ? { pid: result.pid } : null;
+			} catch {
+				return null;
+			}
+		},
+		async stop(): Promise<boolean> {
+			const { exitCode } = await runProcess(["legio", "monitor", "stop", "--json"], {
+				cwd: projectRoot,
+			});
+			return exitCode === 0;
+		},
+		async isRunning(): Promise<boolean> {
+			const { exitCode, stdout } = await runProcess(["legio", "monitor", "status", "--json"], {
+				cwd: projectRoot,
+			});
+			if (exitCode !== 0) return false;
+			try {
+				const result = JSON.parse(stdout.trim()) as { running?: boolean };
+				return result.running === true;
+			} catch {
+				return false;
+			}
+		},
+	};
+}
+
+/**
+ * Build the coordinator startup beacon — the first message sent to the coordinator
+ * via tmux send-keys after Claude Code initializes.
+ */
+export function buildCoordinatorBeacon(): string {
+	const timestamp = new Date().toISOString();
+	const parts = [
+		`[LEGIO] ${COORDINATOR_NAME} (coordinator) ${timestamp}`,
+		"Depth: 0 | Parent: none | Role: persistent orchestrator",
+		"HIERARCHY: You ONLY spawn leads (legio sling --capability lead). Leads spawn scouts, builders, reviewers. NEVER spawn non-lead agents directly.",
+		"DELEGATION: For any exploration/scouting, spawn a lead who will spawn scouts. Do NOT explore the codebase yourself beyond initial planning.",
+		`Startup: run mulch prime, check mail (legio mail check --agent ${COORDINATOR_NAME}), check bd ready, check legio group status, then begin work`,
+	];
+	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.
+ */
+export function resolveAttach(args: string[], isTTY: boolean): boolean {
+	if (args.includes("--attach")) return true;
+	if (args.includes("--no-attach")) return false;
+	return isTTY;
+}
+
+async function startCoordinator(args: string[], deps: CoordinatorDeps = {}): Promise<void> {
+	const tmux = deps._tmux ?? {
+		createSession,
+		isSessionAlive,
+		killSession,
+		sendKeys,
+		waitForTuiReady,
+	};
+	const sleep =
+		deps._sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+
+	if (isRunningAsRoot()) {
+		throw new ValidationError(
+			"legio must not run as root — agent processes execute arbitrary code",
+			{
+				field: "uid",
+			},
+		);
+	}
+
+	const json = args.includes("--json");
+	const shouldAttach = resolveAttach(args, !!process.stdout.isTTY);
+	const watchdogFlag = args.includes("--watchdog");
+	const monitorFlag = args.includes("--monitor");
+	const headlessFlag = args.includes("--headless");
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const projectRoot = config.project.root;
+	const watchdog = deps._watchdog ?? createDefaultWatchdog(projectRoot);
+	const monitor = deps._monitor ?? createDefaultMonitor(projectRoot);
+	const tmuxSession = coordinatorTmuxSession(config.project.name);
+
+	// Check for existing coordinator
+	const legioDir = join(projectRoot, ".legio");
+	const { store } = openSessionStore(legioDir);
+	try {
+		const existing = store.getByName(COORDINATOR_NAME);
+
+		if (
+			existing &&
+			existing.capability === "coordinator" &&
+			existing.state !== "completed" &&
+			existing.state !== "zombie"
+		) {
+			const alive = await tmux.isSessionAlive(existing.tmuxSession);
+			if (alive) {
+				throw new AgentError(
+					`Coordinator is already running (tmux: ${existing.tmuxSession}, since: ${existing.startedAt})`,
+					{ agentName: COORDINATOR_NAME },
+				);
+			}
+			// Session recorded but tmux is dead — mark as completed and continue
+			store.updateState(COORDINATOR_NAME, "completed");
+		}
+
+		// Deploy hooks to the project root so the coordinator gets event logging,
+		// mail check --inject, and activity tracking via the standard hook pipeline.
+		// The ENV_GUARD prefix on all hooks (both template and generated guards)
+		// ensures they only activate when LEGIO_AGENT_NAME is set (i.e. for
+		// the coordinator's tmux session), so the user's own Claude Code session
+		// at the project root is unaffected.
+		await deployHooks(projectRoot, COORDINATOR_NAME, "coordinator");
+
+		// Create coordinator identity if first run
+		const identityBaseDir = join(projectRoot, ".legio", "agents");
+		await mkdir(identityBaseDir, { recursive: true });
+		const existingIdentity = await loadIdentity(identityBaseDir, COORDINATOR_NAME);
+		if (!existingIdentity) {
+			await createIdentity(identityBaseDir, {
+				name: COORDINATOR_NAME,
+				capability: "coordinator",
+				created: new Date().toISOString(),
+				sessionsCompleted: 0,
+				expertiseDomains: config.mulch.enabled ? config.mulch.domains : [],
+				recentTasks: [],
+			});
+		}
+
+		// Resolve model from config > manifest > fallback
+		const manifestLoader = createManifestLoader(
+			join(projectRoot, config.agents.manifestPath),
+			join(projectRoot, config.agents.baseDir),
+		);
+		const manifest = await manifestLoader.load();
+		const model = resolveModel(config, manifest, "coordinator", "opus");
+
+		// 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
+		// (legio-gaio, legio-0kwf).
+		const agentDefPath = join(projectRoot, ".legio", "agent-defs", "coordinator.md");
+		// Build a settings JSON file that: (1) skips the bypass-permissions
+		// confirmation dialog, and (2) injects the agent definition as a system
+		// prompt suffix. Using --settings with a file avoids Claude Code's
+		// ERR_STREAM_DESTROYED crash when --append-system-prompt receives large
+		// inline payloads (14KB+).
+		const settings: Record<string, unknown> = { skipDangerousModePermissionPrompt: true };
+		if (await fileExists(agentDefPath)) {
+			settings.appendSystemPrompt = await readFile(agentDefPath, "utf-8");
+		}
+		const settingsPath = join(legioDir, `settings-${COORDINATOR_NAME}.json`);
+		await writeFile(settingsPath, JSON.stringify(settings), "utf-8");
+		const claudeCmd = `claude --model ${model} --dangerously-skip-permissions --settings ${settingsPath}`;
+
+		if (headlessFlag) {
+			// ----------------------------------------------------------------
+			// Headless path: spawn via HeadlessCoordinator (no tmux)
+			// ----------------------------------------------------------------
+			const headlessFactory = deps._headless ?? {
+				create: (cfg: HeadlessCoordinatorConfig) => new HeadlessCoordinator(cfg),
+			};
+			const headless = headlessFactory.create({
+				command: claudeCmd,
+				cwd: projectRoot,
+				env: { ...collectProviderEnv(), LEGIO_AGENT_NAME: COORDINATOR_NAME },
+			});
+
+			headless.start();
+			const headlessPid = headless.getPid();
+
+			// Write PID file for later stop/status operations
+			if (headlessPid !== null) {
+				const pidFilePath = join(legioDir, "headless-coordinator.pid");
+				await writeFile(pidFilePath, String(headlessPid), "utf-8");
+			}
+
+			// Record session with tmuxSession="headless" to distinguish from tmux sessions
+			const headlessSession: AgentSession = {
+				id: `session-${Date.now()}-${COORDINATOR_NAME}`,
+				agentName: COORDINATOR_NAME,
+				capability: "coordinator",
+				worktreePath: projectRoot,
+				branchName: config.project.canonicalBranch,
+				beadId: "",
+				tmuxSession: "headless",
+				state: "booting",
+				pid: headlessPid,
+				parentAgent: null,
+				depth: 0,
+				runId: null,
+				startedAt: new Date().toISOString(),
+				lastActivity: new Date().toISOString(),
+				escalationLevel: 0,
+				stalledSince: null,
+			};
+
+			store.upsert(headlessSession);
+
+			// Send startup beacon via stdin after initialization delay
+			await sleep(3_000);
+			const headlessBeacon = buildCoordinatorBeacon();
+			try {
+				headless.write(`${headlessBeacon}\n`);
+			} catch {
+				// stdin may not be available if process exited early
+			}
+
+			const headlessOutput = {
+				agentName: COORDINATOR_NAME,
+				capability: "coordinator",
+				headless: true,
+				projectRoot,
+				pid: headlessPid,
+			};
+
+			if (json) {
+				process.stdout.write(`${JSON.stringify(headlessOutput)}\n`);
+			} else {
+				process.stdout.write("Coordinator started (headless)\n");
+				process.stdout.write(`  Root:    ${projectRoot}\n`);
+				process.stdout.write(`  PID:     ${headlessPid ?? "unknown"}\n`);
+			}
+
+			// Keep process alive until the headless coordinator exits
+			await new Promise<void>((resolve) => {
+				headless.on("exit", () => resolve());
+			});
+
+			return;
+		}
+
+		// ----------------------------------------------------------------
+		// Tmux path: existing behavior
+		// ----------------------------------------------------------------
+		const pid = await tmux.createSession(tmuxSession, projectRoot, claudeCmd, {
+			...collectProviderEnv(),
+			LEGIO_AGENT_NAME: COORDINATOR_NAME,
+		});
+
+		// 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" (legio-036f).
+		const session: AgentSession = {
+			id: `session-${Date.now()}-${COORDINATOR_NAME}`,
+			agentName: COORDINATOR_NAME,
+			capability: "coordinator",
+			worktreePath: projectRoot, // Coordinator uses project root, not a worktree
+			branchName: config.project.canonicalBranch, // Operates on canonical branch
+			beadId: "", // No specific bead assignment
+			tmuxSession,
+			state: "booting",
+			pid,
+			parentAgent: null, // Top of hierarchy
+			depth: 0,
+			runId: null,
+			startedAt: new Date().toISOString(),
+			lastActivity: new Date().toISOString(),
+			escalationLevel: 0,
+			stalledSince: null,
+		};
+
+		store.upsert(session);
+
+		// Write output BEFORE the blocking sleep+sendKeys so that callers
+		// reading stdout (e.g., runLegio in the server) get the response
+		// immediately and don't hang waiting for the pipe to close.
+		const output = {
+			agentName: COORDINATOR_NAME,
+			capability: "coordinator",
+			tmuxSession,
+			projectRoot,
+			pid,
+			watchdog: false,
+			monitor: false,
+		};
+
+		if (json) {
+			process.stdout.write(`${JSON.stringify(output)}\n`);
+		} else {
+			process.stdout.write("Coordinator started\n");
+			process.stdout.write(`  Tmux:    ${tmuxSession}\n`);
+			process.stdout.write(`  Root:    ${projectRoot}\n`);
+			process.stdout.write(`  PID:     ${pid}\n`);
+		}
+
+		// Wait for Claude Code's TUI to render before sending beacon.
+		// Falls back to sleep(3_000) when waitForTuiReady is not in the DI mock.
+		if (tmux.waitForTuiReady) {
+			await tmux.waitForTuiReady(tmuxSession);
+		} else {
+			await sleep(3_000);
+		}
+		const beacon = buildCoordinatorBeacon();
+		await tmux.sendKeys(tmuxSession, beacon);
+
+		// Follow-up Enter to ensure submission (same pattern as sling.ts)
+		await sleep(500);
+		await tmux.sendKeys(tmuxSession, "");
+
+		// Auto-start watchdog if --watchdog flag is present
+		if (watchdogFlag) {
+			const watchdogResult = await watchdog.start();
+			if (watchdogResult) {
+				if (!json) process.stdout.write(`  Watchdog: started (PID ${watchdogResult.pid})\n`);
+			} else {
+				if (!json) process.stderr.write("  Watchdog: failed to start or already running\n");
+			}
+		}
+
+		// Auto-start monitor if --monitor flag is present
+		if (monitorFlag) {
+			const monitorResult = await monitor.start([]);
+			if (monitorResult) {
+				if (!json) process.stdout.write(`  Monitor:  started (PID ${monitorResult.pid})\n`);
+			} else {
+				if (!json) process.stderr.write("  Monitor:  failed to start or already running\n");
+			}
+		}
+
+		if (shouldAttach) {
+			spawnSync("tmux", ["attach-session", "-t", tmuxSession], {
+				stdio: ["inherit", "inherit", "inherit"],
+			});
+		}
+	} finally {
+		store.close();
+	}
+}
+
+/**
+ * Stop the coordinator agent.
+ *
+ * 1. Find the active coordinator session
+ * 2. Kill the tmux session (with process tree cleanup)
+ * 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> {
+	const tmux = deps._tmux ?? { createSession, isSessionAlive, killSession, sendKeys };
+
+	const json = args.includes("--json");
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const projectRoot = config.project.root;
+	const watchdog = deps._watchdog ?? createDefaultWatchdog(projectRoot);
+	const monitor = deps._monitor ?? createDefaultMonitor(projectRoot);
+
+	const legioDir = join(projectRoot, ".legio");
+	const { store } = openSessionStore(legioDir);
+	try {
+		const session = store.getByName(COORDINATOR_NAME);
+
+		if (
+			!session ||
+			session.capability !== "coordinator" ||
+			session.state === "completed" ||
+			session.state === "zombie"
+		) {
+			throw new AgentError("No active coordinator session found", {
+				agentName: COORDINATOR_NAME,
+			});
+		}
+
+		if (session.tmuxSession === "headless") {
+			// ----------------------------------------------------------------
+			// Headless stop: read PID from file and kill the process
+			// ----------------------------------------------------------------
+			const pidFilePath = join(legioDir, "headless-coordinator.pid");
+			let headlessPid: number | null = null;
+			try {
+				const pidText = await readFile(pidFilePath, "utf-8");
+				const parsed = Number.parseInt(pidText.trim(), 10);
+				if (!Number.isNaN(parsed) && parsed > 0) {
+					headlessPid = parsed;
+				}
+			} catch {
+				// PID file may not exist — process may already be dead
+			}
+
+			if (headlessPid !== null && isProcessRunning(headlessPid)) {
+				try {
+					process.kill(headlessPid, 15); // SIGTERM
+				} catch {
+					// ignore — process may have already exited
+				}
+			}
+
+			// Clean up PID file
+			try {
+				await unlink(pidFilePath);
+			} catch {
+				// File may already be gone
+			}
+		} else {
+			// Kill tmux session with process tree cleanup
+			const alive = await tmux.isSessionAlive(session.tmuxSession);
+			if (alive) {
+				await tmux.killSession(session.tmuxSession);
+			}
+		}
+
+		// Always attempt to stop watchdog
+		const watchdogStopped = await watchdog.stop();
+
+		// Always attempt to stop monitor
+		const monitorStopped = await monitor.stop();
+
+		// Update session state
+		store.updateState(COORDINATOR_NAME, "completed");
+		store.updateLastActivity(COORDINATOR_NAME);
+
+		// Auto-complete the current run
+		let runCompleted = false;
+		try {
+			const currentRunPath = join(legioDir, "current-run.txt");
+			if (await fileExists(currentRunPath)) {
+				const runId = (await readFile(currentRunPath, "utf-8")).trim();
+				if (runId.length > 0) {
+					const runStore = createRunStore(join(legioDir, "sessions.db"));
+					try {
+						runStore.completeRun(runId, "completed");
+						runCompleted = true;
+					} finally {
+						runStore.close();
+					}
+					try {
+						await unlink(currentRunPath);
+					} catch {
+						// File may already be gone
+					}
+				}
+			}
+		} catch {
+			// Non-fatal: run completion should not break coordinator stop
+		}
+
+		if (json) {
+			process.stdout.write(
+				`${JSON.stringify({ stopped: true, sessionId: session.id, watchdogStopped, monitorStopped, runCompleted })}\n`,
+			);
+		} else {
+			process.stdout.write(`Coordinator stopped (session: ${session.id})\n`);
+			if (watchdogStopped) {
+				process.stdout.write("Watchdog stopped\n");
+			} else {
+				process.stdout.write("No watchdog running\n");
+			}
+			if (monitorStopped) {
+				process.stdout.write("Monitor stopped\n");
+			} else {
+				process.stdout.write("No monitor running\n");
+			}
+			if (runCompleted) {
+				process.stdout.write("Run completed\n");
+			} else {
+				process.stdout.write("No active run\n");
+			}
+		}
+	} finally {
+		store.close();
+	}
+}
+
+/**
+ * Show coordinator status.
+ *
+ * Checks session registry and tmux liveness to report actual state.
+ */
+async function statusCoordinator(args: string[], deps: CoordinatorDeps = {}): Promise<void> {
+	const tmux = deps._tmux ?? { createSession, isSessionAlive, killSession, sendKeys };
+
+	const json = args.includes("--json");
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const projectRoot = config.project.root;
+	const watchdog = deps._watchdog ?? createDefaultWatchdog(projectRoot);
+	const monitor = deps._monitor ?? createDefaultMonitor(projectRoot);
+
+	const legioDir = join(projectRoot, ".legio");
+	const { store } = openSessionStore(legioDir);
+	try {
+		const session = store.getByName(COORDINATOR_NAME);
+		const watchdogRunning = await watchdog.isRunning();
+		const monitorRunning = await monitor.isRunning();
+
+		if (
+			!session ||
+			session.capability !== "coordinator" ||
+			session.state === "completed" ||
+			session.state === "zombie"
+		) {
+			if (json) {
+				process.stdout.write(
+					`${JSON.stringify({ running: false, watchdogRunning, monitorRunning })}\n`,
+				);
+			} else {
+				process.stdout.write("Coordinator is not running\n");
+				if (watchdogRunning) {
+					process.stdout.write("Watchdog: running\n");
+				}
+				if (monitorRunning) {
+					process.stdout.write("Monitor: running\n");
+				}
+			}
+			return;
+		}
+
+		const isHeadless = session.tmuxSession === "headless";
+
+		// For headless sessions, liveness is determined by PID; for tmux sessions, by session.
+		let alive: boolean;
+		if (isHeadless) {
+			alive = session.pid !== null && isProcessRunning(session.pid);
+		} else {
+			alive = await tmux.isSessionAlive(session.tmuxSession);
+		}
+
+		// Reconcile state: if session says active but process/tmux is dead, update.
+		// We already filtered out completed/zombie states above, so if dead
+		// this session needs to be marked as zombie.
+		if (!alive) {
+			store.updateState(COORDINATOR_NAME, "zombie");
+			session.state = "zombie";
+		}
+		const status = {
+			running: alive,
+			headless: isHeadless,
+			sessionId: session.id,
+			state: session.state,
+			tmuxSession: session.tmuxSession,
+			pid: session.pid,
+			startedAt: session.startedAt,
+			lastActivity: session.lastActivity,
+			watchdogRunning,
+			monitorRunning,
+		};
+
+		if (json) {
+			process.stdout.write(`${JSON.stringify(status)}\n`);
+		} else {
+			const stateLabel = alive ? "running" : session.state;
+			process.stdout.write(`Coordinator: ${stateLabel}\n`);
+			process.stdout.write(`  Session:   ${session.id}\n`);
+			process.stdout.write(`  Tmux:      ${session.tmuxSession}\n`);
+			process.stdout.write(`  PID:       ${session.pid}\n`);
+			process.stdout.write(`  Started:   ${session.startedAt}\n`);
+			process.stdout.write(`  Activity:  ${session.lastActivity}\n`);
+			process.stdout.write(`  Watchdog:  ${watchdogRunning ? "running" : "not running"}\n`);
+			process.stdout.write(`  Monitor:   ${monitorRunning ? "running" : "not running"}\n`);
+		}
+	} finally {
+		store.close();
+	}
+}
+
+const COORDINATOR_HELP = `legio coordinator — Manage the persistent coordinator agent
+
+Usage: legio 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
+
+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
+  --headless               Start without tmux — use PTY subprocess (no terminal UI)
+  --watchdog               Auto-start watchdog daemon with coordinator
+  --monitor                Auto-start monitor agent (Tier 2) with coordinator
+
+General options:
+  --json                   Output as JSON
+  --help, -h               Show this help
+
+The coordinator runs at the project root and orchestrates work by:
+  - Decomposing objectives into beads issues
+  - Dispatching agents via legio sling
+  - Tracking batches via task groups
+  - Handling escalations from agents and watchdog`;
+
+/**
+ * Entry point for `legio coordinator <subcommand>`.
+ *
+ * @param args - CLI arguments after "coordinator"
+ * @param deps - Optional dependency injection for testing (tmux)
+ */
+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`);
+		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 'legio coordinator --help' for usage.`,
+				{ field: "subcommand", value: subcommand },
+			);
+	}
+}