@os-eco/overstory-cli 0.6.1 → 0.6.5

package/src/commands/merge.ts

@@ -19,26 +19,17 @@ import { createMergeResolver } from "../merge/resolver.ts";
 import { createMulchClient } from "../mulch/client.ts";
 import type { MergeEntry, MergeResult } from "../types.ts";
 
-/**
- * Parse a named flag value from an args array.
- * Returns the value after the flag, or undefined if not present.
- */
-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];
-}
-
-/** Check if a boolean flag is present in the args. */
-function hasFlag(args: string[], flag: string): boolean {
-	return args.includes(flag);
+export interface MergeOptions {
+	branch?: string;
+	all?: boolean;
+	into?: string;
+	dryRun?: boolean;
+	json?: boolean;
 }
 
 /**
  * Extract agent name from a branch following the overstory naming convention.
- * Pattern: overstory/{agentName}/{beadId}
+ * Pattern: overstory/{agentName}/{taskId}
  * Falls back to "unknown" if the pattern does not match.
  */
 function parseAgentName(branchName: string): string {
@@ -50,8 +41,8 @@ function parseAgentName(branchName: string): string {
 }
 
 /**
- * Extract bead ID from a branch following the overstory naming convention.
- * Pattern: overstory/{agentName}/{beadId}
+ * Extract task ID from a branch following the overstory naming convention.
+ * Pattern: overstory/{agentName}/{taskId}
  * Falls back to "unknown" if the pattern does not match.
  */
 function parseBeadId(branchName: string): string {
@@ -98,7 +89,7 @@ function formatResult(result: MergeResult): string {
 	const statusIcon = result.success ? "Merged" : "Failed";
 	const lines: string[] = [
 		`Merging branch: ${result.entry.branchName}`,
-		`   Agent: ${result.entry.agentName} | Task: ${result.entry.beadId}`,
+		`   Agent: ${result.entry.agentName} | Task: ${result.entry.taskId}`,
 		`   Files: ${result.entry.filesModified.length} modified`,
 		`   Result: ${statusIcon} (tier: ${result.tier})`,
 	];
@@ -118,7 +109,7 @@ function formatResult(result: MergeResult): string {
 function formatDryRun(entry: MergeEntry): string {
 	const lines: string[] = [
 		`[dry-run] Branch: ${entry.branchName}`,
-		`   Agent: ${entry.agentName} | Task: ${entry.beadId}`,
+		`   Agent: ${entry.agentName} | Task: ${entry.taskId}`,
 		`   Status: ${entry.status}`,
 		`   Files: ${entry.filesModified.length} modified`,
 	];
@@ -135,35 +126,14 @@ function formatDryRun(entry: MergeEntry): string {
 /**
  * Entry point for `overstory merge [flags]`.
  *
- * Flags:
- *   --branch <name>  Merge a specific branch
- *   --all            Merge all pending branches in the queue
- *   --dry-run        Check for conflicts without actually merging
- *   --json           Output results as JSON
+ * @param opts - Command options
  */
-const MERGE_HELP = `overstory merge — Merge agent branches into canonical
-
-Usage: overstory merge --branch <name> | --all [--into <branch>] [--dry-run] [--json]
-
-Options:
-  --branch <name>   Merge a specific branch
-  --all             Merge all pending branches in the queue
-  --into <branch>   Target branch to merge into (default: config canonicalBranch)
-  --dry-run         Check for conflicts without actually merging
-  --json            Output results as JSON
-  --help, -h        Show this help`;
-
-export async function mergeCommand(args: string[]): Promise<void> {
-	if (args.includes("--help") || args.includes("-h")) {
-		process.stdout.write(`${MERGE_HELP}\n`);
-		return;
-	}
-
-	const branchName = getFlag(args, "--branch");
-	const all = hasFlag(args, "--all");
-	const into = getFlag(args, "--into");
-	const dryRun = hasFlag(args, "--dry-run");
-	const json = hasFlag(args, "--json");
+export async function mergeCommand(opts: MergeOptions): Promise<void> {
+	const branchName = opts.branch;
+	const all = opts.all ?? false;
+	const into = opts.into;
+	const dryRun = opts.dryRun ?? false;
+	const json = opts.json ?? false;
 
 	if (!branchName && !all) {
 		throw new ValidationError("Either --branch <name> or --all is required for overstory merge", {
@@ -206,7 +176,7 @@ export async function mergeCommand(args: string[]): Promise<void> {
 /**
  * Handle merging a specific branch.
  * If the branch is not in the queue, creates a new entry by detecting
- * agent name, bead ID, and modified files from git.
+ * agent name, task ID, and modified files from git.
  */
 async function handleBranch(
 	branchName: string,
@@ -241,12 +211,12 @@ async function handleBranch(
 		}
 
 		const agentName = parseAgentName(branchName);
-		const beadId = parseBeadId(branchName);
+		const taskId = parseBeadId(branchName);
 		const filesModified = await detectModifiedFiles(repoRoot, canonicalBranch, branchName);
 
 		entry = queue.enqueue({
 			branchName,
-			beadId,
+			taskId,
 			agentName,
 			filesModified,
 		});

package/src/commands/metrics.test.ts

@@ -54,7 +54,7 @@ describe("metricsCommand", () => {
 	function makeSession(overrides: Partial<SessionMetrics> = {}): SessionMetrics {
 		return {
 			agentName: "test-agent",
-			beadId: "bead-001",
+			taskId: "bead-001",
 			capability: "builder",
 			startedAt: new Date(Date.now() - 120_000).toISOString(),
 			completedAt: new Date().toISOString(),
@@ -77,7 +77,7 @@ describe("metricsCommand", () => {
 		await metricsCommand(["--help"]);
 		const out = output();
 
-		expect(out).toContain("overstory metrics");
+		expect(out).toContain("metrics");
 		expect(out).toContain("--last <n>");
 		expect(out).toContain("--json");
 		expect(out).toContain("--help");
@@ -87,7 +87,7 @@ describe("metricsCommand", () => {
 		await metricsCommand(["-h"]);
 		const out = output();
 
-		expect(out).toContain("overstory metrics");
+		expect(out).toContain("metrics");
 		expect(out).toContain("--last <n>");
 	});
 
@@ -177,7 +177,7 @@ describe("metricsCommand", () => {
 		store.recordSession(
 			makeSession({
 				agentName: "test-builder",
-				beadId: "bead-123",
+				taskId: "bead-123",
 				capability: "builder",
 			}),
 		);
@@ -190,7 +190,7 @@ describe("metricsCommand", () => {
 		const parsed = JSON.parse(out.trim()) as { sessions: SessionMetrics[] };
 		expect(parsed.sessions).toHaveLength(1);
 		expect(parsed.sessions[0]?.agentName).toBe("test-builder");
-		expect(parsed.sessions[0]?.beadId).toBe("bead-123");
+		expect(parsed.sessions[0]?.taskId).toBe("bead-123");
 		expect(parsed.sessions[0]?.capability).toBe("builder");
 	});
 
@@ -203,7 +203,7 @@ describe("metricsCommand", () => {
 			store.recordSession(
 				makeSession({
 					agentName: `agent-${i}`,
-					beadId: `bead-${i}`,
+					taskId: `bead-${i}`,
 					startedAt: new Date(Date.now() - (5 - i) * 1000).toISOString(),
 				}),
 			);
@@ -227,7 +227,7 @@ describe("metricsCommand", () => {
 			store.recordSession(
 				makeSession({
 					agentName: `agent-${i}`,
-					beadId: `bead-${i}`,
+					taskId: `bead-${i}`,
 				}),
 			);
 		}
@@ -363,7 +363,7 @@ describe("formatDuration helper", () => {
 	function makeSession(durationMs: number): SessionMetrics {
 		return {
 			agentName: "test-agent",
-			beadId: "bead-001",
+			taskId: "bead-001",
 			capability: "builder",
 			startedAt: new Date(Date.now() - durationMs).toISOString(),
 			completedAt: new Date().toISOString(),

package/src/commands/metrics.ts

@@ -6,22 +6,13 @@
  */
 
 import { join } from "node:path";
+import { Command } from "commander";
 import { loadConfig } from "../config.ts";
 import { createMetricsStore } from "../metrics/store.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);
+interface MetricsOpts {
+	last?: string;
+	json?: boolean;
 }
 
 /**
@@ -39,27 +30,9 @@ function formatDuration(ms: number): string {
 	return `${hours}h ${remainMin}m`;
 }
 
-/**
- * Entry point for `overstory metrics [--last <n>] [--json]`.
- */
-const METRICS_HELP = `overstory metrics — Show session metrics
-
-Usage: overstory metrics [--last <n>] [--json]
-
-Options:
-  --last <n>         Number of recent sessions to show (default: 20)
-  --json             Output as JSON
-  --help, -h         Show this help`;
-
-export async function metricsCommand(args: string[]): Promise<void> {
-	if (args.includes("--help") || args.includes("-h")) {
-		process.stdout.write(`${METRICS_HELP}\n`);
-		return;
-	}
-
-	const lastStr = getFlag(args, "--last");
-	const limit = lastStr ? Number.parseInt(lastStr, 10) : 20;
-	const json = hasFlag(args, "--json");
+async function executeMetrics(opts: MetricsOpts): Promise<void> {
+	const limit = opts.last ? Number.parseInt(opts.last, 10) : 20;
+	const json = opts.json ?? false;
 
 	const cwd = process.cwd();
 	const config = await loadConfig(cwd);
@@ -134,10 +107,36 @@ export async function metricsCommand(args: string[]): Promise<void> {
 			const status = s.completedAt ? "done" : "running";
 			const duration = formatDuration(s.durationMs);
 			process.stdout.write(
-				`  ${s.agentName} [${s.capability}] ${s.beadId} | ${status} | ${duration}\n`,
+				`  ${s.agentName} [${s.capability}] ${s.taskId} | ${status} | ${duration}\n`,
 			);
 		}
 	} finally {
 		store.close();
 	}
 }
+
+export function createMetricsCommand(): Command {
+	return new Command("metrics")
+		.description("Show session metrics")
+		.option("--last <n>", "Number of recent sessions to show (default: 20)")
+		.option("--json", "Output as JSON")
+		.action(async (opts: MetricsOpts) => {
+			await executeMetrics(opts);
+		});
+}
+
+export async function metricsCommand(args: string[]): Promise<void> {
+	const cmd = createMetricsCommand();
+	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/monitor.test.ts

@@ -89,7 +89,7 @@ describe("monitorCommand", () => {
 	test("--help prints help text containing 'overstory monitor'", async () => {
 		await monitorCommand(["--help"]);
 		const output = stdoutWrites.join("");
-		expect(output).toContain("overstory monitor");
+		expect(output).toContain("monitor");
 	});
 
 	test("--help prints help text containing 'start'", async () => {
@@ -113,13 +113,13 @@ describe("monitorCommand", () => {
 	test("-h prints help text", async () => {
 		await monitorCommand(["-h"]);
 		const output = stdoutWrites.join("");
-		expect(output).toContain("overstory monitor");
+		expect(output).toContain("monitor");
 	});
 
 	test("empty args [] shows help (same as --help)", async () => {
 		await monitorCommand([]);
 		const output = stdoutWrites.join("");
-		expect(output).toContain("overstory monitor");
+		expect(output).toContain("monitor");
 	});
 
 	test("unknown subcommand 'restart' throws ValidationError", async () => {

package/src/commands/monitor.ts

@@ -15,6 +15,7 @@
 
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
+import { Command } from "commander";
 import { deployHooks } from "../agents/hooks-deployer.ts";
 import { createIdentity, loadIdentity } from "../agents/identity.ts";
 import { createManifestLoader, resolveModel } from "../agents/manifest.ts";
@@ -50,15 +51,6 @@ export function buildMonitorBeacon(): string {
 	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.
  *
@@ -70,9 +62,8 @@ function resolveAttach(args: string[], isTTY: boolean): boolean {
  * 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);
+async function startMonitor(opts: { json: boolean; attach: boolean }): Promise<void> {
+	const { json, attach: shouldAttach } = opts;
 
 	if (isRunningAsRoot()) {
 		throw new AgentError(
@@ -118,8 +109,6 @@ async function startMonitor(args: string[]): Promise<void> {
 		}
 
 		// 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
@@ -146,7 +135,6 @@ async function startMonitor(args: string[]): Promise<void> {
 		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`;
@@ -168,7 +156,7 @@ async function startMonitor(args: string[]): Promise<void> {
 			capability: "monitor",
 			worktreePath: projectRoot, // Monitor uses project root, not a worktree
 			branchName: config.project.canonicalBranch, // Operates on canonical branch
-			beadId: "", // No specific bead assignment
+			taskId: "", // No specific bead assignment
 			tmuxSession,
 			state: "booting",
 			pid,
@@ -226,8 +214,8 @@ async function startMonitor(args: string[]): Promise<void> {
  * 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");
+async function stopMonitor(opts: { json: boolean }): Promise<void> {
+	const { json } = opts;
 	const cwd = process.cwd();
 	const config = await loadConfig(cwd);
 	const projectRoot = config.project.root;
@@ -273,8 +261,8 @@ async function stopMonitor(args: string[]): Promise<void> {
  *
  * Checks session registry and tmux liveness to report actual state.
  */
-async function statusMonitor(args: string[]): Promise<void> {
-	const json = args.includes("--json");
+async function statusMonitor(opts: { json: boolean }): Promise<void> {
+	const { json } = opts;
 	const cwd = process.cwd();
 	const config = await loadConfig(cwd);
 	const projectRoot = config.project.root;
@@ -301,8 +289,6 @@ async function statusMonitor(args: string[]): Promise<void> {
 		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);
@@ -335,56 +321,65 @@ async function statusMonitor(args: string[]): Promise<void> {
 	}
 }
 
-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
+export function createMonitorCommand(): Command {
+	const cmd = new Command("monitor").description("Manage the persistent Tier 2 monitor agent");
+
+	cmd
+		.command("start")
+		.description("Start the monitor (spawns Claude Code at project root)")
+		.option("--attach", "Always attach to tmux session after start")
+		.option("--no-attach", "Never attach to tmux session after start")
+		.option("--json", "Output as JSON")
+		.action(async (opts: { attach?: boolean; json?: boolean }) => {
+			// opts.attach = true if --attach, false if --no-attach, undefined if neither
+			const shouldAttach = opts.attach !== undefined ? opts.attach : !!process.stdout.isTTY;
+			await startMonitor({ json: opts.json ?? false, attach: shouldAttach });
+		});
 
-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
+	cmd
+		.command("stop")
+		.description("Stop the monitor (kills tmux session)")
+		.option("--json", "Output as JSON")
+		.action(async (opts: { json?: boolean }) => {
+			await stopMonitor({ json: opts.json ?? false });
+		});
 
-General options:
-  --json                   Output as JSON
-  --help, -h               Show this help
+	cmd
+		.command("status")
+		.description("Show monitor state")
+		.option("--json", "Output as JSON")
+		.action(async (opts: { json?: boolean }) => {
+			await statusMonitor({ json: opts.json ?? false });
+		});
 
-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`;
+	return cmd;
+}
 
 /**
  * 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`);
+	const cmd = createMonitorCommand();
+	cmd.exitOverride();
+
+	if (args.length === 0) {
+		process.stdout.write(cmd.helpInformation());
 		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 },
-			);
+	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;
+			}
+			if (code === "commander.unknownCommand") {
+				const message = err instanceof Error ? err.message : String(err);
+				throw new ValidationError(message, { field: "subcommand" });
+			}
+		}
+		throw err;
 	}
 }

package/src/commands/nudge.test.ts

@@ -46,7 +46,7 @@ function makeSession(overrides: Partial<AgentSession> = {}): AgentSession {
 		capability: "builder",
 		worktreePath: "/tmp/wt",
 		branchName: "overstory/test-agent/task-1",
-		beadId: "task-1",
+		taskId: "task-1",
 		tmuxSession: "overstory-test-agent",
 		state: "working",
 		pid: 12345,