@os-eco/overstory-cli 0.9.2 → 0.9.4

package/README.md

@@ -10,6 +10,8 @@ Overstory turns a single coding session into a multi-agent team by spawning work
 
 > **Warning: Agent swarms are not a universal solution.** Do not deploy Overstory without understanding the risks of multi-agent orchestration — compounding error rates, cost amplification, debugging complexity, and merge conflicts are the normal case, not edge cases. Read [STEELMAN.md](STEELMAN.md) for a full risk analysis and the [Agentic Engineering Book](https://github.com/jayminwest/agentic-engineering-book) ([web version](https://jayminwest.com/agentic-engineering-book)) before using this tool in production.
 
+> **Maintenance status.** Overstory is maintained part-time. PRs are reviewed in roughly 2-week batches; PRs inactive for 30+ days are closed (reopen anytime). For features larger than ~200 lines, open an issue or discussion first. See [CONTRIBUTING.md](CONTRIBUTING.md#review-cadence).
+
 ## Install
 
 Requires [Bun](https://bun.sh) v1.0+, git, and tmux. At least one supported agent runtime must be installed:
@@ -295,6 +297,7 @@ overstory/
       checkpoint.ts               Session checkpoint save/restore
       lifecycle.ts                Handoff orchestration
       hooks-deployer.ts           Deploy hooks + tool enforcement
+      copilot-hooks-deployer.ts   Deploy hooks config to Copilot worktrees
       guard-rules.ts              Shared guard constants (tool lists, bash patterns)
     worktree/                     Git worktree + tmux management
     mail/                         SQLite mail system (typed protocol, broadcast)

package/agents/coordinator.md

@@ -319,16 +319,16 @@ When a batch is complete (task group auto-closed, all issues resolved):
 4. **Only then** close the issue: `{{TRACKER_CLI}} close <id> --reason "Merged branch <branch-name>"`.
 
 1. Verify all issues are closed: run `{{TRACKER_CLI}} show <id>` for each issue in the group.
-2. Verify all branches are merged: check `ov status` for unmerged branches. If any branch is unmerged, do NOT proceed — wait for the lead's `merge_ready` signal.
-3. Clean up worktrees: `ov worktree clean --completed`.
-4. Record orchestration insights: `ml record <domain> --type <type> --classification <foundational|tactical|observational> --description "<insight>"`.
-5. Commit and sync state files: after all work is merged and issues are closed, commit any outstanding state changes so runtime state is not left uncommitted when the coordinator goes idle:
+2. Verify all branches are merged: check `ov status` for unmerged branches. If any branch is unmerged, do NOT proceed — wait for the lead's `merge_ready` signal. **Note:** merged branches carry each worker's committed `.mulch/` changes into the canonical branch — this is how discovery scout findings reach the main repo.
+3. Record orchestration insights: `ml record <domain> --type <type> --classification <foundational|tactical|observational> --description "<insight>"`.
+4. Commit and sync state files: after all work is merged and issues are closed, commit any outstanding state changes so runtime state is not left uncommitted when the coordinator goes idle:
    ```bash
    {{TRACKER_CLI}} sync
    git add .overstory/ .mulch/
    git diff --cached --quiet || git commit -m "chore: sync runtime state"
    git push
    ```
+5. Clean up worktrees: `ov worktree clean --completed`. **Only run this after branches are merged and .mulch/ state is committed** — cleaning worktrees before merging destroys any uncommitted scout findings.
 6. Report to the human operator: summarize what was accomplished, what was merged, any issues encountered.
 7. Check for follow-up work: `{{TRACKER_CLI}} ready` to see if new issues surfaced during the batch.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@os-eco/overstory-cli",
-	"version": "0.9.2",
+	"version": "0.9.4",
 	"description": "Multi-agent orchestration for AI coding agents — spawn workers in git worktrees via tmux, coordinate through SQLite mail, merge with tiered conflict resolution. Pluggable runtime adapters for Claude Code, Pi, and more.",
 	"author": "Jaymin West",
 	"license": "MIT",

package/src/agents/copilot-hooks-deployer.test.ts

@@ -0,0 +1,162 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { cleanupTempDir } from "../test-helpers.ts";
+import { deployCopilotHooks } from "./copilot-hooks-deployer.ts";
+import { PATH_PREFIX } from "./hooks-deployer.ts";
+
+describe("deployCopilotHooks", () => {
+	let tempDir: string;
+
+	beforeEach(async () => {
+		tempDir = await mkdtemp(join(tmpdir(), "overstory-copilot-hooks-test-"));
+	});
+
+	afterEach(async () => {
+		await cleanupTempDir(tempDir);
+	});
+
+	test("writes hooks.json to .github/hooks/ directory", async () => {
+		const worktreePath = join(tempDir, "worktree");
+		await deployCopilotHooks(worktreePath, "my-builder");
+
+		const hooksPath = join(worktreePath, ".github", "hooks", "hooks.json");
+		const exists = await Bun.file(hooksPath).exists();
+		expect(exists).toBe(true);
+	});
+
+	test("creates .github/hooks/ directory if it does not exist", async () => {
+		const worktreePath = join(tempDir, "new-worktree");
+		// Directory does not exist before the call
+		await deployCopilotHooks(worktreePath, "builder-1");
+
+		const hooksPath = join(worktreePath, ".github", "hooks", "hooks.json");
+		expect(await Bun.file(hooksPath).exists()).toBe(true);
+	});
+
+	test("output file is valid JSON", async () => {
+		const worktreePath = join(tempDir, "worktree");
+		await deployCopilotHooks(worktreePath, "test-agent");
+
+		const hooksPath = join(worktreePath, ".github", "hooks", "hooks.json");
+		const raw = await Bun.file(hooksPath).text();
+		expect(() => JSON.parse(raw)).not.toThrow();
+	});
+
+	test("output has Copilot schema structure (top-level hooks with onSessionStart)", async () => {
+		const worktreePath = join(tempDir, "worktree");
+		await deployCopilotHooks(worktreePath, "test-agent");
+
+		const hooksPath = join(worktreePath, ".github", "hooks", "hooks.json");
+		const config = JSON.parse(await Bun.file(hooksPath).text()) as Record<string, unknown>;
+
+		expect(config).toHaveProperty("hooks");
+		const hooks = config.hooks as Record<string, unknown>;
+		expect(hooks).toHaveProperty("onSessionStart");
+		expect(Array.isArray(hooks.onSessionStart)).toBe(true);
+	});
+
+	test("replaces {{AGENT_NAME}} with agentName in all commands", async () => {
+		const worktreePath = join(tempDir, "worktree");
+		await deployCopilotHooks(worktreePath, "scout-agent-42");
+
+		const hooksPath = join(worktreePath, ".github", "hooks", "hooks.json");
+		const raw = await Bun.file(hooksPath).text();
+
+		expect(raw).toContain("scout-agent-42");
+		expect(raw).not.toContain("{{AGENT_NAME}}");
+	});
+
+	test("prepends PATH_PREFIX to all hook commands", async () => {
+		const worktreePath = join(tempDir, "worktree");
+		await deployCopilotHooks(worktreePath, "builder-1");
+
+		const hooksPath = join(worktreePath, ".github", "hooks", "hooks.json");
+		const config = JSON.parse(await Bun.file(hooksPath).text()) as {
+			hooks: Record<string, Array<{ command: string }>>;
+		};
+
+		const allCommands = Object.values(config.hooks)
+			.flat()
+			.map((e) => e.command);
+		expect(allCommands.length).toBeGreaterThan(0);
+		for (const cmd of allCommands) {
+			expect(cmd).toStartWith(PATH_PREFIX);
+		}
+	});
+
+	test("onSessionStart entries are objects with command field only (no matcher, no type)", async () => {
+		const worktreePath = join(tempDir, "worktree");
+		await deployCopilotHooks(worktreePath, "builder-1");
+
+		const hooksPath = join(worktreePath, ".github", "hooks", "hooks.json");
+		const config = JSON.parse(await Bun.file(hooksPath).text()) as {
+			hooks: { onSessionStart: Array<Record<string, unknown>> };
+		};
+
+		for (const entry of config.hooks.onSessionStart) {
+			expect(typeof entry.command).toBe("string");
+			// Copilot schema has no matcher or type fields
+			expect(entry).not.toHaveProperty("matcher");
+			expect(entry).not.toHaveProperty("type");
+		}
+	});
+
+	test("onSessionStart includes ov prime command", async () => {
+		const worktreePath = join(tempDir, "worktree");
+		await deployCopilotHooks(worktreePath, "prime-test-agent");
+
+		const hooksPath = join(worktreePath, ".github", "hooks", "hooks.json");
+		const config = JSON.parse(await Bun.file(hooksPath).text()) as {
+			hooks: { onSessionStart: Array<{ command: string }> };
+		};
+
+		const commands = config.hooks.onSessionStart.map((e) => e.command);
+		expect(commands.some((c) => c.includes("ov prime") && c.includes("prime-test-agent"))).toBe(
+			true,
+		);
+	});
+
+	test("onSessionStart includes ov mail check --inject command", async () => {
+		const worktreePath = join(tempDir, "worktree");
+		await deployCopilotHooks(worktreePath, "mail-test-agent");
+
+		const hooksPath = join(worktreePath, ".github", "hooks", "hooks.json");
+		const config = JSON.parse(await Bun.file(hooksPath).text()) as {
+			hooks: { onSessionStart: Array<{ command: string }> };
+		};
+
+		const commands = config.hooks.onSessionStart.map((e) => e.command);
+		expect(
+			commands.some((c) => c.includes("ov mail check --inject") && c.includes("mail-test-agent")),
+		).toBe(true);
+	});
+
+	test("all hook commands include ENV_GUARD pattern", async () => {
+		const worktreePath = join(tempDir, "worktree");
+		await deployCopilotHooks(worktreePath, "guard-test-agent");
+
+		const hooksPath = join(worktreePath, ".github", "hooks", "hooks.json");
+		const config = JSON.parse(await Bun.file(hooksPath).text()) as {
+			hooks: Record<string, Array<{ command: string }>>;
+		};
+
+		const allCommands = Object.values(config.hooks)
+			.flat()
+			.map((e) => e.command);
+		for (const cmd of allCommands) {
+			expect(cmd).toContain("OVERSTORY_AGENT_NAME");
+		}
+	});
+
+	test("template file exists and is valid JSON after substitution", async () => {
+		// Verify template file is present and parseable (basic template health check).
+		const templatePath = join(import.meta.dir, "..", "..", "templates", "copilot-hooks.json.tmpl");
+		const exists = await Bun.file(templatePath).exists();
+		expect(exists).toBe(true);
+
+		const raw = (await Bun.file(templatePath).text()).replace(/\{\{AGENT_NAME\}\}/g, "test");
+		expect(() => JSON.parse(raw)).not.toThrow();
+	});
+});

package/src/agents/copilot-hooks-deployer.ts

@@ -0,0 +1,93 @@
+import { mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { AgentError } from "../errors.ts";
+import { PATH_PREFIX } from "./hooks-deployer.ts";
+
+/** Copilot hook entry shape — simpler than Claude Code (no matcher, no type field). */
+interface CopilotHookEntry {
+	command: string;
+}
+
+/**
+ * Resolve the path to the Copilot hooks template file.
+ * The template lives at `templates/copilot-hooks.json.tmpl` relative to the repo root.
+ */
+function getTemplatePath(): string {
+	// src/agents/copilot-hooks-deployer.ts -> repo root is ../../
+	return join(dirname(import.meta.dir), "..", "templates", "copilot-hooks.json.tmpl");
+}
+
+/**
+ * Deploy Copilot lifecycle hooks to an agent's worktree.
+ *
+ * Reads `templates/copilot-hooks.json.tmpl`, replaces all `{{AGENT_NAME}}` tokens,
+ * prepends PATH_PREFIX to every hook command so CLIs (ov, ml, sd) resolve correctly
+ * under Copilot's minimal PATH, then writes the result to
+ * `<worktreePath>/.github/hooks/hooks.json`.
+ *
+ * Phase 1: lifecycle hooks only (onSessionStart). No security guards.
+ *
+ * @param worktreePath - Absolute path to the agent's git worktree
+ * @param agentName - The unique name of the agent (replaces {{AGENT_NAME}} in template)
+ * @throws {AgentError} If the template is missing or the write fails
+ */
+export async function deployCopilotHooks(worktreePath: string, agentName: string): Promise<void> {
+	const templatePath = getTemplatePath();
+	const file = Bun.file(templatePath);
+	const exists = await file.exists();
+
+	if (!exists) {
+		throw new AgentError(`Copilot hooks template not found: ${templatePath}`, {
+			agentName,
+		});
+	}
+
+	let template: string;
+	try {
+		template = await file.text();
+	} catch (err) {
+		throw new AgentError(`Failed to read Copilot hooks template: ${templatePath}`, {
+			agentName,
+			cause: err instanceof Error ? err : undefined,
+		});
+	}
+
+	// Replace all occurrences of {{AGENT_NAME}}
+	let content = template;
+	while (content.includes("{{AGENT_NAME}}")) {
+		content = content.replace("{{AGENT_NAME}}", agentName);
+	}
+
+	// Parse the base config from the template
+	const config = JSON.parse(content) as { hooks: Record<string, CopilotHookEntry[]> };
+
+	// Extend PATH in all hook commands.
+	// Copilot CLI executes hooks with a minimal PATH — ~/.bun/bin (where ov, ml, sd live)
+	// is not included. Prepend PATH_PREFIX so CLIs resolve correctly.
+	for (const entries of Object.values(config.hooks)) {
+		for (const entry of entries) {
+			entry.command = `${PATH_PREFIX} ${entry.command}`;
+		}
+	}
+
+	const hooksDir = join(worktreePath, ".github", "hooks");
+	const outputPath = join(hooksDir, "hooks.json");
+
+	try {
+		await mkdir(hooksDir, { recursive: true });
+	} catch (err) {
+		throw new AgentError(`Failed to create .github/hooks/ directory at: ${hooksDir}`, {
+			agentName,
+			cause: err instanceof Error ? err : undefined,
+		});
+	}
+
+	try {
+		await Bun.write(outputPath, `${JSON.stringify(config, null, "\t")}\n`);
+	} catch (err) {
+		throw new AgentError(`Failed to write Copilot hooks config to: ${outputPath}`, {
+			agentName,
+			cause: err instanceof Error ? err : undefined,
+		});
+	}
+}

package/src/beads/client.ts

@@ -194,9 +194,37 @@ export function createBeadsClient(cwd: string): BeadsClient {
 			if (options?.limit !== undefined) {
 				args.push("--limit", String(options.limit));
 			}
-			const { stdout } = await runBd(args, "list");
-			const raw = parseJsonOutput<RawBeadIssue[]>(stdout, "list");
-			return raw.map(normalizeIssue);
+			try {
+				const { stdout } = await runBd(args, "list");
+				const trimmed = stdout.trim();
+				if (trimmed === "") return [];
+				const parsed: unknown = JSON.parse(trimmed);
+				if (Array.isArray(parsed)) {
+					// Flat format: RawBeadIssue[]
+					return (parsed as RawBeadIssue[]).map(normalizeIssue);
+				}
+				if (typeof parsed === "object" && parsed !== null) {
+					// Tree format: { mol: RawBeadIssue[] } — flatten all groups
+					const tree = parsed as Record<string, unknown>;
+					const issues: BeadIssue[] = [];
+					for (const group of Object.values(tree)) {
+						if (Array.isArray(group)) {
+							for (const item of group) {
+								issues.push(normalizeIssue(item as RawBeadIssue));
+							}
+						}
+					}
+					if (issues.length > 0) return issues;
+				}
+			} catch {
+				// fall through to ready fallback
+			}
+			// Fallback: bd ready --json always returns a flat array
+			const { stdout: readyStdout } = await runBd(["ready", "--json"], "ready (list fallback)");
+			const readyTrimmed = readyStdout.trim();
+			if (readyTrimmed === "") return [];
+			const readyRaw = parseJsonOutput<RawBeadIssue[]>(readyTrimmed, "ready (list fallback)");
+			return readyRaw.map(normalizeIssue);
 		},
 	};
 }

package/src/commands/clean.ts

@@ -37,6 +37,7 @@ import {
 	killProcessTree,
 	killSession,
 	listSessions,
+	sanitizeTmuxName,
 } from "../worktree/tmux.ts";
 
 export interface CleanOptions {
@@ -155,7 +156,7 @@ interface CleanResult {
  */
 async function killAllTmuxSessions(overstoryDir: string, projectName: string): Promise<number> {
 	let killed = 0;
-	const projectPrefix = `overstory-${projectName}-`;
+	const projectPrefix = `overstory-${sanitizeTmuxName(projectName)}-`;
 	try {
 		const tmuxSessions = await listSessions();
 		const overStorySessions = tmuxSessions.filter((s) => s.name.startsWith(projectPrefix));

package/src/commands/completions.test.ts

@@ -12,7 +12,10 @@ import {
 } from "./completions.ts";
 
 afterEach(() => {
-	process.exitCode = undefined;
+	// Use 0 not undefined — Bun doesn't reliably clear a nonzero exitCode when
+	// reassigned to undefined (see prior fix f3fde1a). If the 1 from completion
+	// tests leaks to bun test's shutdown, the suite exits 1 with 0 test failures.
+	process.exitCode = 0;
 });
 
 describe("COMMANDS array", () => {

package/src/commands/coordinator.ts

@@ -37,7 +37,9 @@ import {
 	ensureTmuxAvailable,
 	isSessionAlive,
 	killSession,
+	sanitizeTmuxName,
 	sendKeys,
+	TMUX_SOCKET,
 	waitForTuiReady,
 } from "../worktree/tmux.ts";
 import { nudgeAgent } from "./nudge.ts";
@@ -75,7 +77,7 @@ const ASK_DEFAULT_TIMEOUT_S = 120;
  * Includes the project name to prevent cross-project collisions (overstory-pcef).
  */
 function coordinatorTmuxSession(projectName: string, name: string = COORDINATOR_NAME): string {
-	return `overstory-${projectName}-${name}`;
+	return `overstory-${sanitizeTmuxName(projectName)}-${name}`;
 }
 
 /** Dependency injection for testing. Uses real implementations when omitted. */
@@ -630,7 +632,7 @@ export async function startCoordinatorSession(
 		}
 
 		if (shouldAttach) {
-			Bun.spawnSync(["tmux", "attach-session", "-t", tmuxSession], {
+			Bun.spawnSync(["tmux", "-L", TMUX_SOCKET, "attach-session", "-t", tmuxSession], {
 				stdio: ["inherit", "inherit", "inherit"],
 			});
 		}

package/src/commands/dashboard.ts

@@ -46,6 +46,7 @@ import type {
 	MailMessage,
 	OverstoryConfig,
 	StoredEvent,
+	TaskTrackerBackend,
 } from "../types.ts";
 import { evaluateHealth } from "../watchdog/health.ts";
 import { isProcessAlive } from "../worktree/tmux.ts";
@@ -356,6 +357,7 @@ async function loadDashboardData(
 	thresholds?: { staleMs: number; zombieMs: number },
 	eventBuffer?: EventBuffer,
 	runtimeConfig?: OverstoryConfig["runtime"],
+	taskTrackerBackend?: TaskTrackerBackend,
 ): Promise<DashboardData> {
 	// Get all sessions from the pre-opened session store — fall back to cache on SQLite errors.
 	let allSessions: AgentSession[];
@@ -516,7 +518,7 @@ async function loadDashboardData(
 	const now2 = Date.now();
 	if (!trackerCache || now2 - trackerCache.fetchedAt > TRACKER_CACHE_TTL_MS) {
 		try {
-			const backend = await resolveBackend("auto", root);
+			const backend = await resolveBackend(taskTrackerBackend ?? "auto", root);
 			const tracker = createTrackerClient(backend, root);
 			tasks = await tracker.list({ limit: 10 });
 			trackerCache = { tasks, fetchedAt: now2 };
@@ -1104,6 +1106,7 @@ async function executeDashboard(opts: DashboardOpts): Promise<void> {
 				thresholds,
 				eventBuffer,
 				config.runtime,
+				config.taskTracker.backend,
 			);
 			lastGoodData = data;
 			// If recovering from an error, clear the stale error line at the bottom

package/src/commands/doctor.ts

@@ -158,10 +158,81 @@ export interface DoctorCommandOptions {
 	checkRunners?: Array<{ category: DoctorCategory; fn: DoctorCheckFn }>;
 }
 
+interface DoctorActionOpts {
+	json?: boolean;
+	verbose?: boolean;
+	category?: string;
+	fix?: boolean;
+}
+
 /**
- * Create the Commander command for `overstory doctor`.
+ * Run the doctor checks. Returns true if any check failed.
+ * Shared by both the Commander action and the programmatic entry point so the
+ * exit-code signal never has to travel through `process.exitCode` (which is
+ * global mutable state and races with other tests in parallel bun test runs).
  */
-export function createDoctorCommand(options?: DoctorCommandOptions): Command {
+async function runDoctorChecks(
+	opts: DoctorActionOpts,
+	checkRunners: Array<{ category: DoctorCategory; fn: DoctorCheckFn }>,
+): Promise<boolean> {
+	const json = opts.json ?? false;
+	const verbose = opts.verbose ?? false;
+	const categoryFilter = opts.category;
+	const fix = opts.fix ?? false;
+
+	if (categoryFilter !== undefined) {
+		const validCategories = ALL_CHECKS.map((c) => c.category);
+		if (!validCategories.includes(categoryFilter as DoctorCategory)) {
+			throw new ValidationError(
+				`Invalid category: ${categoryFilter}. Valid categories: ${validCategories.join(", ")}`,
+				{
+					field: "category",
+					value: categoryFilter,
+				},
+			);
+		}
+	}
+
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const overstoryDir = join(config.project.root, ".overstory");
+
+	const checksToRun = categoryFilter
+		? checkRunners.filter((c) => c.category === categoryFilter)
+		: checkRunners;
+
+	let results: DoctorCheck[] = [];
+	for (const { fn } of checksToRun) {
+		const checkResults = await fn(config, overstoryDir);
+		results.push(...checkResults);
+	}
+
+	let fixedItems: string[] | undefined;
+	if (fix) {
+		const applied = await applyFixes(results);
+		if (applied.length > 0) {
+			fixedItems = applied;
+			results = [];
+			for (const { fn } of checksToRun) {
+				const checkResults = await fn(config, overstoryDir);
+				results.push(...checkResults);
+			}
+		}
+	}
+
+	if (json) {
+		printJSON(results, fixedItems);
+	} else {
+		printHumanReadable(results, verbose, checkRunners, fixedItems);
+	}
+
+	return results.some((c) => c.status === "fail");
+}
+
+function buildDoctorCommand(
+	onResult: (hasFailures: boolean) => void,
+	checkRunners: Array<{ category: DoctorCategory; fn: DoctorCheckFn }>,
+): Command {
 	return new Command("doctor")
 		.description("Run health checks on overstory setup")
 		.option("--json", "Output as JSON")
@@ -172,73 +243,20 @@ export function createDoctorCommand(options?: DoctorCommandOptions): Command {
 			"after",
 			"\nCategories: dependencies, structure, config, databases, consistency, agents, merge, logs, version, ecosystem, providers, watchdog",
 		)
-		.action(
-			async (opts: { json?: boolean; verbose?: boolean; category?: string; fix?: boolean }) => {
-				const json = opts.json ?? false;
-				const verbose = opts.verbose ?? false;
-				const categoryFilter = opts.category;
-				const fix = opts.fix ?? false;
-
-				// Validate category filter if provided
-				if (categoryFilter !== undefined) {
-					const validCategories = ALL_CHECKS.map((c) => c.category);
-					if (!validCategories.includes(categoryFilter as DoctorCategory)) {
-						throw new ValidationError(
-							`Invalid category: ${categoryFilter}. Valid categories: ${validCategories.join(", ")}`,
-							{
-								field: "category",
-								value: categoryFilter,
-							},
-						);
-					}
-				}
-
-				const cwd = process.cwd();
-				const config = await loadConfig(cwd);
-				const overstoryDir = join(config.project.root, ".overstory");
-
-				// Filter checks by category if specified
-				const allChecks = options?.checkRunners ?? ALL_CHECKS;
-				const checksToRun = categoryFilter
-					? allChecks.filter((c) => c.category === categoryFilter)
-					: allChecks;
-
-				// Run all checks sequentially
-				let results: DoctorCheck[] = [];
-				for (const { fn } of checksToRun) {
-					const checkResults = await fn(config, overstoryDir);
-					results.push(...checkResults);
-				}
-
-				// Apply fixes if requested
-				let fixedItems: string[] | undefined;
-				if (fix) {
-					const applied = await applyFixes(results);
-					if (applied.length > 0) {
-						fixedItems = applied;
-						// Re-run all checks to get fresh results after fixes
-						results = [];
-						for (const { fn } of checksToRun) {
-							const checkResults = await fn(config, overstoryDir);
-							results.push(...checkResults);
-						}
-					}
-				}
-
-				// Output results
-				if (json) {
-					printJSON(results, fixedItems);
-				} else {
-					printHumanReadable(results, verbose, allChecks, fixedItems);
-				}
+		.action(async (opts: DoctorActionOpts) => {
+			onResult(await runDoctorChecks(opts, checkRunners));
+		});
+}
 
-				// Set exit code if any check failed
-				const hasFailures = results.some((c) => c.status === "fail");
-				if (hasFailures) {
-					process.exitCode = 1;
-				}
-			},
-		);
+/**
+ * Create the Commander command for `overstory doctor`.
+ */
+export function createDoctorCommand(options?: DoctorCommandOptions): Command {
+	return buildDoctorCommand((hasFailures) => {
+		if (hasFailures) {
+			process.exitCode = 1;
+		}
+	}, options?.checkRunners ?? ALL_CHECKS);
 }
 
 /**
@@ -250,16 +268,15 @@ export async function doctorCommand(
 	args: string[],
 	options?: DoctorCommandOptions,
 ): Promise<number | undefined> {
-	const cmd = createDoctorCommand(options);
+	let hasFailures = false;
+	const cmd = buildDoctorCommand((result) => {
+		hasFailures = result;
+	}, options?.checkRunners ?? ALL_CHECKS);
 	cmd.exitOverride();
 
-	const prevExitCode = process.exitCode as number | undefined;
-	process.exitCode = undefined;
-
 	try {
 		await cmd.parseAsync(args, { from: "user" });
 	} catch (err: unknown) {
-		process.exitCode = prevExitCode;
 		if (err && typeof err === "object" && "code" in err) {
 			const code = (err as { code: string }).code;
 			if (code === "commander.helpDisplayed" || code === "commander.version") {
@@ -269,7 +286,5 @@ export async function doctorCommand(
 		throw err;
 	}
 
-	const exitCode = process.exitCode === 1 ? 1 : undefined;
-	process.exitCode = prevExitCode;
-	return exitCode;
+	return hasFailures ? 1 : undefined;
 }