pi-mega-compact 0.8.17 → 0.8.18

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

@@ -691,6 +691,89 @@ export async function launchDashboardServer(stateDir) {
             }
             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");
+                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");
+            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" &&

package/dist/extensions/mega-runtime/state.js

@@ -15,7 +15,7 @@ import { VectorStore } from "../../src/vectorStore.js";
 import { toEngineMessages } from "../../src/adapt.js";
 import { normalizeSessionId } from "../../src/store.js";
 import { Logger } from "../../src/log.js";
-import { recordModelSnapshot, latestModelSnapshot, upsertRepoRegistry, recordRepoModel, getDedupStats, getCompactCount, getRecallInjected, getCacheHitTokensSaved, getGameState, recordPerfSample, } from "../../src/store/sqlite.js";
+import { recordModelSnapshot, latestModelSnapshot, upsertRepoRegistry, recordRepoModel, getDedupStats, getCompactCount, getRecallInjected, getCacheHitTokensSaved, getGameState, recordPerfSample, recordSessionHeartbeat, appendTokenSample, } from "../../src/store/sqlite.js";
 import { detectCrossRepoDrift } from "../../src/driftDetection.js";
 import { repoStateDir, resolveRepoRoot, pressureRatio, pressureFromPct, pressureBand, effectiveThresholdTokens, } from "../mega-config.js";
 import { Dashboard } from "../mega-dashboard.js";
@@ -513,6 +513,22 @@ export class MegaRuntime {
             },
         });
         const perfDiskMs = this.dashboard.lastWriteMs;
+        // S39: record a session heartbeat + token sample into the shared
+        // machine-wide index.sqlite so the dashboard can show a real-time
+        // stacked-memory graph across all active pi processes. Behind the
+        // material-change gate (this code only runs when sig changed). Non-fatal
+        // try/catch mirrors the recordPerfSample pattern below. Skip the token
+        // sample when lastCtxTokens is null (no context data yet).
+        try {
+            const repo = resolveRepoRoot(ctx?.cwd ?? this.currentStateDir) ?? this.currentStateDir;
+            recordSessionHeartbeat(process.pid, this.rt.sessionId, repo, this.currentStateDir, this.lastCtxWindow || 0);
+            if (this.lastCtxTokens != null) {
+                appendTokenSample(this.rt.sessionId, repo, this.lastCtxTokens, this.lastCtxPercent ?? 0, this.lastCtxWindow || 0, join(this.currentStateDir, "events.log"));
+            }
+        }
+        catch {
+            /* non-fatal: S39 monitoring must never block the snapshot path */
+        }
         // Live stats widget above the editor
         if (ctx) {
             // ── gather widget data (computed per snapshot, rendered per frame) ────

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);
+    }
+}

package/dist/src/store/sqlite/global-index.js

@@ -12,7 +12,7 @@
  * infrequent idempotent upserts (ON CONFLICT). Fully local (PREVENT-PI-004).
  */
 import { DatabaseSync } from "node:sqlite";
-import { existsSync, mkdirSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 /** Resolve the machine-wide index directory (env-overridable). */
@@ -71,6 +71,31 @@ export function openIndexStore(indexDir = getIndexDir()) {
       PRIMARY KEY (checkpoint_id, session_id)
     );
     CREATE INDEX IF NOT EXISTS idx_injected_global_cid ON injected_global(checkpoint_id);
+    -- S39: machine-wide session heartbeats + token time-series for the live
+    -- multi-pi stacked-memory graph. One row per (pid, session_id), updated
+    -- on every material snapshot() change (NOT on idle/context-repeat events).
+    -- Written by every pi process; read by the dashboard server. WAL-safe.
+    -- PRAMETERIZED queries (PREVENT-002); local node:sqlite (PREVENT-PI-004).
+    CREATE TABLE IF NOT EXISTS session_heartbeats (
+      pid          INTEGER NOT NULL,
+      session_id   TEXT NOT NULL,
+      repo_root    TEXT,
+      state_dir    TEXT,
+      ctx_window   INTEGER DEFAULT 0,
+      last_seen    INTEGER NOT NULL,
+      PRIMARY KEY (pid, session_id)
+    );
+    CREATE TABLE IF NOT EXISTS token_samples (
+      id           INTEGER PRIMARY KEY AUTOINCREMENT,
+      session_id   TEXT NOT NULL,
+      repo_root    TEXT,
+      tokens       INTEGER NOT NULL,
+      percent      REAL NOT NULL,
+      ctx_window   INTEGER DEFAULT 0,
+      ts           INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_token_samples_ts ON token_samples(ts);
+    CREATE INDEX IF NOT EXISTS idx_token_samples_sid_ts ON token_samples(session_id, ts);
   `);
     indexCache = iddb;
     indexCacheDir = indexDir;
@@ -222,3 +247,176 @@ export function countInjectedGlobal(indexDir = getIndexDir()) {
     const row = db.prepare("SELECT COUNT(*) AS n FROM injected_global").get();
     return row?.n ?? 0;
 }
+/** Stable color palette for per-session series (hash-based, no randomness). */
+const SESSION_COLORS = [
+    "#60a5fa", // blue-400
+    "#34d399", // emerald-400
+    "#fbbf24", // amber-400
+    "#f87171", // red-400
+    "#a78bfa", // violet-400
+    "#f472b6", // pink-400
+    "#22d3ee", // cyan-400
+    "#a3e635", // lime-400
+];
+/** Hash a sessionId to a stable color index. */
+function sessionColor(sessionId) {
+    let h = 0;
+    for (let i = 0; i < sessionId.length; i++) {
+        h = (h * 31 + sessionId.charCodeAt(i)) | 0;
+    }
+    return SESSION_COLORS[Math.abs(h) % SESSION_COLORS.length];
+}
+/**
+ * Record (upsert) a session heartbeat. Called from snapshot() on every material
+ * change. PRIMARY KEY (pid, session_id) means concurrent pi processes each get
+ * their own row. Non-fatal on conflict (INSERT ... ON CONFLICT DO UPDATE).
+ */
+export function recordSessionHeartbeat(pid, sessionId, repoRoot, stateDir, ctxWindow, indexDir = getIndexDir()) {
+    const db = openIndexStore(indexDir);
+    const now = Date.now();
+    db.prepare(`INSERT INTO session_heartbeats (pid, session_id, repo_root, state_dir, ctx_window, last_seen)
+     VALUES (@pid, @session_id, @repo_root, @state_dir, @ctx_window, @last_seen)
+     ON CONFLICT(pid, session_id) DO UPDATE SET
+       repo_root = excluded.repo_root,
+       state_dir = excluded.state_dir,
+       ctx_window = excluded.ctx_window,
+       last_seen = excluded.last_seen`).run({
+        pid,
+        session_id: sessionId,
+        repo_root: repoRoot,
+        state_dir: stateDir,
+        ctx_window: ctxWindow,
+        last_seen: now,
+    });
+}
+/**
+ * Append a token sample row + optionally a session_sample line to events.log
+ * (for SSE real-time push via /api/events). The eventsLogPath is optional —
+ * callers without an events.log (e.g. tests) can omit it.
+ */
+export function appendTokenSample(sessionId, repoRoot, tokens, percent, ctxWindow, eventsLogPath, indexDir = getIndexDir()) {
+    const db = openIndexStore(indexDir);
+    const now = Date.now();
+    db.prepare(`INSERT INTO token_samples (session_id, repo_root, tokens, percent, ctx_window, ts)
+     VALUES (@session_id, @repo_root, @tokens, @percent, @ctx_window, @ts)`).run({
+        session_id: sessionId,
+        repo_root: repoRoot,
+        tokens,
+        percent,
+        ctx_window: ctxWindow,
+        ts: now,
+    });
+    // Step 5: also append a session_sample JSON line to events.log so the
+    // existing /api/events SSE tail streams it for free (real-time chart push).
+    // Mirrors the DashboardEmitter events.log append pattern in
+    // extensions/mega-dashboard.ts:{ event(type, data) }: a JSON object with
+    // `ts` (ISO 8601 string), `type`, and the event-specific payload. The ISO
+    // timestamp matches the shape of every other SSE variant (SseSessionSample
+    // contract; every SSE variant's `ts` is a string); a numeric ms `ts` would
+    // violate the contract union's "every SSE variant has a ts field of type
+    // string" invariant and break DashboardEmitter consumers.
+    if (eventsLogPath) {
+        try {
+            const dir = eventsLogPath.includes("/") ? eventsLogPath.slice(0, eventsLogPath.lastIndexOf("/")) : ".";
+            if (!existsSync(dir))
+                mkdirSync(dir, { recursive: true });
+            appendFileSync(eventsLogPath, JSON.stringify({
+                ts: new Date(now).toISOString(),
+                type: "session_sample",
+                sessionId,
+                tokens,
+                percent,
+            }) + "\n");
+        }
+        catch {
+            /* non-fatal: SSE push is best-effort */
+        }
+    }
+}
+/**
+ * Prune stale session heartbeats (sessions not seen within maxAgeMs).
+ * Default 30-min retention. Called by /api/sessions.
+ */
+export function pruneStaleSessions(maxAgeMs = 1_800_000, indexDir = getIndexDir()) {
+    const db = openIndexStore(indexDir);
+    const cutoff = Date.now() - maxAgeMs;
+    const result = db.prepare("DELETE FROM session_heartbeats WHERE last_seen < @cutoff").run({ cutoff });
+    return Number(result.changes);
+}
+/**
+ * Prune old token samples older than maxAgeMs. Default 30-min retention.
+ * Called by /api/sessions/timeseries.
+ */
+export function pruneTokenSamples(maxAgeMs = 1_800_000, indexDir = getIndexDir()) {
+    const db = openIndexStore(indexDir);
+    const cutoff = Date.now() - maxAgeMs;
+    const result = db.prepare("DELETE FROM token_samples WHERE ts < @cutoff").run({ cutoff });
+    return Number(result.changes);
+}
+/**
+ * Read all active sessions with their latest token sample (if any).
+ * JOINs session_heartbeats with the latest token_samples per session_id
+ * via a correlated subquery. Returns rows sorted by last_seen descending.
+ */
+export function readActiveSessions(indexDir = getIndexDir()) {
+    const db = openIndexStore(indexDir);
+    const rows = db.prepare(`SELECT h.pid, h.session_id, h.repo_root, h.state_dir, h.ctx_window, h.last_seen,
+            s.tokens, s.percent
+     FROM session_heartbeats h
+     LEFT JOIN token_samples s ON s.id = (
+       SELECT id FROM token_samples t
+       WHERE t.session_id = h.session_id
+       ORDER BY t.ts DESC LIMIT 1
+     )
+     ORDER BY h.last_seen DESC`).all();
+    return rows.map((r) => ({
+        pid: r.pid,
+        sessionId: r.session_id,
+        repoRoot: r.repo_root,
+        stateDir: r.state_dir,
+        ctxWindow: r.ctx_window ?? 0,
+        lastSeen: r.last_seen,
+        tokens: r.tokens,
+        percent: r.percent,
+    }));
+}
+/**
+ * Read token samples since sinceMs, returning a recharts-ready stacked shape:
+ * per-session `SessionSeries` (with stable color) + a `totals` array
+ * [{ts, tokens}] (sum of all sessions at each timestamp).
+ */
+export function readSessionTimeseries(sinceMs, indexDir = getIndexDir()) {
+    const db = openIndexStore(indexDir);
+    const rows = db.prepare(`SELECT session_id, tokens, percent, ts FROM token_samples WHERE ts >= @since ORDER BY ts ASC`).all({ since: sinceMs });
+    // Group by session_id → series; + accumulate totals per timestamp.
+    const seriesMap = new Map();
+    const totalsMap = new Map();
+    for (const r of rows) {
+        let pts = seriesMap.get(r.session_id);
+        if (!pts) {
+            pts = [];
+            seriesMap.set(r.session_id, pts);
+        }
+        pts.push({ ts: r.ts, tokens: r.tokens, percent: r.percent });
+        totalsMap.set(r.ts, (totalsMap.get(r.ts) ?? 0) + r.tokens);
+    }
+    const series = [];
+    for (const [sessionId, data] of seriesMap) {
+        const label = sessionId.length > 12 ? sessionId.slice(0, 12) : sessionId;
+        series.push({ sessionId, label, color: sessionColor(sessionId), data });
+    }
+    // Sort series by first-timestamp for stable legend order.
+    series.sort((a, b) => (a.data[0]?.ts ?? 0) - (b.data[0]?.ts ?? 0));
+    const totals = Array.from(totalsMap.entries())
+        .sort((a, b) => a[0] - b[0])
+        .map(([ts, tokens]) => ({ ts, tokens }));
+    return { series, totals };
+}
+/**
+ * Clear a session's heartbeat row (e.g. on clean shutdown / session reset).
+ * Non-fatal: no-op if the row doesn't exist.
+ */
+export function clearSessionHeartbeat(pid, sessionId, indexDir = getIndexDir()) {
+    const db = openIndexStore(indexDir);
+    db.prepare("DELETE FROM session_heartbeats WHERE pid = @pid AND session_id = @session_id").run({ pid, session_id: sessionId });
+}