pi-mega-compact 0.8.6 → 0.8.8

package/extensions/mega-cache-replay.test.ts

@@ -0,0 +1,211 @@
+/**
+ * mega-cache-replay.test.ts — locks the v0.8.7 cache-stability fix.
+ *
+ * Two tests (reuses the mega-teamrun.test.ts harness shape: mock pi + the REAL
+ * compiled extension at extensions/mega-compact.js):
+ *  a. REPLAY: drive >=2 gated context events past the debounce within ONE epoch
+ *     (same lastCheckpointId) and assert diagLiveTrimReplays > 0 AND the returned
+ *     messages array is byte-identical (deepEqual) across replays (stable prefix).
+ *  b. DEDUP-ON-DIFFERENT-CHECKPOINT: after a fresh trim, simulate a re-compact
+ *     (context grew on the token basis) that DEDUPS onto a DIFFERENT existing
+ *     checkpoint id (L0 contentHash match against an OLDER checkpoint, so
+ *     result.checkpointId != rt.lastCheckpointId), then assert the NEXT gated
+ *     event STILL replays (diagLiveTrimReplays increments) — i.e. the cache key
+ *     trimCache.checkpointId === rt.lastCheckpointId holds. This is the P2 gap the
+ *     v0.8.6 audit found: keying on the dedup-volatile result.checkpointId
+ *     disabled replay for the rest of the epoch after such a dedup fire.
+ *
+ * MEGACOMPACT_PGLITE_DISABLED keeps the run fast (no WASM index init).
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createRequire } from "node:module";
+import { closeVectorIndex } from "../src/store/vectorIndex.js";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+
+const require = createRequire(import.meta.url);
+const baseTmp = mkdtempSync(join(tmpdir(), "mc-cache-"));
+process.env.MEGACOMPACT_INDEX_DIR = join(baseTmp, "index");
+process.env.MEGACOMPACT_PGLITE_DISABLED = "true"; // fast: skip WASM index
+let counter = 0;
+
+function harness() {
+  const stateDir = join(baseTmp, `run-${counter++}`);
+  process.env.MEGACOMPACT_STATE_DIR = stateDir;
+  process.env.MEGACOMPACT_DEBUG = "true";
+  process.env.MEGACOMPACT_THRESHOLD_TOKENS = "50";
+  process.env.MEGACOMPACT_FAST_GATE_PCT = "1";
+  process.env.MEGACOMPACT_ANCHOR_USER_MESSAGES = "1";
+  process.env.MEGACOMPACT_DURABLE_TRIM_FLOOR = "0";
+  process.env.MEGACOMPACT_MEMORY_AUTO_REVIEW = "false";
+  process.env.MEGACOMPACT_RAPTOR_ENABLED = "false";
+  // Disable the FUZZY dedup tiers (L1 MinHash/LSH + L2 cosine) so the DEDUP test
+  // is controlled by L0 contentHash only: setB (different vocabulary) then
+  // creates a genuinely NEW checkpoint instead of fuzzy-matching setA's, and
+  // setA-re-again still L0-contentHash-dedups onto the first setA checkpoint.
+  // The TrigramEmbedder otherwise matches on shared structural trigrams
+  // ("— step N" / "Edit"), collapsing setB onto setA. Harmless for the REPLAY
+  // test (pure replay, no dedup reliance).
+  process.env.MEGACOMPACT_L1_ENABLED = "false";
+  process.env.MEGACOMPACT_L2_ENABLED = "false";
+  delete process.env.MEGACOMPACT_LEGACY_DURABLE_TRIM;
+
+  // Mutable context-usage so tests can drive re-compact on the TOKEN basis by
+  // raising `tokens` while keeping `percent` null (→ token gate + token
+  // grewEnough path in context-handler.ts). The REPLAY test keeps percent=100 so
+  // the percent-basis grewEnough (>=10) never trips (no re-compact → pure replay).
+  const usage = { tokens: 200000, contextWindow: 200000, percent: 100 as number | null };
+
+  const handlers: Record<string, Function> = {};
+  const compactCalls: any[] = [];
+
+  function msg(role: string, text: string, toolName?: string): AgentMessage {
+    if (role === "assistant" && toolName) {
+      return { role: "assistant", content: [{ type: "toolCall", name: toolName, id: "c1", arguments: {} }], api: "anthropic-messages", provider: "anthropic", model: "m", usage: { inputTokens: 1, outputTokens: 1, cacheReadTokens: 0, cacheWriteTokens: 0 }, stopReason: "tool_use", timestamp: 0 } as unknown as AgentMessage;
+    }
+    if (role === "toolResult" && toolName) {
+      return { role: "toolResult", content: [{ type: "text", text }], toolCallId: "c1", toolName, isError: false, timestamp: 0 } as unknown as AgentMessage;
+    }
+    return { role: "user", content: text, timestamp: 0 } as unknown as AgentMessage;
+  }
+
+  // Build a session of `n` tool-call triples tagged `tag`. Set A and B differ in
+  // content (so B never dedups against A) but A === A reproduces the same
+  // regionText → same L0 contentHash → dedup onto the first A checkpoint.
+  function buildSession(tag: string, n: number): AgentMessage[] {
+    const s: AgentMessage[] = [];
+    for (let i = 0; i < n; i++) {
+      s.push(msg("user", `[${tag}] we decided to use approach ${i} for module ${i}`));
+      s.push(msg("assistant", `[${tag}] edited module ${i}`, "Edit"));
+      s.push(msg("toolResult", `[${tag}] edited module ${i}`, "Edit"));
+    }
+    return s;
+  }
+
+  const toEntry = (m: AgentMessage, i: number): any => ({ type: "message", id: `e${i}`, parentId: null, timestamp: String(i), message: m });
+  const sessionManager = {
+    getSessionId: () => "sess_cache_001",
+    getEntries: () => buildSession("A", 14).map(toEntry),
+    getBranch: () => buildSession("A", 14).map(toEntry),
+  };
+
+  function makeCtx(over: Partial<any> = {}) {
+    return {
+      ui: { setStatus: () => {}, notify: () => {}, select: () => {}, confirm: async () => true, input: async () => "", setWidget: () => {} },
+      mode: "tui" as any, hasUI: true, cwd: stateDir, sessionManager,
+      modelRegistry: {} as any, model: undefined, isIdle: () => true, isProjectTrusted: () => true,
+      signal: undefined, abort: () => {}, hasPendingMessages: () => false, shutdown: () => {},
+      getContextUsage: () => ({ ...usage }),
+      compact: (opts?: any) => { compactCalls.push(opts); return undefined; },
+      getSystemPrompt: () => "system base",
+      ...over,
+    } as any;
+  }
+
+  const pi = {
+    on: (ev: string, h: Function) => { handlers[ev] = h; },
+    registerCommand: () => {}, registerTool: () => {}, registerShortcut: () => {},
+    registerFlag: () => {}, getFlag: () => undefined, registerMessageRenderer: () => {},
+    registerEntryRenderer: () => {}, sendMessage: () => {}, sendUserMessage: () => {},
+    appendEntry: () => {}, setSessionName: () => {}, getSessionName: () => undefined,
+    setLabel: () => {}, exec: async () => ({ stdout: "", stderr: "", code: 0 }),
+    getActiveTools: () => [], getAllTools: () => [], setActiveTools: () => {},
+    getCommands: () => [], setModel: async () => false, getThinkingLevel: () => "off" as any,
+    setThinkingLevel: () => {},
+  } as any;
+
+  const mod = require("./mega-compact.js") as { default: (p: any) => void };
+  mod.default(pi);
+  const { lastRuntime } = require("./mega-events.js") as { lastRuntime: any };
+
+  const fire = (ev: string, event: any, ctx: any) => handlers[ev](event, ctx);
+  return {
+    stateDir, handlers, compactCalls, fire, ctx: makeCtx, usage, buildSession,
+    runtime: lastRuntime, // MegaRuntime with diag* counters + rt + trimCache
+    // Bypass the 2s debounce so each fire proceeds without real waiting.
+    clearDebounce: () => { if (lastRuntime) lastRuntime.debounceUntil = 0; },
+  };
+}
+
+test("REPLAY: >=2 gated context events within one epoch replay verbatim (byte-identical)", async () => {
+  const h = harness();
+  const ctx = h.ctx();
+  const session = h.buildSession("A", 14);
+
+  // Fire 3 gated context events; clearDebounce between so each passes the gate.
+  // percent stays 100 → percent-basis grewEnough (>=10) never trips → pure replay.
+  h.clearDebounce();
+  const r1 = await h.fire("context", { type: "context", messages: session }, ctx);
+  h.clearDebounce();
+  const r2 = await h.fire("context", { type: "context", messages: session }, ctx);
+  h.clearDebounce();
+  const r3 = await h.fire("context", { type: "context", messages: session }, ctx);
+
+  const rt = h.runtime;
+  assert.ok(rt.diagLiveTrimFires >= 1, "fresh trim fired on first event");
+  assert.ok(rt.diagLiveTrimReplays >= 2, `replay fired >=2 (got ${rt.diagLiveTrimReplays})`);
+  // byte-identical (stable KV-cache prefix) across replays
+  assert.deepEqual(r2?.messages, r3?.messages, "replay messages byte-identical across replays");
+  // replay matches the fresh-trim view (shallow-copy preserves content)
+  assert.deepEqual(r1?.messages, r2?.messages, "replay matches fresh-trim view (stable prefix)");
+});
+
+test("DEDUP: re-compact that dedups onto a DIFFERENT checkpoint still replays next (P2 fix)", async () => {
+  const h = harness();
+  // Token-basis growth path: percent null → token gate + token grewEnough
+  // (currentTokens - trimCache.ctxTokens >= effectiveThreshold * 0.5 = 25).
+  h.usage.percent = null;
+  h.usage.tokens = 200000;
+  const ctx = h.ctx();
+  const setA = h.buildSession("A", 14);
+  const setB = h.buildSession("B", 14); // different content, same length
+  const rt = h.runtime;
+
+  // 1) Fresh trim on setA → genuinely new checkpoint cp_A. lastCheckpointId = cp_A.
+  h.clearDebounce();
+  await h.fire("context", { type: "context", messages: setA }, ctx);
+  const cpA = rt.rt.lastCheckpointId;
+  assert.ok(cpA, "cp_A created on fresh trim");
+  assert.equal(rt.diagLiveTrimFires, 1, "first fire was a fresh trim");
+
+  // 2) Re-compact on setB (grew tokens) → genuinely new checkpoint cp_B (not deduped).
+  h.usage.tokens = 200100; // grew 100 >= 25
+  h.clearDebounce();
+  await h.fire("context", { type: "context", messages: setB }, ctx);
+  const cpB = rt.rt.lastCheckpointId;
+  assert.notEqual(cpB, cpA, "cp_B is a different, genuinely new checkpoint");
+  assert.equal(rt.rt.dedupSkips, 0, "setB did not dedup (different vocabulary, fuzzy tiers off)");
+
+  // 3) Re-compact on setA AGAIN (grew tokens) → L0 contentHash dedup onto cp_A.
+  //    result.checkpointId = cp_A (!= lastCheckpointId cp_B); lastCheckpointId is
+  //    NOT updated on a dedup (compact.ts:100-104), so it stays cp_B. With the
+  //    fix, trimCache.checkpointId is keyed on lastCheckpointId (cp_B), NOT the
+  //    dedup-volatile result.checkpointId (cp_A).
+  h.usage.tokens = 200200; // grew 100 >= 25
+  h.clearDebounce();
+  await h.fire("context", { type: "context", messages: setA }, ctx);
+  assert.equal(rt.rt.lastCheckpointId, cpB, "dedup did NOT bump lastCheckpointId (still cp_B)");
+  assert.ok(rt.rt.dedupSkips >= 1, "setA re-compact deduped onto an existing checkpoint");
+  // The P2 invariant: the cache key must equal the stable epoch signal.
+  assert.equal(rt.trimCache?.checkpointId, rt.rt.lastCheckpointId,
+    "trimCache.checkpointId keyed on lastCheckpointId (P2 fix), not dedup-volatile result.checkpointId");
+
+  // 4) Next gated event (no growth) MUST replay instead of re-running runCompact.
+  //    Without the fix, trimCache.checkpointId (cp_A) != lastCheckpointId (cp_B)
+  //    → the replay condition is false → runCompact re-runs every fire → the
+  //    thrash silently persists in that path (the audit's finding).
+  const replaysBefore = rt.diagLiveTrimReplays;
+  h.usage.tokens = 200200; // no growth → replay
+  h.clearDebounce();
+  await h.fire("context", { type: "context", messages: setA }, ctx);
+  assert.ok(rt.diagLiveTrimReplays > replaysBefore,
+    `replay fired after dedup-onto-different-checkpoint (got ${rt.diagLiveTrimReplays}, was ${replaysBefore})`);
+});
+
+test("cleanup", async () => {
+  await closeVectorIndex();
+  rmSync(baseTmp, { recursive: true, force: true });
+});

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/context-handler.ts

@@ -184,7 +184,9 @@ export function registerContextHandler(
 				runtime.diagLiveTrimFires++; // trim view returned this call (replay counts as a fire)
 				runtime.diagLiveTrimReplays++;
 				runtime.snapshot(ctx);
-				return { messages: [runtime.trimCache.summaryAgentMsg, ...recent] };
+				// v0.8.7: shallow-copy the cached summary so pi's transformContext can't
+				// mutate the shared reference across replays (audit P3).
+				return { messages: [{ ...runtime.trimCache.summaryAgentMsg }, ...recent] };
 			}
 			// else: context grew enough → fall through to re-compact (cache is stale)
 		}
@@ -308,7 +310,21 @@ export function registerContextHandler(
 			// replay it verbatim (stabilizing the KV-cache prefix) instead of
 			// regenerating a fresh summary + sentinel every fire.
 			runtime.trimCache = {
-				checkpointId: ran.result.checkpointId ?? `epoch-${runtime.rt.lastCompactAt ?? Date.now()}`,
+				// v0.8.7: key the replay cache on the STABLE epoch signal
+				// (rt.lastCheckpointId) instead of ran.result.checkpointId, which is
+				// dedup-volatile: on a re-compact that dedups onto a DIFFERENT existing
+				// checkpoint, result.checkpointId is the matched id (engine.ts:188) while
+				// lastCheckpointId is only updated on a genuinely new checkpoint
+				// (compact.ts:100-104). Keying on result.checkpointId would make
+				// trimCache.checkpointId != rt.lastCheckpointId forever after that
+				// dedup fire, disabling replay for the rest of the epoch (the
+				// alternating cache-miss that 0.8.6 meant to fix). Prefer the stable
+				// signal; fall back to result.checkpointId then the epoch timestamp
+				// only for the no-checkpoint edge case.
+				checkpointId:
+					runtime.rt.lastCheckpointId ??
+					ran.result.checkpointId ??
+					`epoch-${runtime.rt.lastCompactAt ?? Date.now()}`,
 				cut,
 				summaryAgentMsg,
 				ctxPct: pct ?? null,

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.6",
+  "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"));
+	});
+});