@katyella/legio 0.1.0

package/src/commands/gateway.ts

@@ -0,0 +1,419 @@
+/**
+ * CLI command: legio gateway start|stop|status
+ *
+ * Manages the persistent gateway agent lifecycle. The gateway runs
+ * at the project root (NOT in a worktree), acts as a planning companion,
+ * and communicates via mail.
+ *
+ * Unlike regular agents spawned by sling, the gateway:
+ * - Has no worktree (operates on the main working tree)
+ * - Has no bead assignment (it plans and advises, not implements)
+ * - Has no overlay CLAUDE.md (context comes via mail + legio prime)
+ * - Persists across planning sessions
+ */
+
+import { spawnSync } from "node:child_process";
+import { access, mkdir, readFile, writeFile } 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";
+
+/** Default gateway agent name. */
+const GATEWAY_NAME = "gateway";
+
+/**
+ * Build the tmux session name for the gateway.
+ * Includes the project name to prevent cross-project collisions.
+ */
+function gatewayTmuxSession(projectName: string): string {
+	return `legio-${projectName}-${GATEWAY_NAME}`;
+}
+
+/**
+ * Check if a file exists at the given path.
+ */
+async function fileExists(path: string): Promise<boolean> {
+	try {
+		await access(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** Dependency injection for testing. Uses real implementations when omitted. */
+export interface GatewayDeps {
+	_tmux?: {
+		createSession: (
+			name: string,
+			cwd: string,
+			command: string,
+			env?: Record<string, string>,
+		) => Promise<number>;
+		isSessionAlive: (name: string) => Promise<boolean>;
+		killSession: (name: string) => Promise<void>;
+		sendKeys: (name: string, keys: string) => Promise<void>;
+	};
+	_sleep?: (ms: number) => Promise<void>;
+}
+
+/**
+ * Build the gateway startup beacon — the first message sent to the gateway
+ * via tmux send-keys after Claude Code initializes.
+ */
+export function buildGatewayBeacon(): string {
+	const timestamp = new Date().toISOString();
+	const parts = [
+		`[LEGIO] ${GATEWAY_NAME} (gateway) ${timestamp}`,
+		"Depth: 0 | Role: planning companion",
+		"READONLY: No Write/Edit",
+		"ISSUES: Use bd create",
+		`Startup: run mulch prime, check mail (legio mail check --agent ${GATEWAY_NAME}), respond to user`,
+	];
+	return parts.join(" — ");
+}
+
+/**
+ * Determine whether to auto-attach to the tmux session after starting.
+ * Exported for testing.
+ */
+export function resolveAttach(args: string[], isTTY: boolean): boolean {
+	if (args.includes("--attach")) return true;
+	if (args.includes("--no-attach")) return false;
+	return isTTY;
+}
+
+/**
+ * Start the gateway agent.
+ *
+ * 1. Verify no gateway is already running
+ * 2. Load config
+ * 3. Deploy hooks via deployHooks(projectRoot, GATEWAY_NAME, 'gateway')
+ * 4. Create identity if first run
+ * 5. Resolve model — default to 'sonnet'
+ * 6. Read agent def from .legio/agent-defs/gateway.md
+ * 7. Build settings JSON with skipDangerousModePermissionPrompt + appendSystemPrompt
+ * 8. Spawn tmux session at project root with Claude Code
+ * 9. Record session: capability 'gateway', worktreePath projectRoot, depth 0, parentAgent null
+ * 10. Send beacon after delay, optionally attach
+ */
+async function startGateway(args: string[], deps: GatewayDeps = {}): Promise<void> {
+	const tmux = deps._tmux ?? { createSession, isSessionAlive, killSession, sendKeys };
+	const sleep =
+		deps._sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+
+	const json = args.includes("--json");
+	const shouldAttach = resolveAttach(args, !!process.stdout.isTTY);
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const projectRoot = config.project.root;
+	const tmuxSession = gatewayTmuxSession(config.project.name);
+
+	// Check for existing gateway
+	const legioDir = join(projectRoot, ".legio");
+	const { store } = openSessionStore(legioDir);
+	try {
+		const existing = store.getByName(GATEWAY_NAME);
+
+		if (
+			existing &&
+			existing.capability === "gateway" &&
+			existing.state !== "completed" &&
+			existing.state !== "zombie"
+		) {
+			const alive = await tmux.isSessionAlive(existing.tmuxSession);
+			if (alive) {
+				throw new AgentError(
+					`Gateway is already running (tmux: ${existing.tmuxSession}, since: ${existing.startedAt})`,
+					{ agentName: GATEWAY_NAME },
+				);
+			}
+			// Session recorded but tmux is dead — mark as completed and continue
+			store.updateState(GATEWAY_NAME, "completed");
+		}
+
+		// Deploy hooks to the project root so the gateway gets event logging,
+		// mail check --inject, and activity tracking via the standard hook pipeline.
+		await deployHooks(projectRoot, GATEWAY_NAME, "gateway");
+
+		// Create gateway identity if first run
+		const identityBaseDir = join(projectRoot, ".legio", "agents");
+		await mkdir(identityBaseDir, { recursive: true });
+		const existingIdentity = await loadIdentity(identityBaseDir, GATEWAY_NAME);
+		if (!existingIdentity) {
+			await createIdentity(identityBaseDir, {
+				name: GATEWAY_NAME,
+				capability: "gateway",
+				created: new Date().toISOString(),
+				sessionsCompleted: 0,
+				expertiseDomains: config.mulch.enabled ? config.mulch.domains : [],
+				recentTasks: [],
+			});
+		}
+
+		// Resolve model from config > manifest > fallback (opus for gateway)
+		const manifestLoader = createManifestLoader(
+			join(projectRoot, config.agents.manifestPath),
+			join(projectRoot, config.agents.baseDir),
+		);
+		const manifest = await manifestLoader.load();
+		const model = resolveModel(config, manifest, "gateway", "opus");
+
+		// Build settings JSON file to skip the bypass dialog and inject the
+		// agent definition. Avoids --append-system-prompt's ERR_STREAM_DESTROYED
+		// crash with large payloads on Claude Code v2.1.50.
+		const agentDefPath = join(projectRoot, ".legio", "agent-defs", "gateway.md");
+		const settings: Record<string, unknown> = { skipDangerousModePermissionPrompt: true };
+		if (await fileExists(agentDefPath)) {
+			settings.appendSystemPrompt = await readFile(agentDefPath, "utf-8");
+		}
+		const settingsPath = join(legioDir, `settings-${GATEWAY_NAME}.json`);
+		await writeFile(settingsPath, JSON.stringify(settings), "utf-8");
+		const claudeCmd = `claude --model ${model} --dangerously-skip-permissions --settings ${settingsPath}`;
+		const pid = await tmux.createSession(tmuxSession, projectRoot, claudeCmd, {
+			LEGIO_AGENT_NAME: GATEWAY_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()}-${GATEWAY_NAME}`,
+			agentName: GATEWAY_NAME,
+			capability: "gateway",
+			worktreePath: projectRoot, // Gateway 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, // No parent
+			depth: 0,
+			runId: null,
+			startedAt: new Date().toISOString(),
+			lastActivity: new Date().toISOString(),
+			escalationLevel: 0,
+			stalledSince: null,
+		};
+
+		store.upsert(session);
+
+		// Write output BEFORE the blocking sleep+sendKeys so that callers
+		// reading stdout (e.g., runLegio in the server) get the response
+		// immediately and don't hang waiting for the pipe to close.
+		const output = {
+			agentName: GATEWAY_NAME,
+			capability: "gateway",
+			tmuxSession,
+			projectRoot,
+			pid,
+		};
+
+		if (json) {
+			process.stdout.write(`${JSON.stringify(output)}\n`);
+		} else {
+			process.stdout.write("Gateway started\n");
+			process.stdout.write(`  Tmux:    ${tmuxSession}\n`);
+			process.stdout.write(`  Root:    ${projectRoot}\n`);
+			process.stdout.write(`  PID:     ${pid}\n`);
+		}
+
+		// Send beacon after TUI initialization delay
+		await sleep(3_000);
+		const beacon = buildGatewayBeacon();
+		await tmux.sendKeys(tmuxSession, beacon);
+
+		// Follow-up Enter to ensure submission (same pattern as sling.ts)
+		await sleep(500);
+		await tmux.sendKeys(tmuxSession, "");
+
+		if (shouldAttach) {
+			spawnSync("tmux", ["attach-session", "-t", tmuxSession], {
+				stdio: ["inherit", "inherit", "inherit"],
+			});
+		}
+	} finally {
+		store.close();
+	}
+}
+
+/**
+ * Stop the gateway agent.
+ *
+ * 1. Find the active gateway session
+ * 2. Kill the tmux session (with process tree cleanup)
+ * 3. Mark session as completed in SessionStore
+ */
+async function stopGateway(args: string[], deps: GatewayDeps = {}): Promise<void> {
+	const tmux = deps._tmux ?? { createSession, isSessionAlive, killSession, sendKeys };
+
+	const json = args.includes("--json");
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const projectRoot = config.project.root;
+
+	const legioDir = join(projectRoot, ".legio");
+	const { store } = openSessionStore(legioDir);
+	try {
+		const session = store.getByName(GATEWAY_NAME);
+
+		if (
+			!session ||
+			session.capability !== "gateway" ||
+			session.state === "completed" ||
+			session.state === "zombie"
+		) {
+			throw new AgentError("No active gateway session found", {
+				agentName: GATEWAY_NAME,
+			});
+		}
+
+		// Kill tmux session with process tree cleanup
+		const alive = await tmux.isSessionAlive(session.tmuxSession);
+		if (alive) {
+			await tmux.killSession(session.tmuxSession);
+		}
+
+		// Update session state
+		store.updateState(GATEWAY_NAME, "completed");
+		store.updateLastActivity(GATEWAY_NAME);
+
+		if (json) {
+			process.stdout.write(`${JSON.stringify({ stopped: true, sessionId: session.id })}\n`);
+		} else {
+			process.stdout.write(`Gateway stopped (session: ${session.id})\n`);
+		}
+	} finally {
+		store.close();
+	}
+}
+
+/**
+ * Show gateway status.
+ *
+ * Checks session registry and tmux liveness to report actual state.
+ */
+async function statusGateway(args: string[], deps: GatewayDeps = {}): Promise<void> {
+	const tmux = deps._tmux ?? { createSession, isSessionAlive, killSession, sendKeys };
+
+	const json = args.includes("--json");
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const projectRoot = config.project.root;
+
+	const legioDir = join(projectRoot, ".legio");
+	const { store } = openSessionStore(legioDir);
+	try {
+		const session = store.getByName(GATEWAY_NAME);
+
+		if (
+			!session ||
+			session.capability !== "gateway" ||
+			session.state === "completed" ||
+			session.state === "zombie"
+		) {
+			if (json) {
+				process.stdout.write(`${JSON.stringify({ running: false })}\n`);
+			} else {
+				process.stdout.write("Gateway is not running\n");
+			}
+			return;
+		}
+
+		const alive = await tmux.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(GATEWAY_NAME, "zombie");
+			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(`Gateway: ${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 GATEWAY_HELP = `legio gateway — Manage the gateway planning agent
+
+Usage: legio gateway <subcommand> [flags]
+
+Subcommands:
+  start                    Start the gateway (spawns Claude Code at project root)
+  stop                     Stop the gateway (kills tmux session)
+  status                   Show gateway 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 gateway agent is a planning companion that:
+  - Helps decompose objectives into tasks
+  - Advises on architecture and approach
+  - Creates beads issues (bd create)
+  - Communicates via mail with the team`;
+
+/**
+ * Entry point for `legio gateway <subcommand>`.
+ *
+ * @param args - CLI arguments after "gateway"
+ * @param deps - Optional dependency injection for testing (tmux)
+ */
+export async function gatewayCommand(args: string[], deps: GatewayDeps = {}): Promise<void> {
+	if (args.includes("--help") || args.includes("-h") || args.length === 0) {
+		process.stdout.write(`${GATEWAY_HELP}\n`);
+		return;
+	}
+
+	const subcommand = args[0];
+	const subArgs = args.slice(1);
+
+	switch (subcommand) {
+		case "start":
+			await startGateway(subArgs, deps);
+			break;
+		case "stop":
+			await stopGateway(subArgs, deps);
+			break;
+		case "status":
+			await statusGateway(subArgs, deps);
+			break;
+		default:
+			throw new ValidationError(
+				`Unknown gateway subcommand: ${subcommand}. Run 'legio gateway --help' for usage.`,
+				{ field: "subcommand", value: subcommand },
+			);
+	}
+}

package/src/commands/group.test.ts

@@ -0,0 +1,262 @@
+/**
+ * Tests for legio group command.
+ *
+ * Uses real temp directories for groups.json I/O. Does NOT mock bd CLI --
+ * tests focus on the JSON storage layer and validation logic.
+ * The beads validation is tested with --skip-validation flag since
+ * bd is an external CLI not available in unit tests.
+ */
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { cleanupTempDir, createTempGitRepo } from "../test-helpers.ts";
+import type { TaskGroup } from "../types.ts";
+import { loadGroups } from "./group.ts";
+
+let tempDir: string;
+let legioDir: string;
+let groupsJsonPath: string;
+
+beforeEach(async () => {
+	tempDir = await createTempGitRepo();
+	legioDir = join(tempDir, ".legio");
+	await mkdir(legioDir, { recursive: true });
+	groupsJsonPath = join(legioDir, "groups.json");
+});
+
+afterEach(async () => {
+	await cleanupTempDir(tempDir);
+});
+
+/**
+ * Helper to write groups.json directly for test setup.
+ */
+async function writeGroups(groups: TaskGroup[]): Promise<void> {
+	await writeFile(groupsJsonPath, `${JSON.stringify(groups, null, "\t")}\n`);
+}
+
+/**
+ * Helper to read groups.json directly for assertions.
+ */
+async function readGroups(): Promise<TaskGroup[]> {
+	const text = await readFile(groupsJsonPath, "utf-8");
+	return JSON.parse(text) as TaskGroup[];
+}
+
+function makeGroup(overrides?: Partial<TaskGroup>): TaskGroup {
+	return {
+		id: `group-${crypto.randomUUID().slice(0, 8)}`,
+		name: "Test Group",
+		memberIssueIds: ["issue-1", "issue-2"],
+		status: "active",
+		createdAt: new Date().toISOString(),
+		completedAt: null,
+		...overrides,
+	};
+}
+
+describe("loadGroups", () => {
+	test("returns empty array when groups.json does not exist", async () => {
+		const groups = await loadGroups(tempDir);
+		expect(groups).toEqual([]);
+	});
+
+	test("returns empty array when groups.json is malformed", async () => {
+		await writeFile(groupsJsonPath, "not valid json");
+		const groups = await loadGroups(tempDir);
+		expect(groups).toEqual([]);
+	});
+
+	test("loads groups from valid groups.json", async () => {
+		const group = makeGroup({ name: "My Group" });
+		await writeGroups([group]);
+		const groups = await loadGroups(tempDir);
+		expect(groups).toHaveLength(1);
+		expect(groups[0]?.name).toBe("My Group");
+	});
+});
+
+describe("group create (via JSON storage)", () => {
+	test("creates a group with correct structure", async () => {
+		const group = makeGroup({
+			name: "Feature Batch",
+			memberIssueIds: ["abc-123", "def-456"],
+		});
+		await writeGroups([group]);
+
+		const groups = await readGroups();
+		expect(groups).toHaveLength(1);
+		const saved = groups[0];
+		expect(saved?.name).toBe("Feature Batch");
+		expect(saved?.memberIssueIds).toEqual(["abc-123", "def-456"]);
+		expect(saved?.status).toBe("active");
+		expect(saved?.completedAt).toBeNull();
+		expect(saved?.id).toMatch(/^group-[a-f0-9]{8}$/);
+	});
+
+	test("group ID has correct format", () => {
+		const id = `group-${crypto.randomUUID().slice(0, 8)}`;
+		expect(id).toMatch(/^group-[a-f0-9]{8}$/);
+	});
+
+	test("groups.json has trailing newline", async () => {
+		await writeGroups([makeGroup()]);
+		const raw = await readFile(groupsJsonPath, "utf-8");
+		expect(raw.endsWith("\n")).toBe(true);
+	});
+});
+
+describe("group add (via JSON storage)", () => {
+	test("adds issues to existing group", async () => {
+		const group = makeGroup({ memberIssueIds: ["issue-1"] });
+		await writeGroups([group]);
+
+		// Simulate add
+		const groups = await readGroups();
+		const target = groups[0];
+		expect(target).toBeDefined();
+		if (target) {
+			target.memberIssueIds.push("issue-2", "issue-3");
+			await writeGroups(groups);
+		}
+
+		const updated = await readGroups();
+		expect(updated[0]?.memberIssueIds).toEqual(["issue-1", "issue-2", "issue-3"]);
+	});
+
+	test("reopens completed group when adding issues", async () => {
+		const group = makeGroup({
+			status: "completed",
+			completedAt: new Date().toISOString(),
+		});
+		await writeGroups([group]);
+
+		const groups = await readGroups();
+		const target = groups[0];
+		expect(target).toBeDefined();
+		if (target) {
+			target.memberIssueIds.push("new-issue");
+			target.status = "active";
+			target.completedAt = null;
+			await writeGroups(groups);
+		}
+
+		const updated = await readGroups();
+		expect(updated[0]?.status).toBe("active");
+		expect(updated[0]?.completedAt).toBeNull();
+	});
+
+	test("detects duplicate members", () => {
+		const group = makeGroup({ memberIssueIds: ["issue-1", "issue-2"] });
+		const isDuplicate = group.memberIssueIds.includes("issue-1");
+		expect(isDuplicate).toBe(true);
+	});
+});
+
+describe("group remove (via JSON storage)", () => {
+	test("removes issues from group", async () => {
+		const group = makeGroup({ memberIssueIds: ["a", "b", "c"] });
+		await writeGroups([group]);
+
+		const groups = await readGroups();
+		const target = groups[0];
+		expect(target).toBeDefined();
+		if (target) {
+			target.memberIssueIds = target.memberIssueIds.filter((id) => id !== "b");
+			await writeGroups(groups);
+		}
+
+		const updated = await readGroups();
+		expect(updated[0]?.memberIssueIds).toEqual(["a", "c"]);
+	});
+
+	test("cannot remove all issues (would leave empty group)", () => {
+		const group = makeGroup({ memberIssueIds: ["only-one"] });
+		const toRemove = ["only-one"];
+		const remaining = group.memberIssueIds.filter((id) => !toRemove.includes(id));
+		expect(remaining.length).toBe(0);
+		// The command should throw GroupError in this case
+	});
+
+	test("detects non-member issue", () => {
+		const group = makeGroup({ memberIssueIds: ["a", "b"] });
+		const isNotMember = !group.memberIssueIds.includes("c");
+		expect(isNotMember).toBe(true);
+	});
+});
+
+describe("auto-close logic", () => {
+	test("marks group completed when all issues are closed", async () => {
+		const group = makeGroup({
+			status: "active",
+			memberIssueIds: ["done-1", "done-2"],
+		});
+		await writeGroups([group]);
+
+		// Simulate auto-close: all completed
+		const groups = await readGroups();
+		const target = groups[0];
+		expect(target).toBeDefined();
+		if (target && target.status === "active") {
+			// All issues closed -> auto-close
+			target.status = "completed";
+			target.completedAt = new Date().toISOString();
+			await writeGroups(groups);
+		}
+
+		const updated = await readGroups();
+		expect(updated[0]?.status).toBe("completed");
+		expect(updated[0]?.completedAt).not.toBeNull();
+	});
+
+	test("does not auto-close when some issues are still open", async () => {
+		const group = makeGroup({ status: "active" });
+		await writeGroups([group]);
+
+		// No change -- some still open
+		const groups = await readGroups();
+		expect(groups[0]?.status).toBe("active");
+	});
+
+	test("does not auto-close already-completed group", () => {
+		const group = makeGroup({ status: "completed", completedAt: "2025-01-01T00:00:00Z" });
+		// Already completed, should not re-trigger
+		expect(group.status).toBe("completed");
+		expect(group.completedAt).toBe("2025-01-01T00:00:00Z");
+	});
+});
+
+describe("group list (via JSON storage)", () => {
+	test("lists all groups", async () => {
+		const g1 = makeGroup({ name: "Group A" });
+		const g2 = makeGroup({ name: "Group B", status: "completed" });
+		await writeGroups([g1, g2]);
+
+		const groups = await readGroups();
+		expect(groups).toHaveLength(2);
+		expect(groups[0]?.name).toBe("Group A");
+		expect(groups[1]?.name).toBe("Group B");
+	});
+
+	test("empty list when no groups exist", async () => {
+		const groups = await loadGroups(tempDir);
+		expect(groups).toEqual([]);
+	});
+});
+
+describe("error cases", () => {
+	test("group not found by ID", async () => {
+		await writeGroups([makeGroup()]);
+		const groups = await readGroups();
+		const found = groups.find((g) => g.id === "group-nonexist");
+		expect(found).toBeUndefined();
+	});
+
+	test("multiple groups can be stored", async () => {
+		const groups = [makeGroup({ name: "A" }), makeGroup({ name: "B" }), makeGroup({ name: "C" })];
+		await writeGroups(groups);
+		const loaded = await readGroups();
+		expect(loaded).toHaveLength(3);
+	});
+});