@os-eco/overstory-cli 0.9.4 → 0.11.0

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,21 @@ 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;
+	/**
+	 * Acknowledge that a watchdog daemon from a previous session may already be
+	 * running and should be allowed to supervise this coordinator. Without this
+	 * (or `--watchdog`), the start command refuses to spawn when a leftover
+	 * daemon is detected, to surface the "watchdog persists across runs" trap
+	 * that overstory-3f0c was filed for.
+	 */
+	acceptExistingWatchdog?: boolean;
 }
 
 /**
@@ -365,6 +392,8 @@ export async function startCoordinatorSession(
 		agentDefFile: agentDefFileOpt,
 		displayName: displayNameOpt,
 		beaconBuilder: beaconBuilderOpt,
+		headless: headlessFlag,
+		acceptExistingWatchdog: acceptExistingWatchdogFlag,
 	} = opts;
 
 	const coordinatorName = agentNameOpt ?? coordinatorNameOpt ?? COORDINATOR_NAME;
@@ -386,6 +415,25 @@ export async function startCoordinatorSession(
 	const monitor = deps._monitor ?? createDefaultMonitor(projectRoot);
 	const tmuxSession = coordinatorTmuxSession(config.project.name, coordinatorName);
 
+	// Detect leftover watchdog daemon from a previous session (overstory-3f0c).
+	// If a watchdog is already running and the operator did not pass --watchdog
+	// or --accept-existing-watchdog, refuse to start: a persistent daemon will
+	// supervise this coordinator with policy decided by the original invocation,
+	// not the current one. This prevents "I didn't run --watchdog, why is the
+	// watchdog killing things?" surprises.
+	const watchdogAlreadyRunning = await watchdog.isRunning();
+	if (watchdogAlreadyRunning && !watchdogFlag && !acceptExistingWatchdogFlag) {
+		const existingPid = await readWatchdogPid(projectRoot);
+		const pidLabel = existingPid !== null ? `PID ${existingPid}` : "unknown PID";
+		throw new AgentError(
+			`Watchdog daemon (${pidLabel}) is already running from a previous session. ` +
+				`It will supervise this ${displayName.toLowerCase()} run and may take escalation actions you did not opt into. ` +
+				`To proceed: pass --watchdog to acknowledge, pass --accept-existing-watchdog to suppress this check, ` +
+				`or run 'ov watch --kill-others' (or remove .overstory/watchdog.pid) first.`,
+			{ agentName: coordinatorName },
+		);
+	}
+
 	// Check for existing coordinator session with the same name
 	const overstoryDir = join(projectRoot, ".overstory");
 	const { store } = openSessionStore(overstoryDir);
@@ -459,6 +507,170 @@ 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 (watchdogAlreadyRunning) {
+					// createDefaultWatchdog.start() returns null when an existing PID
+					// is alive — that's a no-op success, not a failure. Reuse the
+					// existing daemon. Sentinel value keeps `watchdogPid !== undefined`
+					// truthy in the JSON output.
+					watchdogPid = -1;
+					if (!json) printHint("Watchdog already running, reusing existing daemon");
+				} else {
+					if (!json) printWarning("Watchdog failed to start");
+				}
+			} else if (watchdogAlreadyRunning && acceptExistingWatchdogFlag) {
+				// --accept-existing-watchdog without --watchdog: surface that an
+				// existing daemon is supervising this run, but do not call start().
+				watchdogPid = -1;
+				if (!json) printHint("Watchdog already running, reusing existing daemon");
+			}
+			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: watchdogPid !== undefined,
+				watchdogPreexisting: watchdogAlreadyRunning,
+				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();
@@ -584,16 +796,28 @@ export async function startCoordinatorSession(
 			await tmux.sendKeys(tmuxSession, "");
 		}
 
-		// Auto-start watchdog if --watchdog flag is present
+		// Auto-start watchdog if --watchdog flag is present.
 		let watchdogPid: number | undefined;
 		if (watchdogFlag) {
 			const watchdogResult = await watchdog.start();
 			if (watchdogResult) {
 				watchdogPid = watchdogResult.pid;
 				if (!json) printHint("Watchdog started");
+			} else if (watchdogAlreadyRunning) {
+				// createDefaultWatchdog.start() returns null when an existing PID
+				// is alive — that's a no-op success, not a failure. Reuse the
+				// existing daemon. Sentinel value keeps `watchdogPid !== undefined`
+				// truthy in the JSON output.
+				watchdogPid = -1;
+				if (!json) printHint("Watchdog already running, reusing existing daemon");
 			} else {
 				if (!json) printWarning("Watchdog failed to start");
 			}
+		} else if (watchdogAlreadyRunning && acceptExistingWatchdogFlag) {
+			// --accept-existing-watchdog without --watchdog: surface that an
+			// existing daemon is supervising this run, but do not call start().
+			watchdogPid = -1;
+			if (!json) printHint("Watchdog already running, reusing existing daemon");
 		}
 
 		// Auto-start monitor if --monitor flag is present and tier2 is enabled
@@ -618,7 +842,8 @@ export async function startCoordinatorSession(
 			tmuxSession,
 			projectRoot,
 			pid,
-			watchdog: watchdogFlag ? watchdogPid !== undefined : false,
+			watchdog: watchdogPid !== undefined,
+			watchdogPreexisting: watchdogAlreadyRunning,
 			monitor: monitorFlag ? monitorPid !== undefined : false,
 		};
 
@@ -629,6 +854,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) {
@@ -643,7 +869,14 @@ export async function startCoordinatorSession(
 
 async function startPersistentAgent(
 	spec: PersistentAgentSpec,
-	opts: { json: boolean; attach: boolean; watchdog: boolean; monitor: boolean; profile?: string },
+	opts: {
+		json: boolean;
+		attach: boolean;
+		watchdog: boolean;
+		monitor: boolean;
+		profile?: string;
+		acceptExistingWatchdog?: boolean;
+	},
 	deps: CoordinatorDeps = {},
 ): Promise<void> {
 	await startCoordinatorSession(
@@ -679,6 +912,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 +957,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
@@ -1359,6 +1618,10 @@ export function createPersistentAgentCommand(
 		.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 ${spec.commandName}`)
+		.option(
+			"--accept-existing-watchdog",
+			"Continue when a watchdog daemon from a previous session is already running (it will supervise this run)",
+		)
 		.option("--monitor", `Auto-start Tier 2 monitor agent with ${spec.commandName}`)
 		.option("--profile <name>", "Canopy profile to apply to spawned agents")
 		.option("--json", "Output as JSON")
@@ -1366,6 +1629,7 @@ export function createPersistentAgentCommand(
 			async (opts: {
 				attach?: boolean;
 				watchdog?: boolean;
+				acceptExistingWatchdog?: boolean;
 				monitor?: boolean;
 				json?: boolean;
 				profile?: string;
@@ -1378,6 +1642,7 @@ export function createPersistentAgentCommand(
 						json: opts.json ?? false,
 						attach: shouldAttach,
 						watchdog: opts.watchdog ?? false,
+						acceptExistingWatchdog: opts.acceptExistingWatchdog ?? false,
 						monitor: opts.monitor ?? false,
 						profile: opts.profile,
 					},

package/src/commands/dashboard.test.ts

@@ -295,6 +295,7 @@ function makeDashboardData(
 			worktrees: [],
 			tmuxSessions: [],
 			unreadMailCount: 0,
+			unreadMailScope: "orchestrator",
 			mergeQueueCount: 0,
 			recentMetricsCount: 0,
 		},
@@ -447,6 +448,7 @@ describe("renderAgentPanel", () => {
 				worktrees: [],
 				tmuxSessions: [], // no tmux sessions
 				unreadMailCount: 0,
+				unreadMailScope: "orchestrator",
 				mergeQueueCount: 0,
 				recentMetricsCount: 0,
 			},
@@ -487,6 +489,7 @@ describe("renderAgentPanel", () => {
 				worktrees: [],
 				tmuxSessions: [],
 				unreadMailCount: 0,
+				unreadMailScope: "orchestrator",
 				mergeQueueCount: 0,
 				recentMetricsCount: 0,
 			},
@@ -495,6 +498,191 @@ describe("renderAgentPanel", () => {
 		expect(out).toContain("x");
 		expect(out).toContain("dead-headless");
 	});
+
+	test("renders mixed tmux + headless agents in same frame with correct liveness", () => {
+		const data = {
+			...makeDashboardData({}),
+			status: {
+				currentRunId: null,
+				agents: [
+					{
+						id: "sess-tmux-1",
+						agentName: "pane-agent",
+						capability: "builder",
+						worktreePath: "/tmp/wt/pane-agent",
+						branchName: "overstory/pane-agent/task-t1",
+						taskId: "task-t1",
+						tmuxSession: "overstory-pane-agent",
+						state: "working" as const,
+						pid: 99999,
+						parentAgent: null,
+						depth: 0,
+						runId: null,
+						startedAt: new Date(Date.now() - 10_000).toISOString(),
+						lastActivity: new Date().toISOString(),
+						escalationLevel: 0,
+						stalledSince: null,
+						transcriptPath: null,
+					},
+					{
+						id: "sess-headless-1",
+						agentName: "live-headless",
+						capability: "builder",
+						worktreePath: "/tmp/wt/live-headless",
+						branchName: "overstory/live-headless/task-h1",
+						taskId: "task-h1",
+						tmuxSession: "", // headless
+						state: "working" as const,
+						pid: process.pid, // own PID — guaranteed alive
+						parentAgent: null,
+						depth: 0,
+						runId: null,
+						startedAt: new Date(Date.now() - 10_000).toISOString(),
+						lastActivity: new Date().toISOString(),
+						escalationLevel: 0,
+						stalledSince: null,
+						transcriptPath: null,
+					},
+				],
+				worktrees: [],
+				tmuxSessions: [{ name: "overstory-pane-agent", pid: 99998 }],
+				unreadMailCount: 0,
+				unreadMailScope: "orchestrator",
+				mergeQueueCount: 0,
+				recentMetricsCount: 0,
+			},
+		};
+		const out = renderAgentPanel(data, 100, 12, 3);
+		expect(out).toContain("pane-agent");
+		expect(out).toContain("live-headless");
+		const aliveMarkers = (out.match(/>/g) ?? []).length;
+		expect(aliveMarkers).toBeGreaterThanOrEqual(2);
+		expect(out).not.toContain("x");
+	});
+
+	test("spawn-per-turn worker (no tmux, no pid) renders alive when state is non-terminal (overstory-7a34)", () => {
+		// Repro: freshly slung headless lead has tmuxSession='' and pid=null.
+		// Previously fell into the tmux path → never matched → red "x" while
+		// ov feed showed live tool events from the same agent.
+		const data = {
+			...makeDashboardData({}),
+			status: {
+				currentRunId: null,
+				agents: [
+					{
+						id: "sess-spt-1",
+						agentName: "freshly-slung",
+						capability: "lead",
+						worktreePath: "/tmp/wt/freshly-slung",
+						branchName: "overstory/freshly-slung/task-l1",
+						taskId: "task-l1",
+						tmuxSession: "", // headless
+						state: "working" as const,
+						pid: null, // spawn-per-turn: no persistent process between turns
+						parentAgent: null,
+						depth: 0,
+						runId: null,
+						startedAt: new Date(Date.now() - 5_000).toISOString(),
+						lastActivity: new Date().toISOString(),
+						escalationLevel: 0,
+						stalledSince: null,
+						transcriptPath: null,
+					},
+				],
+				worktrees: [],
+				tmuxSessions: [],
+				unreadMailCount: 0,
+				unreadMailScope: "orchestrator",
+				mergeQueueCount: 0,
+				recentMetricsCount: 0,
+			},
+		};
+		const out = renderAgentPanel(data, 100, 12, 3);
+		expect(out).toContain("freshly-slung");
+		// Green ">" — agent is logically alive between turns
+		expect(out).toContain(">");
+		// No red marker should be present (name 'freshly-slung' has no 'x')
+		expect(out).not.toContain("x");
+	});
+
+	test("spawn-per-turn worker in zombie state renders dead marker (overstory-7a34)", () => {
+		const data = {
+			...makeDashboardData({}),
+			status: {
+				currentRunId: null,
+				agents: [
+					{
+						id: "sess-spt-2",
+						agentName: "abandoned-spt",
+						capability: "builder",
+						worktreePath: "/tmp/wt/abandoned-spt",
+						branchName: "overstory/abandoned-spt/task-a1",
+						taskId: "task-a1",
+						tmuxSession: "",
+						state: "zombie" as const,
+						pid: null,
+						parentAgent: null,
+						depth: 0,
+						runId: null,
+						startedAt: new Date(Date.now() - 600_000).toISOString(),
+						lastActivity: new Date(Date.now() - 600_000).toISOString(),
+						escalationLevel: 0,
+						stalledSince: null,
+						transcriptPath: null,
+					},
+				],
+				worktrees: [],
+				tmuxSessions: [],
+				unreadMailCount: 0,
+				unreadMailScope: "orchestrator",
+				mergeQueueCount: 0,
+				recentMetricsCount: 0,
+			},
+		};
+		const out = renderAgentPanel(data, 100, 12, 3);
+		expect(out).toContain("abandoned-spt");
+		expect(out).toContain("x");
+	});
+
+	test("headless agent renders dead marker when tmux session list is non-empty", () => {
+		const deadPid = 2_147_483_647;
+		const data = {
+			...makeDashboardData({}),
+			status: {
+				currentRunId: null,
+				agents: [
+					{
+						id: "sess-dead-headless-1",
+						agentName: "gone-headless",
+						capability: "builder",
+						worktreePath: "/tmp/wt/gone-headless",
+						branchName: "overstory/gone-headless/task-g1",
+						taskId: "task-g1",
+						tmuxSession: "", // headless
+						state: "working" as const,
+						pid: deadPid,
+						parentAgent: null,
+						depth: 0,
+						runId: null,
+						startedAt: new Date(Date.now() - 10_000).toISOString(),
+						lastActivity: new Date().toISOString(),
+						escalationLevel: 0,
+						stalledSince: null,
+						transcriptPath: null,
+					},
+				],
+				worktrees: [],
+				tmuxSessions: [{ name: "overstory-other-tmux", pid: 11111 }],
+				unreadMailCount: 0,
+				unreadMailScope: "orchestrator",
+				mergeQueueCount: 0,
+				recentMetricsCount: 0,
+			},
+		};
+		const out = renderAgentPanel(data, 100, 12, 3);
+		expect(out).toContain("x");
+		expect(out).toContain("gone-headless");
+	});
 });
 
 describe("openDashboardStores", () => {

package/src/commands/dashboard.ts

@@ -434,6 +434,7 @@ async function loadDashboardData(
 		worktrees,
 		tmuxSessions,
 		unreadMailCount,
+		unreadMailScope: "orchestrator",
 		mergeQueueCount,
 		recentMetricsCount,
 	};
@@ -614,7 +615,7 @@ export function renderAgentPanel(
 
 	// Sort agents: active first, then completed, then zombie
 	const agents = [...data.status.agents].sort((a, b) => {
-		const activeStates = ["working", "booting", "stalled"];
+		const activeStates = ["working", "in_turn", "between_turns", "booting", "stalled"];
 		const aActive = activeStates.includes(a.state);
 		const bActive = activeStates.includes(b.state);
 		if (aActive && !bActive) return -1;
@@ -644,10 +645,19 @@ export function renderAgentPanel(
 				: now;
 		const duration = formatDuration(endTime - new Date(agent.startedAt).getTime());
 		const durationPadded = pad(duration, 9);
+		// Three liveness topologies (overstory-7a34):
+		//   tmux:           tmuxSession !== ""        → tmux session must exist
+		//   long-lived headless: tmuxSession === "" && pid !== null → PID must be alive
+		//   spawn-per-turn: tmuxSession === "" && pid === null   → no process between
+		//     turns is normal, so liveness reduces to "state is non-terminal".
+		//     Time-based stale/zombie classification is handled in evaluateHealth.
 		const isHeadless = agent.tmuxSession === "" && agent.pid !== null;
-		const alive = isHeadless
-			? agent.pid !== null && isProcessAlive(agent.pid)
-			: data.status.tmuxSessions.some((s) => s.name === agent.tmuxSession);
+		const isSpawnPerTurn = agent.tmuxSession === "" && agent.pid === null;
+		const alive = isSpawnPerTurn
+			? agent.state !== "zombie" && agent.state !== "completed"
+			: isHeadless
+				? agent.pid !== null && isProcessAlive(agent.pid)
+				: data.status.tmuxSessions.some((s) => s.name === agent.tmuxSession);
 		const aliveDot = alive ? color.green(">") : color.red("x");
 
 		const lineContent = `${dimBox.vertical} ${stateColorFn(icon)}  ${name} ${capability} ${color.dim(runtime)} ${stateColorFn(state)} ${taskId} ${durationPadded} ${aliveDot}    `;

package/src/commands/doctor.ts

@@ -16,6 +16,7 @@ import { checkEcosystem } from "../doctor/ecosystem.ts";
 import { checkLogs } from "../doctor/logs.ts";
 import { checkMergeQueue } from "../doctor/merge-queue.ts";
 import { checkProviders } from "../doctor/providers.ts";
+import { checkServe } from "../doctor/serve.ts";
 import { checkStructure } from "../doctor/structure.ts";
 import type { DoctorCategory, DoctorCheck, DoctorCheckFn } from "../doctor/types.ts";
 import { checkVersion } from "../doctor/version.ts";
@@ -39,6 +40,7 @@ const ALL_CHECKS: Array<{ category: DoctorCategory; fn: DoctorCheckFn }> = [
 	{ category: "ecosystem", fn: checkEcosystem },
 	{ category: "providers", fn: checkProviders },
 	{ category: "watchdog", fn: checkWatchdog },
+	{ category: "serve", fn: checkServe },
 ];
 
 /**
@@ -241,7 +243,7 @@ function buildDoctorCommand(
 		.option("--fix", "Attempt to auto-fix issues")
 		.addHelpText(
 			"after",
-			"\nCategories: dependencies, structure, config, databases, consistency, agents, merge, logs, version, ecosystem, providers, watchdog",
+			"\nCategories: dependencies, structure, config, databases, consistency, agents, merge, logs, version, ecosystem, providers, watchdog, serve",
 		)
 		.action(async (opts: DoctorActionOpts) => {
 			onResult(await runDoctorChecks(opts, checkRunners));