@os-eco/overstory-cli 0.6.1

package/src/doctor/consistency.ts

@@ -0,0 +1,294 @@
+import { realpathSync } from "node:fs";
+import { join } from "node:path";
+import { openSessionStore } from "../sessions/compat.ts";
+import type { AgentSession, OverstoryConfig } from "../types.ts";
+import { listWorktrees } from "../worktree/manager.ts";
+import { isProcessAlive, listSessions } from "../worktree/tmux.ts";
+import type { DoctorCheck } from "./types.ts";
+
+/**
+ * Dependencies for consistency checks.
+ * Allows injection for testing without module-level mocks.
+ */
+export interface ConsistencyCheckDeps {
+	listSessions: () => Promise<Array<{ name: string; pid: number }>>;
+	isProcessAlive: (pid: number) => boolean;
+}
+
+/**
+ * Cross-subsystem consistency checks.
+ * Validates SessionStore vs worktrees, tmux sessions vs sessions, etc.
+ *
+ * @param config - Overstory configuration
+ * @param overstoryDir - Absolute path to .overstory/
+ * @param deps - Optional dependencies for testing (defaults to real implementations)
+ */
+export async function checkConsistency(
+	config: OverstoryConfig,
+	overstoryDir: string,
+	deps?: ConsistencyCheckDeps,
+): Promise<DoctorCheck[]> {
+	// Use injected dependencies or defaults
+	const { listSessions: listSessionsFn, isProcessAlive: isProcessAliveFn } = deps || {
+		listSessions,
+		isProcessAlive,
+	};
+	const checks: DoctorCheck[] = [];
+
+	// Gather data from all three sources
+	let worktrees: Array<{ path: string; branch: string; head: string }> = [];
+	let tmuxSessions: Array<{ name: string; pid: number }> = [];
+	let storeSessions: AgentSession[] = [];
+
+	// 1. List git worktrees
+	try {
+		worktrees = await listWorktrees(config.project.root);
+	} catch (error) {
+		checks.push({
+			name: "worktree-listing",
+			category: "consistency",
+			status: "fail",
+			message: "Failed to list git worktrees",
+			details: [error instanceof Error ? error.message : String(error)],
+		});
+		// Can't continue consistency checks without worktree data
+		return checks;
+	}
+
+	// 2. List tmux sessions
+	try {
+		tmuxSessions = await listSessionsFn();
+	} catch (error) {
+		// Tmux not installed or not running is not necessarily a fatal error
+		checks.push({
+			name: "tmux-listing",
+			category: "consistency",
+			status: "warn",
+			message: "Failed to list tmux sessions (tmux may not be installed)",
+			details: [error instanceof Error ? error.message : String(error)],
+		});
+		// Continue with empty tmux session list
+		tmuxSessions = [];
+	}
+
+	// 3. Open SessionStore and get all sessions
+	let storeHandle: ReturnType<typeof openSessionStore>["store"] | null = null;
+	try {
+		const { store } = openSessionStore(overstoryDir);
+		storeHandle = store;
+		storeSessions = store.getAll();
+	} catch (error) {
+		checks.push({
+			name: "sessionstore-open",
+			category: "consistency",
+			status: "fail",
+			message: "Failed to open SessionStore",
+			details: [error instanceof Error ? error.message : String(error)],
+		});
+		// Can't do consistency checks without SessionStore
+		return checks;
+	}
+
+	// Now perform cross-validation checks
+
+	// 4. Check for orphaned worktrees (worktree exists but no SessionStore entry)
+	// Normalize all paths to handle symlinks like /tmp -> /private/tmp on macOS
+	const worktreeBasePath = realpathSync(join(overstoryDir, "worktrees"));
+	const overstoryWorktrees = worktrees.filter((wt) => wt.path.startsWith(worktreeBasePath));
+
+	// Normalize SessionStore paths for comparison
+	const storeWorktreePaths = new Set(
+		storeSessions.map((s) => {
+			try {
+				return realpathSync(s.worktreePath);
+			} catch {
+				// Path doesn't exist, use as-is
+				return s.worktreePath;
+			}
+		}),
+	);
+
+	const orphanedWorktrees = overstoryWorktrees.filter((wt) => !storeWorktreePaths.has(wt.path));
+
+	if (orphanedWorktrees.length > 0) {
+		checks.push({
+			name: "orphaned-worktrees",
+			category: "consistency",
+			status: "warn",
+			message: `Found ${orphanedWorktrees.length} orphaned worktree(s) with no SessionStore entry`,
+			details: orphanedWorktrees.map((wt) => `${wt.path} (branch: ${wt.branch})`),
+			fixable: true,
+		});
+	} else {
+		checks.push({
+			name: "orphaned-worktrees",
+			category: "consistency",
+			status: "pass",
+			message: "No orphaned worktrees found",
+		});
+	}
+
+	// 5. Check for orphaned tmux sessions (tmux session exists but no SessionStore entry)
+	const projectName = config.project.name;
+	const overstoryTmuxPrefix = `overstory-${projectName}-`;
+	const overstoryTmuxSessions = tmuxSessions.filter((s) => s.name.startsWith(overstoryTmuxPrefix));
+	const storeTmuxNames = new Set(storeSessions.map((s) => s.tmuxSession));
+
+	const orphanedTmux = overstoryTmuxSessions.filter((s) => !storeTmuxNames.has(s.name));
+
+	if (orphanedTmux.length > 0) {
+		checks.push({
+			name: "orphaned-tmux",
+			category: "consistency",
+			status: "warn",
+			message: `Found ${orphanedTmux.length} orphaned tmux session(s) with no SessionStore entry`,
+			details: orphanedTmux.map((s) => `${s.name} (pid: ${s.pid})`),
+			fixable: true,
+		});
+	} else {
+		checks.push({
+			name: "orphaned-tmux",
+			category: "consistency",
+			status: "pass",
+			message: "No orphaned tmux sessions found",
+		});
+	}
+
+	// 6. Check for dead processes in SessionStore
+	const deadSessions = storeSessions.filter((s) => s.pid !== null && !isProcessAliveFn(s.pid));
+
+	if (deadSessions.length > 0) {
+		checks.push({
+			name: "dead-pids",
+			category: "consistency",
+			status: "warn",
+			message: `Found ${deadSessions.length} session(s) with dead PIDs`,
+			details: deadSessions.map((s) => `${s.agentName} (pid: ${s.pid}, state: ${s.state})`),
+			fixable: true,
+		});
+	} else {
+		checks.push({
+			name: "dead-pids",
+			category: "consistency",
+			status: "pass",
+			message: "All SessionStore PIDs are alive or null",
+		});
+	}
+
+	// 7. Check for SessionStore entries with missing worktrees
+	const existingWorktreePaths = new Set(worktrees.map((wt) => wt.path));
+	const missingWorktrees = storeSessions.filter((s) => {
+		// Try to normalize the SessionStore path for comparison
+		try {
+			const normalizedPath = realpathSync(s.worktreePath);
+			return !existingWorktreePaths.has(normalizedPath);
+		} catch {
+			// Path doesn't exist or can't be resolved, check as-is
+			return !existingWorktreePaths.has(s.worktreePath);
+		}
+	});
+
+	if (missingWorktrees.length > 0) {
+		checks.push({
+			name: "missing-worktrees",
+			category: "consistency",
+			status: "warn",
+			message: `Found ${missingWorktrees.length} session(s) with missing worktrees`,
+			details: missingWorktrees.map((s) => `${s.agentName}: ${s.worktreePath}`),
+			fixable: true,
+		});
+	} else {
+		checks.push({
+			name: "missing-worktrees",
+			category: "consistency",
+			status: "pass",
+			message: "All SessionStore worktrees exist",
+		});
+	}
+
+	// 8. Check for SessionStore entries with missing tmux sessions
+	const existingTmuxNames = new Set(tmuxSessions.map((s) => s.name));
+	const missingTmux = storeSessions.filter((s) => !existingTmuxNames.has(s.tmuxSession));
+
+	if (missingTmux.length > 0) {
+		checks.push({
+			name: "missing-tmux",
+			category: "consistency",
+			status: "warn",
+			message: `Found ${missingTmux.length} session(s) with missing tmux sessions`,
+			details: missingTmux.map((s) => `${s.agentName}: ${s.tmuxSession}`),
+			fixable: true,
+		});
+	} else {
+		checks.push({
+			name: "missing-tmux",
+			category: "consistency",
+			status: "pass",
+			message: "All SessionStore tmux sessions exist",
+		});
+	}
+
+	// 9. Check reviewer-to-builder ratio per lead
+	const parentGroups = new Map<string, { builders: number; reviewers: number }>();
+	for (const session of storeSessions) {
+		if (
+			session.parentAgent &&
+			(session.capability === "builder" || session.capability === "reviewer")
+		) {
+			const group = parentGroups.get(session.parentAgent) ?? { builders: 0, reviewers: 0 };
+			if (session.capability === "builder") {
+				group.builders++;
+			} else {
+				group.reviewers++;
+			}
+			parentGroups.set(session.parentAgent, group);
+		}
+	}
+
+	const leadsWithoutReview: string[] = [];
+	const leadsWithPartialReview: string[] = [];
+	for (const [parent, counts] of parentGroups) {
+		if (counts.builders > 0 && counts.reviewers === 0) {
+			leadsWithoutReview.push(`${parent}: ${counts.builders} builder(s), 0 reviewers`);
+		} else if (counts.builders > 0 && counts.reviewers < counts.builders) {
+			leadsWithPartialReview.push(
+				`${parent}: ${counts.builders} builder(s), ${counts.reviewers} reviewer(s)`,
+			);
+		}
+	}
+
+	if (leadsWithoutReview.length > 0) {
+		checks.push({
+			name: "reviewer-coverage",
+			category: "consistency",
+			status: "warn",
+			message: `${leadsWithoutReview.length} lead(s) spawned builders without any reviewers`,
+			details: [...leadsWithoutReview, ...leadsWithPartialReview],
+		});
+	} else if (leadsWithPartialReview.length > 0) {
+		checks.push({
+			name: "reviewer-coverage",
+			category: "consistency",
+			status: "warn",
+			message: `${leadsWithPartialReview.length} lead(s) have partial reviewer coverage`,
+			details: leadsWithPartialReview,
+		});
+	} else {
+		checks.push({
+			name: "reviewer-coverage",
+			category: "consistency",
+			status: "pass",
+			message:
+				parentGroups.size > 0
+					? "All leads have reviewer coverage for builders"
+					: "No builder sessions found (nothing to check)",
+		});
+	}
+
+	// Close the SessionStore
+	if (storeHandle) {
+		storeHandle.close();
+	}
+
+	return checks;
+}

package/src/doctor/databases.test.ts

@@ -0,0 +1,290 @@
+import { Database } from "bun:sqlite";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { OverstoryConfig } from "../types.ts";
+import { checkDatabases } from "./databases.ts";
+import type { DoctorCheck } from "./types.ts";
+
+describe("checkDatabases", () => {
+	let tempDir: string;
+	let mockConfig: OverstoryConfig;
+
+	beforeEach(() => {
+		tempDir = mkdtempSync(join(tmpdir(), "overstory-test-"));
+		mockConfig = {
+			project: { name: "test", root: tempDir, canonicalBranch: "main" },
+			agents: {
+				manifestPath: "",
+				baseDir: "",
+				maxConcurrent: 5,
+				staggerDelayMs: 100,
+				maxDepth: 2,
+				maxSessionsPerRun: 0,
+			},
+			worktrees: { baseDir: "" },
+			taskTracker: { backend: "auto", enabled: true },
+			mulch: { enabled: true, domains: [], primeFormat: "markdown" },
+			merge: { aiResolveEnabled: false, reimagineEnabled: false },
+			providers: {
+				anthropic: { type: "native" },
+			},
+			watchdog: {
+				tier0Enabled: true,
+				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("fails when database files do not exist", () => {
+		const checks = checkDatabases(mockConfig, tempDir) as DoctorCheck[];
+
+		expect(checks).toHaveLength(3);
+		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");
+	});
+
+	test("passes when databases exist with correct schema", () => {
+		// Create mail.db
+		const mailDb = new Database(join(tempDir, "mail.db"));
+		mailDb.exec("PRAGMA journal_mode=WAL");
+		mailDb.exec(`
+			CREATE TABLE messages (
+				id TEXT PRIMARY KEY,
+				from_agent TEXT NOT NULL,
+				to_agent TEXT NOT NULL,
+				subject TEXT NOT NULL,
+				body TEXT NOT NULL,
+				type TEXT NOT NULL DEFAULT 'status',
+				priority TEXT NOT NULL DEFAULT 'normal',
+				thread_id TEXT,
+				payload TEXT,
+				read INTEGER NOT NULL DEFAULT 0,
+				created_at TEXT NOT NULL DEFAULT (datetime('now'))
+			)
+		`);
+		mailDb.close();
+
+		// Create metrics.db
+		const metricsDb = new Database(join(tempDir, "metrics.db"));
+		metricsDb.exec("PRAGMA journal_mode=WAL");
+		metricsDb.exec(`
+			CREATE TABLE sessions (
+				agent_name TEXT NOT NULL,
+				task_id TEXT NOT NULL,
+				capability TEXT NOT NULL,
+				started_at TEXT NOT NULL,
+				completed_at TEXT,
+				duration_ms INTEGER NOT NULL DEFAULT 0,
+				exit_code INTEGER,
+				merge_result TEXT,
+				parent_agent TEXT,
+				input_tokens INTEGER NOT NULL DEFAULT 0,
+				output_tokens INTEGER NOT NULL DEFAULT 0,
+				cache_read_tokens INTEGER NOT NULL DEFAULT 0,
+				cache_creation_tokens INTEGER NOT NULL DEFAULT 0,
+				estimated_cost_usd REAL,
+				model_used TEXT,
+				PRIMARY KEY (agent_name, task_id)
+			)
+		`);
+		metricsDb.close();
+
+		// Create sessions.db
+		const sessionsDb = new Database(join(tempDir, "sessions.db"));
+		sessionsDb.exec("PRAGMA journal_mode=WAL");
+		sessionsDb.exec(`
+			CREATE TABLE sessions (
+				id TEXT PRIMARY KEY,
+				agent_name TEXT NOT NULL UNIQUE,
+				capability TEXT NOT NULL,
+				worktree_path TEXT NOT NULL,
+				branch_name TEXT NOT NULL,
+				task_id TEXT NOT NULL,
+				tmux_session TEXT NOT NULL,
+				state TEXT NOT NULL DEFAULT 'booting',
+				pid INTEGER,
+				parent_agent TEXT,
+				depth INTEGER NOT NULL DEFAULT 0,
+				run_id TEXT,
+				started_at TEXT NOT NULL,
+				last_activity TEXT NOT NULL,
+				escalation_level INTEGER NOT NULL DEFAULT 0,
+				stalled_since TEXT
+			)
+		`);
+		sessionsDb.exec(`
+			CREATE TABLE runs (
+				id TEXT PRIMARY KEY,
+				started_at TEXT NOT NULL,
+				completed_at TEXT,
+				agent_count INTEGER NOT NULL DEFAULT 0,
+				coordinator_session_id TEXT,
+				status TEXT NOT NULL DEFAULT 'active'
+			)
+		`);
+		sessionsDb.close();
+
+		const checks = checkDatabases(mockConfig, tempDir) as DoctorCheck[];
+
+		expect(checks).toHaveLength(3);
+		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");
+	});
+
+	test("fails when table is missing", () => {
+		// Create mail.db without messages table
+		const mailDb = new Database(join(tempDir, "mail.db"));
+		mailDb.exec("PRAGMA journal_mode=WAL");
+		mailDb.close();
+
+		// Create other databases properly to isolate the test
+		const metricsDb = new Database(join(tempDir, "metrics.db"));
+		metricsDb.exec("PRAGMA journal_mode=WAL");
+		metricsDb.exec(`
+			CREATE TABLE sessions (
+				agent_name TEXT NOT NULL,
+				task_id TEXT NOT NULL,
+				capability TEXT NOT NULL,
+				started_at TEXT NOT NULL,
+				completed_at TEXT,
+				duration_ms INTEGER NOT NULL DEFAULT 0,
+				exit_code INTEGER,
+				merge_result TEXT,
+				parent_agent TEXT,
+				input_tokens INTEGER NOT NULL DEFAULT 0,
+				output_tokens INTEGER NOT NULL DEFAULT 0,
+				cache_read_tokens INTEGER NOT NULL DEFAULT 0,
+				cache_creation_tokens INTEGER NOT NULL DEFAULT 0,
+				estimated_cost_usd REAL,
+				model_used TEXT,
+				PRIMARY KEY (agent_name, task_id)
+			)
+		`);
+		metricsDb.close();
+
+		const sessionsDb = new Database(join(tempDir, "sessions.db"));
+		sessionsDb.exec("PRAGMA journal_mode=WAL");
+		sessionsDb.exec(`
+			CREATE TABLE sessions (
+				id TEXT PRIMARY KEY,
+				agent_name TEXT NOT NULL UNIQUE,
+				capability TEXT NOT NULL,
+				worktree_path TEXT NOT NULL,
+				branch_name TEXT NOT NULL,
+				task_id TEXT NOT NULL,
+				tmux_session TEXT NOT NULL,
+				state TEXT NOT NULL DEFAULT 'booting',
+				pid INTEGER,
+				parent_agent TEXT,
+				depth INTEGER NOT NULL DEFAULT 0,
+				run_id TEXT,
+				started_at TEXT NOT NULL,
+				last_activity TEXT NOT NULL,
+				escalation_level INTEGER NOT NULL DEFAULT 0,
+				stalled_since TEXT
+			)
+		`);
+		sessionsDb.exec(`
+			CREATE TABLE runs (
+				id TEXT PRIMARY KEY,
+				started_at TEXT NOT NULL,
+				completed_at TEXT,
+				agent_count INTEGER NOT NULL DEFAULT 0,
+				coordinator_session_id TEXT,
+				status TEXT NOT NULL DEFAULT 'active'
+			)
+		`);
+		sessionsDb.close();
+
+		const checks = checkDatabases(mockConfig, tempDir) as DoctorCheck[];
+
+		const mailCheck = checks.find((c) => c?.name === "mail.db schema");
+		expect(mailCheck?.status).toBe("fail");
+		expect(mailCheck?.details).toContain("Missing tables: messages");
+	});
+
+	test("fails when column is missing", () => {
+		// Create messages table without payload column
+		const mailDb = new Database(join(tempDir, "mail.db"));
+		mailDb.exec("PRAGMA journal_mode=WAL");
+		mailDb.exec(`
+			CREATE TABLE messages (
+				id TEXT PRIMARY KEY,
+				from_agent TEXT NOT NULL,
+				to_agent TEXT NOT NULL,
+				subject TEXT NOT NULL,
+				body TEXT NOT NULL,
+				type TEXT NOT NULL DEFAULT 'status',
+				priority TEXT NOT NULL DEFAULT 'normal',
+				thread_id TEXT,
+				read INTEGER NOT NULL DEFAULT 0,
+				created_at TEXT NOT NULL DEFAULT (datetime('now'))
+			)
+		`);
+		mailDb.close();
+
+		const checks = checkDatabases(mockConfig, tempDir) as DoctorCheck[];
+
+		const mailCheck = checks.find((c) => c?.name === "mail.db schema");
+		expect(mailCheck?.status).toBe("fail");
+		expect(mailCheck?.details?.some((d) => d.includes("missing column: payload"))).toBe(true);
+	});
+
+	test("warns when WAL mode is not enabled", () => {
+		// Create database without WAL mode
+		const mailDb = new Database(join(tempDir, "mail.db"));
+		mailDb.exec(`
+			CREATE TABLE messages (
+				id TEXT PRIMARY KEY,
+				from_agent TEXT NOT NULL,
+				to_agent TEXT NOT NULL,
+				subject TEXT NOT NULL,
+				body TEXT NOT NULL,
+				type TEXT NOT NULL DEFAULT 'status',
+				priority TEXT NOT NULL DEFAULT 'normal',
+				thread_id TEXT,
+				payload TEXT,
+				read INTEGER NOT NULL DEFAULT 0,
+				created_at TEXT NOT NULL DEFAULT (datetime('now'))
+			)
+		`);
+		mailDb.close();
+
+		const checks = checkDatabases(mockConfig, tempDir) as DoctorCheck[];
+
+		const walCheck = checks.find((c) => c?.name === "mail.db WAL mode");
+		expect(walCheck?.status).toBe("warn");
+		expect(walCheck?.message).toContain("not using WAL mode");
+	});
+
+	test("fails when database is corrupted", () => {
+		// Create a corrupt database file (just write garbage)
+		const { writeFileSync } = require("node:fs");
+		writeFileSync(join(tempDir, "mail.db"), "not a valid sqlite database");
+
+		const checks = checkDatabases(mockConfig, tempDir) as DoctorCheck[];
+
+		const integrityCheck = checks.find((c) => c?.name === "mail.db integrity");
+		expect(integrityCheck?.status).toBe("fail");
+		expect(integrityCheck?.message).toContain("Failed to open or validate");
+	});
+});