@ag-eco/agentplate-cli 0.13.0

package/src/doctor/consistency.test.ts

@@ -0,0 +1,807 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createSessionStore } from "../sessions/store.ts";
+import type { AgentplateConfig } from "../types.ts";
+import type { ConsistencyCheckDeps } from "./consistency.ts";
+import { checkConsistency } from "./consistency.ts";
+
+/**
+ * Mock tmux functions using dependency injection instead of mock.module().
+ * This avoids test isolation issues from module-level mocking.
+ */
+const mockListSessions = mock(() => Promise.resolve([] as Array<{ name: string; pid: number }>));
+const mockIsProcessAlive = mock((_pid: number) => true);
+
+/**
+ * Create a minimal temp git repo for worktree tests.
+ */
+function createTempGitRepo(): string {
+	const dir = mkdtempSync(join(tmpdir(), "agentplate-test-"));
+	const git = (args: string[]) => {
+		const proc = Bun.spawnSync(["git", ...args], { cwd: dir, stdout: "ignore", stderr: "pipe" });
+		if (proc.exitCode !== 0) {
+			throw new Error(`git ${args.join(" ")} failed: ${proc.stderr.toString()}`);
+		}
+	};
+
+	git(["init"]);
+	git(["config", "user.email", "test@test.com"]);
+	git(["config", "user.name", "Test User"]);
+	git(["config", "commit.gpgsign", "false"]);
+	writeFileSync(join(dir, "README.md"), "# Test Repo\n");
+	git(["add", "."]);
+	git(["commit", "-m", "Initial commit"]);
+
+	return dir;
+}
+
+/**
+ * Create a git worktree at the given path.
+ */
+function createWorktree(repoRoot: string, worktreePath: string, branchName: string): void {
+	const proc = Bun.spawnSync(["git", "worktree", "add", "-b", branchName, worktreePath, "HEAD"], {
+		cwd: repoRoot,
+		stdout: "ignore",
+		stderr: "pipe",
+	});
+	if (proc.exitCode !== 0) {
+		throw new Error(`Failed to create worktree: ${proc.stderr.toString()}`);
+	}
+}
+
+describe("checkConsistency", () => {
+	let repoRoot: string;
+	let agentplateDir: string;
+	let config: AgentplateConfig;
+	let mockDeps: ConsistencyCheckDeps;
+
+	beforeEach(() => {
+		repoRoot = createTempGitRepo();
+		agentplateDir = join(repoRoot, ".agentplate");
+		mkdirSync(agentplateDir, { recursive: true });
+		mkdirSync(join(agentplateDir, "worktrees"), { recursive: true });
+
+		config = {
+			project: {
+				name: "testproject",
+				root: repoRoot,
+				canonicalBranch: "main",
+			},
+			agents: {
+				manifestPath: join(agentplateDir, "agent-manifest.json"),
+				baseDir: join(repoRoot, "agents"),
+				maxConcurrent: 5,
+				staggerDelayMs: 100,
+				maxDepth: 2,
+				maxSessionsPerRun: 0,
+				maxAgentsPerLead: 5,
+			},
+			worktrees: {
+				baseDir: join(agentplateDir, "worktrees"),
+			},
+			taskTracker: {
+				backend: "auto",
+				enabled: false,
+			},
+			loam: {
+				enabled: false,
+				domains: [],
+				primeFormat: "markdown",
+			},
+			merge: {
+				aiResolveEnabled: false,
+				reimagineEnabled: false,
+			},
+			providers: {
+				anthropic: { type: "native" },
+			},
+			watchdog: {
+				tier0Enabled: false,
+				tier0IntervalMs: 30000,
+				tier1Enabled: false,
+				tier2Enabled: false,
+				staleThresholdMs: 60000,
+				zombieThresholdMs: 300000,
+				nudgeIntervalMs: 30000,
+			},
+			models: {},
+			logging: {
+				verbose: false,
+				redactSecrets: true,
+			},
+		};
+
+		// Reset mocks and create deps object
+		mockListSessions.mockReset();
+		mockIsProcessAlive.mockReset();
+		mockListSessions.mockResolvedValue([]);
+		mockIsProcessAlive.mockReturnValue(true);
+
+		mockDeps = {
+			listSessions: mockListSessions,
+			isProcessAlive: mockIsProcessAlive,
+		};
+	});
+
+	afterEach(() => {
+		if (existsSync(repoRoot)) {
+			rmSync(repoRoot, { recursive: true, force: true });
+		}
+	});
+
+	test("returns all pass when no sessions exist", async () => {
+		const checks = await checkConsistency(config, agentplateDir, mockDeps);
+
+		expect(checks.length).toBeGreaterThan(0);
+		const passChecks = checks.filter((c) => c.status === "pass");
+		expect(passChecks.length).toBeGreaterThan(0);
+
+		const failChecks = checks.filter((c) => c.status === "fail");
+		expect(failChecks.length).toBe(0);
+	});
+
+	test("detects orphaned worktrees", async () => {
+		// Create a worktree but don't add it to SessionStore
+		const worktreePath = join(agentplateDir, "worktrees", "orphan-agent");
+		createWorktree(repoRoot, worktreePath, "agentplate/orphan-agent/test-123");
+
+		const checks = await checkConsistency(config, agentplateDir, mockDeps);
+
+		const orphanCheck = checks.find((c) => c.name === "orphaned-worktrees");
+		expect(orphanCheck).toBeDefined();
+		expect(orphanCheck?.status).toBe("warn");
+		expect(orphanCheck?.message).toContain("1 orphaned worktree");
+		expect(orphanCheck?.details?.length).toBe(1);
+		expect(orphanCheck?.fixable).toBe(true);
+	});
+
+	test("detects orphaned tmux sessions", async () => {
+		// Mock a tmux session that isn't in SessionStore
+		mockListSessions.mockResolvedValue([{ name: "agentplate-testproject-orphan", pid: 9999 }]);
+
+		const checks = await checkConsistency(config, agentplateDir, mockDeps);
+
+		const orphanCheck = checks.find((c) => c.name === "orphaned-tmux");
+		expect(orphanCheck).toBeDefined();
+		expect(orphanCheck?.status).toBe("warn");
+		expect(orphanCheck?.message).toContain("1 orphaned tmux session");
+		expect(orphanCheck?.fixable).toBe(true);
+	});
+
+	test("ignores tmux sessions from other projects", async () => {
+		// Mock tmux sessions from different projects
+		mockListSessions.mockResolvedValue([
+			{ name: "agentplate-otherproject-agent1", pid: 9999 },
+			{ name: "my-custom-session", pid: 8888 },
+		]);
+
+		const checks = await checkConsistency(config, agentplateDir, mockDeps);
+
+		const orphanCheck = checks.find((c) => c.name === "orphaned-tmux");
+		expect(orphanCheck).toBeDefined();
+		expect(orphanCheck?.status).toBe("pass");
+		expect(orphanCheck?.message).toContain("No orphaned tmux sessions");
+	});
+
+	test("detects dead PIDs in SessionStore", async () => {
+		// Create a session with a PID that's marked as dead
+		const dbPath = join(agentplateDir, "sessions.db");
+		const store = createSessionStore(dbPath);
+
+		store.upsert({
+			id: "session-1",
+			agentName: "dead-agent",
+			capability: "builder",
+			worktreePath: join(agentplateDir, "worktrees", "dead-agent"),
+			branchName: "agentplate/dead-agent/test-123",
+			taskId: "test-123",
+			tmuxSession: "agentplate-testproject-dead-agent",
+			state: "working",
+			pid: 99999, // Non-existent PID
+			parentAgent: null,
+			depth: 0,
+			runId: null,
+			startedAt: new Date().toISOString(),
+			lastActivity: new Date().toISOString(),
+			escalationLevel: 0,
+			stalledSince: null,
+			transcriptPath: null,
+		});
+		store.close();
+
+		// Mock that this PID is not alive
+		mockIsProcessAlive.mockReturnValue(false);
+
+		const checks = await checkConsistency(config, agentplateDir, mockDeps);
+
+		const deadPidCheck = checks.find((c) => c.name === "dead-pids");
+		expect(deadPidCheck).toBeDefined();
+		expect(deadPidCheck?.status).toBe("warn");
+		expect(deadPidCheck?.message).toContain("1 session(s) with dead PIDs");
+		expect(deadPidCheck?.fixable).toBe(true);
+	});
+
+	test("passes when all PIDs are alive", async () => {
+		const dbPath = join(agentplateDir, "sessions.db");
+		const store = createSessionStore(dbPath);
+
+		store.upsert({
+			id: "session-1",
+			agentName: "live-agent",
+			capability: "builder",
+			worktreePath: join(agentplateDir, "worktrees", "live-agent"),
+			branchName: "agentplate/live-agent/test-123",
+			taskId: "test-123",
+			tmuxSession: "agentplate-testproject-live-agent",
+			state: "working",
+			pid: 12345,
+			parentAgent: null,
+			depth: 0,
+			runId: null,
+			startedAt: new Date().toISOString(),
+			lastActivity: new Date().toISOString(),
+			escalationLevel: 0,
+			stalledSince: null,
+			transcriptPath: null,
+		});
+		store.close();
+
+		// Mock that this PID is alive
+		mockIsProcessAlive.mockReturnValue(true);
+
+		const checks = await checkConsistency(config, agentplateDir, mockDeps);
+
+		const deadPidCheck = checks.find((c) => c.name === "dead-pids");
+		expect(deadPidCheck).toBeDefined();
+		expect(deadPidCheck?.status).toBe("pass");
+	});
+
+	test("detects missing worktrees for SessionStore entries", async () => {
+		const dbPath = join(agentplateDir, "sessions.db");
+		const store = createSessionStore(dbPath);
+
+		const missingWorktreePath = join(agentplateDir, "worktrees", "missing-agent");
+		store.upsert({
+			id: "session-1",
+			agentName: "missing-agent",
+			capability: "builder",
+			worktreePath: missingWorktreePath,
+			branchName: "agentplate/missing-agent/test-123",
+			taskId: "test-123",
+			tmuxSession: "agentplate-testproject-missing-agent",
+			state: "working",
+			pid: null,
+			parentAgent: null,
+			depth: 0,
+			runId: null,
+			startedAt: new Date().toISOString(),
+			lastActivity: new Date().toISOString(),
+			escalationLevel: 0,
+			stalledSince: null,
+			transcriptPath: null,
+		});
+		store.close();
+
+		const checks = await checkConsistency(config, agentplateDir, mockDeps);
+
+		const missingCheck = checks.find((c) => c.name === "missing-worktrees");
+		expect(missingCheck).toBeDefined();
+		expect(missingCheck?.status).toBe("warn");
+		expect(missingCheck?.message).toContain("1 session(s) with missing worktrees");
+		expect(missingCheck?.fixable).toBe(true);
+	});
+
+	test("detects missing tmux sessions for SessionStore entries", async () => {
+		const dbPath = join(agentplateDir, "sessions.db");
+		const store = createSessionStore(dbPath);
+
+		const worktreePath = join(agentplateDir, "worktrees", "agent-without-tmux");
+		createWorktree(repoRoot, worktreePath, "agentplate/agent-without-tmux/test-123");
+
+		store.upsert({
+			id: "session-1",
+			agentName: "agent-without-tmux",
+			capability: "builder",
+			worktreePath,
+			branchName: "agentplate/agent-without-tmux/test-123",
+			taskId: "test-123",
+			tmuxSession: "agentplate-testproject-agent-without-tmux",
+			state: "working",
+			pid: null,
+			parentAgent: null,
+			depth: 0,
+			runId: null,
+			startedAt: new Date().toISOString(),
+			lastActivity: new Date().toISOString(),
+			escalationLevel: 0,
+			stalledSince: null,
+			transcriptPath: null,
+		});
+		store.close();
+
+		// Mock empty tmux sessions list
+		mockListSessions.mockResolvedValue([]);
+
+		const checks = await checkConsistency(config, agentplateDir, mockDeps);
+
+		const missingCheck = checks.find((c) => c.name === "missing-tmux");
+		expect(missingCheck).toBeDefined();
+		expect(missingCheck?.status).toBe("warn");
+		expect(missingCheck?.message).toContain("1 session(s) with missing tmux sessions");
+		expect(missingCheck?.fixable).toBe(true);
+	});
+
+	test("passes when everything is consistent", async () => {
+		const dbPath = join(agentplateDir, "sessions.db");
+		const store = createSessionStore(dbPath);
+
+		const worktreePath = join(agentplateDir, "worktrees", "consistent-agent");
+		createWorktree(repoRoot, worktreePath, "agentplate/consistent-agent/test-123");
+
+		store.upsert({
+			id: "session-1",
+			agentName: "consistent-agent",
+			capability: "builder",
+			worktreePath,
+			branchName: "agentplate/consistent-agent/test-123",
+			taskId: "test-123",
+			tmuxSession: "agentplate-testproject-consistent-agent",
+			state: "working",
+			pid: 12345,
+			parentAgent: null,
+			depth: 0,
+			runId: null,
+			startedAt: new Date().toISOString(),
+			lastActivity: new Date().toISOString(),
+			escalationLevel: 0,
+			stalledSince: null,
+			transcriptPath: null,
+		});
+		store.close();
+
+		// Mock matching tmux session
+		mockListSessions.mockResolvedValue([
+			{ name: "agentplate-testproject-consistent-agent", pid: 12345 },
+		]);
+
+		// Mock PID as alive
+		mockIsProcessAlive.mockReturnValue(true);
+
+		const checks = await checkConsistency(config, agentplateDir, mockDeps);
+
+		const warnOrFail = checks.filter((c) => c.status === "warn" || c.status === "fail");
+		expect(warnOrFail.length).toBe(0);
+	});
+
+	test("ignores completed sessions whose tmux, pid, and worktree are gone", async () => {
+		const dbPath = join(agentplateDir, "sessions.db");
+		const store = createSessionStore(dbPath);
+
+		store.upsert({
+			id: "session-1",
+			agentName: "completed-agent",
+			capability: "builder",
+			worktreePath: join(agentplateDir, "worktrees", "completed-agent"),
+			branchName: "agentplate/completed-agent/test-123",
+			taskId: "test-123",
+			tmuxSession: "agentplate-testproject-completed-agent",
+			state: "completed",
+			pid: 99999,
+			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);
+		mockListSessions.mockResolvedValue([]);
+
+		const checks = await checkConsistency(config, agentplateDir, mockDeps);
+
+		expect(checks.find((c) => c.name === "dead-pids")?.status).toBe("pass");
+		expect(checks.find((c) => c.name === "missing-worktrees")?.status).toBe("pass");
+		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(agentplateDir, "sessions.db");
+		const store = createSessionStore(dbPath);
+
+		store.upsert({
+			id: "session-1",
+			agentName: "orphaned-agent",
+			capability: "builder",
+			worktreePath: join(agentplateDir, "worktrees", "orphaned-agent"),
+			branchName: "agentplate/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, agentplateDir, 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(agentplateDir, "sessions.db");
+		const store = createSessionStore(dbPath);
+
+		store.upsert({
+			id: "session-1",
+			agentName: "tmux-dead-agent",
+			capability: "builder",
+			worktreePath: join(agentplateDir, "worktrees", "tmux-dead-agent"),
+			branchName: "agentplate/tmux-dead-agent/test-123",
+			taskId: "test-123",
+			tmuxSession: "agentplate-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, agentplateDir, 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(agentplateDir, "sessions.db");
+		const store = createSessionStore(dbPath);
+
+		store.upsert({
+			id: "session-1",
+			agentName: "clean-completed",
+			capability: "builder",
+			worktreePath: join(agentplateDir, "worktrees", "clean-completed"),
+			branchName: "agentplate/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, agentplateDir, 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"));
+
+		const checks = await checkConsistency(config, agentplateDir, mockDeps);
+
+		const tmuxCheck = checks.find((c) => c.name === "tmux-listing");
+		expect(tmuxCheck).toBeDefined();
+		expect(tmuxCheck?.status).toBe("warn");
+		expect(tmuxCheck?.message).toContain("Failed to list tmux sessions");
+	});
+
+	test("fails early if git worktree list fails", async () => {
+		// Use a non-existent repo root to trigger worktree listing failure
+		const badConfig = { ...config, project: { ...config.project, root: "/nonexistent" } };
+
+		const checks = await checkConsistency(badConfig, agentplateDir, mockDeps);
+
+		expect(checks.length).toBe(1);
+		expect(checks[0]?.name).toBe("worktree-listing");
+		expect(checks[0]?.status).toBe("fail");
+	});
+
+	test("fails early if SessionStore cannot be opened", async () => {
+		// Use a bad agentplate directory path
+		const badAgentplateDir = "/nonexistent/.agentplate";
+
+		const checks = await checkConsistency(config, badAgentplateDir, mockDeps);
+
+		const storeCheck = checks.find((c) => c.name === "sessionstore-open");
+		expect(storeCheck).toBeDefined();
+		expect(storeCheck?.status).toBe("fail");
+	});
+
+	test("reviewer-coverage: leads without reviewers emits warn", async () => {
+		const dbPath = join(agentplateDir, "sessions.db");
+		const store = createSessionStore(dbPath);
+
+		// Add 2 builder sessions under lead-1, no reviewers
+		store.upsert({
+			id: "session-1",
+			agentName: "builder-1",
+			capability: "builder",
+			worktreePath: join(agentplateDir, "worktrees", "builder-1"),
+			branchName: "agentplate/builder-1/test-123",
+			taskId: "test-123",
+			tmuxSession: "agentplate-testproject-builder-1",
+			state: "working",
+			pid: null,
+			parentAgent: "lead-1",
+			depth: 1,
+			runId: null,
+			startedAt: new Date().toISOString(),
+			lastActivity: new Date().toISOString(),
+			escalationLevel: 0,
+			stalledSince: null,
+			transcriptPath: null,
+		});
+
+		store.upsert({
+			id: "session-2",
+			agentName: "builder-2",
+			capability: "builder",
+			worktreePath: join(agentplateDir, "worktrees", "builder-2"),
+			branchName: "agentplate/builder-2/test-456",
+			taskId: "test-456",
+			tmuxSession: "agentplate-testproject-builder-2",
+			state: "working",
+			pid: null,
+			parentAgent: "lead-1",
+			depth: 1,
+			runId: null,
+			startedAt: new Date().toISOString(),
+			lastActivity: new Date().toISOString(),
+			escalationLevel: 0,
+			stalledSince: null,
+			transcriptPath: null,
+		});
+		store.close();
+
+		const checks = await checkConsistency(config, agentplateDir, mockDeps);
+
+		const reviewerCheck = checks.find((c) => c.name === "reviewer-coverage");
+		expect(reviewerCheck).toBeDefined();
+		expect(reviewerCheck?.status).toBe("warn");
+		expect(reviewerCheck?.message).toContain("without any reviewers");
+		expect(reviewerCheck?.details).toBeDefined();
+		expect(reviewerCheck?.details?.length).toBeGreaterThan(0);
+	});
+
+	test("reviewer-coverage: partial reviewer coverage emits warn", async () => {
+		const dbPath = join(agentplateDir, "sessions.db");
+		const store = createSessionStore(dbPath);
+
+		// Add 3 builders and 1 reviewer under same parent
+		for (let i = 1; i <= 3; i++) {
+			store.upsert({
+				id: `session-builder-${i}`,
+				agentName: `builder-${i}`,
+				capability: "builder",
+				worktreePath: join(agentplateDir, "worktrees", `builder-${i}`),
+				branchName: `agentplate/builder-${i}/test-${i}`,
+				taskId: `test-${i}`,
+				tmuxSession: `agentplate-testproject-builder-${i}`,
+				state: "working",
+				pid: null,
+				parentAgent: "lead-1",
+				depth: 1,
+				runId: null,
+				startedAt: new Date().toISOString(),
+				lastActivity: new Date().toISOString(),
+				escalationLevel: 0,
+				stalledSince: null,
+				transcriptPath: null,
+			});
+		}
+
+		store.upsert({
+			id: "session-reviewer-1",
+			agentName: "reviewer-1",
+			capability: "reviewer",
+			worktreePath: join(agentplateDir, "worktrees", "reviewer-1"),
+			branchName: "agentplate/reviewer-1/test-r1",
+			taskId: "test-r1",
+			tmuxSession: "agentplate-testproject-reviewer-1",
+			state: "working",
+			pid: null,
+			parentAgent: "lead-1",
+			depth: 1,
+			runId: null,
+			startedAt: new Date().toISOString(),
+			lastActivity: new Date().toISOString(),
+			escalationLevel: 0,
+			stalledSince: null,
+			transcriptPath: null,
+		});
+		store.close();
+
+		const checks = await checkConsistency(config, agentplateDir, mockDeps);
+
+		const reviewerCheck = checks.find((c) => c.name === "reviewer-coverage");
+		expect(reviewerCheck).toBeDefined();
+		expect(reviewerCheck?.status).toBe("warn");
+		expect(reviewerCheck?.message).toContain("partial reviewer coverage");
+	});
+
+	test("reviewer-coverage: full reviewer coverage emits pass", async () => {
+		const dbPath = join(agentplateDir, "sessions.db");
+		const store = createSessionStore(dbPath);
+
+		// Add 2 builders and 2 reviewers under same parent
+		for (let i = 1; i <= 2; i++) {
+			store.upsert({
+				id: `session-builder-${i}`,
+				agentName: `builder-${i}`,
+				capability: "builder",
+				worktreePath: join(agentplateDir, "worktrees", `builder-${i}`),
+				branchName: `agentplate/builder-${i}/test-${i}`,
+				taskId: `test-${i}`,
+				tmuxSession: `agentplate-testproject-builder-${i}`,
+				state: "working",
+				pid: null,
+				parentAgent: "lead-1",
+				depth: 1,
+				runId: null,
+				startedAt: new Date().toISOString(),
+				lastActivity: new Date().toISOString(),
+				escalationLevel: 0,
+				stalledSince: null,
+				transcriptPath: null,
+			});
+
+			store.upsert({
+				id: `session-reviewer-${i}`,
+				agentName: `reviewer-${i}`,
+				capability: "reviewer",
+				worktreePath: join(agentplateDir, "worktrees", `reviewer-${i}`),
+				branchName: `agentplate/reviewer-${i}/test-r${i}`,
+				taskId: `test-r${i}`,
+				tmuxSession: `agentplate-testproject-reviewer-${i}`,
+				state: "working",
+				pid: null,
+				parentAgent: "lead-1",
+				depth: 1,
+				runId: null,
+				startedAt: new Date().toISOString(),
+				lastActivity: new Date().toISOString(),
+				escalationLevel: 0,
+				stalledSince: null,
+				transcriptPath: null,
+			});
+		}
+		store.close();
+
+		const checks = await checkConsistency(config, agentplateDir, mockDeps);
+
+		const reviewerCheck = checks.find((c) => c.name === "reviewer-coverage");
+		expect(reviewerCheck).toBeDefined();
+		expect(reviewerCheck?.status).toBe("pass");
+	});
+
+	test("reviewer-coverage: no builder sessions emits pass", async () => {
+		// Don't create any sessions at all
+		const checks = await checkConsistency(config, agentplateDir, mockDeps);
+
+		const reviewerCheck = checks.find((c) => c.name === "reviewer-coverage");
+		expect(reviewerCheck).toBeDefined();
+		expect(reviewerCheck?.status).toBe("pass");
+		expect(reviewerCheck?.message).toContain("No builder sessions found");
+	});
+
+	test("reviewer-coverage: multiple leads mixed coverage", async () => {
+		const dbPath = join(agentplateDir, "sessions.db");
+		const store = createSessionStore(dbPath);
+
+		// Lead-1 has builders + reviewers (good)
+		store.upsert({
+			id: "session-builder-1",
+			agentName: "builder-1",
+			capability: "builder",
+			worktreePath: join(agentplateDir, "worktrees", "builder-1"),
+			branchName: "agentplate/builder-1/test-1",
+			taskId: "test-1",
+			tmuxSession: "agentplate-testproject-builder-1",
+			state: "working",
+			pid: null,
+			parentAgent: "lead-1",
+			depth: 1,
+			runId: null,
+			startedAt: new Date().toISOString(),
+			lastActivity: new Date().toISOString(),
+			escalationLevel: 0,
+			stalledSince: null,
+			transcriptPath: null,
+		});
+
+		store.upsert({
+			id: "session-reviewer-1",
+			agentName: "reviewer-1",
+			capability: "reviewer",
+			worktreePath: join(agentplateDir, "worktrees", "reviewer-1"),
+			branchName: "agentplate/reviewer-1/test-r1",
+			taskId: "test-r1",
+			tmuxSession: "agentplate-testproject-reviewer-1",
+			state: "working",
+			pid: null,
+			parentAgent: "lead-1",
+			depth: 1,
+			runId: null,
+			startedAt: new Date().toISOString(),
+			lastActivity: new Date().toISOString(),
+			escalationLevel: 0,
+			stalledSince: null,
+			transcriptPath: null,
+		});
+
+		// Lead-2 has builders only (bad)
+		store.upsert({
+			id: "session-builder-2",
+			agentName: "builder-2",
+			capability: "builder",
+			worktreePath: join(agentplateDir, "worktrees", "builder-2"),
+			branchName: "agentplate/builder-2/test-2",
+			taskId: "test-2",
+			tmuxSession: "agentplate-testproject-builder-2",
+			state: "working",
+			pid: null,
+			parentAgent: "lead-2",
+			depth: 1,
+			runId: null,
+			startedAt: new Date().toISOString(),
+			lastActivity: new Date().toISOString(),
+			escalationLevel: 0,
+			stalledSince: null,
+			transcriptPath: null,
+		});
+		store.close();
+
+		const checks = await checkConsistency(config, agentplateDir, mockDeps);
+
+		const reviewerCheck = checks.find((c) => c.name === "reviewer-coverage");
+		expect(reviewerCheck).toBeDefined();
+		expect(reviewerCheck?.status).toBe("warn");
+		expect(reviewerCheck?.details).toBeDefined();
+		// Should contain lead-2 in the details
+		const detailsStr = reviewerCheck?.details?.join(" ");
+		expect(detailsStr).toContain("lead-2");
+	});
+});