@os-eco/overstory-cli 0.7.2 → 0.7.4

package/src/runtimes/pi-guards.ts

@@ -8,7 +8,7 @@
 // to prevent tool execution — equivalent to Claude Code's PreToolUse hooks.
 //
 // Activity tracking fires via pi.exec("ov log ...") on tool_call,
-// tool_execution_end, and session_shutdown events so the SessionStore
+// tool_execution_end, agent_end, and session_shutdown events so the SessionStore
 // lastActivity stays fresh and the watchdog does not zombie-classify agents.
 
 import {
@@ -113,7 +113,11 @@ function toRegExpArrayLiteral(patterns: string[]): string {
  * Activity tracking:
  * - tool_call handler: fire-and-forget "ov log tool-start" to update lastActivity.
  * - tool_execution_end handler: fire-and-forget "ov log tool-end".
- * - session_shutdown handler: awaited "ov log session-end" to mark agent completed.
+ * - agent_end handler: awaited "ov log session-end" — fires when the agentic loop
+ *   completes (task done). Without this, completed Pi agents get watchdog-escalated
+ *   through stalled → nudge → triage → terminate.
+ * - session_shutdown handler: awaited "ov log session-end" — fires on Ctrl+C/SIGTERM.
+ *   Kept as a safety net in case agent_end does not fire (e.g., crash, force-kill).
  *
  * These tracking calls prevent the watchdog from zombie-classifying Pi agents due
  * to stale lastActivity timestamps (the root cause of the zombie state bug).
@@ -190,7 +194,7 @@ export function generatePiGuardExtension(hooks: HooksDef): string {
 		`//`,
 		`// Uses Pi's ExtensionAPI factory style: export default function(pi: ExtensionAPI) { ... }`,
 		`// pi.on("tool_call", ...) returns { block: true, reason } to prevent tool execution.`,
-		`// pi.exec("ov", [...]) calls the overstory CLI for activity tracking.`,
+		`// pi.exec("ov", [...]) calls the overstory CLI for activity tracking and lifecycle.`,
 		`import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";`,
 		``,
 		`const AGENT_NAME = "${agentName}";`,
@@ -241,7 +245,7 @@ export function generatePiGuardExtension(hooks: HooksDef): string {
 		`\tpi.on("tool_call", async (event) => {`,
 		`\t\t// Activity tracking: update lastActivity so watchdog knows agent is alive.`,
 		`\t\t// Fire-and-forget — do not await (avoids latency on every tool call).`,
-		`\t\tpi.exec("ov", ["log", "tool-start", "--agent", AGENT_NAME]).catch(() => {});`,
+		`\t\tpi.exec("ov", ["log", "tool-start", "--agent", AGENT_NAME, "--tool-name", event.toolName]).catch(() => {});`,
 		``,
 		`\t\t// 1. Block native team/task tools (all agents).`,
 		`\t\tif (TEAM_BLOCKED.has(event.toolName)) {`,
@@ -326,15 +330,28 @@ export function generatePiGuardExtension(hooks: HooksDef): string {
 		`\t * Tool execution end: fire-and-forget "ov log tool-end" for event tracking.`,
 		`\t * Paired with tool_call's tool-start fire for proper begin/end event logging.`,
 		`\t */`,
-		`\tpi.on("tool_execution_end", async (_event) => {`,
-		`\t\tpi.exec("ov", ["log", "tool-end", "--agent", AGENT_NAME]).catch(() => {});`,
+		`\tpi.on("tool_execution_end", async (event) => {`,
+		`\t\tpi.exec("ov", ["log", "tool-end", "--agent", AGENT_NAME, "--tool-name", event.toolName]).catch(() => {});`,
 		`\t});`,
 		``,
 		`\t/**`,
-		`\t * Session shutdown: log session-end so the agent transitions to "completed" state.`,
+		`\t * Agent end: log session-end when the agentic loop completes (task done).`,
 		`\t *`,
-		`\t * Awaited so it completes before Pi exits. Without this call, the agent stays in`,
-		`\t * "booting" or "working" state forever, requiring manual cleanup or watchdog termination.`,
+		`\t * Awaited so it completes before Pi moves on. Without this handler, completed`,
+		`\t * Pi agents never transition to "completed" state in the SessionStore, causing`,
+		`\t * the watchdog to escalate them through stalled → nudge → triage → terminate.`,
+		`\t *`,
+		`\t * Fires when the agent finishes its work — before session_shutdown.`,
+		`\t */`,
+		`\tpi.on("agent_end", async (_event) => {`,
+		`\t\tawait pi.exec("ov", ["log", "session-end", "--agent", AGENT_NAME]).catch(() => {});`,
+		`\t});`,
+		``,
+		`\t/**`,
+		`\t * Session shutdown: safety-net session-end log for non-graceful exits.`,
+		`\t *`,
+		`\t * Awaited so it completes before Pi exits. Kept as a fallback in case`,
+		`\t * agent_end does not fire (e.g., crash, force-kill, Ctrl+C before task completes).`,
 		`\t *`,
 		`\t * Fires on Ctrl+C, Ctrl+D, or SIGTERM.`,
 		`\t */`,

package/src/schema-consistency.test.ts

@@ -12,7 +12,7 @@
 
 import { Database } from "bun:sqlite";
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdtemp } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { createEventStore } from "./events/store.ts";
@@ -21,6 +21,8 @@ import { createMergeQueue } from "./merge/queue.ts";
 import { createMetricsStore } from "./metrics/store.ts";
 import { createSessionStore } from "./sessions/store.ts";
 
+import { cleanupTempDir } from "./test-helpers.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 }>;
@@ -35,7 +37,7 @@ describe("SQL schema consistency", () => {
 	});
 
 	afterEach(async () => {
-		await rm(tmpDir, { recursive: true, force: true });
+		await cleanupTempDir(tmpDir);
 	});
 
 	describe("SessionStore", () => {

package/src/sessions/compat.test.ts

@@ -6,9 +6,10 @@
  */
 
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { mkdtemp, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { cleanupTempDir } from "../test-helpers.ts";
 import { openSessionStore } from "./compat.ts";
 
 let tempDir: string;
@@ -22,7 +23,7 @@ beforeEach(async () => {
 });
 
 afterEach(async () => {
-	await rm(tempDir, { recursive: true, force: true });
+	await cleanupTempDir(tempDir);
 });
 
 /** Create a sessions.json with the given entries. */

package/src/sessions/store.test.ts

@@ -6,9 +6,10 @@
  */
 
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdtemp } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { cleanupTempDir } from "../test-helpers.ts";
 import type { AgentSession, AgentState, InsertRun, Run, RunStore } from "../types.ts";
 import { createRunStore, createSessionStore, type SessionStore } from "./store.ts";
 
@@ -24,7 +25,7 @@ beforeEach(async () => {
 
 afterEach(async () => {
 	store.close();
-	await rm(tempDir, { recursive: true, force: true });
+	await cleanupTempDir(tempDir);
 });
 
 /** Helper to create an AgentSession with optional overrides. */

package/src/test-helpers.ts

@@ -95,9 +95,28 @@ export async function getDefaultBranch(repoDir: string): Promise<string> {
 
 /**
  * Remove a temp directory. Safe to call even if the directory doesn't exist.
+ *
+ * On Windows, SQLite WAL/SHM file handles may linger briefly after db.close(),
+ * causing EBUSY errors on immediate rm(). Retries with exponential backoff
+ * (up to ~1.5s total) to handle this OS-level timing issue.
  */
 export async function cleanupTempDir(dir: string): Promise<void> {
-	await rm(dir, { recursive: true, force: true });
+	const maxRetries = process.platform === "win32" ? 5 : 0;
+	for (let attempt = 0; attempt <= maxRetries; attempt++) {
+		try {
+			await rm(dir, { recursive: true, force: true });
+			return;
+		} catch (err: unknown) {
+			const code = (err as NodeJS.ErrnoException).code;
+			if (code === "EBUSY" && attempt < maxRetries) {
+				// Exponential backoff: 50, 100, 200, 400, 800ms
+				await Bun.sleep(50 * 2 ** attempt);
+				continue;
+			}
+			// Non-EBUSY or final attempt: swallow (temp dirs are cleaned by OS anyway)
+			if (code !== "ENOENT") return;
+		}
+	}
 }
 
 /**

package/src/tracker/beads.test.ts

@@ -0,0 +1,454 @@
+/**
+ * Beads tracker adapter tests.
+ *
+ * Uses Bun.spawn mocks — legitimate exception to "never mock what you can use for real".
+ * The `bd` CLI may not be installed in all environments and would modify real tracker
+ * state (creating/closing actual beads) if invoked directly in tests.
+ */
+
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { AgentError } from "../errors.ts";
+import { createBeadsTracker } from "./beads.ts";
+
+/**
+ * Helper to create a mock Bun.spawn return value.
+ *
+ * The actual code reads stdout/stderr via `new Response(proc.stdout).text()`
+ * and `new Response(proc.stderr).text()`, so we need ReadableStreams.
+ */
+function mockSpawnResult(
+	stdout: string,
+	stderr: string,
+	exitCode: number,
+): {
+	stdout: ReadableStream<Uint8Array>;
+	stderr: ReadableStream<Uint8Array>;
+	exited: Promise<number>;
+	pid: number;
+} {
+	return {
+		stdout: new Response(stdout).body as ReadableStream<Uint8Array>,
+		stderr: new Response(stderr).body as ReadableStream<Uint8Array>,
+		exited: Promise.resolve(exitCode),
+		pid: 12345,
+	};
+}
+
+const TEST_CWD = "/test/repo";
+
+describe("createBeadsTracker — ready()", () => {
+	let spawnSpy: ReturnType<typeof spyOn>;
+
+	beforeEach(() => {
+		spawnSpy = spyOn(Bun, "spawn");
+	});
+
+	afterEach(() => {
+		spawnSpy.mockRestore();
+	});
+
+	test("returns normalized TrackerIssue[] with issue_type → type mapping", async () => {
+		const raw = [
+			{
+				id: "bd-1",
+				title: "Fix login",
+				status: "open",
+				priority: 1,
+				issue_type: "bug",
+			},
+			{
+				id: "bd-2",
+				title: "Add auth",
+				status: "open",
+				priority: 2,
+				issue_type: "feature",
+				assignee: "bob",
+			},
+		];
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify(raw), "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		const issues = await tracker.ready();
+
+		expect(issues).toHaveLength(2);
+		expect(issues[0]).toMatchObject({ id: "bd-1", title: "Fix login", type: "bug" });
+		expect(issues[1]).toMatchObject({ id: "bd-2", type: "feature", assignee: "bob" });
+	});
+
+	test("verifies CLI args: [bd, ready, --json]", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("[]", "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		await tracker.ready();
+
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const cmd = callArgs[0] as string[];
+		expect(cmd).toEqual(["bd", "ready", "--json"]);
+	});
+
+	test("throws AgentError on non-zero exit code", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("", "bd: command not found", 1));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		await expect(tracker.ready()).rejects.toThrow(AgentError);
+	});
+});
+
+describe("createBeadsTracker — show()", () => {
+	let spawnSpy: ReturnType<typeof spyOn>;
+
+	beforeEach(() => {
+		spawnSpy = spyOn(Bun, "spawn");
+	});
+
+	afterEach(() => {
+		spawnSpy.mockRestore();
+	});
+
+	test("returns normalized TrackerIssue from bd array response", async () => {
+		// bd show --json returns an array with a single element
+		const raw = [
+			{
+				id: "bd-42",
+				title: "Critical bug",
+				status: "open",
+				priority: 1,
+				issue_type: "bug",
+				description: "Crashes on startup",
+				blocks: ["bd-50"],
+			},
+		];
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify(raw), "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		const issue = await tracker.show("bd-42");
+
+		expect(issue).toMatchObject({
+			id: "bd-42",
+			title: "Critical bug",
+			type: "bug",
+			description: "Crashes on startup",
+			blocks: ["bd-50"],
+		});
+	});
+
+	test("throws AgentError when bd returns empty array", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("[]", "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		await expect(tracker.show("bd-99")).rejects.toThrow(AgentError);
+	});
+
+	test("verifies CLI args: [bd, show, <id>, --json]", async () => {
+		const raw = [{ id: "bd-1", title: "t", status: "open", priority: 1, issue_type: "task" }];
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify(raw), "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		await tracker.show("bd-1");
+
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const cmd = callArgs[0] as string[];
+		expect(cmd).toEqual(["bd", "show", "bd-1", "--json"]);
+	});
+});
+
+describe("createBeadsTracker — create()", () => {
+	let spawnSpy: ReturnType<typeof spyOn>;
+
+	beforeEach(() => {
+		spawnSpy = spyOn(Bun, "spawn");
+	});
+
+	afterEach(() => {
+		spawnSpy.mockRestore();
+	});
+
+	test("returns new issue ID from { id: '...' } response", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify({ id: "bd-101" }), "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		const id = await tracker.create("New feature");
+
+		expect(id).toBe("bd-101");
+	});
+
+	test("verifies CLI args: [bd, create, <title>, --json]", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify({ id: "bd-1" }), "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		await tracker.create("My Issue");
+
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const cmd = callArgs[0] as string[];
+		expect(cmd[0]).toBe("bd");
+		expect(cmd[1]).toBe("create");
+		expect(cmd[2]).toBe("My Issue");
+		expect(cmd).toContain("--json");
+	});
+
+	test("passes optional --type, --priority, --description args", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify({ id: "bd-200" }), "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		await tracker.create("My task", {
+			type: "feature",
+			priority: 2,
+			description: "A detailed description",
+		});
+
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const cmd = callArgs[0] as string[];
+		expect(cmd).toContain("--type");
+		expect(cmd).toContain("feature");
+		expect(cmd).toContain("--priority");
+		expect(cmd).toContain("2");
+		expect(cmd).toContain("--description");
+		expect(cmd).toContain("A detailed description");
+	});
+});
+
+describe("createBeadsTracker — claim()", () => {
+	let spawnSpy: ReturnType<typeof spyOn>;
+
+	beforeEach(() => {
+		spawnSpy = spyOn(Bun, "spawn");
+	});
+
+	afterEach(() => {
+		spawnSpy.mockRestore();
+	});
+
+	test("calls [bd, update, <id>, --status, in_progress]", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("", "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		await tracker.claim("bd-7");
+
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const cmd = callArgs[0] as string[];
+		expect(cmd).toEqual(["bd", "update", "bd-7", "--status", "in_progress"]);
+	});
+});
+
+describe("createBeadsTracker — close()", () => {
+	let spawnSpy: ReturnType<typeof spyOn>;
+
+	beforeEach(() => {
+		spawnSpy = spyOn(Bun, "spawn");
+	});
+
+	afterEach(() => {
+		spawnSpy.mockRestore();
+	});
+
+	test("calls [bd, close, <id>] without reason", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("", "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		await tracker.close("bd-10");
+
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const cmd = callArgs[0] as string[];
+		expect(cmd).toEqual(["bd", "close", "bd-10"]);
+	});
+
+	test("calls [bd, close, <id>, --reason, ...] with reason", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("", "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		await tracker.close("bd-10", "Completed implementation");
+
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const cmd = callArgs[0] as string[];
+		expect(cmd).toEqual(["bd", "close", "bd-10", "--reason", "Completed implementation"]);
+	});
+});
+
+describe("createBeadsTracker — list()", () => {
+	let spawnSpy: ReturnType<typeof spyOn>;
+
+	beforeEach(() => {
+		spawnSpy = spyOn(Bun, "spawn");
+	});
+
+	afterEach(() => {
+		spawnSpy.mockRestore();
+	});
+
+	test("returns normalized issues from bd array response", async () => {
+		const raw = [
+			{ id: "bd-1", title: "Task A", status: "open", priority: 1, issue_type: "task" },
+			{
+				id: "bd-2",
+				title: "Bug B",
+				status: "in_progress",
+				priority: 2,
+				issue_type: "bug",
+			},
+		];
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify(raw), "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		const issues = await tracker.list();
+
+		expect(issues).toHaveLength(2);
+		expect(issues[0]).toMatchObject({ id: "bd-1", type: "task" });
+		expect(issues[1]).toMatchObject({ id: "bd-2", type: "bug", status: "in_progress" });
+	});
+
+	test("verifies CLI args: [bd, list, --json]", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("[]", "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		await tracker.list();
+
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const cmd = callArgs[0] as string[];
+		expect(cmd[0]).toBe("bd");
+		expect(cmd[1]).toBe("list");
+		expect(cmd).toContain("--json");
+	});
+
+	test("passes --status and --limit options", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("[]", "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		await tracker.list({ status: "open", limit: 5 });
+
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const cmd = callArgs[0] as string[];
+		expect(cmd).toContain("--status");
+		expect(cmd).toContain("open");
+		expect(cmd).toContain("--limit");
+		expect(cmd).toContain("5");
+	});
+});
+
+describe("createBeadsTracker — sync()", () => {
+	let spawnSpy: ReturnType<typeof spyOn>;
+
+	beforeEach(() => {
+		spawnSpy = spyOn(Bun, "spawn");
+	});
+
+	afterEach(() => {
+		spawnSpy.mockRestore();
+	});
+
+	test("calls [bd, sync] directly (not via beads client)", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("", "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		await tracker.sync();
+
+		// sync() calls Bun.spawn directly in beads.ts, not via the beads client
+		expect(spawnSpy).toHaveBeenCalledTimes(1);
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const cmd = callArgs[0] as string[];
+		expect(cmd).toEqual(["bd", "sync"]);
+	});
+
+	test("throws AgentError on failure", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("", "bd sync failed", 1));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		await expect(tracker.sync()).rejects.toThrow(AgentError);
+	});
+});
+
+describe("createBeadsTracker — issue_type normalization", () => {
+	let spawnSpy: ReturnType<typeof spyOn>;
+
+	beforeEach(() => {
+		spawnSpy = spyOn(Bun, "spawn");
+	});
+
+	afterEach(() => {
+		spawnSpy.mockRestore();
+	});
+
+	test("maps issue_type to type field", async () => {
+		const raw = [{ id: "bd-1", title: "t", status: "open", priority: 1, issue_type: "bug" }];
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify(raw), "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		const issues = await tracker.ready();
+
+		expect(issues[0]?.type).toBe("bug");
+	});
+
+	test("falls back to type when issue_type absent", async () => {
+		const raw = [{ id: "bd-1", title: "t", status: "open", priority: 1, type: "feature" }];
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify(raw), "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		const issues = await tracker.ready();
+
+		expect(issues[0]?.type).toBe("feature");
+	});
+
+	test("defaults to 'unknown' when neither issue_type nor type present", async () => {
+		const raw = [{ id: "bd-1", title: "t", status: "open", priority: 1 }];
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify(raw), "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		const issues = await tracker.ready();
+
+		expect(issues[0]?.type).toBe("unknown");
+	});
+
+	test("prefers issue_type over type when both present", async () => {
+		const raw = [
+			{
+				id: "bd-1",
+				title: "t",
+				status: "open",
+				priority: 1,
+				issue_type: "bug",
+				type: "feature",
+			},
+		];
+		spawnSpy.mockImplementation(() => mockSpawnResult(JSON.stringify(raw), "", 0));
+
+		const tracker = createBeadsTracker(TEST_CWD);
+		const issues = await tracker.ready();
+
+		expect(issues[0]?.type).toBe("bug");
+	});
+});
+
+describe("createBeadsTracker — cwd propagation", () => {
+	let spawnSpy: ReturnType<typeof spyOn>;
+
+	beforeEach(() => {
+		spawnSpy = spyOn(Bun, "spawn");
+	});
+
+	afterEach(() => {
+		spawnSpy.mockRestore();
+	});
+
+	test("propagates cwd to Bun.spawn for ready()", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("[]", "", 0));
+
+		const customCwd = "/my/project/root";
+		const tracker = createBeadsTracker(customCwd);
+		await tracker.ready();
+
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const opts = callArgs[1] as { cwd: string };
+		expect(opts.cwd).toBe(customCwd);
+	});
+
+	test("propagates cwd to Bun.spawn for sync()", async () => {
+		spawnSpy.mockImplementation(() => mockSpawnResult("", "", 0));
+
+		const customCwd = "/my/project/root";
+		const tracker = createBeadsTracker(customCwd);
+		await tracker.sync();
+
+		const callArgs = spawnSpy.mock.calls[0] as unknown[];
+		const opts = callArgs[1] as { cwd: string };
+		expect(opts.cwd).toBe(customCwd);
+	});
+});