@ag-eco/agentplate-cli 0.13.0

package/src/commands/serve/rest.ts

@@ -0,0 +1,1130 @@
+/**
+ * REST API handlers for `ap serve`.
+ *
+ * Registers read-only endpoints that surface data from existing SQLite stores
+ * (EventStore, MailStore, SessionStore, RunStore). No new persistence.
+ *
+ * Route registration via registerApiHandler — no changes to serve.ts required
+ * beyond the single registerRestApi() call.
+ */
+
+import { existsSync } from "node:fs";
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import type { DoctorCategory } from "../../doctor/types.ts";
+import { AgentError, AgentplateError, ValidationError } from "../../errors.ts";
+import { createEventStore } from "../../events/store.ts";
+import { apiError, apiJson } from "../../json.ts";
+import type { MailStore } from "../../mail/store.ts";
+import { createMailStore } from "../../mail/store.ts";
+import { createMergeQueue } from "../../merge/queue.ts";
+import type { MetricsStore } from "../../metrics/store.ts";
+import { createMetricsStore } from "../../metrics/store.ts";
+import { generateSummary } from "../../metrics/summary.ts";
+import type { SessionStore } from "../../sessions/store.ts";
+import { createRunStore, createSessionStore } from "../../sessions/store.ts";
+import type { EventStore, MergeEntry, RunStore } from "../../types.ts";
+import { listWorktrees } from "../../worktree/manager.ts";
+import { loadGroups } from "../group.ts";
+import { discoverLogFiles, filterEvents, parseLogFile } from "../logs.ts";
+import { registerApiHandler } from "../serve.ts";
+import {
+	type AgentActionDeps,
+	mergePreview,
+	mergeRun,
+	slingAgent,
+	stopAgent,
+} from "./agent-actions.ts";
+import {
+	askCoordinatorAction,
+	ConflictError,
+	type CoordinatorActionDeps,
+	checkCoordinatorComplete,
+	getCoordinatorState,
+	sendToCoordinator,
+	startCoordinatorHeadless,
+	stopCoordinator,
+} from "./coordinator-actions.ts";
+import { deleteMail, replyMail, sendMail } from "./mail-actions.ts";
+
+// ─── Cursor helpers ───────────────────────────────────────────────────────────
+
+type Cursor = { ts: string; id: string };
+
+function encodeCursor(c: Cursor): string {
+	return Buffer.from(JSON.stringify(c)).toString("base64url");
+}
+
+function decodeCursor(s: string): Cursor {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(Buffer.from(s, "base64url").toString("utf-8"));
+	} catch {
+		throw new ValidationError("Invalid cursor", { field: "cursor", value: s });
+	}
+	const p = parsed as Record<string, unknown>;
+	if (typeof p.ts !== "string" || typeof p.id !== "string") {
+		throw new ValidationError("Invalid cursor", { field: "cursor", value: s });
+	}
+	return { ts: p.ts, id: p.id };
+}
+
+function parseLimitAndCursor(params: URLSearchParams): { limit: number; cursor: Cursor | null } {
+	const limitStr = params.get("limit");
+	const limit = limitStr !== null ? Number.parseInt(limitStr, 10) : 100;
+	if (Number.isNaN(limit) || limit < 1 || limit > 500) {
+		throw new ValidationError(`Invalid limit: ${limitStr ?? "undefined"}`, {
+			field: "limit",
+			value: limitStr,
+		});
+	}
+
+	const cursorStr = params.get("cursor");
+	const cursor = cursorStr !== null ? decodeCursor(cursorStr) : null;
+
+	return { limit, cursor };
+}
+
+// ─── Generic paginator (for string-id collections) ───────────────────────────
+
+interface PaginateResult<T> {
+	page: T[];
+	nextCursor: string | null;
+}
+
+/**
+ * Client-side paginator for pre-sorted collections with string IDs.
+ * direction="asc":  keep items where (ts > cursorTs) OR (ts === cursorTs AND id > cursorId)
+ * direction="desc": keep items where (ts < cursorTs) OR (ts === cursorTs AND id < cursorId)
+ */
+function paginateItems<T extends { id: string }>(
+	items: T[],
+	cursor: Cursor | null,
+	limit: number,
+	getTs: (item: T) => string,
+	direction: "asc" | "desc",
+): PaginateResult<T> {
+	let filtered = items;
+
+	if (cursor !== null) {
+		const { ts: cTs, id: cId } = cursor;
+		if (direction === "asc") {
+			filtered = items.filter((item) => {
+				const ts = getTs(item);
+				if (ts > cTs) return true;
+				if (ts === cTs && item.id > cId) return true;
+				return false;
+			});
+		} else {
+			filtered = items.filter((item) => {
+				const ts = getTs(item);
+				if (ts < cTs) return true;
+				if (ts === cTs && item.id < cId) return true;
+				return false;
+			});
+		}
+	}
+
+	const page = filtered.slice(0, limit);
+	const hasMore = filtered.length > limit;
+	const lastItem = page[page.length - 1];
+	const nextCursor =
+		hasMore && lastItem !== undefined
+			? encodeCursor({ ts: getTs(lastItem), id: lastItem.id })
+			: null;
+
+	return { page, nextCursor };
+}
+
+// ─── Error → HTTP status ──────────────────────────────────────────────────────
+
+function statusFromError(err: AgentplateError): number {
+	if (err instanceof ValidationError) return 400;
+	if (err instanceof ConflictError) return 409;
+	// AgentError with "not running" message — surface as 409 (preconditions
+	// failed) so the UI can offer a "start coordinator" affordance instead of
+	// treating it as a server-side fault.
+	if (err instanceof AgentError && /not running/i.test(err.message)) return 409;
+	return 500;
+}
+
+// ─── Stores ───────────────────────────────────────────────────────────────────
+
+export interface RestApiDeps {
+	_runStore?: RunStore;
+	_sessionStore?: SessionStore;
+	_eventStore?: EventStore;
+	_mailStore?: MailStore;
+	_metricsStore?: MetricsStore;
+	_projectRoot?: string;
+	/**
+	 * Override coordinator action functions (used by tests). When omitted, the
+	 * production functions imported from ./coordinator-actions.ts are called.
+	 */
+	_coordinatorActions?: {
+		getCoordinatorState?: typeof getCoordinatorState;
+		sendToCoordinator?: typeof sendToCoordinator;
+		askCoordinatorAction?: typeof askCoordinatorAction;
+		checkCoordinatorComplete?: typeof checkCoordinatorComplete;
+		startCoordinatorHeadless?: typeof startCoordinatorHeadless;
+		stopCoordinator?: typeof stopCoordinator;
+	};
+	/**
+	 * Override the deps passed to coordinator-actions. When omitted, the actions
+	 * use deps.projectRoot to open their own short-lived stores. Tests pass
+	 * `_sessionStore` / `_mailStore` so actions reuse the test harness DBs.
+	 */
+	_coordinatorActionDeps?: Partial<CoordinatorActionDeps>;
+	/**
+	 * Override the fleet-control action functions (sling/stop/merge). Tests
+	 * inject fakes to avoid spawning real agents or invoking git.
+	 */
+	_agentActions?: {
+		slingAgent?: typeof slingAgent;
+		stopAgent?: typeof stopAgent;
+		mergePreview?: typeof mergePreview;
+		mergeRun?: typeof mergeRun;
+	};
+	/** Override the deps passed to agent-actions (e.g. injected SessionStore). */
+	_agentActionDeps?: Partial<AgentActionDeps>;
+}
+
+interface Stores {
+	run: RunStore;
+	session: SessionStore;
+	event: EventStore;
+	mail: MailStore;
+	metrics: MetricsStore;
+}
+
+function openStores(projectRoot: string): Stores {
+	const ovDir = join(projectRoot, ".agentplate");
+	const sessionsDb = join(ovDir, "sessions.db");
+	const eventsDb = join(ovDir, "events.db");
+	const mailDb = join(ovDir, "mail.db");
+	const metricsDb = join(ovDir, "metrics.db");
+	return {
+		run: createRunStore(sessionsDb),
+		session: createSessionStore(sessionsDb),
+		event: createEventStore(eventsDb),
+		mail: createMailStore(mailDb),
+		metrics: createMetricsStore(metricsDb),
+	};
+}
+
+// ─── Route table ─────────────────────────────────────────────────────────────
+
+type RouteHandler = (
+	req: Request,
+	match: RegExpMatchArray,
+	params: URLSearchParams,
+	stores: Stores,
+	ctx: HandlerContext,
+) => Promise<Response>;
+
+interface Route {
+	method: string;
+	pattern: RegExp;
+	handler: RouteHandler;
+}
+
+/**
+ * Per-request context passed to every handler. Holds the resolved coordinator
+ * action functions (live or DI-overridden) and the deps that drive them.
+ */
+interface HandlerContext {
+	projectRoot: string;
+	coordinatorActions: {
+		getCoordinatorState: typeof getCoordinatorState;
+		sendToCoordinator: typeof sendToCoordinator;
+		askCoordinatorAction: typeof askCoordinatorAction;
+		checkCoordinatorComplete: typeof checkCoordinatorComplete;
+		startCoordinatorHeadless: typeof startCoordinatorHeadless;
+		stopCoordinator: typeof stopCoordinator;
+	};
+	coordinatorActionDeps: CoordinatorActionDeps;
+	agentActions: {
+		slingAgent: typeof slingAgent;
+		stopAgent: typeof stopAgent;
+		mergePreview: typeof mergePreview;
+		mergeRun: typeof mergeRun;
+	};
+	agentActionDeps: AgentActionDeps;
+}
+
+// ─── Body parsing ────────────────────────────────────────────────────────────
+
+async function readJsonBody<T>(req: Request, validate: (v: unknown) => T): Promise<T> {
+	let raw: unknown;
+	try {
+		raw = await req.json();
+	} catch {
+		throw new ValidationError("Invalid JSON body");
+	}
+	return validate(raw);
+}
+
+function asObject(v: unknown, msg: string): Record<string, unknown> {
+	if (v === null || typeof v !== "object" || Array.isArray(v)) {
+		throw new ValidationError(msg);
+	}
+	return v as Record<string, unknown>;
+}
+
+function requireString(obj: Record<string, unknown>, field: string): string {
+	const v = obj[field];
+	if (typeof v !== "string" || v.length === 0) {
+		throw new ValidationError(`Missing or invalid '${field}' (string)`, { field, value: v });
+	}
+	return v;
+}
+
+function optionalString(obj: Record<string, unknown>, field: string): string | undefined {
+	const v = obj[field];
+	if (v === undefined || v === null) return undefined;
+	if (typeof v !== "string") {
+		throw new ValidationError(`Invalid '${field}' (must be string)`, { field, value: v });
+	}
+	return v;
+}
+
+function optionalTimeoutSec(obj: Record<string, unknown>): number {
+	const v = obj.timeoutSec;
+	if (v === undefined || v === null) return 120;
+	if (typeof v !== "number" || !Number.isFinite(v) || v < 1 || v > 600) {
+		throw new ValidationError("Invalid 'timeoutSec' (must be a number 1..600)", {
+			field: "timeoutSec",
+			value: v,
+		});
+	}
+	return v;
+}
+
+async function parseJsonBody(req: Request): Promise<Record<string, unknown>> {
+	let parsed: unknown;
+	try {
+		parsed = await req.json();
+	} catch (err) {
+		throw new ValidationError(
+			`Invalid JSON body: ${err instanceof Error ? err.message : String(err)}`,
+			{
+				field: "body",
+			},
+		);
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw new ValidationError("Request body must be a JSON object", { field: "body" });
+	}
+	return parsed as Record<string, unknown>;
+}
+
+// ─── Individual handlers ──────────────────────────────────────────────────────
+
+async function handleGetRuns(
+	_req: Request,
+	_match: RegExpMatchArray,
+	params: URLSearchParams,
+	stores: Stores,
+): Promise<Response> {
+	const { limit, cursor } = parseLimitAndCursor(params);
+	const all = stores.run.listRuns();
+	// Sort DESC by (startedAt, id)
+	const sorted = [...all].sort((a, b) => {
+		if (b.startedAt !== a.startedAt) return b.startedAt < a.startedAt ? -1 : 1;
+		return b.id < a.id ? -1 : 1;
+	});
+	const { page, nextCursor } = paginateItems(sorted, cursor, limit, (r) => r.startedAt, "desc");
+	return apiJson(page, { nextCursor });
+}
+
+async function handleGetRun(
+	_req: Request,
+	match: RegExpMatchArray,
+	_params: URLSearchParams,
+	stores: Stores,
+): Promise<Response> {
+	const id = match[1];
+	if (id === undefined) return apiError("Run ID required", 400);
+	const run = stores.run.getRun(id);
+	if (run === null) return apiError(`Run not found: ${id}`, 404);
+	const agents = stores.session.getByRun(id);
+	// Sort agents ASC by (startedAt, id)
+	const sortedAgents = [...agents].sort((a, b) => {
+		if (a.startedAt !== b.startedAt) return a.startedAt < b.startedAt ? -1 : 1;
+		return a.id < b.id ? -1 : 1;
+	});
+	return apiJson({ ...run, agents: sortedAgents });
+}
+
+async function handleGetAgents(
+	_req: Request,
+	_match: RegExpMatchArray,
+	params: URLSearchParams,
+	stores: Stores,
+): Promise<Response> {
+	const { limit, cursor } = parseLimitAndCursor(params);
+	const runId = params.get("run");
+
+	const all = runId !== null ? stores.session.getByRun(runId) : stores.session.getAll();
+	// Sort ASC by (startedAt, id)
+	const sorted = [...all].sort((a, b) => {
+		if (a.startedAt !== b.startedAt) return a.startedAt < b.startedAt ? -1 : 1;
+		return a.id < b.id ? -1 : 1;
+	});
+	const { page, nextCursor } = paginateItems(sorted, cursor, limit, (a) => a.startedAt, "asc");
+	return apiJson(page, { nextCursor });
+}
+
+async function handleGetAgent(
+	_req: Request,
+	match: RegExpMatchArray,
+	_params: URLSearchParams,
+	stores: Stores,
+): Promise<Response> {
+	const name = match[1];
+	if (name === undefined) return apiError("Agent name required", 400);
+	const agent = stores.session.getByName(decodeURIComponent(name));
+	if (agent === null) return apiError(`Agent not found: ${name}`, 404);
+	return apiJson(agent);
+}
+
+async function handleGetEvents(
+	_req: Request,
+	_match: RegExpMatchArray,
+	params: URLSearchParams,
+	stores: Stores,
+): Promise<Response> {
+	const { limit, cursor } = parseLimitAndCursor(params);
+	const agentFilter = params.get("agent");
+	const runFilter = params.get("run");
+	const sinceParam = params.get("since");
+
+	// Validate sinceParam as an ISO date if provided
+	if (sinceParam !== null && Number.isNaN(Date.parse(sinceParam))) {
+		throw new ValidationError(`Invalid since timestamp: ${sinceParam}`, {
+			field: "since",
+			value: sinceParam,
+		});
+	}
+
+	// Effective since: cursor.ts > explicit since > default epoch
+	const effectiveSince = cursor !== null ? cursor.ts : (sinceParam ?? "1970-01-01T00:00:00.000Z");
+
+	// Over-fetch by 1 to detect next page
+	const fetchOpts = { since: effectiveSince, limit: limit + 1 };
+
+	let rawItems =
+		agentFilter !== null
+			? stores.event.getByAgent(agentFilter, fetchOpts)
+			: runFilter !== null
+				? stores.event.getByRun(runFilter, fetchOpts)
+				: stores.event.getTimeline(fetchOpts);
+
+	// Drop entries <= cursor.id (ties at cursor.ts)
+	if (cursor !== null) {
+		const cursorIdNum = Number.parseInt(cursor.id, 10);
+		rawItems = rawItems.filter((e) => e.id > cursorIdNum);
+	}
+
+	const page = rawItems.slice(0, limit);
+	const hasMore = rawItems.length > limit;
+	const lastItem = page[page.length - 1];
+	const nextCursor =
+		hasMore && lastItem !== undefined
+			? encodeCursor({ ts: lastItem.createdAt, id: String(lastItem.id) })
+			: null;
+
+	return apiJson(page, { nextCursor });
+}
+
+async function handleGetMetrics(
+	_req: Request,
+	_match: RegExpMatchArray,
+	params: URLSearchParams,
+	stores: Stores,
+): Promise<Response> {
+	const limitStr = params.get("limit");
+	const limit = limitStr !== null ? Number.parseInt(limitStr, 10) : 10;
+	if (Number.isNaN(limit) || limit < 1 || limit > 500) {
+		throw new ValidationError(`Invalid limit: ${limitStr ?? "undefined"}`, {
+			field: "limit",
+			value: limitStr,
+		});
+	}
+	const summary = generateSummary(stores.metrics, limit);
+	return apiJson(summary);
+}
+
+async function handleGetErrors(
+	_req: Request,
+	_match: RegExpMatchArray,
+	params: URLSearchParams,
+	stores: Stores,
+): Promise<Response> {
+	const limitStr = params.get("limit");
+	const limit = limitStr !== null ? Number.parseInt(limitStr, 10) : 100;
+	if (Number.isNaN(limit) || limit < 1 || limit > 500) {
+		throw new ValidationError(`Invalid limit: ${limitStr ?? "undefined"}`, {
+			field: "limit",
+			value: limitStr,
+		});
+	}
+	const agentFilter = params.get("agent");
+	const runFilter = params.get("run");
+	const sinceParam = params.get("since");
+	if (sinceParam !== null && Number.isNaN(Date.parse(sinceParam))) {
+		throw new ValidationError(`Invalid since timestamp: ${sinceParam}`, {
+			field: "since",
+			value: sinceParam,
+		});
+	}
+
+	// getErrors has no agent/run filter, so over-fetch and post-filter. When a
+	// filter is active, widen the window so the client-side cut still fills a page.
+	const hasFilter = agentFilter !== null || runFilter !== null;
+	const errors = stores.event.getErrors({
+		...(sinceParam !== null ? { since: sinceParam } : {}),
+		limit: hasFilter ? Math.min(limit * 10, 500) : limit,
+	});
+	const filtered = errors.filter((e) => {
+		if (agentFilter !== null && e.agentName !== agentFilter) return false;
+		if (runFilter !== null && e.runId !== runFilter) return false;
+		return true;
+	});
+	return apiJson(filtered.slice(0, limit));
+}
+
+async function handleGetMail(
+	_req: Request,
+	_match: RegExpMatchArray,
+	params: URLSearchParams,
+	stores: Stores,
+): Promise<Response> {
+	const { limit, cursor } = parseLimitAndCursor(params);
+	const toFilter = params.get("to") ?? undefined;
+	const fromFilter = params.get("from") ?? undefined;
+	const unreadParam = params.get("unread");
+	const unreadFilter = unreadParam !== null ? unreadParam === "true" : undefined;
+
+	// Fetch a large window when cursor is present for client-side pagination
+	const fetchLimit = cursor !== null ? limit * 5 : undefined;
+	const all = stores.mail.getAll({
+		to: toFilter,
+		from: fromFilter,
+		unread: unreadFilter,
+		limit: fetchLimit,
+	});
+
+	// Already sorted DESC by createdAt from the store; sort explicitly for stability
+	const sorted = [...all].sort((a, b) => {
+		if (b.createdAt !== a.createdAt) return b.createdAt < a.createdAt ? -1 : 1;
+		return b.id < a.id ? -1 : 1;
+	});
+
+	const { page, nextCursor } = paginateItems(sorted, cursor, limit, (m) => m.createdAt, "desc");
+	return apiJson(page, { nextCursor });
+}
+
+async function handleGetMailMessage(
+	_req: Request,
+	match: RegExpMatchArray,
+	_params: URLSearchParams,
+	stores: Stores,
+): Promise<Response> {
+	const id = match[1];
+	if (id === undefined) return apiError("Message ID required", 400);
+	const message = stores.mail.getById(id);
+	if (message === null) return apiError(`Message not found: ${id}`, 404);
+	const thread = message.threadId !== null ? stores.mail.getByThread(message.threadId) : [message];
+	return apiJson({ message, thread });
+}
+
+async function handleMarkMailRead(
+	_req: Request,
+	match: RegExpMatchArray,
+	_params: URLSearchParams,
+	stores: Stores,
+): Promise<Response> {
+	const id = match[1];
+	if (id === undefined) return apiError("Message ID required", 400);
+	const message = stores.mail.getById(id);
+	if (message === null) return apiError(`Message not found: ${id}`, 404);
+	stores.mail.markRead(id);
+	return apiJson({ id, read: true });
+}
+
+async function handleSendMail(
+	req: Request,
+	_match: RegExpMatchArray,
+	_params: URLSearchParams,
+	stores: Stores,
+): Promise<Response> {
+	const body = await parseJsonBody(req);
+	const result = sendMail({ mail: stores.mail, session: stores.session }, body);
+	return apiJson(result);
+}
+
+async function handleReplyMail(
+	req: Request,
+	match: RegExpMatchArray,
+	_params: URLSearchParams,
+	stores: Stores,
+): Promise<Response> {
+	const id = match[1];
+	if (id === undefined) return apiError("Message ID required", 400);
+	if (stores.mail.getById(id) === null) {
+		return apiError(`Message not found: ${id}`, 404);
+	}
+	const body = await parseJsonBody(req);
+	const result = replyMail({ mail: stores.mail, session: stores.session }, id, body);
+	return apiJson(result);
+}
+
+async function handleDeleteMail(
+	_req: Request,
+	match: RegExpMatchArray,
+	_params: URLSearchParams,
+	stores: Stores,
+): Promise<Response> {
+	const id = match[1];
+	if (id === undefined) return apiError("Message ID required", 400);
+	const result = deleteMail({ mail: stores.mail, session: stores.session }, id);
+	if (result === null) return apiError(`Message not found: ${id}`, 404);
+	return apiJson(result);
+}
+
+// ─── Coordinator handlers ─────────────────────────────────────────────────────
+
+async function handleCoordinatorState(
+	_req: Request,
+	_match: RegExpMatchArray,
+	_params: URLSearchParams,
+	_stores: Stores,
+	ctx: HandlerContext,
+): Promise<Response> {
+	const state = ctx.coordinatorActions.getCoordinatorState(ctx.coordinatorActionDeps);
+	return apiJson(state);
+}
+
+async function handleCoordinatorSend(
+	req: Request,
+	_match: RegExpMatchArray,
+	_params: URLSearchParams,
+	_stores: Stores,
+	ctx: HandlerContext,
+): Promise<Response> {
+	const { subject, body, from } = await readJsonBody(req, (raw) => {
+		const obj = asObject(raw, "Body must be a JSON object");
+		return {
+			subject: requireString(obj, "subject"),
+			body: requireString(obj, "body"),
+			from: optionalString(obj, "from"),
+		};
+	});
+	const result = await ctx.coordinatorActions.sendToCoordinator(
+		ctx.coordinatorActionDeps,
+		body,
+		from !== undefined ? { subject, from } : { subject },
+	);
+	return apiJson(result);
+}
+
+async function handleCoordinatorAsk(
+	req: Request,
+	_match: RegExpMatchArray,
+	_params: URLSearchParams,
+	_stores: Stores,
+	ctx: HandlerContext,
+): Promise<Response> {
+	const { subject, body, from, timeoutSec } = await readJsonBody(req, (raw) => {
+		const obj = asObject(raw, "Body must be a JSON object");
+		return {
+			subject: requireString(obj, "subject"),
+			body: requireString(obj, "body"),
+			from: optionalString(obj, "from"),
+			timeoutSec: optionalTimeoutSec(obj),
+		};
+	});
+	const result = await ctx.coordinatorActions.askCoordinatorAction(
+		ctx.coordinatorActionDeps,
+		body,
+		from !== undefined ? { subject, from, timeoutSec } : { subject, timeoutSec },
+	);
+	return apiJson(result);
+}
+
+async function handleCoordinatorCheckComplete(
+	_req: Request,
+	_match: RegExpMatchArray,
+	_params: URLSearchParams,
+	_stores: Stores,
+	ctx: HandlerContext,
+): Promise<Response> {
+	const result = await ctx.coordinatorActions.checkCoordinatorComplete(ctx.coordinatorActionDeps);
+	return apiJson(result);
+}
+
+async function handleCoordinatorStart(
+	_req: Request,
+	_match: RegExpMatchArray,
+	_params: URLSearchParams,
+	_stores: Stores,
+	ctx: HandlerContext,
+): Promise<Response> {
+	const result = await ctx.coordinatorActions.startCoordinatorHeadless(ctx.coordinatorActionDeps);
+	return apiJson(result);
+}
+
+async function handleCoordinatorStop(
+	_req: Request,
+	_match: RegExpMatchArray,
+	_params: URLSearchParams,
+	_stores: Stores,
+	ctx: HandlerContext,
+): Promise<Response> {
+	const result = await ctx.coordinatorActions.stopCoordinator(ctx.coordinatorActionDeps);
+	return apiJson(result);
+}
+
+// ─── Fleet-control handlers (sling / stop / merge) ────────────────────────────
+
+async function handleSlingAgent(
+	req: Request,
+	_match: RegExpMatchArray,
+	_params: URLSearchParams,
+	_stores: Stores,
+	ctx: HandlerContext,
+): Promise<Response> {
+	const { taskId, capability, name, files, spec, runtime, skipTaskCheck } = await readJsonBody(
+		req,
+		(raw) => {
+			const obj = asObject(raw, "Body must be a JSON object");
+			return {
+				taskId: requireString(obj, "taskId"),
+				capability: optionalString(obj, "capability"),
+				name: optionalString(obj, "name"),
+				files: optionalString(obj, "files"),
+				spec: optionalString(obj, "spec"),
+				runtime: optionalString(obj, "runtime"),
+				skipTaskCheck: obj.skipTaskCheck === true,
+			};
+		},
+	);
+	const result = await ctx.agentActions.slingAgent(ctx.agentActionDeps, {
+		taskId,
+		...(capability !== undefined ? { capability } : {}),
+		...(name !== undefined ? { name } : {}),
+		...(files !== undefined ? { files } : {}),
+		...(spec !== undefined ? { spec } : {}),
+		...(runtime !== undefined ? { runtime } : {}),
+		skipTaskCheck,
+	});
+	return apiJson(result);
+}
+
+async function handleStopAgent(
+	req: Request,
+	match: RegExpMatchArray,
+	_params: URLSearchParams,
+	_stores: Stores,
+	ctx: HandlerContext,
+): Promise<Response> {
+	const name = match[1];
+	if (name === undefined) return apiError("Agent name required", 400);
+	// Body is optional; default cleanWorktree=false when absent/empty.
+	let cleanWorktree = false;
+	const text = await req.text();
+	if (text.trim().length > 0) {
+		try {
+			const parsed = JSON.parse(text) as Record<string, unknown>;
+			cleanWorktree = parsed.cleanWorktree === true;
+		} catch {
+			throw new ValidationError("Invalid JSON body", { field: "body" });
+		}
+	}
+	const result = await ctx.agentActions.stopAgent(ctx.agentActionDeps, decodeURIComponent(name), {
+		cleanWorktree,
+	});
+	return apiJson(result);
+}
+
+async function handleMergePreview(
+	_req: Request,
+	_match: RegExpMatchArray,
+	params: URLSearchParams,
+	_stores: Stores,
+	ctx: HandlerContext,
+): Promise<Response> {
+	const branch = params.get("branch");
+	if (branch === null || branch.length === 0) {
+		throw new ValidationError("Missing required query parameter 'branch'", { field: "branch" });
+	}
+	const into = params.get("into");
+	const result = await ctx.agentActions.mergePreview(ctx.agentActionDeps, {
+		branch,
+		...(into !== null ? { into } : {}),
+	});
+	return apiJson(result);
+}
+
+async function handleMergeRun(
+	req: Request,
+	_match: RegExpMatchArray,
+	_params: URLSearchParams,
+	_stores: Stores,
+	ctx: HandlerContext,
+): Promise<Response> {
+	const body = await parseJsonBody(req);
+	const branch = optionalString(body, "branch");
+	const into = optionalString(body, "into");
+	const all = body.all === true;
+	const result = await ctx.agentActions.mergeRun(ctx.agentActionDeps, {
+		...(branch !== undefined ? { branch } : {}),
+		...(into !== undefined ? { into } : {}),
+		all,
+	});
+	return apiJson(result);
+}
+
+// ─── Infrastructure handlers (queue / worktrees / logs / doctor / groups / specs) ─
+
+const MERGE_STATUSES: ReadonlySet<string> = new Set([
+	"pending",
+	"merging",
+	"merged",
+	"conflict",
+	"failed",
+]);
+
+async function handleGetMergeQueue(
+	_req: Request,
+	_match: RegExpMatchArray,
+	params: URLSearchParams,
+	_stores: Stores,
+	ctx: HandlerContext,
+): Promise<Response> {
+	const statusParam = params.get("status");
+	if (statusParam !== null && !MERGE_STATUSES.has(statusParam)) {
+		throw new ValidationError(`Invalid status: ${statusParam}`, {
+			field: "status",
+			value: statusParam,
+		});
+	}
+	const queuePath = join(ctx.projectRoot, ".agentplate", "merge-queue.db");
+	if (!existsSync(queuePath)) return apiJson([]);
+	const queue = createMergeQueue(queuePath);
+	try {
+		const entries = queue.list(
+			statusParam !== null ? (statusParam as MergeEntry["status"]) : undefined,
+		);
+		return apiJson(entries);
+	} finally {
+		queue.close();
+	}
+}
+
+async function handleGetWorktrees(
+	_req: Request,
+	_match: RegExpMatchArray,
+	_params: URLSearchParams,
+	_stores: Stores,
+	ctx: HandlerContext,
+): Promise<Response> {
+	const worktrees = await listWorktrees(ctx.projectRoot);
+	return apiJson(worktrees);
+}
+
+async function handleGetLogs(
+	_req: Request,
+	_match: RegExpMatchArray,
+	params: URLSearchParams,
+	_stores: Stores,
+	ctx: HandlerContext,
+): Promise<Response> {
+	const limitStr = params.get("limit");
+	const limit = limitStr !== null ? Number.parseInt(limitStr, 10) : 200;
+	if (Number.isNaN(limit) || limit < 1 || limit > 2000) {
+		throw new ValidationError(`Invalid limit: ${limitStr ?? "undefined"}`, {
+			field: "limit",
+			value: limitStr,
+		});
+	}
+	const level = params.get("level") ?? undefined;
+	if (level !== undefined && !["debug", "info", "warn", "error"].includes(level)) {
+		throw new ValidationError(`Invalid level: ${level}`, { field: "level", value: level });
+	}
+	const agent = params.get("agent") ?? undefined;
+	const sinceParam = params.get("since");
+	if (sinceParam !== null && Number.isNaN(Date.parse(sinceParam))) {
+		throw new ValidationError(`Invalid since timestamp: ${sinceParam}`, {
+			field: "since",
+			value: sinceParam,
+		});
+	}
+
+	const logsDir = join(ctx.projectRoot, ".agentplate", "logs");
+	if (!existsSync(logsDir)) return apiJson([]);
+
+	const files = await discoverLogFiles(logsDir, agent);
+	const events = [];
+	for (const file of files) {
+		events.push(...(await parseLogFile(file.path)));
+	}
+	const filtered = filterEvents(events, {
+		...(level !== undefined ? { level } : {}),
+		...(sinceParam !== null ? { since: new Date(sinceParam) } : {}),
+	});
+	// Most-recent first, capped at limit.
+	filtered.sort((a, b) => (a.timestamp < b.timestamp ? 1 : a.timestamp > b.timestamp ? -1 : 0));
+	return apiJson(filtered.slice(0, limit));
+}
+
+const DOCTOR_CATEGORIES: ReadonlySet<string> = new Set([
+	"dependencies",
+	"structure",
+	"config",
+	"databases",
+	"consistency",
+	"agents",
+	"merge",
+	"logs",
+	"version",
+	"ecosystem",
+	"providers",
+	"watchdog",
+	"serve",
+]);
+
+async function handleGetDoctor(
+	_req: Request,
+	_match: RegExpMatchArray,
+	params: URLSearchParams,
+	_stores: Stores,
+	ctx: HandlerContext,
+): Promise<Response> {
+	const category = params.get("category");
+	if (category !== null && !DOCTOR_CATEGORIES.has(category)) {
+		throw new ValidationError(`Invalid category: ${category}`, {
+			field: "category",
+			value: category,
+		});
+	}
+	// Lazy import: `../doctor.ts` transitively imports `../commands/serve.ts`
+	// (via the serve doctor check), which would form a module-init cycle with
+	// serve.ts ↔ rest.ts and trip a TDZ on `_apiHandlers`. Importing on demand
+	// keeps doctor out of the static graph.
+	const { collectDoctorChecks } = await import("../doctor.ts");
+	const checks = await collectDoctorChecks(
+		ctx.projectRoot,
+		category !== null ? (category as DoctorCategory) : undefined,
+	);
+	const summary = {
+		pass: checks.filter((c) => c.status === "pass").length,
+		warn: checks.filter((c) => c.status === "warn").length,
+		fail: checks.filter((c) => c.status === "fail").length,
+	};
+	return apiJson({ checks, summary });
+}
+
+async function handleGetGroups(
+	_req: Request,
+	_match: RegExpMatchArray,
+	_params: URLSearchParams,
+	_stores: Stores,
+	ctx: HandlerContext,
+): Promise<Response> {
+	const groups = await loadGroups(ctx.projectRoot);
+	return apiJson(groups);
+}
+
+async function handleGetSpecs(
+	_req: Request,
+	_match: RegExpMatchArray,
+	_params: URLSearchParams,
+	_stores: Stores,
+	ctx: HandlerContext,
+): Promise<Response> {
+	const specsDir = join(ctx.projectRoot, ".agentplate", "specs");
+	if (!existsSync(specsDir)) return apiJson([]);
+	const entries = await readdir(specsDir);
+	const specs = [];
+	for (const file of entries) {
+		if (!file.endsWith(".md")) continue;
+		const info = await stat(join(specsDir, file));
+		specs.push({
+			taskId: file.replace(/\.md$/, ""),
+			sizeBytes: info.size,
+			modifiedAt: info.mtime.toISOString(),
+		});
+	}
+	specs.sort((a, b) => (a.modifiedAt < b.modifiedAt ? 1 : -1));
+	return apiJson(specs);
+}
+
+async function handleGetSpec(
+	_req: Request,
+	match: RegExpMatchArray,
+	_params: URLSearchParams,
+	_stores: Stores,
+	ctx: HandlerContext,
+): Promise<Response> {
+	const taskId = match[1];
+	if (taskId === undefined) return apiError("Task ID required", 400);
+	const decoded = decodeURIComponent(taskId);
+	// Guard against path traversal — task IDs are flat slugs.
+	if (decoded.includes("/") || decoded.includes("..")) {
+		return apiError("Invalid task ID", 400);
+	}
+	const specPath = join(ctx.projectRoot, ".agentplate", "specs", `${decoded}.md`);
+	if (!existsSync(specPath)) return apiError(`Spec not found: ${decoded}`, 404);
+	const content = await readFile(specPath, "utf-8");
+	return apiJson({ taskId: decoded, content });
+}
+
+// ─── Route table ─────────────────────────────────────────────────────────────
+
+const ROUTES: Route[] = [
+	{ method: "GET", pattern: /^\/api\/runs$/, handler: handleGetRuns },
+	{ method: "GET", pattern: /^\/api\/runs\/([^/]+)$/, handler: handleGetRun },
+	{ method: "GET", pattern: /^\/api\/agents$/, handler: handleGetAgents },
+	{ method: "POST", pattern: /^\/api\/agents\/sling$/, handler: handleSlingAgent },
+	{ method: "POST", pattern: /^\/api\/agents\/([^/]+)\/stop$/, handler: handleStopAgent },
+	{ method: "GET", pattern: /^\/api\/agents\/([^/]+)$/, handler: handleGetAgent },
+	{ method: "GET", pattern: /^\/api\/merge\/preview$/, handler: handleMergePreview },
+	{ method: "GET", pattern: /^\/api\/merge\/queue$/, handler: handleGetMergeQueue },
+	{ method: "POST", pattern: /^\/api\/merge$/, handler: handleMergeRun },
+	{ method: "GET", pattern: /^\/api\/worktrees$/, handler: handleGetWorktrees },
+	{ method: "GET", pattern: /^\/api\/logs$/, handler: handleGetLogs },
+	{ method: "GET", pattern: /^\/api\/doctor$/, handler: handleGetDoctor },
+	{ method: "GET", pattern: /^\/api\/groups$/, handler: handleGetGroups },
+	{ method: "GET", pattern: /^\/api\/specs$/, handler: handleGetSpecs },
+	{ method: "GET", pattern: /^\/api\/specs\/([^/]+)$/, handler: handleGetSpec },
+	{ method: "GET", pattern: /^\/api\/events$/, handler: handleGetEvents },
+	{ method: "GET", pattern: /^\/api\/metrics$/, handler: handleGetMetrics },
+	{ method: "GET", pattern: /^\/api\/errors$/, handler: handleGetErrors },
+	{ method: "GET", pattern: /^\/api\/mail$/, handler: handleGetMail },
+	{ method: "POST", pattern: /^\/api\/mail$/, handler: handleSendMail },
+	{ method: "GET", pattern: /^\/api\/mail\/([^/]+)$/, handler: handleGetMailMessage },
+	{ method: "DELETE", pattern: /^\/api\/mail\/([^/]+)$/, handler: handleDeleteMail },
+	{ method: "POST", pattern: /^\/api\/mail\/([^/]+)\/read$/, handler: handleMarkMailRead },
+	{ method: "POST", pattern: /^\/api\/mail\/([^/]+)\/reply$/, handler: handleReplyMail },
+	{ method: "GET", pattern: /^\/api\/coordinator\/state$/, handler: handleCoordinatorState },
+	{ method: "POST", pattern: /^\/api\/coordinator\/send$/, handler: handleCoordinatorSend },
+	{ method: "POST", pattern: /^\/api\/coordinator\/ask$/, handler: handleCoordinatorAsk },
+	{
+		method: "POST",
+		pattern: /^\/api\/coordinator\/check-complete$/,
+		handler: handleCoordinatorCheckComplete,
+	},
+	{ method: "POST", pattern: /^\/api\/coordinator\/start$/, handler: handleCoordinatorStart },
+	{ method: "POST", pattern: /^\/api\/coordinator\/stop$/, handler: handleCoordinatorStop },
+];
+
+// ─── Public registration ──────────────────────────────────────────────────────
+
+/**
+ * Register all REST API handlers with the serve scaffold.
+ * Deps allows injecting stores for testing; in production, stores are opened
+ * from projectRoot/.agentplate/{sessions,events,mail}.db.
+ */
+export function registerRestApi(deps?: RestApiDeps): void {
+	let stores: Stores | null = null;
+	const projectRoot = deps?._projectRoot ?? process.cwd();
+
+	function getStores(): Stores {
+		if (stores !== null) return stores;
+
+		if (
+			deps?._runStore !== undefined &&
+			deps._sessionStore !== undefined &&
+			deps._eventStore !== undefined &&
+			deps._mailStore !== undefined
+		) {
+			stores = {
+				run: deps._runStore,
+				session: deps._sessionStore,
+				event: deps._eventStore,
+				mail: deps._mailStore,
+				// Metrics is optional in DI — tests that don't exercise /api/metrics
+				// get an in-memory store so the field stays non-null.
+				metrics: deps._metricsStore ?? createMetricsStore(":memory:"),
+			};
+		} else {
+			stores = openStores(projectRoot);
+		}
+		return stores;
+	}
+
+	const overrides = deps?._coordinatorActions ?? {};
+	const coordinatorActions = {
+		getCoordinatorState: overrides.getCoordinatorState ?? getCoordinatorState,
+		sendToCoordinator: overrides.sendToCoordinator ?? sendToCoordinator,
+		askCoordinatorAction: overrides.askCoordinatorAction ?? askCoordinatorAction,
+		checkCoordinatorComplete: overrides.checkCoordinatorComplete ?? checkCoordinatorComplete,
+		startCoordinatorHeadless: overrides.startCoordinatorHeadless ?? startCoordinatorHeadless,
+		stopCoordinator: overrides.stopCoordinator ?? stopCoordinator,
+	};
+	const coordinatorActionDeps: CoordinatorActionDeps = {
+		projectRoot,
+		...(deps?._coordinatorActionDeps ?? {}),
+	};
+
+	const agentOverrides = deps?._agentActions ?? {};
+	const agentActions = {
+		slingAgent: agentOverrides.slingAgent ?? slingAgent,
+		stopAgent: agentOverrides.stopAgent ?? stopAgent,
+		mergePreview: agentOverrides.mergePreview ?? mergePreview,
+		mergeRun: agentOverrides.mergeRun ?? mergeRun,
+	};
+	const agentActionDeps: AgentActionDeps = {
+		projectRoot,
+		...(deps?._agentActionDeps ?? {}),
+	};
+
+	registerApiHandler((req: Request): Response | Promise<Response> | null => {
+		const url = new URL(req.url);
+		const path = url.pathname;
+
+		// Two passes: first try to match path+method exactly. If none matches
+		// but the path matched some route, return 405 (method not allowed).
+		let matchedRoute: { route: Route; match: RegExpMatchArray } | null = null;
+		let pathMatched = false;
+		for (const route of ROUTES) {
+			const match = path.match(route.pattern);
+			if (match === null) continue;
+			pathMatched = true;
+			if (req.method === route.method) {
+				matchedRoute = { route, match };
+				break;
+			}
+		}
+
+		if (matchedRoute !== null) {
+			const { route, match } = matchedRoute;
+			return (async (): Promise<Response> => {
+				try {
+					const ctx: HandlerContext = {
+						projectRoot,
+						coordinatorActions,
+						coordinatorActionDeps,
+						agentActions,
+						agentActionDeps,
+					};
+					return await route.handler(req, match, url.searchParams, getStores(), ctx);
+				} catch (err) {
+					if (err instanceof AgentplateError) {
+						return apiError(err.message, statusFromError(err));
+					}
+					process.stderr.write(`REST handler error: ${String(err)}\n`);
+					return apiError("Internal server error", 500);
+				}
+			})();
+		}
+
+		if (pathMatched) {
+			return apiError("Method not allowed", 405);
+		}
+
+		return null;
+	});
+}