@os-eco/overstory-cli 0.6.1 → 0.6.5

package/src/metrics/summary.test.ts

@@ -33,7 +33,7 @@ afterEach(async () => {
 function makeSession(overrides: Partial<SessionMetrics> = {}): SessionMetrics {
 	return {
 		agentName: "test-agent",
-		beadId: "test-task-123",
+		taskId: "test-task-123",
 		capability: "builder",
 		startedAt: new Date("2026-01-01T00:00:00Z").toISOString(),
 		completedAt: new Date("2026-01-01T00:05:00Z").toISOString(),
@@ -66,9 +66,9 @@ describe("generateSummary", () => {
 	});
 
 	test("counts total and completed sessions correctly", () => {
-		store.recordSession(makeSession({ beadId: "task-1", completedAt: "2026-01-01T00:05:00Z" }));
-		store.recordSession(makeSession({ beadId: "task-2", completedAt: null }));
-		store.recordSession(makeSession({ beadId: "task-3", completedAt: "2026-01-01T00:10:00Z" }));
+		store.recordSession(makeSession({ taskId: "task-1", completedAt: "2026-01-01T00:05:00Z" }));
+		store.recordSession(makeSession({ taskId: "task-2", completedAt: null }));
+		store.recordSession(makeSession({ taskId: "task-3", completedAt: "2026-01-01T00:10:00Z" }));
 
 		const summary = generateSummary(store);
 
@@ -79,21 +79,21 @@ describe("generateSummary", () => {
 	test("groups by capability with correct counts and avg durations", () => {
 		store.recordSession(
 			makeSession({
-				beadId: "task-1",
+				taskId: "task-1",
 				capability: "builder",
 				durationMs: 100_000,
 			}),
 		);
 		store.recordSession(
 			makeSession({
-				beadId: "task-2",
+				taskId: "task-2",
 				capability: "builder",
 				durationMs: 200_000,
 			}),
 		);
 		store.recordSession(
 			makeSession({
-				beadId: "task-3",
+				taskId: "task-3",
 				capability: "scout",
 				durationMs: 50_000,
 			}),
@@ -112,10 +112,10 @@ describe("generateSummary", () => {
 	});
 
 	test("respects the limit parameter for recentSessions", () => {
-		store.recordSession(makeSession({ beadId: "task-1" }));
-		store.recordSession(makeSession({ beadId: "task-2" }));
-		store.recordSession(makeSession({ beadId: "task-3" }));
-		store.recordSession(makeSession({ beadId: "task-4" }));
+		store.recordSession(makeSession({ taskId: "task-1" }));
+		store.recordSession(makeSession({ taskId: "task-2" }));
+		store.recordSession(makeSession({ taskId: "task-3" }));
+		store.recordSession(makeSession({ taskId: "task-4" }));
 
 		const summary = generateSummary(store, 2);
 
@@ -124,9 +124,9 @@ describe("generateSummary", () => {
 	});
 
 	test("sessions without completedAt counted in total but not completed", () => {
-		store.recordSession(makeSession({ beadId: "task-1", completedAt: null }));
-		store.recordSession(makeSession({ beadId: "task-2", completedAt: null }));
-		store.recordSession(makeSession({ beadId: "task-3", completedAt: "2026-01-01T00:05:00Z" }));
+		store.recordSession(makeSession({ taskId: "task-1", completedAt: null }));
+		store.recordSession(makeSession({ taskId: "task-2", completedAt: null }));
+		store.recordSession(makeSession({ taskId: "task-3", completedAt: "2026-01-01T00:05:00Z" }));
 
 		const summary = generateSummary(store);
 
@@ -137,7 +137,7 @@ describe("generateSummary", () => {
 	test("aggregates token totals across all sessions", () => {
 		store.recordSession(
 			makeSession({
-				beadId: "task-1",
+				taskId: "task-1",
 				inputTokens: 10_000,
 				outputTokens: 2_000,
 				cacheReadTokens: 50_000,
@@ -147,7 +147,7 @@ describe("generateSummary", () => {
 		);
 		store.recordSession(
 			makeSession({
-				beadId: "task-2",
+				taskId: "task-2",
 				inputTokens: 20_000,
 				outputTokens: 3_000,
 				cacheReadTokens: 80_000,
@@ -166,7 +166,7 @@ describe("generateSummary", () => {
 	});
 
 	test("token totals are zero when no sessions have token data", () => {
-		store.recordSession(makeSession({ beadId: "task-1" }));
+		store.recordSession(makeSession({ taskId: "task-1" }));
 
 		const summary = generateSummary(store);
 
@@ -180,14 +180,14 @@ describe("generateSummary", () => {
 	test("token totals skip null cost entries gracefully", () => {
 		store.recordSession(
 			makeSession({
-				beadId: "task-1",
+				taskId: "task-1",
 				inputTokens: 100,
 				estimatedCostUsd: 0.5,
 			}),
 		);
 		store.recordSession(
 			makeSession({
-				beadId: "task-2",
+				taskId: "task-2",
 				inputTokens: 200,
 				estimatedCostUsd: null, // no cost data
 			}),
@@ -202,7 +202,7 @@ describe("generateSummary", () => {
 	test("capability breakdown excludes incomplete sessions from avgDurationMs", () => {
 		store.recordSession(
 			makeSession({
-				beadId: "task-1",
+				taskId: "task-1",
 				capability: "builder",
 				durationMs: 100_000,
 				completedAt: null,
@@ -210,14 +210,14 @@ describe("generateSummary", () => {
 		);
 		store.recordSession(
 			makeSession({
-				beadId: "task-2",
+				taskId: "task-2",
 				capability: "builder",
 				durationMs: 200_000,
 			}),
 		);
 		store.recordSession(
 			makeSession({
-				beadId: "task-3",
+				taskId: "task-3",
 				capability: "builder",
 				durationMs: 300_000,
 			}),
@@ -242,8 +242,8 @@ describe("formatSummary", () => {
 	});
 
 	test("shows total/completed/average duration", () => {
-		store.recordSession(makeSession({ beadId: "task-1", durationMs: 100_000 }));
-		store.recordSession(makeSession({ beadId: "task-2", durationMs: 200_000 }));
+		store.recordSession(makeSession({ taskId: "task-1", durationMs: 100_000 }));
+		store.recordSession(makeSession({ taskId: "task-2", durationMs: 200_000 }));
 
 		const summary = generateSummary(store);
 		const formatted = formatSummary(summary);
@@ -254,8 +254,8 @@ describe("formatSummary", () => {
 	});
 
 	test("shows capability breakdown", () => {
-		store.recordSession(makeSession({ beadId: "task-1", capability: "builder" }));
-		store.recordSession(makeSession({ beadId: "task-2", capability: "scout" }));
+		store.recordSession(makeSession({ taskId: "task-1", capability: "builder" }));
+		store.recordSession(makeSession({ taskId: "task-2", capability: "scout" }));
 
 		const summary = generateSummary(store);
 		const formatted = formatSummary(summary);
@@ -268,14 +268,14 @@ describe("formatSummary", () => {
 	test("shows recent sessions with status (done vs running)", () => {
 		store.recordSession(
 			makeSession({
-				beadId: "task-1",
+				taskId: "task-1",
 				agentName: "agent-done",
 				completedAt: "2026-01-01T00:05:00Z",
 			}),
 		);
 		store.recordSession(
 			makeSession({
-				beadId: "task-2",
+				taskId: "task-2",
 				agentName: "agent-running",
 				completedAt: null,
 			}),
@@ -293,7 +293,7 @@ describe("formatSummary", () => {
 	});
 
 	test("formatDuration: <1000ms shows ms", () => {
-		store.recordSession(makeSession({ beadId: "task-1", durationMs: 500 }));
+		store.recordSession(makeSession({ taskId: "task-1", durationMs: 500 }));
 
 		const summary = generateSummary(store);
 		const formatted = formatSummary(summary);
@@ -302,7 +302,7 @@ describe("formatSummary", () => {
 	});
 
 	test("formatDuration: <60000ms shows seconds", () => {
-		store.recordSession(makeSession({ beadId: "task-1", durationMs: 5_500 }));
+		store.recordSession(makeSession({ taskId: "task-1", durationMs: 5_500 }));
 
 		const summary = generateSummary(store);
 		const formatted = formatSummary(summary);
@@ -311,7 +311,7 @@ describe("formatSummary", () => {
 	});
 
 	test("formatDuration: >=60000ms shows minutes+seconds", () => {
-		store.recordSession(makeSession({ beadId: "task-1", durationMs: 125_000 }));
+		store.recordSession(makeSession({ taskId: "task-1", durationMs: 125_000 }));
 
 		const summary = generateSummary(store);
 		const formatted = formatSummary(summary);
@@ -322,7 +322,7 @@ describe("formatSummary", () => {
 	test("shows token usage section when sessions have token data", () => {
 		store.recordSession(
 			makeSession({
-				beadId: "task-1",
+				taskId: "task-1",
 				inputTokens: 15_000,
 				outputTokens: 3_000,
 				cacheReadTokens: 100_000,
@@ -344,7 +344,7 @@ describe("formatSummary", () => {
 	});
 
 	test("hides token usage section when no token data exists", () => {
-		store.recordSession(makeSession({ beadId: "task-1" }));
+		store.recordSession(makeSession({ taskId: "task-1" }));
 
 		const summary = generateSummary(store);
 		const formatted = formatSummary(summary);
@@ -355,7 +355,7 @@ describe("formatSummary", () => {
 	test("shows per-session cost in recent sessions", () => {
 		store.recordSession(
 			makeSession({
-				beadId: "task-1",
+				taskId: "task-1",
 				agentName: "agent-costly",
 				inputTokens: 10_000,
 				outputTokens: 2_000,
@@ -373,7 +373,7 @@ describe("formatSummary", () => {
 	test("formats large token counts with M suffix", () => {
 		store.recordSession(
 			makeSession({
-				beadId: "task-1",
+				taskId: "task-1",
 				inputTokens: 2_500_000,
 				outputTokens: 500_000,
 				cacheReadTokens: 0,

package/src/mulch/client.test.ts

@@ -360,7 +360,7 @@ describe("createMulchClient", () => {
 			await addProc.exited;
 
 			const client = createMulchClient(tempDir);
-			// The flag is passed correctly, but may fail if the bead ID is invalid
+			// The flag is passed correctly, but may fail if the task ID is invalid
 			// or if other required fields are missing. This test documents that the
 			// flag is properly passed to the CLI.
 			try {

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.test.ts

@@ -39,7 +39,7 @@ function makeJsonSession(overrides: Record<string, unknown> = {}): Record<string
 		capability: "builder",
 		worktreePath: "/tmp/worktrees/test-agent",
 		branchName: "overstory/test-agent/task-1",
-		beadId: "task-1",
+		taskId: "task-1",
 		tmuxSession: "overstory-test-agent",
 		state: "working",
 		pid: 12345,
@@ -198,7 +198,7 @@ describe("data integrity", () => {
 			capability: "scout",
 			worktreePath: "/tmp/worktrees/full-agent",
 			branchName: "overstory/full-agent/task-42",
-			beadId: "task-42",
+			taskId: "task-42",
 			tmuxSession: "overstory-full-agent",
 			state: "stalled",
 			pid: 99999,
@@ -221,7 +221,7 @@ describe("data integrity", () => {
 		expect(result?.capability).toBe("scout");
 		expect(result?.worktreePath).toBe("/tmp/worktrees/full-agent");
 		expect(result?.branchName).toBe("overstory/full-agent/task-42");
-		expect(result?.beadId).toBe("task-42");
+		expect(result?.taskId).toBe("task-42");
 		expect(result?.tmuxSession).toBe("overstory-full-agent");
 		expect(result?.state).toBe("stalled");
 		expect(result?.pid).toBe(99999);

package/src/sessions/compat.ts

@@ -25,7 +25,7 @@ function normalizeSession(raw: Record<string, unknown>): AgentSession {
 		capability: raw.capability as string,
 		worktreePath: raw.worktreePath as string,
 		branchName: raw.branchName as string,
-		beadId: raw.beadId as string,
+		taskId: raw.taskId as string,
 		tmuxSession: raw.tmuxSession as string,
 		state: raw.state as AgentSession["state"],
 		pid: (raw.pid as number | null) ?? null,
@@ -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

@@ -35,7 +35,7 @@ function makeSession(overrides: Partial<AgentSession> = {}): AgentSession {
 		capability: "builder",
 		worktreePath: "/tmp/worktrees/test-agent",
 		branchName: "overstory/test-agent/task-1",
-		beadId: "task-1",
+		taskId: "task-1",
 		tmuxSession: "overstory-test-agent",
 		state: "booting",
 		pid: 12345,
@@ -81,7 +81,7 @@ describe("upsert", () => {
 			capability: "scout",
 			worktreePath: "/tmp/worktrees/roundtrip",
 			branchName: "overstory/roundtrip-agent/task-42",
-			beadId: "task-42",
+			taskId: "task-42",
 			tmuxSession: "overstory-roundtrip-agent",
 			state: "working",
 			pid: 99999,
@@ -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", () => {
@@ -510,11 +547,11 @@ describe("edge cases", () => {
 	});
 
 	test("empty string fields are stored correctly", () => {
-		const session = makeSession({ beadId: "", capability: "builder" });
+		const session = makeSession({ taskId: "", capability: "builder" });
 		store.upsert(session);
 
 		const result = store.getByName("test-agent");
-		expect(result?.beadId).toBe("");
+		expect(result?.taskId).toBe("");
 	});
 });
 

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. */
@@ -111,7 +113,7 @@ function rowToSession(row: SessionRow): AgentSession {
 		capability: row.capability,
 		worktreePath: row.worktree_path,
 		branchName: row.branch_name,
-		beadId: row.task_id,
+		taskId: row.task_id,
 		tmuxSession: row.tmux_session,
 		state: row.state as AgentState,
 		pid: row.pid,
@@ -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
 	`);
@@ -270,7 +276,7 @@ export function createSessionStore(dbPath: string): SessionStore {
 				$capability: session.capability,
 				$worktree_path: session.worktreePath,
 				$branch_name: session.branchName,
-				$task_id: session.beadId,
+				$task_id: session.taskId,
 				$tmux_session: session.tmuxSession,
 				$state: session.state,
 				$pid: session.pid,
@@ -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);