@os-eco/overstory-cli 0.9.4 → 0.11.0

package/src/commands/watch.ts

@@ -13,7 +13,13 @@ import { jsonOutput } from "../json.ts";
 import { printError, printHint, printSuccess } from "../logging/color.ts";
 import type { HealthCheck } from "../types.ts";
 import { resolveOverstoryBin } from "../utils/bin.ts";
-import { readPidFile, removePidFile, writePidFile } from "../utils/pid.ts";
+import {
+	type AcquirePidLockResult,
+	acquirePidLock,
+	readPidFile,
+	removePidFile,
+} from "../utils/pid.ts";
+import { findRunningWatchdogProcesses, type WatchdogProcess } from "../utils/process-scan.ts";
 import { startDaemon } from "../watchdog/daemon.ts";
 import { isProcessRunning } from "../watchdog/health.ts";
 
@@ -38,6 +44,39 @@ export function formatCheck(check: HealthCheck): string {
 	return line;
 }
 
+/**
+ * Format a "lock contested" error consistently across foreground/background.
+ */
+function formatLockContestedError(existingPid: number, pidFilePath: string): string {
+	if (existingPid <= 0) {
+		return `Watchdog PID file at ${pidFilePath} is owned by another process (could not read PID). Run 'ov watch --kill-others' or remove the file.`;
+	}
+	return `Watchdog already running (PID: ${existingPid}). Kill it first, run 'ov watch --kill-others', or remove ${pidFilePath}`;
+}
+
+/**
+ * Kill running `ov watch` daemons that are NOT the given excludedPid.
+ * Returns the list of PIDs killed (after a SIGTERM was issued — not waited).
+ */
+async function killForeignWatchdogs(
+	excludedPid: number | null,
+): Promise<{ killed: number[]; surveyed: WatchdogProcess[] }> {
+	const surveyed = await findRunningWatchdogProcesses();
+	const killed: number[] = [];
+	for (const proc of surveyed) {
+		if (excludedPid !== null && proc.pid === excludedPid) {
+			continue;
+		}
+		try {
+			process.kill(proc.pid, "SIGTERM");
+			killed.push(proc.pid);
+		} catch {
+			// Process already gone — not an error.
+		}
+	}
+	return { killed, surveyed };
+}
+
 /**
  * Core implementation for the watch command.
  */
@@ -45,6 +84,7 @@ async function runWatch(opts: {
 	interval?: string;
 	background?: boolean;
 	json?: boolean;
+	killOthers?: boolean;
 }): Promise<void> {
 	const cwd = process.cwd();
 	const config = await loadConfig(cwd);
@@ -59,26 +99,46 @@ async function runWatch(opts: {
 
 	const useJson = opts.json ?? false;
 
-	if (opts.background) {
-		// Check if a watchdog is already running
-		const existingPid = await readPidFile(pidFilePath);
-		if (existingPid !== null && isProcessRunning(existingPid)) {
-			if (useJson) {
-				jsonOutput("watch", { running: true, pid: existingPid, error: "Watchdog already running" });
-			} else {
-				printError(
-					`Watchdog already running (PID: ${existingPid}). Kill it first or remove ${pidFilePath}`,
-				);
+	// --kill-others: kill any pre-existing `ov watch` daemons before claiming
+	// the lock. Useful when an earlier release allowed multi-daemon state.
+	if (opts.killOthers) {
+		const { killed } = await killForeignWatchdogs(null);
+
+		// Wait for the just-killed processes to actually exit before reclaiming
+		// the PID file. Without this, the next acquirePidLock call sees a still-
+		// alive PID in the file and refuses, even though we issued SIGTERM
+		// nanoseconds earlier. Poll for up to ~2s.
+		const killedSet = new Set(killed);
+		if (killedSet.size > 0) {
+			const deadline = Date.now() + 2000;
+			while (Date.now() < deadline) {
+				const stillAlive = killed.filter((p) => isProcessRunning(p));
+				if (stillAlive.length === 0) break;
+				await Bun.sleep(50);
 			}
-			process.exitCode = 1;
-			return;
 		}
 
-		// Clean up stale PID file if process is no longer running
+		// Reclaim the PID file if it pointed at a process we just killed (it is
+		// either already dead or in flight to dead) or at any other dead PID.
+		const existingPid = await readPidFile(pidFilePath);
 		if (existingPid !== null) {
-			await removePidFile(pidFilePath);
+			if (killedSet.has(existingPid) || !isProcessRunning(existingPid)) {
+				await removePidFile(pidFilePath);
+			}
 		}
 
+		if (killed.length > 0) {
+			if (useJson) {
+				jsonOutput("watch", { killed });
+			} else {
+				printSuccess(`Killed ${killed.length} foreign watchdog process(es): ${killed.join(", ")}`);
+			}
+		} else if (!useJson) {
+			printHint("No foreign watchdog processes found.");
+		}
+	}
+
+	if (opts.background) {
 		// Build the args for the child process, forwarding --interval but not --background
 		const childArgs: string[] = ["watch"];
 		if (opts.interval) {
@@ -88,7 +148,21 @@ async function runWatch(opts: {
 		// Resolve the overstory binary path
 		const overstoryBin = await resolveOverstoryBin();
 
-		// Spawn a detached background process running `overstory watch` (without --background)
+		// Pre-check: surface "already running" before paying the cost of a spawn.
+		// This is only for friendly errors — the authoritative exclusion happens
+		// in the atomic acquirePidLock call below.
+		const existingPid = await readPidFile(pidFilePath);
+		if (existingPid !== null && isProcessRunning(existingPid)) {
+			if (useJson) {
+				jsonOutput("watch", { running: true, pid: existingPid, error: "Watchdog already running" });
+			} else {
+				printError(formatLockContestedError(existingPid, pidFilePath));
+			}
+			process.exitCode = 1;
+			return;
+		}
+
+		// Spawn the detached background daemon (foreground mode in the child).
 		const child = Bun.spawn(["bun", "run", overstoryBin, ...childArgs], {
 			cwd,
 			stdout: "ignore",
@@ -96,13 +170,33 @@ async function runWatch(opts: {
 			stdin: "ignore",
 		});
 
-		// Unref the child so the parent can exit without waiting for it
-		child.unref();
-
 		const childPid = child.pid;
 
-		// Write PID file for later cleanup
-		await writePidFile(pidFilePath, childPid);
+		// Atomically acquire the lock with the child's PID. If another writer
+		// raced in between our pre-check and the spawn, we have to kill our
+		// child and report contention.
+		const lockResult = await acquirePidLock(pidFilePath, childPid, isProcessRunning);
+		if (!lockResult.acquired) {
+			try {
+				child.kill("SIGTERM");
+			} catch {
+				// Already exited — not an error.
+			}
+			if (useJson) {
+				jsonOutput("watch", {
+					running: true,
+					pid: lockResult.existingPid,
+					error: "Watchdog already running",
+				});
+			} else {
+				printError(formatLockContestedError(lockResult.existingPid, pidFilePath));
+			}
+			process.exitCode = 1;
+			return;
+		}
+
+		// Lock is ours. Detach so this parent invocation can exit independently.
+		child.unref();
 
 		if (useJson) {
 			jsonOutput("watch", { pid: childPid, intervalMs, pidFile: pidFilePath });
@@ -113,7 +207,29 @@ async function runWatch(opts: {
 		return;
 	}
 
-	// Foreground mode: show real-time health checks
+	// Foreground mode: acquire the lock atomically before announcing anything.
+	// In the background-spawn case the parent has already written this PID into
+	// the lock file; acquirePidLock detects own-PID and returns acquired=true
+	// idempotently.
+	const lockResult: AcquirePidLockResult = await acquirePidLock(
+		pidFilePath,
+		process.pid,
+		isProcessRunning,
+	);
+	if (!lockResult.acquired) {
+		if (useJson) {
+			jsonOutput("watch", {
+				running: true,
+				pid: lockResult.existingPid,
+				error: "Watchdog already running",
+			});
+		} else {
+			printError(formatLockContestedError(lockResult.existingPid, pidFilePath));
+		}
+		process.exitCode = 1;
+		return;
+	}
+
 	if (useJson) {
 		jsonOutput("watch", { pid: process.pid, intervalMs, mode: "foreground" });
 	} else {
@@ -121,9 +237,6 @@ async function runWatch(opts: {
 		printHint("Press Ctrl+C to stop.");
 	}
 
-	// Write PID file so `--background` check and external tools can find us
-	await writePidFile(pidFilePath, process.pid);
-
 	const { stop } = startDaemon({
 		root: config.project.root,
 		intervalMs,
@@ -131,6 +244,7 @@ async function runWatch(opts: {
 		zombieThresholdMs,
 		nudgeIntervalMs: config.watchdog.nudgeIntervalMs,
 		tier1Enabled: config.watchdog.tier1Enabled,
+		notifyParentOnDeath: config.watchdog.notifyParentOnDeath ?? true,
 		onHealthCheck(check) {
 			const timestamp = new Date().toISOString().slice(11, 19);
 			process.stdout.write(`[${timestamp}] ${formatCheck(check)}\n`);
@@ -156,10 +270,21 @@ export function createWatchCommand(): Command {
 		.description("Start Tier 0 mechanical watchdog daemon")
 		.option("--interval <ms>", "Health check interval in milliseconds")
 		.option("--background", "Daemonize (run in background)")
+		.option(
+			"--kill-others",
+			"Kill any pre-existing 'ov watch' processes before starting (for cleanup of multi-daemon state)",
+		)
 		.option("--json", "Output as JSON")
-		.action(async (opts: { interval?: string; background?: boolean; json?: boolean }) => {
-			await runWatch(opts);
-		});
+		.action(
+			async (opts: {
+				interval?: string;
+				background?: boolean;
+				killOthers?: boolean;
+				json?: boolean;
+			}) => {
+				await runWatch(opts);
+			},
+		);
 }
 
 /**

package/src/config.ts

@@ -90,6 +90,7 @@ export const DEFAULT_CONFIG: OverstoryConfig = {
 		rpcTimeoutMs: 5_000, // 5 seconds for RPC getState() calls
 		triageTimeoutMs: 30_000, // 30 seconds for Tier 1 AI triage calls
 		maxEscalationLevel: 3, // Maximum escalation level before termination
+		notifyParentOnDeath: true, // Send worker_died mail to parent when watchdog terminates a child
 	},
 	coordinator: {
 		exitTriggers: {
@@ -633,6 +634,16 @@ function validateConfig(config: OverstoryConfig): void {
 		}
 	}
 
+	if (
+		config.watchdog.notifyParentOnDeath !== undefined &&
+		typeof config.watchdog.notifyParentOnDeath !== "boolean"
+	) {
+		throw new ValidationError("watchdog.notifyParentOnDeath must be a boolean", {
+			field: "watchdog.notifyParentOnDeath",
+			value: config.watchdog.notifyParentOnDeath,
+		});
+	}
+
 	// mulch.primeFormat must be one of the valid options
 	const validFormats = ["markdown", "xml", "json"] as const;
 	if (!validFormats.includes(config.mulch.primeFormat as (typeof validFormats)[number])) {
@@ -774,6 +785,18 @@ function validateConfig(config: OverstoryConfig): void {
 		}
 	}
 
+	// runtime.claudeHeadlessByDefault: must be a boolean if present
+	if (
+		config.runtime?.claudeHeadlessByDefault !== undefined &&
+		typeof config.runtime.claudeHeadlessByDefault !== "boolean"
+	) {
+		process.stderr.write(
+			`[overstory] WARNING: runtime.claudeHeadlessByDefault must be a boolean. Got: ${typeof config
+				.runtime.claudeHeadlessByDefault}. Ignoring.\n`,
+		);
+		config.runtime.claudeHeadlessByDefault = undefined;
+	}
+
 	if (config.runtime?.capabilities) {
 		for (const [cap, runtimeName] of Object.entries(config.runtime.capabilities)) {
 			if (runtimeName !== undefined && (typeof runtimeName !== "string" || runtimeName === "")) {

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

@@ -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 {