@katyella/legio 0.1.0

package/src/commands/status.ts

@@ -0,0 +1,339 @@
+/**
+ * CLI command: legio status [--json] [--watch]
+ *
+ * Shows active agents, worktree status, beads summary, mail queue depth,
+ * and merge queue state. --watch mode uses polling for live updates.
+ */
+
+import { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { loadConfig } from "../config.ts";
+import { ValidationError } from "../errors.ts";
+import { createMailStore } from "../mail/store.ts";
+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 { listWorktrees } from "../worktree/manager.ts";
+import { listSessions } from "../worktree/tmux.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 duration in ms to a human-readable string.
+ */
+function formatDuration(ms: number): string {
+	const seconds = Math.floor(ms / 1000);
+	if (seconds < 60) return `${seconds}s`;
+	const minutes = Math.floor(seconds / 60);
+	const remainSec = seconds % 60;
+	if (minutes < 60) return `${minutes}m ${remainSec}s`;
+	const hours = Math.floor(minutes / 60);
+	const remainMin = minutes % 60;
+	return `${hours}h ${remainMin}m`;
+}
+
+export interface VerboseAgentDetail {
+	worktreePath: string;
+	logsDir: string;
+	lastMailSent: string | null;
+	lastMailReceived: string | null;
+	capability: string;
+}
+
+export interface StatusData {
+	agents: AgentSession[];
+	worktrees: Array<{ path: string; branch: string; head: string }>;
+	tmuxSessions: Array<{ name: string; pid: number }>;
+	unreadMailCount: number;
+	mergeQueueCount: number;
+	recentMetricsCount: number;
+	verboseDetails?: Record<string, VerboseAgentDetail>;
+}
+
+/**
+ * Gather all status data.
+ * @param agentName - Which agent's perspective for unread mail count (default "orchestrator")
+ * @param verbose - When true, collect extra per-agent detail (worktree path, logs dir, last mail)
+ */
+export async function gatherStatus(
+	root: string,
+	agentName = "orchestrator",
+	verbose = false,
+): Promise<StatusData> {
+	const legioDir = join(root, ".legio");
+	const { store } = openSessionStore(legioDir);
+
+	let sessions: AgentSession[];
+	try {
+		const currentRunPath = join(legioDir, "current-run.txt");
+		let runId: string | undefined;
+		try {
+			runId = (await readFile(currentRunPath, "utf8")).trim();
+		} catch {
+			// current-run.txt does not exist
+		}
+		sessions = runId ? store.getByRunIncludeOrphans(runId) : store.getActive();
+
+		const worktrees = await listWorktrees(root);
+
+		let tmuxSessions: Array<{ name: string; pid: number }> = [];
+		try {
+			tmuxSessions = await listSessions();
+		} catch {
+			// tmux might not be running
+		}
+
+		// Reconcile agent states: if tmux session is dead but agent state
+		// indicates it should be alive, mark it as zombie
+		for (const session of sessions) {
+			if (session.state === "booting" || session.state === "working") {
+				const tmuxAlive = tmuxSessions.some((s) => s.name === session.tmuxSession);
+				if (!tmuxAlive) {
+					try {
+						store.updateState(session.agentName, "zombie");
+						session.state = "zombie";
+					} catch {
+						// Best effort: don't fail status display if update fails
+					}
+				}
+			}
+		}
+
+		let unreadMailCount = 0;
+		let mailStore: ReturnType<typeof createMailStore> | null = null;
+		try {
+			const mailDbPath = join(root, ".legio", "mail.db");
+			let mailDbExists = false;
+			try {
+				await access(mailDbPath);
+				mailDbExists = true;
+			} catch {
+				/* not found */
+			}
+			if (mailDbExists) {
+				mailStore = createMailStore(mailDbPath);
+				const unread = mailStore.getAll({ to: agentName, unread: true });
+				unreadMailCount = unread.length;
+			}
+		} catch {
+			// mail db might not exist
+		}
+
+		let mergeQueueCount = 0;
+		try {
+			const queuePath = join(root, ".legio", "merge-queue.db");
+			const queue = createMergeQueue(queuePath);
+			mergeQueueCount = queue.list("pending").length;
+			queue.close();
+		} catch {
+			// queue might not exist
+		}
+
+		let recentMetricsCount = 0;
+		try {
+			const metricsDbPath = join(root, ".legio", "metrics.db");
+			let metricsDbExists = false;
+			try {
+				await access(metricsDbPath);
+				metricsDbExists = true;
+			} catch {
+				/* not found */
+			}
+			if (metricsDbExists) {
+				const metricsStore = createMetricsStore(metricsDbPath);
+				recentMetricsCount = metricsStore.getRecentSessions(100).length;
+				metricsStore.close();
+			}
+		} catch {
+			// metrics db might not exist
+		}
+
+		let verboseDetails: Record<string, VerboseAgentDetail> | undefined;
+		if (verbose && sessions.length > 0) {
+			verboseDetails = {};
+			for (const session of sessions) {
+				const logsDir = join(root, ".legio", "logs", session.agentName);
+
+				let lastMailSent: string | null = null;
+				let lastMailReceived: string | null = null;
+				if (mailStore) {
+					try {
+						const sent = mailStore.getAll({ from: session.agentName });
+						if (sent.length > 0 && sent[0]) {
+							lastMailSent = sent[0].createdAt;
+						}
+						const received = mailStore.getAll({ to: session.agentName });
+						if (received.length > 0 && received[0]) {
+							lastMailReceived = received[0].createdAt;
+						}
+					} catch {
+						// Best effort
+					}
+				}
+
+				verboseDetails[session.agentName] = {
+					worktreePath: session.worktreePath,
+					logsDir,
+					lastMailSent,
+					lastMailReceived,
+					capability: session.capability,
+				};
+			}
+		}
+
+		if (mailStore) {
+			mailStore.close();
+		}
+
+		return {
+			agents: sessions,
+			worktrees,
+			tmuxSessions,
+			unreadMailCount,
+			mergeQueueCount,
+			recentMetricsCount,
+			verboseDetails,
+		};
+	} finally {
+		store.close();
+	}
+}
+
+/**
+ * Print status in human-readable format.
+ */
+export function printStatus(data: StatusData): void {
+	const now = Date.now();
+	const w = process.stdout.write.bind(process.stdout);
+
+	w("📊 Legio Status\n");
+	w(`${"═".repeat(60)}\n\n`);
+
+	// Active agents
+	const active = data.agents.filter((a) => a.state !== "zombie" && a.state !== "completed");
+	w(`🤖 Agents: ${active.length} active\n`);
+	if (active.length > 0) {
+		for (const agent of active) {
+			const endTime =
+				agent.state === "completed" || agent.state === "zombie"
+					? new Date(agent.lastActivity).getTime()
+					: now;
+			const duration = formatDuration(endTime - new Date(agent.startedAt).getTime());
+			const tmuxAlive = data.tmuxSessions.some((s) => s.name === agent.tmuxSession);
+			const aliveMarker = tmuxAlive ? "●" : "○";
+			w(`   ${aliveMarker} ${agent.agentName} [${agent.capability}] `);
+			w(`${agent.state} | ${agent.beadId} | ${duration}\n`);
+
+			const detail = data.verboseDetails?.[agent.agentName];
+			if (detail) {
+				w(`     Worktree: ${detail.worktreePath}\n`);
+				w(`     Logs:     ${detail.logsDir}\n`);
+				w(`     Mail sent: ${detail.lastMailSent ?? "none"}`);
+				w(` | received: ${detail.lastMailReceived ?? "none"}\n`);
+			}
+		}
+	} else {
+		w("   No active agents\n");
+	}
+	w("\n");
+
+	// Worktrees
+	const legioWts = data.worktrees.filter((wt) => wt.branch.startsWith("legio/"));
+	w(`🌳 Worktrees: ${legioWts.length}\n`);
+	for (const wt of legioWts) {
+		w(`   ${wt.branch}\n`);
+	}
+	if (legioWts.length === 0) {
+		w("   No agent worktrees\n");
+	}
+	w("\n");
+
+	// Mail
+	w(`📬 Mail: ${data.unreadMailCount} unread\n`);
+
+	// Merge queue
+	w(`🔀 Merge queue: ${data.mergeQueueCount} pending\n`);
+
+	// Metrics
+	w(`📈 Sessions recorded: ${data.recentMetricsCount}\n`);
+}
+
+/**
+ * Entry point for `legio status [--json] [--watch]`.
+ */
+const STATUS_HELP = `legio status — Show all active agents and project state
+
+Usage: legio status [--json] [--verbose] [--agent <name>]
+
+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)
+  --watch            (deprecated) Use 'legio 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;
+	}
+
+	const json = hasFlag(args, "--json");
+	const watch = hasFlag(args, "--watch");
+	const verbose = hasFlag(args, "--verbose");
+	const intervalStr = getFlag(args, "--interval");
+	const interval = intervalStr ? Number.parseInt(intervalStr, 10) : 3000;
+
+	if (Number.isNaN(interval) || interval < 500) {
+		throw new ValidationError("--interval must be a number >= 500 (milliseconds)", {
+			field: "interval",
+			value: intervalStr,
+		});
+	}
+
+	const agentName = getFlag(args, "--agent") ?? "orchestrator";
+
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const root = config.project.root;
+
+	if (watch) {
+		process.stderr.write(
+			"⚠️  --watch is deprecated. Use 'legio dashboard' for live monitoring.\n\n",
+		);
+		// Polling loop (kept for one release cycle)
+		while (true) {
+			// Clear screen
+			process.stdout.write("\x1b[2J\x1b[H");
+			const data = await gatherStatus(root, agentName, verbose);
+			if (json) {
+				process.stdout.write(`${JSON.stringify(data, null, "\t")}\n`);
+			} else {
+				printStatus(data);
+			}
+			await new Promise((resolve) => setTimeout(resolve, interval));
+		}
+	} else {
+		const data = await gatherStatus(root, agentName, verbose);
+		if (json) {
+			process.stdout.write(`${JSON.stringify(data, null, "\t")}\n`);
+		} else {
+			printStatus(data);
+		}
+	}
+}

package/src/commands/stop.test.ts

@@ -0,0 +1,357 @@
+/**
+ * Tests for legio stop command.
+ *
+ * Uses real temp directories, real git repos, and real SQLite session stores.
+ * Tmux operations are injected via StopDeps._tmux DI to avoid real tmux calls
+ * in CI (real tmux would interfere with developer sessions).
+ *
+ * WHY DI instead of mock.module: mock.module() in vitest is process-global
+ * and leaks across test files. DI keeps mocks scoped to each test invocation.
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { openSessionStore } from "../sessions/compat.ts";
+import { cleanupTempDir, createTempGitRepo } from "../test-helpers.ts";
+import type { AgentSession } from "../types.ts";
+import { type StopDeps, stopCommand } from "./stop.ts";
+
+// ---------------------------------------------------------------------------
+// Fake tmux helper
+// ---------------------------------------------------------------------------
+
+interface TmuxCallTracker {
+	isSessionAlive: Array<{ name: string; result: boolean }>;
+	killSession: Array<{ name: string }>;
+}
+
+/** Build a fake tmux DI that tracks calls and reports sessions as alive/dead. */
+function makeFakeTmux(aliveMap: Record<string, boolean> = {}): {
+	tmux: NonNullable<StopDeps["_tmux"]>;
+	calls: TmuxCallTracker;
+} {
+	const calls: TmuxCallTracker = { isSessionAlive: [], killSession: [] };
+	const tmux: NonNullable<StopDeps["_tmux"]> = {
+		isSessionAlive: async (name: string): Promise<boolean> => {
+			const alive = aliveMap[name] ?? false;
+			calls.isSessionAlive.push({ name, result: alive });
+			return alive;
+		},
+		killSession: async (name: string): Promise<void> => {
+			calls.killSession.push({ name });
+		},
+	};
+	return { tmux, calls };
+}
+
+// ---------------------------------------------------------------------------
+// Test fixtures
+// ---------------------------------------------------------------------------
+
+let tempDir: string;
+let legioDir: string;
+const originalCwd = process.cwd();
+
+/** Make a minimal AgentSession for inserting into the store. */
+function makeSession(overrides: Partial<AgentSession> = {}): AgentSession {
+	return {
+		id: `session-${Date.now()}-${Math.random()}`,
+		agentName: "test-builder",
+		capability: "builder",
+		worktreePath: join(tempDir, ".legio", "worktrees", "test-builder"),
+		branchName: "legio/test-builder/legio-abc1",
+		beadId: "legio-abc1",
+		tmuxSession: "legio-test-project-test-builder",
+		state: "working",
+		pid: null,
+		parentAgent: null,
+		depth: 2,
+		runId: null,
+		startedAt: new Date().toISOString(),
+		lastActivity: new Date().toISOString(),
+		escalationLevel: 0,
+		stalledSince: null,
+		...overrides,
+	};
+}
+
+/** Capture stdout output during an async call. */
+async function captureStdout(fn: () => Promise<void>): Promise<string> {
+	const chunks: string[] = [];
+	const orig = process.stdout.write;
+	process.stdout.write = ((chunk: unknown) => {
+		chunks.push(String(chunk));
+		return true;
+	}) as typeof process.stdout.write;
+	try {
+		await fn();
+	} finally {
+		process.stdout.write = orig;
+	}
+	return chunks.join("");
+}
+
+// ---------------------------------------------------------------------------
+// Setup / teardown
+// ---------------------------------------------------------------------------
+
+beforeEach(async () => {
+	process.chdir(originalCwd);
+	tempDir = await createTempGitRepo();
+	legioDir = join(tempDir, ".legio");
+	await mkdir(legioDir, { recursive: true });
+
+	// Minimal config.yaml so loadConfig succeeds
+	await writeFile(
+		join(legioDir, "config.yaml"),
+		["project:", "  name: test-project", `  root: ${tempDir}`, "  canonicalBranch: main"].join(
+			"\n",
+		),
+	);
+
+	process.chdir(tempDir);
+});
+
+afterEach(async () => {
+	process.chdir(originalCwd);
+	await cleanupTempDir(tempDir);
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("stopCommand — help", () => {
+	it("prints help for --help", async () => {
+		const { tmux } = makeFakeTmux();
+		const out = await captureStdout(async () => {
+			await stopCommand(["--help"], { _tmux: tmux, _projectRoot: tempDir });
+		});
+		expect(out).toContain("legio stop");
+		expect(out).toContain("--agent");
+		expect(out).toContain("--json");
+	});
+
+	it("prints help for -h", async () => {
+		const { tmux } = makeFakeTmux();
+		const out = await captureStdout(async () => {
+			await stopCommand(["-h"], { _tmux: tmux, _projectRoot: tempDir });
+		});
+		expect(out).toContain("legio stop");
+	});
+});
+
+describe("stopCommand — nothing to stop", () => {
+	it("prints Nothing to stop when no active sessions", async () => {
+		const { tmux, calls } = makeFakeTmux();
+		const out = await captureStdout(async () => {
+			await stopCommand([], { _tmux: tmux, _projectRoot: tempDir });
+		});
+		expect(out).toContain("Nothing to stop");
+		expect(calls.killSession).toHaveLength(0);
+	});
+
+	it("outputs JSON with nothingToStop=true and empty stopped array", async () => {
+		const { tmux } = makeFakeTmux();
+		const out = await captureStdout(async () => {
+			await stopCommand(["--json"], { _tmux: tmux, _projectRoot: tempDir });
+		});
+		const parsed = JSON.parse(out.trim()) as { stopped: string[]; nothingToStop: boolean };
+		expect(parsed.nothingToStop).toBe(true);
+		expect(parsed.stopped).toHaveLength(0);
+	});
+});
+
+describe("stopCommand — single session", () => {
+	it("kills a live tmux session and marks it completed", async () => {
+		// Insert a session into the real store
+		const { store } = openSessionStore(legioDir);
+		const session = makeSession({
+			agentName: "my-builder",
+			tmuxSession: "legio-test-project-my-builder",
+		});
+		store.upsert(session);
+		store.close();
+
+		const { tmux, calls } = makeFakeTmux({ "legio-test-project-my-builder": true });
+
+		const out = await captureStdout(async () => {
+			await stopCommand([], { _tmux: tmux, _projectRoot: tempDir });
+		});
+
+		expect(calls.killSession).toHaveLength(1);
+		expect(calls.killSession[0]?.name).toBe("legio-test-project-my-builder");
+		expect(out).toContain("my-builder");
+		expect(out).toContain("Stopped 1 agent");
+
+		// Verify session is marked completed
+		const { store: store2 } = openSessionStore(legioDir);
+		const updated = store2.getByName("my-builder");
+		store2.close();
+		expect(updated?.state).toBe("completed");
+	});
+
+	it("skips killSession when tmux session is already dead", async () => {
+		const { store } = openSessionStore(legioDir);
+		store.upsert(makeSession({ agentName: "dead-builder", tmuxSession: "legio-dead" }));
+		store.close();
+
+		const { tmux, calls } = makeFakeTmux({ "legio-dead": false }); // dead
+
+		await captureStdout(async () => {
+			await stopCommand([], { _tmux: tmux, _projectRoot: tempDir });
+		});
+
+		expect(calls.isSessionAlive).toHaveLength(1);
+		expect(calls.killSession).toHaveLength(0); // skip kill for dead sessions
+	});
+
+	it("outputs JSON with stopped agent name", async () => {
+		const { store } = openSessionStore(legioDir);
+		store.upsert(makeSession({ agentName: "json-builder", tmuxSession: "legio-json" }));
+		store.close();
+
+		const { tmux } = makeFakeTmux({ "legio-json": true });
+		const out = await captureStdout(async () => {
+			await stopCommand(["--json"], { _tmux: tmux, _projectRoot: tempDir });
+		});
+
+		const parsed = JSON.parse(out.trim()) as { stopped: string[]; nothingToStop: boolean };
+		expect(parsed.nothingToStop).toBe(false);
+		expect(parsed.stopped).toContain("json-builder");
+	});
+});
+
+describe("stopCommand — deepest-first ordering", () => {
+	it("kills deeper sessions before shallower ones", async () => {
+		const { store } = openSessionStore(legioDir);
+		// Insert a lead (depth=1) and a builder (depth=2) — builder should die first
+		store.upsert(
+			makeSession({
+				agentName: "my-lead",
+				depth: 1,
+				tmuxSession: "legio-lead",
+			}),
+		);
+		store.upsert(
+			makeSession({
+				agentName: "my-builder",
+				depth: 2,
+				tmuxSession: "legio-builder",
+			}),
+		);
+		store.close();
+
+		const killOrder: string[] = [];
+		const tmux: NonNullable<StopDeps["_tmux"]> = {
+			isSessionAlive: async () => true,
+			killSession: async (name: string) => {
+				killOrder.push(name);
+			},
+		};
+
+		await captureStdout(async () => {
+			await stopCommand([], { _tmux: tmux, _projectRoot: tempDir });
+		});
+
+		// Builder (depth 2) should die before lead (depth 1)
+		expect(killOrder[0]).toBe("legio-builder");
+		expect(killOrder[1]).toBe("legio-lead");
+	});
+
+	it("handles sessions at equal depth in any order", async () => {
+		const { store } = openSessionStore(legioDir);
+		store.upsert(makeSession({ agentName: "builder-a", depth: 2, tmuxSession: "legio-a" }));
+		store.upsert(makeSession({ agentName: "builder-b", depth: 2, tmuxSession: "legio-b" }));
+		store.close();
+
+		const killOrder: string[] = [];
+		const tmux: NonNullable<StopDeps["_tmux"]> = {
+			isSessionAlive: async () => true,
+			killSession: async (name: string) => {
+				killOrder.push(name);
+			},
+		};
+
+		await captureStdout(async () => {
+			await stopCommand([], { _tmux: tmux, _projectRoot: tempDir });
+		});
+
+		// Both should be killed, order within same depth is unspecified
+		expect(killOrder).toHaveLength(2);
+		expect(killOrder).toContain("legio-a");
+		expect(killOrder).toContain("legio-b");
+	});
+
+	it("correctly orders 3 levels deep", async () => {
+		const { store } = openSessionStore(legioDir);
+		store.upsert(makeSession({ agentName: "coord", depth: 0, tmuxSession: "legio-coord" }));
+		store.upsert(makeSession({ agentName: "lead", depth: 1, tmuxSession: "legio-lead" }));
+		store.upsert(makeSession({ agentName: "builder", depth: 2, tmuxSession: "legio-builder" }));
+		store.close();
+
+		const killOrder: string[] = [];
+		const tmux: NonNullable<StopDeps["_tmux"]> = {
+			isSessionAlive: async () => true,
+			killSession: async (name: string) => {
+				killOrder.push(name);
+			},
+		};
+
+		await captureStdout(async () => {
+			await stopCommand([], { _tmux: tmux, _projectRoot: tempDir });
+		});
+
+		expect(killOrder[0]).toBe("legio-builder");
+		expect(killOrder[1]).toBe("legio-lead");
+		expect(killOrder[2]).toBe("legio-coord");
+	});
+});
+
+describe("stopCommand — --agent filter", () => {
+	it("stops only the specified agent when --agent is given", async () => {
+		const { store } = openSessionStore(legioDir);
+		store.upsert(makeSession({ agentName: "target-agent", tmuxSession: "legio-target" }));
+		store.upsert(makeSession({ agentName: "other-agent", tmuxSession: "legio-other" }));
+		store.close();
+
+		const { tmux, calls } = makeFakeTmux({
+			"legio-target": true,
+			"legio-other": true,
+		});
+
+		const out = await captureStdout(async () => {
+			await stopCommand(["--agent", "target-agent"], { _tmux: tmux, _projectRoot: tempDir });
+		});
+
+		// Only target should be killed
+		expect(calls.killSession).toHaveLength(1);
+		expect(calls.killSession[0]?.name).toBe("legio-target");
+		expect(out).toContain("target-agent");
+	});
+
+	it("throws AgentError when --agent specifies a non-existent agent", async () => {
+		const { tmux } = makeFakeTmux();
+		await expect(
+			stopCommand(["--agent", "nonexistent"], { _tmux: tmux, _projectRoot: tempDir }),
+		).rejects.toThrow("No session found for agent 'nonexistent'");
+	});
+});
+
+describe("stopCommand — completed sessions not stopped again", () => {
+	it("does not stop sessions already in completed state", async () => {
+		const { store } = openSessionStore(legioDir);
+		// Insert a completed session — should not appear in getActive()
+		store.upsert(makeSession({ agentName: "done-agent", state: "completed" }));
+		store.close();
+
+		const { tmux, calls } = makeFakeTmux();
+		const out = await captureStdout(async () => {
+			await stopCommand([], { _tmux: tmux, _projectRoot: tempDir });
+		});
+
+		expect(calls.killSession).toHaveLength(0);
+		expect(out).toContain("Nothing to stop");
+	});
+});