@os-eco/overstory-cli 0.9.3 → 0.10.3

package/src/doctor/consistency.test.ts

@@ -410,6 +410,112 @@ describe("checkConsistency", () => {
 		expect(checks.find((c) => c.name === "missing-tmux")?.status).toBe("pass");
 	});
 
+	test("orphan-spawns: terminal state with live pid is flagged", async () => {
+		const dbPath = join(overstoryDir, "sessions.db");
+		const store = createSessionStore(dbPath);
+
+		store.upsert({
+			id: "session-1",
+			agentName: "orphaned-agent",
+			capability: "builder",
+			worktreePath: join(overstoryDir, "worktrees", "orphaned-agent"),
+			branchName: "overstory/orphaned-agent/test-123",
+			taskId: "test-123",
+			tmuxSession: "",
+			state: "completed",
+			pid: 4242,
+			parentAgent: null,
+			depth: 0,
+			runId: null,
+			startedAt: new Date().toISOString(),
+			lastActivity: new Date().toISOString(),
+			escalationLevel: 0,
+			stalledSince: null,
+			transcriptPath: null,
+		});
+		store.close();
+
+		mockIsProcessAlive.mockReturnValue(true);
+		mockListSessions.mockResolvedValue([]);
+
+		const checks = await checkConsistency(config, overstoryDir, mockDeps);
+
+		const orphanCheck = checks.find((c) => c.name === "orphan-spawns");
+		expect(orphanCheck).toBeDefined();
+		expect(orphanCheck?.status).toBe("warn");
+		expect(orphanCheck?.message).toContain("1 orphaned spawn");
+		expect(orphanCheck?.details?.[0]).toContain("orphaned-agent");
+		expect(orphanCheck?.fixable).toBe(true);
+	});
+
+	test("orphan-spawns: tmux dead but pid alive is flagged", async () => {
+		const dbPath = join(overstoryDir, "sessions.db");
+		const store = createSessionStore(dbPath);
+
+		store.upsert({
+			id: "session-1",
+			agentName: "tmux-dead-agent",
+			capability: "builder",
+			worktreePath: join(overstoryDir, "worktrees", "tmux-dead-agent"),
+			branchName: "overstory/tmux-dead-agent/test-123",
+			taskId: "test-123",
+			tmuxSession: "overstory-testproject-tmux-dead-agent",
+			state: "working",
+			pid: 4242,
+			parentAgent: null,
+			depth: 0,
+			runId: null,
+			startedAt: new Date().toISOString(),
+			lastActivity: new Date().toISOString(),
+			escalationLevel: 0,
+			stalledSince: null,
+			transcriptPath: null,
+		});
+		store.close();
+
+		mockIsProcessAlive.mockReturnValue(true);
+		// tmux server reports no matching session
+		mockListSessions.mockResolvedValue([]);
+
+		const checks = await checkConsistency(config, overstoryDir, mockDeps);
+
+		const orphanCheck = checks.find((c) => c.name === "orphan-spawns");
+		expect(orphanCheck?.status).toBe("warn");
+		expect(orphanCheck?.details?.[0]).toContain("tmux session");
+	});
+
+	test("orphan-spawns: passes when terminal-state pid is dead", async () => {
+		const dbPath = join(overstoryDir, "sessions.db");
+		const store = createSessionStore(dbPath);
+
+		store.upsert({
+			id: "session-1",
+			agentName: "clean-completed",
+			capability: "builder",
+			worktreePath: join(overstoryDir, "worktrees", "clean-completed"),
+			branchName: "overstory/clean-completed/test-123",
+			taskId: "test-123",
+			tmuxSession: "",
+			state: "completed",
+			pid: 4242,
+			parentAgent: null,
+			depth: 0,
+			runId: null,
+			startedAt: new Date().toISOString(),
+			lastActivity: new Date().toISOString(),
+			escalationLevel: 0,
+			stalledSince: null,
+			transcriptPath: null,
+		});
+		store.close();
+
+		mockIsProcessAlive.mockReturnValue(false);
+
+		const checks = await checkConsistency(config, overstoryDir, mockDeps);
+
+		expect(checks.find((c) => c.name === "orphan-spawns")?.status).toBe("pass");
+	});
+
 	test("handles tmux not installed gracefully", async () => {
 		// Mock tmux listing to throw an error
 		mockListSessions.mockRejectedValue(new Error("tmux: command not found"));

package/src/doctor/consistency.ts

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { openSessionStore } from "../sessions/compat.ts";
 import type { AgentSession, OverstoryConfig } from "../types.ts";
 import { listWorktrees } from "../worktree/manager.ts";
-import { isProcessAlive, listSessions } from "../worktree/tmux.ts";
+import { isProcessAlive, listSessions, sanitizeTmuxName } from "../worktree/tmux.ts";
 import type { DoctorCheck } from "./types.ts";
 
 /**
@@ -134,7 +134,7 @@ export async function checkConsistency(
 
 	// 5. Check for orphaned tmux sessions (tmux session exists but no SessionStore entry)
 	const projectName = config.project.name;
-	const overstoryTmuxPrefix = `overstory-${projectName}-`;
+	const overstoryTmuxPrefix = `overstory-${sanitizeTmuxName(projectName)}-`;
 	const overstoryTmuxSessions = tmuxSessions.filter((s) => s.name.startsWith(overstoryTmuxPrefix));
 	const storeTmuxNames = new Set(storeSessions.map((s) => s.tmuxSession));
 
@@ -212,7 +212,9 @@ export async function checkConsistency(
 
 	// 8. Check for SessionStore entries with missing tmux sessions
 	const existingTmuxNames = new Set(tmuxSessions.map((s) => s.name));
-	const missingTmux = liveSessions.filter((s) => !existingTmuxNames.has(s.tmuxSession));
+	const missingTmux = liveSessions.filter(
+		(s) => s.tmuxSession.length > 0 && !existingTmuxNames.has(s.tmuxSession),
+	);
 
 	if (missingTmux.length > 0) {
 		checks.push({
@@ -232,6 +234,51 @@ export async function checkConsistency(
 		});
 	}
 
+	// 8b. Check for orphaned claude spawn PIDs (overstory-505d).
+	//
+	// An orphan is a session whose pid is still alive but should not be:
+	//   - the session reached a terminal state (completed/zombie) yet the
+	//     spawn didn't exit, or
+	//   - the tmux container is gone but the claude child survived (was
+	//     reparented to init when its bash wrapper got SIGHUP).
+	// Run `ov clean --all` to reap. Distinct from `dead-pids` (the inverse:
+	// session is live but its pid already died).
+	const orphanedSpawns: Array<{ session: AgentSession; reason: string }> = [];
+	for (const s of storeSessions) {
+		if (s.pid === null || !isProcessAliveFn(s.pid)) continue;
+		if (s.state === "completed" || s.state === "zombie") {
+			orphanedSpawns.push({
+				session: s,
+				reason: `state=${s.state} but pid ${s.pid} still alive`,
+			});
+			continue;
+		}
+		if (s.tmuxSession.length > 0 && !existingTmuxNames.has(s.tmuxSession)) {
+			orphanedSpawns.push({
+				session: s,
+				reason: `tmux session "${s.tmuxSession}" missing but pid ${s.pid} alive`,
+			});
+		}
+	}
+
+	if (orphanedSpawns.length > 0) {
+		checks.push({
+			name: "orphan-spawns",
+			category: "consistency",
+			status: "warn",
+			message: `Found ${orphanedSpawns.length} orphaned spawn process(es) — run "ov clean --all" to reap`,
+			details: orphanedSpawns.map(({ session, reason }) => `${session.agentName}: ${reason}`),
+			fixable: true,
+		});
+	} else {
+		checks.push({
+			name: "orphan-spawns",
+			category: "consistency",
+			status: "pass",
+			message: "No orphaned spawn processes detected",
+		});
+	}
+
 	// 9. Check reviewer-to-builder ratio per lead
 	const parentGroups = new Map<string, { builders: number; reviewers: number }>();
 	for (const session of storeSessions) {

package/src/doctor/serve.test.ts

@@ -0,0 +1,95 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { OverstoryConfig } from "../types.ts";
+import { checkServe } from "./serve.ts";
+
+describe("checkServe", () => {
+	let tempDir: string;
+	let mockConfig: OverstoryConfig;
+
+	beforeEach(() => {
+		tempDir = mkdtempSync(join(tmpdir(), "overstory-serve-doctor-test-"));
+		mockConfig = {
+			project: { name: "test", root: tempDir, canonicalBranch: "main" },
+			agents: {
+				manifestPath: "",
+				baseDir: "",
+				maxConcurrent: 5,
+				staggerDelayMs: 100,
+				maxDepth: 2,
+				maxSessionsPerRun: 0,
+				maxAgentsPerLead: 5,
+			},
+			worktrees: { baseDir: "" },
+			taskTracker: { backend: "auto", enabled: true },
+			mulch: { enabled: true, domains: [], primeFormat: "markdown" },
+			merge: { aiResolveEnabled: false, reimagineEnabled: false },
+			providers: {
+				anthropic: { type: "native" },
+			},
+			watchdog: {
+				tier0Enabled: false,
+				tier0IntervalMs: 30000,
+				tier1Enabled: false,
+				tier2Enabled: false,
+				staleThresholdMs: 300000,
+				zombieThresholdMs: 600000,
+				nudgeIntervalMs: 60000,
+			},
+			models: {},
+			logging: { verbose: false, redactSecrets: true },
+		};
+	});
+
+	afterEach(() => {
+		rmSync(tempDir, { recursive: true, force: true });
+	});
+
+	test("ui/dist missing — returns warn about missing build", async () => {
+		const checks = await checkServe(mockConfig, tempDir);
+		const distCheck = checks.find((c) => c.name === "serve ui/dist");
+
+		expect(distCheck).toBeDefined();
+		expect(distCheck?.status).toBe("warn");
+		expect(distCheck?.message).toContain("ui/dist not found");
+		expect(distCheck?.details?.some((d) => d.includes("ui/dist"))).toBe(true);
+	});
+
+	test("ui/dist exists but index.html missing — returns warn about incomplete build", async () => {
+		mkdirSync(join(tempDir, "ui", "dist"), { recursive: true });
+		const checks = await checkServe(mockConfig, tempDir);
+		const distCheck = checks.find((c) => c.name === "serve ui/dist");
+
+		expect(distCheck).toBeDefined();
+		expect(distCheck?.status).toBe("warn");
+		expect(distCheck?.message).toContain("index.html is missing");
+	});
+
+	test("ui/dist with index.html — returns pass", async () => {
+		mkdirSync(join(tempDir, "ui", "dist"), { recursive: true });
+		writeFileSync(join(tempDir, "ui", "dist", "index.html"), "<html></html>");
+		const checks = await checkServe(mockConfig, tempDir);
+		const distCheck = checks.find((c) => c.name === "serve ui/dist");
+
+		expect(distCheck).toBeDefined();
+		expect(distCheck?.status).toBe("pass");
+		expect(distCheck?.message).toContain("index.html");
+	});
+
+	test("port check included in results", async () => {
+		const checks = await checkServe(mockConfig, tempDir);
+		const portCheck = checks.find((c) => c.name === "serve port");
+
+		expect(portCheck).toBeDefined();
+		// Server not running — should warn (or pass if something happens to be on the default port)
+		expect(portCheck?.status === "warn" || portCheck?.status === "pass").toBe(true);
+	});
+
+	test("returns exactly 2 checks (ui/dist + port)", async () => {
+		const checks = await checkServe(mockConfig, tempDir);
+		expect(checks).toHaveLength(2);
+		expect(checks.map((c) => c.category).every((cat) => cat === "serve")).toBe(true);
+	});
+});

package/src/doctor/serve.ts

@@ -0,0 +1,86 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { DEFAULT_SERVE_PORT } from "../commands/serve.ts";
+import type { DoctorCheck, DoctorCheckFn } from "./types.ts";
+
+/**
+ * ov serve subsystem health checks.
+ * Validates ui/dist build output and port reachability.
+ */
+export const checkServe: DoctorCheckFn = async (config, _overstoryDir): Promise<DoctorCheck[]> => {
+	const checks: DoctorCheck[] = [];
+
+	// Check 1: ui/dist directory exists (only relevant if a UI has been built)
+	const uiDistPath = join(config.project.root, "ui", "dist");
+	const uiDistExists = existsSync(uiDistPath);
+	const indexHtmlExists = uiDistExists && existsSync(join(uiDistPath, "index.html"));
+
+	if (!uiDistExists) {
+		checks.push({
+			name: "serve ui/dist",
+			category: "serve",
+			status: "warn",
+			message: "ui/dist not found — run the UI build before starting ov serve",
+			details: [`Expected: ${uiDistPath}`],
+		});
+	} else if (!indexHtmlExists) {
+		checks.push({
+			name: "serve ui/dist",
+			category: "serve",
+			status: "warn",
+			message: "ui/dist exists but index.html is missing — UI build may be incomplete",
+			details: [`Expected: ${join(uiDistPath, "index.html")}`],
+		});
+	} else {
+		checks.push({
+			name: "serve ui/dist",
+			category: "serve",
+			status: "pass",
+			message: "ui/dist is present with index.html",
+		});
+	}
+
+	// Check 2: default port reachability (non-blocking probe)
+	const port = DEFAULT_SERVE_PORT;
+	const host = "127.0.0.1";
+	const reachable = await probePort(host, port);
+	if (reachable) {
+		checks.push({
+			name: "serve port",
+			category: "serve",
+			status: "pass",
+			message: `ov serve is reachable on ${host}:${port}`,
+		});
+	} else {
+		checks.push({
+			name: "serve port",
+			category: "serve",
+			status: "warn",
+			message: `ov serve is not running on ${host}:${port}`,
+			details: [`Start with: ov serve --port ${port}`],
+		});
+	}
+
+	return checks;
+};
+
+/**
+ * Probe whether a TCP port is open by attempting an HTTP connection.
+ * Returns true if the server responds, false on any error.
+ */
+async function probePort(host: string, port: number): Promise<boolean> {
+	try {
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), 1000);
+		try {
+			const res = await fetch(`http://${host}:${port}/healthz`, {
+				signal: controller.signal,
+			});
+			return res.ok || res.status < 500;
+		} finally {
+			clearTimeout(timeout);
+		}
+	} catch {
+		return false;
+	}
+}

package/src/doctor/types.ts

@@ -15,7 +15,8 @@ export type DoctorCategory =
 	| "version"
 	| "ecosystem"
 	| "providers"
-	| "watchdog";
+	| "watchdog"
+	| "serve";
 
 /** Result of a single doctor health check. */
 export interface DoctorCheck {

package/src/doctor/watchdog.ts

@@ -3,6 +3,7 @@ import { stat, unlink } from "node:fs/promises";
 import { join } from "node:path";
 import { getRuntime } from "../runtimes/registry.ts";
 import { openSessionStore } from "../sessions/compat.ts";
+import { findRunningWatchdogProcesses } from "../utils/process-scan.ts";
 import { isProcessRunning } from "../watchdog/health.ts";
 import type { DoctorCheck, DoctorCheckFn } from "./types.ts";
 
@@ -134,7 +135,62 @@ export const checkWatchdog: DoctorCheckFn = async (
 		}
 	}
 
-	// Check 6: Tier 1 triage available if tier1Enabled
+	// Check 6: multi-daemon detection (overstory-8ef6).
+	// Earlier releases had no exclusion lock, so multiple `ov watch` daemons
+	// could run simultaneously. We scan the process table for `ov watch`
+	// processes and flag any case with more than one. This is observational —
+	// even with the lock now in place, a corrupted/missing PID file could
+	// still let a foreign daemon slip past, and we want doctor to catch it.
+	try {
+		const watchProcs = await findRunningWatchdogProcesses();
+		if (watchProcs.length > 1) {
+			const lockOwner = existsSync(pidFilePath)
+				? Number.parseInt((await Bun.file(pidFilePath).text()).trim(), 10)
+				: Number.NaN;
+			const lockOwnerLabel = Number.isFinite(lockOwner) ? `${lockOwner}` : "(none)";
+			const pidList = watchProcs.map((p) => p.pid).join(", ");
+			checks.push({
+				name: "watchdog multi-daemon",
+				category: "watchdog",
+				status: "fail",
+				message: `${watchProcs.length} 'ov watch' daemons running concurrently — only one should be live`,
+				details: [
+					`Live PIDs: ${pidList}`,
+					`PID-file owner: ${lockOwnerLabel}`,
+					"Run 'ov watch --kill-others' to terminate the foreign daemons.",
+				],
+				fixable: true,
+				fix: async () => {
+					const ownerPid = Number.isFinite(lockOwner) ? lockOwner : null;
+					const messages: string[] = [];
+					for (const proc of watchProcs) {
+						if (proc.pid === ownerPid) continue;
+						try {
+							process.kill(proc.pid, "SIGTERM");
+							messages.push(`Killed foreign watchdog PID ${proc.pid}`);
+						} catch {
+							messages.push(`PID ${proc.pid} already gone`);
+						}
+					}
+					if (messages.length === 0) {
+						messages.push("No foreign watchdogs to kill — fix is a no-op");
+					}
+					return messages;
+				},
+			});
+		}
+	} catch {
+		// Process scan failure is non-fatal — leave a soft warning instead of
+		// failing the whole doctor run.
+		checks.push({
+			name: "watchdog multi-daemon",
+			category: "watchdog",
+			status: "warn",
+			message: "Could not scan process table for foreign 'ov watch' daemons",
+		});
+	}
+
+	// Check 7: Tier 1 triage available if tier1Enabled
 	if (config.watchdog.tier1Enabled) {
 		try {
 			getRuntime(config?.runtime?.printCommand ?? config?.runtime?.default, config);