@os-eco/overstory-cli 0.6.1

package/src/commands/monitor.test.ts

@@ -0,0 +1,191 @@
+/**
+ * Tests for src/commands/monitor.ts
+ *
+ * Note: We do NOT test start/stop/status subcommands here because they require
+ * tmux session management, which is fragile in test environments and interferes
+ * with developer tmux sessions. Those operations are covered by E2E testing.
+ */
+
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { AgentError, ValidationError } from "../errors.ts";
+import { cleanupTempDir, createTempGitRepo } from "../test-helpers.ts";
+import { buildMonitorBeacon, monitorCommand } from "./monitor.ts";
+import { isRunningAsRoot } from "./sling.ts";
+
+describe("buildMonitorBeacon", () => {
+	test("contains monitor agent name", () => {
+		const beacon = buildMonitorBeacon();
+		expect(beacon).toContain("monitor");
+	});
+
+	test("contains tier-2 designation", () => {
+		const beacon = buildMonitorBeacon();
+		expect(beacon).toContain("tier-2");
+	});
+
+	test("contains ISO timestamp with today's date", () => {
+		const beacon = buildMonitorBeacon();
+		const today = new Date().toISOString().split("T")[0]; // YYYY-MM-DD
+		if (!today) {
+			throw new Error("Failed to extract date from ISO string");
+		}
+		expect(beacon).toContain(today);
+	});
+
+	test("contains startup instruction: mulch prime", () => {
+		const beacon = buildMonitorBeacon();
+		expect(beacon).toContain("mulch prime");
+	});
+
+	test("contains startup instruction: overstory status --json", () => {
+		const beacon = buildMonitorBeacon();
+		expect(beacon).toContain("overstory status --json");
+	});
+
+	test("contains startup instruction: overstory mail check --agent monitor", () => {
+		const beacon = buildMonitorBeacon();
+		expect(beacon).toContain("overstory mail check --agent monitor");
+	});
+
+	test("contains startup instruction: patrol loop", () => {
+		const beacon = buildMonitorBeacon();
+		expect(beacon).toContain("patrol loop");
+	});
+
+	test("contains [OVERSTORY] prefix", () => {
+		const beacon = buildMonitorBeacon();
+		expect(beacon).toContain("[OVERSTORY]");
+	});
+
+	test("contains Depth: 0", () => {
+		const beacon = buildMonitorBeacon();
+		expect(beacon).toContain("Depth: 0");
+	});
+
+	test("contains Parent: none", () => {
+		const beacon = buildMonitorBeacon();
+		expect(beacon).toContain("Parent: none");
+	});
+});
+
+describe("monitorCommand", () => {
+	let stdoutSpy: ReturnType<typeof spyOn>;
+	let stdoutWrites: string[] = [];
+
+	beforeEach(() => {
+		stdoutWrites = [];
+		stdoutSpy = spyOn(process.stdout, "write").mockImplementation((chunk: unknown) => {
+			stdoutWrites.push(String(chunk));
+			return true;
+		});
+	});
+
+	afterEach(() => {
+		stdoutSpy.mockRestore();
+	});
+
+	test("--help prints help text containing 'overstory monitor'", async () => {
+		await monitorCommand(["--help"]);
+		const output = stdoutWrites.join("");
+		expect(output).toContain("overstory monitor");
+	});
+
+	test("--help prints help text containing 'start'", async () => {
+		await monitorCommand(["--help"]);
+		const output = stdoutWrites.join("");
+		expect(output).toContain("start");
+	});
+
+	test("--help prints help text containing 'stop'", async () => {
+		await monitorCommand(["--help"]);
+		const output = stdoutWrites.join("");
+		expect(output).toContain("stop");
+	});
+
+	test("--help prints help text containing 'status'", async () => {
+		await monitorCommand(["--help"]);
+		const output = stdoutWrites.join("");
+		expect(output).toContain("status");
+	});
+
+	test("-h prints help text", async () => {
+		await monitorCommand(["-h"]);
+		const output = stdoutWrites.join("");
+		expect(output).toContain("overstory monitor");
+	});
+
+	test("empty args [] shows help (same as --help)", async () => {
+		await monitorCommand([]);
+		const output = stdoutWrites.join("");
+		expect(output).toContain("overstory monitor");
+	});
+
+	test("unknown subcommand 'restart' throws ValidationError", async () => {
+		await expect(monitorCommand(["restart"])).rejects.toThrow(ValidationError);
+	});
+
+	test("unknown subcommand error message contains the bad value 'restart'", async () => {
+		try {
+			await monitorCommand(["restart"]);
+			// Should not reach here
+			expect(true).toBe(false);
+		} catch (err) {
+			if (err instanceof ValidationError) {
+				expect(err.message).toContain("restart");
+			} else {
+				throw err;
+			}
+		}
+	});
+
+	describe("tier2Enabled gate", () => {
+		let tempDir: string;
+		const originalCwd = process.cwd();
+
+		beforeEach(async () => {
+			process.chdir(originalCwd);
+			tempDir = await createTempGitRepo();
+			const overstoryDir = join(tempDir, ".overstory");
+			await mkdir(overstoryDir, { recursive: true });
+			// Write minimal config — tier2Enabled defaults to false
+			await Bun.write(
+				join(overstoryDir, "config.yaml"),
+				["project:", "  name: test-project", `  root: ${tempDir}`, "  canonicalBranch: main"].join(
+					"\n",
+				),
+			);
+			process.chdir(tempDir);
+		});
+
+		afterEach(async () => {
+			process.chdir(originalCwd);
+			await cleanupTempDir(tempDir);
+		});
+
+		test("monitor start throws AgentError when tier2Enabled is false (default)", async () => {
+			await expect(monitorCommand(["start"])).rejects.toThrow(AgentError);
+		});
+
+		test("monitor start error message contains 'disabled' when tier2Enabled is false", async () => {
+			try {
+				await monitorCommand(["start"]);
+				expect(true).toBe(false); // Should not reach here
+			} catch (err) {
+				if (err instanceof AgentError) {
+					expect(err.message).toContain("disabled");
+				} else {
+					throw err;
+				}
+			}
+		});
+	});
+});
+
+describe("isRunningAsRoot (imported from sling)", () => {
+	test("is accessible from monitor test file", () => {
+		expect(isRunningAsRoot(() => 0)).toBe(true);
+		expect(isRunningAsRoot(() => 1000)).toBe(false);
+	});
+});

package/src/commands/monitor.ts

@@ -0,0 +1,390 @@
+/**
+ * CLI command: overstory monitor start|stop|status
+ *
+ * Manages the persistent Tier 2 monitor agent lifecycle. The monitor runs
+ * at the project root (NOT in a worktree), continuously patrols the agent
+ * fleet, sends nudges to stalled agents, and reports health summaries to
+ * the coordinator.
+ *
+ * Unlike regular agents spawned by sling, the monitor:
+ * - Has no worktree (operates on the main working tree)
+ * - Has no bead assignment (it monitors, not implements)
+ * - Has no overlay CLAUDE.md (context comes via overstory status + mail)
+ * - Persists across patrol cycles
+ */
+
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { deployHooks } from "../agents/hooks-deployer.ts";
+import { createIdentity, loadIdentity } from "../agents/identity.ts";
+import { createManifestLoader, resolveModel } from "../agents/manifest.ts";
+import { loadConfig } from "../config.ts";
+import { AgentError, ValidationError } from "../errors.ts";
+import { openSessionStore } from "../sessions/compat.ts";
+import type { AgentSession } from "../types.ts";
+import { createSession, isSessionAlive, killSession, sendKeys } from "../worktree/tmux.ts";
+import { isRunningAsRoot } from "./sling.ts";
+
+/** Default monitor agent name. */
+const MONITOR_NAME = "monitor";
+
+/**
+ * Build the tmux session name for the monitor.
+ * Includes the project name to prevent cross-project collisions (overstory-pcef).
+ */
+function monitorTmuxSession(projectName: string): string {
+	return `overstory-${projectName}-${MONITOR_NAME}`;
+}
+
+/**
+ * Build the monitor startup beacon — the first message sent to the monitor
+ * via tmux send-keys after Claude Code initializes.
+ */
+export function buildMonitorBeacon(): string {
+	const timestamp = new Date().toISOString();
+	const parts = [
+		`[OVERSTORY] ${MONITOR_NAME} (monitor/tier-2) ${timestamp}`,
+		"Depth: 0 | Parent: none | Role: continuous fleet patrol",
+		`Startup: run mulch prime, check fleet (overstory status --json), check mail (overstory mail check --agent ${MONITOR_NAME}), then begin patrol loop`,
+	];
+	return parts.join(" — ");
+}
+
+/**
+ * Determine whether to auto-attach to the tmux session after starting.
+ */
+function resolveAttach(args: string[], isTTY: boolean): boolean {
+	if (args.includes("--attach")) return true;
+	if (args.includes("--no-attach")) return false;
+	return isTTY;
+}
+
+/**
+ * Start the monitor agent.
+ *
+ * 1. Verify no monitor is already running
+ * 2. Load config
+ * 3. Deploy hooks to project root's .claude/ (monitor-specific guards)
+ * 4. Create agent identity (if first time)
+ * 5. Spawn tmux session at project root with Claude Code
+ * 6. Send startup beacon
+ * 7. Record session in SessionStore (sessions.db)
+ */
+async function startMonitor(args: string[]): Promise<void> {
+	const json = args.includes("--json");
+	const shouldAttach = resolveAttach(args, !!process.stdout.isTTY);
+
+	if (isRunningAsRoot()) {
+		throw new AgentError(
+			"Cannot spawn agents as root (UID 0). The claude CLI rejects --dangerously-skip-permissions when run as root, causing the tmux session to die immediately. Run overstory as a non-root user.",
+		);
+	}
+
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+
+	// Gate on tier2Enabled config flag
+	if (!config.watchdog.tier2Enabled) {
+		throw new AgentError(
+			"Monitor agent (Tier 2) is disabled. Set watchdog.tier2Enabled: true in .overstory/config.yaml to enable.",
+			{ agentName: MONITOR_NAME },
+		);
+	}
+
+	const projectRoot = config.project.root;
+	const tmuxSession = monitorTmuxSession(config.project.name);
+
+	// Check for existing monitor
+	const overstoryDir = join(projectRoot, ".overstory");
+	const { store } = openSessionStore(overstoryDir);
+	try {
+		const existing = store.getByName(MONITOR_NAME);
+
+		if (
+			existing &&
+			existing.capability === "monitor" &&
+			existing.state !== "completed" &&
+			existing.state !== "zombie"
+		) {
+			const alive = await isSessionAlive(existing.tmuxSession);
+			if (alive) {
+				throw new AgentError(
+					`Monitor is already running (tmux: ${existing.tmuxSession}, since: ${existing.startedAt})`,
+					{ agentName: MONITOR_NAME },
+				);
+			}
+			// Session recorded but tmux is dead — mark as completed and continue
+			store.updateState(MONITOR_NAME, "completed");
+		}
+
+		// Deploy monitor-specific hooks to the project root's .claude/ directory.
+		// The monitor gets the same structural enforcement as other non-implementation
+		// agents (Write/Edit/NotebookEdit blocked, dangerous bash commands blocked).
+		await deployHooks(projectRoot, MONITOR_NAME, "monitor");
+
+		// Create monitor identity if first run
+		const identityBaseDir = join(projectRoot, ".overstory", "agents");
+		await mkdir(identityBaseDir, { recursive: true });
+		const existingIdentity = await loadIdentity(identityBaseDir, MONITOR_NAME);
+		if (!existingIdentity) {
+			await createIdentity(identityBaseDir, {
+				name: MONITOR_NAME,
+				capability: "monitor",
+				created: new Date().toISOString(),
+				sessionsCompleted: 0,
+				expertiseDomains: config.mulch.enabled ? config.mulch.domains : [],
+				recentTasks: [],
+			});
+		}
+
+		// Resolve model from config > manifest > fallback
+		const manifestLoader = createManifestLoader(
+			join(projectRoot, config.agents.manifestPath),
+			join(projectRoot, config.agents.baseDir),
+		);
+		const manifest = await manifestLoader.load();
+		const { model, env } = resolveModel(config, manifest, "monitor", "sonnet");
+
+		// Spawn tmux session at project root with Claude Code (interactive mode).
+		// Inject the monitor base definition via --append-system-prompt.
+		const agentDefPath = join(projectRoot, ".overstory", "agent-defs", "monitor.md");
+		const agentDefFile = Bun.file(agentDefPath);
+		let claudeCmd = `claude --model ${model} --dangerously-skip-permissions`;
+		if (await agentDefFile.exists()) {
+			const agentDef = await agentDefFile.text();
+			const escaped = agentDef.replace(/'/g, "'\\''");
+			claudeCmd += ` --append-system-prompt '${escaped}'`;
+		}
+		const pid = await createSession(tmuxSession, projectRoot, claudeCmd, {
+			...env,
+			OVERSTORY_AGENT_NAME: MONITOR_NAME,
+		});
+
+		// Record session BEFORE sending the beacon so that hook-triggered
+		// updateLastActivity() can find the entry and transition booting->working.
+		const session: AgentSession = {
+			id: `session-${Date.now()}-${MONITOR_NAME}`,
+			agentName: MONITOR_NAME,
+			capability: "monitor",
+			worktreePath: projectRoot, // Monitor uses project root, not a worktree
+			branchName: config.project.canonicalBranch, // Operates on canonical branch
+			beadId: "", // No specific bead assignment
+			tmuxSession,
+			state: "booting",
+			pid,
+			parentAgent: null, // Top of hierarchy (alongside coordinator)
+			depth: 0,
+			runId: null,
+			startedAt: new Date().toISOString(),
+			lastActivity: new Date().toISOString(),
+			escalationLevel: 0,
+			stalledSince: null,
+		};
+
+		store.upsert(session);
+
+		// Send beacon after TUI initialization delay
+		await Bun.sleep(3_000);
+		const beacon = buildMonitorBeacon();
+		await sendKeys(tmuxSession, beacon);
+
+		// Follow-up Enter to ensure submission (same pattern as sling.ts)
+		await Bun.sleep(500);
+		await sendKeys(tmuxSession, "");
+
+		const output = {
+			agentName: MONITOR_NAME,
+			capability: "monitor",
+			tmuxSession,
+			projectRoot,
+			pid,
+		};
+
+		if (json) {
+			process.stdout.write(`${JSON.stringify(output)}\n`);
+		} else {
+			process.stdout.write("Monitor started\n");
+			process.stdout.write(`  Tmux:    ${tmuxSession}\n`);
+			process.stdout.write(`  Root:    ${projectRoot}\n`);
+			process.stdout.write(`  PID:     ${pid}\n`);
+		}
+
+		if (shouldAttach) {
+			Bun.spawnSync(["tmux", "attach-session", "-t", tmuxSession], {
+				stdio: ["inherit", "inherit", "inherit"],
+			});
+		}
+	} finally {
+		store.close();
+	}
+}
+
+/**
+ * Stop the monitor agent.
+ *
+ * 1. Find the active monitor session
+ * 2. Kill the tmux session (with process tree cleanup)
+ * 3. Mark session as completed in SessionStore
+ */
+async function stopMonitor(args: string[]): Promise<void> {
+	const json = args.includes("--json");
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const projectRoot = config.project.root;
+
+	const overstoryDir = join(projectRoot, ".overstory");
+	const { store } = openSessionStore(overstoryDir);
+	try {
+		const session = store.getByName(MONITOR_NAME);
+
+		if (
+			!session ||
+			session.capability !== "monitor" ||
+			session.state === "completed" ||
+			session.state === "zombie"
+		) {
+			throw new AgentError("No active monitor session found", {
+				agentName: MONITOR_NAME,
+			});
+		}
+
+		// Kill tmux session with process tree cleanup
+		const alive = await isSessionAlive(session.tmuxSession);
+		if (alive) {
+			await killSession(session.tmuxSession);
+		}
+
+		// Update session state
+		store.updateState(MONITOR_NAME, "completed");
+		store.updateLastActivity(MONITOR_NAME);
+
+		if (json) {
+			process.stdout.write(`${JSON.stringify({ stopped: true, sessionId: session.id })}\n`);
+		} else {
+			process.stdout.write(`Monitor stopped (session: ${session.id})\n`);
+		}
+	} finally {
+		store.close();
+	}
+}
+
+/**
+ * Show monitor status.
+ *
+ * Checks session registry and tmux liveness to report actual state.
+ */
+async function statusMonitor(args: string[]): Promise<void> {
+	const json = args.includes("--json");
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const projectRoot = config.project.root;
+
+	const overstoryDir = join(projectRoot, ".overstory");
+	const { store } = openSessionStore(overstoryDir);
+	try {
+		const session = store.getByName(MONITOR_NAME);
+
+		if (
+			!session ||
+			session.capability !== "monitor" ||
+			session.state === "completed" ||
+			session.state === "zombie"
+		) {
+			if (json) {
+				process.stdout.write(`${JSON.stringify({ running: false })}\n`);
+			} else {
+				process.stdout.write("Monitor is not running\n");
+			}
+			return;
+		}
+
+		const alive = await isSessionAlive(session.tmuxSession);
+
+		// Reconcile state: if session says active but tmux is dead, update.
+		// We already filtered out completed/zombie states above, so if tmux is dead
+		// this session needs to be marked as zombie.
+		if (!alive) {
+			store.updateState(MONITOR_NAME, "zombie");
+			store.updateLastActivity(MONITOR_NAME);
+			session.state = "zombie";
+		}
+
+		const status = {
+			running: alive,
+			sessionId: session.id,
+			state: session.state,
+			tmuxSession: session.tmuxSession,
+			pid: session.pid,
+			startedAt: session.startedAt,
+			lastActivity: session.lastActivity,
+		};
+
+		if (json) {
+			process.stdout.write(`${JSON.stringify(status)}\n`);
+		} else {
+			const stateLabel = alive ? "running" : session.state;
+			process.stdout.write(`Monitor: ${stateLabel}\n`);
+			process.stdout.write(`  Session:   ${session.id}\n`);
+			process.stdout.write(`  Tmux:      ${session.tmuxSession}\n`);
+			process.stdout.write(`  PID:       ${session.pid}\n`);
+			process.stdout.write(`  Started:   ${session.startedAt}\n`);
+			process.stdout.write(`  Activity:  ${session.lastActivity}\n`);
+		}
+	} finally {
+		store.close();
+	}
+}
+
+const MONITOR_HELP = `overstory monitor — Manage the persistent Tier 2 monitor agent
+
+Usage: overstory monitor <subcommand> [flags]
+
+Subcommands:
+  start                    Start the monitor (spawns Claude Code at project root)
+  stop                     Stop the monitor (kills tmux session)
+  status                   Show monitor state
+
+Start options:
+  --attach                 Always attach to tmux session after start
+  --no-attach              Never attach to tmux session after start
+                           Default: attach when running in an interactive TTY
+
+General options:
+  --json                   Output as JSON
+  --help, -h               Show this help
+
+The monitor agent (Tier 2) continuously patrols the agent fleet by:
+  - Checking agent health via overstory status
+  - Sending progressive nudges to stalled agents
+  - Escalating unresponsive agents to the coordinator
+  - Producing periodic health summaries`;
+
+/**
+ * Entry point for `overstory monitor <subcommand>`.
+ */
+export async function monitorCommand(args: string[]): Promise<void> {
+	if (args.includes("--help") || args.includes("-h") || args.length === 0) {
+		process.stdout.write(`${MONITOR_HELP}\n`);
+		return;
+	}
+
+	const subcommand = args[0];
+	const subArgs = args.slice(1);
+
+	switch (subcommand) {
+		case "start":
+			await startMonitor(subArgs);
+			break;
+		case "stop":
+			await stopMonitor(subArgs);
+			break;
+		case "status":
+			await statusMonitor(subArgs);
+			break;
+		default:
+			throw new ValidationError(
+				`Unknown monitor subcommand: ${subcommand}. Run 'overstory monitor --help' for usage.`,
+				{ field: "subcommand", value: subcommand },
+			);
+	}
+}