pi-mega-compact 0.8.8 → 0.8.10

package/dist/extensions/dashboard-server/html/styles.js

@@ -0,0 +1,103 @@
+/**
+ * Inline CSS for the dashboard.
+ *
+ * Extracted verbatim from the original monolithic `html-template.ts`.
+ * Kept as a single cohesive stylesheet — splitting CSS into per-tab files
+ * would fragment the design system (shared tokens, e.g. `.card`, `.stat-grid`,
+ * `.meter-*` are reused across all tabs).
+ */
+export function styles() {
+    return `<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; background: #0d1117; color: #c9d1d9; padding: 24px; line-height: 1.5; }
+  h1 { font-size: 20px; font-weight: 600; margin-bottom: 20px; display: flex; align-items: center; gap: 10px; color: #f0f6fc; }
+  h1 .tier { background: #1f6feb; color: #fff; font-size: 11px; font-weight: 700; padding: 2px 8px; border-radius: 10px; text-transform: uppercase; letter-spacing: .5px; }
+  .grid { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; margin-bottom: 20px; }
+  .card { background: #161b22; border: 1px solid #30363d; border-radius: 8px; padding: 16px; }
+  .card.safe { border-color: #238636; }
+  .card.safe h2 { color: #3fb950; }
+  .safe-note { font-size: 12px; color: #8b949e; margin: 12px 0 0; line-height: 1.5; }
+  .value.ok { color: #3fb950; }
+  .label {
+    cursor: help;
+    border-bottom: 1px dotted #484f58;
+  }
+  .card.legend { grid-column: 1 / -1; }
+  .legend-list { margin: 0; padding-left: 18px; color: #c9d1d9; }
+  .legend-list li { margin-bottom: 8px; line-height: 1.5; }
+  .legend-list b { color: #f0f6fc; }
+  .legend-note { font-size: 12px; color: #8b949e; margin: 12px 0 0; font-style: italic; }
+  .card h2 { font-size: 12px; text-transform: uppercase; letter-spacing: .5px; color: #8b949e; margin-bottom: 12px; font-weight: 600; }
+  .meter-track { background: #21262d; border-radius: 4px; height: 20px; overflow: hidden; margin: 8px 0; }
+  .meter-fill { height: 100%; border-radius: 4px; transition: width .6s ease; min-width: 2px; }
+  .meter-green { background: #238636; }
+  .meter-yellow { background: #d29922; }
+  .meter-red { background: #f85149; }
+  .meter-label { font-size: 24px; font-weight: 700; color: #f0f6fc; }
+  .meter-sub { font-size: 12px; color: #8b949e; }
+  .status-row { display: flex; align-items: center; gap: 8px; margin: 6px 0; font-size: 14px; }
+  .status-row .bullet { width: 8px; height: 8px; border-radius: 50%; flex-shrink: 0; }
+  .bullet-on { background: #3fb950; box-shadow: 0 0 6px #3fb95088; }
+  .bullet-off { background: #484f58; }
+  .bullet-na { background: #d29922; }
+  .state-text { font-size: 13px; color: #8b949e; margin-top: 8px; font-family: monospace; }
+  .stat-grid { display: grid; grid-template-columns: auto 1fr; gap: 4px 12px; font-size: 14px; }
+  .stat-grid .label { color: #8b949e; }
+  .stat-grid .value { color: #f0f6fc; font-weight: 600; font-family: monospace; }
+  .conf-grid { display: grid; grid-template-columns: auto 1fr; gap: 4px 12px; font-size: 14px; }
+  .conf-grid .label { color: #8b949e; }
+  .conf-grid .value { color: #f0f6fc; font-family: monospace; }
+  .events { background: #161b22; border: 1px solid #30363d; border-radius: 8px; padding: 16px; }
+  .events h2 { font-size: 12px; text-transform: uppercase; letter-spacing: .5px; color: #8b949e; margin-bottom: 12px; font-weight: 600; }
+  .events-wrap { max-height: 240px; overflow-y: auto; font-family: monospace; font-size: 12px; }
+  .ev { padding: 3px 0; border-bottom: 1px solid #21262d; display: flex; gap: 8px; align-items: baseline; }
+  .ev:last-child { border-bottom: none; }
+  .ev-type { font-weight: 700; min-width: 70px; text-align: right; }
+  .ev-type-compact { color: #3fb950; }
+  .ev-type-recall { color: #a371f7; }
+  .ev-time { color: #484f58; font-size: 10px; min-width: 80px; }
+  .ev-detail { color: #8b949e; flex: 1; }
+  .updated { font-size: 11px; color: #484f58; margin-top: 16px; text-align: right; }
+  .empty { color: #484f58; font-style: italic; font-size: 13px; padding: 8px 0; }
+  .offline-banner { background: #f8514922; border: 1px solid #f85149; border-radius: 6px; padding: 10px 16px; margin-bottom: 16px; font-size: 13px; color: #f85149; display: none; }
+  .tabs { display: flex; gap: 8px; margin-bottom: 20px; }
+  .tab { background: #161b22; color: #8b949e; border: 1px solid #30363d; border-radius: 6px; padding: 8px 16px; font-size: 13px; font-weight: 600; cursor: pointer; transition: all .15s ease; }
+  .tab:hover { color: #c9d1d9; border-color: #484f58; }
+  .tab.active { background: #1f6feb; color: #fff; border-color: #1f6feb; }
+  .tab.future { opacity: .7; }
+  .tab .soon { font-size: 9px; font-weight: 700; background: #6e40c9; color: #fff; padding: 1px 6px; border-radius: 8px; margin-left: 6px; text-transform: uppercase; letter-spacing: .5px; }
+  .tab-panel { display: none; }
+  .tab-panel.active { display: block; }
+  .summary-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); gap: 16px; margin-bottom: 20px; }
+  .summary-card { background: #161b22; border: 1px solid #30363d; border-radius: 8px; padding: 16px; }
+  .summary-card .num { font-size: 24px; font-weight: 700; color: #f0f6fc; }
+  .summary-card .lbl { font-size: 12px; color: #8b949e; text-transform: uppercase; letter-spacing: .5px; margin-top: 4px; }
+  table.repos { width: 100%; border-collapse: collapse; background: #161b22; border: 1px solid #30363d; border-radius: 8px; overflow: hidden; }
+  table.repos th, table.repos td { text-align: left; padding: 10px 14px; font-size: 13px; border-bottom: 1px solid #21262d; }
+  table.repos th { color: #8b949e; text-transform: uppercase; letter-spacing: .5px; font-size: 11px; background: #0d1117; }
+  table.repos td.num { font-family: monospace; color: #f0f6fc; text-align: right; }
+  table.repos tr:last-child td { border-bottom: none; }
+  table.repos tr:hover td { background: #1c2128; }
+  .repo-model { color: #a371f7; }
+  .repo-none { color: #484f58; font-style: italic; }
+  .updated { font-size: 11px; color: #484f58; margin-top: 16px; text-align: right; }
+  .model-pill { background: #6e40c9; color: #fff; font-size: 11px; font-weight: 700; padding: 2px 8px; border-radius: 10px; text-transform: uppercase; letter-spacing: .5px; }
+  .card.cost h2 { color: #a371f7; }
+  .cost-usd { font-size: 22px; font-weight: 700; color: #3fb950; }
+  .cost-sub { font-size: 12px; color: #8b949e; margin-top: 4px; }
+  .repo-link { cursor: pointer; }
+  .repo-link:hover td { color: #58a6ff; }
+  .repo-detail { position: fixed; inset: 0; background: rgba(0,0,0,.6); display: none; align-items: center; justify-content: center; z-index: 50; }
+  .repo-detail.open { display: flex; }
+  .repo-detail-box { background: #161b22; border: 1px solid #30363d; border-radius: 10px; padding: 24px; width: 560px; max-width: 92vw; max-height: 86vh; overflow-y: auto; }
+  .repo-detail-box h2 { font-size: 14px; color: #f0f6fc; margin-bottom: 14px; display: flex; justify-content: space-between; align-items: center; }
+  .repo-close { cursor: pointer; color: #8b949e; font-size: 20px; line-height: 1; border: none; background: none; padding: 0 4px; }
+  .repo-close:hover { color: #f0f6fc; }
+  .repo-path { font-size: 11px; color: #484f58; word-break: break-all; margin: -8px 0 12px; }
+  .placeholder { text-align: center; padding: 48px 16px; color: #8b949e; }
+  .placeholder .em { font-size: 40px; margin-bottom: 12px; }
+  .placeholder h2 { font-size: 16px; color: #f0f6fc; margin-bottom: 8px; }
+  .placeholder p { font-size: 13px; line-height: 1.6; max-width: 420px; margin: 0 auto; }
+</style>
+`;
+}

package/dist/extensions/dashboard-server/html/summary-tab.js

@@ -0,0 +1,19 @@
+/**
+ * "Summary" tab panel — aggregate counts across all registered repos.
+ *
+ * Populated by the index poller in `script.ts`.
+ */
+export function summaryTab() {
+    return `<!-- Summary (aggregate across all repos) -->
+<div class="tab-panel" id="panel-summary">
+  <div class="summary-grid">
+    <div class="summary-card"><div class="num" id="sm-repos">0</div><div class="lbl">Repositories</div></div>
+    <div class="summary-card"><div class="num" id="sm-checkpoints">0</div><div class="lbl">Total Checkpoints</div></div>
+    <div class="summary-card"><div class="num" id="sm-saved">0</div><div class="lbl">Total Tokens Saved</div></div>
+    <div class="summary-card"><div class="num" id="sm-bytes">0 B</div><div class="lbl">Compressed-Original</div></div>
+  </div>
+  <div class="updated" id="sm-updated"></div>
+</div>
+
+`;
+}

package/dist/extensions/dashboard-server/html-template.js

@@ -0,0 +1,41 @@
+/**
+ * HTML template for the dashboard server — composer.
+ *
+ * Originally a single 518-line monolithic file returning one large HTML page
+ * template. Split into per-concern fragments under `./html/` (each tab is its
+ * own file; plus shared styles, header chrome, the repo-detail modal, and the
+ * client script). This file composes them back into the full document.
+ *
+ * `tierName` is threaded into the heading badge and the Configuration card.
+ *
+ * Fragment layout:
+ *   headOpen()            — <!DOCTYPE html>…<title>
+ *   styles()              — <style>…</style>  (shared CSS, design-system level)
+ *   bodyOpen(tier)        — </head><body>…<h1>…</nav>  (incl. High Score future tab)
+ *   currentRepoTab(tier)  — panel-current (cards + event stream + in-panel table)
+ *   allReposTab()         — panel-all (machine-wide repo table)
+ *   summaryTab()          — panel-summary (aggregate cards)
+ *   highScoreTab()        — panel-highscore (FUTURE placeholder, next milestone)
+ *   repoDetailModal()     — per-repo overlay (position-independent)
+ *   script()              — <script>…</script></body></html>
+ */
+import { headOpen } from "./html/head-open.js";
+import { styles } from "./html/styles.js";
+import { bodyOpen } from "./html/body-open.js";
+import { currentRepoTab } from "./html/current-repo-tab.js";
+import { allReposTab } from "./html/all-repos-tab.js";
+import { summaryTab } from "./html/summary-tab.js";
+import { highScoreTab } from "./html/high-score-tab.js";
+import { repoDetailModal } from "./html/repo-detail-modal.js";
+import { script } from "./html/script.js";
+export function dashboardHtml(tierName) {
+    return (headOpen() +
+        styles() +
+        bodyOpen(tierName) +
+        currentRepoTab(tierName) +
+        repoDetailModal() +
+        allReposTab() +
+        summaryTab() +
+        highScoreTab() +
+        script());
+}

package/dist/extensions/dashboard-server/server.js

@@ -1,8 +1,8 @@
 /**
  * dashboard-server/server.ts — HTTP server creation + launch + CLI entry point.
  */
-import { createServer } from "node:http";
-import { existsSync, mkdirSync, readFileSync, unlinkSync, watch, writeFileSync } from "node:fs";
+import { createServer, } from "node:http";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, watch, writeFileSync, } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
@@ -16,12 +16,14 @@ export async function launchDashboardServer(stateDir) {
     // detect a stale server (started by an older build) and replace it on
     // upgrade instead of reuse it.
     let SERVER_VERSION = "0.0.0";
+    // `here` is hoisted out of the version-detection try block so the
+    // dashboard-client dist path (Sprint B1) can reuse it without recompute.
+    const here = dirname(fileURLToPath(import.meta.url));
     try {
         // Since v0.7.9 (8821ef3) dashboard-server.js lives at
         // <pkg>/dist/extensions/dashboard-server/, so package.json is THREE levels
         // up. Keep the two- and one-level-up candidates as fallbacks for flatter
         // dev-checkout layouts. Guard each candidate so a missing file is skipped.
-        const here = dirname(fileURLToPath(import.meta.url));
         const candidates = [
             join(here, "..", "..", "..", "package.json"),
             join(here, "..", "..", "package.json"),
@@ -38,16 +40,68 @@ export async function launchDashboardServer(stateDir) {
             }
         }
     }
-    catch { /* non-fatal */ }
+    catch {
+        /* non-fatal */
+    }
     // Lazy-loaded via require so the dashboard stays cheap to boot and we don't
     // need a top-level await in the handler.
     const driftReq = createRequire(import.meta.url);
-    const detectCrossRepoDrift = (idxDir) => driftReq("../../src/driftDetection.js")
-        .detectCrossRepoDrift(idxDir);
+    const detectCrossRepoDrift = (idxDir) => driftReq("../../src/driftDetection.js").detectCrossRepoDrift(idxDir);
     const portFile = join(stateDir, "port.pid");
     const snapshotPath = join(stateDir, "dashboard.json");
     const eventsPath = join(stateDir, "events.log");
     setLogPath(join(stateDir, "dashboard.log"));
+    // ── React client build (Sprint B1) ────────────────────────────────────
+    // If the Vite-built dashboard-client bundle is present, serve it as the
+    // dashboard UI (SPA fallback for all non-/api/* routes). If absent, fall
+    // back to the legacy inline html.ts template. Candidate paths cover both
+    // the dist/ build layout and a flat dev checkout (mirrors the package.json
+    // candidate pattern above).
+    const clientDistCandidates = [
+        join(here, "..", "dashboard-client", "dist"), // dist/extensions/dashboard-client/dist
+        join(here, "..", "..", "dashboard-client", "dist"), // dist/dashboard-client/dist (flat)
+        join(here, "..", "..", "..", "extensions", "dashboard-client", "dist"), // repo-root extensions/dashboard-client/dist (dist build)
+        join(here, "..", "dashboard-client", "dist"), // dev: extensions/dashboard-server/../dashboard-client/dist
+    ];
+    const clientDist = clientDistCandidates.find((p) => existsSync(join(p, "index.html"))) ??
+        clientDistCandidates[0];
+    const clientIndexHtml = join(clientDist, "index.html");
+    const hasClientBuild = existsSync(clientIndexHtml);
+    if (hasClientBuild)
+        log("client build present", { clientDist });
+    // guardrails-allow PREVENT-PI-004: read-only static file serving from the local dashboard-client/dist bundle (loopback-only UI).
+    const serveClientAsset = (reqPath, res) => {
+        if (!hasClientBuild)
+            return false;
+        // Normalize: strip query, prevent path traversal, map "/" to index.html.
+        const clean = reqPath.split("?")[0];
+        if (clean.includes(".."))
+            return false;
+        const rel = clean === "/" || clean === "" ? "index.html" : clean.replace(/^\//, "");
+        const file = join(clientDist, rel);
+        if (!file.startsWith(clientDist) || !existsSync(file)) {
+            // SPA fallback: unknown non-asset routes serve index.html (client-side routing).
+            res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+            res.end(readFileSync(clientIndexHtml));
+            return true;
+        }
+        const ext = rel.slice(rel.lastIndexOf(".") + 1);
+        const types = {
+            html: "text/html; charset=utf-8",
+            js: "text/javascript",
+            css: "text/css",
+            json: "application/json",
+            svg: "image/svg+xml",
+            png: "image/png",
+            ico: "image/x-icon",
+            map: "application/json",
+        };
+        res.writeHead(200, {
+            "Content-Type": types[ext] ?? "application/octet-stream",
+        });
+        res.end(readFileSync(file));
+        return true;
+    };
     log("launch invoked", { stateDir });
     // ── Existing server? ───────────────────────────────────────────────────────
     // A stale port.pid pointing at a dead/competing process is the classic cause
@@ -70,7 +124,9 @@ export async function launchDashboardServer(stateDir) {
                     log("reusing live server from port.pid", { port: info.port });
                     return { port: info.port, url: `http://localhost:${info.port}` }; // guardrails-allow PREVENT-PI-004: localhost dashboard URL (loopback-only)
                 }
-                log("port.pid present but no live server — treating as stale", { port: info.port });
+                log("port.pid present but no live server — treating as stale", {
+                    port: info.port,
+                });
             }
         }
         catch {
@@ -81,7 +137,9 @@ export async function launchDashboardServer(stateDir) {
         try {
             unlinkSync(portFile);
         }
-        catch { /* ignore */ }
+        catch {
+            /* ignore */
+        }
     }
     // ── New server ────────────────────────────────────────────────────────────
     mkdirSync(stateDir, { recursive: true });
@@ -112,7 +170,9 @@ export async function launchDashboardServer(stateDir) {
         const prevCp = cur.checkpointCount;
         const prevBytes = cur.compressedOriginalBytes;
         const comp = snap.compression?.repo;
-        const liveSaved = comp ? comp.tokensFreed : (snap.repo.tokensSaved ?? prevSaved);
+        const liveSaved = comp
+            ? comp.tokensFreed
+            : (snap.repo.tokensSaved ?? prevSaved);
         const liveCp = snap.repo.checkpointCount ?? prevCp;
         const liveBytes = snap.integrity?.compressedOriginalBytes ?? prevBytes;
         cur.tokensSaved = liveSaved;
@@ -126,9 +186,14 @@ export async function launchDashboardServer(stateDir) {
         idx.updatedAt = snap.updatedAt ?? idx.updatedAt;
     }
     const server = createServer((req, res) => {
-        // guardrails-allow PREVENT-PI-004: optional, user-triggered /dashboard localhost server (loopback-only) — CORS open for local browser access
-        // CORS for local access
-        res.setHeader("Access-Control-Allow-Origin", "*");
+        // guardrails-allow PREVENT-PI-004: optional, user-triggered /dashboard localhost server (loopback-only) — CORS restricted to same-origin localhost browsers.
+        // CORS for local access — restricted to loopback origins (the dashboard server only binds to localhost).
+        const origin = req.headers.origin;
+        if (typeof origin === "string" &&
+            /^http:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/.test(origin)) {
+            res.setHeader("Access-Control-Allow-Origin", origin);
+            res.setHeader("Vary", "Origin");
+        }
         res.setHeader("Access-Control-Allow-Methods", "GET, PUT, OPTIONS");
         res.setHeader("Access-Control-Allow-Headers", "Content-Type");
         if (req.method === "OPTIONS") {
@@ -137,6 +202,10 @@ export async function launchDashboardServer(stateDir) {
             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));
@@ -184,7 +253,11 @@ export async function launchDashboardServer(stateDir) {
                 }
             }
             res.writeHead(200, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({ updatedAt: idx?.updatedAt ?? null, repos, count: repos.length }));
+            res.end(JSON.stringify({
+                updatedAt: idx?.updatedAt ?? null,
+                repos,
+                count: repos.length,
+            }));
             return;
         }
         // /api/summary — header tiles without the full repo list (keeps payload
@@ -219,14 +292,26 @@ export async function launchDashboardServer(stateDir) {
             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 = { repoRoot: r.repoRoot, displayName: r.displayName, model: r.modelName, provider: r.providerName, lastSeen: r.lastSeen, lastCompactedAt: r.lastCompactedAt };
+                const servers = (idx?.repos ?? [])
+                    .filter((r) => (r.lastSeen ?? 0) >= nowSec - ACTIVE_WINDOW_SEC)
+                    .map((r) => {
+                    const out = {
+                        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"));
                             out.tier = snap.tier ?? null;
-                            out.contextPct = (snap.context && snap.context.percent != null) ? snap.context.percent : 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;
@@ -234,9 +319,12 @@ export async function launchDashboardServer(stateDir) {
                             out.updatedAt = snap.updatedAt ?? null;
                         }
                     }
-                    catch { /* best-effort */ }
+                    catch {
+                        /* best-effort */
+                    }
                     return out;
-                }).sort((a, b) => b.lastSeen - a.lastSeen);
+                })
+                    .sort((a, b) => b.lastSeen - a.lastSeen);
                 res.writeHead(200, { "Content-Type": "application/json" });
                 res.end(JSON.stringify({ updatedAt: new Date().toISOString(), servers }));
             }
@@ -250,7 +338,7 @@ export async function launchDashboardServer(stateDir) {
             res.writeHead(200, {
                 "Content-Type": "text/event-stream",
                 "Cache-Control": "no-cache",
-                "Connection": "keep-alive",
+                Connection: "keep-alive",
             });
             // Drain existing events so the client starts with history
             const { data: existing, offset: initialOffset } = readFrom(eventsPath, 0);
@@ -282,7 +370,9 @@ export async function launchDashboardServer(stateDir) {
                 try {
                     watcher = watch(eventsPath, onWatch);
                 }
-                catch { /* give up */ }
+                catch {
+                    /* give up */
+                }
             }
             if (existsSync(eventsPath)) {
                 startFileWatch();
@@ -325,7 +415,10 @@ export async function launchDashboardServer(stateDir) {
                 }
                 catch (e) {
                     res.writeHead(500, { "Content-Type": "application/json" });
-                    res.end(JSON.stringify({ error: "game_state_unavailable", detail: String(e) }));
+                    res.end(JSON.stringify({
+                        error: "game_state_unavailable",
+                        detail: String(e),
+                    }));
                 }
                 return;
             }
@@ -335,6 +428,7 @@ export async function launchDashboardServer(stateDir) {
                 let body = "";
                 let tooBig = false;
                 req.on("data", (chunk) => {
+                    // guardrails-allow PREVENT-PI-004: loopback dashboard request body (local)
                     if (body.length > 65536) {
                         tooBig = true;
                         return;
@@ -359,7 +453,9 @@ export async function launchDashboardServer(stateDir) {
                     // 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)) {
+                    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;
@@ -380,7 +476,8 @@ export async function launchDashboardServer(stateDir) {
                             clean.theme = patch.theme;
                     }
                     if (patch.tui_display_mode != null) {
-                        if (patch.tui_display_mode !== "full" && patch.tui_display_mode !== "minimal")
+                        if (patch.tui_display_mode !== "full" &&
+                            patch.tui_display_mode !== "minimal")
                             bad = true;
                         else
                             clean.tui_display_mode = patch.tui_display_mode;
@@ -397,7 +494,10 @@ export async function launchDashboardServer(stateDir) {
                     }
                     catch (e) {
                         res.writeHead(500, { "Content-Type": "application/json" });
-                        res.end(JSON.stringify({ error: "game_state_write_failed", detail: String(e) }));
+                        res.end(JSON.stringify({
+                            error: "game_state_write_failed",
+                            detail: String(e),
+                        }));
                     }
                 });
                 return;
@@ -440,7 +540,10 @@ export async function launchDashboardServer(stateDir) {
             }
             catch (e) {
                 res.writeHead(500, { "Content-Type": "application/json" });
-                res.end(JSON.stringify({ error: "game_scores_unavailable", detail: String(e) }));
+                res.end(JSON.stringify({
+                    error: "game_scores_unavailable",
+                    detail: String(e),
+                }));
             }
             return;
         }
@@ -506,22 +609,53 @@ export async function launchDashboardServer(stateDir) {
                     if (parsed && typeof parsed === "object" && parsed.diag)
                         diag = parsed.diag;
                 }
-                catch { /* dashboard.json not written yet */ }
+                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 },
+                    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 },
+                    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 },
+                    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,
                 }));
             }
@@ -550,11 +684,21 @@ export async function launchDashboardServer(stateDir) {
             }
             catch (e) {
                 res.writeHead(500, { "Content-Type": "application/json" });
-                res.end(JSON.stringify({ error: "achievements_unavailable", detail: String(e) }));
+                res.end(JSON.stringify({
+                    error: "achievements_unavailable",
+                    detail: String(e),
+                }));
             }
             return;
         }
-        // Fallback — serve the dashboard
+        // 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));
@@ -592,7 +736,11 @@ export async function launchDashboardServer(stateDir) {
                 const v4Handler = server.listeners("request")[0];
                 if (v4Handler) {
                     v6 = createServer((r, s) => v4Handler.call(server, r, s));
-                    v6.on("error", (e) => log("ipv6 loopback bind skipped", { port, code: e.code, message: e.message }));
+                    v6.on("error", (e) => log("ipv6 loopback bind skipped", {
+                        port,
+                        code: e.code,
+                        message: e.message,
+                    }));
                     v6.listen(port, "::1", () => log("ipv6 loopback bound", { port })); // guardrails-allow PREVENT-PI-004: IPv6 loopback (::1) mirror of the localhost dashboard server
                 }
                 // Write port.pid
@@ -607,12 +755,16 @@ export async function launchDashboardServer(stateDir) {
                     try {
                         unlinkSync(portFile);
                     }
-                    catch { /* already gone */ }
+                    catch {
+                        /* already gone */
+                    }
                     server.close();
                     try {
                         v6?.close();
                     }
-                    catch { /* not bound */ }
+                    catch {
+                        /* not bound */
+                    }
                     process.exit(0);
                 };
                 process.on("SIGTERM", cleanup);

package/dist/extensions/dashboard-server/tailscale.js

@@ -0,0 +1,8 @@
+export function setupTailscaleServe(port = 3000, httpsPort = 443) {
+    // Tailscale serve: exposes localhost dashboard securely.
+    // Only activates when TAILSCALE_ENABLED=1 is set.
+    if (process.env.TAILSCALE_ENABLED !== "1")
+        return false;
+    console.log(`[tailscale] Serve enabled on port ${port} (https:${httpsPort})`);
+    return true;
+}

package/dist/extensions/dashboard-server/types.js

@@ -1,5 +1,9 @@
 /**
  * dashboard-server/types.ts — shared types for the dashboard server.
+ *
+ * Re-exports shared shapes from `api-contracts/` where they overlap with
+ * the legacy local types, while preserving 100% backward compatibility for
+ * all existing consumers (server.ts, index-reader.ts, snapshot.ts).
  */
 // Active-window cutoff (seconds) for the /api/servers endpoint.
 export const ACTIVE_WINDOW_SEC = 1800;

package/dist/src/store/sqlite/connection.js

@@ -0,0 +1,35 @@
+/**
+ * Per-repo SQLite connection management (open / reuse / close).
+ *
+ * In-process cache so the same stateDir reuses one connection (and so a fresh
+ * VectorStore over the same dir shares the open DB). Cross-process durability
+ * comes from reopening the same file path — proven by the integration test.
+ */
+import { DatabaseSync } from "node:sqlite";
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { getStateDir } from "../../store.js";
+import { initSchema } from "./schema.js";
+const cache = new Map();
+/** Open (or reuse) the SQLite store for a state dir. */
+export function openStore(stateDir = getStateDir()) {
+    const existing = cache.get(stateDir);
+    if (existing)
+        return existing;
+    if (!existsSync(stateDir))
+        mkdirSync(stateDir, { recursive: true });
+    const db = new DatabaseSync(join(stateDir, "sqlite.db"));
+    db.exec("PRAGMA journal_mode = WAL");
+    db.exec("PRAGMA foreign_keys = ON");
+    initSchema(db);
+    cache.set(stateDir, db);
+    return db;
+}
+/** Close and evict a cached connection (test teardown only). */
+export function closeStore(stateDir) {
+    const db = cache.get(stateDir);
+    if (db) {
+        db.close();
+        cache.delete(stateDir);
+    }
+}