@os-eco/overstory-cli 0.9.4 → 0.10.3

package/src/commands/clean.ts

@@ -124,6 +124,7 @@ async function logSyntheticSessionEndEvents(overstoryDir: string): Promise<numbe
 interface CleanResult {
 	sessionEndEventsLogged: number;
 	tmuxKilled: number;
+	orphanPidsReaped: number;
 	worktreesCleaned: number;
 	branchesDeleted: number;
 	mailWiped: boolean;
@@ -217,6 +218,45 @@ function loadRegisteredTmuxNames(overstoryDir: string): Set<string> | null {
 	}
 }
 
+/**
+ * Reap any spawn PIDs in sessions.db that survived tmux teardown.
+ *
+ * `killAllTmuxSessions` walks descendants of the live tmux pane PID and is
+ * sufficient for sessions whose tmux container is still up. This handles the
+ * leftover case: a stored pid that is still alive but its tmux session is
+ * gone (claude was reparented to init when its bash wrapper got SIGHUP) or
+ * the session is in a terminal state but the spawn never exited. Best-effort.
+ * (overstory-505d)
+ */
+async function reapOrphanedPids(overstoryDir: string): Promise<number> {
+	let reaped = 0;
+	try {
+		const dbPath = join(overstoryDir, "sessions.db");
+		const jsonPath = join(overstoryDir, "sessions.json");
+		if (!existsSync(dbPath) && !existsSync(jsonPath)) {
+			return 0;
+		}
+		const { store } = openSessionStore(overstoryDir);
+		try {
+			for (const session of store.getAll()) {
+				if (session.pid === null) continue;
+				if (!isProcessAlive(session.pid)) continue;
+				try {
+					await killProcessTree(session.pid);
+					reaped++;
+				} catch {
+					// Best effort
+				}
+			}
+		} finally {
+			store.close();
+		}
+	} catch {
+		// Best effort
+	}
+	return reaped;
+}
+
 /**
  * Remove all overstory worktrees (force remove with branch deletion).
  */
@@ -568,6 +608,7 @@ export async function cleanCommand(opts: CleanOptions): Promise<void> {
 	const result: CleanResult = {
 		sessionEndEventsLogged: 0,
 		tmuxKilled: 0,
+		orphanPidsReaped: 0,
 		worktreesCleaned: 0,
 		branchesDeleted: 0,
 		mailWiped: false,
@@ -609,6 +650,14 @@ export async function cleanCommand(opts: CleanOptions): Promise<void> {
 		result.tmuxKilled = await killAllTmuxSessions(overstoryDir, config.project.name);
 	}
 
+	// 2b. Reap any orphaned spawn PIDs that survived tmux teardown.
+	// Must run after killAllTmuxSessions (which collects descendants of live
+	// panes) but before sessions.db is wiped (we need pid records to find
+	// orphans). (overstory-505d)
+	if (doWorktrees || all) {
+		result.orphanPidsReaped = await reapOrphanedPids(overstoryDir);
+	}
+
 	// 3. Remove worktrees
 	if (doWorktrees) {
 		result.worktreesCleaned = await cleanAllWorktrees(root);
@@ -670,6 +719,11 @@ export async function cleanCommand(opts: CleanOptions): Promise<void> {
 	if (result.tmuxKilled > 0) {
 		lines.push(`Killed ${result.tmuxKilled} tmux session${result.tmuxKilled === 1 ? "" : "s"}`);
 	}
+	if (result.orphanPidsReaped > 0) {
+		lines.push(
+			`Reaped ${result.orphanPidsReaped} orphaned spawn process${result.orphanPidsReaped === 1 ? "" : "es"}`,
+		);
+	}
 	if (result.worktreesCleaned > 0) {
 		lines.push(
 			`Removed ${result.worktreesCleaned} worktree${result.worktreesCleaned === 1 ? "" : "s"}`,

package/src/commands/coordinator.test.ts

@@ -28,6 +28,7 @@ import {
 	coordinatorCommand,
 	createCoordinatorCommand,
 	resolveAttach,
+	startCoordinatorSession,
 } from "./coordinator.ts";
 import {
 	buildOrchestratorBeacon,
@@ -2665,3 +2666,129 @@ describe("checkComplete", () => {
 		expect(subcommandNames).toContain("check-complete");
 	});
 });
+
+describe("startCoordinatorSession headless", () => {
+	test("with headless: true, calls spawnHeadlessAgent and skips tmux", async () => {
+		const { tmux, calls: tmuxCalls } = makeFakeTmux();
+		const { watchdog } = makeFakeWatchdog();
+		const { monitor } = makeFakeMonitor();
+
+		const spawnCalls: Array<{
+			argv: string[];
+			cwd: string;
+			agentName?: string;
+		}> = [];
+		const writes: string[] = [];
+
+		const fakeSpawn = async (
+			argv: string[],
+			opts: { cwd: string; env: Record<string, string>; agentName?: string },
+		): Promise<{
+			pid: number;
+			stdin: { write(data: string | Uint8Array): number | Promise<number> };
+			stdout: ReadableStream<Uint8Array> | null;
+		}> => {
+			spawnCalls.push({ argv, cwd: opts.cwd, agentName: opts.agentName });
+			return {
+				pid: 55555,
+				stdin: {
+					write(data: string | Uint8Array): number {
+						writes.push(typeof data === "string" ? data : new TextDecoder().decode(data));
+						return 0;
+					},
+				},
+				stdout: null,
+			};
+		};
+
+		const deps: CoordinatorDeps = {
+			_tmux: tmux,
+			_watchdog: watchdog,
+			_monitor: monitor,
+			_spawnHeadless: fakeSpawn,
+		};
+
+		await captureStdout(async () => {
+			await startCoordinatorSession(
+				{
+					json: true,
+					attach: false,
+					watchdog: false,
+					monitor: false,
+					headless: true,
+				},
+				deps,
+			);
+		});
+
+		// spawnHeadlessAgent was called exactly once with agentName: "coordinator"
+		expect(spawnCalls.length).toBe(1);
+		expect(spawnCalls[0]?.agentName).toBe("coordinator");
+		expect(spawnCalls[0]?.cwd).toBe(tempDir);
+
+		// initial stdin prompt was written
+		expect(writes.length).toBeGreaterThanOrEqual(1);
+
+		// tmux helpers were never called for the headless path
+		expect(tmuxCalls.createSession.length).toBe(0);
+		expect(tmuxCalls.sendKeys.length).toBe(0);
+		expect(tmuxCalls.waitForTuiReady.length).toBe(0);
+		expect(tmuxCalls.ensureTmuxAvailable).toBe(0);
+
+		// Session row records empty tmuxSession + the headless spawn pid
+		const sessions = loadSessionsFromDb();
+		expect(sessions.length).toBe(1);
+		expect(sessions[0]?.agentName).toBe("coordinator");
+		expect(sessions[0]?.tmuxSession).toBe("");
+		expect(sessions[0]?.pid).toBe(55555);
+		expect(sessions[0]?.state).toBe("booting");
+
+		// current-run.txt was written for downstream consumers
+		const runFile = Bun.file(join(overstoryDir, "current-run.txt"));
+		expect(await runFile.exists()).toBe(true);
+	});
+
+	test("rejects when runtime has no buildDirectSpawn", async () => {
+		// Override config to route the coordinator capability to a runtime that
+		// lacks buildDirectSpawn (e.g. cursor). The headless path must reject.
+		await Bun.write(
+			join(overstoryDir, "config.yaml"),
+			[
+				"project:",
+				"  name: test-project",
+				`  root: ${tempDir}`,
+				"  canonicalBranch: main",
+				"watchdog:",
+				"  tier2Enabled: true",
+				"runtime:",
+				"  capabilities:",
+				"    coordinator: cursor",
+			].join("\n"),
+		);
+
+		const { tmux } = makeFakeTmux();
+		const { watchdog } = makeFakeWatchdog();
+		const { monitor } = makeFakeMonitor();
+		const deps: CoordinatorDeps = {
+			_tmux: tmux,
+			_watchdog: watchdog,
+			_monitor: monitor,
+			_spawnHeadless: async () => {
+				throw new Error("should not be called");
+			},
+		};
+
+		await expect(
+			startCoordinatorSession(
+				{
+					json: true,
+					attach: false,
+					watchdog: false,
+					monitor: false,
+					headless: true,
+				},
+				deps,
+			),
+		).rejects.toThrow(ValidationError);
+	});
+});

package/src/commands/coordinator.ts

@@ -15,6 +15,7 @@
 import { mkdir, unlink } from "node:fs/promises";
 import { join } from "node:path";
 import { Command } from "commander";
+import { buildInitialHeadlessPrompt, formatMailSection } from "../agents/headless-prompt.ts";
 import { createIdentity, loadIdentity } from "../agents/identity.ts";
 import { createManifestLoader, resolveModel } from "../agents/manifest.ts";
 import { loadConfig } from "../config.ts";
@@ -29,6 +30,8 @@ import { createRunStore, createSessionStore } from "../sessions/store.ts";
 import { resolveBackend, trackerCliName } from "../tracker/factory.ts";
 import type { AgentSession } from "../types.ts";
 import { isProcessRunning } from "../watchdog/health.ts";
+import type { SpawnHeadlessOptions } from "../worktree/process.ts";
+import { spawnHeadlessAgent } from "../worktree/process.ts";
 import type { SessionState } from "../worktree/tmux.ts";
 import {
 	capturePaneContent,
@@ -46,7 +49,7 @@ import { nudgeAgent } from "./nudge.ts";
 import { isRunningAsRoot } from "./sling.ts";
 
 /** Default coordinator agent name. */
-const COORDINATOR_NAME = "coordinator";
+export const COORDINATOR_NAME = "coordinator";
 
 export interface PersistentAgentSpec {
 	commandName: string;
@@ -120,6 +123,15 @@ export interface CoordinatorDeps {
 	_capturePaneContent?: (name: string, lines?: number) => Promise<string | null>;
 	/** Override poll interval for ask subcommand (default: ASK_POLL_INTERVAL_MS). Used in tests. */
 	_pollIntervalMs?: number;
+	/** Override headless spawn (used by tests to avoid forking real subprocesses). */
+	_spawnHeadless?: (
+		argv: string[],
+		opts: SpawnHeadlessOptions,
+	) => Promise<{
+		pid: number;
+		stdin: { write(data: string | Uint8Array): number | Promise<number> };
+		stdout: ReadableStream<Uint8Array> | null;
+	}>;
 }
 
 /**
@@ -332,6 +344,13 @@ export interface CoordinatorSessionOptions {
 	displayName?: string;
 	/** Custom beacon builder. Receives tracker CLI name, returns beacon string. */
 	beaconBuilder?: (trackerCli: string) => string;
+	/**
+	 * When true, spawn the coordinator headless (no tmux pane). The runtime must
+	 * implement buildDirectSpawn(). The CLI command `ov coordinator start` does
+	 * not yet pass this flag — it is consumed by the headless start path used by
+	 * the web UI's POST /api/coordinator/start endpoint.
+	 */
+	headless?: boolean;
 }
 
 /**
@@ -365,6 +384,7 @@ export async function startCoordinatorSession(
 		agentDefFile: agentDefFileOpt,
 		displayName: displayNameOpt,
 		beaconBuilder: beaconBuilderOpt,
+		headless: headlessFlag,
 	} = opts;
 
 	const coordinatorName = agentNameOpt ?? coordinatorNameOpt ?? COORDINATOR_NAME;
@@ -459,6 +479,157 @@ export async function startCoordinatorSession(
 			});
 		}
 
+		// Headless start path: bypass tmux entirely and spawn the coordinator
+		// process directly via runtime.buildDirectSpawn(). Same hooks, identity,
+		// and run-tracking as the tmux path — only the spawn mechanism differs.
+		if (headlessFlag === true) {
+			if (!runtime.buildDirectSpawn) {
+				throw new ValidationError(
+					`Headless coordinator start requires a runtime with buildDirectSpawn (got: ${runtime.id})`,
+					{ field: "runtime", value: runtime.id },
+				);
+			}
+
+			const spawnHeadless = deps._spawnHeadless ?? spawnHeadlessAgent;
+			const directEnv: Record<string, string> = {
+				...runtime.buildEnv(resolvedModel),
+				OVERSTORY_AGENT_NAME: coordinatorName,
+				OVERSTORY_PROJECT_ROOT: projectRoot,
+				...(profileFlag ? { OVERSTORY_PROFILE: profileFlag } : {}),
+			};
+			const argv = runtime.buildDirectSpawn({
+				cwd: projectRoot,
+				env: directEnv,
+				...(resolvedModel.isExplicitOverride ? { model: resolvedModel.model } : {}),
+				instructionPath: runtime.instructionPath,
+			});
+
+			// Per-session log dir mirrors sling.ts headless path.
+			const logTimestamp = new Date().toISOString().replace(/[:.]/g, "-");
+			const headlessLogDir = join(overstoryDir, "logs", "coordinator", logTimestamp);
+			await mkdir(headlessLogDir, { recursive: true });
+
+			const headlessProc = await spawnHeadless(argv, {
+				cwd: projectRoot,
+				env: { ...(process.env as Record<string, string>), ...directEnv },
+				stdoutFile: join(headlessLogDir, "stdout.log"),
+				stderrFile: join(headlessLogDir, "stderr.log"),
+				agentName: coordinatorName,
+			});
+
+			// Build the initial stdin prompt from agent definition + pending dispatch
+			// mail + activation beacon. Replaces SessionStart hooks (no-op headless).
+			const agentDefPath = join(projectRoot, ".overstory", "agent-defs", agentDefFile);
+			const agentDefHandle = Bun.file(agentDefPath);
+			const primeContext = (await agentDefHandle.exists()) ? await agentDefHandle.text() : "";
+
+			const mailDbPath = join(overstoryDir, "mail.db");
+			const pendingMailStore = createMailStore(mailDbPath);
+			let mailSection = "";
+			try {
+				const pendingMailClient = createMailClient(pendingMailStore);
+				const pendingMessages = pendingMailClient.check(coordinatorName);
+				mailSection = formatMailSection(pendingMessages);
+			} finally {
+				pendingMailStore.close();
+			}
+
+			const resolvedBackend = await resolveBackend(config.taskTracker.backend, config.project.root);
+			const trackerCli = trackerCliName(resolvedBackend);
+			const beacon = beaconBuilder(trackerCli);
+			const initialPrompt = buildInitialHeadlessPrompt(
+				primeContext || undefined,
+				mailSection || undefined,
+				beacon,
+			);
+			await headlessProc.stdin.write(initialPrompt);
+
+			// Create run record + current-run.txt + session row.
+			const sessionId = `session-${Date.now()}-${coordinatorName}`;
+			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,
+					status: "active",
+				});
+			} finally {
+				runStore.close();
+			}
+			await Bun.write(join(overstoryDir, "current-run.txt"), runId);
+
+			const session: AgentSession = {
+				id: sessionId,
+				agentName: coordinatorName,
+				capability,
+				worktreePath: projectRoot,
+				branchName: config.project.canonicalBranch,
+				taskId: "",
+				tmuxSession: "", // headless: no tmux pane
+				state: "booting",
+				pid: headlessProc.pid,
+				parentAgent: null,
+				depth: 0,
+				runId,
+				startedAt: new Date().toISOString(),
+				lastActivity: new Date().toISOString(),
+				escalationLevel: 0,
+				stalledSince: null,
+				transcriptPath: null,
+			};
+			store.upsert(session);
+
+			// Auto-start watchdog / monitor (same as tmux path).
+			let watchdogPid: number | undefined;
+			if (watchdogFlag) {
+				const watchdogResult = await watchdog.start();
+				if (watchdogResult) {
+					watchdogPid = watchdogResult.pid;
+					if (!json) printHint("Watchdog started");
+				} else {
+					if (!json) printWarning("Watchdog failed to start");
+				}
+			}
+			let monitorPid: number | undefined;
+			if (monitorFlag) {
+				if (!config.watchdog.tier2Enabled) {
+					if (!json) printWarning("Monitor skipped", "watchdog.tier2Enabled is false");
+				} else {
+					const monitorResult = await monitor.start([]);
+					if (monitorResult) {
+						monitorPid = monitorResult.pid;
+						if (!json) printHint("Monitor started");
+					} else {
+						if (!json) printWarning("Monitor failed to start");
+					}
+				}
+			}
+
+			const output = {
+				agentName: coordinatorName,
+				capability,
+				tmuxSession: "",
+				projectRoot,
+				pid: headlessProc.pid,
+				headless: true,
+				watchdog: watchdogFlag ? watchdogPid !== undefined : false,
+				monitor: monitorFlag ? monitorPid !== undefined : false,
+			};
+
+			if (json) {
+				jsonOutput(`${capability} start`, output);
+			} else {
+				printSuccess(`${displayName} started (headless)`);
+				process.stdout.write(`  Root:    ${projectRoot}\n`);
+				process.stdout.write(`  PID:     ${headlessProc.pid}\n`);
+				process.stdout.write(`  Logs:    ${headlessLogDir}\n`);
+			}
+			return;
+		}
+
 		// Preflight: verify tmux is installed before attempting to spawn.
 		// Without this check, a missing tmux leads to cryptic errors later.
 		await tmux.ensureTmuxAvailable();
@@ -629,6 +800,7 @@ export async function startCoordinatorSession(
 			process.stdout.write(`  Tmux:    ${tmuxSession}\n`);
 			process.stdout.write(`  Root:    ${projectRoot}\n`);
 			process.stdout.write(`  PID:     ${pid}\n`);
+			printHint("Open the UI: `ov serve` then http://localhost:7321 — primary operator surface");
 		}
 
 		if (shouldAttach) {
@@ -679,6 +851,18 @@ function isActivePersistentAgentSession(
  * 3. Mark session as completed in SessionStore
  * 4. Auto-complete the active run (if current-run.txt exists)
  */
+/**
+ * Stop the default coordinator. Handles both tmux and headless sessions.
+ * Exposed for callers outside the CLI command surface (e.g. the web-UI POST
+ * /api/coordinator/stop endpoint, which lives in coordinator-actions.ts).
+ */
+export async function stopCoordinatorSession(
+	opts: { json: boolean },
+	deps: CoordinatorDeps = {},
+): Promise<void> {
+	await stopPersistentAgent(COORDINATOR_SPEC, opts, deps);
+}
+
 async function stopPersistentAgent(
 	spec: PersistentAgentSpec,
 	opts: { json: boolean },
@@ -712,10 +896,24 @@ async function stopPersistentAgent(
 			});
 		}
 
-		// Kill tmux session with process tree cleanup
-		const alive = await tmux.isSessionAlive(session.tmuxSession);
-		if (alive) {
-			await tmux.killSession(session.tmuxSession);
+		// Headless sessions have no tmux pane (tmuxSession === ""). Tear down via
+		// the connection registry (SIGTERM-with-SIGKILL-escalation) and skip tmux.
+		if (session.tmuxSession === "") {
+			const { removeConnection } = await import("../runtimes/connections.ts");
+			removeConnection(spec.agentName);
+			if (session.pid !== null && isProcessRunning(session.pid)) {
+				try {
+					process.kill(session.pid, "SIGTERM");
+				} catch {
+					// process may have exited between the check and the signal
+				}
+			}
+		} 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