@os-eco/overstory-cli 0.6.1 → 0.6.5

package/src/types.ts

@@ -129,7 +129,7 @@ export interface AgentSession {
 	capability: string; // Which agent definition
 	worktreePath: string;
 	branchName: string;
-	beadId: string; // Task being worked
+	taskId: string; // Task being worked
 	tmuxSession: string; // Tmux session name
 	state: AgentState;
 	pid: number | null; // Claude Code PID
@@ -151,7 +151,7 @@ export interface AgentIdentity {
 	sessionsCompleted: number;
 	expertiseDomains: string[];
 	recentTasks: Array<{
-		beadId: string;
+		taskId: string;
 		summary: string;
 		completedAt: string;
 	}>;
@@ -210,7 +210,7 @@ export interface MailMessage {
 
 /** Worker signals task completion to supervisor. */
 export interface WorkerDonePayload {
-	beadId: string;
+	taskId: string;
 	branch: string;
 	exitCode: number;
 	filesModified: string[];
@@ -219,7 +219,7 @@ export interface WorkerDonePayload {
 /** Supervisor signals branch is verified and ready for merge. */
 export interface MergeReadyPayload {
 	branch: string;
-	beadId: string;
+	taskId: string;
 	agentName: string;
 	filesModified: string[];
 }
@@ -227,14 +227,14 @@ export interface MergeReadyPayload {
 /** Merger signals branch was merged successfully. */
 export interface MergedPayload {
 	branch: string;
-	beadId: string;
+	taskId: string;
 	tier: ResolutionTier;
 }
 
 /** Merger signals merge failed, needs rework. */
 export interface MergeFailedPayload {
 	branch: string;
-	beadId: string;
+	taskId: string;
 	conflictFiles: string[];
 	errorMessage: string;
 }
@@ -242,7 +242,7 @@ export interface MergeFailedPayload {
 /** Any agent escalates an issue to a higher-level decision-maker. */
 export interface EscalationPayload {
 	severity: "warning" | "error" | "critical";
-	beadId: string | null;
+	taskId: string | null;
 	context: string;
 }
 
@@ -254,7 +254,7 @@ export interface HealthCheckPayload {
 
 /** Coordinator dispatches work to a supervisor. */
 export interface DispatchPayload {
-	beadId: string;
+	taskId: string;
 	specPath: string;
 	capability: Capability;
 	fileScope: string[];
@@ -262,7 +262,7 @@ export interface DispatchPayload {
 
 /** Supervisor assigns work to a specific worker. */
 export interface AssignPayload {
-	beadId: string;
+	taskId: string;
 	specPath: string;
 	workerName: string;
 	branch: string;
@@ -284,7 +284,7 @@ export interface MailPayloadMap {
 
 export interface OverlayConfig {
 	agentName: string;
-	beadId: string;
+	taskId: string;
 	specPath: string | null;
 	branchName: string;
 	worktreePath: string;
@@ -312,7 +312,7 @@ export type ResolutionTier = "clean-merge" | "auto-resolve" | "ai-resolve" | "re
 
 export interface MergeEntry {
 	branchName: string;
-	beadId: string;
+	taskId: string;
 	agentName: string;
 	filesModified: string[];
 	enqueuedAt: string;
@@ -376,7 +376,7 @@ export interface LogEvent {
 
 export interface SessionMetrics {
 	agentName: string;
-	beadId: string;
+	taskId: string;
 	capability: string;
 	startedAt: string;
 	completedAt: string | null;
@@ -645,7 +645,7 @@ export interface MulchCompactResult {
  */
 export interface SessionCheckpoint {
 	agentName: string;
-	beadId: string;
+	taskId: string;
 	sessionId: string; // The AgentSession.id that created this checkpoint
 	timestamp: string; // ISO
 	progressSummary: string; // Human-readable summary of work done so far
@@ -677,7 +677,7 @@ export interface AgentLayers {
 	sandbox: {
 		worktreePath: string;
 		branchName: string;
-		beadId: string;
+		taskId: string;
 	};
 	session: {
 		id: string;

package/src/watchdog/daemon.test.ts

@@ -66,7 +66,7 @@ function makeSession(overrides: Partial<AgentSession> = {}): AgentSession {
 		capability: "builder",
 		worktreePath: "/tmp/test",
 		branchName: "overstory/test-agent/test-task",
-		beadId: "test-task",
+		taskId: "test-task",
 		tmuxSession: "overstory-test-agent",
 		state: "working",
 		pid: process.pid, // Use our own PID so isProcessRunning returns true
@@ -798,7 +798,7 @@ describe("daemon tick", () => {
 			agentName: "old-agent",
 			worktreePath: "/tmp/test",
 			branchName: "overstory/old-agent/task",
-			beadId: "task",
+			taskId: "task",
 			tmuxSession: "overstory-old-agent",
 			state: "working",
 			pid: process.pid,
@@ -1133,7 +1133,7 @@ describe("daemon mulch failure recording", () => {
 		const session = makeSession({
 			agentName: "dying-agent",
 			capability: "builder",
-			beadId: "task-123",
+			taskId: "task-123",
 			tmuxSession: "overstory-dying-agent",
 			state: "working",
 			lastActivity: new Date().toISOString(),
@@ -1158,7 +1158,7 @@ describe("daemon mulch failure recording", () => {
 		expect(failureMock.calls[0]?.tier).toBe(0);
 		expect(failureMock.calls[0]?.session.agentName).toBe("dying-agent");
 		expect(failureMock.calls[0]?.session.capability).toBe("builder");
-		expect(failureMock.calls[0]?.session.beadId).toBe("task-123");
+		expect(failureMock.calls[0]?.session.taskId).toBe("task-123");
 		// Reason should be either the reconciliationNote or default "Process terminated"
 		expect(failureMock.calls[0]?.reason).toBeDefined();
 	});
@@ -1169,7 +1169,7 @@ describe("daemon mulch failure recording", () => {
 		const session = makeSession({
 			agentName: "triaged-agent",
 			capability: "scout",
-			beadId: "task-456",
+			taskId: "task-456",
 			tmuxSession: "overstory-triaged-agent",
 			state: "stalled",
 			lastActivity: staleActivity,
@@ -1198,7 +1198,7 @@ describe("daemon mulch failure recording", () => {
 		expect(failureMock.calls[0]?.tier).toBe(1);
 		expect(failureMock.calls[0]?.session.agentName).toBe("triaged-agent");
 		expect(failureMock.calls[0]?.session.capability).toBe("scout");
-		expect(failureMock.calls[0]?.session.beadId).toBe("task-456");
+		expect(failureMock.calls[0]?.session.taskId).toBe("task-456");
 		expect(failureMock.calls[0]?.triageSuggestion).toBe("terminate");
 		expect(failureMock.calls[0]?.reason).toContain("AI triage");
 	});
@@ -1267,11 +1267,11 @@ describe("daemon mulch failure recording", () => {
 		expect(failureMock.calls).toHaveLength(0);
 	});
 
-	test("recordFailure includes evidenceBead when beadId is present", async () => {
+	test("recordFailure includes evidenceBead when taskId is present", async () => {
 		const session = makeSession({
 			agentName: "beaded-agent",
 			capability: "builder",
-			beadId: "task-789",
+			taskId: "task-789",
 			tmuxSession: "overstory-beaded-agent",
 			state: "working",
 			lastActivity: new Date().toISOString(),
@@ -1292,7 +1292,7 @@ describe("daemon mulch failure recording", () => {
 		});
 
 		expect(failureMock.calls).toHaveLength(1);
-		expect(failureMock.calls[0]?.session.beadId).toBe("task-789");
+		expect(failureMock.calls[0]?.session.taskId).toBe("task-789");
 	});
 
 	test("Tier 0: recordFailure called at escalation level 3+ (progressive termination)", async () => {
@@ -1301,7 +1301,7 @@ describe("daemon mulch failure recording", () => {
 		const session = makeSession({
 			agentName: "doomed-agent",
 			capability: "builder",
-			beadId: "task-999",
+			taskId: "task-999",
 			tmuxSession: "overstory-doomed-agent",
 			state: "stalled",
 			lastActivity: staleActivity,

package/src/watchdog/daemon.ts

@@ -73,7 +73,7 @@ async function recordFailure(
 			type: "failure",
 			description,
 			tags: ["watchdog", "auto-recorded"],
-			evidenceBead: session.beadId || undefined,
+			evidenceBead: session.taskId || undefined,
 		});
 	} catch {
 		// Fire-and-forget: recording failures must not break the watchdog

package/src/watchdog/health.test.ts

@@ -36,7 +36,7 @@ function makeSession(overrides: Partial<AgentSession> = {}): AgentSession {
 		capability: "builder",
 		worktreePath: "/tmp/test",
 		branchName: "overstory/test-agent/test-task",
-		beadId: "test-task",
+		taskId: "test-task",
 		tmuxSession: "overstory-test-agent",
 		state: "booting",
 		pid: ALIVE_PID,

package/src/worktree/manager.test.ts

@@ -58,7 +58,7 @@ describe("createWorktree", () => {
 			baseDir: worktreesDir,
 			agentName: "auth-login",
 			baseBranch: defaultBranch,
-			beadId: "bead-abc123",
+			taskId: "bead-abc123",
 		});
 
 		expect(result.path).toBe(join(worktreesDir, "auth-login"));
@@ -71,7 +71,7 @@ describe("createWorktree", () => {
 			baseDir: worktreesDir,
 			agentName: "auth-login",
 			baseBranch: defaultBranch,
-			beadId: "bead-abc123",
+			taskId: "bead-abc123",
 		});
 
 		expect(existsSync(result.path)).toBe(true);
@@ -85,7 +85,7 @@ describe("createWorktree", () => {
 			baseDir: worktreesDir,
 			agentName: "auth-login",
 			baseBranch: defaultBranch,
-			beadId: "bead-abc123",
+			taskId: "bead-abc123",
 		});
 
 		const branchList = await git(repoDir, ["branch", "--list"]);
@@ -98,7 +98,7 @@ describe("createWorktree", () => {
 			baseDir: worktreesDir,
 			agentName: "auth-login",
 			baseBranch: defaultBranch,
-			beadId: "bead-abc123",
+			taskId: "bead-abc123",
 		});
 
 		await expect(
@@ -107,7 +107,7 @@ describe("createWorktree", () => {
 				baseDir: worktreesDir,
 				agentName: "auth-login",
 				baseBranch: defaultBranch,
-				beadId: "bead-abc123",
+				taskId: "bead-abc123",
 			}),
 		).rejects.toThrow(WorktreeError);
 	});
@@ -119,7 +119,7 @@ describe("createWorktree", () => {
 			baseDir: worktreesDir,
 			agentName: "auth-login",
 			baseBranch: defaultBranch,
-			beadId: "bead-abc123",
+			taskId: "bead-abc123",
 		});
 
 		try {
@@ -128,7 +128,7 @@ describe("createWorktree", () => {
 				baseDir: worktreesDir,
 				agentName: "auth-login",
 				baseBranch: defaultBranch,
-				beadId: "bead-abc123",
+				taskId: "bead-abc123",
 			});
 			// Should not reach here
 			expect(true).toBe(false);
@@ -174,7 +174,7 @@ describe("listWorktrees", () => {
 			baseDir: worktreesDir,
 			agentName: "auth-login",
 			baseBranch: defaultBranch,
-			beadId: "bead-abc",
+			taskId: "bead-abc",
 		});
 
 		await createWorktree({
@@ -182,7 +182,7 @@ describe("listWorktrees", () => {
 			baseDir: worktreesDir,
 			agentName: "data-sync",
 			baseBranch: defaultBranch,
-			beadId: "bead-xyz",
+			taskId: "bead-xyz",
 		});
 
 		const entries = await listWorktrees(repoDir);
@@ -206,7 +206,7 @@ describe("listWorktrees", () => {
 			baseDir: worktreesDir,
 			agentName: "feature-worker",
 			baseBranch: defaultBranch,
-			beadId: "bead-123",
+			taskId: "bead-123",
 		});
 
 		const entries = await listWorktrees(repoDir);
@@ -223,7 +223,7 @@ describe("listWorktrees", () => {
 			baseDir: worktreesDir,
 			agentName: "auth-login",
 			baseBranch: defaultBranch,
-			beadId: "bead-abc",
+			taskId: "bead-abc",
 		});
 
 		const entries = await listWorktrees(repoDir);
@@ -266,7 +266,7 @@ describe("isBranchMerged", () => {
 			baseDir: worktreesDir,
 			agentName: "feature-agent",
 			baseBranch: defaultBranch,
-			beadId: "bead-merged",
+			taskId: "bead-merged",
 		});
 
 		// Add a commit to the feature branch
@@ -285,7 +285,7 @@ describe("isBranchMerged", () => {
 			baseDir: worktreesDir,
 			agentName: "feature-agent",
 			baseBranch: defaultBranch,
-			beadId: "bead-unmerged",
+			taskId: "bead-unmerged",
 		});
 
 		// Add a commit to the feature branch (not merged)
@@ -302,7 +302,7 @@ describe("isBranchMerged", () => {
 			baseDir: worktreesDir,
 			agentName: "feature-agent",
 			baseBranch: defaultBranch,
-			beadId: "bead-same",
+			taskId: "bead-same",
 		});
 
 		// The branch was created from defaultBranch with no additional commits,
@@ -334,7 +334,7 @@ describe("removeWorktree", () => {
 			baseDir: worktreesDir,
 			agentName: "auth-login",
 			baseBranch: defaultBranch,
-			beadId: "bead-abc",
+			taskId: "bead-abc",
 		});
 
 		expect(existsSync(wtPath)).toBe(true);
@@ -350,7 +350,7 @@ describe("removeWorktree", () => {
 			baseDir: worktreesDir,
 			agentName: "auth-login",
 			baseBranch: defaultBranch,
-			beadId: "bead-abc",
+			taskId: "bead-abc",
 		});
 
 		await removeWorktree(repoDir, wtPath);
@@ -365,7 +365,7 @@ describe("removeWorktree", () => {
 			baseDir: worktreesDir,
 			agentName: "auth-login",
 			baseBranch: defaultBranch,
-			beadId: "bead-abc",
+			taskId: "bead-abc",
 		});
 
 		await removeWorktree(repoDir, wtPath);
@@ -381,7 +381,7 @@ describe("removeWorktree", () => {
 			baseDir: worktreesDir,
 			agentName: "auth-login",
 			baseBranch: defaultBranch,
-			beadId: "bead-abc",
+			taskId: "bead-abc",
 		});
 
 		// Create an untracked file in the worktree
@@ -400,7 +400,7 @@ describe("removeWorktree", () => {
 			baseDir: worktreesDir,
 			agentName: "auth-login",
 			baseBranch: defaultBranch,
-			beadId: "bead-abc",
+			taskId: "bead-abc",
 		});
 
 		// Add a commit in the worktree so the branch diverges (making it "unmerged")
@@ -419,7 +419,7 @@ describe("removeWorktree", () => {
 			baseDir: worktreesDir,
 			agentName: "auth-login",
 			baseBranch: defaultBranch,
-			beadId: "bead-abc",
+			taskId: "bead-abc",
 		});
 
 		// Add a commit to make the branch unmerged

package/src/worktree/manager.ts

@@ -1,3 +1,4 @@
+import { unlink } from "node:fs/promises";
 import { join } from "node:path";
 import { WorktreeError } from "../errors.ts";
 
@@ -38,7 +39,7 @@ async function runGit(
  * Create a new git worktree for an agent.
  *
  * Creates a worktree at `{baseDir}/{agentName}` with a new branch
- * named `overstory/{agentName}/{beadId}` based on `baseBranch`.
+ * named `overstory/{agentName}/{taskId}` based on `baseBranch`.
  *
  * @returns The absolute worktree path and branch name.
  */
@@ -47,12 +48,12 @@ export async function createWorktree(options: {
 	baseDir: string;
 	agentName: string;
 	baseBranch: string;
-	beadId: string;
+	taskId: string;
 }): Promise<{ path: string; branch: string }> {
-	const { repoRoot, baseDir, agentName, baseBranch, beadId } = options;
+	const { repoRoot, baseDir, agentName, baseBranch, taskId } = options;
 
 	const worktreePath = join(baseDir, agentName);
-	const branchName = `overstory/${agentName}/${beadId}`;
+	const branchName = `overstory/${agentName}/${taskId}`;
 
 	await runGit(repoRoot, ["worktree", "add", "-b", branchName, worktreePath, baseBranch], {
 		worktreePath,
@@ -196,3 +197,118 @@ export async function removeWorktree(
 		}
 	}
 }
+
+/**
+ * Preserve .seeds/ changes from a branch into the canonical branch.
+ *
+ * Lead agent branches are never merged via the normal merge pipeline, so
+ * any .seeds/ issue files they create would be lost when the worktree is
+ * cleaned. This function extracts only the .seeds/ diff from the branch
+ * and applies it to the canonical branch via a patch.
+ *
+ * @returns `{ preserved: true }` if changes were found and committed,
+ *          `{ preserved: false }` if there were no .seeds/ changes,
+ *          `{ preserved: false, error: "..." }` if something went wrong.
+ */
+export async function preserveSeedsChanges(
+	repoRoot: string,
+	branch: string,
+	canonicalBranch: string,
+	agentName: string,
+): Promise<{ preserved: boolean; error?: string }> {
+	// Step 1: Get the .seeds/ diff between canonical and the branch (three-dot diff).
+	// Three-dot diff shows changes introduced on branch since it diverged from canonicalBranch.
+	let diff: string;
+	try {
+		diff = await runGit(repoRoot, ["diff", `${canonicalBranch}...${branch}`, "--", ".seeds/"]);
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		return { preserved: false, error: `Failed to compute .seeds/ diff: ${msg}` };
+	}
+
+	if (diff.trim() === "") {
+		// No .seeds/ changes on this branch
+		return { preserved: false };
+	}
+
+	// Step 2: Verify the repo root is currently on canonicalBranch.
+	let currentBranch: string;
+	try {
+		currentBranch = (await runGit(repoRoot, ["rev-parse", "--abbrev-ref", "HEAD"])).trim();
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		return { preserved: false, error: `Failed to determine current branch: ${msg}` };
+	}
+
+	if (currentBranch !== canonicalBranch) {
+		return {
+			preserved: false,
+			error: `Repo root is on '${currentBranch}', expected '${canonicalBranch}'. Cannot apply patch.`,
+		};
+	}
+
+	// Step 3: Check that .seeds/ is clean in the canonical branch.
+	let statusOutput: string;
+	try {
+		statusOutput = await runGit(repoRoot, ["status", "--porcelain", "--", ".seeds/"]);
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		return { preserved: false, error: `Failed to check .seeds/ status: ${msg}` };
+	}
+
+	if (statusOutput.trim() !== "") {
+		return {
+			preserved: false,
+			error: `.seeds/ has uncommitted changes in canonical branch. Cannot apply patch safely.`,
+		};
+	}
+
+	// Step 4: Write diff to a temp file.
+	const tmpFile = join(repoRoot, ".overstory", `_seeds-patch-${Date.now()}.diff`);
+	try {
+		await Bun.write(tmpFile, diff);
+
+		// Step 5: Apply the patch with --index (stages changes).
+		try {
+			await runGit(repoRoot, ["apply", "--index", tmpFile]);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			// Revert any partial changes
+			try {
+				await runGit(repoRoot, ["reset", "HEAD", "--", ".seeds/"]);
+				await runGit(repoRoot, ["checkout", "--", ".seeds/"]);
+			} catch {
+				// Best-effort revert
+			}
+			return { preserved: false, error: `Failed to apply .seeds/ patch: ${msg}` };
+		}
+
+		// Step 6: Commit the changes.
+		try {
+			await runGit(repoRoot, [
+				"commit",
+				"-m",
+				`chore: preserve .seeds/ changes from lead ${agentName}`,
+			]);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			// Revert any staged changes
+			try {
+				await runGit(repoRoot, ["reset", "HEAD", "--", ".seeds/"]);
+				await runGit(repoRoot, ["checkout", "--", ".seeds/"]);
+			} catch {
+				// Best-effort revert
+			}
+			return { preserved: false, error: `Failed to commit .seeds/ changes: ${msg}` };
+		}
+
+		return { preserved: true };
+	} finally {
+		// Step 8: Always clean up the temp file.
+		try {
+			await unlink(tmpFile);
+		} catch {
+			// Ignore cleanup errors
+		}
+	}
+}

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");
+		}
+	});
 });