@ag-eco/agentplate-cli 0.13.0

package/src/doctor/watchdog.test.ts

@@ -0,0 +1,167 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { utimes } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { AgentplateConfig } from "../types.ts";
+import { checkWatchdog } from "./watchdog.ts";
+
+describe("checkWatchdog", () => {
+	let tempDir: string;
+	let mockConfig: AgentplateConfig;
+
+	beforeEach(() => {
+		tempDir = mkdtempSync(join(tmpdir(), "agentplate-watchdog-test-"));
+		mockConfig = {
+			project: { name: "test", root: tempDir, canonicalBranch: "main" },
+			agents: {
+				manifestPath: "",
+				baseDir: "",
+				maxConcurrent: 5,
+				staggerDelayMs: 100,
+				maxDepth: 2,
+				maxSessionsPerRun: 0,
+				maxAgentsPerLead: 5,
+			},
+			worktrees: { baseDir: "" },
+			taskTracker: { backend: "auto", enabled: true },
+			loam: { enabled: true, domains: [], primeFormat: "markdown" },
+			merge: { aiResolveEnabled: false, reimagineEnabled: false },
+			providers: {
+				anthropic: { type: "native" },
+			},
+			watchdog: {
+				tier0Enabled: true,
+				tier0IntervalMs: 30000,
+				tier1Enabled: false,
+				tier2Enabled: false,
+				staleThresholdMs: 300000,
+				zombieThresholdMs: 600000,
+				nudgeIntervalMs: 60000,
+			},
+			models: {},
+			logging: { verbose: false, redactSecrets: true },
+		};
+	});
+
+	afterEach(() => {
+		rmSync(tempDir, { recursive: true, force: true });
+	});
+
+	test("all checks skip when tier0Enabled is false — returns single pass check", async () => {
+		mockConfig.watchdog.tier0Enabled = false;
+		const checks = await checkWatchdog(mockConfig, tempDir);
+
+		expect(checks).toHaveLength(1);
+		expect(checks[0]?.status).toBe("pass");
+		expect(checks[0]?.message).toContain("disabled");
+	});
+
+	test("PID file missing — returns warn about daemon not running", async () => {
+		const checks = await checkWatchdog(mockConfig, tempDir);
+
+		const pidCheck = checks.find((c) => c.name === "watchdog pid file");
+		expect(pidCheck).toBeDefined();
+		expect(pidCheck?.status).toBe("warn");
+		expect(pidCheck?.message).toContain("PID file not found");
+	});
+
+	test("PID file corrupted — returns fail with fixable", async () => {
+		writeFileSync(join(tempDir, "watchdog.pid"), "not-a-pid");
+		const checks = await checkWatchdog(mockConfig, tempDir);
+
+		const integrityCheck = checks.find((c) => c.name === "watchdog pid integrity");
+		expect(integrityCheck).toBeDefined();
+		expect(integrityCheck?.status).toBe("fail");
+		expect(integrityCheck?.fixable).toBe(true);
+		expect(integrityCheck?.details?.some((d) => d.includes("not-a-pid"))).toBe(true);
+	});
+
+	test("PID file with valid PID but process not running — returns warn (stale PID)", async () => {
+		// PID 999999999 is extremely unlikely to exist
+		writeFileSync(join(tempDir, "watchdog.pid"), "999999999");
+		const checks = await checkWatchdog(mockConfig, tempDir);
+
+		const processCheck = checks.find((c) => c.name === "watchdog process");
+		expect(processCheck).toBeDefined();
+		expect(processCheck?.status).toBe("warn");
+		expect(processCheck?.message).toContain("stale PID file");
+		expect(processCheck?.fixable).toBe(true);
+	});
+
+	test("PID file with current process PID — returns pass", async () => {
+		writeFileSync(join(tempDir, "watchdog.pid"), String(process.pid));
+		const checks = await checkWatchdog(mockConfig, tempDir);
+
+		const processCheck = checks.find((c) => c.name === "watchdog process");
+		expect(processCheck).toBeDefined();
+		expect(processCheck?.status).toBe("pass");
+		expect(processCheck?.message).toContain("running");
+	});
+
+	test("PID file older than 24 hours — returns staleness warn", async () => {
+		const pidFile = join(tempDir, "watchdog.pid");
+		writeFileSync(pidFile, String(process.pid));
+
+		// Set mtime 25 hours ago
+		const twentyFiveHoursAgo = new Date(Date.now() - 25 * 60 * 60 * 1000);
+		await utimes(pidFile, twentyFiveHoursAgo, twentyFiveHoursAgo);
+
+		const checks = await checkWatchdog(mockConfig, tempDir);
+
+		const stalenessCheck = checks.find((c) => c.name === "watchdog pid staleness");
+		expect(stalenessCheck).toBeDefined();
+		expect(stalenessCheck?.status).toBe("warn");
+		expect(stalenessCheck?.message).toContain("older than 24 hours");
+		expect(stalenessCheck?.details?.some((d) => d.includes("hours"))).toBe(true);
+	});
+
+	test("Tier 2 monitor check skipped when tier2Enabled=false — no monitor check in results", async () => {
+		mockConfig.watchdog.tier2Enabled = false;
+		writeFileSync(join(tempDir, "watchdog.pid"), String(process.pid));
+		const checks = await checkWatchdog(mockConfig, tempDir);
+
+		const monitorCheck = checks.find((c) => c.name === "tier2 monitor");
+		expect(monitorCheck).toBeUndefined();
+	});
+
+	test("Tier 1 triage check skipped when tier1Enabled=false — no triage check in results", async () => {
+		mockConfig.watchdog.tier1Enabled = false;
+		writeFileSync(join(tempDir, "watchdog.pid"), String(process.pid));
+		const checks = await checkWatchdog(mockConfig, tempDir);
+
+		const triageCheck = checks.find((c) => c.name === "tier1 triage");
+		expect(triageCheck).toBeUndefined();
+	});
+
+	test("Tier 2 monitor check warns when no monitor session found", async () => {
+		mockConfig.watchdog.tier2Enabled = true;
+		writeFileSync(join(tempDir, "watchdog.pid"), String(process.pid));
+		// No sessions.db or sessions.json — openSessionStore creates empty DB
+		const checks = await checkWatchdog(mockConfig, tempDir);
+
+		const monitorCheck = checks.find((c) => c.name === "tier2 monitor");
+		expect(monitorCheck).toBeDefined();
+		// Either warns about not running or store unavailable — both are acceptable
+		expect(monitorCheck?.status).toBe("warn");
+	});
+
+	test("Tier 1 triage check does not crash when enabled", async () => {
+		mockConfig.watchdog.tier1Enabled = true;
+		writeFileSync(join(tempDir, "watchdog.pid"), String(process.pid));
+		// getRuntime will succeed (defaults to "claude" which is always registered)
+		let checks: Awaited<ReturnType<typeof checkWatchdog>>;
+		try {
+			checks = await checkWatchdog(mockConfig, tempDir);
+		} catch {
+			// Should not throw
+			expect(false).toBe(true);
+			return;
+		}
+
+		const triageCheck = checks.find((c) => c.name === "tier1 triage");
+		expect(triageCheck).toBeDefined();
+		// Either pass or warn — depending on environment; it should not throw
+		expect(triageCheck?.status === "pass" || triageCheck?.status === "warn").toBe(true);
+	});
+});

package/src/doctor/watchdog.ts

@@ -0,0 +1,214 @@
+import { existsSync } from "node:fs";
+import { stat, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { getRuntime } from "../runtimes/registry.ts";
+import { openSessionStore } from "../sessions/compat.ts";
+import { findRunningWatchdogProcesses } from "../utils/process-scan.ts";
+import { isProcessRunning } from "../watchdog/health.ts";
+import type { DoctorCheck, DoctorCheckFn } from "./types.ts";
+
+/**
+ * Watchdog subsystem health checks.
+ * Validates PID file integrity, process liveness, and tier availability.
+ */
+export const checkWatchdog: DoctorCheckFn = async (
+	config,
+	agentplateDir,
+): Promise<DoctorCheck[]> => {
+	const checks: DoctorCheck[] = [];
+
+	// If tier0 is disabled, skip all checks with a single pass result
+	if (!config.watchdog.tier0Enabled) {
+		checks.push({
+			name: "watchdog disabled",
+			category: "watchdog",
+			status: "pass",
+			message: "Watchdog daemon is disabled (tier0Enabled: false)",
+		});
+		return checks;
+	}
+
+	const pidFilePath = join(agentplateDir, "watchdog.pid");
+
+	// Check 1: PID file exists and is readable
+	if (!existsSync(pidFilePath)) {
+		checks.push({
+			name: "watchdog pid file",
+			category: "watchdog",
+			status: "warn",
+			message: "Watchdog PID file not found — daemon may not be running",
+		});
+	} else {
+		// Check 2: PID file not corrupted
+		const pidText = await Bun.file(pidFilePath).text();
+		const pid = Number.parseInt(pidText.trim(), 10);
+
+		if (Number.isNaN(pid) || pid <= 0) {
+			checks.push({
+				name: "watchdog pid integrity",
+				category: "watchdog",
+				status: "fail",
+				message: "Watchdog PID file is corrupted",
+				details: [`Raw content: ${pidText.trim()}`],
+				fixable: true,
+				fix: async () => {
+					await unlink(pidFilePath);
+					return ["Removed corrupted watchdog PID file"];
+				},
+			});
+		} else {
+			// Check 3: PID alive via isProcessRunning()
+			const alive = isProcessRunning(pid);
+			if (!alive) {
+				checks.push({
+					name: "watchdog process",
+					category: "watchdog",
+					status: "warn",
+					message: "Watchdog process is not running (stale PID file)",
+					details: [`PID: ${pid}`],
+					fixable: true,
+					fix: async () => {
+						await unlink(pidFilePath);
+						return ["Removed stale watchdog PID file"];
+					},
+				});
+			} else {
+				checks.push({
+					name: "watchdog process",
+					category: "watchdog",
+					status: "pass",
+					message: "Watchdog daemon is running",
+				});
+			}
+
+			// Check 4: PID file staleness > 24h
+			const fileStat = await stat(pidFilePath);
+			const ageMs = Date.now() - fileStat.mtimeMs;
+			const twentyFourHoursMs = 24 * 60 * 60 * 1000;
+			if (ageMs > twentyFourHoursMs) {
+				const ageHours = Math.round(ageMs / (1000 * 60 * 60));
+				checks.push({
+					name: "watchdog pid staleness",
+					category: "watchdog",
+					status: "warn",
+					message: "Watchdog PID file is older than 24 hours",
+					details: [`File age: ${ageHours} hours`],
+				});
+			}
+		}
+	}
+
+	// Check 5: Tier 2 monitor running if tier2Enabled
+	if (config.watchdog.tier2Enabled) {
+		try {
+			const { store } = openSessionStore(agentplateDir);
+			try {
+				const sessions = store.getAll();
+				const monitorActive = sessions.some(
+					(s) => s.capability === "monitor" && s.state !== "completed" && s.state !== "zombie",
+				);
+				if (!monitorActive) {
+					checks.push({
+						name: "tier2 monitor",
+						category: "watchdog",
+						status: "warn",
+						message: "Tier 2 monitor is enabled but not running",
+					});
+				} else {
+					checks.push({
+						name: "tier2 monitor",
+						category: "watchdog",
+						status: "pass",
+						message: "Tier 2 monitor agent is active",
+					});
+				}
+			} finally {
+				store.close();
+			}
+		} catch {
+			checks.push({
+				name: "tier2 monitor",
+				category: "watchdog",
+				status: "warn",
+				message: "Tier 2 monitor check skipped — session store unavailable",
+			});
+		}
+	}
+
+	// Check 6: multi-daemon detection (agentplate-8ef6).
+	// Earlier releases had no exclusion lock, so multiple `ap watch` daemons
+	// could run simultaneously. We scan the process table for `ap watch`
+	// processes and flag any case with more than one. This is observational —
+	// even with the lock now in place, a corrupted/missing PID file could
+	// still let a foreign daemon slip past, and we want doctor to catch it.
+	try {
+		const watchProcs = await findRunningWatchdogProcesses();
+		if (watchProcs.length > 1) {
+			const lockOwner = existsSync(pidFilePath)
+				? Number.parseInt((await Bun.file(pidFilePath).text()).trim(), 10)
+				: Number.NaN;
+			const lockOwnerLabel = Number.isFinite(lockOwner) ? `${lockOwner}` : "(none)";
+			const pidList = watchProcs.map((p) => p.pid).join(", ");
+			checks.push({
+				name: "watchdog multi-daemon",
+				category: "watchdog",
+				status: "fail",
+				message: `${watchProcs.length} 'ap watch' daemons running concurrently — only one should be live`,
+				details: [
+					`Live PIDs: ${pidList}`,
+					`PID-file owner: ${lockOwnerLabel}`,
+					"Run 'ap watch --kill-others' to terminate the foreign daemons.",
+				],
+				fixable: true,
+				fix: async () => {
+					const ownerPid = Number.isFinite(lockOwner) ? lockOwner : null;
+					const messages: string[] = [];
+					for (const proc of watchProcs) {
+						if (proc.pid === ownerPid) continue;
+						try {
+							process.kill(proc.pid, "SIGTERM");
+							messages.push(`Killed foreign watchdog PID ${proc.pid}`);
+						} catch {
+							messages.push(`PID ${proc.pid} already gone`);
+						}
+					}
+					if (messages.length === 0) {
+						messages.push("No foreign watchdogs to kill — fix is a no-op");
+					}
+					return messages;
+				},
+			});
+		}
+	} catch {
+		// Process scan failure is non-fatal — leave a soft warning instead of
+		// failing the whole doctor run.
+		checks.push({
+			name: "watchdog multi-daemon",
+			category: "watchdog",
+			status: "warn",
+			message: "Could not scan process table for foreign 'ap watch' daemons",
+		});
+	}
+
+	// Check 7: Tier 1 triage available if tier1Enabled
+	if (config.watchdog.tier1Enabled) {
+		try {
+			getRuntime(config?.runtime?.printCommand ?? config?.runtime?.default, config);
+			checks.push({
+				name: "tier1 triage",
+				category: "watchdog",
+				status: "pass",
+				message: "Tier 1 triage runtime is available",
+			});
+		} catch {
+			checks.push({
+				name: "tier1 triage",
+				category: "watchdog",
+				status: "warn",
+				message: "Tier 1 triage is enabled but runtime is not available",
+			});
+		}
+	}
+
+	return checks;
+};

package/src/e2e/init-sling-lifecycle.test.ts

@@ -0,0 +1,283 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { createManifestLoader } from "../agents/manifest.ts";
+import { writeOverlay } from "../agents/overlay.ts";
+import type { Spawner } from "../commands/init.ts";
+import { initCommand } from "../commands/init.ts";
+import { loadConfig } from "../config.ts";
+import { cleanupTempDir, createTempGitRepo } from "../test-helpers.ts";
+import type { OverlayConfig } from "../types.ts";
+
+/**
+ * E2E test: init→sling lifecycle on a throwaway external project.
+ *
+ * Validates the "project-agnostic" promise by running agentplate init on a
+ * fresh temp git repo (NOT the agentplate repo itself), then verifying all
+ * artifacts, loading config + manifest via real APIs, and generating an overlay.
+ *
+ * Uses real filesystem and real git repos.
+ * Uses a no-op spawner so ecosystem CLIs (lm/sr/tl) don't need to be installed in CI.
+ * Suppresses stdout because initCommand prints status lines.
+ */
+
+/** No-op spawner that treats all ecosystem tools as "not installed". */
+const noopSpawner: Spawner = async () => ({ exitCode: 1, stdout: "", stderr: "not found" });
+
+const EXPECTED_AGENT_DEFS = [
+	"builder.md",
+	"coordinator.md",
+	"lead.md",
+	"merger.md",
+	"monitor.md",
+	"orchestrator.md",
+	"ap-co-creation.md",
+	"reviewer.md",
+	"scout.md",
+];
+
+describe("E2E: init→sling lifecycle on external project", () => {
+	let tempDir: string;
+	let originalCwd: string;
+	let originalWrite: typeof process.stdout.write;
+
+	beforeEach(async () => {
+		tempDir = await createTempGitRepo();
+		originalCwd = process.cwd();
+		process.chdir(tempDir);
+
+		// Suppress stdout noise from initCommand
+		originalWrite = process.stdout.write;
+		process.stdout.write = (() => true) as typeof process.stdout.write;
+	});
+
+	afterEach(async () => {
+		process.chdir(originalCwd);
+		process.stdout.write = originalWrite;
+		await cleanupTempDir(tempDir);
+	});
+
+	test("init creates all expected artifacts", async () => {
+		await initCommand({ _spawner: noopSpawner });
+
+		const agentplateDir = join(tempDir, ".agentplate");
+
+		// config.yaml exists
+		const configFile = Bun.file(join(agentplateDir, "config.yaml"));
+		expect(await configFile.exists()).toBe(true);
+
+		// agent-manifest.json exists and is valid JSON
+		const manifestFile = Bun.file(join(agentplateDir, "agent-manifest.json"));
+		expect(await manifestFile.exists()).toBe(true);
+		const manifestText = await manifestFile.text();
+		const manifestJson = JSON.parse(manifestText);
+		expect(manifestJson).toBeDefined();
+		expect(manifestJson.version).toBe("1.0");
+		expect(typeof manifestJson.agents).toBe("object");
+
+		// hooks.json exists
+		const hooksFile = Bun.file(join(agentplateDir, "hooks.json"));
+		expect(await hooksFile.exists()).toBe(true);
+
+		// .gitignore exists
+		const gitignoreFile = Bun.file(join(agentplateDir, ".gitignore"));
+		expect(await gitignoreFile.exists()).toBe(true);
+
+		// agent-defs/ contains all 9 agent definition files (supervisor deprecated)
+		const agentDefsDir = join(agentplateDir, "agent-defs");
+		const agentDefFiles = (await readdir(agentDefsDir)).filter((f) => f.endsWith(".md")).sort();
+		expect(agentDefFiles).toEqual(EXPECTED_AGENT_DEFS);
+
+		// Required subdirectories exist
+		const expectedDirs = ["agents", "worktrees", "specs", "logs"];
+		for (const dirName of expectedDirs) {
+			const dirPath = join(agentplateDir, dirName);
+			const dirStat = await stat(dirPath);
+			expect(dirStat.isDirectory()).toBe(true);
+		}
+	});
+
+	test("loadConfig returns valid config pointing to temp dir", async () => {
+		await initCommand({ _spawner: noopSpawner });
+
+		const config = await loadConfig(tempDir);
+
+		// project.root should point to the temp directory
+		expect(config.project.root).toBe(tempDir);
+
+		// agents.baseDir should be the relative path to agent-defs
+		expect(config.agents.baseDir).toBe(".agentplate/agent-defs");
+
+		// canonicalBranch should be detected (main for our test repos)
+		expect(config.project.canonicalBranch).toBeTruthy();
+
+		// name should be set (from dir basename or git remote)
+		expect(config.project.name).toBeTruthy();
+	});
+
+	test("manifest loads successfully with all 8 agents (supervisor deprecated)", async () => {
+		await initCommand({ _spawner: noopSpawner });
+
+		const manifestPath = join(tempDir, ".agentplate", "agent-manifest.json");
+		const agentDefsDir = join(tempDir, ".agentplate", "agent-defs");
+		const loader = createManifestLoader(manifestPath, agentDefsDir);
+
+		const manifest = await loader.load();
+
+		// All 8 agents present (supervisor removed: deprecated, use lead instead)
+		const agentNames = Object.keys(manifest.agents).sort();
+		expect(agentNames).toEqual([
+			"builder",
+			"coordinator",
+			"lead",
+			"merger",
+			"monitor",
+			"orchestrator",
+			"reviewer",
+			"scout",
+		]);
+
+		// Each agent has a valid file reference
+		for (const [_name, def] of Object.entries(manifest.agents)) {
+			expect(def.file).toEndWith(".md");
+			// Verify the referenced .md file actually exists
+			const mdFile = Bun.file(join(agentDefsDir, def.file));
+			expect(await mdFile.exists()).toBe(true);
+		}
+
+		// Validation returns no errors
+		const errors = loader.validate();
+		expect(errors).toEqual([]);
+	});
+
+	test("manifest capability index is consistent", async () => {
+		await initCommand({ _spawner: noopSpawner });
+
+		const manifestPath = join(tempDir, ".agentplate", "agent-manifest.json");
+		const agentDefsDir = join(tempDir, ".agentplate", "agent-defs");
+		const loader = createManifestLoader(manifestPath, agentDefsDir);
+
+		const manifest = await loader.load();
+
+		// capabilityIndex should map capabilities to agent names
+		expect(Object.keys(manifest.capabilityIndex).length).toBeGreaterThan(0);
+
+		// Each capability in the index should reference agents that declare it
+		for (const [cap, names] of Object.entries(manifest.capabilityIndex)) {
+			for (const name of names) {
+				const agent = manifest.agents[name];
+				expect(agent).toBeDefined();
+				expect(agent?.capabilities).toContain(cap);
+			}
+		}
+	});
+
+	test("overlay generation works for external project", async () => {
+		await initCommand({ _spawner: noopSpawner });
+
+		const agentDefsDir = join(tempDir, ".agentplate", "agent-defs");
+		const baseDefinition = await Bun.file(join(agentDefsDir, "builder.md")).text();
+
+		const overlayConfig: OverlayConfig = {
+			agentName: "test-agent",
+			taskId: "test-bead-001",
+			specPath: null,
+			branchName: "agentplate/test-agent/test-bead-001",
+			worktreePath: join(tempDir, ".agentplate", "worktrees", "test-agent"),
+			fileScope: [],
+			loamDomains: [],
+			parentAgent: null,
+			depth: 0,
+			canSpawn: false,
+			capability: "builder",
+			baseDefinition,
+		};
+
+		// Write the overlay into a subdirectory of the temp dir (simulating a worktree)
+		const worktreePath = join(tempDir, ".agentplate", "worktrees", "test-agent");
+		const { mkdir } = await import("node:fs/promises");
+		await mkdir(worktreePath, { recursive: true });
+
+		await writeOverlay(worktreePath, overlayConfig, tempDir);
+
+		// Verify the overlay was written
+		const overlayPath = join(worktreePath, ".claude", "CLAUDE.md");
+		const overlayFile = Bun.file(overlayPath);
+		expect(await overlayFile.exists()).toBe(true);
+
+		const content = await overlayFile.text();
+
+		// Verify template placeholders were replaced
+		expect(content).toContain("test-agent");
+		expect(content).toContain("test-bead-001");
+		expect(content).toContain("agentplate/test-agent/test-bead-001");
+		expect(content).not.toContain("{{AGENT_NAME}}");
+		expect(content).not.toContain("{{BEAD_ID}}");
+		expect(content).not.toContain("{{BRANCH_NAME}}");
+	});
+
+	test("full init→config→manifest→overlay pipeline succeeds", async () => {
+		// This test validates the entire lifecycle in sequence:
+		// init → load config → load manifest → generate overlay
+
+		// Step 1: Init
+		await initCommand({ _spawner: noopSpawner });
+
+		// Step 2: Load config
+		const config = await loadConfig(tempDir);
+		expect(config.project.root).toBe(tempDir);
+
+		// Step 3: Load manifest using config paths
+		const manifestPath = join(config.project.root, config.agents.manifestPath);
+		const agentDefsDir = join(config.project.root, config.agents.baseDir);
+		const loader = createManifestLoader(manifestPath, agentDefsDir);
+		await loader.load();
+
+		// Verify builder agent exists (the one we'll use for overlay)
+		const builder = loader.getAgent("builder");
+		expect(builder).toBeDefined();
+		expect(builder?.canSpawn).toBe(false);
+
+		// Verify lead agent can spawn
+		const lead = loader.getAgent("lead");
+		expect(lead).toBeDefined();
+		expect(lead?.canSpawn).toBe(true);
+
+		// Step 4: Generate overlay using a realistic config
+		const builderDef = await Bun.file(join(agentDefsDir, "builder.md")).text();
+		const overlayConfig: OverlayConfig = {
+			agentName: "lifecycle-builder",
+			taskId: "lifecycle-001",
+			specPath: join(tempDir, ".agentplate", "specs", "lifecycle-001.md"),
+			branchName: "agentplate/lifecycle-builder/lifecycle-001",
+			worktreePath: join(tempDir, ".agentplate", "worktrees", "lifecycle-builder"),
+			fileScope: ["src/main.ts", "src/utils.ts"],
+			loamDomains: ["typescript"],
+			parentAgent: "orchestrator",
+			depth: 0,
+			canSpawn: false,
+			capability: "builder",
+			baseDefinition: builderDef,
+		};
+
+		const worktreePath = join(tempDir, ".agentplate", "worktrees", "lifecycle-builder");
+		const { mkdir } = await import("node:fs/promises");
+		await mkdir(worktreePath, { recursive: true });
+
+		await writeOverlay(worktreePath, overlayConfig, tempDir);
+
+		const overlayContent = await Bun.file(join(worktreePath, ".claude", "CLAUDE.md")).text();
+
+		// Verify all overlay fields rendered correctly
+		expect(overlayContent).toContain("lifecycle-builder");
+		expect(overlayContent).toContain("lifecycle-001");
+		expect(overlayContent).toContain("agentplate/lifecycle-builder/lifecycle-001");
+		expect(overlayContent).toContain("orchestrator");
+		expect(overlayContent).toContain("`src/main.ts`");
+		expect(overlayContent).toContain("`src/utils.ts`");
+		expect(overlayContent).toContain("lm prime typescript");
+
+		// No unresolved placeholders
+		expect(overlayContent).not.toMatch(/\{\{[A-Z_]+\}\}/);
+	});
+});