@katyella/legio 0.1.0

package/src/commands/sling.ts

@@ -0,0 +1,700 @@
+/**
+ * CLI command: legio sling <task-id>
+ *
+ * CRITICAL PATH. Orchestrates a full agent spawn:
+ * 1. Load config + manifest
+ * 2. Validate (depth limit, hierarchy)
+ * 3. Load manifest + validate capability
+ * 4. Resolve or create run_id (current-run.txt)
+ * 5. Check name uniqueness + concurrency limit
+ * 6. Validate bead exists
+ * 7. Create worktree
+ * 8. Generate + write overlay CLAUDE.md
+ * 9. Deploy hooks config
+ * 10. Claim beads issue
+ * 11. Create agent identity
+ * 12. Create tmux session running claude
+ * 13. Record session in SessionStore + increment run agent count
+ * 14. Return AgentSession
+ */
+
+import { spawn } from "node:child_process";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { deployHooks } from "../agents/hooks-deployer.ts";
+import { createIdentity, loadIdentity } from "../agents/identity.ts";
+import { createManifestLoader } from "../agents/manifest.ts";
+import { writeOverlay } from "../agents/overlay.ts";
+import type { BeadIssue } from "../beads/client.ts";
+import { createBeadsClient } from "../beads/client.ts";
+import { collectProviderEnv, loadConfig } from "../config.ts";
+import { AgentError, HierarchyError, isRunningAsRoot, ValidationError } from "../errors.ts";
+import { createMailStore } from "../mail/store.ts";
+import { createMulchClient, inferDomainsFromFiles } from "../mulch/client.ts";
+import { openSessionStore } from "../sessions/compat.ts";
+import { createRunStore } from "../sessions/store.ts";
+import type { AgentSession, OverlayConfig } from "../types.ts";
+import { createWorktree } from "../worktree/manager.ts";
+import { createSession, sendKeys, startPipePane, waitForTuiReady } from "../worktree/tmux.ts";
+
+/**
+ * Calculate how many milliseconds to sleep before spawning a new agent,
+ * based on the configured stagger delay and when the most recent active
+ * session was started.
+ *
+ * Returns 0 if no sleep is needed (no active sessions, delay is 0, or
+ * enough time has already elapsed).
+ *
+ * @param staggerDelayMs - The configured minimum delay between spawns
+ * @param activeSessions - Currently active (non-zombie) sessions
+ * @param now - Current timestamp in ms (defaults to Date.now(), injectable for testing)
+ */
+export function calculateStaggerDelay(
+	staggerDelayMs: number,
+	activeSessions: ReadonlyArray<{ startedAt: string }>,
+	now: number = Date.now(),
+): number {
+	if (staggerDelayMs <= 0 || activeSessions.length === 0) {
+		return 0;
+	}
+
+	const mostRecent = activeSessions.reduce((latest, s) => {
+		return new Date(s.startedAt).getTime() > new Date(latest.startedAt).getTime() ? s : latest;
+	});
+	const elapsed = now - new Date(mostRecent.startedAt).getTime();
+	const remaining = staggerDelayMs - elapsed;
+	return remaining > 0 ? remaining : 0;
+}
+
+/**
+ * Parse a named flag value from an args array.
+ */
+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];
+}
+
+/**
+ * Options for building the structured startup beacon.
+ */
+export interface BeaconOptions {
+	agentName: string;
+	capability: string;
+	taskId: string;
+	parentAgent: string | null;
+	depth: number;
+}
+
+/**
+ * Build a structured startup beacon for an agent.
+ *
+ * The beacon is the first user message sent to a Claude Code agent via
+ * tmux send-keys. It provides identity context and a numbered startup
+ * protocol so the agent knows exactly what to do on boot.
+ *
+ * Format:
+ *   [LEGIO] <agent-name> (<capability>) <ISO timestamp> task:<bead-id>
+ *   Depth: <n> | Parent: <parent-name|none>
+ *   Startup protocol:
+ *   1. Read your assignment in .claude/CLAUDE.md
+ *   2. Load expertise: mulch prime
+ *   3. Check mail: legio mail check --agent <name>
+ *   4. Begin working on task <bead-id>
+ */
+export function buildBeacon(opts: BeaconOptions): string {
+	const timestamp = new Date().toISOString();
+	const parent = opts.parentAgent ?? "none";
+	const parts = [
+		`[LEGIO] ${opts.agentName} (${opts.capability}) ${timestamp} task:${opts.taskId}`,
+		`Depth: ${opts.depth} | Parent: ${parent}`,
+		`Startup: read .claude/CLAUDE.md, run mulch prime, check mail (legio mail check --agent ${opts.agentName}), then begin task ${opts.taskId}`,
+	];
+	return parts.join(" — ");
+}
+
+/**
+ * Build the auto-dispatch mail message object that sling writes to mail.db
+ * before creating the tmux session. This guarantees the dispatch mail exists
+ * when the agent's SessionStart hook fires `legio mail check`.
+ *
+ * Pure function — no side effects, easily testable.
+ */
+export function buildAutoDispatch(opts: {
+	parentAgent: string | null;
+	agentName: string;
+	taskId: string;
+	specPath: string | null;
+	branchName: string;
+}): { from: string; to: string; subject: string; body: string; type: string; priority: string } {
+	const from = opts.parentAgent ?? "orchestrator";
+	const specDisplay = opts.specPath ?? "none";
+	return {
+		from,
+		to: opts.agentName,
+		subject: `dispatch: ${opts.taskId}`,
+		body: `Assigned task ${opts.taskId}. Spec: ${specDisplay}. Branch: ${opts.branchName}. Begin immediately.`,
+		type: "dispatch",
+		priority: "normal",
+	};
+}
+
+/**
+ * Check if a parent agent has spawned any scouts.
+ * Returns true if the parent has at least one scout child in the session history.
+ */
+export function parentHasScouts(
+	sessions: ReadonlyArray<{ parentAgent: string | null; capability: string }>,
+	parentAgent: string,
+): boolean {
+	return sessions.some((s) => s.parentAgent === parentAgent && s.capability === "scout");
+}
+
+/**
+ * Validate hierarchy constraints: the coordinator (no parent) may only spawn leads and scouts.
+ *
+ * When parentAgent is null, the caller is the coordinator or a human.
+ * Only "lead" and "scout" capabilities are allowed in that case. All other capabilities
+ * (builder, scout, reviewer, merger) must be spawned by a lead or supervisor
+ * that passes --parent.
+ *
+ * @param parentAgent - The --parent flag value (null = coordinator/human)
+ * @param capability - The requested agent capability
+ * @param name - The agent name (for error context)
+ * @param depth - The requested hierarchy depth
+ * @param forceHierarchy - If true, bypass the check (for debugging)
+ * @throws HierarchyError if the constraint is violated
+ */
+export function validateHierarchy(
+	parentAgent: string | null,
+	capability: string,
+	name: string,
+	_depth: number,
+	forceHierarchy: boolean,
+): void {
+	if (forceHierarchy) {
+		return;
+	}
+
+	if (parentAgent === null && capability !== "lead" && capability !== "scout") {
+		throw new HierarchyError(
+			`Coordinator cannot spawn "${capability}" directly. Only "lead" and "scout" are allowed without --parent. Use a lead as intermediary, or pass --force-hierarchy to bypass.`,
+			{ agentName: name, requestedCapability: capability },
+		);
+	}
+}
+
+/**
+ * Check if a parent agent has reached its child agent budget ceiling.
+ * @throws AgentError if the parent already has maxAgentsPerLead active children.
+ */
+export function checkParentAgentLimit(
+	sessions: ReadonlyArray<{ parentAgent: string | null; state: string }>,
+	parentAgent: string,
+	maxAgentsPerLead: number,
+	agentName: string,
+): void {
+	const activeChildren = sessions.filter(
+		(s) => s.parentAgent === parentAgent && s.state !== "zombie" && s.state !== "completed",
+	);
+	if (activeChildren.length >= maxAgentsPerLead) {
+		throw new AgentError(
+			`Parent "${parentAgent}" has reached its child agent limit: ${activeChildren.length}/${maxAgentsPerLead} active children`,
+			{ agentName },
+		);
+	}
+}
+
+/**
+ * Check if a lead agent is already active for the given task ID.
+ * Prevents two leads from concurrently working the same issue.
+ * @throws AgentError if a lead is already active for this task.
+ */
+export function checkDuplicateLead(
+	sessions: ReadonlyArray<{ beadId: string; capability: string; state: string; agentName: string }>,
+	taskId: string,
+	capability: string,
+	agentName: string,
+): void {
+	if (capability !== "lead") return; // Only applies to leads
+
+	const existingLead = sessions.find(
+		(s) =>
+			s.beadId === taskId &&
+			s.capability === "lead" &&
+			s.state !== "zombie" &&
+			s.state !== "completed",
+	);
+	if (existingLead) {
+		throw new AgentError(
+			`Lead already active for task "${taskId}": ${existingLead.agentName}. Cannot spawn duplicate lead "${agentName}".`,
+			{ agentName },
+		);
+	}
+}
+
+/**
+ * Entry point for `legio sling <task-id> [flags]`.
+ *
+ * Flags:
+ *   --capability <type>    builder | scout | reviewer | lead | merger
+ *   --name <name>          Unique agent name
+ *   --spec <path>          Path to task spec file
+ *   --files <f1,f2,...>    Exclusive file scope
+ *   --parent <agent-name>  Parent agent (for hierarchy tracking)
+ *   --depth <n>            Current hierarchy depth (default 0)
+ *   --force-hierarchy      Bypass hierarchy validation (debugging only)
+ */
+const SLING_HELP = `legio sling — Spawn a worker agent
+
+Usage: legio sling <task-id> [flags]
+
+Arguments:
+  <task-id>                  Beads task ID to assign
+
+Options:
+  --capability <type>        Agent type: builder | scout | reviewer | lead | merger | cto (default: builder)
+  --name <name>              Unique agent name (required)
+  --spec <path>              Path to task spec file
+  --files <f1,f2,...>        Exclusive file scope (comma-separated)
+  --parent <agent-name>      Parent agent for hierarchy tracking
+  --depth <n>                Current hierarchy depth (default: 0)
+  --force-hierarchy            Bypass hierarchy validation (debugging only)
+  --skip-review                Skip reviewer spawn (lead self-verifies)
+  --json                     Output result as JSON
+  --help, -h                 Show this help`;
+
+export async function slingCommand(args: string[]): Promise<void> {
+	if (args.includes("--help") || args.includes("-h")) {
+		process.stdout.write(`${SLING_HELP}\n`);
+		return;
+	}
+
+	if (isRunningAsRoot()) {
+		throw new ValidationError(
+			"legio must not run as root — agent processes execute arbitrary code",
+			{
+				field: "uid",
+			},
+		);
+	}
+
+	const taskId = args.find((a) => !a.startsWith("--"));
+	if (!taskId) {
+		throw new ValidationError("Task ID is required: legio sling <task-id>", {
+			field: "taskId",
+		});
+	}
+
+	const capability = getFlag(args, "--capability") ?? "builder";
+	const name = getFlag(args, "--name");
+	const specPath = getFlag(args, "--spec") ?? null;
+	const filesRaw = getFlag(args, "--files");
+	const parentAgent = getFlag(args, "--parent") ?? null;
+	const depthStr = getFlag(args, "--depth");
+	const depth = depthStr !== undefined ? Number.parseInt(depthStr, 10) : 0;
+	const forceHierarchy = args.includes("--force-hierarchy");
+	const skipReview = args.includes("--skip-review");
+
+	if (!name || name.trim().length === 0) {
+		throw new ValidationError("--name is required for sling", { field: "name" });
+	}
+
+	if (Number.isNaN(depth) || depth < 0) {
+		throw new ValidationError("--depth must be a non-negative integer", {
+			field: "depth",
+			value: depthStr,
+		});
+	}
+
+	// Validate that spec file exists if provided, and resolve to absolute path
+	// so agents in worktrees can access it (worktrees don't have .legio/)
+	let absoluteSpecPath: string | null = null;
+	if (specPath !== null) {
+		absoluteSpecPath = resolve(specPath);
+		let specExists = false;
+		try {
+			await access(absoluteSpecPath);
+			specExists = true;
+		} catch {
+			specExists = false;
+		}
+		if (!specExists) {
+			throw new ValidationError(`Spec file not found: ${specPath}`, {
+				field: "spec",
+				value: specPath,
+			});
+		}
+	}
+
+	const fileScope = filesRaw
+		? filesRaw
+				.split(",")
+				.map((f) => f.trim())
+				.filter((f) => f.length > 0)
+		: [];
+
+	// 1. Load config
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+
+	// 2. Validate depth limit
+	// Hierarchy: orchestrator(0) -> lead(1) -> specialist(2)
+	// With maxDepth=2, depth=2 is the deepest allowed leaf, so reject only depth > maxDepth
+	if (depth > config.agents.maxDepth) {
+		throw new AgentError(
+			`Depth limit exceeded: depth ${depth} > maxDepth ${config.agents.maxDepth}`,
+			{ agentName: name },
+		);
+	}
+
+	// 2b. Validate hierarchy: coordinator (no --parent) can only spawn leads and scouts
+	validateHierarchy(parentAgent, capability, name, depth, forceHierarchy);
+
+	// 3. Load manifest and validate capability
+	const manifestLoader = createManifestLoader(
+		join(config.project.root, config.agents.manifestPath),
+		join(config.project.root, config.agents.baseDir),
+	);
+	const manifest = await manifestLoader.load();
+
+	const agentDef = manifest.agents[capability];
+	if (!agentDef) {
+		throw new AgentError(
+			`Unknown capability "${capability}". Available: ${Object.keys(manifest.agents).join(", ")}`,
+			{ agentName: name, capability },
+		);
+	}
+
+	// 4. Resolve or create run_id for this spawn
+	const legioDir = join(config.project.root, ".legio");
+	const currentRunPath = join(legioDir, "current-run.txt");
+	let runId: string;
+
+	let currentRunExists = false;
+	try {
+		await access(currentRunPath);
+		currentRunExists = true;
+	} catch {
+		currentRunExists = false;
+	}
+	if (currentRunExists) {
+		runId = (await readFile(currentRunPath, "utf-8")).trim();
+	} else {
+		runId = `run-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+		const runStore = createRunStore(join(legioDir, "sessions.db"));
+		try {
+			runStore.createRun({
+				id: runId,
+				startedAt: new Date().toISOString(),
+				coordinatorSessionId: null,
+				status: "active",
+			});
+		} finally {
+			runStore.close();
+		}
+		await writeFile(currentRunPath, runId);
+	}
+
+	// 5. Check name uniqueness and concurrency limit against active sessions
+	const { store } = openSessionStore(legioDir);
+	try {
+		const activeSessions = store.getActive();
+		if (activeSessions.length >= config.agents.maxConcurrent) {
+			throw new AgentError(
+				`Max concurrent agent limit reached: ${activeSessions.length}/${config.agents.maxConcurrent} active agents`,
+				{ agentName: name },
+			);
+		}
+
+		const existing = store.getByName(name);
+		if (existing && existing.state !== "zombie" && existing.state !== "completed") {
+			throw new AgentError(`Agent name "${name}" is already in use (state: ${existing.state})`, {
+				agentName: name,
+			});
+		}
+
+		// 5b. Enforce stagger delay between agent spawns
+		const staggerMs = calculateStaggerDelay(config.agents.staggerDelayMs, activeSessions);
+		if (staggerMs > 0) {
+			await new Promise<void>((resolve) => setTimeout(resolve, staggerMs));
+		}
+
+		// 5c. Structural enforcement: warn when a lead spawns a builder without prior scouts.
+		// This is a non-blocking warning — it does not prevent the spawn, but surfaces
+		// the scout-skip pattern so agents and operators can see it happening.
+		if (capability === "builder" && parentAgent && !parentHasScouts(store.getAll(), parentAgent)) {
+			process.stderr.write(
+				`⚠️  Warning: "${parentAgent}" is spawning builder "${name}" without having spawned any scouts.\n`,
+			);
+			process.stderr.write(
+				"   Leads should spawn scouts in Phase 1 before building. See agents/lead.md.\n",
+			);
+		}
+
+		// 5d. Enforce per-lead agent budget ceiling
+		if (parentAgent !== null) {
+			checkParentAgentLimit(activeSessions, parentAgent, config.agents.maxAgentsPerLead ?? 5, name);
+		}
+
+		// 5e. Prevent duplicate leads on the same task
+		checkDuplicateLead(activeSessions, taskId, capability, name);
+
+		// 6. Validate bead exists and is in a workable state (if beads enabled)
+		const beads = createBeadsClient(config.project.root);
+		if (config.beads.enabled) {
+			let issue: BeadIssue;
+			try {
+				issue = await beads.show(taskId);
+			} catch (err) {
+				throw new AgentError(`Bead task "${taskId}" not found or inaccessible`, {
+					agentName: name,
+					cause: err instanceof Error ? err : undefined,
+				});
+			}
+
+			const workableStatuses = ["open", "in_progress"];
+			if (!workableStatuses.includes(issue.status)) {
+				throw new ValidationError(
+					`Bead task "${taskId}" is not workable (status: ${issue.status}). Only open or in_progress issues can be assigned.`,
+					{ field: "taskId", value: taskId },
+				);
+			}
+		}
+
+		// 7. Create worktree
+		const worktreeBaseDir = join(config.project.root, config.worktrees.baseDir);
+		await mkdir(worktreeBaseDir, { recursive: true });
+
+		const { path: worktreePath, branch: branchName } = await createWorktree({
+			repoRoot: config.project.root,
+			baseDir: worktreeBaseDir,
+			agentName: name,
+			baseBranch: config.project.canonicalBranch,
+			beadId: taskId,
+		});
+
+		// 8. Generate + write overlay CLAUDE.md
+		const agentDefPath = join(config.project.root, config.agents.baseDir, agentDef.file);
+		const baseDefinition = await readFile(agentDefPath, "utf-8");
+
+		// 8a. Infer mulch domains from file scope and fetch expertise
+		const customDomainMap = config.mulch.domainMap;
+		const inferredDomains = inferDomainsFromFiles(
+			fileScope,
+			customDomainMap && Object.keys(customDomainMap).length > 0 ? customDomainMap : undefined,
+		);
+		let mulchExpertise: string | undefined;
+		if (config.mulch.enabled && fileScope.length > 0) {
+			try {
+				const mulch = createMulchClient(config.project.root);
+				if (inferredDomains.length > 0) {
+					mulchExpertise = await mulch.prime(inferredDomains);
+				} else {
+					mulchExpertise = await mulch.prime(undefined, undefined, { files: fileScope });
+				}
+			} catch {
+				// Non-fatal: mulch expertise is supplementary context
+				mulchExpertise = undefined;
+			}
+		}
+
+		const overlayConfig: OverlayConfig = {
+			agentName: name,
+			beadId: taskId,
+			specPath: absoluteSpecPath,
+			branchName,
+			worktreePath,
+			fileScope,
+			mulchDomains: config.mulch.enabled
+				? inferredDomains.length > 0
+					? inferredDomains
+					: config.mulch.domains
+				: [],
+			parentAgent: parentAgent,
+			depth,
+			canSpawn: agentDef.canSpawn,
+			capability,
+			baseDefinition,
+			mulchExpertise,
+			canonicalRoot: config.project.root,
+			skipReview,
+		};
+
+		try {
+			await writeOverlay(worktreePath, overlayConfig, config.project.root);
+		} catch (err) {
+			// Clean up the orphaned worktree created in step 7 (legio-p4st)
+			try {
+				await new Promise<void>((res) => {
+					const p = spawn("git", ["worktree", "remove", "--force", worktreePath], {
+						cwd: config.project.root,
+						stdio: "ignore",
+					});
+					p.on("close", () => res());
+					p.on("error", () => res());
+				});
+			} catch {
+				// Best-effort cleanup; the original error is more important
+			}
+			throw err;
+		}
+
+		// 9. Deploy hooks config (capability-specific guards)
+		await deployHooks(worktreePath, name, capability);
+
+		// 10. Claim beads issue
+		if (config.beads.enabled) {
+			try {
+				await beads.claim(taskId);
+			} catch {
+				// Non-fatal: issue may already be claimed
+			}
+		}
+
+		// 11. Create agent identity (if new)
+		const identityBaseDir = join(config.project.root, ".legio", "agents");
+		const existingIdentity = await loadIdentity(identityBaseDir, name);
+		if (!existingIdentity) {
+			await createIdentity(identityBaseDir, {
+				name,
+				capability,
+				created: new Date().toISOString(),
+				sessionsCompleted: 0,
+				expertiseDomains: config.mulch.enabled ? config.mulch.domains : [],
+				recentTasks: [],
+			});
+		}
+
+		// 11b. Write dispatch mail BEFORE creating the tmux session so the mail
+		// exists when the agent's SessionStart hook fires `legio mail check`.
+		// Without this, there is a race: the agent boots, checks mail, finds nothing,
+		// and idles without an assignment.
+		const dispatchMsg = buildAutoDispatch({
+			parentAgent,
+			agentName: name,
+			taskId,
+			specPath: absoluteSpecPath,
+			branchName,
+		});
+		const mailStore = createMailStore(join(legioDir, "mail.db"));
+		try {
+			mailStore.insert({
+				id: `dispatch-${Date.now()}-${name}`,
+				from: dispatchMsg.from,
+				to: dispatchMsg.to,
+				subject: dispatchMsg.subject,
+				body: dispatchMsg.body,
+				type: dispatchMsg.type as "dispatch",
+				priority: dispatchMsg.priority as "normal",
+				threadId: null,
+			});
+		} finally {
+			mailStore.close();
+		}
+
+		// 12. Create tmux session running claude in interactive mode
+		// Write a settings JSON file to skip the bypass-permissions dialog.
+		const settingsPath = join(legioDir, `settings-${name}.json`);
+		await writeFile(
+			settingsPath,
+			JSON.stringify({ skipDangerousModePermissionPrompt: true }),
+			"utf-8",
+		);
+		const tmuxSessionName = `legio-${config.project.name}-${name}`;
+		const claudeCmd = `claude --model ${agentDef.model} --dangerously-skip-permissions --settings ${settingsPath}`;
+		const pid = await createSession(tmuxSessionName, worktreePath, claudeCmd, {
+			...collectProviderEnv(),
+			LEGIO_AGENT_NAME: name,
+			LEGIO_WORKTREE_PATH: worktreePath,
+		});
+
+		// 13. Record session BEFORE sending the beacon so that hook-triggered
+		// updateLastActivity() can find the entry and transition booting->working.
+		// Without this, a race exists: hooks fire before the session is persisted,
+		// leaving the agent stuck in "booting" (legio-036f).
+		const terminalLogPath = join(legioDir, "logs", name, "terminal.log");
+		const session: AgentSession = {
+			id: `session-${Date.now()}-${name}`,
+			agentName: name,
+			capability,
+			worktreePath,
+			branchName,
+			beadId: taskId,
+			tmuxSession: tmuxSessionName,
+			state: "booting",
+			pid,
+			parentAgent: parentAgent,
+			depth,
+			runId,
+			startedAt: new Date().toISOString(),
+			lastActivity: new Date().toISOString(),
+			escalationLevel: 0,
+			stalledSince: null,
+			terminalLogPath,
+		};
+
+		store.upsert(session);
+
+		// Increment agent count for the run
+		const runStore = createRunStore(join(legioDir, "sessions.db"));
+		try {
+			runStore.incrementAgentCount(runId);
+		} finally {
+			runStore.close();
+		}
+
+		// 13b. Send beacon prompt via tmux send-keys
+		// Wait for Claude Code's TUI to render before sending input.
+		// Polls pane content until non-empty (replaces hardcoded 3s sleep).
+		await waitForTuiReady(tmuxSessionName);
+
+		// 13c. Start pipe-pane streaming to terminal log (non-fatal)
+		try {
+			await startPipePane(tmuxSessionName, terminalLogPath);
+		} catch {
+			// Non-fatal: pipe-pane unavailable or session not yet ready
+		}
+		const beacon = buildBeacon({
+			agentName: name,
+			capability,
+			taskId,
+			parentAgent,
+			depth,
+		});
+		await sendKeys(tmuxSessionName, beacon);
+
+		// 13d. Send a follow-up Enter after a short delay to ensure submission.
+		// Claude Code's TUI may consume the first Enter during initialization,
+		// leaving the beacon text visible but unsubmitted (legio-yhv6).
+		// A redundant Enter on an empty input line is harmless.
+		await new Promise<void>((resolve) => setTimeout(resolve, 500));
+		await sendKeys(tmuxSessionName, "");
+
+		// 14. Output result
+		const output = {
+			agentName: name,
+			capability,
+			taskId,
+			branch: branchName,
+			worktree: worktreePath,
+			tmuxSession: tmuxSessionName,
+			pid,
+		};
+
+		if (args.includes("--json")) {
+			process.stdout.write(`${JSON.stringify(output)}\n`);
+		} else {
+			process.stdout.write(`🚀 Agent "${name}" launched!\n`);
+			process.stdout.write(`   Task:     ${taskId}\n`);
+			process.stdout.write(`   Branch:   ${branchName}\n`);
+			process.stdout.write(`   Worktree: ${worktreePath}\n`);
+			process.stdout.write(`   Tmux:     ${tmuxSessionName}\n`);
+			process.stdout.write(`   PID:      ${pid}\n`);
+		}
+	} finally {
+		store.close();
+	}
+}