@katyella/legio 0.1.0

package/src/server/routes.ts

@@ -0,0 +1,1964 @@
+/**
+ * REST API route handlers for the legio web UI server.
+ *
+ * Single exported function `handleApiRequest` dispatches all /api/* routes
+ * to the appropriate store. Each handler opens and closes its store within
+ * the request — per-request store lifecycle with no shared state.
+ */
+
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { access, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { createBeadsClient } from "../beads/client.ts";
+import { gatherInspectData } from "../commands/inspect.ts";
+import { gatherStatus } from "../commands/status.ts";
+import { loadConfig } from "../config.ts";
+import { createEventStore } from "../events/store.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 { createRunStore, createSessionStore } from "../sessions/store.ts";
+import type {
+	EventLevel,
+	HeadlessCoordinatorConfig,
+	MailAudience,
+	MailMessage,
+	MergeEntry,
+	RunStatus,
+} from "../types.ts";
+import { MAIL_MESSAGE_TYPES } from "../types.ts";
+import { isSessionAlive, readTerminalLog, sendKeys } from "../worktree/tmux.ts";
+import { createAuditStore } from "./audit-store.ts";
+import { HeadlessCoordinator } from "./headless.ts";
+
+// TODO: move Idea and IdeasFile to types.ts
+interface Idea {
+	id: string; // "idea-" + randomUUID().slice(0, 8)
+	title: string;
+	body: string;
+	status: "active" | "dispatched" | "backlog";
+	createdAt: string;
+	updatedAt: string;
+}
+
+interface IdeasFile {
+	ideas: Idea[];
+}
+
+// ---------------------------------------------------------------------------
+// Module-level cache for /api/issues (default requests only)
+// ---------------------------------------------------------------------------
+
+let issuesCacheData: unknown = null;
+let issuesCacheAt = 0;
+const ISSUES_CACHE_TTL = 3000;
+
+// ---------------------------------------------------------------------------
+// File helpers
+// ---------------------------------------------------------------------------
+
+async function fileExists(p: string): Promise<boolean> {
+	try {
+		await access(p, constants.F_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Route helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Match a URL path against a pattern with named params (e.g. `/api/agents/:name`).
+ * Returns a Record of captured param values, or null if not matched.
+ */
+function matchRoute(path: string, pattern: string): Record<string, string> | null {
+	const regexStr = pattern.replace(/:(\w+)/g, "(?<$1>[^/]+)");
+	const match = new RegExp(`^${regexStr}$`).exec(path);
+	return match?.groups ?? null;
+}
+
+function jsonResponse(data: unknown, status = 200): Response {
+	return new Response(JSON.stringify(data), {
+		status,
+		headers: { "Content-Type": "application/json" },
+	});
+}
+
+function errorResponse(message: string, status = 500): Response {
+	return jsonResponse({ error: message }, status);
+}
+
+// ---------------------------------------------------------------------------
+// Terminal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Load the orchestrator's registered tmux session name from orchestrator-tmux.json.
+ * Written by `legio prime` at SessionStart when running inside tmux.
+ */
+async function loadOrchestratorTmuxSession(projectRoot: string): Promise<string | null> {
+	const regPath = join(projectRoot, ".legio", "orchestrator-tmux.json");
+	if (!(await fileExists(regPath))) {
+		return null;
+	}
+	try {
+		const text = await readFile(regPath, "utf-8");
+		const reg = JSON.parse(text) as { tmuxSession?: string };
+		return reg.tmuxSession ?? null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Resolve the tmux session name for an agent.
+ *
+ * For regular agents, looks up the SessionStore.
+ * For "coordinator" or "orchestrator", falls back to orchestrator-tmux.json.
+ */
+async function resolveTerminalSession(
+	legioDir: string,
+	projectRoot: string,
+	agentName: string,
+): Promise<string | null> {
+	const dbPath = join(legioDir, "sessions.db");
+	if (await fileExists(dbPath)) {
+		const { store } = openSessionStore(legioDir);
+		try {
+			const session = store.getByName(agentName);
+			if (session && session.state !== "zombie" && session.state !== "completed") {
+				return session.tmuxSession;
+			}
+		} finally {
+			store.close();
+		}
+	}
+
+	// Fallback for coordinator/orchestrator: check orchestrator-tmux.json
+	if (agentName === "coordinator" || agentName === "orchestrator") {
+		return await loadOrchestratorTmuxSession(projectRoot);
+	}
+
+	return null;
+}
+
+/**
+ * Capture the output of a tmux pane.
+ *
+ * @param sessionName - Tmux session name
+ * @param lines - Number of history lines to capture
+ * @returns Captured pane output, or null if capture failed
+ */
+async function captureTmuxPane(sessionName: string, lines: number): Promise<string | null> {
+	return new Promise((resolve) => {
+		const proc = spawn("tmux", ["capture-pane", "-t", sessionName, "-p", "-S", `-${lines}`], {
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+		let out = "";
+		proc.stdout.on("data", (chunk: Buffer) => {
+			out += chunk;
+		});
+		proc.on("close", (code: number | null) => {
+			resolve(code === 0 ? out.trim() : null);
+		});
+	});
+}
+
+// ---------------------------------------------------------------------------
+// runLegio helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Spawn `legio <args>` as a subprocess, capture stdout/stderr, and return
+ * parsed JSON output on success.
+ */
+async function runLegio(
+	args: string[],
+	projectRoot: string,
+): Promise<{ ok: true; data: unknown } | { ok: false; error: string }> {
+	return new Promise((resolve) => {
+		const proc = spawn("legio", args, {
+			cwd: projectRoot,
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+		let stdout = "";
+		let stderr = "";
+		let resolved = false;
+		const doResolve = (result: { ok: true; data: unknown } | { ok: false; error: string }) => {
+			if (!resolved) {
+				resolved = true;
+				resolve(result);
+			}
+		};
+		proc.stdout?.on("data", (chunk: Buffer) => {
+			stdout += chunk;
+		});
+		proc.stderr?.on("data", (chunk: Buffer) => {
+			stderr += chunk;
+		});
+		// Use 'exit' instead of 'close' — 'close' waits for all stdio pipes
+		// to drain, which can hang if child processes (e.g., tmux sessions)
+		// inherit the pipe file descriptors.
+		proc.on("exit", (code: number | null) => {
+			if (code === 0) {
+				try {
+					doResolve({ ok: true, data: JSON.parse(stdout) });
+				} catch {
+					doResolve({ ok: true, data: stdout.trim() });
+				}
+			} else {
+				const raw = stderr.trim() || stdout.trim() || "Command failed";
+				const errorText = raw.split("\n")[0] ?? "Command failed";
+				doResolve({ ok: false, error: errorText });
+			}
+		});
+		proc.on("error", (err: Error) => {
+			doResolve({ ok: false, error: err.message });
+		});
+		// Safety timeout: resolve after 10s even if the process hasn't exited
+		setTimeout(() => {
+			if (stdout.trim().length > 0) {
+				try {
+					doResolve({ ok: true, data: JSON.parse(stdout) });
+				} catch {
+					doResolve({ ok: true, data: stdout.trim() });
+				}
+			} else {
+				doResolve({ ok: false, error: "Command timed out" });
+			}
+		}, 10_000);
+	});
+}
+
+/**
+ * Parse and validate a JSON request body as a plain object.
+ * Returns the parsed object or an error Response if invalid.
+ */
+async function parseJsonBody(request: Request): Promise<Record<string, unknown> | Response> {
+	let body: unknown;
+	try {
+		body = await request.json();
+	} catch {
+		return errorResponse("Invalid JSON body", 400);
+	}
+	if (typeof body !== "object" || body === null || Array.isArray(body)) {
+		return errorResponse("Request body must be a JSON object", 400);
+	}
+	return body as Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Main dispatcher
+// ---------------------------------------------------------------------------
+
+export async function handleApiRequest(
+	request: Request,
+	legioDir: string,
+	projectRoot: string,
+	wsManager?: { broadcastEvent(event: { type: string; data?: unknown }): void } | null,
+	headless?: {
+		coordinator: HeadlessCoordinator | null;
+		setCoordinator: (c: HeadlessCoordinator | null) => void;
+	} | null,
+): Promise<Response> {
+	const url = new URL(request.url);
+	const path = url.pathname;
+
+	// -------------------------------------------------------------------------
+	// POST /api/mail/send
+	// -------------------------------------------------------------------------
+
+	if (request.method === "POST" && path === "/api/mail/send") {
+		let body: unknown;
+		try {
+			body = await request.json();
+		} catch {
+			return errorResponse("Invalid JSON body", 400);
+		}
+		if (typeof body !== "object" || body === null || Array.isArray(body)) {
+			return errorResponse("Request body must be a JSON object", 400);
+		}
+		const obj = body as Record<string, unknown>;
+
+		if (typeof obj.from !== "string" || !obj.from) {
+			return errorResponse("Missing required field: from", 400);
+		}
+		if (typeof obj.to !== "string" || !obj.to) {
+			return errorResponse("Missing required field: to", 400);
+		}
+		if (typeof obj.subject !== "string" || !obj.subject) {
+			return errorResponse("Missing required field: subject", 400);
+		}
+		if (typeof obj.body !== "string") {
+			return errorResponse("Missing required field: body", 400);
+		}
+
+		const typeRaw = typeof obj.type === "string" ? obj.type : "status";
+		const mailType: MailMessage["type"] = (MAIL_MESSAGE_TYPES as readonly string[]).includes(
+			typeRaw,
+		)
+			? (typeRaw as MailMessage["type"])
+			: "status";
+
+		const priorityRaw = typeof obj.priority === "string" ? obj.priority : "normal";
+		const validPriorities: readonly string[] = ["low", "normal", "high", "urgent"];
+		const priority: MailMessage["priority"] = validPriorities.includes(priorityRaw)
+			? (priorityRaw as MailMessage["priority"])
+			: "normal";
+
+		const threadId = typeof obj.threadId === "string" ? obj.threadId : null;
+
+		const isHumanSender = obj.from === "orchestrator" || obj.from === "coordinator";
+		const audienceDefault = isHumanSender ? "both" : "agent";
+		const audienceRaw = typeof obj.audience === "string" ? obj.audience : audienceDefault;
+		const validAudiences: readonly string[] = ["human", "agent", "both"];
+		const audience = (
+			validAudiences.includes(audienceRaw) ? audienceRaw : audienceDefault
+		) as MailAudience;
+
+		const dbPath = join(legioDir, "mail.db");
+		const store = createMailStore(dbPath);
+		try {
+			const message = store.insert({
+				id: "",
+				from: obj.from,
+				to: obj.to,
+				subject: obj.subject,
+				body: obj.body,
+				type: mailType,
+				priority,
+				threadId,
+				audience,
+			});
+			wsManager?.broadcastEvent({ type: "mail_new", data: message });
+			return jsonResponse(message, 201);
+		} catch (err) {
+			return errorResponse(
+				`Failed to send message: ${err instanceof Error ? err.message : String(err)}`,
+			);
+		} finally {
+			store.close();
+		}
+	}
+
+	// -------------------------------------------------------------------------
+	// POST /api/terminal/send
+	// -------------------------------------------------------------------------
+
+	if (request.method === "POST" && path === "/api/terminal/send") {
+		let body: unknown;
+		try {
+			body = await request.json();
+		} catch {
+			return errorResponse("Invalid JSON body", 400);
+		}
+		if (typeof body !== "object" || body === null || Array.isArray(body)) {
+			return errorResponse("Request body must be a JSON object", 400);
+		}
+		const obj = body as Record<string, unknown>;
+
+		if (typeof obj.text !== "string" || obj.text.trim().length === 0) {
+			return errorResponse("Missing or empty required field: text", 400);
+		}
+
+		const agentName = typeof obj.agent === "string" && obj.agent ? obj.agent : "coordinator";
+
+		// If a headless coordinator is running for the coordinator agent, write to stdin
+		if (
+			(agentName === "coordinator" || agentName === "headless") &&
+			headless?.coordinator?.isRunning()
+		) {
+			try {
+				headless.coordinator.write(`${obj.text}\n`);
+			} catch (err) {
+				return errorResponse(
+					`Failed to write to headless coordinator: ${err instanceof Error ? err.message : String(err)}`,
+				);
+			}
+			return jsonResponse({ ok: true });
+		}
+
+		const tmuxSession = await resolveTerminalSession(legioDir, projectRoot, agentName);
+		if (!tmuxSession) {
+			return errorResponse(`Cannot resolve tmux session for agent "${agentName}"`, 404);
+		}
+
+		if (!(await isSessionAlive(tmuxSession))) {
+			return errorResponse(`Tmux session "${tmuxSession}" is not alive`, 404);
+		}
+
+		try {
+			await sendKeys(tmuxSession, obj.text);
+			// Follow-up Enter after a short delay to ensure Claude Code's TUI submits.
+			// Same pattern as nudge.ts line 168-169.
+			await new Promise((resolve) => setTimeout(resolve, 500));
+			await sendKeys(tmuxSession, "");
+		} catch (err) {
+			return errorResponse(
+				`Failed to send keys: ${err instanceof Error ? err.message : String(err)}`,
+			);
+		}
+
+		return jsonResponse({ ok: true });
+	}
+
+	// -------------------------------------------------------------------------
+	// Audit — POST route (before the GET-only guard)
+	// -------------------------------------------------------------------------
+
+	if (request.method === "POST" && path === "/api/audit") {
+		let body: unknown;
+		try {
+			body = await request.json();
+		} catch {
+			return errorResponse("Invalid JSON body", 400);
+		}
+		if (typeof body !== "object" || body === null || Array.isArray(body)) {
+			return errorResponse("Request body must be a JSON object", 400);
+		}
+		const obj = body as Record<string, unknown>;
+
+		if (typeof obj.type !== "string" || !obj.type) {
+			return errorResponse("Missing required field: type", 400);
+		}
+		if (typeof obj.summary !== "string" || !obj.summary) {
+			return errorResponse("Missing required field: summary", 400);
+		}
+
+		const source = typeof obj.source === "string" ? obj.source : "web_ui";
+		const agent = typeof obj.agent === "string" ? obj.agent : null;
+		const detail = typeof obj.detail === "string" ? obj.detail : null;
+		const sessionId = typeof obj.sessionId === "string" ? obj.sessionId : null;
+
+		const auditDbPath = join(legioDir, "audit.db");
+		const store = createAuditStore(auditDbPath);
+		try {
+			const id = store.insert({
+				type: obj.type,
+				agent,
+				source,
+				summary: obj.summary,
+				detail,
+				sessionId,
+			});
+			// Fetch the inserted event back from the database to return the full record
+			const created = store.getAll().find((e) => e.id === id);
+			return jsonResponse(created ?? { id }, 201);
+		} catch (err) {
+			return errorResponse(
+				`Failed to record audit event: ${err instanceof Error ? err.message : String(err)}`,
+			);
+		} finally {
+			store.close();
+		}
+	}
+
+	// -------------------------------------------------------------------------
+	// Setup — POST route (before the GET-only guard)
+	// -------------------------------------------------------------------------
+
+	if (request.method === "POST" && path === "/api/setup/init") {
+		let force = false;
+		try {
+			const body = await request.json();
+			if (typeof body === "object" && body !== null && !Array.isArray(body)) {
+				const obj = body as Record<string, unknown>;
+				force = obj.force === true;
+			}
+		} catch {
+			// ignore — force defaults to false
+		}
+		const args = force ? ["init", "--force"] : ["init"];
+		const result = await runLegio(args, projectRoot);
+		if (result.ok) {
+			return jsonResponse({ success: true, message: "Project initialized successfully" });
+		}
+		return jsonResponse({ success: false, error: result.error });
+	}
+
+	// -------------------------------------------------------------------------
+	// Ideas — POST/PUT/DELETE routes (before the GET-only guard)
+	// -------------------------------------------------------------------------
+
+	if (request.method === "POST" && path === "/api/ideas") {
+		const parsed = await parseJsonBody(request);
+		if (parsed instanceof Response) return parsed;
+
+		const title = typeof parsed.title === "string" ? parsed.title.trim() : "";
+		if (!title) return errorResponse("Missing required field: title", 400);
+
+		const body = typeof parsed.body === "string" ? parsed.body : "";
+		const now = new Date().toISOString();
+		const idea: Idea = {
+			id: `idea-${randomUUID().slice(0, 8)}`,
+			title,
+			body,
+			status: "active",
+			createdAt: now,
+			updatedAt: now,
+		};
+
+		const ideasPath = join(legioDir, "ideas.json");
+		let data: IdeasFile = { ideas: [] };
+		if (await fileExists(ideasPath)) {
+			try {
+				data = JSON.parse(await readFile(ideasPath, "utf-8")) as IdeasFile;
+			} catch {
+				// start fresh on corrupt file
+			}
+		}
+		data.ideas.push(idea);
+		await writeFile(ideasPath, JSON.stringify(data, null, 2));
+		return jsonResponse(idea, 201);
+	}
+
+	{
+		const params = matchRoute(path, "/api/ideas/:id");
+		if (request.method === "PUT" && params) {
+			const { id } = params;
+			if (!id) return errorResponse("Missing idea ID", 400);
+
+			const ideasPath = join(legioDir, "ideas.json");
+			if (!(await fileExists(ideasPath))) {
+				return errorResponse(`Idea not found: ${id}`, 404);
+			}
+
+			const parsed = await parseJsonBody(request);
+			if (parsed instanceof Response) return parsed;
+
+			try {
+				const data = JSON.parse(await readFile(ideasPath, "utf-8")) as IdeasFile;
+				const idea = data.ideas.find((i) => i.id === id);
+				if (!idea) return errorResponse(`Idea not found: ${id}`, 404);
+
+				if (typeof parsed.title === "string") idea.title = parsed.title;
+				if (typeof parsed.body === "string") idea.body = parsed.body;
+				idea.updatedAt = new Date().toISOString();
+
+				await writeFile(ideasPath, JSON.stringify(data, null, 2));
+				return jsonResponse(idea);
+			} catch (err) {
+				return errorResponse(
+					`Failed to update idea: ${err instanceof Error ? err.message : String(err)}`,
+				);
+			}
+		}
+
+		if (request.method === "DELETE" && params) {
+			const { id } = params;
+			if (!id) return errorResponse("Missing idea ID", 400);
+
+			const ideasPath = join(legioDir, "ideas.json");
+			if (!(await fileExists(ideasPath))) {
+				return errorResponse(`Idea not found: ${id}`, 404);
+			}
+
+			try {
+				const data = JSON.parse(await readFile(ideasPath, "utf-8")) as IdeasFile;
+				const idx = data.ideas.findIndex((i) => i.id === id);
+				if (idx === -1) return errorResponse(`Idea not found: ${id}`, 404);
+
+				data.ideas.splice(idx, 1);
+				await writeFile(ideasPath, JSON.stringify(data, null, 2));
+				return jsonResponse({ success: true });
+			} catch (err) {
+				return errorResponse(
+					`Failed to delete idea: ${err instanceof Error ? err.message : String(err)}`,
+				);
+			}
+		}
+	}
+
+	{
+		const params = matchRoute(path, "/api/ideas/:id/dispatch");
+		if (request.method === "POST" && params) {
+			const { id } = params;
+			if (!id) return errorResponse("Missing idea ID", 400);
+
+			const ideasPath = join(legioDir, "ideas.json");
+			if (!(await fileExists(ideasPath))) {
+				return errorResponse(`Idea not found: ${id}`, 404);
+			}
+
+			try {
+				const data = JSON.parse(await readFile(ideasPath, "utf-8")) as IdeasFile;
+				const idea = data.ideas.find((i) => i.id === id);
+				if (!idea) return errorResponse(`Idea not found: ${id}`, 404);
+
+				const store = createMailStore(join(legioDir, "mail.db"));
+				const messageId = `idea-dispatch-${randomUUID().slice(0, 8)}`;
+				store.insert({
+					id: messageId,
+					from: "human",
+					to: "coordinator",
+					subject: idea.title,
+					body: idea.body ? `${idea.title}\n\n${idea.body}` : idea.title,
+					type: "dispatch",
+					priority: "normal",
+					threadId: null,
+					audience: "agent",
+				});
+				store.close();
+
+				idea.status = "dispatched";
+				idea.updatedAt = new Date().toISOString();
+				await writeFile(ideasPath, JSON.stringify(data, null, 2));
+
+				return jsonResponse({ idea, messageId });
+			} catch (err) {
+				return errorResponse(
+					`Failed to dispatch idea: ${err instanceof Error ? err.message : String(err)}`,
+				);
+			}
+		}
+	}
+
+	{
+		const params = matchRoute(path, "/api/ideas/:id/backlog");
+		if (request.method === "POST" && params) {
+			const { id } = params;
+			if (!id) return errorResponse("Missing idea ID", 400);
+
+			const ideasPath = join(legioDir, "ideas.json");
+			if (!(await fileExists(ideasPath))) {
+				return errorResponse(`Idea not found: ${id}`, 404);
+			}
+
+			try {
+				const data = JSON.parse(await readFile(ideasPath, "utf-8")) as IdeasFile;
+				const idea = data.ideas.find((i) => i.id === id);
+				if (!idea) return errorResponse(`Idea not found: ${id}`, 404);
+
+				const client = createBeadsClient(projectRoot);
+				const issueId = await client.create(idea.title, { description: idea.body });
+
+				idea.status = "backlog";
+				idea.updatedAt = new Date().toISOString();
+				await writeFile(ideasPath, JSON.stringify(data, null, 2));
+
+				return jsonResponse({ idea, issueId });
+			} catch (err) {
+				return errorResponse(
+					`Failed to add idea to backlog: ${err instanceof Error ? err.message : String(err)}`,
+				);
+			}
+		}
+	}
+
+	// -------------------------------------------------------------------------
+	// Coordinator — POST routes (before the GET-only guard)
+	// -------------------------------------------------------------------------
+
+	if (request.method === "POST" && path === "/api/coordinator/start") {
+		const parsed = await parseJsonBody(request);
+		if (parsed instanceof Response) return parsed;
+
+		if (parsed.headless === true) {
+			// Start headless coordinator in-process
+			if (headless?.coordinator?.isRunning()) {
+				return errorResponse("Headless coordinator is already running", 409);
+			}
+
+			// Build the command (same as CLI path but we can't read full config here,
+			// so we use a sensible default and let the caller configure via env)
+			const claudeCmd =
+				typeof parsed.command === "string" && parsed.command
+					? parsed.command
+					: "claude --dangerously-skip-permissions";
+
+			const config: HeadlessCoordinatorConfig = {
+				command: claudeCmd,
+				cwd: projectRoot,
+				env:
+					typeof parsed.env === "object" && parsed.env !== null
+						? (parsed.env as Record<string, string>)
+						: { LEGIO_AGENT_NAME: "coordinator" },
+				ringBufferSize: typeof parsed.ringBufferSize === "number" ? parsed.ringBufferSize : 500,
+			};
+
+			const coordinator = new HeadlessCoordinator(config);
+
+			// Wire output events to WebSocket broadcast
+			coordinator.on("output", (chunk: string) => {
+				wsManager?.broadcastEvent({ type: "coordinator_output", data: { text: chunk } });
+			});
+
+			coordinator.on("exit", (code: number) => {
+				wsManager?.broadcastEvent({ type: "coordinator_stop", data: { headless: true, code } });
+				headless?.setCoordinator(null);
+			});
+
+			coordinator.start();
+			headless?.setCoordinator(coordinator);
+
+			const responseData = { headless: true, pid: coordinator.getPid() };
+			wsManager?.broadcastEvent({ type: "coordinator_start", data: responseData });
+			return jsonResponse(responseData);
+		}
+
+		const args = ["coordinator", "start", "--no-attach", "--json"];
+		if (parsed.watchdog === true) args.push("--watchdog");
+		if (parsed.monitor === true) args.push("--monitor");
+		const result = await runLegio(args, projectRoot);
+		if (result.ok) {
+			wsManager?.broadcastEvent({ type: "coordinator_start", data: result.data });
+			return jsonResponse(result.data);
+		}
+		return errorResponse(result.error);
+	}
+
+	if (request.method === "POST" && path === "/api/coordinator/stop") {
+		// If headless coordinator is running, stop it
+		if (headless?.coordinator?.isRunning()) {
+			await headless.coordinator.stop();
+			headless.setCoordinator(null);
+			const responseData = { stopped: true, headless: true };
+			wsManager?.broadcastEvent({ type: "coordinator_stop", data: responseData });
+			return jsonResponse(responseData);
+		}
+
+		const parsed = await parseJsonBody(request);
+		if (parsed instanceof Response) return parsed;
+		const result = await runLegio(["coordinator", "stop", "--json"], projectRoot);
+		if (result.ok) {
+			wsManager?.broadcastEvent({ type: "coordinator_stop", data: result.data });
+			return jsonResponse(result.data);
+		}
+		return errorResponse(result.error);
+	}
+
+	// -------------------------------------------------------------------------
+	// Merge — POST route (before the GET-only guard)
+	// -------------------------------------------------------------------------
+
+	if (request.method === "POST" && path === "/api/merge") {
+		const parsed = await parseJsonBody(request);
+		if (parsed instanceof Response) return parsed;
+
+		const branch = typeof parsed.branch === "string" ? parsed.branch : null;
+		const all = parsed.all === true;
+
+		if (!branch && !all) {
+			return errorResponse("Must specify either branch or all", 400);
+		}
+
+		const args = ["merge", "--json"];
+		if (branch) args.push("--branch", branch);
+		if (all) args.push("--all");
+		if (typeof parsed.into === "string") args.push("--into", parsed.into);
+		if (parsed.dryRun === true) args.push("--dry-run");
+
+		const result = await runLegio(args, projectRoot);
+		if (result.ok) {
+			wsManager?.broadcastEvent({ type: "merge_complete", data: result.data });
+			return jsonResponse(result.data);
+		}
+		return errorResponse(result.error);
+	}
+
+	// -------------------------------------------------------------------------
+	// Nudge — POST route (before the GET-only guard)
+	// -------------------------------------------------------------------------
+
+	if (request.method === "POST" && path === "/api/nudge") {
+		const parsed = await parseJsonBody(request);
+		if (parsed instanceof Response) return parsed;
+
+		const agent = typeof parsed.agent === "string" ? parsed.agent : null;
+		if (!agent) return errorResponse("Missing required field: agent", 400);
+
+		const message = typeof parsed.message === "string" ? parsed.message : null;
+		const args = ["nudge", agent];
+		if (message) args.push(message);
+		args.push("--json");
+
+		const result = await runLegio(args, projectRoot);
+		if (result.ok) {
+			wsManager?.broadcastEvent({ type: "agent_nudge", data: { agent, message } });
+			return jsonResponse(result.data);
+		}
+		return errorResponse(result.error);
+	}
+
+	// -------------------------------------------------------------------------
+	// Gateway — POST routes (before the GET-only guard)
+	// -------------------------------------------------------------------------
+
+	if (request.method === "POST" && path === "/api/gateway/start") {
+		const parsed = await parseJsonBody(request);
+		if (parsed instanceof Response) return parsed;
+		const result = await runLegio(["gateway", "start", "--no-attach", "--json"], projectRoot);
+		if (result.ok) {
+			wsManager?.broadcastEvent({ type: "gateway_start", data: result.data });
+			return jsonResponse(result.data);
+		}
+		return errorResponse(result.error);
+	}
+
+	if (request.method === "POST" && path === "/api/gateway/stop") {
+		const parsed = await parseJsonBody(request);
+		if (parsed instanceof Response) return parsed;
+		const result = await runLegio(["gateway", "stop", "--json"], projectRoot);
+		if (result.ok) {
+			wsManager?.broadcastEvent({ type: "gateway_stop", data: result.data });
+			return jsonResponse(result.data);
+		}
+		return errorResponse(result.error);
+	}
+
+	if (request.method === "POST" && path === "/api/gateway/chat") {
+		const parsed = await parseJsonBody(request);
+		if (parsed instanceof Response) return parsed;
+
+		const text = typeof parsed.text === "string" ? parsed.text.trim() : null;
+		if (!text) return errorResponse("Missing or empty required field: text", 400);
+
+		const tmuxSession = await resolveTerminalSession(legioDir, projectRoot, "gateway");
+		if (!tmuxSession) {
+			return errorResponse("Gateway is not running", 404);
+		}
+
+		if (!(await isSessionAlive(tmuxSession))) {
+			return errorResponse(`Gateway tmux session "${tmuxSession}" is not alive`, 404);
+		}
+
+		const mailStore = createMailStore(join(legioDir, "mail.db"));
+		const savedMessage = mailStore.insert({
+			id: "",
+			from: "human",
+			to: "gateway",
+			subject: "chat",
+			body: text,
+			type: "status",
+			priority: "normal",
+			threadId: null,
+			audience: "human",
+		});
+		mailStore.close();
+		wsManager?.broadcastEvent({ type: "mail_new", data: savedMessage });
+
+		try {
+			await sendKeys(tmuxSession, text);
+		} catch (err) {
+			return errorResponse(
+				`Failed to send keys: ${err instanceof Error ? err.message : String(err)}`,
+			);
+		}
+
+		return jsonResponse(savedMessage, 201);
+	}
+
+	// -------------------------------------------------------------------------
+	// Coordinator Chat — POST /api/coordinator/chat (before GET-only guard)
+	// -------------------------------------------------------------------------
+
+	if (request.method === "POST" && path === "/api/coordinator/chat") {
+		const parsed = await parseJsonBody(request);
+		if (parsed instanceof Response) return parsed;
+
+		const text = typeof parsed.text === "string" ? parsed.text.trim() : null;
+		if (!text) return errorResponse("Missing or empty required field: text", 400);
+
+		const mailStore = createMailStore(join(legioDir, "mail.db"));
+		const savedMessage = mailStore.insert({
+			id: "",
+			from: "human",
+			to: "coordinator",
+			subject: "chat",
+			body: text,
+			type: "status",
+			priority: "normal",
+			threadId: null,
+			audience: "human",
+		});
+		mailStore.close();
+
+		// Forward to terminal: headless coordinator first, then tmux fallback
+		const agentName = "coordinator";
+		if (
+			(agentName === "coordinator" || agentName === "headless") &&
+			headless?.coordinator?.isRunning()
+		) {
+			try {
+				headless.coordinator.write(`${text}\n`);
+			} catch (err) {
+				return errorResponse(
+					`Failed to write to headless coordinator: ${err instanceof Error ? err.message : String(err)}`,
+				);
+			}
+			return jsonResponse(savedMessage, 201);
+		}
+
+		const tmuxSession = await resolveTerminalSession(legioDir, projectRoot, agentName);
+		if (!tmuxSession) {
+			return errorResponse(`Cannot resolve tmux session for agent "${agentName}"`, 404);
+		}
+
+		if (!(await isSessionAlive(tmuxSession))) {
+			return errorResponse(`Tmux session "${tmuxSession}" is not alive`, 404);
+		}
+
+		try {
+			await sendKeys(tmuxSession, text);
+			await new Promise((resolve) => setTimeout(resolve, 500));
+			await sendKeys(tmuxSession, "");
+		} catch (err) {
+			return errorResponse(
+				`Failed to send keys: ${err instanceof Error ? err.message : String(err)}`,
+			);
+		}
+
+		return jsonResponse(savedMessage, 201);
+	}
+
+	// -------------------------------------------------------------------------
+	// Agent Chat — POST /api/agents/:name/chat (before GET-only guard)
+	// -------------------------------------------------------------------------
+
+	{
+		const params = matchRoute(path, "/api/agents/:name/chat");
+		if (request.method === "POST" && params) {
+			const agentName = params.name;
+			if (!agentName) return errorResponse("Missing agent name", 400);
+
+			const parsed = await parseJsonBody(request);
+			if (parsed instanceof Response) return parsed;
+
+			const text = typeof parsed.text === "string" ? parsed.text.trim() : null;
+			if (!text) return errorResponse("Missing or empty required field: text", 400);
+
+			const mailStore = createMailStore(join(legioDir, "mail.db"));
+			const savedMessage = mailStore.insert({
+				id: "",
+				from: "human",
+				to: agentName,
+				subject: "chat",
+				body: text,
+				type: "status",
+				priority: "normal",
+				threadId: null,
+				audience: "human",
+			});
+			mailStore.close();
+
+			// Forward to terminal: headless coordinator first (when agent is coordinator), then tmux
+			if (
+				(agentName === "coordinator" || agentName === "headless") &&
+				headless?.coordinator?.isRunning()
+			) {
+				try {
+					headless.coordinator.write(`${text}\n`);
+				} catch (err) {
+					return errorResponse(
+						`Failed to write to headless coordinator: ${err instanceof Error ? err.message : String(err)}`,
+					);
+				}
+				return jsonResponse(savedMessage, 201);
+			}
+
+			const tmuxSession = await resolveTerminalSession(legioDir, projectRoot, agentName);
+			if (!tmuxSession) {
+				return errorResponse(`Cannot resolve tmux session for agent "${agentName}"`, 404);
+			}
+
+			if (!(await isSessionAlive(tmuxSession))) {
+				return errorResponse(`Tmux session "${tmuxSession}" is not alive`, 404);
+			}
+
+			try {
+				await sendKeys(tmuxSession, text);
+				await new Promise((resolve) => setTimeout(resolve, 500));
+				await sendKeys(tmuxSession, "");
+			} catch (err) {
+				return errorResponse(
+					`Failed to send keys: ${err instanceof Error ? err.message : String(err)}`,
+				);
+			}
+
+			return jsonResponse(savedMessage, 201);
+		}
+	}
+
+	// -------------------------------------------------------------------------
+	// Transcript Sync — POST /api/chat/transcript-sync
+	// Triggers on-demand transcript sync for a persistent agent.
+	// -------------------------------------------------------------------------
+
+	if (request.method === "POST" && path === "/api/chat/transcript-sync") {
+		const parsed = await parseJsonBody(request);
+		if (parsed instanceof Response) return parsed;
+
+		const agentName = typeof parsed.agent === "string" ? parsed.agent.trim() : null;
+		if (!agentName) return errorResponse("Missing or empty required field: agent", 400);
+
+		if (!(await fileExists(join(legioDir, "sessions.db")))) {
+			return errorResponse("No sessions database found", 404);
+		}
+
+		const { store: sessionStore } = openSessionStore(legioDir);
+		try {
+			const sessions = sessionStore.getActive();
+			const agentSession = sessions.find((s) => s.agentName === agentName);
+			if (!agentSession) {
+				return errorResponse(`No active session found for agent "${agentName}"`, 404);
+			}
+
+			const logsBase = join(legioDir, "logs");
+			const cachePath = join(logsBase, agentName, ".transcript-path");
+			let transcriptPath: string | null = null;
+			try {
+				const cached = (await readFile(cachePath, "utf-8")).trim();
+				if (cached.length > 0) {
+					await access(cached, constants.R_OK);
+					transcriptPath = cached;
+				}
+			} catch {
+				// No cached transcript path
+			}
+
+			if (!transcriptPath) {
+				return errorResponse(`No transcript found for agent "${agentName}"`, 404);
+			}
+
+			const { parseTranscriptTexts } = await import("../metrics/transcript.ts");
+			const offsetPath = join(logsBase, agentName, ".chat-transcript-offset");
+			const mailStore = createMailStore(join(legioDir, "mail.db"));
+			try {
+				let fromLine = 0;
+				try {
+					const savedOffset = await readFile(offsetPath, "utf-8");
+					const parsedOffset = Number.parseInt(savedOffset.trim(), 10);
+					if (!Number.isNaN(parsedOffset) && parsedOffset >= 0) {
+						fromLine = parsedOffset;
+					}
+				} catch {
+					// No offset file yet — start from beginning.
+					// If messages already exist for this agent, we're in a restart scenario.
+					// Skip to the end to avoid replaying old messages.
+					const existingMessages = mailStore.getAll({ from: agentName, to: "human" });
+					if (existingMessages.length > 0) {
+						const { nextLine: endLine } = await parseTranscriptTexts(transcriptPath, 0);
+						await writeFile(offsetPath, String(endLine));
+						return jsonResponse({ synced: 0, skipped: true, reason: "offset_recovered" });
+					}
+				}
+
+				const { messages, nextLine } = await parseTranscriptTexts(transcriptPath, fromLine);
+				const assistantMessages = messages.filter((m) => m.role === "assistant");
+
+				let synced = 0;
+				if (assistantMessages.length > 0) {
+					// Dedup: build a set of recent message bodies to skip replays.
+					const oneDayAgo = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
+					const recentBodies = new Set(
+						mailStore
+							.getAll({ from: agentName, to: "human" })
+							.filter((m) => m.createdAt > oneDayAgo)
+							.map((m) => m.body),
+					);
+
+					for (const msg of assistantMessages) {
+						if (recentBodies.has(msg.text)) continue;
+						const savedMsg = mailStore.insert({
+							id: "",
+							from: agentName,
+							to: "human",
+							subject: "chat",
+							body: msg.text,
+							type: "status",
+							priority: "normal",
+							threadId: null,
+							audience: "human",
+						});
+						wsManager?.broadcastEvent({ type: "mail_new", data: savedMsg });
+						synced++;
+					}
+				}
+
+				await writeFile(offsetPath, String(nextLine));
+
+				return jsonResponse({
+					synced,
+					nextLine,
+					agent: agentName,
+				});
+			} finally {
+				mailStore.close();
+			}
+		} finally {
+			sessionStore.close();
+		}
+	}
+
+	// -------------------------------------------------------------------------
+	// Issues — POST routes (before the GET-only guard)
+	// -------------------------------------------------------------------------
+
+	{
+		const params = matchRoute(path, "/api/issues/:id/dispatch");
+		if (request.method === "POST" && params) {
+			const { id } = params;
+			if (!id) return errorResponse("Missing issue ID", 400);
+			try {
+				const client = createBeadsClient(projectRoot);
+				const issue = await client.show(id);
+				const body = issue.description ? `${issue.title}\n\n${issue.description}` : issue.title;
+				const store = createMailStore(join(legioDir, "mail.db"));
+				const messageId = `issue-dispatch-${randomUUID().slice(0, 8)}`;
+				store.insert({
+					id: messageId,
+					from: "human",
+					to: "coordinator",
+					subject: `dispatch: ${issue.title}`,
+					body,
+					type: "dispatch",
+					priority: "normal",
+					threadId: null,
+					audience: "agent",
+				});
+				store.close();
+				return jsonResponse({ success: true, message: "Dispatched" });
+			} catch (err) {
+				if (err instanceof Error && err.message.toLowerCase().includes("not found")) {
+					return errorResponse(`Issue not found: ${id}`, 404);
+				}
+				return errorResponse(
+					`Failed to dispatch issue: ${err instanceof Error ? err.message : String(err)}`,
+				);
+			}
+		}
+	}
+
+	{
+		const params = matchRoute(path, "/api/issues/:id/close");
+		if (request.method === "POST" && params) {
+			const { id } = params;
+			if (!id) return errorResponse("Missing issue ID", 400);
+			try {
+				const body = await request.json().catch(() => ({})) as { reason?: string };
+				const reason = typeof body.reason === "string" ? body.reason : "Closed from dashboard";
+				const client = createBeadsClient(projectRoot);
+				await client.close(id, reason);
+				return jsonResponse({ success: true, id });
+			} catch (err) {
+				if (err instanceof Error && err.message.toLowerCase().includes("not found")) {
+					return errorResponse(`Issue not found: ${id}`, 404);
+				}
+				return errorResponse(
+					`Failed to close issue: ${err instanceof Error ? err.message : String(err)}`,
+				);
+			}
+		}
+	}
+
+	// Only handle GET requests for all other routes
+	if (request.method !== "GET") {
+		return errorResponse("Method not allowed", 405);
+	}
+
+	// -------------------------------------------------------------------------
+	// Core
+	// -------------------------------------------------------------------------
+
+	if (path === "/api/health") {
+		return jsonResponse({ ok: true, timestamp: new Date().toISOString() });
+	}
+
+	if (path === "/api/setup/status") {
+		const configPath = join(legioDir, "config.yaml");
+		const initialized = await fileExists(configPath);
+		let projectName: string | null = null;
+		if (initialized) {
+			try {
+				const config = await loadConfig(projectRoot);
+				projectName = config.project.name;
+			} catch {
+				// ignore — return initialized: true with null name
+			}
+		}
+		return jsonResponse({ initialized, projectName, projectRoot });
+	}
+
+	if (path === "/api/status") {
+		try {
+			const data = await gatherStatus(projectRoot, "orchestrator", true);
+			return jsonResponse(data);
+		} catch (err) {
+			return errorResponse(
+				`Failed to gather status: ${err instanceof Error ? err.message : String(err)}`,
+			);
+		}
+	}
+
+	if (path === "/api/coordinator/status") {
+		// Check headless coordinator first
+		const headlessRunning = headless?.coordinator?.isRunning() ?? false;
+		if (headlessRunning) {
+			return jsonResponse({
+				running: true,
+				headless: true,
+				tmuxSession: undefined,
+			});
+		}
+
+		const tmuxSession = await resolveTerminalSession(legioDir, projectRoot, "coordinator");
+		return jsonResponse({
+			running: tmuxSession !== null,
+			headless: false,
+			tmuxSession: tmuxSession ?? undefined,
+		});
+	}
+
+	if (path === "/api/gateway/status") {
+		const tmuxSession = await resolveTerminalSession(legioDir, projectRoot, "gateway");
+		return jsonResponse({
+			running: tmuxSession !== null,
+			tmuxSession: tmuxSession ?? undefined,
+		});
+	}
+
+	if (path === "/api/config") {
+		try {
+			const config = await loadConfig(projectRoot);
+			return jsonResponse(config);
+		} catch (err) {
+			return errorResponse(
+				`Failed to load config: ${err instanceof Error ? err.message : String(err)}`,
+			);
+		}
+	}
+
+	// -------------------------------------------------------------------------
+	// Agents — specific routes before parameterized
+	// -------------------------------------------------------------------------
+
+	if (path === "/api/agents") {
+		const dbPath = join(legioDir, "sessions.db");
+		if (!(await fileExists(dbPath))) {
+			return jsonResponse([]);
+		}
+		const { store } = openSessionStore(legioDir);
+		try {
+			return jsonResponse(store.getAll());
+		} finally {
+			store.close();
+		}
+	}
+
+	if (path === "/api/agents/active") {
+		const dbPath = join(legioDir, "sessions.db");
+		if (!(await fileExists(dbPath))) {
+			return jsonResponse([]);
+		}
+		const { store } = openSessionStore(legioDir);
+		try {
+			return jsonResponse(store.getActive());
+		} finally {
+			store.close();
+		}
+	}
+
+	// /api/agents/:name/chat/history
+	{
+		const params = matchRoute(path, "/api/agents/:name/chat/history");
+		if (params) {
+			const agentName = params.name;
+			if (!agentName) return errorResponse("Missing agent name", 400);
+			const dbPath = join(legioDir, "mail.db");
+			if (!(await fileExists(dbPath))) {
+				return jsonResponse([]);
+			}
+			const limitParam = url.searchParams.get("limit");
+			const limit = limitParam !== null ? Math.max(1, parseInt(limitParam, 10) || 100) : 100;
+			const store = createMailStore(dbPath);
+			try {
+				const humanToAgent = store.getAll({ from: "human", to: agentName });
+				const agentToHuman = store.getAll({ from: agentName, to: "human" });
+				const combined = [...humanToAgent, ...agentToHuman];
+				const seen = new Set<string>();
+				const relevant = combined.filter((m) => {
+					if (seen.has(m.id)) return false;
+					seen.add(m.id);
+					return m.audience === "human" || m.audience === "both";
+				});
+				relevant.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+				return jsonResponse(relevant.slice(-limit));
+			} finally {
+				store.close();
+			}
+		}
+	}
+
+	// /api/agents/:name/inspect
+	{
+		const params = matchRoute(path, "/api/agents/:name/inspect");
+		if (params) {
+			const { name } = params;
+			if (!name) return errorResponse("Missing agent name", 400);
+			try {
+				const data = await gatherInspectData(projectRoot, name, { noTmux: true });
+				return jsonResponse(data);
+			} catch {
+				return errorResponse(`Agent not found: ${name}`, 404);
+			}
+		}
+	}
+
+	// /api/agents/:name/events
+	{
+		const params = matchRoute(path, "/api/agents/:name/events");
+		if (params) {
+			const { name } = params;
+			if (!name) return errorResponse("Missing agent name", 400);
+			const dbPath = join(legioDir, "events.db");
+			if (!(await fileExists(dbPath))) {
+				return jsonResponse([]);
+			}
+			const since = url.searchParams.get("since") ?? undefined;
+			const until = url.searchParams.get("until") ?? undefined;
+			const limitStr = url.searchParams.get("limit");
+			const limit = limitStr ? Number.parseInt(limitStr, 10) : undefined;
+			const levelParam = url.searchParams.get("level");
+			const level = levelParam ? (levelParam as EventLevel) : undefined;
+			const store = createEventStore(dbPath);
+			try {
+				return jsonResponse(store.getByAgent(name, { since, until, limit, level }));
+			} finally {
+				store.close();
+			}
+		}
+	}
+
+	// /api/agents/:name
+	{
+		const params = matchRoute(path, "/api/agents/:name");
+		if (params) {
+			const { name } = params;
+			if (!name) return errorResponse("Missing agent name", 400);
+			const dbPath = join(legioDir, "sessions.db");
+			if (!(await fileExists(dbPath))) {
+				return errorResponse(`Agent not found: ${name}`, 404);
+			}
+			const { store } = openSessionStore(legioDir);
+			try {
+				const session = store.getByName(name);
+				if (!session) return errorResponse(`Agent not found: ${name}`, 404);
+				return jsonResponse(session);
+			} finally {
+				store.close();
+			}
+		}
+	}
+
+	// -------------------------------------------------------------------------
+	// Mail — specific routes before parameterized
+	// -------------------------------------------------------------------------
+
+	if (path === "/api/mail") {
+		const dbPath = join(legioDir, "mail.db");
+		if (!(await fileExists(dbPath))) {
+			return jsonResponse([]);
+		}
+		const from = url.searchParams.get("from") ?? undefined;
+		const to = url.searchParams.get("to") ?? undefined;
+		const unreadStr = url.searchParams.get("unread");
+		const unread = unreadStr !== null ? unreadStr === "true" : undefined;
+		const audience = url.searchParams.get("audience") ?? undefined;
+		const store = createMailStore(dbPath);
+		try {
+			return jsonResponse(store.getAll({ from, to, unread, audience }));
+		} finally {
+			store.close();
+		}
+	}
+
+	if (path === "/api/mail/unread") {
+		const agent = url.searchParams.get("agent");
+		if (!agent) return errorResponse("Missing required query param: agent", 400);
+		const dbPath = join(legioDir, "mail.db");
+		if (!(await fileExists(dbPath))) {
+			return jsonResponse([]);
+		}
+		const store = createMailStore(dbPath);
+		try {
+			return jsonResponse(store.getUnread(agent));
+		} finally {
+			store.close();
+		}
+	}
+
+	if (path === "/api/mail/conversations") {
+		const dbPath = join(legioDir, "mail.db");
+		if (!(await fileExists(dbPath))) {
+			return jsonResponse([]);
+		}
+		const agentFilter = url.searchParams.get("agent") ?? undefined;
+		const audience = url.searchParams.get("audience") ?? undefined;
+		const store = createMailStore(dbPath);
+		try {
+			const allMessages = store.getAll();
+			const messages =
+				audience !== undefined ? allMessages.filter((m) => m.audience === audience) : allMessages;
+
+			// Group messages by normalized agent pair (sorted alphabetically)
+			const groups = new Map<string, { participants: [string, string]; messages: MailMessage[] }>();
+			for (const msg of messages) {
+				const sorted = [msg.from, msg.to].sort();
+				const a = sorted[0];
+				const b = sorted[1];
+				if (!a || !b) continue;
+				const pair: [string, string] = [a, b];
+				const key = `${a}:${b}`;
+				let group = groups.get(key);
+				if (!group) {
+					group = { participants: pair, messages: [] };
+					groups.set(key, group);
+				}
+				group.messages.push(msg);
+			}
+
+			// Build conversation objects
+			const conversations: Array<{
+				participants: [string, string];
+				lastMessage: MailMessage;
+				messageCount: number;
+				unreadCount: number;
+			}> = [];
+			for (const { participants, messages: msgs } of groups.values()) {
+				if (agentFilter && !participants.includes(agentFilter)) {
+					continue;
+				}
+				const sorted = [...msgs].sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+				const lastMessage = sorted[0];
+				if (!lastMessage) continue;
+				conversations.push({
+					participants,
+					lastMessage,
+					messageCount: msgs.length,
+					unreadCount: msgs.filter((m) => !m.read).length,
+				});
+			}
+
+			// Sort conversations by most recent message first
+			conversations.sort((a, b) => b.lastMessage.createdAt.localeCompare(a.lastMessage.createdAt));
+			return jsonResponse(conversations);
+		} finally {
+			store.close();
+		}
+	}
+
+	// /api/mail/thread/:threadId — before /api/mail/:id
+	{
+		const params = matchRoute(path, "/api/mail/thread/:threadId");
+		if (params) {
+			const { threadId } = params;
+			if (!threadId) return errorResponse("Missing thread ID", 400);
+			const dbPath = join(legioDir, "mail.db");
+			if (!(await fileExists(dbPath))) {
+				return jsonResponse([]);
+			}
+			const store = createMailStore(dbPath);
+			try {
+				return jsonResponse(store.getByThread(threadId));
+			} finally {
+				store.close();
+			}
+		}
+	}
+
+	// /api/mail/:id
+	{
+		const params = matchRoute(path, "/api/mail/:id");
+		if (params) {
+			const { id } = params;
+			if (!id) return errorResponse("Missing message ID", 400);
+			const dbPath = join(legioDir, "mail.db");
+			if (!(await fileExists(dbPath))) {
+				return errorResponse(`Message not found: ${id}`, 404);
+			}
+			const store = createMailStore(dbPath);
+			try {
+				const message = store.getById(id);
+				if (!message) return errorResponse(`Message not found: ${id}`, 404);
+				return jsonResponse(message);
+			} finally {
+				store.close();
+			}
+		}
+	}
+
+	// -------------------------------------------------------------------------
+	// Events — specific routes before parameterized
+	// -------------------------------------------------------------------------
+
+	if (path === "/api/events") {
+		const since = url.searchParams.get("since");
+		if (!since) return errorResponse("Missing required query param: since", 400);
+		const dbPath = join(legioDir, "events.db");
+		if (!(await fileExists(dbPath))) {
+			return jsonResponse([]);
+		}
+		const until = url.searchParams.get("until") ?? undefined;
+		const limitStr = url.searchParams.get("limit");
+		const limit = limitStr ? Number.parseInt(limitStr, 10) : undefined;
+		const levelParam = url.searchParams.get("level");
+		const level = levelParam ? (levelParam as EventLevel) : undefined;
+		const store = createEventStore(dbPath);
+		try {
+			return jsonResponse(store.getTimeline({ since, until, limit, level }));
+		} finally {
+			store.close();
+		}
+	}
+
+	if (path === "/api/events/errors") {
+		const dbPath = join(legioDir, "events.db");
+		if (!(await fileExists(dbPath))) {
+			return jsonResponse([]);
+		}
+		const since = url.searchParams.get("since") ?? undefined;
+		const until = url.searchParams.get("until") ?? undefined;
+		const limitStr = url.searchParams.get("limit");
+		const limit = limitStr ? Number.parseInt(limitStr, 10) : undefined;
+		const store = createEventStore(dbPath);
+		try {
+			return jsonResponse(store.getErrors({ since, until, limit }));
+		} finally {
+			store.close();
+		}
+	}
+
+	if (path === "/api/events/tools") {
+		const dbPath = join(legioDir, "events.db");
+		if (!(await fileExists(dbPath))) {
+			return jsonResponse([]);
+		}
+		const agentName = url.searchParams.get("agent") ?? undefined;
+		const since = url.searchParams.get("since") ?? undefined;
+		const store = createEventStore(dbPath);
+		try {
+			return jsonResponse(store.getToolStats({ agentName, since }));
+		} finally {
+			store.close();
+		}
+	}
+
+	// -------------------------------------------------------------------------
+	// Metrics — specific routes before parameterized
+	// -------------------------------------------------------------------------
+
+	if (path === "/api/metrics") {
+		const dbPath = join(legioDir, "metrics.db");
+		if (!(await fileExists(dbPath))) {
+			return jsonResponse([]);
+		}
+		const limitStr = url.searchParams.get("limit");
+		const limit = limitStr ? Number.parseInt(limitStr, 10) : 100;
+		const since = url.searchParams.get("since") ?? undefined;
+		const until = url.searchParams.get("until") ?? undefined;
+		const store = createMetricsStore(dbPath);
+		try {
+			if (since !== undefined || until !== undefined) {
+				return jsonResponse(store.getSessionsFiltered({ since, until, limit }));
+			}
+			return jsonResponse(store.getRecentSessions(limit));
+		} finally {
+			store.close();
+		}
+	}
+
+	if (path === "/api/metrics/by-model") {
+		const dbPath = join(legioDir, "metrics.db");
+		if (!(await fileExists(dbPath))) {
+			return jsonResponse([]);
+		}
+		const since = url.searchParams.get("since") ?? undefined;
+		const until = url.searchParams.get("until") ?? undefined;
+		const store = createMetricsStore(dbPath);
+		try {
+			return jsonResponse(store.getSessionsByModel({ since, until }));
+		} finally {
+			store.close();
+		}
+	}
+
+	if (path === "/api/metrics/by-date") {
+		const dbPath = join(legioDir, "metrics.db");
+		if (!(await fileExists(dbPath))) {
+			return jsonResponse([]);
+		}
+		const since = url.searchParams.get("since") ?? undefined;
+		const until = url.searchParams.get("until") ?? undefined;
+		const store = createMetricsStore(dbPath);
+		try {
+			return jsonResponse(store.getSessionsByDate({ since, until }));
+		} finally {
+			store.close();
+		}
+	}
+
+	if (path === "/api/metrics/snapshots") {
+		const dbPath = join(legioDir, "metrics.db");
+		if (!(await fileExists(dbPath))) {
+			return jsonResponse([]);
+		}
+		const store = createMetricsStore(dbPath);
+		try {
+			return jsonResponse(store.getLatestSnapshots());
+		} finally {
+			store.close();
+		}
+	}
+
+	// -------------------------------------------------------------------------
+	// Runs — specific routes before parameterized
+	// -------------------------------------------------------------------------
+
+	if (path === "/api/runs") {
+		const dbPath = join(legioDir, "sessions.db");
+		if (!(await fileExists(dbPath))) {
+			return jsonResponse([]);
+		}
+		const limitStr = url.searchParams.get("limit");
+		const limit = limitStr ? Number.parseInt(limitStr, 10) : undefined;
+		const statusParam = url.searchParams.get("status");
+		const status = statusParam as RunStatus | undefined;
+		const store = createRunStore(dbPath);
+		try {
+			return jsonResponse(store.listRuns({ limit, status: status ?? undefined }));
+		} finally {
+			store.close();
+		}
+	}
+
+	if (path === "/api/runs/active") {
+		const dbPath = join(legioDir, "sessions.db");
+		if (!(await fileExists(dbPath))) {
+			return jsonResponse(null);
+		}
+		const store = createRunStore(dbPath);
+		try {
+			return jsonResponse(store.getActiveRun());
+		} finally {
+			store.close();
+		}
+	}
+
+	// /api/runs/:id
+	{
+		const params = matchRoute(path, "/api/runs/:id");
+		if (params) {
+			const { id } = params;
+			if (!id) return errorResponse("Missing run ID", 400);
+			const dbPath = join(legioDir, "sessions.db");
+			if (!(await fileExists(dbPath))) {
+				return errorResponse(`Run not found: ${id}`, 404);
+			}
+			const runStore = createRunStore(dbPath);
+			const sessionStore = createSessionStore(dbPath);
+			try {
+				const run = runStore.getRun(id);
+				if (!run) return errorResponse(`Run not found: ${id}`, 404);
+				const agents = sessionStore.getByRun(id);
+				return jsonResponse({ run, agents });
+			} finally {
+				runStore.close();
+				sessionStore.close();
+			}
+		}
+	}
+
+	// -------------------------------------------------------------------------
+	// Merge Queue
+	// -------------------------------------------------------------------------
+
+	if (path === "/api/merge-queue") {
+		const dbPath = join(legioDir, "merge-queue.db");
+		if (!(await fileExists(dbPath))) {
+			return jsonResponse([]);
+		}
+		const statusParam = url.searchParams.get("status");
+		const queue = createMergeQueue(dbPath);
+		try {
+			const status = statusParam ? (statusParam as MergeEntry["status"]) : undefined;
+			return jsonResponse(queue.list(status));
+		} finally {
+			queue.close();
+		}
+	}
+
+	// -------------------------------------------------------------------------
+	// Issues (beads)
+	// -------------------------------------------------------------------------
+
+	if (path === "/api/issues") {
+		const statusParam = url.searchParams.get("status") ?? undefined;
+		const allParam = url.searchParams.get("all");
+		const all = allParam !== "false"; // default true
+		const limitStr = url.searchParams.get("limit");
+		const limit = limitStr ? Number.parseInt(limitStr, 10) : undefined;
+
+		// Cache key: only use cache for default requests (no filters)
+		const isDefaultRequest = !statusParam && all && !limit;
+		if (isDefaultRequest && issuesCacheData && Date.now() - issuesCacheAt < ISSUES_CACHE_TTL) {
+			return jsonResponse(issuesCacheData);
+		}
+
+		try {
+			const client = createBeadsClient(projectRoot);
+			const issues = await client.list({ status: statusParam, limit, all });
+			if (isDefaultRequest) {
+				issuesCacheData = issues;
+				issuesCacheAt = Date.now();
+			}
+			return jsonResponse(issues);
+		} catch {
+			return jsonResponse([]);
+		}
+	}
+
+	if (path === "/api/issues/ready") {
+		try {
+			const client = createBeadsClient(projectRoot);
+			const issues = await client.ready();
+			return jsonResponse(issues);
+		} catch {
+			return jsonResponse([]);
+		}
+	}
+
+	// /api/issues/:id
+	{
+		const params = matchRoute(path, "/api/issues/:id");
+		if (params) {
+			const { id } = params;
+			if (!id) return errorResponse("Missing issue ID", 400);
+			try {
+				const client = createBeadsClient(projectRoot);
+				const issue = await client.show(id);
+				return jsonResponse(issue);
+			} catch {
+				return errorResponse(`Issue not found: ${id}`, 404);
+			}
+		}
+	}
+
+	// -------------------------------------------------------------------------
+	// Terminal
+	// -------------------------------------------------------------------------
+
+	if (path === "/api/terminal/capture") {
+		const agentName = url.searchParams.get("agent") ?? "coordinator";
+		const linesStr = url.searchParams.get("lines");
+		const lines = linesStr ? Math.max(1, Number.parseInt(linesStr, 10)) : 100;
+
+		// If headless coordinator is running for this agent, return its ring buffer
+		if (
+			(agentName === "coordinator" || agentName === "headless") &&
+			headless?.coordinator?.isRunning()
+		) {
+			return jsonResponse({
+				output: headless.coordinator.getOutput(),
+				agent: agentName,
+				headless: true,
+				timestamp: new Date().toISOString(),
+			});
+		}
+
+		// Try terminal log file first (pipe-pane streaming)
+		let output: string | null = null;
+		const { store: captureStore } = openSessionStore(legioDir);
+		try {
+			const agentSession = captureStore.getByName(agentName);
+			if (agentSession?.terminalLogPath) {
+				output = await readTerminalLog(agentSession.terminalLogPath, lines);
+			}
+		} finally {
+			captureStore.close();
+		}
+
+		// Fall back to capture-pane if no terminal log available
+		if (output === null) {
+			const tmuxSession = await resolveTerminalSession(legioDir, projectRoot, agentName);
+			if (!tmuxSession) {
+				return errorResponse(`Cannot resolve tmux session for agent "${agentName}"`, 404);
+			}
+
+			output = await captureTmuxPane(tmuxSession, lines);
+			if (output === null) {
+				return errorResponse(`Failed to capture tmux pane for session "${tmuxSession}"`);
+			}
+		}
+
+		return jsonResponse({
+			output,
+			agent: agentName,
+			timestamp: new Date().toISOString(),
+		});
+	}
+
+	// -------------------------------------------------------------------------
+	// Audit
+	// -------------------------------------------------------------------------
+
+	if (path === "/api/audit/timeline") {
+		const auditDbPath = join(legioDir, "audit.db");
+		if (!(await fileExists(auditDbPath))) {
+			return jsonResponse([]);
+		}
+		const sinceParam = url.searchParams.get("since");
+		// Default since to 24h ago if not provided
+		const since = sinceParam ?? new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
+		const until = url.searchParams.get("until") ?? undefined;
+		const limitStr = url.searchParams.get("limit");
+		const limit = limitStr ? Number.parseInt(limitStr, 10) : undefined;
+		const store = createAuditStore(auditDbPath);
+		try {
+			return jsonResponse(store.getTimeline({ since, until, limit }));
+		} finally {
+			store.close();
+		}
+	}
+
+	if (path === "/api/audit") {
+		const auditDbPath = join(legioDir, "audit.db");
+		if (!(await fileExists(auditDbPath))) {
+			return jsonResponse([]);
+		}
+		const since = url.searchParams.get("since") ?? undefined;
+		const until = url.searchParams.get("until") ?? undefined;
+		const agent = url.searchParams.get("agent") ?? undefined;
+		const type = url.searchParams.get("type") ?? undefined;
+		const source = url.searchParams.get("source") ?? undefined;
+		const limitStr = url.searchParams.get("limit");
+		const limit = limitStr ? Number.parseInt(limitStr, 10) : undefined;
+		const store = createAuditStore(auditDbPath);
+		try {
+			return jsonResponse(store.getAll({ since, until, agent, type, source, limit }));
+		} finally {
+			store.close();
+		}
+	}
+
+	// -------------------------------------------------------------------------
+	// Ideas
+	// -------------------------------------------------------------------------
+
+	if (path === "/api/ideas") {
+		const ideasPath = join(legioDir, "ideas.json");
+		if (!(await fileExists(ideasPath))) {
+			return jsonResponse([]);
+		}
+		try {
+			const raw = await readFile(ideasPath, "utf-8");
+			const data = JSON.parse(raw) as IdeasFile;
+			return jsonResponse(data.ideas ?? []);
+		} catch (err) {
+			return errorResponse(
+				`Failed to read ideas.json: ${err instanceof Error ? err.message : String(err)}`,
+			);
+		}
+	}
+
+	// -------------------------------------------------------------------------
+	// Coordinator Chat — GET /api/coordinator/chat/history
+	// -------------------------------------------------------------------------
+
+	if (path === "/api/coordinator/chat/history") {
+		const limitParam = url.searchParams.get("limit");
+		const limit = limitParam !== null ? Math.max(1, parseInt(limitParam, 10) || 100) : 100;
+		const dbPath = join(legioDir, "mail.db");
+		if (!(await fileExists(dbPath))) {
+			return jsonResponse([]);
+		}
+		const store = createMailStore(dbPath);
+		try {
+			const humanToCoord = store.getAll({ from: "human", to: "coordinator" });
+			const coordToHuman = store.getAll({ from: "coordinator", to: "human" });
+			const combined = [...humanToCoord, ...coordToHuman];
+			const seen = new Set<string>();
+			const relevant = combined.filter((m) => {
+				if (seen.has(m.id)) return false;
+				seen.add(m.id);
+				return m.audience === "human" || m.audience === "both";
+			});
+			relevant.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+			return jsonResponse(relevant.slice(-limit));
+		} finally {
+			store.close();
+		}
+	}
+
+	// -------------------------------------------------------------------------
+	// Gateway Chat — GET /api/gateway/chat/history
+	// -------------------------------------------------------------------------
+
+	if (path === "/api/gateway/chat/history") {
+		const limitParam = url.searchParams.get("limit");
+		const limit = limitParam !== null ? Math.max(1, parseInt(limitParam, 10) || 100) : 100;
+		const dbPath = join(legioDir, "mail.db");
+		if (!(await fileExists(dbPath))) {
+			return jsonResponse([]);
+		}
+		const store = createMailStore(dbPath);
+		try {
+			const humanToGateway = store.getAll({ from: "human", to: "gateway" });
+			const gatewayToHuman = store.getAll({ from: "gateway", to: "human" });
+			const combined = [...humanToGateway, ...gatewayToHuman];
+			const seen = new Set<string>();
+			const relevant = combined.filter((m) => {
+				if (seen.has(m.id)) return false;
+				seen.add(m.id);
+				return m.audience === "human" || m.audience === "both";
+			});
+			relevant.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+			return jsonResponse(relevant.slice(-limit));
+		} finally {
+			store.close();
+		}
+	}
+
+	// -------------------------------------------------------------------------
+	// Unified Chat History — GET /api/chat/unified/history
+	// Returns all human-audience messages across all agents in chronological order.
+	// Bidirectional: includes messages from human AND messages to human,
+	// filtered by audience (human or both).
+	// -------------------------------------------------------------------------
+
+	if (path === "/api/chat/unified/history") {
+		const limitParam = url.searchParams.get("limit");
+		const limit = limitParam !== null ? Math.max(1, parseInt(limitParam, 10) || 200) : 200;
+		const dbPath = join(legioDir, "mail.db");
+		if (!(await fileExists(dbPath))) {
+			return jsonResponse([]);
+		}
+		const store = createMailStore(dbPath);
+		try {
+			const fromHuman = store.getAll({ from: "human" });
+			const toHuman = store.getAll({ to: "human" });
+			const combined = [...fromHuman, ...toHuman];
+			const seen = new Set<string>();
+			const relevant = combined.filter((m) => {
+				if (seen.has(m.id)) return false;
+				seen.add(m.id);
+				return m.audience === "human" || m.audience === "both";
+			});
+			relevant.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+			return jsonResponse(relevant.slice(-limit));
+		} finally {
+			store.close();
+		}
+	}
+
+	// -------------------------------------------------------------------------
+	// Catch-all for unmatched /api/* paths
+	// -------------------------------------------------------------------------
+
+	return errorResponse("Not found", 404);
+}