@os-eco/overstory-cli 0.6.1

package/src/commands/trace.ts

@@ -0,0 +1,325 @@
+/**
+ * CLI command: overstory trace <target> [--json] [--since <ts>] [--until <ts>] [--limit <n>]
+ *
+ * Shows a chronological timeline of events for an agent or bead task.
+ * Target can be an agent name or a bead ID (resolved to agent name via SessionStore).
+ */
+
+import { join } from "node:path";
+import { loadConfig } from "../config.ts";
+import { ValidationError } from "../errors.ts";
+import { createEventStore } from "../events/store.ts";
+import { color } from "../logging/color.ts";
+import { openSessionStore } from "../sessions/compat.ts";
+import type { EventType, StoredEvent } from "../types.ts";
+
+/** Labels and colors for each event type. */
+const EVENT_LABELS: Record<EventType, { label: string; color: string }> = {
+	tool_start: { label: "TOOL START", color: color.blue },
+	tool_end: { label: "TOOL END  ", color: color.blue },
+	session_start: { label: "SESSION  +", color: color.green },
+	session_end: { label: "SESSION  -", color: color.yellow },
+	mail_sent: { label: "MAIL SENT ", color: color.cyan },
+	mail_received: { label: "MAIL RECV ", color: color.cyan },
+	spawn: { label: "SPAWN     ", color: color.magenta },
+	error: { label: "ERROR     ", color: color.red },
+	custom: { label: "CUSTOM    ", color: color.gray },
+};
+
+/**
+ * Parse a named flag value from args.
+ */
+function getFlag(args: string[], flag: string): string | undefined {
+	const idx = args.indexOf(flag);
+	if (idx === -1 || idx + 1 >= args.length) {
+		return undefined;
+	}
+	return args[idx + 1];
+}
+
+function hasFlag(args: string[], flag: string): boolean {
+	return args.includes(flag);
+}
+
+/**
+ * Detect whether a target string looks like a bead ID.
+ * Bead IDs follow the pattern: word-alphanumeric (e.g., "overstory-rj1k", "myproject-abc1").
+ */
+function looksLikeBeadId(target: string): boolean {
+	return /^[a-z][a-z0-9]*-[a-z0-9]{3,}$/i.test(target);
+}
+
+/**
+ * Format a relative time string from a timestamp.
+ * Returns strings like "2m ago", "1h ago", "3d ago".
+ */
+function formatRelativeTime(timestamp: string): string {
+	const eventTime = new Date(timestamp).getTime();
+	const now = Date.now();
+	const diffMs = now - eventTime;
+
+	if (diffMs < 0) return "just now";
+
+	const seconds = Math.floor(diffMs / 1000);
+	if (seconds < 60) return `${seconds}s ago`;
+
+	const minutes = Math.floor(seconds / 60);
+	if (minutes < 60) return `${minutes}m ago`;
+
+	const hours = Math.floor(minutes / 60);
+	if (hours < 24) return `${hours}h ago`;
+
+	const days = Math.floor(hours / 24);
+	return `${days}d ago`;
+}
+
+/**
+ * Format an absolute time from an ISO timestamp.
+ * Returns "HH:MM:SS" portion.
+ */
+function formatAbsoluteTime(timestamp: string): string {
+	const match = /T(\d{2}:\d{2}:\d{2})/.exec(timestamp);
+	if (match?.[1]) {
+		return match[1];
+	}
+	return timestamp;
+}
+
+/**
+ * Format the date portion of an ISO timestamp.
+ * Returns "YYYY-MM-DD".
+ */
+function formatDate(timestamp: string): string {
+	const match = /^(\d{4}-\d{2}-\d{2})/.exec(timestamp);
+	if (match?.[1]) {
+		return match[1];
+	}
+	return "";
+}
+
+/**
+ * Build a detail string for a timeline event based on its type and fields.
+ */
+function buildEventDetail(event: StoredEvent): string {
+	const parts: string[] = [];
+
+	if (event.toolName) {
+		parts.push(`tool=${event.toolName}`);
+	}
+
+	if (event.toolDurationMs !== null) {
+		parts.push(`duration=${event.toolDurationMs}ms`);
+	}
+
+	if (event.data) {
+		try {
+			const parsed: unknown = JSON.parse(event.data);
+			if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+				const data = parsed as Record<string, unknown>;
+				for (const [key, value] of Object.entries(data)) {
+					if (value !== null && value !== undefined) {
+						const strValue = typeof value === "string" ? value : JSON.stringify(value);
+						// Truncate long values
+						const truncated = strValue.length > 80 ? `${strValue.slice(0, 77)}...` : strValue;
+						parts.push(`${key}=${truncated}`);
+					}
+				}
+			}
+		} catch {
+			// data is not valid JSON; show it raw if short enough
+			if (event.data.length <= 80) {
+				parts.push(event.data);
+			}
+		}
+	}
+
+	return parts.join(" ");
+}
+
+/**
+ * Print events as a formatted timeline with ANSI colors.
+ */
+function printTimeline(events: StoredEvent[], agentName: string, useAbsoluteTime: boolean): void {
+	const w = process.stdout.write.bind(process.stdout);
+
+	w(`${color.bold}Timeline for ${agentName}${color.reset}\n`);
+	w(`${"=".repeat(70)}\n`);
+
+	if (events.length === 0) {
+		w(`${color.dim}No events found.${color.reset}\n`);
+		return;
+	}
+
+	w(`${color.dim}${events.length} event${events.length === 1 ? "" : "s"}${color.reset}\n\n`);
+
+	let lastDate = "";
+
+	for (const event of events) {
+		// Print date separator when the date changes
+		const date = formatDate(event.createdAt);
+		if (date && date !== lastDate) {
+			if (lastDate !== "") {
+				w("\n");
+			}
+			w(`${color.dim}--- ${date} ---${color.reset}\n`);
+			lastDate = date;
+		}
+
+		const timeStr = useAbsoluteTime
+			? formatAbsoluteTime(event.createdAt)
+			: formatRelativeTime(event.createdAt);
+
+		const eventInfo = EVENT_LABELS[event.eventType] ?? {
+			label: event.eventType.padEnd(10),
+			color: color.gray,
+		};
+
+		const levelColor =
+			event.level === "error" ? color.red : event.level === "warn" ? color.yellow : "";
+		const levelReset = levelColor ? color.reset : "";
+
+		const detail = buildEventDetail(event);
+		const detailSuffix = detail ? ` ${color.dim}${detail}${color.reset}` : "";
+
+		const agentLabel =
+			event.agentName !== agentName ? ` ${color.dim}[${event.agentName}]${color.reset}` : "";
+
+		w(
+			`${color.dim}${timeStr.padStart(10)}${color.reset} ` +
+				`${levelColor}${eventInfo.color}${color.bold}${eventInfo.label}${color.reset}${levelReset}` +
+				`${agentLabel}${detailSuffix}\n`,
+		);
+	}
+}
+
+const TRACE_HELP = `overstory trace -- Show chronological timeline for an agent or bead
+
+Usage: overstory trace <target> [options]
+
+Arguments:
+  <target>               Agent name or bead ID
+
+Options:
+  --json                 Output as JSON array of StoredEvent objects
+  --since <timestamp>    Start time filter (ISO 8601)
+  --until <timestamp>    End time filter (ISO 8601)
+  --limit <n>            Max events to show (default: 100)
+  --help, -h             Show this help`;
+
+/**
+ * Entry point for `overstory trace <target> [--json] [--since] [--until] [--limit]`.
+ */
+export async function traceCommand(args: string[]): Promise<void> {
+	if (args.includes("--help") || args.includes("-h")) {
+		process.stdout.write(`${TRACE_HELP}\n`);
+		return;
+	}
+
+	// Extract positional target: first arg that is not a flag or flag value
+	const flagsWithValues = new Set(["--since", "--until", "--limit"]);
+	const booleanFlags = new Set(["--json", "--help", "-h"]);
+	let target: string | undefined;
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === undefined) continue;
+		if (booleanFlags.has(arg)) continue;
+		if (flagsWithValues.has(arg)) {
+			i++; // skip the value
+			continue;
+		}
+		if (arg.startsWith("-")) continue;
+		target = arg;
+		break;
+	}
+
+	if (!target) {
+		throw new ValidationError("Missing target. Usage: overstory trace <agent-name|bead-id>", {
+			field: "target",
+		});
+	}
+
+	const json = hasFlag(args, "--json");
+	const sinceStr = getFlag(args, "--since");
+	const untilStr = getFlag(args, "--until");
+	const limitStr = getFlag(args, "--limit");
+	const limit = limitStr ? Number.parseInt(limitStr, 10) : 100;
+
+	if (Number.isNaN(limit) || limit < 1) {
+		throw new ValidationError("--limit must be a positive integer", {
+			field: "limit",
+			value: limitStr,
+		});
+	}
+
+	// Validate timestamps if provided
+	if (sinceStr !== undefined && Number.isNaN(new Date(sinceStr).getTime())) {
+		throw new ValidationError("--since must be a valid ISO 8601 timestamp", {
+			field: "since",
+			value: sinceStr,
+		});
+	}
+	if (untilStr !== undefined && Number.isNaN(new Date(untilStr).getTime())) {
+		throw new ValidationError("--until must be a valid ISO 8601 timestamp", {
+			field: "until",
+			value: untilStr,
+		});
+	}
+
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const overstoryDir = join(config.project.root, ".overstory");
+
+	// Resolve target to agent name
+	let agentName = target;
+
+	if (looksLikeBeadId(target)) {
+		// Try to resolve bead ID to agent name via SessionStore
+		const { store: sessionStore } = openSessionStore(overstoryDir);
+		try {
+			const allSessions = sessionStore.getAll();
+			const matchingSession = allSessions.find((s) => s.beadId === target);
+			if (matchingSession) {
+				agentName = matchingSession.agentName;
+			} else {
+				// No session found for this bead ID; treat it as an agent name anyway
+				// (the event query will return empty results if no events match)
+				agentName = target;
+			}
+		} finally {
+			sessionStore.close();
+		}
+	}
+
+	// Open event store and query events
+	const eventsDbPath = join(overstoryDir, "events.db");
+	const eventsFile = Bun.file(eventsDbPath);
+	if (!(await eventsFile.exists())) {
+		if (json) {
+			process.stdout.write("[]\n");
+		} else {
+			process.stdout.write("No events data yet.\n");
+		}
+		return;
+	}
+
+	const eventStore = createEventStore(eventsDbPath);
+
+	try {
+		const events = eventStore.getByAgent(agentName, {
+			since: sinceStr,
+			until: untilStr,
+			limit,
+		});
+
+		if (json) {
+			process.stdout.write(`${JSON.stringify(events)}\n`);
+			return;
+		}
+
+		// Use absolute time if --since is specified, relative otherwise
+		const useAbsoluteTime = sinceStr !== undefined;
+		printTimeline(events, agentName, useAbsoluteTime);
+	} finally {
+		eventStore.close();
+	}
+}

package/src/commands/watch.test.ts

@@ -0,0 +1,145 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { watchCommand } from "./watch.ts";
+
+/**
+ * Tests for `overstory 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;
+	let originalExitCode: string | number | null | undefined;
+
+	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;
+
+		// Save original exitCode
+		originalExitCode = process.exitCode;
+		process.exitCode = 0;
+
+		// Create temp dir with .overstory/config.yaml structure
+		tempDir = await mkdtemp(join(tmpdir(), "watch-test-"));
+		const overstoryDir = join(tempDir, ".overstory");
+		await Bun.write(
+			join(overstoryDir, "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;
+		process.exitCode = originalExitCode;
+		process.chdir(originalCwd);
+		await rm(tempDir, { recursive: true, force: true });
+	});
+
+	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("overstory watch");
+		expect(out).toContain("--interval");
+		expect(out).toContain("--background");
+		expect(out).toContain("Tier 0");
+	});
+
+	test("-h flag shows help text", async () => {
+		await watchCommand(["-h"]);
+		const out = output();
+
+		expect(out).toContain("overstory 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, ".overstory", "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("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, ".overstory", "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 overstory 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)
+	});
+});

package/src/commands/watch.ts

@@ -0,0 +1,247 @@
+/**
+ * CLI command: overstory 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 { loadConfig } from "../config.ts";
+import { OverstoryError } from "../errors.ts";
+import type { HealthCheck } from "../types.ts";
+import { startDaemon } from "../watchdog/daemon.ts";
+import { isProcessRunning } from "../watchdog/health.ts";
+
+/**
+ * Parse a named flag value from args.
+ */
+function getFlag(args: string[], flag: string): string | undefined {
+	const idx = args.indexOf(flag);
+	if (idx === -1 || idx + 1 >= args.length) {
+		return undefined;
+	}
+	return args[idx + 1];
+}
+
+function hasFlag(args: string[], flag: string): boolean {
+	return args.includes(flag);
+}
+
+/**
+ * Format a health check for display.
+ */
+function formatCheck(check: HealthCheck): string {
+	const actionIcon =
+		check.action === "terminate"
+			? "💀"
+			: check.action === "escalate"
+				? "⚠️"
+				: check.action === "investigate"
+					? "🔍"
+					: "✅";
+	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;
+}
+
+// isProcessRunning is imported from ../watchdog/health.ts (ZFC shared utility)
+
+/**
+ * Read the PID from the watchdog PID file.
+ * Returns null if the file doesn't exist or can't be parsed.
+ */
+async function readPidFile(pidFilePath: string): Promise<number | null> {
+	const file = Bun.file(pidFilePath);
+	const exists = await file.exists();
+	if (!exists) {
+		return null;
+	}
+
+	try {
+		const text = await file.text();
+		const pid = Number.parseInt(text.trim(), 10);
+		if (Number.isNaN(pid) || pid <= 0) {
+			return null;
+		}
+		return pid;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Write a PID to the watchdog PID file.
+ */
+async function writePidFile(pidFilePath: string, pid: number): Promise<void> {
+	await Bun.write(pidFilePath, `${pid}\n`);
+}
+
+/**
+ * Remove the watchdog PID file.
+ */
+async function removePidFile(pidFilePath: string): Promise<void> {
+	const { unlink } = await import("node:fs/promises");
+	try {
+		await unlink(pidFilePath);
+	} catch {
+		// File may already be gone — not an error
+	}
+}
+
+/**
+ * Resolve the path to the overstory binary for re-launching.
+ * Uses `which overstory` first, then falls back to process.argv.
+ */
+async function resolveOverstoryBin(): Promise<string> {
+	try {
+		const proc = Bun.spawn(["which", "overstory"], {
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		const exitCode = await proc.exited;
+		if (exitCode === 0) {
+			const binPath = (await new Response(proc.stdout).text()).trim();
+			if (binPath.length > 0) {
+				return binPath;
+			}
+		}
+	} catch {
+		// which not available or overstory not on PATH
+	}
+
+	// Fallback: use the script that's currently running (process.argv[1])
+	const scriptPath = process.argv[1];
+	if (scriptPath) {
+		return scriptPath;
+	}
+
+	throw new OverstoryError(
+		"Cannot resolve overstory binary path for background launch",
+		"WATCH_ERROR",
+	);
+}
+
+/**
+ * Entry point for `overstory watch [--interval <ms>] [--background]`.
+ */
+const WATCH_HELP = `overstory watch — Start Tier 0 mechanical watchdog daemon
+
+Usage: overstory watch [--interval <ms>] [--background]
+
+Tier numbering:
+  Tier 0  Mechanical daemon (heartbeat, tmux/pid liveness) — this command
+  Tier 1  Triage agent (ephemeral AI analysis of stalled agents)
+  Tier 2  Monitor agent (continuous patrol — not yet implemented)
+  Tier 3  Supervisor monitors (per-project)
+
+Options:
+  --interval <ms>    Health check interval in milliseconds (default: from config)
+  --background       Daemonize (run in background)
+  --help, -h         Show this help`;
+
+export async function watchCommand(args: string[]): Promise<void> {
+	if (args.includes("--help") || args.includes("-h")) {
+		process.stdout.write(`${WATCH_HELP}\n`);
+		return;
+	}
+
+	const intervalStr = getFlag(args, "--interval");
+	const background = hasFlag(args, "--background");
+
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+
+	const intervalMs = intervalStr
+		? Number.parseInt(intervalStr, 10)
+		: config.watchdog.tier0IntervalMs;
+
+	const staleThresholdMs = config.watchdog.staleThresholdMs;
+	const zombieThresholdMs = config.watchdog.zombieThresholdMs;
+	const pidFilePath = join(config.project.root, ".overstory", "watchdog.pid");
+
+	if (background) {
+		// Check if a watchdog is already running
+		const existingPid = await readPidFile(pidFilePath);
+		if (existingPid !== null && isProcessRunning(existingPid)) {
+			process.stderr.write(
+				`Error: Watchdog already running (PID: ${existingPid}). ` +
+					`Kill it first or remove ${pidFilePath}\n`,
+			);
+			process.exitCode = 1;
+			return;
+		}
+
+		// Clean up stale PID file if process is no longer running
+		if (existingPid !== null) {
+			await removePidFile(pidFilePath);
+		}
+
+		// Build the args for the child process, forwarding --interval but not --background
+		const childArgs: string[] = ["watch"];
+		if (intervalStr) {
+			childArgs.push("--interval", intervalStr);
+		}
+
+		// Resolve the overstory binary path
+		const overstoryBin = await resolveOverstoryBin();
+
+		// Spawn a detached background process running `overstory watch` (without --background)
+		const child = Bun.spawn(["bun", "run", overstoryBin, ...childArgs], {
+			cwd,
+			stdout: "ignore",
+			stderr: "ignore",
+			stdin: "ignore",
+		});
+
+		// Unref the child so the parent can exit without waiting for it
+		child.unref();
+
+		const childPid = child.pid;
+
+		// Write PID file for later cleanup
+		await writePidFile(pidFilePath, childPid);
+
+		process.stdout.write(
+			`Watchdog started in background (PID: ${childPid}, interval: ${intervalMs}ms)\n`,
+		);
+		process.stdout.write(`PID file: ${pidFilePath}\n`);
+		return;
+	}
+
+	// Foreground mode: show real-time health checks
+	process.stdout.write(`Watchdog running (interval: ${intervalMs}ms)\n`);
+	process.stdout.write("Press Ctrl+C to stop.\n\n");
+
+	// Write PID file so `--background` check and external tools can find us
+	await writePidFile(pidFilePath, process.pid);
+
+	const { stop } = startDaemon({
+		root: config.project.root,
+		intervalMs,
+		staleThresholdMs,
+		zombieThresholdMs,
+		nudgeIntervalMs: config.watchdog.nudgeIntervalMs,
+		tier1Enabled: config.watchdog.tier1Enabled,
+		onHealthCheck(check) {
+			const timestamp = new Date().toISOString().slice(11, 19);
+			process.stdout.write(`[${timestamp}] ${formatCheck(check)}\n`);
+		},
+	});
+
+	// Keep running until interrupted
+	process.on("SIGINT", () => {
+		stop();
+		// Clean up PID file on graceful shutdown
+		removePidFile(pidFilePath).finally(() => {
+			process.stdout.write("\nWatchdog stopped.\n");
+			process.exit(0);
+		});
+	});
+
+	// Block forever
+	await new Promise(() => {});
+}