pi-mega-compact 0.7.8 → 0.8.0

package/extensions/dashboard-server/server.ts

@@ -0,0 +1,505 @@
+/**
+ * dashboard-server/server.ts — HTTP server creation + launch + CLI entry point.
+ */
+
+import { createServer, type IncomingMessage, type ServerResponse } 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";
+
+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";
+
+export async function launchDashboardServer(stateDir: string): Promise<{ port: number; url: string }> {
+  // Our own package version — exposed at /api/version so the launcher can
+  // detect a stale server (started by an older build) and replace it on
+  // upgrade instead of reuse it.
+  let SERVER_VERSION = "0.0.0";
+  try {
+    // dashboard-server.js lives at <pkg>/dist/extensions/, so package.json is
+    // two levels up. Guard each candidate so a dev-checkout layout still works.
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [join(here, "..", "..", "package.json"), join(here, "..", "package.json")];
+    for (const p of candidates) {
+      if (!existsSync(p)) continue;
+      const pkg = JSON.parse(readFileSync(p, "utf-8"));
+      if (pkg.version) { SERVER_VERSION = pkg.version; setDashboardServerVersion(pkg.version); break; }
+    }
+  } 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: string) =>
+    (driftReq("../../src/driftDetection.js") as typeof import("../../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"));
+  log("launch invoked", { stateDir });
+
+  // ── Existing server? ───────────────────────────────────────────────────────
+  // A stale port.pid pointing at a dead/competing process is the classic cause
+  // of "dashboard failed to start" — we return a port that is NOT actually
+  // serving. Probe for a live server on that port first; only reuse the marker
+  // when something real answers /api/version. Otherwise drop it and start fresh.
+  if (existsSync(portFile)) {
+    try {
+      const info = JSON.parse(readFileSync(portFile, "utf-8"));
+      if (info && info.port) {
+        let live = false;
+        try {
+          const probe = await fetch(`http://localhost:${info.port}/api/version`, { signal: AbortSignal.timeout(800) }); // guardrails-allow PREVENT-PI-004: optional localhost dashboard server probe (loopback-only)
+          live = probe.ok;
+        } catch {
+          live = false;
+        }
+        if (live) {
+          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 });
+      }
+    } catch {
+      log("port.pid unparseable — treating as stale");
+    }
+    // stale file, remove so the fresh bind does not collide with a lingering
+    // process that still holds the port
+    try { unlinkSync(portFile); } catch { /* ignore */ }
+  }
+
+  // ── 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;
+  }
+
+  const server = createServer((req: IncomingMessage, res: ServerResponse) => {
+    // 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", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET, PUT, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+
+    if (req.method === "OPTIONS") {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+
+    if (req.url === "/" || req.url === "/index.html") {
+      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/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;
+    }
+
+    // Fallback — serve the dashboard
+    const tier = readSnapshot(snapshotPath).tier;
+    res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+    res.end(dashboardHtml(tier));
+  });
+
+  // Bind base + range are env-configurable so tests can use a private,
+  // non-colliding range (parallel runs / leftover servers from killed runs
+  // would otherwise EADDRINUSE on the machine-global 9320 range). Default
+  // MEGACOMPACT_DASHBOARD_PORT=9320 (10-port range 9320–9329) preserves the
+  // production behavior.
+  const TARGET_PORT = Number(process.env.MEGACOMPACT_DASHBOARD_PORT ?? "9320");
+  const PORT_RANGE = 10; // TARGET_PORT..TARGET_PORT+9
+
+  return new Promise((resolve, reject) => {
+    function tryPort(port: number) {
+      server.once("error", (err: NodeJS.ErrnoException) => {
+        if (err.code === "EADDRINUSE" && port < TARGET_PORT + PORT_RANGE - 1) {
+          log("port in use, trying next", { port });
+          tryPort(port + 1);
+        } else {
+          log("listen failed", { port, code: err.code, message: err.message });
+          reject(err);
+        }
+      });
+
+      server.listen(port, "127.0.0.1", () => {
+        const url = `http://localhost:${port}`; // guardrails-allow PREVENT-PI-004: localhost dashboard URL (loopback-only)
+        log("server running", { url });
+        // eslint-disable-next-line no-console
+        console.log(`[mega-compact] dashboard server running: ${url}`);
+
+        // Write port.pid
+        try {
+          writeFileSync(portFile, JSON.stringify({ port, pid: process.pid }));
+        } catch (e) {
+          log("could not write port.pid", { error: String(e) });
+        }
+
+        // Graceful cleanup
+        const cleanup = () => {
+          try { unlinkSync(portFile); } catch { /* already gone */ }
+          server.close();
+          process.exit(0);
+        };
+        process.on("SIGTERM", cleanup);
+        process.on("SIGINT", cleanup);
+
+        resolve({ port, url });
+      });
+    }
+
+    tryPort(TARGET_PORT);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry point — when run directly as `node dashboard-server.js <stateDir>`
+// ---------------------------------------------------------------------------
+
+if (process.argv[1] && process.argv[1].includes("dashboard-server")) {
+  const stateDir = process.argv[2];
+  if (!stateDir) {
+    console.error("Usage: node dashboard-server.js <stateDir>");
+    process.exit(1);
+  }
+  launchDashboardServer(stateDir).catch((err) => {
+    console.error("[mega-compact] dashboard server failed:", err);
+    process.exit(1);
+  });
+}

package/extensions/dashboard-server/snapshot.ts

@@ -0,0 +1,44 @@
+/**
+ * dashboard-server/snapshot.ts — snapshot + events.log file readers.
+ */
+
+import { readFileSync } from "node:fs";
+import type { Snapshot } from "./types.js";
+
+export function readSnapshot(snapshotPath: string) {
+  try {
+    const raw = readFileSync(snapshotPath, "utf-8");
+    return JSON.parse(raw) as Snapshot;
+  } catch {
+    return {
+      version: 1,
+      updatedAt: null,
+      tier: "unknown",
+      presetTier: "unknown",
+      pressure: 0,
+      config: { fastGatePct: 80, thresholdTokens: 100_000, tierPct: null, effectiveThresholdPct: null, anchorUserMessages: 1, preserveRecent: 2, auto: true, autoInlineK: 3 },
+      session: { id: null, state: null, persistedThisSession: false, lastCheckpointId: null, lastCompactedFrom: 0 },
+      context: { tokens: null, percent: null, contextWindow: 0 },
+      trigger: { armed: false, ready: false, currentTokens: null, thresholdTokens: 100_000, fastGatePct: 80, tierPct: null, effectiveThresholdPct: null },
+      store: { checkpointCount: 0, totalTokenEstimate: 0, originalTokens: 0, tokensSaved: 0, injectedCount: 0, dedupHitRate: 0, storageDedupRate: 0, dedupCollapsed: 0 },
+      crew: { activeAgents: 0, currentTurn: 0 },
+      repo: { checkpointCount: 0, totalTokenEstimate: 0, originalTokens: 0, tokensSaved: 0, sessionCount: 0, dedupAttempts: 0, dedupCollapsed: 0, storageDedupRate: 0 },
+      integrity: { regionsRetained: 0, compressedOriginalBytes: 0, duplicatesCollapsed: 0, bytesPermanentlyDeleted: 0 },
+      cacheHits: { session: 0, total: 0, sessionTokensSaved: 0, totalTokensSaved: 0 },
+      compacts: { session: 0, total: 0 },
+      timeSaved: { compact: { sessionSec: 0, totalSec: 0 }, cacheHit: { sessionSec: 0, totalSec: 0 } },
+      compression: { session: { tokensIn: 0, tokensOut: 0, tokensFreed: 0, compressionPct: 0, dedupPct: 0 }, repo: { tokensIn: 0, tokensOut: 0, tokensFreed: 0, compressionPct: 0, dedupPct: 0 } },
+      model: undefined,
+    } as Snapshot;
+  }
+}
+
+export function readFrom(path: string, charOffset: number): { data: string; offset: number } {
+  try {
+    const content = readFileSync(path, "utf-8");
+    if (content.length <= charOffset) return { data: "", offset: charOffset };
+    return { data: content.slice(charOffset), offset: content.length };
+  } catch {
+    return { data: "", offset: charOffset };
+  }
+}

package/extensions/dashboard-server/state.ts

@@ -0,0 +1,33 @@
+/**
+ * dashboard-server/state.ts — local runtime log + version state.
+ *
+ * The dashboard server is spawned as a DETACHED child. When it is launched with
+ * `stdio: "ignore"` (the old default) any crash before the first console.log is
+ * invisible — there is no log to "check". We therefore mirror every lifecycle
+ * line to a file in the state dir so a failed start is always diagnosable. The
+ * launcher also captures stderr, so this doubles as defense-in-depth.
+ */
+
+import { appendFileSync } from "node:fs";
+
+let LOG_PATH: string | null = null;
+
+export function setLogPath(path: string | null): void {
+  LOG_PATH = path;
+}
+
+export function log(...parts: unknown[]): void {
+  const line = `[mega-compact][dashboard] ${parts.map((p) => (typeof p === "string" ? p : JSON.stringify(p))).join(" ")}`;
+  // eslint-disable-next-line no-console
+  console.error(line); // stderr — captured by the launcher pipe
+  if (LOG_PATH) {
+    try { appendFileSync(LOG_PATH, new Date().toISOString() + " " + line + "\n"); } catch { /* non-fatal */ }
+  }
+}
+
+/** Package version of this extension, surfaced in the dashboard header. */
+export let dashboardServerVersion = "0.0.0";
+
+export function setDashboardServerVersion(v: string): void {
+  dashboardServerVersion = v;
+}