@ag-eco/agentplate-cli 0.13.0

package/src/commands/watch.test.ts

@@ -0,0 +1,257 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { cleanupTempDir } from "../test-helpers.ts";
+import type { HealthCheck } from "../types.ts";
+import { formatCheck, watchCommand } from "./watch.ts";
+
+/**
+ * Tests for `agentplate watch` command.
+ *
+ * IMPORTANT: We CANNOT test the actual daemon loop (it would hang the test).
+ * Focus on:
+ * - Help output (safe, returns immediately)
+ * - Background mode: already-running detection
+ * - Background mode: stale PID cleanup
+ *
+ * We do NOT test:
+ * - Foreground mode (blocks forever with await new Promise(() => {}))
+ * - Actual health check loop behavior
+ */
+
+describe("watchCommand", () => {
+	let chunks: string[];
+	let stderrChunks: string[];
+	let originalWrite: typeof process.stdout.write;
+	let originalStderrWrite: typeof process.stderr.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;
+
+		// Spy on stderr
+		stderrChunks = [];
+		originalStderrWrite = process.stderr.write;
+		process.stderr.write = ((chunk: string) => {
+			stderrChunks.push(chunk);
+			return true;
+		}) as typeof process.stderr.write;
+
+		process.exitCode = 0;
+
+		// Create temp dir with .agentplate/config.yaml structure
+		tempDir = await mkdtemp(join(tmpdir(), "watch-test-"));
+		const agentplateDir = join(tempDir, ".agentplate");
+		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.stderr.write = originalStderrWrite;
+		// Unconditionally clear to 0 rather than restoring a captured "original" that
+		// could itself have been polluted by a parallel test file in the same bun
+		// process. `watchCommand` sets `process.exitCode = 1` as a side effect, so
+		// without this clear the 1 can leak all the way to bun test's shutdown and
+		// turn a fully-green run into exit 1.
+		process.exitCode = 0;
+		process.chdir(originalCwd);
+		await cleanupTempDir(tempDir);
+	});
+
+	function output(): string {
+		return chunks.join("");
+	}
+
+	function stderr(): string {
+		return stderrChunks.join("");
+	}
+
+	test("--help flag shows help text with key info", async () => {
+		await watchCommand(["--help"]);
+		const out = output();
+
+		expect(out).toContain("watch");
+		expect(out).toContain("--interval");
+		expect(out).toContain("--background");
+		expect(out).toContain("--kill-others");
+		expect(out).toContain("Tier 0");
+	});
+
+	test("-h flag shows help text", async () => {
+		await watchCommand(["-h"]);
+		const out = output();
+
+		expect(out).toContain("watch");
+		expect(out).toContain("Tier 0");
+	});
+
+	test("background mode: already running detection", async () => {
+		// Write a PID file with a running process (use our own PID)
+		const pidFilePath = join(tempDir, ".agentplate", "watchdog.pid");
+		await Bun.write(pidFilePath, `${process.pid}\n`);
+
+		// Try to start in background mode — should fail with "already running"
+		await watchCommand(["--background"]);
+
+		const err = stderr();
+		expect(err).toContain("already running");
+		expect(err).toContain(`${process.pid}`);
+		expect(process.exitCode).toBe(1);
+	});
+
+	test("foreground mode: refuses when a live foreign PID owns the lock", async () => {
+		// Spawn a long-running child to act as the "foreign live process". Its
+		// PID will not match our own, so acquirePidLock should refuse rather
+		// than treat the existing PID as idempotent self-ownership. The
+		// foreground path used to overwrite this file unconditionally — the
+		// agentplate-8ef6 fix forces it to refuse.
+		const sleeper = Bun.spawn(["sleep", "30"], {
+			stdout: "ignore",
+			stderr: "ignore",
+		});
+		try {
+			const pidFilePath = join(tempDir, ".agentplate", "watchdog.pid");
+			await Bun.write(pidFilePath, `${sleeper.pid}\n`);
+
+			// --json for structured output. No --background, so this exercises
+			// the foreground exclusion path. A correctly contested lock returns
+			// immediately (exit 1) without starting the daemon loop.
+			await watchCommand(["--json"]);
+
+			const out = output();
+			const jsonLine = out
+				.split("\n")
+				.map((l) => l.trim())
+				.find((l) => l.startsWith("{"));
+			expect(jsonLine).toBeDefined();
+			if (jsonLine) {
+				const parsed = JSON.parse(jsonLine);
+				expect(parsed.running).toBe(true);
+				expect(parsed.pid).toBe(sleeper.pid);
+				expect(parsed.error).toContain("already running");
+			}
+			expect(process.exitCode).toBe(1);
+
+			// PID file untouched — still the foreign owner's PID.
+			const fileContent = await Bun.file(pidFilePath).text();
+			expect(fileContent.trim()).toBe(`${sleeper.pid}`);
+		} finally {
+			sleeper.kill("SIGTERM");
+			await sleeper.exited.catch(() => {});
+		}
+	});
+
+	test("background mode: stale PID cleanup", async () => {
+		// Write a PID file with a non-running process (999999 is very unlikely to exist)
+		const pidFilePath = join(tempDir, ".agentplate", "watchdog.pid");
+		await Bun.write(pidFilePath, "999999\n");
+
+		// Verify the stale PID file exists before the test
+		const fileBeforeExists = await Bun.file(pidFilePath).exists();
+		expect(fileBeforeExists).toBe(true);
+
+		// Try to start in background mode
+		// This will clean up the stale PID file, then attempt to spawn.
+		// The spawn will fail because there's no real agentplate binary in test env,
+		// but the important part is that the stale PID file gets removed.
+		try {
+			await watchCommand(["--background"]);
+		} catch {
+			// Expected to fail when trying to spawn — that's OK
+		}
+
+		// The stale PID file should have been removed during the check
+		// (Even if the spawn itself failed, the cleanup happens before spawn)
+		// Actually, looking at the code: if existingPid is not null but not running,
+		// it removes the PID file. Then it tries to spawn. So the file should be gone
+		// OR replaced with a new PID.
+
+		// Let's check: the file should either not exist, OR contain a different PID
+		const fileAfterExists = await Bun.file(pidFilePath).exists();
+		if (fileAfterExists) {
+			const content = await Bun.file(pidFilePath).text();
+			expect(content.trim()).not.toBe("999999");
+		}
+		// If it doesn't exist, that's also valid (spawn failed before writing new PID)
+	});
+});
+
+describe("formatCheck", () => {
+	function makeCheck(overrides: Partial<HealthCheck>): HealthCheck {
+		return {
+			agentName: "test-agent",
+			timestamp: new Date().toISOString(),
+			processAlive: true,
+			tmuxAlive: true,
+			pidAlive: true,
+			lastActivity: new Date().toISOString(),
+			state: "working",
+			action: "none",
+			reconciliationNote: null,
+			...overrides,
+		};
+	}
+
+	test("terminate action uses x icon", () => {
+		const result = formatCheck(makeCheck({ action: "terminate" }));
+		expect(result).toMatch(/^x /);
+	});
+
+	test("escalate action uses ! icon", () => {
+		const result = formatCheck(makeCheck({ action: "escalate" }));
+		expect(result).toMatch(/^! /);
+	});
+
+	test("investigate action uses > icon", () => {
+		const result = formatCheck(makeCheck({ action: "investigate" }));
+		expect(result).toMatch(/^> /);
+	});
+
+	test("pidAlive true shows up", () => {
+		const result = formatCheck(makeCheck({ pidAlive: true }));
+		expect(result).toContain("pid=up");
+	});
+
+	test("pidAlive false shows down", () => {
+		const result = formatCheck(makeCheck({ pidAlive: false }));
+		expect(result).toContain("pid=down");
+	});
+
+	test("pidAlive null shows n/a", () => {
+		const result = formatCheck(makeCheck({ pidAlive: null }));
+		expect(result).toContain("pid=n/a");
+	});
+
+	test("includes reconciliation note when present", () => {
+		const result = formatCheck(makeCheck({ reconciliationNote: "stale session" }));
+		expect(result).toContain("[stale session]");
+	});
+
+	test("no reconciliation note brackets when null", () => {
+		const result = formatCheck(makeCheck({ reconciliationNote: null }));
+		expect(result).not.toContain("[");
+	});
+
+	test("includes agent name and state", () => {
+		const result = formatCheck(makeCheck({ agentName: "builder-1", state: "stalled" }));
+		expect(result).toContain("builder-1");
+		expect(result).toContain("stalled");
+	});
+});
+
+// PID and bin utility tests moved to src/utils/pid.test.ts and src/utils/bin.test.ts

package/src/commands/watch.ts

@@ -0,0 +1,308 @@
+/**
+ * CLI command: agentplate watch [--interval <ms>] [--background]
+ *
+ * Starts the Tier 0 mechanical watchdog daemon. Foreground mode shows real-time status.
+ * Background mode spawns a detached process via Bun.spawn and writes a PID file.
+ * Interval configurable, default 30000ms.
+ */
+
+import { join } from "node:path";
+import { Command } from "commander";
+import { loadConfig } from "../config.ts";
+import { jsonOutput } from "../json.ts";
+import { printError, printHint, printSuccess } from "../logging/color.ts";
+import type { HealthCheck } from "../types.ts";
+import { resolveAgentplateBin } from "../utils/bin.ts";
+import {
+	type AcquirePidLockResult,
+	acquirePidLock,
+	readPidFile,
+	removePidFile,
+} from "../utils/pid.ts";
+import { findRunningWatchdogProcesses, type WatchdogProcess } from "../utils/process-scan.ts";
+import { startDaemon } from "../watchdog/daemon.ts";
+import { isProcessRunning } from "../watchdog/health.ts";
+
+/**
+ * Format a health check for display.
+ * @internal Exported for testing.
+ */
+export function formatCheck(check: HealthCheck): string {
+	const actionIcon =
+		check.action === "terminate"
+			? "x"
+			: check.action === "escalate"
+				? "!"
+				: check.action === "investigate"
+					? ">"
+					: "x";
+	const pidLabel = check.pidAlive === null ? "n/a" : check.pidAlive ? "up" : "down";
+	let line = `${actionIcon} ${check.agentName}: ${check.state} (tmux=${check.tmuxAlive ? "up" : "down"}, pid=${pidLabel})`;
+	if (check.reconciliationNote) {
+		line += ` [${check.reconciliationNote}]`;
+	}
+	return line;
+}
+
+/**
+ * Format a "lock contested" error consistently across foreground/background.
+ */
+function formatLockContestedError(existingPid: number, pidFilePath: string): string {
+	if (existingPid <= 0) {
+		return `Watchdog PID file at ${pidFilePath} is owned by another process (could not read PID). Run 'ap watch --kill-others' or remove the file.`;
+	}
+	return `Watchdog already running (PID: ${existingPid}). Kill it first, run 'ap watch --kill-others', or remove ${pidFilePath}`;
+}
+
+/**
+ * Kill running `ap watch` daemons that are NOT the given excludedPid.
+ * Returns the list of PIDs killed (after a SIGTERM was issued — not waited).
+ */
+async function killForeignWatchdogs(
+	excludedPid: number | null,
+): Promise<{ killed: number[]; surveyed: WatchdogProcess[] }> {
+	const surveyed = await findRunningWatchdogProcesses();
+	const killed: number[] = [];
+	for (const proc of surveyed) {
+		if (excludedPid !== null && proc.pid === excludedPid) {
+			continue;
+		}
+		try {
+			process.kill(proc.pid, "SIGTERM");
+			killed.push(proc.pid);
+		} catch {
+			// Process already gone — not an error.
+		}
+	}
+	return { killed, surveyed };
+}
+
+/**
+ * Core implementation for the watch command.
+ */
+async function runWatch(opts: {
+	interval?: string;
+	background?: boolean;
+	json?: boolean;
+	killOthers?: boolean;
+}): Promise<void> {
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+
+	const intervalMs = opts.interval
+		? Number.parseInt(opts.interval, 10)
+		: config.watchdog.tier0IntervalMs;
+
+	const staleThresholdMs = config.watchdog.staleThresholdMs;
+	const zombieThresholdMs = config.watchdog.zombieThresholdMs;
+	const pidFilePath = join(config.project.root, ".agentplate", "watchdog.pid");
+
+	const useJson = opts.json ?? false;
+
+	// --kill-others: kill any pre-existing `ap watch` daemons before claiming
+	// the lock. Useful when an earlier release allowed multi-daemon state.
+	if (opts.killOthers) {
+		const { killed } = await killForeignWatchdogs(null);
+
+		// Wait for the just-killed processes to actually exit before reclaiming
+		// the PID file. Without this, the next acquirePidLock call sees a still-
+		// alive PID in the file and refuses, even though we issued SIGTERM
+		// nanoseconds earlier. Poll for up to ~2s.
+		const killedSet = new Set(killed);
+		if (killedSet.size > 0) {
+			const deadline = Date.now() + 2000;
+			while (Date.now() < deadline) {
+				const stillAlive = killed.filter((p) => isProcessRunning(p));
+				if (stillAlive.length === 0) break;
+				await Bun.sleep(50);
+			}
+		}
+
+		// Reclaim the PID file if it pointed at a process we just killed (it is
+		// either already dead or in flight to dead) or at any other dead PID.
+		const existingPid = await readPidFile(pidFilePath);
+		if (existingPid !== null) {
+			if (killedSet.has(existingPid) || !isProcessRunning(existingPid)) {
+				await removePidFile(pidFilePath);
+			}
+		}
+
+		if (killed.length > 0) {
+			if (useJson) {
+				jsonOutput("watch", { killed });
+			} else {
+				printSuccess(`Killed ${killed.length} foreign watchdog process(es): ${killed.join(", ")}`);
+			}
+		} else if (!useJson) {
+			printHint("No foreign watchdog processes found.");
+		}
+	}
+
+	if (opts.background) {
+		// Build the args for the child process, forwarding --interval but not --background
+		const childArgs: string[] = ["watch"];
+		if (opts.interval) {
+			childArgs.push("--interval", opts.interval);
+		}
+
+		// Resolve the agentplate binary path
+		const agentplateBin = await resolveAgentplateBin();
+
+		// Pre-check: surface "already running" before paying the cost of a spawn.
+		// This is only for friendly errors — the authoritative exclusion happens
+		// in the atomic acquirePidLock call below.
+		const existingPid = await readPidFile(pidFilePath);
+		if (existingPid !== null && isProcessRunning(existingPid)) {
+			if (useJson) {
+				jsonOutput("watch", { running: true, pid: existingPid, error: "Watchdog already running" });
+			} else {
+				printError(formatLockContestedError(existingPid, pidFilePath));
+			}
+			process.exitCode = 1;
+			return;
+		}
+
+		// Spawn the detached background daemon (foreground mode in the child).
+		const child = Bun.spawn(["bun", "run", agentplateBin, ...childArgs], {
+			cwd,
+			stdout: "ignore",
+			stderr: "ignore",
+			stdin: "ignore",
+		});
+
+		const childPid = child.pid;
+
+		// Atomically acquire the lock with the child's PID. If another writer
+		// raced in between our pre-check and the spawn, we have to kill our
+		// child and report contention.
+		const lockResult = await acquirePidLock(pidFilePath, childPid, isProcessRunning);
+		if (!lockResult.acquired) {
+			try {
+				child.kill("SIGTERM");
+			} catch {
+				// Already exited — not an error.
+			}
+			if (useJson) {
+				jsonOutput("watch", {
+					running: true,
+					pid: lockResult.existingPid,
+					error: "Watchdog already running",
+				});
+			} else {
+				printError(formatLockContestedError(lockResult.existingPid, pidFilePath));
+			}
+			process.exitCode = 1;
+			return;
+		}
+
+		// Lock is ours. Detach so this parent invocation can exit independently.
+		child.unref();
+
+		if (useJson) {
+			jsonOutput("watch", { pid: childPid, intervalMs, pidFile: pidFilePath });
+		} else {
+			printSuccess("Watchdog started in background", `PID: ${childPid}, interval: ${intervalMs}ms`);
+			printHint(`PID file: ${pidFilePath}`);
+		}
+		return;
+	}
+
+	// Foreground mode: acquire the lock atomically before announcing anything.
+	// In the background-spawn case the parent has already written this PID into
+	// the lock file; acquirePidLock detects own-PID and returns acquired=true
+	// idempotently.
+	const lockResult: AcquirePidLockResult = await acquirePidLock(
+		pidFilePath,
+		process.pid,
+		isProcessRunning,
+	);
+	if (!lockResult.acquired) {
+		if (useJson) {
+			jsonOutput("watch", {
+				running: true,
+				pid: lockResult.existingPid,
+				error: "Watchdog already running",
+			});
+		} else {
+			printError(formatLockContestedError(lockResult.existingPid, pidFilePath));
+		}
+		process.exitCode = 1;
+		return;
+	}
+
+	if (useJson) {
+		jsonOutput("watch", { pid: process.pid, intervalMs, mode: "foreground" });
+	} else {
+		printSuccess("Watchdog running", `interval: ${intervalMs}ms`);
+		printHint("Press Ctrl+C to stop.");
+	}
+
+	const { stop } = startDaemon({
+		root: config.project.root,
+		intervalMs,
+		staleThresholdMs,
+		zombieThresholdMs,
+		nudgeIntervalMs: config.watchdog.nudgeIntervalMs,
+		tier1Enabled: config.watchdog.tier1Enabled,
+		notifyParentOnDeath: config.watchdog.notifyParentOnDeath ?? true,
+		onHealthCheck(check) {
+			const timestamp = new Date().toISOString().slice(11, 19);
+			process.stdout.write(`[${timestamp}] ${formatCheck(check)}\n`);
+		},
+	});
+
+	// Keep running until interrupted
+	await new Promise<void>((resolve) => {
+		process.on("SIGINT", () => {
+			stop();
+			// Clean up PID file on graceful shutdown
+			removePidFile(pidFilePath).finally(() => {
+				printSuccess("Watchdog stopped.");
+				process.exitCode = 0;
+				resolve();
+			});
+		});
+	});
+}
+
+export function createWatchCommand(): Command {
+	return new Command("watch")
+		.description("Start Tier 0 mechanical watchdog daemon")
+		.option("--interval <ms>", "Health check interval in milliseconds")
+		.option("--background", "Daemonize (run in background)")
+		.option(
+			"--kill-others",
+			"Kill any pre-existing 'ap watch' processes before starting (for cleanup of multi-daemon state)",
+		)
+		.option("--json", "Output as JSON")
+		.action(
+			async (opts: {
+				interval?: string;
+				background?: boolean;
+				killOthers?: boolean;
+				json?: boolean;
+			}) => {
+				await runWatch(opts);
+			},
+		);
+}
+
+/**
+ * Entry point for `agentplate watch [--interval <ms>] [--background]`.
+ */
+export async function watchCommand(args: string[]): Promise<void> {
+	const cmd = createWatchCommand();
+	cmd.exitOverride();
+
+	try {
+		await cmd.parseAsync(args, { from: "user" });
+	} catch (err: unknown) {
+		if (err && typeof err === "object" && "code" in err) {
+			const code = (err as { code: string }).code;
+			if (code === "commander.helpDisplayed" || code === "commander.version") {
+				return;
+			}
+		}
+		throw err;
+	}
+}