@ag-eco/agentplate-cli 0.13.0

package/src/commands/worktree.test.ts

@@ -0,0 +1,1297 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, realpathSync } from "node:fs";
+import { mkdir, mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ValidationError } from "../errors.ts";
+import { createSessionStore } from "../sessions/store.ts";
+import { cleanupTempDir, commitFile, createTempGitRepo, runGitInDir } from "../test-helpers.ts";
+import type { AgentSession } from "../types.ts";
+import { createWorktree } from "../worktree/manager.ts";
+import { checkLiveChildren, worktreeCommand } from "./worktree.ts";
+
+/**
+ * Tests for `agentplate worktree` command.
+ *
+ * Uses real git worktrees in temp repos to test list and clean subcommands.
+ * Captures process.stdout.write to verify output formatting.
+ */
+
+describe("worktreeCommand", () => {
+	let chunks: string[];
+	let originalWrite: typeof process.stdout.write;
+	let tempDir: string;
+	let originalCwd: string;
+
+	beforeEach(async () => {
+		// Spy on stdout
+		chunks = [];
+		originalWrite = process.stdout.write;
+		process.stdout.write = ((chunk: string) => {
+			chunks.push(chunk);
+			return true;
+		}) as typeof process.stdout.write;
+
+		// Create temp git repo with .agentplate/config.yaml structure
+		tempDir = await createTempGitRepo();
+		// Normalize tempDir to resolve macOS /var -> /private/var symlink
+		tempDir = realpathSync(tempDir);
+		const agentplateDir = join(tempDir, ".agentplate");
+		await mkdir(agentplateDir, { recursive: true });
+		await Bun.write(
+			join(agentplateDir, "config.yaml"),
+			`project:\n  name: test\n  root: ${tempDir}\n  canonicalBranch: main\n`,
+		);
+
+		// Change to temp dir so loadConfig() works
+		originalCwd = process.cwd();
+		process.chdir(tempDir);
+	});
+
+	afterEach(async () => {
+		process.stdout.write = originalWrite;
+		process.chdir(originalCwd);
+		await cleanupTempDir(tempDir);
+	});
+
+	function output(): string {
+		return chunks.join("");
+	}
+
+	/**
+	 * Helper to create an AgentSession with sensible defaults.
+	 * Uses FAKE tmux session names to avoid real tmux calls during tests.
+	 */
+	function makeSession(overrides: Partial<AgentSession> = {}): AgentSession {
+		return {
+			id: "session-test",
+			agentName: "test-agent",
+			capability: "builder",
+			worktreePath: join(tempDir, ".agentplate", "worktrees", "test-agent"),
+			branchName: "agentplate/test-agent/task-1",
+			taskId: "task-1",
+			tmuxSession: "agentplate-test-agent-fake", // FAKE tmux session name
+			state: "working",
+			pid: 12345,
+			parentAgent: null,
+			depth: 0,
+			runId: null,
+			startedAt: new Date().toISOString(),
+			lastActivity: new Date().toISOString(),
+			escalationLevel: 0,
+			stalledSince: null,
+			transcriptPath: null,
+			...overrides,
+		};
+	}
+
+	/**
+	 * Helper to write sessions to SessionStore (sessions.db) in the temp repo.
+	 */
+	function writeSessionsToStore(sessions: AgentSession[]): void {
+		const dbPath = join(tempDir, ".agentplate", "sessions.db");
+		const store = createSessionStore(dbPath);
+		for (const session of sessions) {
+			store.upsert(session);
+		}
+		store.close();
+	}
+
+	describe("help flags", () => {
+		test("--help shows help text", async () => {
+			await worktreeCommand(["--help"]);
+			const out = output();
+
+			expect(out).toContain("worktree");
+			expect(out).toContain("list");
+			expect(out).toContain("clean");
+		});
+
+		test("-h shows help text", async () => {
+			await worktreeCommand(["-h"]);
+			const out = output();
+
+			expect(out).toContain("worktree");
+			expect(out).toContain("list");
+		});
+	});
+
+	describe("validation", () => {
+		test("unknown subcommand throws ValidationError", async () => {
+			await expect(worktreeCommand(["unknown"])).rejects.toThrow(ValidationError);
+		});
+
+		test("empty args shows help text", async () => {
+			await worktreeCommand([]);
+			const out = output();
+			expect(out).toContain("worktree");
+		});
+	});
+
+	describe("worktree list", () => {
+		test("no agentplate worktrees returns empty message", async () => {
+			await worktreeCommand(["list"]);
+			const out = output();
+
+			expect(out).toContain("No agent worktrees found");
+		});
+
+		test("with agentplate worktrees lists them with agent info", async () => {
+			// Create a real git worktree with agentplate/ prefix branch
+			const worktreesDir = join(tempDir, ".agentplate", "worktrees");
+			await mkdir(worktreesDir, { recursive: true });
+
+			const worktreePath = join(worktreesDir, "test-agent");
+			await runGitInDir(tempDir, [
+				"worktree",
+				"add",
+				worktreePath,
+				"-b",
+				"agentplate/test-agent/task-1",
+			]);
+
+			// Write sessions.db to associate worktree with agent
+			writeSessionsToStore([
+				{
+					id: "session-1",
+					agentName: "test-agent",
+					capability: "builder",
+					worktreePath,
+					branchName: "agentplate/test-agent/task-1",
+					taskId: "task-1",
+					tmuxSession: "agentplate-test-agent",
+					state: "working",
+					pid: 12345,
+					parentAgent: null,
+					depth: 0,
+					runId: null,
+					startedAt: new Date().toISOString(),
+					lastActivity: new Date().toISOString(),
+					escalationLevel: 0,
+					stalledSince: null,
+					transcriptPath: null,
+				},
+			]);
+
+			await worktreeCommand(["list"]);
+			const out = output();
+
+			expect(out).toContain("Agent worktrees: 1");
+			expect(out).toContain("agentplate/test-agent/task-1");
+			expect(out).toContain("Agent: test-agent");
+			expect(out).toContain("State: working");
+			expect(out).toContain("Task: task-1");
+			expect(out).toContain(`Path: ${worktreePath}`);
+		});
+
+		test("--json flag outputs valid JSON array", async () => {
+			// Create a real git worktree
+			const worktreesDir = join(tempDir, ".agentplate", "worktrees");
+			await mkdir(worktreesDir, { recursive: true });
+
+			const worktreePath = join(worktreesDir, "test-agent");
+			await runGitInDir(tempDir, [
+				"worktree",
+				"add",
+				worktreePath,
+				"-b",
+				"agentplate/test-agent/task-1",
+			]);
+
+			// Write sessions.db
+			writeSessionsToStore([
+				{
+					id: "session-1",
+					agentName: "test-agent",
+					capability: "builder",
+					worktreePath,
+					branchName: "agentplate/test-agent/task-1",
+					taskId: "task-1",
+					tmuxSession: "agentplate-test-agent",
+					state: "working",
+					pid: 12345,
+					parentAgent: null,
+					depth: 0,
+					runId: null,
+					startedAt: new Date().toISOString(),
+					lastActivity: new Date().toISOString(),
+					escalationLevel: 0,
+					stalledSince: null,
+					transcriptPath: null,
+				},
+			]);
+
+			await worktreeCommand(["list", "--json"]);
+			const out = output();
+
+			const parsed = JSON.parse(out.trim()) as {
+				success: boolean;
+				command: string;
+				worktrees: Array<{
+					path: string;
+					branch: string;
+					head: string;
+					agentName: string | null;
+					state: string | null;
+					taskId: string | null;
+				}>;
+			};
+
+			expect(parsed.success).toBe(true);
+			expect(parsed.command).toBe("worktree list");
+			expect(parsed.worktrees).toHaveLength(1);
+			expect(parsed.worktrees[0]?.path).toBe(worktreePath);
+			expect(parsed.worktrees[0]?.branch).toBe("agentplate/test-agent/task-1");
+			expect(parsed.worktrees[0]?.agentName).toBe("test-agent");
+			expect(parsed.worktrees[0]?.state).toBe("working");
+			expect(parsed.worktrees[0]?.taskId).toBe("task-1");
+		});
+
+		test("worktrees without sessions show unknown state", async () => {
+			// Create a worktree but no sessions.db entry
+			const worktreesDir = join(tempDir, ".agentplate", "worktrees");
+			await mkdir(worktreesDir, { recursive: true });
+
+			const worktreePath = join(worktreesDir, "orphan-agent");
+			await runGitInDir(tempDir, [
+				"worktree",
+				"add",
+				worktreePath,
+				"-b",
+				"agentplate/orphan-agent/task-2",
+			]);
+
+			await worktreeCommand(["list"]);
+			const out = output();
+
+			expect(out).toContain("agentplate/orphan-agent/task-2");
+			expect(out).toContain("Agent: ?");
+			expect(out).toContain("State: unknown");
+			expect(out).toContain("Task: ?");
+		});
+	});
+
+	describe("worktree clean", () => {
+		test("no agentplate worktrees returns empty message", async () => {
+			await worktreeCommand(["clean"]);
+			const out = output();
+
+			expect(out).toContain("No worktrees to clean");
+		});
+
+		test("with completed agent worktree removes it and reports count", async () => {
+			// Create a real git worktree
+			const worktreesDir = join(tempDir, ".agentplate", "worktrees");
+			await mkdir(worktreesDir, { recursive: true });
+
+			const worktreePath = join(worktreesDir, "completed-agent");
+			await runGitInDir(tempDir, [
+				"worktree",
+				"add",
+				worktreePath,
+				"-b",
+				"agentplate/completed-agent/task-done",
+			]);
+
+			// Write sessions.db with completed state
+			writeSessionsToStore([
+				{
+					id: "session-1",
+					agentName: "completed-agent",
+					capability: "builder",
+					worktreePath,
+					branchName: "agentplate/completed-agent/task-done",
+					taskId: "task-done",
+					tmuxSession: "agentplate-completed-agent",
+					state: "completed",
+					pid: 12345,
+					parentAgent: null,
+					depth: 0,
+					runId: null,
+					startedAt: new Date().toISOString(),
+					lastActivity: new Date().toISOString(),
+					escalationLevel: 0,
+					stalledSince: null,
+					transcriptPath: null,
+				},
+			]);
+
+			await worktreeCommand(["clean"]);
+			const out = output();
+
+			expect(out).toContain("Removed");
+			expect(out).toContain("agentplate/completed-agent/task-done");
+			expect(out).toContain("Cleaned 1 worktree");
+
+			// Verify the worktree directory is gone
+			const worktreeExists = await Bun.file(worktreePath).exists();
+			expect(worktreeExists).toBe(false);
+
+			// Verify the branch is deleted
+			const branchListProc = Bun.spawn(
+				["git", "branch", "--list", "agentplate/completed-agent/*"],
+				{
+					cwd: tempDir,
+					stdout: "pipe",
+				},
+			);
+			const branchList = await new Response(branchListProc.stdout).text();
+			expect(branchList.trim()).toBe("");
+		});
+
+		test("--json flag returns JSON with cleaned/failed/pruned arrays", async () => {
+			// Create a completed worktree
+			const worktreesDir = join(tempDir, ".agentplate", "worktrees");
+			await mkdir(worktreesDir, { recursive: true });
+
+			const worktreePath = join(worktreesDir, "done-agent");
+			await runGitInDir(tempDir, [
+				"worktree",
+				"add",
+				worktreePath,
+				"-b",
+				"agentplate/done-agent/task-x",
+			]);
+
+			writeSessionsToStore([
+				{
+					id: "session-1",
+					agentName: "done-agent",
+					capability: "builder",
+					worktreePath,
+					branchName: "agentplate/done-agent/task-x",
+					taskId: "task-x",
+					tmuxSession: "agentplate-done-agent",
+					state: "completed",
+					pid: 12345,
+					parentAgent: null,
+					depth: 0,
+					runId: null,
+					startedAt: new Date().toISOString(),
+					lastActivity: new Date().toISOString(),
+					escalationLevel: 0,
+					stalledSince: null,
+					transcriptPath: null,
+				},
+			]);
+
+			await worktreeCommand(["clean", "--json"]);
+			const out = output();
+
+			const parsed = JSON.parse(out.trim()) as {
+				cleaned: string[];
+				failed: string[];
+				pruned: number;
+			};
+
+			expect(parsed.cleaned).toEqual(["agentplate/done-agent/task-x"]);
+			expect(parsed.failed).toEqual([]);
+			expect(parsed.pruned).toBe(1); // The zombie session was pruned
+		});
+
+		test("zombie sessions whose worktree paths no longer exist get pruned from sessions.db", async () => {
+			// Create sessions.db with a zombie entry whose worktree doesn't exist
+			const nonExistentPath = join(tempDir, ".agentplate", "worktrees", "ghost-agent");
+			writeSessionsToStore([
+				{
+					id: "session-ghost",
+					agentName: "ghost-agent",
+					capability: "builder",
+					worktreePath: nonExistentPath,
+					branchName: "agentplate/ghost-agent/task-ghost",
+					taskId: "task-ghost",
+					tmuxSession: "agentplate-ghost-agent",
+					state: "zombie",
+					pid: null,
+					parentAgent: null,
+					depth: 0,
+					runId: null,
+					startedAt: new Date().toISOString(),
+					lastActivity: new Date().toISOString(),
+					escalationLevel: 0,
+					stalledSince: null,
+					transcriptPath: null,
+				},
+			]);
+
+			await worktreeCommand(["clean", "--json"]);
+			const out = output();
+
+			const parsed = JSON.parse(out.trim()) as {
+				cleaned: string[];
+				failed: string[];
+				pruned: number;
+			};
+
+			expect(parsed.pruned).toBe(1);
+
+			// Verify sessions.db no longer contains the zombie
+			const dbPath = join(tempDir, ".agentplate", "sessions.db");
+			const store = createSessionStore(dbPath);
+			const updatedSessions = store.getAll();
+			store.close();
+			expect(updatedSessions).toHaveLength(0);
+		});
+
+		test("stalled agents are cleaned like working agents (not by default)", async () => {
+			// Create a worktree with stalled state
+			const worktreesDir = join(tempDir, ".agentplate", "worktrees");
+			await mkdir(worktreesDir, { recursive: true });
+
+			const worktreePath = join(worktreesDir, "stalled-agent");
+			await runGitInDir(tempDir, [
+				"worktree",
+				"add",
+				worktreePath,
+				"-b",
+				"agentplate/stalled-agent/task-stuck",
+			]);
+
+			writeSessionsToStore([
+				{
+					id: "session-1",
+					agentName: "stalled-agent",
+					capability: "builder",
+					worktreePath,
+					branchName: "agentplate/stalled-agent/task-stuck",
+					taskId: "task-stuck",
+					tmuxSession: "agentplate-stalled-agent",
+					state: "stalled",
+					pid: 12345,
+					parentAgent: null,
+					depth: 0,
+					runId: null,
+					startedAt: new Date().toISOString(),
+					lastActivity: new Date().toISOString(),
+					escalationLevel: 0,
+					stalledSince: new Date().toISOString(),
+					transcriptPath: null,
+				},
+			]);
+
+			await worktreeCommand(["clean"]);
+			const out = output();
+
+			// Stalled agents should not be cleaned by default (only completed/zombie are cleaned)
+			expect(out).toContain("No worktrees to clean");
+		});
+
+		test("--completed flag only cleans completed agents", async () => {
+			// Create two worktrees using createWorktree
+			const worktreesDir = join(tempDir, ".agentplate", "worktrees");
+			await mkdir(worktreesDir, { recursive: true });
+
+			const { path: completedPath } = await createWorktree({
+				repoRoot: tempDir,
+				baseDir: worktreesDir,
+				agentName: "completed-agent",
+				baseBranch: "main",
+				taskId: "task-done",
+			});
+
+			const { path: workingPath } = await createWorktree({
+				repoRoot: tempDir,
+				baseDir: worktreesDir,
+				agentName: "working-agent",
+				baseBranch: "main",
+				taskId: "task-wip",
+			});
+
+			// Write sessions.db with both agents
+			writeSessionsToStore([
+				makeSession({
+					id: "session-1",
+					agentName: "completed-agent",
+					worktreePath: completedPath,
+					branchName: "agentplate/completed-agent/task-done",
+					taskId: "task-done",
+					tmuxSession: "agentplate-completed-agent-fake",
+					state: "completed",
+				}),
+				makeSession({
+					id: "session-2",
+					agentName: "working-agent",
+					worktreePath: workingPath,
+					branchName: "agentplate/working-agent/task-wip",
+					taskId: "task-wip",
+					tmuxSession: "agentplate-working-agent-fake",
+					state: "working",
+					pid: 12346,
+				}),
+			]);
+
+			await worktreeCommand(["clean", "--completed"]);
+			const out = output();
+
+			expect(out).toContain("Cleaned 1 worktree");
+
+			// Verify only the completed worktree is removed
+			expect(existsSync(completedPath)).toBe(false);
+			expect(existsSync(workingPath)).toBe(true);
+		});
+
+		test("--all flag cleans all worktrees regardless of state", async () => {
+			// Create three worktrees with different states
+			const worktreesDir = join(tempDir, ".agentplate", "worktrees");
+			await mkdir(worktreesDir, { recursive: true });
+
+			const { path: completedPath } = await createWorktree({
+				repoRoot: tempDir,
+				baseDir: worktreesDir,
+				agentName: "completed-agent",
+				baseBranch: "main",
+				taskId: "task-done",
+			});
+
+			const { path: workingPath } = await createWorktree({
+				repoRoot: tempDir,
+				baseDir: worktreesDir,
+				agentName: "working-agent",
+				baseBranch: "main",
+				taskId: "task-wip",
+			});
+
+			const { path: stalledPath } = await createWorktree({
+				repoRoot: tempDir,
+				baseDir: worktreesDir,
+				agentName: "stalled-agent",
+				baseBranch: "main",
+				taskId: "task-stuck",
+			});
+
+			// Write sessions with different states
+			writeSessionsToStore([
+				makeSession({
+					id: "session-1",
+					agentName: "completed-agent",
+					worktreePath: completedPath,
+					branchName: "agentplate/completed-agent/task-done",
+					taskId: "task-done",
+					state: "completed",
+				}),
+				makeSession({
+					id: "session-2",
+					agentName: "working-agent",
+					worktreePath: workingPath,
+					branchName: "agentplate/working-agent/task-wip",
+					taskId: "task-wip",
+					state: "working",
+				}),
+				makeSession({
+					id: "session-3",
+					agentName: "stalled-agent",
+					worktreePath: stalledPath,
+					branchName: "agentplate/stalled-agent/task-stuck",
+					taskId: "task-stuck",
+					state: "stalled",
+				}),
+			]);
+
+			await worktreeCommand(["clean", "--all"]);
+			const out = output();
+
+			expect(out).toContain("Cleaned 3 worktrees");
+
+			// Verify all worktrees are removed
+			expect(existsSync(completedPath)).toBe(false);
+			expect(existsSync(workingPath)).toBe(false);
+			expect(existsSync(stalledPath)).toBe(false);
+		});
+
+		test("multiple completed worktrees reports correct count", async () => {
+			// Create two completed worktrees
+			const worktreesDir = join(tempDir, ".agentplate", "worktrees");
+			await mkdir(worktreesDir, { recursive: true });
+
+			const path1 = join(worktreesDir, "agent-1");
+			await runGitInDir(tempDir, ["worktree", "add", path1, "-b", "agentplate/agent-1/task-1"]);
+
+			const path2 = join(worktreesDir, "agent-2");
+			await runGitInDir(tempDir, ["worktree", "add", path2, "-b", "agentplate/agent-2/task-2"]);
+
+			writeSessionsToStore([
+				{
+					id: "session-1",
+					agentName: "agent-1",
+					capability: "builder",
+					worktreePath: path1,
+					branchName: "agentplate/agent-1/task-1",
+					taskId: "task-1",
+					tmuxSession: "agentplate-agent-1",
+					state: "completed",
+					pid: 12345,
+					parentAgent: null,
+					depth: 0,
+					runId: null,
+					startedAt: new Date().toISOString(),
+					lastActivity: new Date().toISOString(),
+					escalationLevel: 0,
+					stalledSince: null,
+					transcriptPath: null,
+				},
+				{
+					id: "session-2",
+					agentName: "agent-2",
+					capability: "builder",
+					worktreePath: path2,
+					branchName: "agentplate/agent-2/task-2",
+					taskId: "task-2",
+					tmuxSession: "agentplate-agent-2",
+					state: "completed",
+					pid: 12346,
+					parentAgent: null,
+					depth: 0,
+					runId: null,
+					startedAt: new Date().toISOString(),
+					lastActivity: new Date().toISOString(),
+					escalationLevel: 0,
+					stalledSince: null,
+					transcriptPath: null,
+				},
+			]);
+
+			await worktreeCommand(["clean"]);
+			const out = output();
+
+			expect(out).toContain("Cleaned 2 worktrees");
+		});
+
+		test("without --force, skips worktrees with unmerged branches and prints warning", async () => {
+			const worktreesDir = join(tempDir, ".agentplate", "worktrees");
+			await mkdir(worktreesDir, { recursive: true });
+
+			const { path: wtPath } = await createWorktree({
+				repoRoot: tempDir,
+				baseDir: worktreesDir,
+				agentName: "unmerged-agent",
+				baseBranch: "main",
+				taskId: "task-unmerged",
+			});
+
+			// Add an unmerged commit
+			await commitFile(wtPath, "work.ts", "export const y = 2;", "unmerged work");
+
+			writeSessionsToStore([
+				makeSession({
+					id: "session-u",
+					agentName: "unmerged-agent",
+					worktreePath: wtPath,
+					branchName: "agentplate/unmerged-agent/task-unmerged",
+					taskId: "task-unmerged",
+					state: "completed",
+				}),
+			]);
+
+			await worktreeCommand(["clean"]);
+			const out = output();
+
+			// Worktree should NOT have been removed
+			expect(existsSync(wtPath)).toBe(true);
+			// Warning should be printed
+			expect(out).toContain("Skipped 1 worktree");
+			expect(out).toContain("agentplate/unmerged-agent/task-unmerged");
+			expect(out).toContain("--force");
+		});
+
+		test("with --force, deletes worktrees with unmerged branches", async () => {
+			const worktreesDir = join(tempDir, ".agentplate", "worktrees");
+			await mkdir(worktreesDir, { recursive: true });
+
+			const { path: wtPath } = await createWorktree({
+				repoRoot: tempDir,
+				baseDir: worktreesDir,
+				agentName: "unmerged-agent",
+				baseBranch: "main",
+				taskId: "task-force",
+			});
+
+			// Add an unmerged commit
+			await commitFile(wtPath, "work.ts", "export const y = 2;", "unmerged work");
+
+			writeSessionsToStore([
+				makeSession({
+					id: "session-f",
+					agentName: "unmerged-agent",
+					worktreePath: wtPath,
+					branchName: "agentplate/unmerged-agent/task-force",
+					taskId: "task-force",
+					state: "completed",
+				}),
+			]);
+
+			await worktreeCommand(["clean", "--force"]);
+			const out = output();
+
+			// Worktree should be removed
+			expect(existsSync(wtPath)).toBe(false);
+			expect(out).toContain("agentplate/unmerged-agent/task-force");
+		});
+
+		test("without --force, removes worktrees whose branches ARE merged", async () => {
+			const worktreesDir = join(tempDir, ".agentplate", "worktrees");
+			await mkdir(worktreesDir, { recursive: true });
+
+			const { path: wtPath, branch } = await createWorktree({
+				repoRoot: tempDir,
+				baseDir: worktreesDir,
+				agentName: "merged-agent",
+				baseBranch: "main",
+				taskId: "task-merged",
+			});
+
+			// Add a commit and merge it into main
+			await commitFile(wtPath, "work.ts", "export const z = 3;", "work to merge");
+			await runGitInDir(tempDir, ["merge", "--no-ff", branch, "-m", "merge feature"]);
+
+			writeSessionsToStore([
+				makeSession({
+					id: "session-m",
+					agentName: "merged-agent",
+					worktreePath: wtPath,
+					branchName: branch,
+					taskId: "task-merged",
+					state: "completed",
+				}),
+			]);
+
+			await worktreeCommand(["clean"]);
+			const out = output();
+
+			// Merged worktree should be cleaned
+			expect(existsSync(wtPath)).toBe(false);
+			expect(out).toContain("Cleaned 1 worktree");
+		});
+
+		test("--json output includes skipped array for unmerged branches", async () => {
+			const worktreesDir = join(tempDir, ".agentplate", "worktrees");
+			await mkdir(worktreesDir, { recursive: true });
+
+			const { path: wtPath } = await createWorktree({
+				repoRoot: tempDir,
+				baseDir: worktreesDir,
+				agentName: "unmerged-json-agent",
+				baseBranch: "main",
+				taskId: "task-json",
+			});
+
+			// Add an unmerged commit
+			await commitFile(wtPath, "work.ts", "export const w = 4;", "unmerged work");
+
+			writeSessionsToStore([
+				makeSession({
+					id: "session-j",
+					agentName: "unmerged-json-agent",
+					worktreePath: wtPath,
+					branchName: "agentplate/unmerged-json-agent/task-json",
+					taskId: "task-json",
+					state: "completed",
+				}),
+			]);
+
+			await worktreeCommand(["clean", "--json"]);
+			const out = output();
+
+			const parsed = JSON.parse(out.trim()) as {
+				cleaned: string[];
+				failed: string[];
+				skipped: string[];
+				pruned: number;
+				mailPurged: number;
+			};
+
+			expect(parsed.cleaned).toEqual([]);
+			expect(parsed.skipped).toEqual(["agentplate/unmerged-json-agent/task-json"]);
+		});
+
+		test("lead worktree with .sprout/ changes preserves them to canonical before cleanup", async () => {
+			const worktreesDir = join(tempDir, ".agentplate", "worktrees");
+			await mkdir(worktreesDir, { recursive: true });
+
+			const { path: wtPath, branch } = await createWorktree({
+				repoRoot: tempDir,
+				baseDir: worktreesDir,
+				agentName: "lead-with-sprout",
+				baseBranch: "main",
+				taskId: "task-lead-sprout",
+			});
+
+			// Commit a .sprout/ file in the lead worktree
+			await commitFile(
+				wtPath,
+				".sprout/issues/test-issue.yaml",
+				"id: test-issue\ntitle: Test Issue\nstatus: open\n",
+				"sprout: add test issue",
+			);
+
+			writeSessionsToStore([
+				makeSession({
+					id: "session-lead-sprout",
+					agentName: "lead-with-sprout",
+					capability: "lead",
+					worktreePath: wtPath,
+					branchName: branch,
+					taskId: "task-lead-sprout",
+					state: "completed",
+				}),
+			]);
+
+			await worktreeCommand(["clean"]);
+			const out = output();
+
+			// The worktree should be removed
+			expect(existsSync(wtPath)).toBe(false);
+
+			// The .sprout/ changes should have been preserved to main
+			const showProc = Bun.spawn(["git", "show", "main:.sprout/issues/test-issue.yaml"], {
+				cwd: tempDir,
+				stdout: "pipe",
+				stderr: "pipe",
+			});
+			const showOut = await new Response(showProc.stdout).text();
+			const showExit = await showProc.exited;
+			expect(showExit).toBe(0);
+			expect(showOut).toContain("test-issue");
+
+			// Output should mention preservation
+			expect(out).toContain("Preserved .sprout/");
+		});
+
+		test("lead worktree without .sprout/ changes cleans normally", async () => {
+			const worktreesDir = join(tempDir, ".agentplate", "worktrees");
+			await mkdir(worktreesDir, { recursive: true });
+
+			const { path: wtPath, branch } = await createWorktree({
+				repoRoot: tempDir,
+				baseDir: worktreesDir,
+				agentName: "lead-no-sprout",
+				baseBranch: "main",
+				taskId: "task-lead-no-sprout",
+			});
+
+			// Commit a non-.sprout/ file
+			await commitFile(wtPath, "src/work.ts", "export const x = 1;", "non-sprout work");
+
+			writeSessionsToStore([
+				makeSession({
+					id: "session-lead-no-sprout",
+					agentName: "lead-no-sprout",
+					capability: "lead",
+					worktreePath: wtPath,
+					branchName: branch,
+					taskId: "task-lead-no-sprout",
+					state: "completed",
+				}),
+			]);
+
+			await worktreeCommand(["clean"]);
+			const out = output();
+
+			// Worktree should be removed
+			expect(existsSync(wtPath)).toBe(false);
+			// Output should NOT mention .sprout/ preservation
+			expect(out).not.toContain("Preserved .sprout/");
+			// Should still report as cleaned
+			expect(out).toContain("Cleaned 1 worktree");
+		});
+
+		test("lead worktrees are cleaned without --force even with unmerged non-sprout changes", async () => {
+			const worktreesDir = join(tempDir, ".agentplate", "worktrees");
+			await mkdir(worktreesDir, { recursive: true });
+
+			const { path: wtPath, branch } = await createWorktree({
+				repoRoot: tempDir,
+				baseDir: worktreesDir,
+				agentName: "lead-unmerged",
+				baseBranch: "main",
+				taskId: "task-lead-unmerged",
+			});
+
+			// Add unmerged non-.sprout/ commit
+			await commitFile(wtPath, "src/lead-work.ts", "export const y = 2;", "unmerged lead work");
+
+			writeSessionsToStore([
+				makeSession({
+					id: "session-lead-unmerged",
+					agentName: "lead-unmerged",
+					capability: "lead",
+					worktreePath: wtPath,
+					branchName: branch,
+					taskId: "task-lead-unmerged",
+					state: "completed",
+				}),
+			]);
+
+			// Run clean WITHOUT --force — leads bypass merge check
+			await worktreeCommand(["clean"]);
+			const out = output();
+
+			// Lead worktree SHOULD be removed (not skipped)
+			expect(existsSync(wtPath)).toBe(false);
+			expect(out).toContain("Cleaned 1 worktree");
+			expect(out).not.toContain("Skipped");
+		});
+
+		test("--json output includes sproutPreserved array", async () => {
+			const worktreesDir = join(tempDir, ".agentplate", "worktrees");
+			await mkdir(worktreesDir, { recursive: true });
+
+			const { path: wtPath, branch } = await createWorktree({
+				repoRoot: tempDir,
+				baseDir: worktreesDir,
+				agentName: "lead-sprout-json",
+				baseBranch: "main",
+				taskId: "task-sprout-json",
+			});
+
+			// Commit a .sprout/ file in the lead worktree
+			await commitFile(
+				wtPath,
+				".sprout/issues/json-issue.yaml",
+				"id: json-issue\ntitle: JSON Issue\nstatus: open\n",
+				"sprout: add json issue",
+			);
+
+			writeSessionsToStore([
+				makeSession({
+					id: "session-lead-json",
+					agentName: "lead-sprout-json",
+					capability: "lead",
+					worktreePath: wtPath,
+					branchName: branch,
+					taskId: "task-sprout-json",
+					state: "completed",
+				}),
+			]);
+
+			await worktreeCommand(["clean", "--json"]);
+			const out = output();
+
+			const parsed = JSON.parse(out.trim()) as {
+				cleaned: string[];
+				failed: string[];
+				skipped: string[];
+				pruned: number;
+				mailPurged: number;
+				sproutPreserved: string[];
+			};
+
+			expect(parsed.cleaned).toContain(branch);
+			expect(parsed.sproutPreserved).toContain(branch);
+		});
+
+		describe("live-children guard", () => {
+			/**
+			 * Write sessions into a nested .agentplate/sessions.db inside a worktree.
+			 * Simulates a lead worktree that has spawned builder children.
+			 */
+			function writeNestedSessions(worktreePath: string, sessions: AgentSession[]): void {
+				const nestedAgentplate = join(worktreePath, ".agentplate");
+				mkdirSync(nestedAgentplate, { recursive: true });
+				const store = createSessionStore(join(nestedAgentplate, "sessions.db"));
+				for (const s of sessions) {
+					store.upsert(s);
+				}
+				store.close();
+			}
+
+			test("clean skipped when live children present (no --force)", async () => {
+				const worktreesDir = join(tempDir, ".agentplate", "worktrees");
+				await mkdir(worktreesDir, { recursive: true });
+
+				const { path: wtPath } = await createWorktree({
+					repoRoot: tempDir,
+					baseDir: worktreesDir,
+					agentName: "lead-with-children",
+					baseBranch: "main",
+					taskId: "task-lead",
+				});
+
+				// Parent session is completed
+				writeSessionsToStore([
+					makeSession({
+						id: "session-lead",
+						agentName: "lead-with-children",
+						capability: "lead",
+						worktreePath: wtPath,
+						branchName: "agentplate/lead-with-children/task-lead",
+						taskId: "task-lead",
+						state: "completed",
+					}),
+				]);
+
+				// Nested session with process.pid (guaranteed alive)
+				writeNestedSessions(wtPath, [
+					{
+						id: "nested-builder",
+						agentName: "nested-builder",
+						capability: "builder",
+						worktreePath: join(wtPath, ".agentplate", "worktrees", "nested-builder"),
+						branchName: "agentplate/nested-builder/task-child",
+						taskId: "task-child",
+						tmuxSession: "agentplate-nested-builder-fake",
+						state: "working",
+						pid: process.pid, // current process — guaranteed alive
+						parentAgent: "lead-with-children",
+						depth: 2,
+						runId: null,
+						startedAt: new Date().toISOString(),
+						lastActivity: new Date().toISOString(),
+						escalationLevel: 0,
+						stalledSince: null,
+						transcriptPath: null,
+					},
+				]);
+
+				await worktreeCommand(["clean", "--completed", "--json"]);
+				const out = output();
+
+				const parsed = JSON.parse(out.trim()) as {
+					cleaned: string[];
+					blockedByChildren: string[];
+				};
+
+				expect(parsed.cleaned).toEqual([]);
+				expect(parsed.blockedByChildren).toContain("agentplate/lead-with-children/task-lead");
+				// Worktree still exists
+				expect(existsSync(wtPath)).toBe(true);
+			});
+
+			test("clean proceeds when nested sessions are dead (pid unreachable)", async () => {
+				const worktreesDir = join(tempDir, ".agentplate", "worktrees");
+				await mkdir(worktreesDir, { recursive: true });
+
+				const { path: wtPath } = await createWorktree({
+					repoRoot: tempDir,
+					baseDir: worktreesDir,
+					agentName: "lead-dead-children",
+					baseBranch: "main",
+					taskId: "task-dead",
+				});
+
+				writeSessionsToStore([
+					makeSession({
+						id: "session-lead-dead",
+						agentName: "lead-dead-children",
+						capability: "lead",
+						worktreePath: wtPath,
+						branchName: "agentplate/lead-dead-children/task-dead",
+						taskId: "task-dead",
+						state: "completed",
+					}),
+				]);
+
+				// Nested session with a dead pid (extremely high, will not exist)
+				writeNestedSessions(wtPath, [
+					{
+						id: "nested-dead",
+						agentName: "nested-dead",
+						capability: "builder",
+						worktreePath: join(wtPath, ".agentplate", "worktrees", "nested-dead"),
+						branchName: "agentplate/nested-dead/task-dead-child",
+						taskId: "task-dead-child",
+						tmuxSession: "agentplate-nested-dead-fake",
+						state: "working",
+						pid: 999999999, // dead pid
+						parentAgent: "lead-dead-children",
+						depth: 2,
+						runId: null,
+						startedAt: new Date().toISOString(),
+						lastActivity: new Date().toISOString(),
+						escalationLevel: 0,
+						stalledSince: null,
+						transcriptPath: null,
+					},
+				]);
+
+				await worktreeCommand(["clean", "--completed", "--json"]);
+				const out = output();
+
+				const parsed = JSON.parse(out.trim()) as {
+					cleaned: string[];
+					blockedByChildren: string[];
+				};
+
+				expect(parsed.cleaned).toContain("agentplate/lead-dead-children/task-dead");
+				expect(parsed.blockedByChildren).toEqual([]);
+				expect(existsSync(wtPath)).toBe(false);
+			});
+
+			test("--force removes worktree even with live children", async () => {
+				const worktreesDir = join(tempDir, ".agentplate", "worktrees");
+				await mkdir(worktreesDir, { recursive: true });
+
+				const { path: wtPath } = await createWorktree({
+					repoRoot: tempDir,
+					baseDir: worktreesDir,
+					agentName: "lead-force",
+					baseBranch: "main",
+					taskId: "task-force-children",
+				});
+
+				writeSessionsToStore([
+					makeSession({
+						id: "session-lead-force",
+						agentName: "lead-force",
+						capability: "lead",
+						worktreePath: wtPath,
+						branchName: "agentplate/lead-force/task-force-children",
+						taskId: "task-force-children",
+						state: "completed",
+					}),
+				]);
+
+				// Use a dead pid — avoids actually killing any live process,
+				// but still exercises the --force code path.
+				writeNestedSessions(wtPath, [
+					{
+						id: "nested-force",
+						agentName: "nested-force",
+						capability: "builder",
+						worktreePath: join(wtPath, ".agentplate", "worktrees", "nested-force"),
+						branchName: "agentplate/nested-force/task-force-child",
+						taskId: "task-force-child",
+						tmuxSession: "agentplate-nested-force-fake",
+						state: "working",
+						pid: 999999999, // dead pid, safe to kill
+						parentAgent: "lead-force",
+						depth: 2,
+						runId: null,
+						startedAt: new Date().toISOString(),
+						lastActivity: new Date().toISOString(),
+						escalationLevel: 0,
+						stalledSince: null,
+						transcriptPath: null,
+					},
+				]);
+
+				await worktreeCommand(["clean", "--force", "--json"]);
+				const out = output();
+
+				const parsed = JSON.parse(out.trim()) as {
+					cleaned: string[];
+					blockedByChildren: string[];
+				};
+
+				// Should be cleaned (not blocked) even though nested sessions existed
+				expect(parsed.cleaned).toContain("agentplate/lead-force/task-force-children");
+				expect(existsSync(wtPath)).toBe(false);
+			});
+
+			test("no nested .agentplate — treated as no live children, clean proceeds", async () => {
+				const worktreesDir = join(tempDir, ".agentplate", "worktrees");
+				await mkdir(worktreesDir, { recursive: true });
+
+				const { path: wtPath } = await createWorktree({
+					repoRoot: tempDir,
+					baseDir: worktreesDir,
+					agentName: "lead-no-nested",
+					baseBranch: "main",
+					taskId: "task-no-nested",
+				});
+
+				writeSessionsToStore([
+					makeSession({
+						id: "session-lead-no-nested",
+						agentName: "lead-no-nested",
+						capability: "lead",
+						worktreePath: wtPath,
+						branchName: "agentplate/lead-no-nested/task-no-nested",
+						taskId: "task-no-nested",
+						state: "completed",
+					}),
+				]);
+
+				// No nested .agentplate/ directory written
+
+				await worktreeCommand(["clean", "--completed", "--json"]);
+				const out = output();
+
+				const parsed = JSON.parse(out.trim()) as {
+					cleaned: string[];
+					blockedByChildren: string[];
+				};
+
+				expect(parsed.cleaned).toContain("agentplate/lead-no-nested/task-no-nested");
+				expect(parsed.blockedByChildren).toEqual([]);
+				expect(existsSync(wtPath)).toBe(false);
+			});
+		});
+	});
+});
+
+describe("checkLiveChildren", () => {
+	let tempDir: string;
+
+	beforeEach(async () => {
+		tempDir = await mkdtemp(join(tmpdir(), "agentplate-checkchildren-"));
+	});
+
+	afterEach(async () => {
+		await cleanupTempDir(tempDir);
+	});
+
+	test("returns empty array when no nested .agentplate/sessions.db", async () => {
+		const result = await checkLiveChildren(tempDir);
+		expect(result).toEqual([]);
+	});
+
+	test("returns empty array when all sessions are completed", async () => {
+		const nestedAgentplate = join(tempDir, ".agentplate");
+		mkdirSync(nestedAgentplate, { recursive: true });
+		const store = createSessionStore(join(nestedAgentplate, "sessions.db"));
+		store.upsert({
+			id: "s1",
+			agentName: "done-agent",
+			capability: "builder",
+			worktreePath: "/fake/wt",
+			branchName: "agentplate/done/task",
+			taskId: "task",
+			tmuxSession: "",
+			state: "completed",
+			pid: process.pid,
+			parentAgent: null,
+			depth: 2,
+			runId: null,
+			startedAt: new Date().toISOString(),
+			lastActivity: new Date().toISOString(),
+			escalationLevel: 0,
+			stalledSince: null,
+			transcriptPath: null,
+		});
+		store.close();
+
+		const result = await checkLiveChildren(tempDir);
+		expect(result).toEqual([]);
+	});
+
+	test("returns live children when working session with alive pid exists", async () => {
+		const nestedAgentplate = join(tempDir, ".agentplate");
+		mkdirSync(nestedAgentplate, { recursive: true });
+		const store = createSessionStore(join(nestedAgentplate, "sessions.db"));
+		store.upsert({
+			id: "s1",
+			agentName: "live-agent",
+			capability: "builder",
+			worktreePath: "/fake/wt",
+			branchName: "agentplate/live/task",
+			taskId: "task",
+			tmuxSession: "",
+			state: "working",
+			pid: process.pid, // current process — alive
+			parentAgent: null,
+			depth: 2,
+			runId: null,
+			startedAt: new Date().toISOString(),
+			lastActivity: new Date().toISOString(),
+			escalationLevel: 0,
+			stalledSince: null,
+			transcriptPath: null,
+		});
+		store.close();
+
+		const result = await checkLiveChildren(tempDir);
+		expect(result).toHaveLength(1);
+		expect(result[0]?.agentName).toBe("live-agent");
+		expect(result[0]?.pid).toBe(process.pid);
+	});
+});