pi-mega-compact 0.8.7 → 0.8.8

package/extensions/dashboard-server/html.ts

@@ -189,6 +189,7 @@ export function dashboardHtml(tierName: string): string {
   <button class="tab" data-tab="active">Active Repos</button>
   <button class="tab" data-tab="summary">Summary</button>
   <button class="tab" data-tab="game">Game Mode</button>
+  <button class="tab" data-tab="perf">Perf</button>
 </nav>
 
 <!-- Current repo (existing single-repo view) -->
@@ -443,6 +444,18 @@ export function dashboardHtml(tierName: string): string {
   <div id="game-empty">No scores yet — run a session with game mode on.</div>
 </div>
 
+<!-- Perf (v0.8.8) — live local instrumentation -->
+<div class="tab-panel" id="panel-perf">
+  <div class="grid">
+    <div class="card"><h2>Model latency</h2><div class="stat-grid"><span class="label">Turn p50</span><span class="value" id="pf-turn-p50">—</span><span class="label">Turn p95</span><span class="value" id="pf-turn-p95">—</span><span class="label">Provider p50</span><span class="value" id="pf-prov-p50">—</span><span class="label">Provider p95</span><span class="value" id="pf-prov-p95">—</span></div></div>
+    <div class="card"><h2>Throughput</h2><div class="stat-grid"><span class="label">TPS (avg)</span><span class="value" id="pf-tps">—</span><span class="label">Cache hit %</span><span class="value" id="pf-cache">—</span></div></div>
+    <div class="card"><h2>Process</h2><div class="stat-grid"><span class="label">RSS</span><span class="value" id="pf-rss">—</span><span class="label">Heap</span><span class="value" id="pf-heap">—</span><span class="label">CPU user/sys</span><span class="value" id="pf-cpu">—</span></div></div>
+    <div class="card"><h2>Snapshot cost</h2><div class="stat-grid"><span class="label">DB recompute p50</span><span class="value" id="pf-db-p50">—</span><span class="label">DB recompute p95</span><span class="value" id="pf-db-p95">—</span><span class="label">Disk write p50</span><span class="value" id="pf-disk">—</span></div></div>
+    <div class="card"><h2>TUI lag proxy</h2><div class="stat-grid"><span class="label">Live-trim fires</span><span class="value" id="pf-recompute">—</span><span class="label">Cache replays</span><span class="value" id="pf-replays">—</span><span class="label">Fast-gate skips</span><span class="value" id="pf-skips">—</span></div><div class="meter-sub">skip vs recompute vs replay cadence</div></div>
+  </div>
+  <div class="updated" id="perf-updated">waiting for data</div>
+</div>
+
 <script>
 (function() {
   var evBox = document.getElementById('events');
@@ -1000,9 +1013,40 @@ export function dashboardHtml(tierName: string): string {
     }).catch(function() {});
   }
 
+  // --- Perf tab (v0.8.8) — live local instrumentation ----------------------
+  var perfPollTimer = null;
+  function pollPerf() {
+    fetch('/api/perf?minutes=30').then(function(r) { return r.ok ? r.json() : null; }).then(function(d) { // guardrails-allow PREVENT-PI-004: browser-side fetch in dashboard HTML template (not Node runtime)
+      if (!d) return;
+      var el = document.getElementById('perf-updated');
+      if (el) el.textContent = d.sampleCount + ' samples \u00b7 updated ' + (d.updatedAt || '');
+      function setText(id, txt) { var e = document.getElementById(id); if (e) e.textContent = txt; }
+      function fmtMs(v) { return v == null ? '\u2014' : (v >= 100 ? Math.round(v) + 'ms' : v.toFixed(1) + 'ms'); }
+      function fmtNum(v, dec) { return v == null ? '\u2014' : (typeof v === 'number' ? v.toFixed(dec) : '\u2014'); }
+      setText('pf-turn-p50', fmtMs(d.turn_latency_ms && d.turn_latency_ms.p50));
+      setText('pf-turn-p95', fmtMs(d.turn_latency_ms && d.turn_latency_ms.p95));
+      setText('pf-prov-p50', fmtMs(d.provider_latency_ms && d.provider_latency_ms.p50));
+      setText('pf-prov-p95', fmtMs(d.provider_latency_ms && d.provider_latency_ms.p95));
+      setText('pf-tps', fmtNum(d.tps && d.tps.avg, 1));
+      setText('pf-cache', (d.cache_hit_pct && typeof d.cache_hit_pct.avg === 'number') ? fmtNum(d.cache_hit_pct.avg, 1) + '%' : '\u2014');
+      setText('pf-rss', (d.rss_mb && typeof d.rss_mb.latest === 'number') ? fmtNum(d.rss_mb.latest, 1) + ' MB' : '\u2014');
+      setText('pf-heap', (d.heap_mb && typeof d.heap_mb.latest === 'number') ? fmtNum(d.heap_mb.latest, 1) + ' MB' : '\u2014');
+      setText('pf-cpu', (d.cpu_user_ms && d.cpu_sys_ms) ? (fmtNum(d.cpu_user_ms.latest,1) + ' / ' + fmtNum(d.cpu_sys_ms.latest,1) + ' ms') : '\u2014');
+      setText('pf-db-p50', fmtMs(d.db_recompute_ms && d.db_recompute_ms.p50));
+      setText('pf-db-p95', fmtMs(d.db_recompute_ms && d.db_recompute_ms.p95));
+      setText('pf-disk', fmtMs(d.disk_write_ms && d.disk_write_ms.p50));
+      var diag = d.diag || {};
+      setText('pf-recompute', diag.liveTrimFires != null ? String(diag.liveTrimFires) : '\u2014');
+      setText('pf-replays', diag.liveTrimReplays != null ? String(diag.liveTrimReplays) : '\u2014');
+      setText('pf-skips', diag.ctxFastGate != null ? String(diag.ctxFastGate) : '\u2014');
+    }).catch(function() {});
+  }
+  function startPerfPoll() { if (perfPollTimer) return; pollPerf(); perfPollTimer = setInterval(pollPerf, 2000); }
+  function stopPerfPoll() { if (perfPollTimer) { clearInterval(perfPollTimer); perfPollTimer = null; } }
+
   // --- Tab switching ------------------------------------------------------
   var tabs = document.querySelectorAll('.tab');
-  var panels = { current: 'panel-current', all: 'panel-all', active: 'panel-active', summary: 'panel-summary', game: 'panel-game' };
+  var panels = { current: 'panel-current', all: 'panel-all', active: 'panel-active', summary: 'panel-summary', game: 'panel-game', perf: 'panel-perf' };
   for (var i = 0; i < tabs.length; i++) {
     tabs[i].addEventListener('click', function() {
       var name = this.getAttribute('data-tab');
@@ -1017,6 +1061,7 @@ export function dashboardHtml(tierName: string): string {
       if (name === 'all' || name === 'summary') pollIndex();
       if (name === 'active') pollServers();
       if (name === 'game') { renderGameScores(); renderAchievements(); }
+      if (name === 'perf') startPerfPoll(); else stopPerfPoll();
     });
   }
 })();

package/extensions/dashboard-server/perf-server.test.ts

@@ -0,0 +1,101 @@
+/**
+ * perf-server.test.ts — v0.8.8 /api/perf endpoint (GET aggregates + 405).
+ * Mirrors the server.test.ts spawn-and-fetch harness (self-contained so the
+ * dashboard HTTP-port lane stays isolated).
+ */
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import { recordPerfSample } from "../../src/store/sqlite.js";
+
+const SERVER_ENTRY = new URL("./server.js", import.meta.url).pathname;
+
+function waitFor(cond: () => boolean | Promise<boolean>, timeoutMs = 6000): Promise<void> {
+  const start = Date.now();
+  return new Promise((resolve, reject) => {
+    const tick = async () => {
+      if (await cond()) return resolve();
+      if (Date.now() - start > timeoutMs) return reject(new Error("timeout"));
+      setTimeout(tick, 50);
+    };
+    tick();
+  });
+}
+
+function freshDir(prefix: string): string {
+  return mkdtempSync(join(tmpdir(), prefix));
+}
+
+async function withServer<T>(
+  port: string,
+  dir: string,
+  fn: (port: number) => Promise<T>,
+): Promise<T> {
+  process.env.MEGACOMPACT_DASHBOARD_PORT = port;
+  const child = spawn(process.execPath, [SERVER_ENTRY, dir], { stdio: "ignore" });
+  try {
+    await waitFor(async () => {
+      try {
+        const raw = JSON.parse(readFileSync(join(dir, "port.pid"), "utf-8"));
+        const res = await fetch(`http://localhost:${raw.port}/api/version`);
+        return res.ok;
+      } catch {
+        return false;
+      }
+    });
+    const raw = JSON.parse(readFileSync(join(dir, "port.pid"), "utf-8"));
+    return await fn(raw.port);
+  } finally {
+    child.kill("SIGTERM");
+    delete process.env.MEGACOMPACT_DASHBOARD_PORT;
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+interface PerfResp {
+  sampleCount: number;
+  turn_latency_ms: { p50: number; p95: number; n: number };
+  provider_latency_ms: { p50: number; p95: number; n: number };
+  tps: { avg: number; n: number };
+  cache_hit_pct: { avg: number; latest: number; n: number };
+  db_recompute_ms: { p50: number; p95: number; n: number };
+  disk_write_ms: { p50: number; p95: number; n: number };
+  rss_mb: { latest: number; n: number };
+  heap_mb: { latest: number; n: number };
+  cpu_user_ms: { latest: number; n: number };
+  cpu_sys_ms: { latest: number; n: number };
+  diag: { ctxFastGate: number; liveTrimFires: number; liveTrimReplays: number } | null;
+}
+
+describe("v0.8.8 /api/perf", () => {
+  test("GET returns aggregates over recorded perf_samples", async () => {
+    const dir = freshDir("dash-perf-agg-");
+    recordPerfSample(dir, "turn_latency_ms", 100, { turnIndex: 1 });
+    recordPerfSample(dir, "turn_latency_ms", 200);
+    recordPerfSample(dir, "tps", 50);
+    recordPerfSample(dir, "rss_mb", 256);
+    await withServer("19440", dir, async (port) => {
+      const res = await fetch(`http://localhost:${port}/api/perf?minutes=30`);
+      assert.equal(res.status, 200);
+      const d = (await res.json()) as PerfResp;
+      assert.equal(d.sampleCount, 4);
+      assert.equal(d.turn_latency_ms.n, 2);
+      assert.equal(d.turn_latency_ms.p50, 100); // nearest-rank p50 of [100,200]
+      assert.equal(d.turn_latency_ms.p95, 200); // nearest-rank p95 of [100,200]
+      assert.equal(d.tps.avg, 50);
+      assert.equal(d.rss_mb.latest, 256);
+      assert.equal(d.diag, null); // no runtime wrote dashboard.json in this dir
+    });
+  });
+
+  test("non-GET (POST) -> 405", async () => {
+    const dir = freshDir("dash-perf-meth-");
+    await withServer("19441", dir, async (port) => {
+      const res = await fetch(`http://localhost:${port}/api/perf`, { method: "POST" });
+      assert.equal(res.status, 405);
+    });
+  });
+});

package/extensions/dashboard-server/server.ts

@@ -415,6 +415,85 @@ export async function launchDashboardServer(stateDir: string): Promise<{ port: n
       return;
     }
 
+    // /api/perf — v0.8.8 Perf dashboard tab. GET returns rolling-window
+    // aggregates over perf_samples: per-kind p50/p95 (turn/provider latency,
+    // tps avg, db recompute, disk write), latest rss/heap, cpu user/sys delta,
+    // cache hit %, plus the diag recompute/skip/replay counts (read from
+    // dashboard.json snapshot if available). The dashboard server is a detached
+    // child with no MegaRuntime ref, so it reads perf_samples via a require()'d
+    // sqlite helper (same pattern as /api/game-scores). Unknown/invalid params
+    // are clamped (never throw). Non-GET -> 405. PREVENT-PI-004: loopback.
+    if (req.url?.startsWith("/api/perf")) {
+      const pfReq = createRequire(import.meta.url);
+      const { readPerfSamples } = pfReq("../../src/store/sqlite.js") as typeof import("../../src/store/sqlite.js");
+      if (req.method !== "GET") {
+        res.writeHead(405, { "Content-Type": "application/json" }); // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+        res.end(JSON.stringify({ error: "method_not_allowed" }));
+        return;
+      }
+      try {
+        const url = new URL(req.url, "http://x"); // guardrails-allow PREVENT-PI-004: localhost dashboard URL base (loopback-only)
+        let minutes = Number(url.searchParams.get("minutes") ?? "30");
+        if (!Number.isFinite(minutes) || minutes <= 0) minutes = 30;
+        minutes = Math.min(minutes, 1440); // cap at 24h
+        const sinceTs = Date.now() - minutes * 60_000;
+        const rows = readPerfSamples(stateDir, sinceTs); // guardrails-allow PREVENT-PI-004: local SQLite read (loopback dashboard)
+        const byKind = new Map<string, number[]>();
+        for (const r of rows) {
+          let arr = byKind.get(r.kind);
+          if (!arr) { arr = []; byKind.set(r.kind, arr); }
+          arr.push(r.value);
+        }
+        // Nearest-rank percentile (ceil(p/100*n)-1, clamped). Code-controlled,
+        // never user input (PREVENT-002 safe).
+        function pct(arr: number[], p: number): number {
+          if (!arr.length) return 0;
+          const s = [...arr].sort((a, b) => a - b);
+          const idx = Math.min(s.length - 1, Math.max(0, Math.ceil((p / 100) * s.length) - 1));
+          return s[idx];
+        }
+        function avg(arr: number[]): number {
+          if (!arr.length) return 0;
+          return arr.reduce((a, b) => a + b, 0) / arr.length;
+        }
+        // rows are ASC by ts, so the last pushed value is the most recent.
+        function latest(arr: number[]): number {
+          return arr.length ? arr[arr.length - 1] : 0;
+        }
+        const get = (k: string): number[] => byKind.get(k) ?? [];
+        // diag counters live in the runtime-written dashboard.json (the server is
+        // a detached child with no MegaRuntime ref). Read defensively — absent
+        // until the first snapshot() write (PREVENT-001: assign before access).
+        let diag: { ctxFastGate: number; liveTrimFires: number; liveTrimReplays: number } | null = null;
+        try {
+          const raw = readFileSync(snapshotPath, "utf-8");
+          const parsed = JSON.parse(raw) as { diag?: { ctxFastGate: number; liveTrimFires: number; liveTrimReplays: number } };
+          if (parsed && typeof parsed === "object" && parsed.diag) diag = parsed.diag;
+        } catch { /* dashboard.json not written yet */ }
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({
+          updatedAt: new Date().toISOString(),
+          windowMinutes: minutes,
+          sampleCount: rows.length,
+          turn_latency_ms: { p50: pct(get("turn_latency_ms"), 50), p95: pct(get("turn_latency_ms"), 95), n: get("turn_latency_ms").length },
+          provider_latency_ms: { p50: pct(get("provider_latency_ms"), 50), p95: pct(get("provider_latency_ms"), 95), n: get("provider_latency_ms").length },
+          tps: { avg: avg(get("tps")), n: get("tps").length },
+          cache_hit_pct: { avg: avg(get("cache_hit_pct")), latest: latest(get("cache_hit_pct")), n: get("cache_hit_pct").length },
+          db_recompute_ms: { p50: pct(get("db_recompute_ms"), 50), p95: pct(get("db_recompute_ms"), 95), n: get("db_recompute_ms").length },
+          disk_write_ms: { p50: pct(get("disk_write_ms"), 50), p95: pct(get("disk_write_ms"), 95), n: get("disk_write_ms").length },
+          rss_mb: { latest: latest(get("rss_mb")), n: get("rss_mb").length },
+          heap_mb: { latest: latest(get("heap_mb")), n: get("heap_mb").length },
+          cpu_user_ms: { latest: latest(get("cpu_user_ms")), n: get("cpu_user_ms").length },
+          cpu_sys_ms: { latest: latest(get("cpu_sys_ms")), n: get("cpu_sys_ms").length },
+          diag,
+        }));
+      } catch (e) {
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "perf_unavailable", detail: String(e) }));
+      }
+      return;
+    }
+
     // /api/achievements — S35 achievement tiles. GET returns the 9 seeded rows
     // {id,title,description,icon,hidden,unlocked_at}. The dashboard server is a
     // detached child with no MegaRuntime ref, so it reads game_achievements via

package/extensions/mega-dashboard.ts

@@ -139,6 +139,13 @@ export interface DashboardSnapshot {
     inputRate: number;     // USD per input token (Model.cost)
     outputRate: number;    // USD per output token (Model.cost)
   };
+  /** v0.8.8 Perf dashboard: live diag counters (skip vs recompute vs replay)
+   *  for the Perf tab's "TUI lag proxy" cards. Optional for back-compat. */
+  diag?: {
+    ctxFastGate: number;
+    liveTrimFires: number;
+    liveTrimReplays: number;
+  };
 }
 
 export class Dashboard {
@@ -151,9 +158,19 @@ export class Dashboard {
     this.eventsPath = join(stateDir, "events.log");
   }
 
+  /** v0.8.8: duration (ms) of the last dashboard.json write — read by
+   *  MegaRuntime.snapshot() to record a `disk_write_ms` perf sample without
+   *  wrapping the giant snapshot object literal at the call site. */
+  private _lastWriteMs = 0;
+  get lastWriteMs(): number {
+    return this._lastWriteMs;
+  }
+
   /** Write a full state snapshot (atomically replaces previous). */
   snapshot(data: DashboardSnapshot): void {
+    const t = performance.now();
     writeFileSync(this.snapshotPath, JSON.stringify(data, null, 2) + "\n");
+    this._lastWriteMs = performance.now() - t;
   }
 
   /** Append a timestamped JSONL event line. */

package/extensions/mega-events/perf-handler.ts

@@ -0,0 +1,113 @@
+/**
+ * mega-events/perf-handler.ts — local perf instrumentation handlers (v0.8.8).
+ *
+ * Captures cheap, local-only telemetry into the `perf_samples` SQLite table for
+ * the dashboard's Perf tab: turn + provider latency, TPS, cache hit %, and (via
+ * MegaRuntime.ensurePerfInterval) a 5s cpu/mem interval. All capture is wrapped in
+ * try/catch — instrumentation NEVER blocks the agent loop (non-fatal).
+ *
+ * PREVENT-PI-004: Date.now / process.cpuUsage / process.memoryUsage + local
+ *   SQLite only, zero network.
+ * PREVENT-011: no `any` — the usage block is narrowed structurally.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type MegaRuntime } from "../mega-runtime.js";
+import { recordPerfSample } from "../../src/store/sqlite.js";
+
+/** Structural view of an AssistantMessage usage block (no pi-ai import). */
+interface UsageBlock {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+}
+
+/** Narrow a turn_end message to its usage block when it is an assistant msg. */
+function usageOf(
+	msg: { role?: string; usage?: UsageBlock },
+): UsageBlock | null {
+	if (msg.role !== "assistant" || !msg.usage) return null;
+	return msg.usage;
+}
+
+/** Register perf instrumentation handlers + start the 5s cpu/mem interval. */
+export function registerPerfHandler(
+	pi: ExtensionAPI,
+	runtime: MegaRuntime,
+): void {
+	// turn_start: record the wall-clock start of the turn. Using Date.now() (not
+	// event.timestamp) so the turn_end duration is on ONE clock — mixing pi's
+	// timestamp with Date.now() would skew the delta. Also (re)arms the cpu/mem
+	// interval so a new session after a dispose() resumes sampling on its first
+	// turn (the interval is cleared in runtime.dispose()).
+	pi.on("turn_start", async () => {
+		try {
+			runtime.perfTurnStart = Date.now();
+			runtime.ensurePerfInterval();
+		} catch {
+			/* non-fatal */
+		}
+	});
+
+	// turn_end: compute turn latency + TPS + cache hit % from the assistant
+	// message's usage block. One perf_samples row per metric per turn.
+	pi.on("turn_end", async (event) => {
+		try {
+			if (runtime.perfTurnStart > 0) {
+				const durMs = Date.now() - runtime.perfTurnStart;
+				recordPerfSample(runtime.currentStateDir, "turn_latency_ms", durMs, {
+					turnIndex: event.turnIndex,
+				});
+				const u = usageOf(event.message);
+				if (u) {
+					const durSec = Math.max(durMs / 1000, 0.001);
+					recordPerfSample(
+						runtime.currentStateDir,
+						"tps",
+						u.output / durSec,
+						{ outputTokens: u.output },
+					);
+					const denom = u.cacheRead + u.input + u.cacheWrite;
+					const hitPct = denom > 0 ? (u.cacheRead / denom) * 100 : 0;
+					recordPerfSample(
+						runtime.currentStateDir,
+						"cache_hit_pct",
+						hitPct,
+						{ input: u.input, cacheRead: u.cacheRead, cacheWrite: u.cacheWrite },
+					);
+			}
+		}
+		} catch {
+			/* non-fatal: instrumentation must never break the agent loop */
+		}
+	});
+
+	// before_provider_request -> after_provider_response: raw round-trip latency
+	// to the model endpoint (HTTP status carried on the response event).
+	pi.on("before_provider_request", async () => {
+		try {
+			runtime.perfProviderStart = Date.now();
+		} catch {
+			/* non-fatal */
+		}
+	});
+	pi.on("after_provider_response", async (event) => {
+		try {
+			if (runtime.perfProviderStart > 0) {
+				const lat = Date.now() - runtime.perfProviderStart;
+				recordPerfSample(
+					runtime.currentStateDir,
+					"provider_latency_ms",
+					lat,
+					{ status: event.status },
+				);
+			}
+		} catch {
+			/* non-fatal */
+		}
+	});
+
+	// Start the 5s cpu/mem sampling interval (one per MegaRuntime; cleared in
+	// runtime.dispose()). Idempotent — safe to call again after a dispose().
+	runtime.ensurePerfInterval();
+}

package/extensions/mega-events/register.ts

@@ -12,6 +12,7 @@ import { registerSessionHandlers } from "./session-handlers.js";
 import { registerAgentHandlers } from "./agent-handlers.js";
 import { registerContextHandler } from "./context-handler.js";
 import { registerCompactHandlers } from "./compact-handlers.js";
+import { registerPerfHandler } from "./perf-handler.js";
 
 /**
  * DIAG accessor for the headless test harness: the most recently constructed
@@ -34,4 +35,5 @@ export function registerEventHandlers(
 	registerAgentHandlers(pi, runtime, config);
 	registerContextHandler(pi, runtime, config);
 	registerCompactHandlers(pi, runtime, config);
+	registerPerfHandler(pi, runtime);
 }

package/extensions/mega-events.ts

@@ -15,3 +15,4 @@ export * from "./mega-events/session-handlers.js";
 export * from "./mega-events/agent-handlers.js";
 export * from "./mega-events/context-handler.js";
 export * from "./mega-events/compact-handlers.js";
+export * from "./mega-events/perf-handler.js";

package/extensions/mega-runtime/state.ts

@@ -28,6 +28,7 @@ import {
 	getRecallInjected,
 	getCacheHitTokensSaved,
 	getGameState,
+	recordPerfSample,
 	type ModelSnapshot,
 	type GameState,
 } from "../../src/store/sqlite.js";
@@ -164,6 +165,12 @@ export class MegaRuntime {
 	// Last explain-why line (dedup reason / anchor-kept / superseded), surfaced
 	// while fresh.
 	lastWhy: string | undefined = undefined;
+	// v0.8.8 Perf dashboard instrumentation: turn/provider start timestamps +
+	// the 5s cpu/mem interval handle (one per MegaRuntime, cleared in dispose()).
+	perfTurnStart = 0;
+	perfProviderStart = 0;
+	perfCpuInterval: ReturnType<typeof setInterval> | undefined;
+	private perfCpuBaseline: { user: number; sys: number } | undefined;
 
 	// Context tracking for the dashboard (updated in the context handler).
 	lastCtxTokens: number | null = null;
@@ -385,6 +392,7 @@ export class MegaRuntime {
 			this.renderWidget(ctx);
 			return;
 		}
+		const perfT0 = performance.now();
 		const st = this.store.stats(this.rt.sessionId);
 		const repo = this.store.repoStats();
 		const di = this.store.dataInvariant();
@@ -540,7 +548,13 @@ export class MegaRuntime {
 				cacheHit: { sessionSec: sec(this.rt.cacheHitTokens), totalSec: sec(cacheHitsTotalTokens) },
 			},
 			model,
+			diag: {
+				ctxFastGate: this.diagCtxFastGate,
+				liveTrimFires: this.diagLiveTrimFires,
+				liveTrimReplays: this.diagLiveTrimReplays,
+			},
 		} as DashboardSnapshot);
+		const perfDiskMs = this.dashboard.lastWriteMs;
 
 		// Live stats widget above the editor
 		if (ctx) {
@@ -708,6 +722,12 @@ export class MegaRuntime {
 		}
 		// v0.8.5: record the material-change signature computed at the top so the
 		// next snapshot() can skip this whole body when nothing material changed.
+		try {
+			recordPerfSample(this.currentStateDir, "db_recompute_ms", performance.now() - perfT0);
+			recordPerfSample(this.currentStateDir, "disk_write_ms", perfDiskMs);
+		} catch {
+			/* non-fatal: perf instrumentation never blocks the agent */
+		}
 		this.lastSnapshotSig = sig;
 	}
 
@@ -981,6 +1001,43 @@ export class MegaRuntime {
 			this.gameStateWatcher = undefined;
 			this.gameStateWatchDir = undefined;
 		}
+		// v0.8.8: stop the cpu/mem sampling interval on teardown. Re-armed lazily
+		// by ensurePerfInterval() on the next turn_start.
+		if (this.perfCpuInterval) {
+			clearInterval(this.perfCpuInterval);
+			this.perfCpuInterval = undefined;
+			this.perfCpuBaseline = undefined;
+		}
+	}
+
+	/** v0.8.8: (re)start the 5s cpu/mem sampling interval (idempotent). One per
+	 *  MegaRuntime; cleared in dispose(). Samples process.cpuUsage() (user/sys
+	 *  delta vs the last tick → ms) + process.memoryUsage() (rss/heap → MB) and
+	 *  records them as perf_samples. unref'd so it never keeps the process alive
+	 *  on its own. Non-fatal: any failure is swallowed (instrumentation never
+	 *  blocks the agent). PREVENT-PI-004: local process stats + SQLite only. */
+	ensurePerfInterval(): void {
+		if (this.perfCpuInterval) return;
+		this.perfCpuBaseline = undefined; // first tick sets the baseline (no delta)
+		this.perfCpuInterval = setInterval(() => {
+			try {
+				const dir = this.currentStateDir;
+				const cpu = process.cpuUsage();
+				const mem = process.memoryUsage();
+				if (this.perfCpuBaseline) {
+					const du = (cpu.user - this.perfCpuBaseline.user) / 1000; // μs → ms
+					const ds = (cpu.system - this.perfCpuBaseline.sys) / 1000;
+					recordPerfSample(dir, "cpu_user_ms", Math.max(0, du));
+					recordPerfSample(dir, "cpu_sys_ms", Math.max(0, ds));
+				}
+				this.perfCpuBaseline = { user: cpu.user, sys: cpu.system };
+				recordPerfSample(dir, "rss_mb", mem.rss / 1_000_000);
+				recordPerfSample(dir, "heap_mb", mem.heapUsed / 1_000_000);
+			} catch {
+				/* non-fatal */
+			}
+		}, 5000);
+		this.perfCpuInterval.unref?.();
 	}
 
 	/** S31: the cached game-mode state (game_mode_on/theme/tui_display_mode).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.8.7",
+  "version": "0.8.8",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-2-Clause",

package/src/store/sqlite/perf-samples.test.ts

@@ -0,0 +1,65 @@
+/**
+ * perf-samples.test.ts — v0.8.8 perf_samples table round-trip + filtering.
+ * Pi-agnostic. Uses an isolated state dir (never the real user dir — G7).
+ */
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { mkdtempSync, rmSync } from "node:fs";
+import { closeStore } from "./utils.js";
+import {
+	recordPerfSample,
+	readPerfSamples,
+	PERF_KINDS,
+} from "./perf-samples.js";
+
+describe("perf-samples (v0.8.8)", () => {
+	let dir: string;
+	before(() => {
+		dir = mkdtempSync(join(tmpdir(), "mc-perfsamples-"));
+		process.env.MEGACOMPACT_STATE_DIR = dir;
+	});
+	after(() => {
+		closeStore(dir);
+		delete process.env.MEGACOMPACT_STATE_DIR;
+		rmSync(dir, { recursive: true, force: true });
+	});
+
+	it("records + reads back a turn_latency_ms sample with parsed meta", () => {
+		recordPerfSample(dir, "turn_latency_ms", 123.4, { turnIndex: 2 });
+		const rows = readPerfSamples(dir, 0);
+		assert.equal(rows.length, 1);
+		assert.equal(rows[0].kind, "turn_latency_ms");
+		assert.equal(rows[0].value, 123.4);
+		assert.deepEqual(rows[0].meta, { turnIndex: 2 });
+	});
+
+	it("filters by kind and by sinceTs", () => {
+		recordPerfSample(dir, "tps", 50);
+		recordPerfSample(dir, "rss_mb", 256);
+		const tps = readPerfSamples(dir, 0, "tps");
+		assert.equal(tps.length, 1);
+		assert.equal(tps[0].kind, "tps");
+		assert.equal(tps[0].value, 50);
+		const future = readPerfSamples(dir, Date.now() + 10000, "tps");
+		assert.equal(future.length, 0);
+	});
+
+	it("ignores non-finite values + unknown kinds (never throws, nothing added)", () => {
+		const before = readPerfSamples(dir, 0).length;
+		recordPerfSample(dir, "tps", Number.NaN);
+		recordPerfSample(dir, "tps", Infinity);
+		assert.doesNotThrow(() =>
+			recordPerfSample(dir, "bogus" as never, 1),
+		);
+		const after = readPerfSamples(dir, 0).length;
+		assert.equal(after, before);
+	});
+
+	it("PERF_KINDS lists the 10 instrumentation kinds", () => {
+		assert.equal(PERF_KINDS.length, 10);
+		assert.ok(PERF_KINDS.includes("db_recompute_ms"));
+		assert.ok(PERF_KINDS.includes("cache_hit_pct"));
+	});
+});