@os-eco/overstory-cli 0.6.1 → 0.6.5

package/src/commands/worktree.ts

@@ -7,18 +7,20 @@
  */
 
 import { join } from "node:path";
+import { Command } from "commander";
 import { loadConfig } from "../config.ts";
 import { ValidationError } from "../errors.ts";
 import { createMailStore } from "../mail/store.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import type { AgentSession } from "../types.ts";
-import { isBranchMerged, listWorktrees, removeWorktree } from "../worktree/manager.ts";
+import {
+	isBranchMerged,
+	listWorktrees,
+	preserveSeedsChanges,
+	removeWorktree,
+} from "../worktree/manager.ts";
 import { isSessionAlive, killSession } from "../worktree/tmux.ts";
 
-function hasFlag(args: string[], flag: string): boolean {
-	return args.includes(flag);
-}
-
 /**
  * Handle `overstory worktree list`.
  */
@@ -44,7 +46,7 @@ async function handleList(root: string, json: boolean): Promise<void> {
 				head: wt.head,
 				agentName: session?.agentName ?? null,
 				state: session?.state ?? null,
-				beadId: session?.beadId ?? null,
+				taskId: session?.taskId ?? null,
 			};
 		});
 		process.stdout.write(`${JSON.stringify(entries, null, "\t")}\n`);
@@ -61,7 +63,7 @@ async function handleList(root: string, json: boolean): Promise<void> {
 		const session = sessions.find((s) => s.worktreePath === wt.path);
 		const state = session?.state ?? "unknown";
 		const agent = session?.agentName ?? "?";
-		const bead = session?.beadId ?? "?";
+		const bead = session?.taskId ?? "?";
 		process.stdout.write(`  ${wt.branch}\n`);
 		process.stdout.write(`    Agent: ${agent} | State: ${state} | Task: ${bead}\n`);
 		process.stdout.write(`    Path: ${wt.path}\n\n`);
@@ -72,14 +74,12 @@ async function handleList(root: string, json: boolean): Promise<void> {
  * Handle `overstory worktree clean [--completed] [--all] [--force]`.
  */
 async function handleClean(
-	args: string[],
+	opts: { all: boolean; force: boolean; completedOnly: boolean },
 	root: string,
 	json: boolean,
 	canonicalBranch: string,
 ): Promise<void> {
-	const all = hasFlag(args, "--all");
-	const force = hasFlag(args, "--force");
-	const completedOnly = hasFlag(args, "--completed") || !all;
+	const { force, completedOnly } = opts;
 
 	const worktrees = await listWorktrees(root);
 	const overstoryDir = join(root, ".overstory");
@@ -97,6 +97,7 @@ async function handleClean(
 	const cleaned: string[] = [];
 	const failed: string[] = [];
 	const skipped: string[] = [];
+	const seedsPreserved: string[] = [];
 
 	try {
 		for (const wt of overstoryWts) {
@@ -107,8 +108,11 @@ async function handleClean(
 				continue;
 			}
 
-			// Check if the branch has been merged into the canonical branch (unless --force)
-			if (!force && wt.branch.length > 0) {
+			// Lead branches are never merged via the normal pipeline — skip merge check for leads.
+			const isLead = session?.capability === "lead";
+
+			// Check if the branch has been merged into the canonical branch (unless --force or lead)
+			if (!force && !isLead && wt.branch.length > 0) {
 				let merged = false;
 				try {
 					merged = await isBranchMerged(root, wt.branch, canonicalBranch);
@@ -136,8 +140,8 @@ async function handleClean(
 				}
 			}
 
-			// Warn about force-deleting unmerged branch
-			if (force && wt.branch.length > 0) {
+			// Warn about force-deleting unmerged branch (non-lead only)
+			if (force && !isLead && wt.branch.length > 0) {
 				let merged = false;
 				try {
 					merged = await isBranchMerged(root, wt.branch, canonicalBranch);
@@ -149,6 +153,29 @@ async function handleClean(
 				}
 			}
 
+			// Preserve .seeds/ changes from lead worktrees before removal.
+			// Lead branches are never merged, so .seeds/ files would otherwise be lost.
+			if (isLead && wt.branch.length > 0) {
+				const result = await preserveSeedsChanges(
+					root,
+					wt.branch,
+					canonicalBranch,
+					session?.agentName ?? "unknown-lead",
+				);
+				if (result.preserved) {
+					seedsPreserved.push(wt.branch);
+					if (!json) {
+						process.stdout.write(
+							`🌱 Preserved .seeds/ changes from lead ${session?.agentName ?? "unknown-lead"}\n`,
+						);
+					}
+				} else if (result.error) {
+					process.stderr.write(
+						`⚠️  Failed to preserve .seeds/ from ${wt.branch}: ${result.error}\n`,
+					);
+				}
+			}
+
 			// Remove worktree and its branch.
 			// Always force worktree removal since deployed .claude/ files create untracked
 			// files that cause non-forced removal to fail.
@@ -215,13 +242,14 @@ async function handleClean(
 
 		if (json) {
 			process.stdout.write(
-				`${JSON.stringify({ cleaned, failed, skipped, pruned: pruneCount, mailPurged })}\n`,
+				`${JSON.stringify({ cleaned, failed, skipped, pruned: pruneCount, mailPurged, seedsPreserved })}\n`,
 			);
 		} else if (
 			cleaned.length === 0 &&
 			pruneCount === 0 &&
 			failed.length === 0 &&
-			skipped.length === 0
+			skipped.length === 0 &&
+			seedsPreserved.length === 0
 		) {
 			process.stdout.write("No worktrees to clean.\n");
 		} else {
@@ -245,6 +273,11 @@ async function handleClean(
 					`Pruned ${pruneCount} zombie session${pruneCount === 1 ? "" : "s"} from store.\n`,
 				);
 			}
+			if (seedsPreserved.length > 0) {
+				process.stdout.write(
+					`Preserved .seeds/ changes from ${seedsPreserved.length} lead${seedsPreserved.length === 1 ? "" : "s"}.\n`,
+				);
+			}
 			if (skipped.length > 0) {
 				process.stdout.write(
 					`\n⚠️  Skipped ${skipped.length} worktree${skipped.length === 1 ? "" : "s"} with unmerged branches:\n`,
@@ -260,52 +293,74 @@ async function handleClean(
 	}
 }
 
+export function createWorktreeCommand(): Command {
+	const cmd = new Command("worktree").description("Manage agent worktrees");
+
+	cmd
+		.command("list")
+		.description("List worktrees with agent status")
+		.option("--json", "Output as JSON")
+		.action(async (opts: { json?: boolean }) => {
+			const cwd = process.cwd();
+			const config = await loadConfig(cwd);
+			await handleList(config.project.root, opts.json ?? false);
+		});
+
+	cmd
+		.command("clean")
+		.description("Remove completed worktrees")
+		.option("--completed", "Only finished agents (default)")
+		.option("--all", "Force remove all worktrees")
+		.option("--force", "Delete even if branches are unmerged")
+		.option("--json", "Output as JSON")
+		.action(
+			async (opts: { completed?: boolean; all?: boolean; force?: boolean; json?: boolean }) => {
+				const cwd = process.cwd();
+				const config = await loadConfig(cwd);
+				const all = opts.all ?? false;
+				await handleClean(
+					{
+						all,
+						force: opts.force ?? false,
+						completedOnly: opts.completed ?? !all,
+					},
+					config.project.root,
+					opts.json ?? false,
+					config.project.canonicalBranch,
+				);
+			},
+		);
+
+	return cmd;
+}
+
 /**
  * Entry point for `overstory worktree <subcommand> [flags]`.
  *
  * Subcommands: list, clean.
  */
-const WORKTREE_HELP = `overstory worktree — Manage agent worktrees
-
-Usage: overstory worktree <subcommand> [flags]
-
-Subcommands:
-  list               List worktrees with agent status
-  clean              Remove completed worktrees
-                       [--completed]  Only finished agents (default)
-                       [--all]        Force remove all
-                       [--force]      Delete even if branches are unmerged
-
-Options:
-  --json             Output as JSON
-  --help, -h         Show this help`;
-
 export async function worktreeCommand(args: string[]): Promise<void> {
-	if (args.includes("--help") || args.includes("-h")) {
-		process.stdout.write(`${WORKTREE_HELP}\n`);
+	const cmd = createWorktreeCommand();
+	cmd.exitOverride();
+
+	if (args.length === 0) {
+		process.stdout.write(cmd.helpInformation());
 		return;
 	}
 
-	const subcommand = args[0];
-	const subArgs = args.slice(1);
-	const jsonFlag = hasFlag(args, "--json");
-
-	const cwd = process.cwd();
-	const config = await loadConfig(cwd);
-	const root = config.project.root;
-	const canonicalBranch = config.project.canonicalBranch;
-
-	switch (subcommand) {
-		case "list":
-			await handleList(root, jsonFlag);
-			break;
-		case "clean":
-			await handleClean(subArgs, root, jsonFlag, canonicalBranch);
-			break;
-		default:
-			throw new ValidationError(
-				`Unknown worktree subcommand: ${subcommand ?? "(none)"}. Use: list, clean`,
-				{ field: "subcommand" },
-			);
+	try {
+		await cmd.parseAsync(args, { from: "user" });
+	} catch (err: unknown) {
+		if (err && typeof err === "object" && "code" in err) {
+			const code = (err as { code: string }).code;
+			if (code === "commander.helpDisplayed" || code === "commander.version") {
+				return;
+			}
+			if (code === "commander.unknownCommand") {
+				const message = err instanceof Error ? err.message : String(err);
+				throw new ValidationError(message, { field: "subcommand" });
+			}
+		}
+		throw err;
 	}
 }

package/src/config.test.ts

@@ -265,6 +265,80 @@ providers:
 		expect(config.providers.anthropic).toEqual({ type: "native" });
 	});
 
+	test("multiple providers parsed correctly", async () => {
+		await ensureOverstoryDir();
+		await writeConfig(`
+providers:
+  anthropic:
+    type: native
+  openrouter:
+    type: gateway
+    baseUrl: https://openrouter.ai/api/v1
+    authTokenEnv: OPENROUTER_API_KEY
+  litellm:
+    type: gateway
+    baseUrl: http://localhost:4000
+    authTokenEnv: LITELLM_API_KEY
+`);
+		const config = await loadConfig(tempDir);
+		expect(Object.keys(config.providers).length).toBe(3);
+		expect(config.providers.anthropic).toEqual({ type: "native" });
+		expect(config.providers.openrouter).toEqual({
+			type: "gateway",
+			baseUrl: "https://openrouter.ai/api/v1",
+			authTokenEnv: "OPENROUTER_API_KEY",
+		});
+		expect(config.providers.litellm).toEqual({
+			type: "gateway",
+			baseUrl: "http://localhost:4000",
+			authTokenEnv: "LITELLM_API_KEY",
+		});
+	});
+
+	test("config.local.yaml adds new provider alongside config.yaml providers", async () => {
+		await ensureOverstoryDir();
+		await writeConfig(`
+providers:
+  openrouter:
+    type: gateway
+    baseUrl: https://openrouter.ai/api/v1
+    authTokenEnv: OPENROUTER_API_KEY
+`);
+		await Bun.write(
+			join(tempDir, ".overstory", "config.local.yaml"),
+			`providers:\n  litellm:\n    type: gateway\n    baseUrl: http://localhost:4000\n    authTokenEnv: LITELLM_API_KEY\n`,
+		);
+		const config = await loadConfig(tempDir);
+		// All three providers present: default anthropic + openrouter from config.yaml + litellm from config.local.yaml
+		expect(config.providers.anthropic).toEqual({ type: "native" });
+		expect(config.providers.openrouter).toEqual({
+			type: "gateway",
+			baseUrl: "https://openrouter.ai/api/v1",
+			authTokenEnv: "OPENROUTER_API_KEY",
+		});
+		expect(config.providers.litellm).toEqual({
+			type: "gateway",
+			baseUrl: "http://localhost:4000",
+			authTokenEnv: "LITELLM_API_KEY",
+		});
+	});
+
+	test("simple model strings still work without providers section", async () => {
+		await ensureOverstoryDir();
+		await writeConfig(`
+models:
+  coordinator: sonnet
+  builder: opus
+  monitor: haiku
+`);
+		const config = await loadConfig(tempDir);
+		expect(config.models.coordinator).toBe("sonnet");
+		expect(config.models.builder).toBe("opus");
+		expect(config.models.monitor).toBe("haiku");
+		// Default anthropic provider still present even without explicit providers section
+		expect(config.providers.anthropic).toEqual({ type: "native" });
+	});
+
 	test("migrates deprecated watchdog tier1/tier2 keys to tier0/tier1", async () => {
 		await ensureOverstoryDir();
 		await writeConfig(`
@@ -556,6 +630,28 @@ models:
 		await expect(loadConfig(tempDir)).rejects.toThrow(ValidationError);
 	});
 
+	test("rejects model ref with deeply nested slashes when provider unknown", async () => {
+		await writeConfig(`
+models:
+  coordinator: unknown/openai/gpt-5.3/latest
+`);
+		await expect(loadConfig(tempDir)).rejects.toThrow(ValidationError);
+	});
+
+	test("accepts model ref with deeply nested slashes when provider exists", async () => {
+		await writeConfig(`
+providers:
+  openrouter:
+    type: gateway
+    baseUrl: https://openrouter.ai/api/v1
+    authTokenEnv: OPENROUTER_API_KEY
+models:
+  coordinator: openrouter/openai/gpt-5.3/variant
+`);
+		const config = await loadConfig(tempDir);
+		expect(config.models.coordinator).toBe("openrouter/openai/gpt-5.3/variant");
+	});
+
 	test("rejects bare invalid model name", async () => {
 		await writeConfig(`
 models:

package/src/doctor/consistency.test.ts

@@ -195,7 +195,7 @@ describe("checkConsistency", () => {
 			capability: "builder",
 			worktreePath: join(overstoryDir, "worktrees", "dead-agent"),
 			branchName: "overstory/dead-agent/test-123",
-			beadId: "test-123",
+			taskId: "test-123",
 			tmuxSession: "overstory-testproject-dead-agent",
 			state: "working",
 			pid: 99999, // Non-existent PID
@@ -231,7 +231,7 @@ describe("checkConsistency", () => {
 			capability: "builder",
 			worktreePath: join(overstoryDir, "worktrees", "live-agent"),
 			branchName: "overstory/live-agent/test-123",
-			beadId: "test-123",
+			taskId: "test-123",
 			tmuxSession: "overstory-testproject-live-agent",
 			state: "working",
 			pid: 12345,
@@ -266,7 +266,7 @@ describe("checkConsistency", () => {
 			capability: "builder",
 			worktreePath: missingWorktreePath,
 			branchName: "overstory/missing-agent/test-123",
-			beadId: "test-123",
+			taskId: "test-123",
 			tmuxSession: "overstory-testproject-missing-agent",
 			state: "working",
 			pid: null,
@@ -302,7 +302,7 @@ describe("checkConsistency", () => {
 			capability: "builder",
 			worktreePath,
 			branchName: "overstory/agent-without-tmux/test-123",
-			beadId: "test-123",
+			taskId: "test-123",
 			tmuxSession: "overstory-testproject-agent-without-tmux",
 			state: "working",
 			pid: null,
@@ -341,7 +341,7 @@ describe("checkConsistency", () => {
 			capability: "builder",
 			worktreePath,
 			branchName: "overstory/consistent-agent/test-123",
-			beadId: "test-123",
+			taskId: "test-123",
 			tmuxSession: "overstory-testproject-consistent-agent",
 			state: "working",
 			pid: 12345,
@@ -414,7 +414,7 @@ describe("checkConsistency", () => {
 			capability: "builder",
 			worktreePath: join(overstoryDir, "worktrees", "builder-1"),
 			branchName: "overstory/builder-1/test-123",
-			beadId: "test-123",
+			taskId: "test-123",
 			tmuxSession: "overstory-testproject-builder-1",
 			state: "working",
 			pid: null,
@@ -433,7 +433,7 @@ describe("checkConsistency", () => {
 			capability: "builder",
 			worktreePath: join(overstoryDir, "worktrees", "builder-2"),
 			branchName: "overstory/builder-2/test-456",
-			beadId: "test-456",
+			taskId: "test-456",
 			tmuxSession: "overstory-testproject-builder-2",
 			state: "working",
 			pid: null,
@@ -469,7 +469,7 @@ describe("checkConsistency", () => {
 				capability: "builder",
 				worktreePath: join(overstoryDir, "worktrees", `builder-${i}`),
 				branchName: `overstory/builder-${i}/test-${i}`,
-				beadId: `test-${i}`,
+				taskId: `test-${i}`,
 				tmuxSession: `overstory-testproject-builder-${i}`,
 				state: "working",
 				pid: null,
@@ -489,7 +489,7 @@ describe("checkConsistency", () => {
 			capability: "reviewer",
 			worktreePath: join(overstoryDir, "worktrees", "reviewer-1"),
 			branchName: "overstory/reviewer-1/test-r1",
-			beadId: "test-r1",
+			taskId: "test-r1",
 			tmuxSession: "overstory-testproject-reviewer-1",
 			state: "working",
 			pid: null,
@@ -523,7 +523,7 @@ describe("checkConsistency", () => {
 				capability: "builder",
 				worktreePath: join(overstoryDir, "worktrees", `builder-${i}`),
 				branchName: `overstory/builder-${i}/test-${i}`,
-				beadId: `test-${i}`,
+				taskId: `test-${i}`,
 				tmuxSession: `overstory-testproject-builder-${i}`,
 				state: "working",
 				pid: null,
@@ -542,7 +542,7 @@ describe("checkConsistency", () => {
 				capability: "reviewer",
 				worktreePath: join(overstoryDir, "worktrees", `reviewer-${i}`),
 				branchName: `overstory/reviewer-${i}/test-r${i}`,
-				beadId: `test-r${i}`,
+				taskId: `test-r${i}`,
 				tmuxSession: `overstory-testproject-reviewer-${i}`,
 				state: "working",
 				pid: null,
@@ -585,7 +585,7 @@ describe("checkConsistency", () => {
 			capability: "builder",
 			worktreePath: join(overstoryDir, "worktrees", "builder-1"),
 			branchName: "overstory/builder-1/test-1",
-			beadId: "test-1",
+			taskId: "test-1",
 			tmuxSession: "overstory-testproject-builder-1",
 			state: "working",
 			pid: null,
@@ -604,7 +604,7 @@ describe("checkConsistency", () => {
 			capability: "reviewer",
 			worktreePath: join(overstoryDir, "worktrees", "reviewer-1"),
 			branchName: "overstory/reviewer-1/test-r1",
-			beadId: "test-r1",
+			taskId: "test-r1",
 			tmuxSession: "overstory-testproject-reviewer-1",
 			state: "working",
 			pid: null,
@@ -624,7 +624,7 @@ describe("checkConsistency", () => {
 			capability: "builder",
 			worktreePath: join(overstoryDir, "worktrees", "builder-2"),
 			branchName: "overstory/builder-2/test-2",
-			beadId: "test-2",
+			taskId: "test-2",
 			tmuxSession: "overstory-testproject-builder-2",
 			state: "working",
 			pid: null,

package/src/doctor/databases.test.ts

@@ -51,13 +51,15 @@ describe("checkDatabases", () => {
 	test("fails when database files do not exist", () => {
 		const checks = checkDatabases(mockConfig, tempDir) as DoctorCheck[];
 
-		expect(checks).toHaveLength(3);
+		expect(checks).toHaveLength(4);
 		expect(checks[0]?.status).toBe("fail");
 		expect(checks[0]?.name).toBe("mail.db exists");
 		expect(checks[1]?.status).toBe("fail");
 		expect(checks[1]?.name).toBe("metrics.db exists");
 		expect(checks[2]?.status).toBe("fail");
 		expect(checks[2]?.name).toBe("sessions.db exists");
+		expect(checks[3]?.status).toBe("fail");
+		expect(checks[3]?.name).toBe("merge-queue.db exists");
 	});
 
 	test("passes when databases exist with correct schema", () => {
@@ -141,13 +143,31 @@ describe("checkDatabases", () => {
 		`);
 		sessionsDb.close();
 
+		// Create merge-queue.db
+		const mergeDb = new Database(join(tempDir, "merge-queue.db"));
+		mergeDb.exec("PRAGMA journal_mode=WAL");
+		mergeDb.exec(`
+			CREATE TABLE merge_queue (
+				id INTEGER PRIMARY KEY AUTOINCREMENT,
+				branch_name TEXT NOT NULL,
+				task_id TEXT NOT NULL,
+				agent_name TEXT NOT NULL,
+				files_modified TEXT NOT NULL DEFAULT '[]',
+				enqueued_at TEXT NOT NULL,
+				status TEXT NOT NULL DEFAULT 'pending',
+				resolved_tier TEXT
+			)
+		`);
+		mergeDb.close();
+
 		const checks = checkDatabases(mockConfig, tempDir) as DoctorCheck[];
 
-		expect(checks).toHaveLength(3);
+		expect(checks).toHaveLength(4);
 		expect(checks.every((c) => c?.status === "pass")).toBe(true);
 		expect(checks[0]?.name).toBe("mail.db health");
 		expect(checks[1]?.name).toBe("metrics.db health");
 		expect(checks[2]?.name).toBe("sessions.db health");
+		expect(checks[3]?.name).toBe("merge-queue.db health");
 	});
 
 	test("fails when table is missing", () => {

package/src/doctor/databases.ts

@@ -85,6 +85,22 @@ export const checkDatabases: DoctorCheckFn = (_config, overstoryDir): DoctorChec
 				],
 			},
 		},
+		{
+			name: "merge-queue.db",
+			tables: ["merge_queue"],
+			requiredColumns: {
+				merge_queue: [
+					"id",
+					"branch_name",
+					"task_id",
+					"agent_name",
+					"files_modified",
+					"enqueued_at",
+					"status",
+					"resolved_tier",
+				],
+			},
+		},
 	];
 
 	for (const dbSpec of databases) {

package/src/doctor/dependencies.test.ts

@@ -57,7 +57,7 @@ describe("checkDependencies", () => {
 		const checks = await checkDependencies(mockConfig, "/tmp/.overstory");
 
 		expect(checks).toBeArray();
-		expect(checks.length).toBeGreaterThanOrEqual(5);
+		expect(checks.length).toBeGreaterThanOrEqual(7);
 
 		// Verify we have checks for each required tool
 		const toolNames = checks.map((c) => c.name);
@@ -66,6 +66,8 @@ describe("checkDependencies", () => {
 		expect(toolNames).toContain("tmux availability");
 		expect(toolNames).toContain("sd availability");
 		expect(toolNames).toContain("mulch availability");
+		expect(toolNames).toContain("overstory availability");
+		expect(toolNames).toContain("cn availability");
 	});
 
 	test("includes bd CGO support check when bd is available", async () => {
@@ -181,4 +183,56 @@ describe("checkDependencies", () => {
 		const cgoCheck = checks.find((c) => c.name === "bd CGO support");
 		expect(cgoCheck).toBeUndefined();
 	});
+
+	test("cn check is warn (not fail) when missing", async () => {
+		const checks = await checkDependencies(mockConfig, "/tmp/.overstory");
+		const cnCheck = checks.find((c) => c.name === "cn availability");
+		expect(cnCheck).toBeDefined();
+		// cn is optional — should never be "fail", only "pass" or "warn"
+		expect(cnCheck?.status).not.toBe("fail");
+	});
+
+	test("checks short aliases for available tools", async () => {
+		const checks = await checkDependencies(mockConfig, "/tmp/.overstory");
+		const mulchCheck = checks.find((c) => c.name === "mulch availability");
+		if (mulchCheck?.status === "pass") {
+			const mlAlias = checks.find((c) => c.name === "ml alias");
+			expect(mlAlias).toBeDefined();
+			expect(mlAlias?.category).toBe("dependencies");
+			expect(["pass", "warn"]).toContain(mlAlias?.status ?? "");
+		}
+		const ovCheck = checks.find((c) => c.name === "overstory availability");
+		if (ovCheck?.status === "pass") {
+			const ovAlias = checks.find((c) => c.name === "ov alias");
+			expect(ovAlias).toBeDefined();
+			expect(["pass", "warn"]).toContain(ovAlias?.status ?? "");
+		}
+	});
+
+	test("alias checks are only run when primary tool passes", async () => {
+		const checks = await checkDependencies(mockConfig, "/tmp/.overstory");
+		// If mulch failed, ml alias should NOT be present
+		const mulchCheck = checks.find((c) => c.name === "mulch availability");
+		const mlAlias = checks.find((c) => c.name === "ml alias");
+		if (mulchCheck?.status !== "pass") {
+			expect(mlAlias).toBeUndefined();
+		}
+	});
+
+	test("install hints appear in details for missing tools", async () => {
+		const checks = await checkDependencies(mockConfig, "/tmp/.overstory");
+		// Check any failing/warning check with an installHint has npm install guidance
+		const cnCheck = checks.find((c) => c.name === "cn availability");
+		if (cnCheck?.status === "warn" || cnCheck?.status === "fail") {
+			const hasInstallHint = cnCheck.details?.some((d) => d.includes("npm install -g"));
+			expect(hasInstallHint).toBe(true);
+		}
+	});
+
+	test("includes overstory availability check", async () => {
+		const checks = await checkDependencies(mockConfig, "/tmp/.overstory");
+		const ovCheck = checks.find((c) => c.name === "overstory availability");
+		expect(ovCheck).toBeDefined();
+		expect(ovCheck?.category).toBe("dependencies");
+	});
 });