@os-eco/overstory-cli 0.6.1 → 0.6.5

package/src/commands/status.ts

@@ -6,6 +6,7 @@
  */
 
 import { join } from "node:path";
+import { Command } from "commander";
 import { loadConfig } from "../config.ts";
 import { ValidationError } from "../errors.ts";
 import { createMailStore } from "../mail/store.ts";
@@ -13,6 +14,7 @@ import { createMergeQueue } from "../merge/queue.ts";
 import { createMetricsStore } from "../metrics/store.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import type { AgentSession } from "../types.ts";
+import { evaluateHealth } from "../watchdog/health.ts";
 import { listWorktrees } from "../worktree/manager.ts";
 import { listSessions } from "../worktree/tmux.ts";
 
@@ -64,21 +66,6 @@ export async function getCachedTmuxSessions(
 	}
 }
 
-/**
- * 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 duration in ms to a human-readable string.
  */
@@ -150,23 +137,23 @@ export async function gatherStatus(
 
 		const tmuxSessions = await getCachedTmuxSessions();
 
-		// Reconcile agent states: if tmux session is dead but agent state
-		// indicates it should be alive, mark it as zombie
+		// Reconcile agent states using the same health evaluation as the
+		// dashboard and watchdog. This handles:
+		//   1. tmux dead -> zombie (regardless of recorded state)
+		//   2. persistent capabilities (coordinator, monitor) booting -> working when tmux alive
+		//   3. time-based stale/zombie detection for non-persistent agents
 		const tmuxSessionNames = new Set(tmuxSessions.map((s) => s.name));
+		const healthThresholds = { staleMs: 300_000, zombieMs: 600_000 };
 		for (const session of sessions) {
-			if (
-				session.state === "booting" ||
-				session.state === "working" ||
-				session.state === "stalled"
-			) {
-				const tmuxAlive = tmuxSessionNames.has(session.tmuxSession);
-				if (!tmuxAlive) {
-					try {
-						store.updateState(session.agentName, "zombie");
-						session.state = "zombie";
-					} catch {
-						// Best effort: don't fail status display if update fails
-					}
+			if (session.state === "completed") continue;
+			const tmuxAlive = tmuxSessionNames.has(session.tmuxSession);
+			const check = evaluateHealth(session, tmuxAlive, healthThresholds);
+			if (check.state !== session.state) {
+				try {
+					store.updateState(session.agentName, check.state);
+					session.state = check.state;
+				} catch {
+					// Best effort: don't fail status display if update fails
 				}
 			}
 		}
@@ -287,7 +274,7 @@ export function printStatus(data: StatusData): void {
 			const tmuxAlive = tmuxSessionNames.has(agent.tmuxSession);
 			const aliveMarker = tmuxAlive ? "●" : "○";
 			w(`   ${aliveMarker} ${agent.agentName} [${agent.capability}] `);
-			w(`${agent.state} | ${agent.beadId} | ${duration}\n`);
+			w(`${agent.state} | ${agent.taskId} | ${duration}\n`);
 
 			const detail = data.verboseDetails?.[agent.agentName];
 			if (detail) {
@@ -323,33 +310,21 @@ export function printStatus(data: StatusData): void {
 	w(`📈 Sessions recorded: ${data.recentMetricsCount}\n`);
 }
 
-/**
- * Entry point for `overstory status [--json] [--watch]`.
- */
-const STATUS_HELP = `overstory status — Show all active agents and project state
-
-Usage: overstory status [--json] [--verbose] [--agent <name>] [--all]
-
-Options:
-  --json             Output as JSON
-  --verbose          Show extra detail per agent (worktree, logs, mail timestamps)
-  --agent <name>     Show unread mail for this agent (default: orchestrator)
-  --all              Show sessions from all runs (default: current run only)
-  --watch            (deprecated) Use 'overstory dashboard' for live monitoring
-  --interval <ms>    Poll interval for --watch in milliseconds (default: 3000)
-  --help, -h         Show this help`;
-
-export async function statusCommand(args: string[]): Promise<void> {
-	if (args.includes("--help") || args.includes("-h")) {
-		process.stdout.write(`${STATUS_HELP}\n`);
-		return;
-	}
+interface StatusOpts {
+	json?: boolean;
+	watch?: boolean;
+	verbose?: boolean;
+	all?: boolean;
+	interval?: string;
+	agent?: string;
+}
 
-	const json = hasFlag(args, "--json");
-	const watch = hasFlag(args, "--watch");
-	const verbose = hasFlag(args, "--verbose");
-	const all = hasFlag(args, "--all");
-	const intervalStr = getFlag(args, "--interval");
+async function executeStatus(opts: StatusOpts): Promise<void> {
+	const json = opts.json ?? false;
+	const watch = opts.watch ?? false;
+	const verbose = opts.verbose ?? false;
+	const all = opts.all ?? false;
+	const intervalStr = opts.interval;
 	const interval = intervalStr ? Number.parseInt(intervalStr, 10) : 3000;
 
 	if (Number.isNaN(interval) || interval < 500) {
@@ -359,7 +334,7 @@ export async function statusCommand(args: string[]): Promise<void> {
 		});
 	}
 
-	const agentName = getFlag(args, "--agent") ?? "orchestrator";
+	const agentName = opts.agent ?? "orchestrator";
 
 	const cwd = process.cwd();
 	const config = await loadConfig(cwd);
@@ -396,3 +371,33 @@ export async function statusCommand(args: string[]): Promise<void> {
 		}
 	}
 }
+
+export function createStatusCommand(): Command {
+	return new Command("status")
+		.description("Show all active agents and project state")
+		.option("--json", "Output as JSON")
+		.option("--verbose", "Show extra detail per agent (worktree, logs, mail timestamps)")
+		.option("--agent <name>", "Show unread mail for this agent (default: orchestrator)")
+		.option("--all", "Show sessions from all runs (default: current run only)")
+		.option("--watch", "(deprecated) Use 'overstory dashboard' for live monitoring")
+		.option("--interval <ms>", "Poll interval for --watch in milliseconds (default: 3000)")
+		.action(async (opts: StatusOpts) => {
+			await executeStatus(opts);
+		});
+}
+
+export async function statusCommand(args: string[]): Promise<void> {
+	const cmd = createStatusCommand();
+	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;
+	}
+}

package/src/commands/stop.test.ts

@@ -137,7 +137,7 @@ function makeAgentSession(overrides: Partial<AgentSession> = {}): AgentSession {
 		capability: "builder",
 		worktreePath: join(tempDir, ".overstory", "worktrees", "my-builder"),
 		branchName: "overstory/my-builder/bead-123",
-		beadId: "bead-123",
+		taskId: "bead-123",
 		tmuxSession: "overstory-test-project-my-builder",
 		state: "working",
 		pid: 99999,
@@ -207,37 +207,15 @@ function makeDeps(
 
 // --- Tests ---
 
-describe("stopCommand help", () => {
-	test("--help outputs help text", async () => {
-		const output = await captureStdout(() => stopCommand(["--help"]));
-		expect(output).toContain("overstory stop");
-		expect(output).toContain("<agent-name>");
-		expect(output).toContain("--force");
-		expect(output).toContain("--clean-worktree");
-		expect(output).toContain("--json");
-	});
-
-	test("-h outputs help text", async () => {
-		const output = await captureStdout(() => stopCommand(["-h"]));
-		expect(output).toContain("overstory stop");
-		expect(output).toContain("<agent-name>");
-	});
-});
-
 describe("stopCommand validation", () => {
-	test("throws ValidationError when no agent name provided", async () => {
+	test("throws ValidationError when agent name is empty string", async () => {
 		const { deps } = makeDeps();
-		await expect(stopCommand([], deps)).rejects.toThrow(ValidationError);
-	});
-
-	test("throws ValidationError when only flags are provided (no agent name)", async () => {
-		const { deps } = makeDeps();
-		await expect(stopCommand(["--json"], deps)).rejects.toThrow(ValidationError);
+		await expect(stopCommand("", {}, deps)).rejects.toThrow(ValidationError);
 	});
 
 	test("throws AgentError when agent not found", async () => {
 		const { deps } = makeDeps();
-		await expect(stopCommand(["nonexistent-agent"], deps)).rejects.toThrow(AgentError);
+		await expect(stopCommand("nonexistent-agent", {}, deps)).rejects.toThrow(AgentError);
 	});
 
 	test("throws AgentError when agent is already completed", async () => {
@@ -245,8 +223,8 @@ describe("stopCommand validation", () => {
 		saveSessionsToDb([session]);
 
 		const { deps } = makeDeps();
-		await expect(stopCommand(["my-builder"], deps)).rejects.toThrow(AgentError);
-		await expect(stopCommand(["my-builder"], deps)).rejects.toThrow(/already completed/);
+		await expect(stopCommand("my-builder", {}, deps)).rejects.toThrow(AgentError);
+		await expect(stopCommand("my-builder", {}, deps)).rejects.toThrow(/already completed/);
 	});
 
 	test("throws AgentError when agent is already zombie", async () => {
@@ -254,8 +232,8 @@ describe("stopCommand validation", () => {
 		saveSessionsToDb([session]);
 
 		const { deps } = makeDeps();
-		await expect(stopCommand(["my-builder"], deps)).rejects.toThrow(AgentError);
-		await expect(stopCommand(["my-builder"], deps)).rejects.toThrow(/zombie/);
+		await expect(stopCommand("my-builder", {}, deps)).rejects.toThrow(AgentError);
+		await expect(stopCommand("my-builder", {}, deps)).rejects.toThrow(/zombie/);
 	});
 });
 
@@ -265,7 +243,7 @@ describe("stopCommand stop behavior", () => {
 		saveSessionsToDb([session]);
 
 		const { deps, tmuxCalls } = makeDeps({ [session.tmuxSession]: true });
-		const output = await captureStdout(() => stopCommand(["my-builder"], deps));
+		const output = await captureStdout(() => stopCommand("my-builder", {}, deps));
 
 		expect(output).toContain(`Agent "my-builder" stopped`);
 		expect(output).toContain(`Tmux session killed: ${session.tmuxSession}`);
@@ -284,7 +262,7 @@ describe("stopCommand stop behavior", () => {
 		saveSessionsToDb([session]);
 
 		const { deps, tmuxCalls } = makeDeps({ [session.tmuxSession]: true });
-		await stopCommand(["my-builder"], deps);
+		await stopCommand("my-builder", {}, deps);
 
 		expect(tmuxCalls.killSession).toHaveLength(1);
 		const { store } = openSessionStore(overstoryDir);
@@ -298,7 +276,7 @@ describe("stopCommand stop behavior", () => {
 		saveSessionsToDb([session]);
 
 		const { deps, tmuxCalls } = makeDeps({ [session.tmuxSession]: true });
-		await stopCommand(["my-builder"], deps);
+		await stopCommand("my-builder", {}, deps);
 
 		expect(tmuxCalls.killSession).toHaveLength(1);
 		const { store } = openSessionStore(overstoryDir);
@@ -313,7 +291,7 @@ describe("stopCommand stop behavior", () => {
 
 		// tmux session is NOT alive
 		const { deps, tmuxCalls } = makeDeps({ [session.tmuxSession]: false });
-		const output = await captureStdout(() => stopCommand(["my-builder"], deps));
+		const output = await captureStdout(() => stopCommand("my-builder", {}, deps));
 
 		expect(output).toContain("Tmux session was already dead");
 		expect(tmuxCalls.killSession).toHaveLength(0);
@@ -332,7 +310,7 @@ describe("stopCommand --json output", () => {
 		saveSessionsToDb([session]);
 
 		const { deps } = makeDeps({ [session.tmuxSession]: true });
-		const output = await captureStdout(() => stopCommand(["my-builder", "--json"], deps));
+		const output = await captureStdout(() => stopCommand("my-builder", { json: true }, deps));
 
 		const parsed = JSON.parse(output.trim()) as Record<string, unknown>;
 		expect(parsed.stopped).toBe(true);
@@ -350,7 +328,7 @@ describe("stopCommand --json output", () => {
 
 		const { deps } = makeDeps({ [session.tmuxSession]: true });
 		const output = await captureStdout(() =>
-			stopCommand(["my-builder", "--json", "--force"], deps),
+			stopCommand("my-builder", { json: true, force: true }, deps),
 		);
 
 		const parsed = JSON.parse(output.trim()) as Record<string, unknown>;
@@ -364,7 +342,9 @@ describe("stopCommand --clean-worktree", () => {
 		saveSessionsToDb([session]);
 
 		const { deps, worktreeCalls } = makeDeps({ [session.tmuxSession]: true });
-		const output = await captureStdout(() => stopCommand(["my-builder", "--clean-worktree"], deps));
+		const output = await captureStdout(() =>
+			stopCommand("my-builder", { cleanWorktree: true }, deps),
+		);
 
 		expect(output).toContain(`Worktree removed: ${session.worktreePath}`);
 		expect(worktreeCalls.remove).toHaveLength(1);
@@ -376,7 +356,9 @@ describe("stopCommand --clean-worktree", () => {
 		saveSessionsToDb([session]);
 
 		const { deps, worktreeCalls } = makeDeps({ [session.tmuxSession]: true });
-		await captureStdout(() => stopCommand(["my-builder", "--clean-worktree", "--force"], deps));
+		await captureStdout(() =>
+			stopCommand("my-builder", { cleanWorktree: true, force: true }, deps),
+		);
 
 		expect(worktreeCalls.remove).toHaveLength(1);
 		expect(worktreeCalls.remove[0]?.options?.force).toBe(true);
@@ -389,7 +371,7 @@ describe("stopCommand --clean-worktree", () => {
 
 		const { deps } = makeDeps({ [session.tmuxSession]: true }, { shouldFail: true });
 		const { stderr, stdout } = await captureStderr(() =>
-			stopCommand(["my-builder", "--clean-worktree"], deps),
+			stopCommand("my-builder", { cleanWorktree: true }, deps),
 		);
 
 		// Agent was still stopped
@@ -410,7 +392,7 @@ describe("stopCommand --clean-worktree", () => {
 
 		const { deps } = makeDeps({ [session.tmuxSession]: true }, { shouldFail: true });
 		const { stdout } = await captureStderr(() =>
-			stopCommand(["my-builder", "--clean-worktree", "--json"], deps),
+			stopCommand("my-builder", { cleanWorktree: true, json: true }, deps),
 		);
 
 		const parsed = JSON.parse(stdout.trim()) as Record<string, unknown>;

package/src/commands/stop.ts

@@ -15,6 +15,12 @@ import { openSessionStore } from "../sessions/compat.ts";
 import { removeWorktree } from "../worktree/manager.ts";
 import { isSessionAlive, killSession } from "../worktree/tmux.ts";
 
+export interface StopOptions {
+	force?: boolean;
+	cleanWorktree?: boolean;
+	json?: boolean;
+}
+
 /** Dependency injection for testing. Uses real implementations when omitted. */
 export interface StopDeps {
 	_tmux?: {
@@ -30,50 +36,29 @@ export interface StopDeps {
 	};
 }
 
-const STOP_HELP = `overstory stop — Terminate a running agent
-
-Usage: overstory stop <agent-name> [flags]
-
-Arguments:
-  <agent-name>          Name of the agent to stop
-
-Options:
-  --force               Force kill and force-delete branch when cleaning worktree
-  --clean-worktree      Remove the agent's worktree after stopping
-  --json                Output as JSON
-  --help, -h            Show this help
-
-Examples:
-  overstory stop my-builder
-  overstory stop my-builder --clean-worktree
-  overstory stop my-builder --clean-worktree --force
-  overstory stop my-builder --json`;
-
 /**
  * Entry point for `overstory stop <agent-name>`.
  *
- * @param args - CLI arguments after "stop"
+ * @param agentName - Name of the agent to stop
+ * @param opts - Command options
  * @param deps - Optional dependency injection for testing (tmux, worktree)
  */
-export async function stopCommand(args: string[], deps: StopDeps = {}): Promise<void> {
-	if (args.includes("--help") || args.includes("-h")) {
-		process.stdout.write(`${STOP_HELP}\n`);
-		return;
-	}
-
-	const json = args.includes("--json");
-	const force = args.includes("--force");
-	const cleanWorktree = args.includes("--clean-worktree");
-
-	// First non-flag arg is the agent name
-	const agentName = args.find((a) => !a.startsWith("-"));
-	if (!agentName) {
+export async function stopCommand(
+	agentName: string,
+	opts: StopOptions,
+	deps: StopDeps = {},
+): Promise<void> {
+	if (!agentName || agentName.trim().length === 0) {
 		throw new ValidationError("Missing required argument: <agent-name>", {
 			field: "agentName",
 			value: "",
 		});
 	}
 
+	const json = opts.json ?? false;
+	const force = opts.force ?? false;
+	const cleanWorktree = opts.cleanWorktree ?? false;
+
 	const tmux = deps._tmux ?? { isSessionAlive, killSession };
 	const worktree = deps._worktree ?? { remove: removeWorktree };
 

package/src/commands/supervisor.test.ts

@@ -11,10 +11,10 @@ import { buildSupervisorBeacon, supervisorCommand } from "./supervisor.ts";
  */
 
 describe("buildSupervisorBeacon", () => {
-	test("contains agent name and beadId from opts", () => {
+	test("contains agent name and taskId from opts", () => {
 		const beacon = buildSupervisorBeacon({
 			name: "supervisor-1",
-			beadId: "task-abc123",
+			taskId: "task-abc123",
 			depth: 1,
 			parent: "coordinator",
 		});
@@ -26,7 +26,7 @@ describe("buildSupervisorBeacon", () => {
 	test("contains [OVERSTORY] prefix", () => {
 		const beacon = buildSupervisorBeacon({
 			name: "supervisor-1",
-			beadId: "task-1",
+			taskId: "task-1",
 			depth: 1,
 			parent: "coordinator",
 		});
@@ -37,7 +37,7 @@ describe("buildSupervisorBeacon", () => {
 	test("contains (supervisor) designation", () => {
 		const beacon = buildSupervisorBeacon({
 			name: "supervisor-1",
-			beadId: "task-1",
+			taskId: "task-1",
 			depth: 1,
 			parent: "coordinator",
 		});
@@ -48,7 +48,7 @@ describe("buildSupervisorBeacon", () => {
 	test("contains depth and parent info from opts", () => {
 		const beacon = buildSupervisorBeacon({
 			name: "supervisor-1",
-			beadId: "task-1",
+			taskId: "task-1",
 			depth: 2,
 			parent: "lead-cli",
 		});
@@ -60,7 +60,7 @@ describe("buildSupervisorBeacon", () => {
 	test("contains startup instructions", () => {
 		const beacon = buildSupervisorBeacon({
 			name: "supervisor-1",
-			beadId: "task-1",
+			taskId: "task-1",
 			depth: 1,
 			parent: "coordinator",
 		});
@@ -71,7 +71,7 @@ describe("buildSupervisorBeacon", () => {
 		// Should include mail check with agent name
 		expect(beacon).toContain("overstory mail check --agent supervisor-1");
 
-		// Should include bd show with beadId
+		// Should include bd show with taskId
 		expect(beacon).toContain("bd show task-1");
 	});
 
@@ -79,13 +79,13 @@ describe("buildSupervisorBeacon", () => {
 		const before = new Date();
 		const beacon = buildSupervisorBeacon({
 			name: "supervisor-1",
-			beadId: "task-1",
+			taskId: "task-1",
 			depth: 1,
 			parent: "coordinator",
 		});
 		const after = new Date();
 
-		// Extract timestamp from beacon (format: [OVERSTORY] {name} (supervisor) {timestamp} task:{beadId})
+		// Extract timestamp from beacon (format: [OVERSTORY] {name} (supervisor) {timestamp} task:{taskId})
 		const timestampMatch = beacon.match(/\(supervisor\)\s+(\S+)\s+task:/);
 		expect(timestampMatch).toBeTruthy();
 
@@ -111,12 +111,10 @@ describe("supervisorCommand", () => {
 
 		try {
 			await supervisorCommand(["--help"]);
-			expect(output).toContain("overstory supervisor");
+			expect(output).toContain("supervisor");
 			expect(output).toContain("start");
 			expect(output).toContain("stop");
 			expect(output).toContain("status");
-			expect(output).toContain("--task");
-			expect(output).toContain("--name");
 		} finally {
 			process.stdout.write = originalWrite;
 		}
@@ -132,7 +130,7 @@ describe("supervisorCommand", () => {
 
 		try {
 			await supervisorCommand(["-h"]);
-			expect(output).toContain("overstory supervisor");
+			expect(output).toContain("supervisor");
 		} finally {
 			process.stdout.write = originalWrite;
 		}
@@ -148,7 +146,7 @@ describe("supervisorCommand", () => {
 
 		try {
 			await supervisorCommand([]);
-			expect(output).toContain("overstory supervisor");
+			expect(output).toContain("supervisor");
 		} finally {
 			process.stdout.write = originalWrite;
 		}