pi-mega-compact 0.8.21 → 0.8.22

package/dist/src/recall.test.js

@@ -6,7 +6,9 @@ import { join } from "node:path";
 import { VectorStore } from "./vectorStore.js";
 import { compactSession } from "./engine.js";
 import { recallAndInline, recallAndInlineAsync, formatRecallBlock } from "./recall.js";
+import { vectorList } from "./vectorStore.js";
 import { markInjectedGlobal, wasInjectedGlobal, closeIndexStore } from "./store/sqlite.js";
+import { closeVectorIndex, initVectorIndex, rebuildFromSqlite, } from "./store/vectorIndex.js";
 const baseTmp = mkdtempSync(join(tmpdir(), "mc-recall-"));
 let counter = 0;
 function store() {
@@ -92,53 +94,109 @@ test("Fix C: inline dedupe drops a hit already resident in the live window", ()
     assert.ok(rDedup.toInject.length <= rNoDedup.toInject.length, "dedupe never adds hits");
     assert.ok(rDedup.toInject.length < rNoDedup.toInject.length, "inline dedupe dropped a resident hit");
 });
+// ---- S18 cross-repo global injected-set (real-data, no mocks) ----------------
+//
+// Earlier versions of these tests used `as any` mock stores with canned
+// `searchAsync` returns. That was mock data: it asserted recall's orchestration
+// against a fake search result, not the real embed → HNSW → hydrate → inject
+// path. Per the no-mock-data principle, both tests now seed a REAL foreign
+// VectorStore (real checkpoint + real TrigramEmbedder embedding persisted to
+// SQLite), rebuild the real PGlite index from it via `rebuildFromSqlite`, and
+// run the full `recallAndInlineAsync` cross-repo path against a separate self
+// store. The foreign checkpoint hydrates from the foreign store via its real
+// repoId (== stateDir, per VectorStore's repoId convention).
+async function seedForeignRepo(foreignStateDir) {
+    // A real VectorStore at the foreign repo's stateDir. repoId == stateDir.
+    const foreign = new VectorStore({ stateDir: foreignStateDir, dedupSim: 0.9 });
+    const sess = "sess_foreign";
+    // Seed a real checkpoint via the real compactSession pipeline. The summary
+    // text determines the embedding; the query below must land near it.
+    const summary = "foreign repo authentication jwt token validation";
+    const result = compactSession({
+        sessionId: sess,
+        messages: [msg("user", summary), msg("assistant", "ok", "Edit")],
+        keepFrom: 2,
+        timestamp: 1,
+    }, foreign);
+    return { sessionId: sess, checkpointId: result.checkpointId ?? "", summary };
+}
 test("S18: global injected-set skips a foreign checkpoint already injected machine-wide", async () => {
+    if (process.env.MEGACOMPACT_PGLITE_DISABLED === "true") {
+        return;
+    } // skip when WASM index is off
     const indexDir = mkdtempSync(join(tmpdir(), "mc-gi-"));
+    const foreignStateDir = mkdtempSync(join(tmpdir(), "mc-gi-foreign-"));
+    const selfStateDir = mkdtempSync(join(tmpdir(), "mc-gi-self-"));
+    process.env.MEGACOMPACT_VECTOR_INDEX_DIR = mkdtempSync(join(tmpdir(), "mc-gi-vidx-"));
     try {
+        await closeVectorIndex(); // fresh singleton per this index dir
+        const seed = await seedForeignRepo(foreignStateDir);
+        // Populate the real PGlite index from the foreign store's real checkpoints.
+        await rebuildFromSqlite(() => [{ repoId: foreignStateDir, stateDir: foreignStateDir }], (sd) => {
+            // readCheckpoints: yield (sessionId, checkpointId, embedding) for every
+            // real checkpoint in this store. Mirrors the production enumerator.
+            const store = new VectorStore({ stateDir: sd, dedupSim: 0.9 });
+            return vectorList(store, seed.sessionId).map((cp) => ({
+                sessionId: seed.sessionId,
+                checkpointId: cp.checkpointId,
+                embedding: cp.embedding,
+            }));
+        });
+        const pg = await initVectorIndex();
+        assert.ok(pg, "PGlite index should initialize (WASM available)");
         const sess = "sess_cross";
-        // A foreign checkpoint already marked injected globally (in this session).
-        markInjectedGlobal("chkpt_foreign", "/repo/other", sess, indexDir);
-        assert.equal(wasInjectedGlobal("chkpt_foreign", sess, indexDir), true);
-        // searchAsync returns the foreign hit; recallAndInlineAsync must skip it
-        // (globally injected) → toInject is empty.
-        const mockStore = {
-            searchAsync: async () => [{
-                    checkpoint: { checkpointId: "chkpt_foreign", summary: "foreign work", filesModified: [], dedupStatus: "active" },
-                    score: 0.92,
-                    repoId: "/repo/other",
-                }],
-            wasInjected: () => false,
-            markInjected: () => { },
-        };
-        const r = await recallAndInlineAsync({ sessionId: sess, query: "foreign", limit: 3, source: "command", crossRepo: true, globalIndexDir: indexDir }, mockStore);
+        // Pre-mark the foreign checkpoint as already injected machine-wide.
+        markInjectedGlobal(seed.checkpointId, foreignStateDir, sess, indexDir);
+        assert.equal(wasInjectedGlobal(seed.checkpointId, sess, indexDir), true);
+        // Self store (different repo) — the cross-repo query runs against the index.
+        const selfStore = new VectorStore({ stateDir: selfStateDir, dedupSim: 0.9 });
+        const r = await recallAndInlineAsync({ sessionId: sess, query: "foreign repo authentication jwt", limit: 3, source: "command", crossRepo: true, globalIndexDir: indexDir }, selfStore);
         assert.equal(r.toInject.length, 0, "globally-injected foreign checkpoint skipped");
     }
     finally {
+        await closeVectorIndex();
         closeIndexStore();
+        delete process.env.MEGACOMPACT_VECTOR_INDEX_DIR;
         rmSync(indexDir, { recursive: true, force: true });
+        rmSync(foreignStateDir, { recursive: true, force: true });
+        rmSync(selfStateDir, { recursive: true, force: true });
     }
 });
 test("S18: a fresh foreign checkpoint is injected AND recorded globally", async () => {
+    if (process.env.MEGACOMPACT_PGLITE_DISABLED === "true") {
+        return;
+    } // skip when WASM index is off
     const indexDir = mkdtempSync(join(tmpdir(), "mc-gi2-"));
+    const foreignStateDir = mkdtempSync(join(tmpdir(), "mc-gi2-foreign-"));
+    const selfStateDir = mkdtempSync(join(tmpdir(), "mc-gi2-self-"));
+    process.env.MEGACOMPACT_VECTOR_INDEX_DIR = mkdtempSync(join(tmpdir(), "mc-gi2-vidx-"));
     try {
+        await closeVectorIndex(); // fresh singleton per this index dir
+        const seed = await seedForeignRepo(foreignStateDir);
+        assert.equal(wasInjectedGlobal(seed.checkpointId, "sess_fresh", indexDir), false);
+        await rebuildFromSqlite(() => [{ repoId: foreignStateDir, stateDir: foreignStateDir }], (sd) => {
+            const store = new VectorStore({ stateDir: sd, dedupSim: 0.9 });
+            return vectorList(store, seed.sessionId).map((cp) => ({
+                sessionId: seed.sessionId,
+                checkpointId: cp.checkpointId,
+                embedding: cp.embedding,
+            }));
+        });
+        const pg = await initVectorIndex();
+        assert.ok(pg, "PGlite index should initialize (WASM available)");
         const sess = "sess_fresh";
-        assert.equal(wasInjectedGlobal("chkpt_new", sess, indexDir), false);
-        const mockStore = {
-            searchAsync: async () => [{
-                    checkpoint: { checkpointId: "chkpt_new", summary: "brand new foreign work", filesModified: [], dedupStatus: "active" },
-                    score: 0.93,
-                    repoId: "/repo/alpha",
-                }],
-            wasInjected: () => false,
-            markInjected: () => { },
-        };
-        const r = await recallAndInlineAsync({ sessionId: sess, query: "foreign", limit: 3, source: "command", crossRepo: true, globalIndexDir: indexDir }, mockStore);
+        const selfStore = new VectorStore({ stateDir: selfStateDir, dedupSim: 0.9 });
+        const r = await recallAndInlineAsync({ sessionId: sess, query: "foreign repo authentication jwt", limit: 3, source: "command", crossRepo: true, globalIndexDir: indexDir }, selfStore);
         assert.equal(r.toInject.length, 1, "fresh foreign checkpoint injected");
-        assert.equal(wasInjectedGlobal("chkpt_new", sess, indexDir), true, "recorded machine-wide");
+        assert.equal(wasInjectedGlobal(seed.checkpointId, sess, indexDir), true, "recorded machine-wide");
     }
     finally {
+        await closeVectorIndex();
         closeIndexStore();
+        delete process.env.MEGACOMPACT_VECTOR_INDEX_DIR;
         rmSync(indexDir, { recursive: true, force: true });
+        rmSync(foreignStateDir, { recursive: true, force: true });
+        rmSync(selfStateDir, { recursive: true, force: true });
     }
 });
 test("cleanup", () => {

package/dist/src/sprint14.test.js

@@ -7,7 +7,7 @@ import assert from "node:assert/strict";
 import { mkdtempSync, rmSync, readFileSync, existsSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { VectorStore } from "./vectorStore.js";
+import { VectorStore, vectorSearch } from "./vectorStore.js";
 import { defaultEmbedder } from "./embedder.js";
 import { loadDedupConfig } from "./config/dedup.js";
 import { loadMetrics, saveMetrics, recordDecision, evaluateAlerts, fpRate, p95, } from "./monitoring.js";
@@ -35,7 +35,7 @@ test("flag matrix: all 16 L0/L1/L2/RAPTOR enable combos are safe", () => {
                     s.add({ sessionId: "s", summary: "x", regionText: `region A for combo ${combos} about the cache`, timestamp: 1 });
                     const r2 = s.add({ sessionId: "s", summary: "x", regionText: `region B for combo ${combos} about the parser`, timestamp: 2 });
                     // search must not throw under any combination
-                    const hits = s.search("s", "cache", 3);
+                    const hits = vectorSearch(s, "s", "cache", 3);
                     assert.ok(Array.isArray(hits));
                     // With all tiers off, the second add is always "new" (no collapse).
                     if (!l0 && !l1 && !l2)

package/dist/src/store/migrate.test.js

@@ -15,7 +15,7 @@ import assert from "node:assert/strict";
 import { mkdtempSync, rmSync, existsSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { VectorStore } from "../vectorStore.js";
+import { VectorStore, vectorMarkInjected, vectorWasInjected, vectorSearch } from "../vectorStore.js";
 import { writeGzJson } from "../store.js";
 import { migrateJsonToSqlite, readLegacyCheckpointFile } from "../store/migrate.js";
 import { listCheckpoints, closeStore } from "../store/sqlite.js";
@@ -110,7 +110,7 @@ test("cross-process recall: fresh VectorStore over same dir recalls prior checkp
     closeStore(dir);
     // Process B: brand-new VectorStore, same stateDir.
     const b = new VectorStore({ stateDir: dir });
-    const hits = b.search(sid, "cross process recall proof", 5);
+    const hits = vectorSearch(b, sid, "cross process recall proof", 5);
     assert.equal(hits.length, 1, "checkpoint survives cross-process reopen");
     assert.equal(hits[0].checkpoint.checkpointId, "chkpt_001");
     assert.ok(hits[0].score > 0.5, "recall is relevant");
@@ -127,11 +127,11 @@ test("cross-process recall: injected state persists across reopen", () => {
         regionText: "injected state persists across process reopen test",
         timestamp: 1,
     });
-    a.markInjected(sid, added.checkpoint.checkpointId);
-    assert.equal(a.wasInjected(sid, added.checkpoint.checkpointId), true);
+    vectorMarkInjected(a, sid, added.checkpoint.checkpointId);
+    assert.equal(vectorWasInjected(a, sid, added.checkpoint.checkpointId), true);
     closeStore(dir);
     const b = new VectorStore({ stateDir: dir });
-    assert.equal(b.wasInjected(sid, added.checkpoint.checkpointId), true, "injection remembered");
+    assert.equal(vectorWasInjected(b, sid, added.checkpoint.checkpointId), true, "injection remembered");
     closeStore(dir);
 });
 test("cleanup", () => {

package/dist/src/store/sprint10.test.js

@@ -3,7 +3,7 @@ import assert from "node:assert/strict";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { VectorStore } from "../vectorStore.js";
+import { VectorStore, vectorList, vectorRepoStats } from "../vectorStore.js";
 import { normalize } from "../dedup/normalize.js";
 import { openBloom, closeBloom } from "./bloom.js";
 import { backfillContentHashes, isBackfillComplete } from "./backfill.js";
@@ -25,7 +25,7 @@ test("Sprint 10 L0: case/whitespace/ANSI variants dedup to one row", () => {
         if (!r.deduped)
             added++;
     }
-    assert.equal(s.list("sess_norm").length, 1);
+    assert.equal(vectorList(s, "sess_norm").length, 1);
 });
 test("normalize case-folds so Foo/foo/FOO are equal", () => {
     assert.equal(normalize("Foo Bar"), normalize("foo bar"));
@@ -63,7 +63,7 @@ test("duplicate add is idempotent (no partial rows, single checkpoint)", () => {
     const b = s.add({ sessionId: "sess_atom", summary: "x", regionText: raw, timestamp: 2 });
     assert.equal(a.deduped, false);
     assert.equal(b.deduped, true);
-    assert.equal(s.list("sess_atom").length, 1);
+    assert.equal(vectorList(s, "sess_atom").length, 1);
 });
 // --- Backfill orchestrator -------------------------------------------------
 test("backfill populates null content_hash rows and is idempotent", () => {
@@ -170,14 +170,14 @@ test("Sprint 10 migration: pre-0.4.2 db gains original_token_estimate and repoSt
         originalTokenEstimate: 500,
         timestamp: 1,
     });
-    const repo = vs.repoStats();
+    const repo = vectorRepoStats(vs);
     // No "no such column" crash = migration succeeded; totals reflect the new col.
     assert.equal(repo.checkpointCount, 1);
     assert.equal(repo.originalTokens, 500, "originalTokens read from migrated column");
     // Re-open a second time to prove idempotency (column already exists).
     closeStore(dir);
     const vs2 = new VectorStore({ dedupSim: 0.9, stateDir: dir });
-    assert.equal(vs2.repoStats().originalTokens, 500, "stable across re-open");
+    assert.equal(vectorRepoStats(vs2).originalTokens, 500, "stable across re-open");
 });
 // --- cleanup ---------------------------------------------------------------
 test("Sprint 10 cleanup", () => {

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

@@ -12,9 +12,13 @@
  * infrequent idempotent upserts (ON CONFLICT). Fully local (PREVENT-PI-004).
  */
 import { DatabaseSync } from "node:sqlite";
-import { appendFileSync, existsSync, mkdirSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
+import { existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
+// Back-compat re-exports: session heartbeat + timeseries helpers moved to
+// global-sessions.ts (file-size split). Existing imports from this module
+// keep resolving; behavior is unchanged.
+export { recordSessionHeartbeat, appendTokenSample, pruneStaleSessions, pruneTokenSamples, readActiveSessions, readSessionTimeseries, clearSessionHeartbeat, } from "./global-sessions.js";
 /** Resolve the machine-wide index directory (env-overridable). */
 export function getIndexDir() {
     const override = process.env.MEGACOMPACT_INDEX_DIR;
@@ -247,176 +251,3 @@ 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 });
-}

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

@@ -0,0 +1,190 @@
+/**
+ * global-sessions.ts — session heartbeats + token time-series (S39).
+ *
+ * Split out of global-index.ts so each file stays under 500 lines. Shares the
+ * same machine-wide index DB (`indexCache` in global-index.ts) via
+ * `openIndexStore()`; no schema or behavior change — pure structural move.
+ *
+ * `session_heartbeats`: one row per (pid, session_id) live session, upserted on
+ * every material snapshot. `token_samples`: append-only rows with
+ * (session_id, tokens, percent, ts) for the stacked-memory graph. Garbage-
+ * collected by pruneTokenSamples.
+ *
+ * All queries use @named/$named bind parameters (PREVENT-002); local
+ * node:sqlite + WAL (PREVENT-PI-004), multi-process safe.
+ */
+import { appendFileSync, existsSync, mkdirSync } from "node:fs";
+import { openIndexStore, getIndexDir } from "./global-index.js";
+/** 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 });
+}