pi-mega-compact 0.8.21 → 0.8.23

package/extensions/dashboard-server/server.ts

@@ -1,5 +1,10 @@
 /**
  * dashboard-server/server.ts — HTTP server creation + launch + CLI entry point.
+ *
+ * Route handlers are extracted to routes.ts. This file owns:
+ * - launchDashboardServer (setup, version detection, port finding, IPv6 mirror, lifecycle)
+ * - createServer as a thin dispatcher that builds RouteContext and delegates each route
+ * - CORS preflight + OPTIONS handling (per-request middleware, not a route)
  */
 
 import {
@@ -12,7 +17,6 @@ import {
 	mkdirSync,
 	readFileSync,
 	unlinkSync,
-	watch,
 	writeFileSync,
 } from "node:fs";
 import { join, dirname } from "node:path";
@@ -20,12 +24,18 @@ import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 
 import { log, setLogPath, setDashboardServerVersion } from "./state.js";
-import { readIndex, getIndexDir } from "./index-reader.js";
-import { readSnapshot, readFrom } from "./snapshot.js";
-import { dashboardHtml } from "./html.js";
-import { ACTIVE_WINDOW_SEC } from "./types.js";
-import type { IndexIndex, Snapshot, LiveSnapshot } from "./types.js";
-import type { GameMetric } from "../../src/game/scoring.js";
+import {
+	buildRouteContext,
+	handleIndex,
+	handleRepoIndex,
+	handleEvents,
+	handleGameState,
+	handleGameScores,
+	handlePerf,
+	handleAchievements,
+	handleSessions,
+	handleStatic,
+} from "./routes.js";
 
 export async function launchDashboardServer(
 	stateDir: string,
@@ -170,45 +180,15 @@ export async function launchDashboardServer(
 	// ── New server ────────────────────────────────────────────────────────────
 	mkdirSync(stateDir, { recursive: true });
 
-	let eventOffset = 0;
-
-	// Overlay the live current-repo snapshot (snapshot.json, rewritten every
-	// context event) onto its registry row so the All-repos / Summary views stay
-	// in sync with the live menu bar + Current-repo card in real time. The
-	// registry (index.sqlite) is only written on repo-switch (bindRepo), so
-	// without this the current repo's row freezes between switches. Read-only —
-	// no extra writes to index.sqlite. Matched by stateDir, which equals the
-	// value this server was launched with (runtime.currentStateDir).
-	function overlayCurrentRepo(idx: IndexIndex | null): void {
-		if (!idx || !idx.repos.length) return;
-		let snap: Snapshot | null = null;
-		try {
-			snap = readSnapshot(snapshotPath);
-		} catch {
-			return;
-		}
-		if (!snap || !snap.repo) return;
-		const cur = idx.repos.find((r) => r.stateDir === stateDir);
-		if (!cur) return;
-		const prevSaved = cur.tokensSaved;
-		const prevCp = cur.checkpointCount;
-		const prevBytes = cur.compressedOriginalBytes;
-		const comp = snap.compression?.repo;
-		const liveSaved = comp
-			? comp.tokensFreed
-			: (snap.repo.tokensSaved ?? prevSaved);
-		const liveCp = snap.repo.checkpointCount ?? prevCp;
-		const liveBytes = snap.integrity?.compressedOriginalBytes ?? prevBytes;
-		cur.tokensSaved = liveSaved;
-		cur.checkpointCount = liveCp;
-		cur.compressedOriginalBytes = liveBytes;
-		if (idx.summary) {
-			idx.summary.totalTokensSaved += liveSaved - prevSaved;
-			idx.summary.totalCheckpoints += liveCp - prevCp;
-			idx.summary.totalCompressedOriginalBytes += liveBytes - prevBytes;
-		}
-		idx.updatedAt = snap.updatedAt ?? idx.updatedAt;
-	}
+	// Build RouteContext once; all handlers receive the same ctx object.
+	const ctx = buildRouteContext({
+		snapshotPath,
+		eventsPath,
+		stateDir,
+		SERVER_VERSION,
+		serveClientAsset,
+		detectCrossRepoDrift,
+	});
 
 	const server = createServer((req: IncomingMessage, res: ServerResponse) => {
 		// guardrails-allow PREVENT-PI-004: optional, user-triggered /dashboard localhost server (loopback-only) — CORS restricted to same-origin localhost browsers.
@@ -230,659 +210,16 @@ export async function launchDashboardServer(
 			return;
 		}
 
-		if (req.url === "/" || req.url === "/index.html") {
-			// Sprint B1: prefer the React client build when present; fall back to the
-			// legacy inline html.ts template when the client dist is absent.
-			if (serveClientAsset("/", res)) return;
-			const tier = readSnapshot(snapshotPath).tier;
-			res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
-			res.end(dashboardHtml(tier));
-			return;
-		}
-
-		if (req.url === "/api/snapshot") {
-			const snap = readSnapshot(snapshotPath);
-			res.writeHead(200, { "Content-Type": "application/json" });
-			res.end(JSON.stringify(snap));
-			return;
-		}
-
-		// Server version — lets the /dashboard launcher detect a stale server from
-		// an older build and replace it on upgrade rather than reuse it.
-		if (req.url === "/api/version") {
-			res.writeHead(200, { "Content-Type": "application/json" });
-			res.end(JSON.stringify({ version: SERVER_VERSION }));
-			return;
-		}
-
-		// Multi-repo aggregate (Phase 5b): the machine-wide repo registry read
-		// directly from SQLite (index.sqlite). Lets one dashboard show every repo's
-		// checkpoints, tokens saved, and active model. Read-only.
-		if (req.url === "/api/index") {
-			const idx = readIndex();
-			if (idx) overlayCurrentRepo(idx);
-			res.writeHead(200, { "Content-Type": "application/json" });
-			res.end(
-				JSON.stringify(idx ?? { updatedAt: null, summary: null, repos: [] }),
-			);
-			return;
-		}
-
-		// /api/repos — registry list. Optional `?active=24h` filters to repos
-		// seen within the last N hours (default: all). The dashboard uses this to
-		// drive its "active vs archived" badge without refetching /api/index.
-		if (req.url?.startsWith("/api/repos")) {
-			const url = new URL(req.url, "http://x"); // guardrails-allow PREVENT-PI-004: localhost dashboard URL base (loopback-only)
-			const activeParam = url.searchParams.get("active");
-			const idx = readIndex();
-			if (idx) overlayCurrentRepo(idx);
-			let repos = idx?.repos ?? [];
-			if (activeParam) {
-				const m = /^(\d+)h$/.exec(activeParam);
-				if (m) {
-					const cutoffSec = Math.floor(Date.now() / 1000) - Number(m[1]) * 3600;
-					repos = repos.filter((r) => (r.lastSeen ?? 0) >= cutoffSec);
-				}
-			}
-			res.writeHead(200, { "Content-Type": "application/json" });
-			res.end(
-				JSON.stringify({
-					updatedAt: idx?.updatedAt ?? null,
-					repos,
-					count: repos.length,
-				}),
-			);
-			return;
-		}
-
-		// /api/summary — header tiles without the full repo list (keeps payload
-		// small for embed scenarios). activeRepos mirrors the /api/repos?active=24h
-		// count so the dashboard can render the active badge alongside totals.
-		if (req.url?.startsWith("/api/summary")) {
-			const idx = readIndex();
-			if (idx) overlayCurrentRepo(idx);
-			const repos = idx?.repos ?? [];
-			const cutoffSec = Math.floor(Date.now() / 1000) - 24 * 3600;
-			const activeRepos = repos.filter(
-				(r) => (r.lastSeen ?? 0) >= cutoffSec,
-			).length;
-			res.writeHead(200, { "Content-Type": "application/json" });
-			res.end(
-				JSON.stringify({
-					updatedAt: idx?.updatedAt ?? null,
-					summary: idx?.summary ?? null,
-					activeRepos,
-					totalRepos: repos.length,
-				}),
-			);
-			return;
-		}
-
-		// /api/drift — R4: cross-repo drift report over repo_registry. Flags stale
-		// repos (>30d idle), compaction lag (active but >24h since last
-		// compaction), and recent model churn. Read-only.
-		if (req.url?.startsWith("/api/drift")) {
-			const report = detectCrossRepoDrift(getIndexDir());
-			res.writeHead(200, { "Content-Type": "application/json" });
-			res.end(JSON.stringify(report));
-			return;
-		}
-
-		if (req.url === "/api/servers") {
-			try {
-				const idx = readIndex();
-				const nowSec = Math.floor(Date.now() / 1000);
-				const servers = (idx?.repos ?? [])
-					.filter((r) => (r.lastSeen ?? 0) >= nowSec - ACTIVE_WINDOW_SEC)
-					.map((r) => {
-						const out: Record<string, unknown> = {
-							repoRoot: r.repoRoot,
-							displayName: r.displayName,
-							model: r.modelName,
-							provider: r.providerName,
-							lastSeen: r.lastSeen,
-							lastCompactedAt: r.lastCompactedAt,
-						};
-						try {
-							const p = join(r.stateDir, "dashboard.json");
-							if (existsSync(p)) {
-								const snap = JSON.parse(
-									readFileSync(p, "utf-8"),
-								) as LiveSnapshot;
-								out.tier = snap.tier ?? null;
-								out.contextPct =
-									snap.context && snap.context.percent != null
-										? snap.context.percent
-										: null;
-								out.state = (snap.session && snap.session.state) || null;
-								out.cacheHits = snap.cacheHits ?? null;
-								out.compacts = snap.compacts ?? null;
-								out.timeSaved = snap.timeSaved ?? null;
-								out.updatedAt = snap.updatedAt ?? null;
-							}
-						} catch {
-							/* best-effort */
-						}
-						return out;
-					})
-					.sort((a, b) => (b.lastSeen as number) - (a.lastSeen as number));
-				res.writeHead(200, { "Content-Type": "application/json" });
-				res.end(
-					JSON.stringify({ updatedAt: new Date().toISOString(), servers }),
-				);
-			} catch {
-				res.writeHead(500, { "Content-Type": "application/json" });
-				res.end(JSON.stringify({ error: "servers_unavailable" }));
-			}
-			return;
-		}
-
-		if (req.url === "/api/events") {
-			res.writeHead(200, {
-				"Content-Type": "text/event-stream",
-				"Cache-Control": "no-cache",
-				Connection: "keep-alive",
-			});
-
-			// Drain existing events so the client starts with history
-			const { data: existing, offset: initialOffset } = readFrom(eventsPath, 0);
-			eventOffset = initialOffset;
-			const lines = existing.split("\n").filter((l: string) => l.trim());
-			for (const line of lines) {
-				res.write(`data: ${line}\n\n`);
-			}
-
-			// Tail new events via fs.watch (coalesced with 100ms debounce)
-			let watchTimer: ReturnType<typeof setTimeout> | null = null;
-			const onWatch = () => {
-				if (watchTimer) return;
-				watchTimer = setTimeout(() => {
-					watchTimer = null;
-					const { data, offset } = readFrom(eventsPath, eventOffset);
-					eventOffset = offset;
-					const newLines = data.split("\n").filter((l: string) => l.trim());
-					for (const line of newLines) {
-						res.write(`data: ${line}\n\n`);
-					}
-				}, 100);
-			};
-
-			// Set up file watching: if file exists, watch it directly;
-			// otherwise poll for creation every 1s then switch to fs.watch.
-			let watcher: ReturnType<typeof watch> | null = null;
-			let pollInterval: ReturnType<typeof setInterval> | null = null;
-
-			function startFileWatch(): void {
-				try {
-					watcher = watch(eventsPath, onWatch);
-				} catch {
-					/* give up */
-				}
-			}
-
-			if (existsSync(eventsPath)) {
-				startFileWatch();
-			} else {
-				pollInterval = setInterval(() => {
-					if (existsSync(eventsPath)) {
-						if (pollInterval) {
-							clearInterval(pollInterval);
-							pollInterval = null;
-						}
-						startFileWatch();
-					}
-				}, 1000);
-			}
-
-			req.on("close", () => {
-				if (watchTimer) clearTimeout(watchTimer);
-				if (pollInterval) clearInterval(pollInterval);
-				watcher?.close();
-			});
-			return;
-		}
-
-		// /api/game-state — S32 game-mode settings (game_mode_on / theme /
-		// tui_display_mode). GET returns the current row; PUT applies a partial
-		// patch (validated) and returns the post-write row. The dashboard server is
-		// a detached child with no MegaRuntime ref, so it reads/writes the
-		// game_state SQLite row directly; the in-process MegaRuntime picks up the
-		// change via its fs.watch cache-eviction watcher. PREVENT-PI-004: loopback.
-		if (req.url?.startsWith("/api/game-state")) {
-			const gsReq = createRequire(import.meta.url);
-			const { getGameState, setGameState } = gsReq(
-				"../../src/store/sqlite.js",
-			) as typeof import("../../src/store/sqlite.js");
-			const { isValidTheme } = gsReq(
-				"../../src/config/themes.js",
-			) as typeof import("../../src/config/themes.js");
-			if (req.method === "GET") {
-				try {
-					const gs = getGameState(stateDir); // guardrails-allow PREVENT-PI-004: local SQLite read (loopback dashboard)
-					res.writeHead(200, { "Content-Type": "application/json" });
-					res.end(JSON.stringify(gs));
-				} catch (e) {
-					res.writeHead(500, { "Content-Type": "application/json" });
-					res.end(
-						JSON.stringify({
-							error: "game_state_unavailable",
-							detail: String(e),
-						}),
-					);
-				}
-				return;
-			}
-			if (req.method === "PUT") {
-				// Read + parse the JSON body (capped — the patch is tiny). The handler
-				// is sync, so drain the stream via data/end listeners then continue.
-				let body = "";
-				let tooBig = false;
-				req.on("data", (chunk: Buffer) => {
-					// guardrails-allow PREVENT-PI-004: loopback dashboard request body (local)
-					if (body.length > 65536) {
-						tooBig = true;
-						return;
-					}
-					body += chunk.toString();
-				});
-				req.on("end", () => {
-					if (tooBig) {
-						res.writeHead(413, { "Content-Type": "application/json" });
-						res.end(JSON.stringify({ error: "body_too_large" }));
-						return;
-					}
-					let patch: Record<string, unknown> = {};
-					try {
-						patch = body ? JSON.parse(body) : {};
-					} catch {
-						res.writeHead(400, { "Content-Type": "application/json" });
-						res.end(JSON.stringify({ error: "invalid_json" }));
-						return;
-					}
-					// Reject valid-but-non-object JSON (null/[]/42) — dereferencing
-					// patch.game_mode_on would throw an unhandled TypeError inside this
-					// 'end' listener and crash the detached server (audit P1: loopback DoS).
-					if (
-						typeof patch !== "object" ||
-						patch === null ||
-						Array.isArray(patch)
-					) {
-						res.writeHead(400, { "Content-Type": "application/json" });
-						res.end(JSON.stringify({ error: "invalid_patch_object" }));
-						return;
-					}
-					// Validate the patch fields (unknown keys ignored; invalid values -> 400).
-					const clean: {
-						game_mode_on?: boolean;
-						theme?: string;
-						tui_display_mode?: "full" | "minimal";
-					} = {};
-					let bad = false;
-					if (patch.game_mode_on != null) {
-						if (typeof patch.game_mode_on !== "boolean") bad = true;
-						else clean.game_mode_on = patch.game_mode_on;
-					}
-					if (patch.theme != null) {
-						if (typeof patch.theme !== "string" || !isValidTheme(patch.theme))
-							bad = true;
-						else clean.theme = patch.theme;
-					}
-					if (patch.tui_display_mode != null) {
-						if (
-							patch.tui_display_mode !== "full" &&
-							patch.tui_display_mode !== "minimal"
-						)
-							bad = true;
-						else clean.tui_display_mode = patch.tui_display_mode;
-					}
-					if (bad) {
-						res.writeHead(400, { "Content-Type": "application/json" });
-						res.end(JSON.stringify({ error: "invalid_patch" }));
-						return;
-					}
-					try {
-						const gs = setGameState(clean, stateDir); // guardrails-allow PREVENT-PI-004: local SQLite write (loopback dashboard)
-						res.writeHead(200, { "Content-Type": "application/json" });
-						res.end(JSON.stringify(gs));
-					} catch (e) {
-						res.writeHead(500, { "Content-Type": "application/json" });
-						res.end(
-							JSON.stringify({
-								error: "game_state_write_failed",
-								detail: String(e),
-							}),
-						);
-					}
-				});
-				return;
-			}
-			// Any other method on /api/game-state → 405.
-			res.writeHead(405, { "Content-Type": "application/json" }); // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
-			res.end(JSON.stringify({ error: "method_not_allowed" }));
-			return;
-		}
-
-		// /api/game-scores — S34 high-score leaderboards. GET returns the leaderboard
-		// for a metric (?metric=<m>&limit=<n>). `metric` is validated against the
-		// METRICS allow-list from src/game/scoring (re-exported via the sqlite barrel);
-		// default limit 10, clamped to [1,100]. The dashboard server is a detached
-		// child with no MegaRuntime ref, so it reads the game_scores SQLite table
-		// directly. Unknown metric -> 400, non-GET -> 405. PREVENT-PI-004: loopback.
-		if (req.url?.startsWith("/api/game-scores")) {
-			const gsReq = createRequire(import.meta.url);
-			const { leaderboard, METRICS } = gsReq(
-				"../../src/store/sqlite.js",
-			) as typeof import("../../src/store/sqlite.js");
-			if (req.method !== "GET") {
-				res.writeHead(405, { "Content-Type": "application/json" }); // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
-				res.end(JSON.stringify({ error: "method_not_allowed" }));
-				return;
-			}
-			try {
-				const url = new URL(req.url, "http://x"); // guardrails-allow PREVENT-PI-004: localhost dashboard URL base (loopback-only)
-				const metricParam = url.searchParams.get("metric") ?? "cache";
-				if (!(METRICS as readonly string[]).includes(metricParam)) {
-					res.writeHead(400, { "Content-Type": "application/json" }); // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
-					res.end(
-						JSON.stringify({ error: "unknown_metric", metric: metricParam }),
-					);
-					return;
-				}
-				const metric = metricParam as GameMetric; // validated against METRICS above
-				let limit = Number(url.searchParams.get("limit") ?? "10");
-				if (!Number.isFinite(limit) || limit <= 0) limit = 10;
-				limit = Math.min(Math.max(limit, 1), 100); // clamp to [1,100]
-				const rows = leaderboard(stateDir, metric, { limit }); // guardrails-allow PREVENT-PI-004: local SQLite read (loopback dashboard)
-				res.writeHead(200, { "Content-Type": "application/json" });
-				res.end(JSON.stringify(rows));
-			} catch (e) {
-				res.writeHead(500, { "Content-Type": "application/json" });
-				res.end(
-					JSON.stringify({
-						error: "game_scores_unavailable",
-						detail: String(e),
-					}),
-				);
-			}
-			return;
-		}
-
-		// /api/perf — v0.8.8 Perf dashboard tab. GET returns rolling-window
-		// aggregates over perf_samples: per-kind p50/p95 (turn/provider latency,
-		// tps avg, db recompute, disk write), latest rss/heap, cpu user/sys delta,
-		// cache hit %, plus the diag recompute/skip/replay counts (read from
-		// dashboard.json snapshot if available). The dashboard server is a detached
-		// child with no MegaRuntime ref, so it reads perf_samples via a require()'d
-		// sqlite helper (same pattern as /api/game-scores). Unknown/invalid params
-		// are clamped (never throw). Non-GET -> 405. PREVENT-PI-004: loopback.
-		if (req.url?.startsWith("/api/perf")) {
-			const pfReq = createRequire(import.meta.url);
-			const { readPerfSamples } = pfReq(
-				"../../src/store/sqlite.js",
-			) as typeof import("../../src/store/sqlite.js");
-			if (req.method !== "GET") {
-				res.writeHead(405, { "Content-Type": "application/json" }); // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
-				res.end(JSON.stringify({ error: "method_not_allowed" }));
-				return;
-			}
-			try {
-				const url = new URL(req.url, "http://x"); // guardrails-allow PREVENT-PI-004: localhost dashboard URL base (loopback-only)
-				let minutes = Number(url.searchParams.get("minutes") ?? "30");
-				if (!Number.isFinite(minutes) || minutes <= 0) minutes = 30;
-				minutes = Math.min(minutes, 1440); // cap at 24h
-				const sinceTs = Date.now() - minutes * 60_000;
-				const rows = readPerfSamples(stateDir, sinceTs); // guardrails-allow PREVENT-PI-004: local SQLite read (loopback dashboard)
-				const byKind = new Map<string, number[]>();
-				for (const r of rows) {
-					let arr = byKind.get(r.kind);
-					if (!arr) {
-						arr = [];
-						byKind.set(r.kind, arr);
-					}
-					arr.push(r.value);
-				}
-				// Nearest-rank percentile (ceil(p/100*n)-1, clamped). Code-controlled,
-				// never user input (PREVENT-002 safe).
-				function pct(arr: number[], p: number): number {
-					if (!arr.length) return 0;
-					const s = [...arr].sort((a, b) => a - b);
-					const idx = Math.min(
-						s.length - 1,
-						Math.max(0, Math.ceil((p / 100) * s.length) - 1),
-					);
-					return s[idx];
-				}
-				function avg(arr: number[]): number {
-					if (!arr.length) return 0;
-					return arr.reduce((a, b) => a + b, 0) / arr.length;
-				}
-				// rows are ASC by ts, so the last pushed value is the most recent.
-				function latest(arr: number[]): number {
-					return arr.length ? arr[arr.length - 1] : 0;
-				}
-				const get = (k: string): number[] => byKind.get(k) ?? [];
-				// diag counters live in the runtime-written dashboard.json (the server is
-				// a detached child with no MegaRuntime ref). Read defensively — absent
-				// until the first snapshot() write (PREVENT-001: assign before access).
-				let diag: {
-					ctxFastGate: number;
-					liveTrimFires: number;
-					liveTrimReplays: number;
-				} | null = null;
-				try {
-					const raw = readFileSync(snapshotPath, "utf-8");
-					const parsed = JSON.parse(raw) as {
-						diag?: {
-							ctxFastGate: number;
-							liveTrimFires: number;
-							liveTrimReplays: number;
-						};
-					};
-					if (parsed && typeof parsed === "object" && parsed.diag)
-						diag = parsed.diag;
-				} catch {
-					/* dashboard.json not written yet */
-				}
-				res.writeHead(200, { "Content-Type": "application/json" });
-				res.end(
-					JSON.stringify({
-						updatedAt: new Date().toISOString(),
-						windowMinutes: minutes,
-						sampleCount: rows.length,
-						turn_latency_ms: {
-							p50: pct(get("turn_latency_ms"), 50),
-							p95: pct(get("turn_latency_ms"), 95),
-							n: get("turn_latency_ms").length,
-						},
-						provider_latency_ms: {
-							p50: pct(get("provider_latency_ms"), 50),
-							p95: pct(get("provider_latency_ms"), 95),
-							n: get("provider_latency_ms").length,
-						},
-						tps: { avg: avg(get("tps")), n: get("tps").length },
-						cache_hit_pct: {
-							avg: avg(get("cache_hit_pct")),
-							latest: latest(get("cache_hit_pct")),
-							n: get("cache_hit_pct").length,
-						},
-						db_recompute_ms: {
-							p50: pct(get("db_recompute_ms"), 50),
-							p95: pct(get("db_recompute_ms"), 95),
-							n: get("db_recompute_ms").length,
-						},
-						disk_write_ms: {
-							p50: pct(get("disk_write_ms"), 50),
-							p95: pct(get("disk_write_ms"), 95),
-							n: get("disk_write_ms").length,
-						},
-						rss_mb: { latest: latest(get("rss_mb")), n: get("rss_mb").length },
-						heap_mb: {
-							latest: latest(get("heap_mb")),
-							n: get("heap_mb").length,
-						},
-						cpu_user_ms: {
-							latest: latest(get("cpu_user_ms")),
-							n: get("cpu_user_ms").length,
-						},
-						cpu_sys_ms: {
-							latest: latest(get("cpu_sys_ms")),
-							n: get("cpu_sys_ms").length,
-						},
-						diag,
-					}),
-				);
-			} catch (e) {
-				res.writeHead(500, { "Content-Type": "application/json" });
-				res.end(
-					JSON.stringify({ error: "perf_unavailable", detail: String(e) }),
-				);
-			}
-			return;
-		}
-
-		// /api/achievements — S35 achievement tiles. GET returns the 9 seeded rows
-		// {id,title,description,icon,hidden,unlocked_at}. The dashboard server is a
-		// detached child with no MegaRuntime ref, so it reads game_achievements via
-		// listAchievements(stateDir) directly. Non-GET -> 405. PREVENT-PI-004: loopback.
-		if (req.url?.startsWith("/api/achievements")) {
-			const achReq = createRequire(import.meta.url);
-			const { listAchievements } = achReq(
-				"../../src/store/sqlite.js",
-			) as typeof import("../../src/store/sqlite.js");
-			if (req.method !== "GET") {
-				res.writeHead(405, { "Content-Type": "application/json" }); // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
-				res.end(JSON.stringify({ error: "method_not_allowed" }));
-				return;
-			}
-			try {
-				const rows = listAchievements(stateDir); // guardrails-allow PREVENT-PI-004: local SQLite read (loopback dashboard)
-				res.writeHead(200, { "Content-Type": "application/json" });
-				res.end(JSON.stringify(rows));
-			} catch (e) {
-				res.writeHead(500, { "Content-Type": "application/json" });
-				res.end(
-					JSON.stringify({
-						error: "achievements_unavailable",
-						detail: String(e),
-					}),
-				);
-			}
-			return;
-		}
-
-		// /api/sessions — S39: active pi sessions with latest token usage + heartbeat.
-		// GET returns {updatedAt, pruned, sessions[]} after pruning stale heartbeats.
-		// The dashboard server is a detached child with no MegaRuntime ref, so it
-		// reads session_heartbeats via a require()'d sqlite helper (same pattern as
-		// /api/achievements, /api/perf). Non-GET -> 405. PREVENT-PI-004: loopback.
-		if (req.url?.startsWith("/api/sessions")) {
-			// Guard: /api/sessions/timeseries handled separately below.
-			if (req.url.startsWith("/api/sessions/timeseries")) {
-				// Fall through to the timeseries handler below.
-			} else {
-				const sReq = createRequire(import.meta.url);
-				const {
-					readActiveSessions,
-					pruneStaleSessions,
-					listRepoRegistry,
-				} = sReq(
-						"../../src/store/sqlite.js",
-					) as typeof import("../../src/store/sqlite.js");
-				if (req.method !== "GET") {
-					res.writeHead(405, { "Content-Type": "application/json" }); // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
-					res.end(JSON.stringify({ error: "method_not_allowed" }));
-					return;
-				}
-				try {
-					const pruned = pruneStaleSessions(); // guardrails-allow PREVENT-PI-004: local SQLite read (loopback dashboard)
-					const active = readActiveSessions();
-					const repos = listRepoRegistry();
-					const repoMap = new Map(repos.map((r) => [r.repoRoot, r]));
-					const sessions = active.map((s) => ({
-						pid: s.pid,
-						sessionId: s.sessionId,
-						repoRoot: s.repoRoot,
-						displayName: s.repoRoot
-							? (s.repoRoot.split(/[\\/]/).filter(Boolean).pop() ?? s.repoRoot)
-							: (s.stateDir?.split(/[\\/]/).filter(Boolean).pop() ?? "unknown"),
-						model: s.repoRoot ? (repoMap.get(s.repoRoot)?.modelName ?? null) : null,
-						tokens: s.tokens,
-						percent: s.percent,
-						ctxWindow: s.ctxWindow,
-						lastSeen: s.lastSeen,
-						stateDir: s.stateDir,
-					}));
-					res.writeHead(200, { "Content-Type": "application/json" });
-					res.end(
-						JSON.stringify({ updatedAt: new Date().toISOString(), pruned, sessions }),
-					);
-				} catch (e) {
-					res.writeHead(500, { "Content-Type": "application/json" });
-					res.end(
-						JSON.stringify({ error: "sessions_unavailable", detail: String(e) }),
-					);
-				}
-				return;
-			}
-		}
-
-		// /api/sessions/timeseries — S39: stacked per-session token timeseries for
-		// the recharts memory graph. GET ?minutes=N (clamped [1,1440]) returns
-		// {updatedAt, windowMinutes, series[], totals[]} in recharts-ready shape.
-		// Non-GET -> 405. PREVENT-PI-004: loopback.
-		if (req.url?.startsWith("/api/sessions/timeseries")) {
-			const tsReq = createRequire(import.meta.url);
-			const {
-				readSessionTimeseries,
-				pruneTokenSamples,
-			} = tsReq(
-					"../../src/store/sqlite.js",
-				) as typeof import("../../src/store/sqlite.js");
-			if (req.method !== "GET") {
-				res.writeHead(405, { "Content-Type": "application/json" }); // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
-				res.end(JSON.stringify({ error: "method_not_allowed" }));
-				return;
-			}
-			try {
-				const url = new URL(req.url, "http://x"); // guardrails-allow PREVENT-PI-004: localhost dashboard URL base (loopback-only)
-				let minutes = Number(url.searchParams.get("minutes") ?? "30");
-				if (!Number.isFinite(minutes) || minutes <= 0) minutes = 30;
-				minutes = Math.min(Math.max(minutes, 1), 1440);
-				const sinceTs = Date.now() - minutes * 60_000;
-				const pruneMs = Math.max(minutes * 60_000, 1_800_000);
-				pruneTokenSamples(pruneMs); // guardrails-allow PREVENT-PI-004: local SQLite read (loopback dashboard)
-				const result = readSessionTimeseries(sinceTs); // guardrails-allow PREVENT-PI-004: local SQLite read (loopback dashboard)
-				res.writeHead(200, { "Content-Type": "application/json" });
-				res.end(
-					JSON.stringify({
-						updatedAt: new Date().toISOString(),
-						windowMinutes: minutes,
-						series: result.series,
-						totals: result.totals,
-					}),
-				);
-			} catch (e) {
-				res.writeHead(500, { "Content-Type": "application/json" });
-				res.end(
-					JSON.stringify({ error: "timeseries_unavailable", detail: String(e) }),
-				);
-			}
-			return;
-		}
-
-		// Fallback — serve the React client build (SPA route) or legacy dashboard.
-		// Non-/api/* GETs hit here: serve client assets if built, else inline HTML.
-		if (
-			req.method === "GET" &&
-			req.url &&
-			!req.url.startsWith("/api/") &&
-			serveClientAsset(req.url, res)
-		) {
-			return;
-		}
-		const tier = readSnapshot(snapshotPath).tier;
-		res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
-		res.end(dashboardHtml(tier));
+		// Dispatch — each handler returns true if it ended the response.
+		if (handleIndex(req, res, ctx)) return;
+		if (handleRepoIndex(req, res, ctx)) return;
+		if (handleEvents(req, res, ctx)) return;
+		if (handleGameState(req, res, ctx)) return;
+		if (handleGameScores(req, res, ctx)) return;
+		if (handlePerf(req, res, ctx)) return;
+		if (handleAchievements(req, res, ctx)) return;
+		if (handleSessions(req, res, ctx)) return;
+		handleStatic(req, res, ctx);
 	});
 
 	// Bind base + range are env-configurable so tests can use a private,
@@ -983,4 +320,4 @@ if (process.argv[1] && process.argv[1].includes("dashboard-server")) {
 		console.error("[mega-compact] dashboard server failed:", err);
 		process.exit(1);
 	});
-}
+}