pi-mega-compact 0.11.4 → 0.11.6

package/extensions/dashboard-server/api-contracts/setup.ts

@@ -0,0 +1,80 @@
+/**
+ * api-contracts/setup.ts — Setup wizard API response types.
+ *
+ * Types for the /api/setup-status and /api/setup-detect endpoints used
+ * by the /megasetup command and dashboard Setup tab.
+ *
+ * PREVENT-PI-004: type definitions only, no network code.
+ * PREVENT-011: no `any` type — all types are explicit.
+ */
+
+/**
+ * Response for GET /api/setup-status.
+ * Returns the current embedder configuration read from the environment.
+ */
+export interface SetupStatusResponse {
+  /** Which embedder implementation is currently active. */
+  readonly currentEmbedder: "trigram" | "http" | "minilm" | "unknown";
+  /** The embedding URL if httpEmbedder is active, otherwise null. */
+  readonly embeddingUrl: string | null;
+  /** The MEGACOMPACT_EMBED_CACHE value (number as string), or null. */
+  readonly embedCache: string | null;
+  /** Whether MEGACOMPACT_MINILM is set to a truthy value. */
+  readonly minilm: boolean;
+}
+
+/**
+ * A single detection result for one embedder backend.
+ */
+export interface DetectResult {
+  readonly installed: boolean;
+  readonly detail: string | null;
+}
+
+/**
+ * Ollama-specific detection result with model listing and runtime status.
+ */
+export interface OllamaDetectResult extends DetectResult {
+  readonly installed: boolean;
+  readonly models: string[];
+  readonly running: boolean;
+  readonly detail: string | null;
+}
+
+/**
+ * Response for GET /api/setup-detect.
+ * Best-effort detection of local embedder backends available on the machine.
+ * All fields are best-effort; failures are non-fatal.
+ */
+export interface SetupDetectResponse {
+  /** Ollama detection: installed, available models, whether the server is running. */
+  readonly ollama: OllamaDetectResult | null;
+  /** llama.cpp / llama-server detection on PATH. */
+  readonly llamaCpp: DetectResult | null;
+  /** ONNX runtime detection (onnxruntime-node in node_modules). */
+  readonly onnx: DetectResult | null;
+  /** Error message if detection itself failed, or null. */
+  readonly error: string | null;
+}
+
+/** Request body for POST /api/setup-configure. */
+export interface SetupConfigureRequest {
+  /** Which embedder to configure. "trigram" clears the URL (uses built-in). */
+  readonly embedder: "ollama" | "llama" | "trigram";
+  /** Optional override URL (for non-default Ollama ports or llama.cpp). */
+  readonly url?: string;
+}
+
+/** Response for POST /api/setup-configure. */
+export interface SetupConfigureResponse {
+  /** The embedder that was configured. */
+  readonly embedder: string;
+  /** The URL that was written (null for trigram). */
+  readonly url: string | null;
+  /** Path to the .mega-compact.env file that was written. */
+  readonly envPath: string;
+  /** Whether the user needs to restart pi to activate. */
+  readonly restartRequired: boolean;
+  /** The already-active embedder, if the new config matches (no restart needed). */
+  readonly alreadyActive: boolean;
+}

package/extensions/dashboard-server/index-reader.ts

@@ -16,138 +16,155 @@ import { DatabaseSync } from "node:sqlite";
 import type { IndexRepo, IndexIndex } from "./types.js";
 
 export function getIndexDir(): string {
-  const override = process.env.MEGACOMPACT_INDEX_DIR;
-  if (override && override.trim() !== "") return override;
-  try {
-    return join(homedir(), ".mega-compact-index");
-  } catch {
-    return join("/tmp", ".mega-compact-index");
-  }
+	const override = process.env.MEGACOMPACT_INDEX_DIR;
+	if (override && override.trim() !== "") return override;
+	try {
+		return join(homedir(), ".mega-compact-index");
+	} catch {
+		return join("/tmp", ".mega-compact-index");
+	}
 }
 
 /** Read the machine-wide repo registry from SQLite (read-only, single shot). */
 export function readIndex(): IndexIndex | null {
-  const indexPath = join(getIndexDir(), "index.sqlite");
-  if (!existsSync(indexPath)) return null;
-  let db: DatabaseSync | undefined;
-  try {
-    // Read-only + immutable WAL so a concurrent writer's WAL never blocks us.
-    db = new DatabaseSync(indexPath, { readOnly: true });
-    db.exec("PRAGMA journal_mode = WAL");
-    const rows = db
-      .prepare("SELECT * FROM repo_registry ORDER BY last_seen DESC")
-      .all() as Record<string, unknown>[];
-    const mapped: IndexRepo[] = rows.map((r) => ({
-      repoRoot: String(r.repo_root ?? ""),
-      displayName: String(r.display_name ?? ""),
-      stateDir: String(r.state_dir ?? ""),
-      checkpointCount: Number(r.checkpoint_count ?? 0),
-      tokensSaved: Number(r.tokens_saved ?? 0),
-      compressedOriginalBytes: Number(r.compressed_original_bytes ?? 0),
-      lastCompactedAt: (r.last_compacted_at as number | null) ?? null,
-      provider: (r.provider as string | null) ?? null,
-      providerName: (r.provider_name as string | null) ?? null,
-      modelName: (r.model_name as string | null) ?? null,
-      inputRate: (r.input_rate as number | null) ?? null,
-      outputRate: (r.output_rate as number | null) ?? null,
-      lastSeen: Number(r.last_seen ?? 0),
-      // Defaults — enriched below from each repo's own store.
-      tokensKept: 0,
-      tokensDropped: 0,
-      sessions: 0,
-      contextWindow: null,
-      maxTokens: null,
-      reasoning: null,
-      providerCachePct: null,
-      providerCacheRead: null,
-      providerCacheWrite: null,
-    }));
-    // Enrich each repo with per-store token + model detail read directly via
-    // node:sqlite (same zero-dependency invariant as readIndex; no store graph
-    // import). Best-effort: a missing/corrupt store degrades to the defaults
-    // above so the dashboard never fails to render.
-    for (const repo of mapped) {
-      try {
-        const storePath = join(repo.stateDir, "sqlite.db");
-        if (existsSync(storePath)) {
-          const sdb = new DatabaseSync(storePath, { readOnly: true });
-          try {
-            const tok = sdb
-              .prepare(
-                `SELECT COALESCE(SUM(token_estimate),0) AS kept,
+	const indexPath = join(getIndexDir(), "index.sqlite");
+	if (!existsSync(indexPath)) return null;
+	let db: DatabaseSync | undefined;
+	try {
+		// Read-only + immutable WAL so a concurrent writer's WAL never blocks us.
+		db = new DatabaseSync(indexPath, { readOnly: true });
+		db.exec("PRAGMA journal_mode = WAL");
+		const rows = db
+			.prepare("SELECT * FROM repo_registry ORDER BY last_seen DESC")
+			.all() as Record<string, unknown>[];
+		const mapped: IndexRepo[] = rows.map((r) => ({
+			repoRoot: String(r.repo_root ?? ""),
+			displayName: String(r.display_name ?? ""),
+			stateDir: String(r.state_dir ?? ""),
+			checkpointCount: Number(r.checkpoint_count ?? 0),
+			tokensSaved: Number(r.tokens_saved ?? 0),
+			compressedOriginalBytes: Number(r.compressed_original_bytes ?? 0),
+			lastCompactedAt: (r.last_compacted_at as number | null) ?? null,
+			provider: (r.provider as string | null) ?? null,
+			providerName: (r.provider_name as string | null) ?? null,
+			modelName: (r.model_name as string | null) ?? null,
+			inputRate: (r.input_rate as number | null) ?? null,
+			outputRate: (r.output_rate as number | null) ?? null,
+			lastSeen: Number(r.last_seen ?? 0),
+			// Defaults — enriched below from each repo's own store.
+			tokensKept: 0,
+			tokensDropped: 0,
+			sessions: 0,
+			contextWindow: null,
+			maxTokens: null,
+			reasoning: null,
+			providerCachePct: null,
+			providerCacheRead: null,
+			providerCacheWrite: null,
+		}));
+		// Enrich each repo with per-store token + model detail read directly via
+		// node:sqlite (same zero-dependency invariant as readIndex; no store graph
+		// import). Best-effort: a missing/corrupt store degrades to the defaults
+		// above so the dashboard never fails to render.
+		for (const repo of mapped) {
+			try {
+				const storePath = join(repo.stateDir, "sqlite.db");
+				if (existsSync(storePath)) {
+					const sdb = new DatabaseSync(storePath, { readOnly: true });
+					try {
+						const tok = sdb
+							.prepare(
+								`SELECT COALESCE(SUM(token_estimate),0) AS kept,
                         COALESCE(SUM(original_token_estimate),0) AS dropped,
                         COUNT(DISTINCT session_id) AS sess
                  FROM context_chunks WHERE dedup_status != 'removed'`,
-              )
-              .get() as { kept: number; dropped: number; sess: number };
-            repo.tokensKept = Number(tok.kept ?? 0);
-            repo.tokensDropped = Number(tok.dropped ?? 0);
-            repo.sessions = Number(tok.sess ?? 0);
-            const mrow = sdb
-              .prepare(
-                `SELECT context_window, max_tokens, reasoning
+							)
+							.get() as { kept: number; dropped: number; sess: number };
+						repo.tokensKept = Number(tok.kept ?? 0);
+						repo.tokensDropped = Number(tok.dropped ?? 0);
+						repo.sessions = Number(tok.sess ?? 0);
+						const mrow = sdb
+							.prepare(
+								`SELECT context_window, max_tokens, reasoning
                  FROM model_snapshots ORDER BY captured_at DESC LIMIT 1`,
-              )
-              .get() as { context_window: number; max_tokens: number; reasoning: number } | undefined;
-            if (mrow) {
-              repo.contextWindow = Number(mrow.context_window ?? 0) || null;
-              repo.maxTokens = Number(mrow.max_tokens ?? 0) || null;
-              repo.reasoning = Number(mrow.reasoning ?? 0) === 1;
-            }
-            // Provider prompt-cache stats (E.3)
-            try {
-              const pRow = sdb
-                .prepare(
-                  `SELECT
+							)
+							.get() as
+							| {
+									context_window: number;
+									max_tokens: number;
+									reasoning: number;
+							  }
+							| undefined;
+						if (mrow) {
+							repo.contextWindow = Number(mrow.context_window ?? 0) || null;
+							repo.maxTokens = Number(mrow.max_tokens ?? 0) || null;
+							repo.reasoning = Number(mrow.reasoning ?? 0) === 1;
+						}
+						// Provider prompt-cache stats (E.3)
+						try {
+							const pRow = sdb
+								.prepare(
+									`SELECT
                     SUM(cache_read) AS totalRead,
                     SUM(cache_write) AS totalWrite,
                     SUM(cache_read + cache_write) * 1.0 / MAX(SUM(cache_read + cache_write + tokens_in), 1) AS hitPct
                    FROM perf_samples
                    WHERE cache_read > 0 OR cache_write > 0`,
-                )
-                .get() as { totalRead: number; totalWrite: number; hitPct: number } | undefined;
-              if (pRow && pRow.totalRead > 0) {
-                repo.providerCacheRead = Number(pRow.totalRead);
-                repo.providerCacheWrite = Number(pRow.totalWrite);
-                repo.providerCachePct = Number((pRow.hitPct * 100).toFixed(1));
-              }
-            } catch {
-              /* best-effort — perf_samples may not exist */
-            }
-          } finally {
-            sdb.close();
-          }
-        }
-      } catch {
-        /* best-effort — keep the defaults */
-      }
-    }
-    // Defensive display hygiene (belt-and-suspenders — the real fix is that
-    // tests now isolate via MEGACOMPACT_INDEX_DIR): drop transient test/temp
-    // paths that should never have been real repos, and collapse duplicate
-    // display names to the most-recently-seen row (rows are last_seen DESC, so
-    // the first occurrence wins). Keeps the All-repos list readable.
-    const isTransient = (p: string) =>
-      /^\/tmp\//.test(p) || /^\/private\/tmp\//.test(p) || /^\/var\/folders\//.test(p) ||
-      /\/mc-(ext|e2e|resume|recall)-/.test(p);
-    const seenName = new Set<string>();
-    const repos: IndexRepo[] = [];
-    for (const r of mapped) {
-      if (isTransient(r.repoRoot)) continue;
-      if (seenName.has(r.displayName)) continue;
-      seenName.add(r.displayName);
-      repos.push(r);
-    }
-    const summary = {
-      totalRepos: repos.length,
-      totalCheckpoints: repos.reduce((a, r) => a + r.checkpointCount, 0),
-      totalTokensSaved: repos.reduce((a, r) => a + r.tokensSaved, 0),
-      totalCompressedOriginalBytes: repos.reduce((a, r) => a + r.compressedOriginalBytes, 0),
-    };
-    return { updatedAt: new Date().toISOString(), summary, repos };
-  } catch {
-    return null;
-  } finally {
-    try { db?.close(); } catch { /* ignore */ }
-  }
+								)
+								.get() as
+								| { totalRead: number; totalWrite: number; hitPct: number }
+								| undefined;
+							if (pRow && pRow.totalRead > 0) {
+								repo.providerCacheRead = Number(pRow.totalRead);
+								repo.providerCacheWrite = Number(pRow.totalWrite);
+								repo.providerCachePct = Number((pRow.hitPct * 100).toFixed(1));
+							}
+						} catch {
+							/* best-effort — perf_samples may not exist */
+						}
+					} finally {
+						sdb.close();
+					}
+				}
+			} catch {
+				/* best-effort — keep the defaults */
+			}
+		}
+		// Defensive display hygiene (belt-and-suspenders — the real fix is that
+		// tests now isolate via MEGACOMPACT_INDEX_DIR): drop transient test/temp
+		// paths that should never have been real repos, and collapse duplicate
+		// display names to the most-recently-seen row (rows are last_seen DESC, so
+		// the first occurrence wins). Keeps the All-repos list readable.
+		const isTransient = (p: string) =>
+			/^\/tmp\//.test(p) ||
+			/^\/private\/tmp\//.test(p) ||
+			/^\/var\/folders\//.test(p) ||
+			/\/mc-(ext|e2e|resume|recall)-/.test(p);
+		const seenName = new Set<string>();
+		const repos: IndexRepo[] = [];
+		for (const r of mapped) {
+			if (isTransient(r.repoRoot)) continue;
+			if (seenName.has(r.displayName)) continue;
+			seenName.add(r.displayName);
+			repos.push(r);
+		}
+		const summary = {
+			totalRepos: repos.length,
+			totalCheckpoints: repos.reduce((a, r) => a + r.checkpointCount, 0),
+			totalTokensSaved: repos.reduce((a, r) => a + r.tokensSaved, 0),
+			totalCompressedOriginalBytes: repos.reduce(
+				(a, r) => a + r.compressedOriginalBytes,
+				0,
+			),
+		};
+		return { updatedAt: new Date().toISOString(), summary, repos };
+	} catch {
+		return null;
+	} finally {
+		try {
+			db?.close();
+		} catch {
+			/* ignore */
+		}
+	}
 }

package/extensions/dashboard-server/routes-cache.ts

@@ -3,6 +3,7 @@
  *
  * GET /api/provider-cache — Lifetime provider prompt cache hit-rate aggregates
  * plus dollar savings estimate (priced from latest model snapshot).
+ * Accepts optional ?minutes=N, ?since=<epoch-ms>, ?until=<epoch-ms> (S53A).
  *
  * Guardrails: PREVENT-PI-004 (loopback-only), PREVENT-001 (null-safe JSON parse),
  * PREVENT-002 (parameterized SQL). Loopback-only localhost dashboard endpoint.
@@ -24,97 +25,207 @@ export function handleProviderCache(
 	ctx: RouteContext,
 ): boolean {
 	if (!req.url?.startsWith("/api/provider-cache")) return false;
-
-	const { stateDir } = ctx;
-
-	// /api/provider-cache — GET returns lifetime provider prompt cache aggregates
-	// from perf_samples (cache_hit_pct rows with meta JSON) plus an optional
-	// dollar savings estimate priced from the latest model snapshot. The dashboard
-	// server is a detached child with no MegaRuntime ref, so it reads via a
-	// require()'d sqlite helper (same pattern as /api/perf). Non-GET → 405.
-	// PREVENT-PI-004: loopback.
-	const pfReq = createRequire(import.meta.url);
-	const { readProviderCacheLifetime, latestModelSnapshot } = pfReq(
-		"../../src/store/sqlite.js",
-	) as typeof import("../../src/store/sqlite.js");
-	if (req.method !== "GET") {
-		// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
-		res.writeHead(405, { "Content-Type": "application/json" });
-		res.end(JSON.stringify({ error: "method_not_allowed" }));
-		return true;
-	}
 	try {
-		const lifetime = readProviderCacheLifetime(stateDir); // guardrails-allow PREVENT-PI-004: local SQLite read (loopback dashboard)
+		const stateDir = ctx.stateDir;
+		// PREVENT-PI-004: loopback.
+		const pfReq = createRequire(import.meta.url);
+		const { readProviderCacheLifetime, readProviderCacheWindow, latestModelSnapshot } = pfReq(
+			"../../src/store/sqlite.js",
+		) as typeof import("../../src/store/sqlite.js");
+		if (req.method !== "GET") {
+			// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+			res.writeHead(405, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({ error: "method_not_allowed" }));
+			return true;
+		}
 
-		// D3: compute dollar savings from the latest model snapshot.  Null-safe:
-		// when no snapshot or zero input rate, savings stays null (UI shows "—").
-		let savings: {
-			cacheReadSaved: number;
-			cacheWriteCost: number;
-			netSaved: number;
-			model: string;
-			inputRate: number;
-		} | null = null;
-		try {
-			const snap = latestModelSnapshot(stateDir); // guardrails-allow PREVENT-PI-004: local SQLite read (loopback dashboard)
-			if (snap && snap.inputRate > 0) {
-				const s = computeCacheSavings(
-					lifetime.totalCacheRead,
-					lifetime.totalCacheWrite,
-					snap.inputRate,
-				);
-				savings = {
-					cacheReadSaved: s.cacheReadSaved,
-					cacheWriteCost: s.cacheWriteCost,
-					netSaved: s.netSaved,
-					model: snap.modelName ?? snap.modelId ?? "unknown",
-					inputRate: snap.inputRate,
-				};
+		// Parse query params: ?minutes=N | ?since=&until= (mutually exclusive).
+		let windowMinutes: number | null = null;
+		let sinceTs = 0;
+		let untilTs = 0;
+		if (req.url) {
+			const qIdx = req.url.indexOf("?");
+			if (qIdx !== -1) {
+				const params = new URLSearchParams(req.url.slice(qIdx));
+				const m = params.get("minutes");
+				if (m != null) {
+					const n = parseInt(m, 10);
+					if (Number.isFinite(n) && n > 0 && String(n) === m.trim()) {
+						windowMinutes = n;
+					}
+				}
+				// S53A: ?since=&until= epoch-ms timestamps.
+				const s = params.get("since");
+				const u = params.get("until");
+				if (s != null) {
+					const sn = Number(s);
+					if (Number.isFinite(sn) && sn >= 0) sinceTs = sn;
+				}
+				if (u != null) {
+					const un = Number(u);
+					if (Number.isFinite(un) && un > 0) untilTs = un;
+				}
 			}
+		}
+
+		// S53A: read prefix_break samples in the same window as the aggregates.
+		// Import lazily to avoid a circular dependency in the test harness.
+		let prefixBreaks: Array<{
+			id: number;
+			ts: number;
+			cause: "recall" | "compaction" | "inject" | "other";
+			confidence: number;
+			prevHitPct: number;
+			currHitPct: number;
+			breakAt: number;
+		}> = [];
+		try {
+			// guardrails-allow PREVENT-PI-004: local SQLite read (loopback dashboard)
+			const { readPrefixBreaks } = pfReq(
+				"../../src/store/sqlite/perf-samples.js",
+			) as typeof import("../../src/store/sqlite/perf-samples.js");
+			// When ?since=&until= is used, pass those directly; otherwise derive
+			// from windowMinutes or 0 (no bounds = lifetime).
+			const pSince = sinceTs > 0 ? sinceTs : (windowMinutes != null ? Date.now() - windowMinutes * 60_000 : 0);
+			const pUntil = untilTs > 0 ? untilTs : (windowMinutes != null ? Date.now() : 0);
+			const rows = readPrefixBreaks(stateDir, pSince, pUntil);
+			prefixBreaks = rows.map((r) => ({
+				id: r.id,
+				ts: r.ts,
+				cause: r.meta.cause,
+				confidence: r.meta.confidence,
+				prevHitPct: r.meta.prevHitPct,
+				currHitPct: r.meta.currHitPct,
+				breakAt: r.meta.breakAt,
+			}));
 		} catch {
-			/* pricing unavailable — savings stays null */
+			/* prefix-break read unavailable — response still returns empty array */
 		}
 
-		const body: {
-			cache: {
-				avgHitPct: number;
-				turnCount: number;
-				totalCacheRead: number;
-				totalCacheWrite: number;
-				totalInput: number;
-				firstTurnAt: string | null;
-				latestTurnAt: string | null;
-			};
-			savings: {
+		try {
+			const lifetime = windowMinutes != null
+				? readProviderCacheWindow(stateDir, windowMinutes)
+				: readProviderCacheLifetime(stateDir); // guardrails-allow PREVENT-PI-004: local SQLite read (loopback dashboard)
+
+			// D3: compute dollar savings from the latest model snapshot.  Null-safe:
+			// when no snapshot or zero input rate, savings stays null (UI shows "—").
+			let savings: {
 				cacheReadSaved: number;
 				cacheWriteCost: number;
 				netSaved: number;
 				model: string;
 				inputRate: number;
-			} | null;
-			updatedAt: string;
-		} = {
-			cache: {
-				avgHitPct: lifetime.avgHitPct,
-				turnCount: lifetime.sampleCount,
-				totalCacheRead: lifetime.totalCacheRead,
-				totalCacheWrite: lifetime.totalCacheWrite,
-				totalInput: lifetime.totalInput,
-				firstTurnAt: lifetime.firstSampleAt,
-				latestTurnAt: lifetime.latestSampleAt,
-			},
-			savings,
-			updatedAt: new Date().toISOString(),
-		};
-		// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+			} | null = null;
+			try {
+				const snap = latestModelSnapshot(stateDir); // guardrails-allow PREVENT-PI-004: local SQLite read (loopback dashboard)
+				if (snap && snap.inputRate > 0) {
+					const s = computeCacheSavings(
+						lifetime.totalCacheRead,
+						lifetime.totalCacheWrite,
+						snap.inputRate,
+					);
+					savings = {
+						cacheReadSaved: s.cacheReadSaved,
+						cacheWriteCost: s.cacheWriteCost,
+						netSaved: s.netSaved,
+						model: snap.modelName ?? snap.modelId ?? "unknown",
+						inputRate: snap.inputRate,
+					};
+				}
+			} catch {
+				/* pricing unavailable — savings stays null */
+			}
+
+			const body: {
+				cache: {
+					avgHitPct: number;
+					turnCount: number;
+					totalCacheRead: number;
+					totalCacheWrite: number;
+					totalInput: number;
+					firstTurnAt: string | null;
+					latestTurnAt: string | null;
+					byModel: Array<{
+						model: string;
+						hitPct: number;
+						totalCacheRead: number;
+						totalCacheWrite: number;
+						sampleCount: number;
+					}>;
+				};
+				savings: {
+					cacheReadSaved: number;
+					cacheWriteCost: number;
+					netSaved: number;
+					model: string;
+					inputRate: number;
+				} | null;
+				updatedAt: string;
+				windowMinutes?: number | null;
+				prefixBreaks: typeof prefixBreaks;
+			} = {
+				cache: {
+					avgHitPct: lifetime.avgHitPct,
+					turnCount: lifetime.sampleCount,
+					totalCacheRead: lifetime.totalCacheRead,
+					totalCacheWrite: lifetime.totalCacheWrite,
+					totalInput: lifetime.totalInput,
+					firstTurnAt: lifetime.firstSampleAt,
+					latestTurnAt: lifetime.latestSampleAt,
+					byModel: lifetime.byModel,
+				},
+				savings,
+				updatedAt: new Date().toISOString(),
+				windowMinutes,
+				prefixBreaks,
+			};
+			// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+			res.writeHead(200, { "Content-Type": "application/json" });
+			res.end(JSON.stringify(body));
+		} catch (e) {
+			// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+			res.writeHead(500, { "Content-Type": "application/json" });
+			res.end(
+				JSON.stringify({
+					error: "provider_cache_unavailable",
+					detail: String(e),
+				}),
+			);
+		}
+		return true;
+	} catch {
+		return false;
+	}
+}
+// ---------------------------------------------------------------------------
+// handleCacheStripes — "GET /api/cache-stripes"
+// ---------------------------------------------------------------------------
+
+export function handleCacheStripes(
+	req: IncomingMessage,
+	res: ServerResponse,
+	ctx: RouteContext,
+): boolean {
+	if (!req.url?.startsWith("/api/cache-stripes")) return false;
+	if (req.method !== "GET") {
+		res.writeHead(405, { "Content-Type": "application/json" });
+		res.end(JSON.stringify({ error: "method_not_allowed" }));
+		return true;
+	}
+	try {
+		const stateDir = ctx.stateDir;
+		const pfReq = createRequire(import.meta.url);
+		const { readCacheStripes } = pfReq(
+			"../../src/store/sqlite/cache-stripes.js",
+		) as typeof import("../../src/store/sqlite/cache-stripes.js");
+		const result = readCacheStripes(stateDir);
 		res.writeHead(200, { "Content-Type": "application/json" });
-		res.end(JSON.stringify(body));
+		res.end(JSON.stringify(result));
 	} catch (e) {
-		// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
 		res.writeHead(500, { "Content-Type": "application/json" });
 		res.end(
 			JSON.stringify({
-				error: "provider_cache_unavailable",
+				error: "cache_stripes_unavailable",
 				detail: String(e),
 			}),
 		);

package/extensions/dashboard-server/routes-game.ts

@@ -307,6 +307,9 @@ export function handlePerf(
 					avg: avg(get("cache_hit_pct")),
 					latest: latest(get("cache_hit_pct")),
 					n: get("cache_hit_pct").length,
+					samples: rows
+						.filter((r) => r.kind === "cache_hit_pct")
+						.map((r) => ({ pct: r.value, ts: r.ts })),
 				},
 				db_recompute_ms: {
 					p50: pct(get("db_recompute_ms"), 50),