@os-eco/overstory-cli 0.6.1 → 0.6.4

package/src/schema-consistency.test.ts

@@ -0,0 +1,239 @@
+/**
+ * SQL schema consistency tests.
+ *
+ * Verifies that SQL CREATE TABLE column names match the TypeScript row interfaces
+ * and row-to-object conversion functions across all four SQLite stores.
+ * Prevents regressions like the bead_id/task_id column rename that caused runtime failures.
+ *
+ * Strategy: create each store (which runs CREATE TABLE), then open a second
+ * read-only connection to the same temp file and query PRAGMA table_info().
+ * bun:sqlite with WAL mode allows concurrent readers.
+ */
+
+import { Database } from "bun:sqlite";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createEventStore } from "./events/store.ts";
+import { createMailStore } from "./mail/store.ts";
+import { createMergeQueue } from "./merge/queue.ts";
+import { createMetricsStore } from "./metrics/store.ts";
+import { createSessionStore } from "./sessions/store.ts";
+
+/** Extract sorted column names from a table via PRAGMA table_info(). */
+function getTableColumns(db: Database, tableName: string): string[] {
+	const rows = db.prepare(`PRAGMA table_info(${tableName})`).all() as Array<{ name: string }>;
+	return rows.map((r) => r.name).sort();
+}
+
+describe("SQL schema consistency", () => {
+	let tmpDir: string;
+
+	beforeEach(async () => {
+		tmpDir = await mkdtemp(join(tmpdir(), "overstory-schema-test-"));
+	});
+
+	afterEach(async () => {
+		await rm(tmpDir, { recursive: true, force: true });
+	});
+
+	describe("SessionStore", () => {
+		test("sessions table columns match SessionRow interface", () => {
+			const dbPath = join(tmpDir, "sessions.db");
+			const store = createSessionStore(dbPath);
+
+			const db = new Database(dbPath, { readonly: true });
+			const actual = getTableColumns(db, "sessions");
+			db.close();
+			store.close();
+
+			// Columns from SessionRow interface in src/sessions/store.ts
+			const expected = [
+				"agent_name",
+				"branch_name",
+				"capability",
+				"depth",
+				"escalation_level",
+				"id",
+				"last_activity",
+				"parent_agent",
+				"pid",
+				"run_id",
+				"stalled_since",
+				"started_at",
+				"state",
+				"task_id",
+				"tmux_session",
+				"worktree_path",
+			].sort();
+
+			expect(actual).toEqual(expected);
+		});
+
+		test("runs table columns match RunRow interface", () => {
+			const dbPath = join(tmpDir, "sessions.db");
+			const store = createSessionStore(dbPath);
+
+			const db = new Database(dbPath, { readonly: true });
+			const actual = getTableColumns(db, "runs");
+			db.close();
+			store.close();
+
+			// Columns from RunRow interface in src/sessions/store.ts
+			const expected = [
+				"agent_count",
+				"completed_at",
+				"coordinator_session_id",
+				"id",
+				"started_at",
+				"status",
+			].sort();
+
+			expect(actual).toEqual(expected);
+		});
+	});
+
+	describe("EventStore", () => {
+		test("events table columns match EventRow interface", () => {
+			const dbPath = join(tmpDir, "events.db");
+			const store = createEventStore(dbPath);
+
+			const db = new Database(dbPath, { readonly: true });
+			const actual = getTableColumns(db, "events");
+			db.close();
+			store.close();
+
+			// Columns from EventRow interface in src/events/store.ts
+			const expected = [
+				"agent_name",
+				"created_at",
+				"data",
+				"event_type",
+				"id",
+				"level",
+				"run_id",
+				"session_id",
+				"tool_args",
+				"tool_duration_ms",
+				"tool_name",
+			].sort();
+
+			expect(actual).toEqual(expected);
+		});
+	});
+
+	describe("MetricsStore", () => {
+		test("sessions table columns match metrics SessionRow interface", () => {
+			const dbPath = join(tmpDir, "metrics.db");
+			const store = createMetricsStore(dbPath);
+
+			const db = new Database(dbPath, { readonly: true });
+			const actual = getTableColumns(db, "sessions");
+			db.close();
+			store.close();
+
+			// Columns from SessionRow interface in src/metrics/store.ts
+			const expected = [
+				"agent_name",
+				"cache_creation_tokens",
+				"cache_read_tokens",
+				"capability",
+				"completed_at",
+				"duration_ms",
+				"estimated_cost_usd",
+				"exit_code",
+				"input_tokens",
+				"merge_result",
+				"model_used",
+				"output_tokens",
+				"parent_agent",
+				"run_id",
+				"started_at",
+				"task_id",
+			].sort();
+
+			expect(actual).toEqual(expected);
+		});
+
+		test("token_snapshots table columns match SnapshotRow interface", () => {
+			const dbPath = join(tmpDir, "metrics.db");
+			const store = createMetricsStore(dbPath);
+
+			const db = new Database(dbPath, { readonly: true });
+			const actual = getTableColumns(db, "token_snapshots");
+			db.close();
+			store.close();
+
+			// Columns from SnapshotRow interface in src/metrics/store.ts
+			const expected = [
+				"agent_name",
+				"cache_creation_tokens",
+				"cache_read_tokens",
+				"created_at",
+				"estimated_cost_usd",
+				"id",
+				"input_tokens",
+				"model_used",
+				"output_tokens",
+			].sort();
+
+			expect(actual).toEqual(expected);
+		});
+	});
+
+	describe("MailStore", () => {
+		test("messages table columns match MessageRow interface", () => {
+			const dbPath = join(tmpDir, "mail.db");
+			const store = createMailStore(dbPath);
+
+			const db = new Database(dbPath, { readonly: true });
+			const actual = getTableColumns(db, "messages");
+			db.close();
+			store.close();
+
+			// Columns from MessageRow interface in src/mail/store.ts
+			const expected = [
+				"body",
+				"created_at",
+				"from_agent",
+				"id",
+				"payload",
+				"priority",
+				"read",
+				"subject",
+				"thread_id",
+				"to_agent",
+				"type",
+			].sort();
+
+			expect(actual).toEqual(expected);
+		});
+	});
+
+	describe("MergeQueue", () => {
+		test("merge_queue table columns match MergeQueueRow interface", () => {
+			const dbPath = join(tmpDir, "merge-queue.db");
+			const queue = createMergeQueue(dbPath);
+
+			const db = new Database(dbPath, { readonly: true });
+			const actual = getTableColumns(db, "merge_queue");
+			db.close();
+			queue.close();
+
+			// Columns from MergeQueueRow interface in src/merge/queue.ts
+			const expected = [
+				"agent_name",
+				"branch_name",
+				"enqueued_at",
+				"files_modified",
+				"id",
+				"resolved_tier",
+				"status",
+				"task_id",
+			].sort();
+
+			expect(actual).toEqual(expected);
+		});
+	});
+});

package/src/sessions/compat.ts

@@ -86,7 +86,7 @@ export function openSessionStore(overstoryDir: string): {
 	// If the DB already existed AND has data, it is authoritative -- no migration needed.
 	// If the DB file exists but is empty (e.g., created by init before any sessions were
 	// recorded), fall through to check sessions.json for importable records (overstory-036f).
-	if (dbExists && store.getAll().length > 0) {
+	if (dbExists && store.count() > 0) {
 		return { store, migrated: false };
 	}
 

package/src/sessions/store.test.ts

@@ -231,6 +231,43 @@ describe("getAll", () => {
 	});
 });
 
+// === count ===
+
+describe("count", () => {
+	test("returns 0 on empty database", () => {
+		expect(store.count()).toBe(0);
+	});
+
+	test("returns correct count after inserts", () => {
+		store.upsert(makeSession({ agentName: "a1", id: "s-1" }));
+		expect(store.count()).toBe(1);
+
+		store.upsert(makeSession({ agentName: "a2", id: "s-2" }));
+		expect(store.count()).toBe(2);
+
+		store.upsert(makeSession({ agentName: "a3", id: "s-3" }));
+		expect(store.count()).toBe(3);
+	});
+
+	test("count reflects removals", () => {
+		store.upsert(makeSession({ agentName: "a1", id: "s-1" }));
+		store.upsert(makeSession({ agentName: "a2", id: "s-2" }));
+
+		store.remove("a1");
+		expect(store.count()).toBe(1);
+
+		store.remove("a2");
+		expect(store.count()).toBe(0);
+	});
+
+	test("count matches getAll().length", () => {
+		for (let i = 0; i < 5; i++) {
+			store.upsert(makeSession({ agentName: `agent-${i}`, id: `s-${i}` }));
+		}
+		expect(store.count()).toBe(store.getAll().length);
+	});
+});
+
 // === getByRun ===
 
 describe("getByRun", () => {

package/src/sessions/store.ts

@@ -18,6 +18,8 @@ export interface SessionStore {
 	getActive(): AgentSession[];
 	/** Get all sessions regardless of state. */
 	getAll(): AgentSession[];
+	/** Get the total number of sessions. Lightweight alternative to getAll().length. */
+	count(): number;
 	/** Get sessions belonging to a specific run. */
 	getByRun(runId: string): AgentSession[];
 	/** Update only the state of a session. */
@@ -233,6 +235,10 @@ export function createSessionStore(dbPath: string): SessionStore {
 		SELECT * FROM sessions ORDER BY started_at ASC
 	`);
 
+	const countStmt = db.prepare<{ cnt: number }, Record<string, never>>(
+		"SELECT COUNT(*) as cnt FROM sessions",
+	);
+
 	const getByRunStmt = db.prepare<SessionRow, { $run_id: string }>(`
 		SELECT * FROM sessions WHERE run_id = $run_id ORDER BY started_at ASC
 	`);
@@ -299,6 +305,11 @@ export function createSessionStore(dbPath: string): SessionStore {
 			return rows.map(rowToSession);
 		},
 
+		count(): number {
+			const row = countStmt.get({});
+			return row?.cnt ?? 0;
+		},
+
 		getByRun(runId: string): AgentSession[] {
 			const rows = getByRunStmt.all({ $run_id: runId });
 			return rows.map(rowToSession);

package/src/worktree/tmux.test.ts

@@ -3,6 +3,7 @@ import { AgentError } from "../errors.ts";
 import {
 	capturePaneContent,
 	createSession,
+	ensureTmuxAvailable,
 	getDescendantPids,
 	getPanePid,
 	isProcessAlive,
@@ -961,21 +962,26 @@ describe("waitForTuiReady", () => {
 	});
 
 	test("returns true after content appears on later poll", async () => {
-		let callCount = 0;
-		spawnSpy.mockImplementation(() => {
-			callCount++;
-			if (callCount <= 3) {
-				// First 3 polls: empty pane (TUI still loading)
-				return mockSpawnResult("", "", 0);
+		let captureCallCount = 0;
+		spawnSpy.mockImplementation((...args: unknown[]) => {
+			const cmd = args[0] as string[];
+			if (cmd[1] === "capture-pane") {
+				captureCallCount++;
+				if (captureCallCount <= 3) {
+					// First 3 capture-pane polls: empty pane (TUI still loading)
+					return mockSpawnResult("", "", 0);
+				}
+				// 4th poll: content appears
+				return mockSpawnResult("Welcome to Claude Code!", "", 0);
 			}
-			// 4th poll: content appears
-			return mockSpawnResult("Welcome to Claude Code!", "", 0);
+			// has-session: session is alive throughout
+			return mockSpawnResult("", "", 0);
 		});
 
 		const ready = await waitForTuiReady("overstory-agent", 10_000, 500);
 
 		expect(ready).toBe(true);
-		// Should have slept 3 times (3 empty polls before content appeared)
+		// Should have slept 3 times (3 empty capture-pane polls before content appeared)
 		expect(sleepSpy).toHaveBeenCalledTimes(3);
 	});
 
@@ -1006,4 +1012,87 @@ describe("waitForTuiReady", () => {
 
 		expect(ready).toBe(true);
 	});
+
+	test("returns false immediately when session is dead", async () => {
+		// capture-pane fails (session dead), has-session also fails (session dead)
+		spawnSpy.mockImplementation((...args: unknown[]) => {
+			const cmd = args[0] as string[];
+			if (cmd[1] === "capture-pane") {
+				return mockSpawnResult("", "can't find session", 1);
+			}
+			// has-session: session is dead
+			return mockSpawnResult("", "can't find session", 1);
+		});
+
+		const ready = await waitForTuiReady("dead-session", 15_000, 500);
+
+		expect(ready).toBe(false);
+		// Should NOT have polled the full timeout (no sleeps — returned immediately)
+		expect(sleepSpy).not.toHaveBeenCalled();
+	});
+
+	test("continues polling when session is alive but pane is empty", async () => {
+		let captureCallCount = 0;
+		spawnSpy.mockImplementation((...args: unknown[]) => {
+			const cmd = args[0] as string[];
+			if (cmd[1] === "capture-pane") {
+				captureCallCount++;
+				// Pane stays empty for all polls (session alive but TUI not rendered yet)
+				return mockSpawnResult("", "", 0);
+			}
+			// has-session: session is alive
+			return mockSpawnResult("", "", 0);
+		});
+
+		// Use a short timeout so the test doesn't take long
+		const ready = await waitForTuiReady("loading-session", 1_000, 500);
+
+		expect(ready).toBe(false);
+		// Should have polled multiple times (not returned early)
+		expect(captureCallCount).toBeGreaterThan(1);
+		expect(sleepSpy).toHaveBeenCalled();
+	});
+});
+
+describe("ensureTmuxAvailable", () => {
+	let spawnSpy: ReturnType<typeof spyOn>;
+
+	beforeEach(() => {
+		spawnSpy = spyOn(Bun, "spawn");
+	});
+
+	afterEach(() => {
+		spawnSpy.mockRestore();
+	});
+
+	test("succeeds when tmux is available", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("tmux 3.3a\n", "", 0));
+
+		// Should not throw
+		await ensureTmuxAvailable();
+
+		expect(spawnSpy).toHaveBeenCalledTimes(1);
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const cmd = callArgs[0] as string[];
+		expect(cmd).toEqual(["tmux", "-V"]);
+	});
+
+	test("throws AgentError when tmux is not installed", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("", "tmux: command not found", 1));
+
+		await expect(ensureTmuxAvailable()).rejects.toThrow(AgentError);
+	});
+
+	test("AgentError message mentions tmux not installed", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("", "", 127));
+
+		try {
+			await ensureTmuxAvailable();
+			expect(true).toBe(false); // Should have thrown
+		} catch (err: unknown) {
+			expect(err).toBeInstanceOf(AgentError);
+			const agentErr = err as AgentError;
+			expect(agentErr.message).toContain("tmux is not installed");
+		}
+	});
 });

package/src/worktree/tmux.ts

@@ -455,11 +455,29 @@ export async function waitForTuiReady(
 		if (content !== null) {
 			return true;
 		}
+		// Check if session died — no point waiting if it's gone
+		const alive = await isSessionAlive(name);
+		if (!alive) {
+			return false;
+		}
 		await Bun.sleep(pollIntervalMs);
 	}
 	return false;
 }
 
+/**
+ * Verify that tmux is installed and executable.
+ * Throws AgentError with a clear message if tmux is not available.
+ */
+export async function ensureTmuxAvailable(): Promise<void> {
+	const { exitCode } = await runCommand(["tmux", "-V"]);
+	if (exitCode !== 0) {
+		throw new AgentError(
+			"tmux is not installed or not on PATH. Install tmux to use overstory agent orchestration.",
+		);
+	}
+}
+
 /**
  * Send keys to a tmux session.
  *