@os-eco/overstory-cli 0.6.1 → 0.6.5

package/src/logging/color.test.ts

@@ -5,138 +5,121 @@ import { dirname, join } from "node:path";
 const projectRoot = join(dirname(import.meta.dir), "..");
 
 describe("color module", () => {
-	// Test via subprocess to control env vars at import time
+	test("color.red is a function that wraps text", async () => {
+		const { color } = await import("./color.ts");
+		const result = color.red("hello");
+		expect(result).toContain("hello");
+		expect(typeof result).toBe("string");
+	});
 
-	test("colors enabled by default (no env vars)", async () => {
-		const proc = Bun.spawn(
-			[
-				"bun",
-				"-e",
-				'import { color, colorsEnabled } from "./src/logging/color.ts"; console.log(JSON.stringify({ colorsEnabled, reset: color.reset }))',
-			],
-			{
-				cwd: projectRoot,
-				stdout: "pipe",
-				stderr: "pipe",
-				env: { ...process.env, NO_COLOR: undefined, FORCE_COLOR: undefined, TERM: undefined },
-			},
-		);
-		await proc.exited;
-		const output = await new Response(proc.stdout).text();
-		const result = JSON.parse(output.trim());
-		expect(result.colorsEnabled).toBe(true);
-		expect(result.reset).toBe("\x1b[0m");
+	test("color functions all exist", async () => {
+		const { color } = await import("./color.ts");
+		const expectedKeys = [
+			"bold",
+			"dim",
+			"red",
+			"green",
+			"yellow",
+			"blue",
+			"magenta",
+			"cyan",
+			"white",
+			"gray",
+		];
+		for (const key of expectedKeys) {
+			expect(key in color).toBe(true);
+			expect(typeof (color as Record<string, unknown>)[key]).toBe("function");
+		}
 	});
 
-	test("NO_COLOR disables colors", async () => {
-		const proc = Bun.spawn(
-			[
-				"bun",
-				"-e",
-				'import { color, colorsEnabled } from "./src/logging/color.ts"; console.log(JSON.stringify({ colorsEnabled, reset: color.reset }))',
-			],
-			{
-				cwd: projectRoot,
-				stdout: "pipe",
-				stderr: "pipe",
-				env: { ...process.env, NO_COLOR: "1", FORCE_COLOR: undefined },
-			},
-		);
-		await proc.exited;
-		const output = await new Response(proc.stdout).text();
-		const result = JSON.parse(output.trim());
-		expect(result.colorsEnabled).toBe(false);
-		expect(result.reset).toBe("");
+	test("brand palette functions wrap text", async () => {
+		const { brand, accent, muted } = await import("./color.ts");
+		const result = brand("Overstory");
+		expect(result).toContain("Overstory");
+		expect(typeof accent("test")).toBe("string");
+		expect(typeof muted("test")).toBe("string");
 	});
 
-	test("TERM=dumb disables colors", async () => {
-		const proc = Bun.spawn(
-			[
-				"bun",
-				"-e",
-				'import { color, colorsEnabled } from "./src/logging/color.ts"; console.log(JSON.stringify({ colorsEnabled, reset: color.reset }))',
-			],
-			{
-				cwd: projectRoot,
-				stdout: "pipe",
-				stderr: "pipe",
-				env: { ...process.env, TERM: "dumb", NO_COLOR: undefined, FORCE_COLOR: undefined },
-			},
-		);
-		await proc.exited;
-		const output = await new Response(proc.stdout).text();
-		const result = JSON.parse(output.trim());
-		expect(result.colorsEnabled).toBe(false);
-		expect(result.reset).toBe("");
+	test("noColor is an identity function", async () => {
+		const { noColor } = await import("./color.ts");
+		expect(noColor("hello")).toBe("hello");
+		expect(noColor("")).toBe("");
 	});
 
-	test("FORCE_COLOR overrides NO_COLOR", async () => {
+	test("stripAnsi removes escape codes", async () => {
+		const { stripAnsi } = await import("./color.ts");
+		expect(stripAnsi("\x1b[31mhello\x1b[39m")).toBe("hello");
+		expect(stripAnsi("plain")).toBe("plain");
+		expect(stripAnsi("\x1b[1m\x1b[31mbold red\x1b[39m\x1b[22m")).toBe("bold red");
+	});
+
+	test("visibleLength excludes ANSI codes", async () => {
+		const { visibleLength } = await import("./color.ts");
+		expect(visibleLength("\x1b[31mhello\x1b[39m")).toBe(5);
+		expect(visibleLength("hello")).toBe(5);
+		expect(visibleLength("")).toBe(0);
+	});
+
+	test("setQuiet/isQuiet controls quiet mode", async () => {
+		const { isQuiet, setQuiet } = await import("./color.ts");
+		expect(isQuiet()).toBe(false);
+		setQuiet(true);
+		expect(isQuiet()).toBe(true);
+		setQuiet(false);
+		expect(isQuiet()).toBe(false);
+	});
+
+	test("NO_COLOR env causes chalk.level to be 0", async () => {
 		const proc = Bun.spawn(
 			[
 				"bun",
 				"-e",
-				'import { color, colorsEnabled } from "./src/logging/color.ts"; console.log(JSON.stringify({ colorsEnabled, reset: color.reset }))',
+				'import chalk from "chalk"; console.log(JSON.stringify({ level: chalk.level }))',
 			],
 			{
 				cwd: projectRoot,
 				stdout: "pipe",
 				stderr: "pipe",
-				env: { ...process.env, NO_COLOR: "1", FORCE_COLOR: "1" },
+				env: { ...process.env, NO_COLOR: "1", FORCE_COLOR: undefined },
 			},
 		);
 		await proc.exited;
 		const output = await new Response(proc.stdout).text();
 		const result = JSON.parse(output.trim());
-		expect(result.colorsEnabled).toBe(true);
-		expect(result.reset).toBe("\x1b[0m");
+		expect(result.level).toBe(0);
 	});
 
-	test("FORCE_COLOR=0 disables colors", async () => {
+	test("FORCE_COLOR overrides NO_COLOR", async () => {
 		const proc = Bun.spawn(
 			[
 				"bun",
 				"-e",
-				'import { color, colorsEnabled } from "./src/logging/color.ts"; console.log(JSON.stringify({ colorsEnabled, reset: color.reset }))',
+				'import chalk from "chalk"; console.log(JSON.stringify({ level: chalk.level }))',
 			],
 			{
 				cwd: projectRoot,
 				stdout: "pipe",
 				stderr: "pipe",
-				env: { ...process.env, FORCE_COLOR: "0", NO_COLOR: undefined },
+				env: { ...process.env, NO_COLOR: "1", FORCE_COLOR: "1" },
 			},
 		);
 		await proc.exited;
 		const output = await new Response(proc.stdout).text();
 		const result = JSON.parse(output.trim());
-		expect(result.colorsEnabled).toBe(false);
+		expect(result.level).toBeGreaterThan(0);
 	});
 
-	test("setQuiet/isQuiet controls quiet mode", async () => {
-		const { isQuiet, setQuiet } = await import("./color.ts");
-		expect(isQuiet()).toBe(false);
-		setQuiet(true);
-		expect(isQuiet()).toBe(true);
-		setQuiet(false);
-		expect(isQuiet()).toBe(false);
+	test("chalk re-export is available", async () => {
+		const { chalk } = await import("./color.ts");
+		expect(typeof chalk.red).toBe("function");
+		expect(chalk.red("test")).toContain("test");
 	});
 
-	test("all color keys present", async () => {
+	test("ColorFn type: color functions accept strings and return strings", async () => {
 		const { color } = await import("./color.ts");
-		const expectedKeys = [
-			"reset",
-			"bold",
-			"dim",
-			"red",
-			"green",
-			"yellow",
-			"blue",
-			"magenta",
-			"cyan",
-			"white",
-			"gray",
-		];
-		for (const key of expectedKeys) {
-			expect(key in color).toBe(true);
-		}
+		// Each color function should accept a string and return a string
+		const result = color.bold(color.red("nested"));
+		expect(result).toContain("nested");
+		expect(typeof result).toBe("string");
 	});
 });

package/src/logging/color.ts

@@ -1,63 +1,69 @@
 /**
- * Central ANSI color and output control.
+ * Central color and output control using Chalk.
  *
- * Respects the NO_COLOR convention (https://no-color.org/):
- * - When NO_COLOR env var is set (any value), all color codes become empty strings
- * - When TERM=dumb, colors are disabled
- * - When FORCE_COLOR is set to a truthy value, colors are forced on
- *
- * Also provides --quiet support: when quiet mode is enabled, non-error
- * output is suppressed. Commands check isQuiet() before writing to stdout.
+ * Chalk natively handles NO_COLOR, FORCE_COLOR, and TERM=dumb.
+ * See https://github.com/chalk/chalk#supportscolor for detection logic.
  */
 
-/**
- * Priority order for color detection:
- * 1. FORCE_COLOR (highest) — set to non-"0" to force colors on
- * 2. NO_COLOR — any value disables colors
- * 3. TERM=dumb — disables colors
- * 4. Default: colors enabled
- */
-function shouldUseColor(): boolean {
-	if (process.env.FORCE_COLOR !== undefined) {
-		return process.env.FORCE_COLOR !== "0";
-	}
-	if (process.env.NO_COLOR !== undefined) {
-		return false;
-	}
-	if (process.env.TERM === "dumb") {
-		return false;
-	}
-	return true;
-}
+import chalk from "chalk";
 
-const useColor = shouldUseColor();
+// --- Brand palette (os-eco brand colors) ---
 
-function code(ansiCode: string): string {
-	return useColor ? ansiCode : "";
-}
+/** Forest green — Overstory primary brand color. */
+export const brand = chalk.rgb(27, 94, 32);
+
+/** Amber — highlights, warnings. */
+export const accent = chalk.rgb(255, 183, 77);
+
+/** Stone gray — secondary text, muted content. */
+export const muted = chalk.rgb(120, 120, 110);
+
+// --- Standard color functions ---
 
 /**
- * ANSI color codes that respect NO_COLOR.
- * When colors are disabled, all values are empty strings.
+ * Color functions that wrap text with ANSI codes.
+ * Each value is a function: color.red("text") returns "\x1b[31mtext\x1b[39m".
+ * Chalk auto-resets when wrapping, so color.reset is not needed.
  */
 export const color = {
-	reset: code("\x1b[0m"),
-	bold: code("\x1b[1m"),
-	dim: code("\x1b[2m"),
-	red: code("\x1b[31m"),
-	green: code("\x1b[32m"),
-	yellow: code("\x1b[33m"),
-	blue: code("\x1b[34m"),
-	magenta: code("\x1b[35m"),
-	cyan: code("\x1b[36m"),
-	white: code("\x1b[37m"),
-	gray: code("\x1b[90m"),
+	bold: chalk.bold,
+	dim: chalk.dim,
+	red: chalk.red,
+	green: chalk.green,
+	yellow: chalk.yellow,
+	blue: chalk.blue,
+	magenta: chalk.magenta,
+	cyan: chalk.cyan,
+	white: chalk.white,
+	gray: chalk.gray,
 } as const;
 
-/** Whether ANSI colors are currently enabled. */
-export const colorsEnabled = useColor;
+// Re-export chalk for direct use (chaining, custom RGB, etc.)
+export { chalk };
+
+/** Type for color function values (for consumers that store colors in variables). */
+export type ColorFn = (text: string) => string;
+
+/** Identity function for "no color" cases (replaces old color.white as default). */
+export const noColor: ColorFn = (text: string) => text;
+
+// --- ANSI strip utilities (for visible-width calculations in dashboard) ---
+
+// biome-ignore lint/suspicious/noControlCharactersInRegex: ESC (0x1B) is required to match ANSI escape sequences
+const ANSI_REGEX = /\x1b\[[0-9;]*m/g;
+
+/** Strip ANSI escape codes from a string. */
+export function stripAnsi(str: string): string {
+	return str.replace(ANSI_REGEX, "");
+}
+
+/** Visible string length (excluding ANSI escape codes). */
+export function visibleLength(str: string): number {
+	return stripAnsi(str).length;
+}
 
 // --- Quiet mode ---
+
 let quietMode = false;
 
 /** Enable quiet mode (suppress non-error output). */

package/src/logging/reporter.test.ts

@@ -106,12 +106,12 @@ describe("formatLogLine", () => {
 		expect(result).toContain("[invalid-timestamp]");
 	});
 
-	test("contains ANSI escape codes in output", () => {
+	test("output is a formatted string with level label and timestamp", () => {
 		const result = formatLogLine(makeEvent());
-		// \x1b[ is the ANSI escape sequence prefix
-		expect(result).toContain("\x1b[");
-		// Reset sequence should appear at least once
-		expect(result).toContain("\x1b[0m");
+		// Chalk adds ANSI codes in TTY environments; in non-TTY (CI/tests) output is plain.
+		// Verify the result contains the expected label and timestamp regardless of color mode.
+		expect(result).toContain("INF");
+		expect(result).toContain("[14:30:00]");
 	});
 
 	test("uses different ANSI color codes for different levels", () => {
@@ -120,11 +120,11 @@ describe("formatLogLine", () => {
 		const warnResult = formatLogLine(makeEvent({ level: "warn" }));
 		const errorResult = formatLogLine(makeEvent({ level: "error" }));
 
-		// Each level uses a distinct color: gray(90), blue(34), yellow(33), red(31)
-		expect(debugResult).toContain("\x1b[90m");
-		expect(infoResult).toContain("\x1b[34m");
-		expect(warnResult).toContain("\x1b[33m");
-		expect(errorResult).toContain("\x1b[31m");
+		// Each level produces distinct output (Chalk's exact escape codes may vary by terminal)
+		expect(debugResult).not.toBe(infoResult);
+		expect(infoResult).not.toBe(warnResult);
+		expect(warnResult).not.toBe(errorResult);
+		expect(debugResult).not.toBe(errorResult);
 	});
 
 	test("formats boolean data values via String()", () => {

package/src/logging/reporter.ts

@@ -2,13 +2,14 @@
  * Console reporter with ANSI colors for human-readable log output.
  *
  * Formats LogEvent objects into colored terminal output.
- * Uses ANSI escape codes directly (no external dependencies).
+ * Uses Chalk for color formatting.
  */
 
 import type { LogEvent } from "../types.ts";
+import type { ColorFn } from "./color.ts";
 import { color, isQuiet } from "./color.ts";
 
-const LEVEL_COLORS: Record<LogEvent["level"], string> = {
+const LEVEL_COLORS: Record<LogEvent["level"], ColorFn> = {
 	debug: color.gray,
 	info: color.blue,
 	warn: color.yellow,
@@ -35,13 +36,13 @@ export function formatLogLine(event: LogEvent): string {
 	const time = extractTime(event.timestamp);
 
 	// Build the agent prefix
-	const agentPart = event.agentName ? `${color.dim}${event.agentName}${color.reset} | ` : "";
+	const agentPart = event.agentName ? `${color.dim(event.agentName)} | ` : "";
 
 	// Build key=value pairs from data
 	const dataPart = formatData(event.data);
-	const dataSuffix = dataPart.length > 0 ? ` ${color.dim}${dataPart}${color.reset}` : "";
+	const dataSuffix = dataPart.length > 0 ? ` ${color.dim(dataPart)}` : "";
 
-	return `${color.dim}[${time}]${color.reset} ${levelColor}${color.bold}${label}${color.reset} ${agentPart}${event.event}${dataSuffix}`;
+	return `${color.dim(`[${time}]`)} ${levelColor(color.bold(label))} ${agentPart}${event.event}${dataSuffix}`;
 }
 
 /**

package/src/mail/broadcast.test.ts

@@ -30,7 +30,7 @@ describe("resolveGroupAddress", () => {
 			capability,
 			worktreePath: `/worktrees/${agentName}`,
 			branchName: `branch-${agentName}`,
-			beadId: "bead-001",
+			taskId: "bead-001",
 			tmuxSession: `overstory-test-${agentName}`,
 			state: "working",
 			pid: 12345,

package/src/mail/client.test.ts

@@ -598,7 +598,7 @@ describe("createMailClient", () => {
 	describe("sendProtocol", () => {
 		test("sends a worker_done message with serialized payload", () => {
 			const payload: WorkerDonePayload = {
-				beadId: "beads-abc",
+				taskId: "beads-abc",
 				branch: "agent/builder-1",
 				exitCode: 0,
 				filesModified: ["src/foo.ts", "src/bar.ts"],
@@ -625,7 +625,7 @@ describe("createMailClient", () => {
 				subject: "Merged",
 				body: "Branch merged",
 				type: "merged",
-				payload: { branch: "agent/b1", beadId: "beads-xyz", tier: "clean-merge" as const },
+				payload: { branch: "agent/b1", taskId: "beads-xyz", tier: "clean-merge" as const },
 			});
 
 			const msg = store.getById(id);
@@ -640,7 +640,7 @@ describe("createMailClient", () => {
 				body: "Build failing",
 				type: "escalation",
 				priority: "urgent",
-				payload: { severity: "critical" as const, beadId: null, context: "OOM" },
+				payload: { severity: "critical" as const, taskId: null, context: "OOM" },
 			});
 
 			const msg = store.getById(id);
@@ -656,7 +656,7 @@ describe("createMailClient", () => {
 				type: "assign",
 				threadId: "thread-dispatch-1",
 				payload: {
-					beadId: "beads-123",
+					taskId: "beads-123",
 					specPath: ".overstory/specs/beads-123.md",
 					workerName: "builder-1",
 					branch: "agent/builder-1",
@@ -671,7 +671,7 @@ describe("createMailClient", () => {
 	describe("parsePayload", () => {
 		test("parses a valid JSON payload", () => {
 			const payload: WorkerDonePayload = {
-				beadId: "beads-abc",
+				taskId: "beads-abc",
 				branch: "agent/builder-1",
 				exitCode: 0,
 				filesModified: ["src/foo.ts"],
@@ -727,7 +727,7 @@ describe("createMailClient", () => {
 	describe("checkInject with protocol messages", () => {
 		test("includes payload in injection output for protocol messages", () => {
 			const payload: WorkerDonePayload = {
-				beadId: "beads-abc",
+				taskId: "beads-abc",
 				branch: "agent/builder-1",
 				exitCode: 0,
 				filesModified: ["src/foo.ts"],

package/src/mail/store.test.ts

@@ -638,7 +638,7 @@ describe("createMailStore", () => {
 
 		test("stores JSON payload string", () => {
 			const payload = JSON.stringify({
-				beadId: "beads-abc",
+				taskId: "beads-abc",
 				branch: "agent/builder-1",
 				exitCode: 0,
 				filesModified: ["src/foo.ts"],
@@ -661,7 +661,7 @@ describe("createMailStore", () => {
 		});
 
 		test("returns payload in getUnread results", () => {
-			const payload = JSON.stringify({ severity: "critical", beadId: null, context: "OOM" });
+			const payload = JSON.stringify({ severity: "critical", taskId: null, context: "OOM" });
 			store.insert({
 				id: "msg-escalation",
 				from: "builder-1",
@@ -682,7 +682,7 @@ describe("createMailStore", () => {
 		test("returns payload in getAll results", () => {
 			const payload = JSON.stringify({
 				branch: "agent/b1",
-				beadId: "beads-xyz",
+				taskId: "beads-xyz",
 				tier: "clean-merge",
 			});
 			store.insert({

package/src/merge/queue.test.ts

@@ -1,3 +1,4 @@
+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";
@@ -22,14 +23,14 @@ describe("createMergeQueue", () => {
 	function makeInput(
 		overrides?: Partial<{
 			branchName: string;
-			beadId: string;
+			taskId: string;
 			agentName: string;
 			filesModified: string[];
 		}>,
 	) {
 		return {
 			branchName: overrides?.branchName ?? "overstory/test-agent/bead-123",
-			beadId: overrides?.beadId ?? "bead-123",
+			taskId: overrides?.taskId ?? "bead-123",
 			agentName: overrides?.agentName ?? "test-agent",
 			filesModified: overrides?.filesModified ?? ["src/test.ts"],
 		};
@@ -51,7 +52,7 @@ describe("createMergeQueue", () => {
 			const after = new Date().toISOString();
 
 			expect(entry.branchName).toBe("overstory/test-agent/bead-123");
-			expect(entry.beadId).toBe("bead-123");
+			expect(entry.taskId).toBe("bead-123");
 			expect(entry.agentName).toBe("test-agent");
 			expect(entry.filesModified).toEqual(["src/test.ts"]);
 			expect(entry.enqueuedAt).toBeDefined();
@@ -64,7 +65,7 @@ describe("createMergeQueue", () => {
 			const queue = createMergeQueue(queuePath);
 			const input = makeInput({
 				branchName: "overstory/builder-1/bead-xyz",
-				beadId: "bead-xyz",
+				taskId: "bead-xyz",
 				agentName: "builder-1",
 				filesModified: ["src/a.ts", "src/b.ts"],
 			});
@@ -72,7 +73,7 @@ describe("createMergeQueue", () => {
 			const entry = queue.enqueue(input);
 
 			expect(entry.branchName).toBe("overstory/builder-1/bead-xyz");
-			expect(entry.beadId).toBe("bead-xyz");
+			expect(entry.taskId).toBe("bead-xyz");
 			expect(entry.agentName).toBe("builder-1");
 			expect(entry.filesModified).toEqual(["src/a.ts", "src/b.ts"]);
 		});
@@ -81,8 +82,8 @@ describe("createMergeQueue", () => {
 	describe("dequeue", () => {
 		test("returns first pending entry (FIFO)", () => {
 			const queue = createMergeQueue(queuePath);
-			queue.enqueue(makeInput({ branchName: "branch-a", beadId: "bead-a" }));
-			queue.enqueue(makeInput({ branchName: "branch-b", beadId: "bead-b" }));
+			queue.enqueue(makeInput({ branchName: "branch-a", taskId: "bead-a" }));
+			queue.enqueue(makeInput({ branchName: "branch-b", taskId: "bead-b" }));
 
 			const dequeued = queue.dequeue();
 
@@ -333,6 +334,71 @@ describe("createMergeQueue", () => {
 		});
 	});
 
+	describe("bead_id → task_id migration", () => {
+		test("renames bead_id column to task_id on existing databases", () => {
+			// Create a database with the old bead_id schema
+			const db = new Database(queuePath);
+			db.exec("PRAGMA journal_mode = WAL");
+			db.exec(`
+				CREATE TABLE merge_queue (
+					id INTEGER PRIMARY KEY AUTOINCREMENT,
+					branch_name TEXT NOT NULL,
+					bead_id TEXT NOT NULL,
+					agent_name TEXT NOT NULL,
+					files_modified TEXT NOT NULL DEFAULT '[]',
+					enqueued_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f','now')),
+					status TEXT NOT NULL DEFAULT 'pending'
+						CHECK(status IN ('pending','merging','merged','conflict','failed')),
+					resolved_tier TEXT
+						CHECK(resolved_tier IS NULL OR resolved_tier IN ('clean-merge','auto-resolve','ai-resolve','reimagine'))
+				)
+			`);
+			db.exec(
+				"INSERT INTO merge_queue (branch_name, bead_id, agent_name, files_modified, status, enqueued_at) VALUES ('overstory/test/bead-1', 'bead-1', 'test', '[\"src/a.ts\"]', 'pending', '2026-01-01T00:00:00.000')",
+			);
+			db.close();
+
+			// Opening with createMergeQueue should migrate and work
+			const queue = createMergeQueue(queuePath);
+			const entries = queue.list();
+
+			expect(entries).toHaveLength(1);
+			expect(entries[0]?.taskId).toBe("bead-1");
+			expect(entries[0]?.branchName).toBe("overstory/test/bead-1");
+
+			// New inserts should also work
+			const newEntry = queue.enqueue({
+				branchName: "overstory/test/bead-2",
+				taskId: "bead-2",
+				agentName: "test",
+				filesModified: ["src/b.ts"],
+			});
+			expect(newEntry.taskId).toBe("bead-2");
+
+			queue.close();
+		});
+
+		test("no-op when task_id column already exists", () => {
+			// Create with current schema (has task_id)
+			const queue1 = createMergeQueue(queuePath);
+			queue1.enqueue({
+				branchName: "overstory/test/bead-1",
+				taskId: "bead-1",
+				agentName: "test",
+				filesModified: [],
+			});
+			queue1.close();
+
+			// Re-opening should not error
+			const queue2 = createMergeQueue(queuePath);
+			const entries = queue2.list();
+
+			expect(entries).toHaveLength(1);
+			expect(entries[0]?.taskId).toBe("bead-1");
+			queue2.close();
+		});
+	});
+
 	describe("close", () => {
 		test("closes the database connection", () => {
 			const queue = createMergeQueue(queuePath);

package/src/merge/queue.ts

@@ -74,7 +74,7 @@ function rowToEntry(row: MergeQueueRow): MergeEntry {
 
 	return {
 		branchName: row.branch_name,
-		beadId: row.task_id,
+		taskId: row.task_id,
 		agentName: row.agent_name,
 		filesModified,
 		enqueuedAt: row.enqueued_at,
@@ -83,6 +83,18 @@ function rowToEntry(row: MergeQueueRow): MergeEntry {
 	};
 }
 
+/**
+ * Migrate an existing merge_queue table from bead_id to task_id column.
+ * Safe to call multiple times — only renames if bead_id exists and task_id does not.
+ */
+function migrateBeadIdToTaskId(db: Database): void {
+	const rows = db.prepare("PRAGMA table_info(merge_queue)").all() as Array<{ name: string }>;
+	const existingColumns = new Set(rows.map((r) => r.name));
+	if (existingColumns.has("bead_id") && !existingColumns.has("task_id")) {
+		db.exec("ALTER TABLE merge_queue RENAME COLUMN bead_id TO task_id");
+	}
+}
+
 /**
  * Create a new MergeQueue backed by a SQLite database at the given path.
  *
@@ -101,6 +113,9 @@ export function createMergeQueue(dbPath: string): MergeQueue {
 	db.exec(CREATE_TABLE);
 	db.exec(CREATE_INDEXES);
 
+	// Migrate: rename bead_id → task_id on existing tables
+	migrateBeadIdToTaskId(db);
+
 	// Prepare statements for frequent operations
 	const insertStmt = db.prepare<
 		MergeQueueRow,
@@ -157,7 +172,7 @@ export function createMergeQueue(dbPath: string): MergeQueue {
 
 			const row = insertStmt.get({
 				$branch_name: input.branchName,
-				$task_id: input.beadId,
+				$task_id: input.taskId,
 				$agent_name: input.agentName,
 				$files_modified: filesModifiedJson,
 				$enqueued_at: enqueuedAt,