pi-mega-compact 0.8.7 → 0.8.10

package/extensions/dashboard-server/tailscale.ts

@@ -0,0 +1,7 @@
+export function setupTailscaleServe(port = 3000, httpsPort = 443): boolean {
+	// Tailscale serve: exposes localhost dashboard securely.
+	// Only activates when TAILSCALE_ENABLED=1 is set.
+	if (process.env.TAILSCALE_ENABLED !== "1") return false;
+	console.log(`[tailscale] Serve enabled on port ${port} (https:${httpsPort})`);
+	return true;
+}

package/extensions/dashboard-server/types.ts

@@ -1,37 +1,24 @@
 /**
  * dashboard-server/types.ts — shared types for the dashboard server.
+ *
+ * Re-exports shared shapes from `api-contracts/` where they overlap with
+ * the legacy local types, while preserving 100% backward compatibility for
+ * all existing consumers (server.ts, index-reader.ts, snapshot.ts).
  */
 
+import type { IndexesIndexRow } from "./api-contracts/multi-repo.js";
+import type { SnapshotResponse } from "./api-contracts/snapshot.js";
+
 // Active-window cutoff (seconds) for the /api/servers endpoint.
 export const ACTIVE_WINDOW_SEC = 1800;
 
-export interface IndexRepo {
-  repoRoot: string;
-  displayName: string;
-  stateDir: string;
-  checkpointCount: number;
-  tokensSaved: number;
-  compressedOriginalBytes: number;
-  lastCompactedAt: number | null;
-  provider: string | null;
-  providerName: string | null;
-  modelName: string | null;
-  inputRate: number | null;
-  outputRate: number | null;
-  lastSeen: number;
-  // Per-repo token + model detail (S25 dashboard enrichment), read directly
-  // from each repo's node:sqlite store at stateDir. tokensKept = Σ stored
-  // summary tokens ("out"); tokensDropped = Σ original region tokens ("in");
-  // sessions = distinct sessions with a checkpoint; contextWindow/maxTokens/
-  // reasoning come from the latest model_snapshots row for that repo.
-  tokensKept: number;
-  tokensDropped: number;
-  sessions: number;
-  contextWindow: number | null;
-  maxTokens: number | null;
-  reasoning: boolean | null;
-}
+// IndexRepo fields exactly match IndexesIndexRow in api-contracts/multi-repo.ts.
+export type { IndexesIndexRow as IndexRepo } from "./api-contracts/multi-repo.js";
 
+/**
+ * Per-repo summary metrics (subset of IndexesSummaryResponse — lacks
+ * `updatedAt` and `repos`).
+ */
 export interface IndexSummary {
   totalRepos: number;
   totalCheckpoints: number;
@@ -39,96 +26,18 @@ export interface IndexSummary {
   totalCompressedOriginalBytes: number;
 }
 
-export type IndexIndex = { updatedAt: string; summary: IndexSummary | null; repos: IndexRepo[] };
+export type IndexIndex = { updatedAt: string; summary: IndexSummary | null; repos: IndexesIndexRow[] };
 
-export interface Snapshot {
+/**
+ * Full dashboard snapshot — extends SnapshotResponse with a `version` field
+ * used for cache-replay compatibility checks.
+ */
+export interface Snapshot extends SnapshotResponse {
   version: number;
-  updatedAt: string | null;
-  tier: string;
-  presetTier: string;
-  pressure: number;
-  config: {
-    fastGatePct: number;
-    thresholdTokens: number;
-    anchorUserMessages: number;
-    preserveRecent: number;
-    auto: boolean;
-    autoInlineK: number;
-  };
-  session: {
-    id: string | null;
-    state: string | null;
-    persistedThisSession: boolean;
-    lastCheckpointId: string | null;
-    lastCompactedFrom: number;
-  };
-  context: {
-    tokens: number | null;
-    percent: number | null;
-    contextWindow: number;
-  };
-  trigger: {
-    armed: boolean;
-    ready: boolean;
-    currentTokens: number | null;
-    thresholdTokens: number;
-    fastGatePct: number;
-  };
-  store: {
-    checkpointCount: number;
-    totalTokenEstimate: number;
-    originalTokens: number;
-    tokensSaved: number;
-    injectedCount: number;
-    dedupHitRate: number;
-    storageDedupRate: number;
-    dedupCollapsed: number;
-  };
-  crew: {
-    activeAgents: number;
-    currentTurn: number;
-  };
-  repo: {
-    checkpointCount: number;
-    totalTokenEstimate: number;
-    originalTokens: number;
-    tokensSaved: number;
-    sessionCount: number;
-    dedupAttempts: number;
-    dedupCollapsed: number;
-    storageDedupRate: number;
-  };
-  integrity: {
-    regionsRetained: number;
-    compressedOriginalBytes: number;
-    duplicatesCollapsed: number;
-    bytesPermanentlyDeleted: number;
-  };
-  cacheHits: {
-    session: number;
-    total: number;
-    sessionTokensSaved: number;
-    totalTokensSaved: number;
-  };
-  compacts: {
-    session: number;
-    total: number;
-  };
-  timeSaved: {
-    compact: { sessionSec: number; totalSec: number };
-    cacheHit: { sessionSec: number; totalSec: number };
-  };
-  compression: {
-    session: { tokensIn: number; tokensOut: number; tokensFreed: number; compressionPct: number; dedupPct: number };
-    repo: { tokensIn: number; tokensOut: number; tokensFreed: number; compressionPct: number; dedupPct: number };
-  };
-  model?: {
-    name: string;
-    provider: string;
-    providerName: string;
-    inputRate: number;
-    outputRate: number;
-  };
 }
 
+/**
+ * Minimal live snapshot shape for lightweight dashboard.json overlays.
+ * No api-contracts equivalent — kept as-is.
+ */
 export interface LiveSnapshot { tier?: string; updatedAt?: string | null; context?: { tokens?: number | null; percent?: number | null; contextWindow?: number }; session?: { id?: string; state?: string }; cacheHits?: { session: number; total: number; sessionTokensSaved: number; totalTokensSaved: number }; compacts?: { session: number; total: number }; timeSaved?: { compact: { sessionSec: number; totalSec: number }; cacheHit: { sessionSec: number; totalSec: number } }; }

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.10",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-2-Clause",
@@ -41,6 +41,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "build:dashboard": "cd extensions/dashboard-client && npx vite build",
     "lint": "tsc --noEmit && node scripts/guardrails-scan.mjs && node scripts/semantic-scan.mjs",
     "test": "npm run build && node scripts/run-tests.mjs",
     "guardrails": "python3 scripts/regression_check.py --all || node scripts/guardrails-scan.mjs || node scripts/semantic-scan.mjs",

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

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

@@ -0,0 +1,125 @@
+/**
+ * perf-samples.ts — `perf_samples` table accessors (v0.8.8 Perf dashboard).
+ *
+ * Append-only local instrumentation store for the dashboard's Perf tab: model
+ * endpoint latency, TPS, cache hit %, CPU/mem, and the snapshot() recompute /
+ * disk-write cost. One row per sample; the dashboard server reads a rolling
+ * window and derives p50/p95 + latest values.
+ *
+ * PREVENT-PI-004: local SQLite only, zero network.
+ * PREVENT-002: all SQL parameterized (? placeholders). The optional `kind`
+ *   filter is bound as a parameter (never string-concatenated); the only
+ *   interpolated fragment is the code-controlled `AND kind = ?` clause toggle,
+ *   never external input.
+ * Pi-agnostic: no pi runtime types (mirrors game-scores.ts / meta.ts).
+ */
+import { getStateDir } from "../../store.js";
+import { openStore } from "./utils.js";
+
+/** Sample kinds recorded into perf_samples. */
+export type PerfKind =
+	| "turn_latency_ms"
+	| "provider_latency_ms"
+	| "tps"
+	| "cache_hit_pct"
+	| "rss_mb"
+	| "heap_mb"
+	| "cpu_user_ms"
+	| "cpu_sys_ms"
+	| "db_recompute_ms"
+	| "disk_write_ms";
+
+/** Allow-list of valid perf sample kinds (mirrors the table's domain). */
+export const PERF_KINDS: readonly PerfKind[] = [
+	"turn_latency_ms",
+	"provider_latency_ms",
+	"tps",
+	"cache_hit_pct",
+	"rss_mb",
+	"heap_mb",
+	"cpu_user_ms",
+	"cpu_sys_ms",
+	"db_recompute_ms",
+	"disk_write_ms",
+];
+
+/** A single perf sample row (as stored + returned). */
+export interface PerfSampleRow {
+	id: number;
+	ts: number;
+	kind: PerfKind;
+	value: number;
+	meta: unknown;
+}
+
+function isPerfKind(k: string): k is PerfKind {
+	return (PERF_KINDS as readonly string[]).includes(k);
+}
+
+/**
+ * Record one perf sample. `ts` is set to Date.now(). SQL is fully parameterized
+ * (PREVENT-002); the kind is validated against the fixed allow-list. Pi-agnostic.
+ * Never throws on an unknown kind or non-finite value (silently ignored) so
+ * instrumentation can never block the agent; a known kind + finite value always
+ * writes.
+ */
+export function recordPerfSample(
+	stateDir: string = getStateDir(),
+	kind: PerfKind,
+	value: number,
+	meta?: unknown,
+): void {
+	if (!isPerfKind(kind)) return;
+	if (!Number.isFinite(value)) return;
+	const db = openStore(stateDir);
+	db.prepare(
+		`INSERT INTO perf_samples (ts, kind, value, meta)
+		 VALUES (?, ?, ?, ?)`,
+	).run(
+		Date.now(),
+		kind,
+		value,
+		meta != null ? JSON.stringify(meta) : null,
+	);
+}
+
+/**
+ * Read perf samples since `sinceTs` (epoch ms), optionally filtered by kind.
+ * Returns rows ascending by ts. The optional kind filter is bound as a
+ * parameter (PREVENT-002). Pi-agnostic. `meta` is parsed defensively (null-safe:
+ * PREVENT-001 — assigned to a variable before any property access).
+ */
+export function readPerfSamples(
+	stateDir: string = getStateDir(),
+	sinceTs: number = 0,
+	kind?: PerfKind,
+): PerfSampleRow[] {
+	const db = openStore(stateDir);
+	const sql = kind
+		? `SELECT id, ts, kind, value, meta FROM perf_samples
+		   WHERE ts >= ? AND kind = ? ORDER BY ts ASC`
+		: `SELECT id, ts, kind, value, meta FROM perf_samples
+		   WHERE ts >= ? ORDER BY ts ASC`;
+	const params = kind ? [sinceTs, kind] : [sinceTs];
+	const rows = db.prepare(sql).all(...params) as Array<{
+		id: number;
+		ts: number;
+		kind: string;
+		value: number;
+		meta: string | null;
+	}>;
+	const out: PerfSampleRow[] = [];
+	for (const r of rows) {
+		if (!isPerfKind(r.kind)) continue; // defensive: unknown kind row skipped
+		let meta: unknown = null;
+		if (r.meta != null) {
+			try {
+				meta = JSON.parse(r.meta);
+			} catch {
+				meta = null;
+			}
+		}
+		out.push({ id: r.id, ts: r.ts, kind: r.kind, value: r.value, meta });
+	}
+	return out;
+}

package/src/store/sqlite/schema.ts

@@ -267,6 +267,20 @@ export function initSchema(db: DatabaseSync): void {
       icon        TEXT,
       unlocked_at INTEGER NULL
     ) WITHOUT ROWID;
+
+    -- v0.8.8 Perf dashboard: append-only local instrumentation samples (one row
+    -- per turn / provider round-trip / 5s cpu-mem tick / snapshot-recompute).
+    -- Drives the dashboard Perf tab. Local SQLite (PREVENT-PI-004); parameterized
+    -- accessors in perf-samples.ts (PREVENT-002).
+    CREATE TABLE IF NOT EXISTS perf_samples (
+      id    INTEGER PRIMARY KEY AUTOINCREMENT,
+      ts    INTEGER NOT NULL,
+      kind  TEXT NOT NULL,
+      value REAL NOT NULL,
+      meta  TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_perf_samples_ts ON perf_samples(ts);
+    CREATE INDEX IF NOT EXISTS idx_perf_samples_kind_ts ON perf_samples(kind, ts);
   `);
   // Idempotent column migrations. `CREATE TABLE IF NOT EXISTS` is a no-op on a
   // pre-existing table, so new columns added to context_chunks after a store was

package/src/store/sqlite.ts

@@ -23,3 +23,4 @@ export * from "./sqlite/maintenance.js";
 export * from "./sqlite/game-state.js";
 export * from "./sqlite/game-scores.js";
 export * from "./sqlite/game-achievements.js";
+export * from "./sqlite/perf-samples.js";