pi-context-engine 0.6.0 → 0.7.0

package/README.md

@@ -37,7 +37,7 @@ runs fixed queries. Run it yourself; nothing is cherry-picked.
 
 ## What you get
 
-Ten tools the agent can call, plus four slash commands.
+Ten tools the agent can call, plus five slash commands.
 
 **Search**
 - **`context_search`**: hybrid vector + BM25 retrieval with confidence scores.
@@ -57,7 +57,7 @@ Ten tools the agent can call, plus four slash commands.
 - **`reindex`**: refresh a path or the whole project.
 
 Commands: `/context-index [--full] [--reset]`, `/context-status`, `/context-savings`,
-`/context-warmup`.
+`/context-warmup`, `/context-dashboard`.
 
 **Shipped guidance.** The package also injects a ~900-token guidance section
 into the system prompt while `context_search` is active: how to formulate
@@ -150,6 +150,26 @@ unchanged repo took 237 ms.
   provisioning step (a devcontainer `postCreateCommand`, a CI cache setup),
   keeping first searches fast.
 
+### Web dashboard
+
+`/context-dashboard` starts a small read-only web server inside the pi process
+and opens it in your browser. Port is picked per session; set `dashboard.port`
+in config for a stable URL.
+
+- **Overview**: donut of measured savings, chunk/file counts, live indexing
+  state (polled every 5 s), and the active configuration.
+- **Files**: every indexed file with its chunk count, largest first.
+- **Sessions**: past sessions with per-turn summaries and tool events.
+- **Memory**: recorded decisions and code areas.
+- **Savings**: the per-bucket ledger with dollar estimates and a 30-day trend.
+- **Export**: one JSON download of all of the above.
+
+The dashboard is strictly read-only: every state change (reindex, reset,
+config) stays in pi commands. It binds to `127.0.0.1` only, serves GET
+requests only, and rejects requests whose `Host` header is not loopback, so a
+malicious page cannot read your index data via DNS rebinding. It stops when
+the session ends.
+
 ## Requirements
 
 - **Node 22+** on macOS, Linux or Windows.
@@ -220,6 +240,8 @@ indexer:
   watch: true             # reindex on file changes while the session runs (debounced, incremental)
 memory:
   redact_pii: true
+dashboard:
+  port: 0                # 0 = pick a free port; set one for a stable dashboard URL
 pricing:
   model: opus            # opus | sonnet | haiku | gpt-4o | gemini-2.5-pro | ...
 storage:
@@ -269,6 +291,10 @@ by default:
 Path arguments are validated against the project root, so a crafted `path` cannot
 read outside it.
 
+The web dashboard adds its own guards: loopback binding, GET-only routing, and
+`Host` header validation against DNS rebinding. With no mutating endpoints,
+there is nothing for a cross-site request to trigger.
+
 ## Supported languages
 
 **AST chunking** (tree-sitter): Python, JavaScript, TypeScript, TSX, PHP, Go,
@@ -286,13 +312,17 @@ This is a port, not a wrapper. Three deliberate changes:
   the `curl`-based Claude Code hooks. Session capture rides on pi's own events.
 - **No Python runtime**: embeddings run through transformers.js or Ollama, so
   installation is one npm command.
+- **Dashboard rebuilt, not ported**: upstream serves its dashboard from a
+  FastAPI app with a mutating REST surface. Ours is a read-only `node:http`
+  server (zero dependencies) with a fresh single-file page — same tabs, no
+  write endpoints.
 - **Two upstream bugs fixed**: chunk ids now include column offsets (identical
   spans on one line used to overwrite each other in the index), and the
   placeholder filter no longer suppresses unambiguous vendor keys that happen to
   contain a word like `example`.
 
-Not ported (yet): the web dashboard, output-compression rules, and editor
-bootstrapping for non-pi editors.
+Not ported (yet): output-compression rules and editor bootstrapping for
+non-pi editors.
 
 ## Development
 
@@ -302,6 +332,7 @@ npm run check          # typecheck + 251 unit tests
 npm run smoke:env      # tree-sitter + sqlite-vec capability check
 npm run smoke:loader   # load the extension through pi's jiti loader
 npm run smoke:real-world  # index this repo with the local embedder
+npx tsx scripts/smoke-dashboard.mts  # boot the dashboard, probe every route, write a static UI preview
 ```
 
 ## Credits

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-context-engine",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Semantic code context for pi: tree-sitter index + hybrid vector/BM25 retrieval + cross-session memory, all local. Port of code-context-engine (MIT, elara-labs) as a native pi extension.",
   "keywords": [
     "pi-package",

package/src/config.ts

@@ -105,6 +105,8 @@ export interface Config {
 	indexerWatch: boolean;
 	indexerRedactSecrets: boolean;
 	memoryRedactPii: boolean;
+	/** TCP port for the /context-dashboard web server. 0 = pick a free port (default). */
+	dashboardPort: number;
 	pricingModel: string;
 	pricingInput: number | null;
 	pricingOutput: number | null;
@@ -140,6 +142,7 @@ export function defaultConfig(): Config {
 		indexerWatch: true,
 		indexerRedactSecrets: true,
 		memoryRedactPii: true,
+		dashboardPort: 0,
 		pricingModel: "opus",
 		pricingInput: null,
 		pricingOutput: null,
@@ -176,6 +179,7 @@ const MAPPING: Record<string, keyof Config> = {
 	"indexer.watch": "indexerWatch",
 	"indexer.redact_secrets": "indexerRedactSecrets",
 	"memory.redact_pii": "memoryRedactPii",
+	"dashboard.port": "dashboardPort",
 	"storage.path": "storagePath",
 	"pricing.model": "pricingModel",
 	"pricing.input": "pricingInput",
@@ -221,6 +225,11 @@ function applyDict(config: Config, data: any): void {
 				throw new Error(`config ${dotted} must be a non-negative integer`);
 			}
 			config.indexerMaxAutoFiles = value;
+		} else if (attr === "dashboardPort") {
+			if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > 65535) {
+				throw new Error(`config ${dotted} must be an integer between 0 and 65535 (0 = pick a free port)`);
+			}
+			config.dashboardPort = value;
 		} else if (attr === "pricingInput" || attr === "pricingOutput") {
 			if (value !== null && typeof value !== "number") throw new Error(`config ${dotted} must be a number or null`);
 			(config as any)[attr] = value;

package/src/dashboard/api.ts

@@ -0,0 +1,155 @@
+/**
+ * Read-only JSON snapshots for the web dashboard.
+ *
+ * Every function here is a pure reader over the engine's stores: no writes,
+ * no savings accounting, no embedder/model initialization (a dashboard
+ * refresh must never trigger a model download). Dollar estimates use the
+ * static/cached pricing table only — resolvePricing(config, false).
+ */
+import type { ContextEngine } from "../engine.js";
+import { resolvePricing } from "../pricing.js";
+
+export interface ExtDashboardState {
+	/** True while a background (auto/watcher) index run is in flight. */
+	indexing: boolean;
+}
+
+const num = (n: number): number => Math.max(0, Math.floor(n || 0));
+
+/** Cheap overview: index size, config summary and savings aggregates. No
+ * pricing resolution, no model init — polled every few seconds. */
+export function statusPayload(eng: ContextEngine, ext: ExtDashboardState) {
+	const stats = eng.getStats();
+	let fileCounts: Record<string, number> = {};
+	try {
+		fileCounts = eng.backend.fileChunkCounts();
+	} catch {
+		// index stores may not exist yet
+	}
+	const saved = num(stats.rawTokens - stats.servedTokens);
+	const fullSaved = num(stats.fullFileTokens - stats.servedTokens);
+	return {
+		project: eng.projectName,
+		projectDir: eng.projectDir,
+		storageDir: eng.storageBase,
+		sessionId: eng.sessionId,
+		chunks: eng.chunkCount(),
+		files: Object.keys(fileCounts).length,
+		indexing: ext.indexing,
+		config: {
+			embeddingModel: eng.config.embeddingModel,
+			topK: eng.config.retrievalTopK,
+			rerank: eng.config.retrievalRerank,
+			chunking: eng.config.indexerChunking,
+			autoIndex: eng.config.indexerAutoIndex,
+			watch: eng.config.indexerWatch,
+			compression: eng.config.compressionLevel,
+		},
+		stats: {
+			queries: stats.queries,
+			rawTokens: stats.rawTokens,
+			servedTokens: stats.servedTokens,
+			fullFileTokens: stats.fullFileTokens,
+			tokensSaved: saved,
+			fullFileTokensSaved: fullSaved,
+			savingsPct: stats.fullFileTokens > 0 ? Math.floor((fullSaved / stats.fullFileTokens) * 100) : null,
+		},
+	};
+}
+
+/** Bucket ledger + dollar estimates + per-day trend. Never fetches live
+ * pricing: the dashboard must stay offline-safe. */
+export async function savingsPayload(eng: ContextEngine) {
+	const { label, pricing } = await resolvePricing(eng.config, false);
+	const buckets: Record<string, { baseline: number; served: number; calls: number }> = eng.aggregateSavings() ?? {};
+	const toUsd = (tokens: number): number => (tokens / 1e6) * pricing.input;
+	const rows = Object.entries(buckets)
+		.map(([bucket, v]) => ({
+			bucket,
+			calls: v.calls,
+			baseline: v.baseline,
+			served: v.served,
+			saved: num(v.baseline - v.served),
+			savedUsd: toUsd(num(v.baseline - v.served)),
+		}))
+		.sort((a, b) => b.saved - a.saved);
+	let memory = null;
+	try {
+		memory = eng.getMemory();
+	} catch {
+		memory = null;
+	}
+	const byDay = (memory?.savingsByDay(30) ?? []).map((d) => ({
+		day: d.day,
+		saved: num(d.baseline - d.served),
+	}));
+	const stats = eng.getStats();
+	const fullSaved = num(stats.fullFileTokens - stats.servedTokens);
+	return {
+		pricing: { model: label, inputUsdPer1M: pricing.input, outputUsdPer1M: pricing.output },
+		totals: {
+			savedTokens: fullSaved,
+			savedUsd: toUsd(fullSaved),
+			savingsPct: stats.fullFileTokens > 0 ? Math.floor((fullSaved / stats.fullFileTokens) * 100) : null,
+		},
+		buckets: rows,
+		byDay,
+	};
+}
+
+/** Indexed files with chunk counts, largest first. */
+export function filesPayload(eng: ContextEngine, limit = 500) {
+	let counts: Record<string, number> = {};
+	try {
+		counts = eng.backend.fileChunkCounts();
+	} catch {
+		// no index yet
+	}
+	const rows = Object.entries(counts)
+		.map(([filePath, chunks]) => ({ filePath, chunks }))
+		.sort((a, b) => b.chunks - a.chunks || a.filePath.localeCompare(b.filePath));
+	return {
+		total: rows.length,
+		chunks: rows.reduce((acc, r) => acc + r.chunks, 0),
+		files: rows.slice(0, Math.max(1, Math.min(limit, 5000))),
+	};
+}
+
+export function sessionsPayload(eng: ContextEngine, limit = 50) {
+	const memory = eng.getMemory();
+	return {
+		sessions: memory ? memory.listSessions(limit) : [],
+		// JSON snapshots (SessionCapture) survive memory-db failures and carry
+		// decisions/code areas even when SQLite is unavailable.
+		activeSessionId: eng.sessionId,
+	};
+}
+
+export function timelinePayload(eng: ContextEngine, sessionId: string) {
+	const memory = eng.getMemory();
+	if (!memory) return { session: null, turns: [], events: [] };
+	const meta = memory.listSessions(500).find((s) => s.id === sessionId) ?? null;
+	const detail = memory.sessionDetail(sessionId);
+	return { session: meta, turns: detail.turns, events: detail.events };
+}
+
+export function decisionsPayload(eng: ContextEngine, limit = 100) {
+	const memory = eng.getMemory();
+	return {
+		decisions: memory?.listDecisions(limit) ?? [],
+		codeAreas: memory?.listCodeAreas(limit) ?? [],
+		consolidated: eng.sessionCapture.loadConsolidatedDecisions().slice(0, limit),
+	};
+}
+
+/** Everything, for /api/export. */
+export async function exportPayload(eng: ContextEngine, ext: ExtDashboardState) {
+	return {
+		generatedAt: new Date().toISOString(),
+		status: statusPayload(eng, ext),
+		savings: await savingsPayload(eng),
+		files: filesPayload(eng),
+		sessions: sessionsPayload(eng),
+		decisions: decisionsPayload(eng),
+	};
+}

package/src/dashboard/page.ts

@@ -0,0 +1,403 @@
+/**
+ * Single-file dashboard SPA: dark theme, system fonts, hand-rolled SVG charts,
+ * zero external requests (no CDN fonts, no chart libs) — consistent with the
+ * package's all-local ethos. Client JS uses string concatenation (no template
+ * literals) so this file stays a plain TS template literal.
+ */
+export const PAGE_HTML = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>pi-context-engine · dashboard</title>
+<style>
+  :root {
+    --bg: #0d1117; --panel: #161b22; --panel2: #1c2129; --border: #2d333b;
+    --text: #e6edf3; --muted: #8b949e; --accent: #4493f8; --green: #3fb950;
+    --warn: #d29922; --red: #f85149; --mono: ui-monospace, 'Cascadia Code', Consolas, monospace;
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: var(--bg); color: var(--text);
+         font: 14px/1.5 -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif; }
+  a { color: var(--accent); text-decoration: none; }
+  header { display: flex; align-items: center; gap: 14px; padding: 12px 20px;
+           border-bottom: 1px solid var(--border); background: var(--panel); flex-wrap: wrap; }
+  header h1 { font-size: 15px; margin: 0; font-weight: 600; }
+  header .sub { color: var(--muted); font-size: 12px; }
+  .badge { font-size: 11px; padding: 2px 9px; border-radius: 10px; border: 1px solid var(--border);
+           color: var(--muted); display: inline-flex; align-items: center; gap: 6px; }
+  .badge .dot { width: 7px; height: 7px; border-radius: 50%; background: var(--muted); }
+  .badge.live .dot { background: var(--green); }
+  .badge.indexing .dot { background: var(--warn); animation: pulse 1.2s infinite; }
+  @keyframes pulse { 50% { opacity: .35; } }
+  .spacer { flex: 1; }
+  .btn { font-size: 12px; padding: 5px 12px; border-radius: 6px; border: 1px solid var(--border);
+         background: var(--panel2); color: var(--text); cursor: pointer; }
+  .btn:hover { border-color: var(--accent); }
+  nav { display: flex; gap: 2px; padding: 0 20px; border-bottom: 1px solid var(--border); background: var(--panel); }
+  nav button { appearance: none; border: none; background: none; color: var(--muted); font: inherit;
+               padding: 9px 14px; cursor: pointer; border-bottom: 2px solid transparent; }
+  nav button.active { color: var(--text); border-bottom-color: var(--accent); }
+  nav button:hover { color: var(--text); }
+  main { padding: 20px; max-width: 1200px; margin: 0 auto; }
+  .grid { display: grid; gap: 14px; }
+  .cards { grid-template-columns: repeat(auto-fit, minmax(170px, 1fr)); }
+  .card { background: var(--panel); border: 1px solid var(--border); border-radius: 10px; padding: 14px 16px; }
+  .card .k { color: var(--muted); font-size: 12px; }
+  .card .v { font-size: 22px; font-weight: 650; margin-top: 2px; }
+  .card .s { color: var(--muted); font-size: 11px; margin-top: 2px; }
+  .panel { background: var(--panel); border: 1px solid var(--border); border-radius: 10px; padding: 16px; }
+  .panel h2 { font-size: 13px; margin: 0 0 12px; color: var(--muted); font-weight: 600;
+              text-transform: uppercase; letter-spacing: .04em; }
+  .two-col { grid-template-columns: 1fr 1fr; }
+  @media (max-width: 860px) { .two-col { grid-template-columns: 1fr; } }
+  table { width: 100%; border-collapse: collapse; font-size: 13px; }
+  th { text-align: left; color: var(--muted); font-weight: 500; font-size: 12px;
+       padding: 6px 10px; border-bottom: 1px solid var(--border); }
+  td { padding: 6px 10px; border-bottom: 1px solid var(--border); vertical-align: top; }
+  tr:last-child td { border-bottom: none; }
+  td.num, th.num { text-align: right; font-variant-numeric: tabular-nums; }
+  code, .path { font-family: var(--mono); font-size: 12px; }
+  .path { word-break: break-all; }
+  .bar-track { background: var(--panel2); border-radius: 4px; height: 8px; overflow: hidden; min-width: 60px; }
+  .bar-fill { height: 100%; background: var(--accent); border-radius: 4px; }
+  .bar-fill.green { background: var(--green); }
+  .muted { color: var(--muted); }
+  .empty { color: var(--muted); padding: 18px; text-align: center; }
+  .donut-wrap { display: flex; align-items: center; gap: 22px; flex-wrap: wrap; }
+  .donut-legend { display: flex; flex-direction: column; gap: 6px; font-size: 13px; }
+  .donut-legend b { font-size: 16px; }
+  .cfg-list { display: grid; grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); gap: 4px 18px;
+              font-size: 12.5px; color: var(--muted); }
+  .cfg-list b { color: var(--text); font-weight: 500; }
+  .vbars { display: flex; align-items: flex-end; gap: 3px; height: 120px; padding-top: 8px; }
+  .vbars .col { flex: 1; display: flex; flex-direction: column; justify-content: flex-end; height: 100%; }
+  .vbars .col > div { background: var(--accent); border-radius: 3px 3px 0 0; min-height: 2px; }
+  .vbars .col:hover { outline: 1px solid var(--border); }
+  .sess-item { padding: 10px 12px; border: 1px solid var(--border); border-radius: 8px;
+               cursor: pointer; background: var(--panel2); }
+  .sess-item:hover { border-color: var(--accent); }
+  .sess-item.active { border-color: var(--accent); }
+  .sess-item .when { color: var(--muted); font-size: 11.5px; }
+  .turn { border-left: 2px solid var(--border); padding: 6px 12px; margin: 8px 0; }
+  .turn .tier { font-size: 10.5px; color: var(--accent); text-transform: uppercase; letter-spacing: .05em; }
+  .ev { display: inline-block; font-family: var(--mono); font-size: 11px; background: var(--panel2);
+        border: 1px solid var(--border); border-radius: 4px; padding: 1px 6px; margin: 2px 4px 2px 0; }
+  .decision { border-left: 3px solid var(--green); padding: 8px 12px; margin-bottom: 10px;
+              background: var(--panel2); border-radius: 0 8px 8px 0; }
+  .decision .why { color: var(--muted); font-size: 12.5px; margin-top: 3px; }
+  .decision .when { color: var(--muted); font-size: 11px; }
+  #toast { position: fixed; bottom: 18px; left: 50%; transform: translateX(-50%);
+           background: var(--panel2); border: 1px solid var(--border); color: var(--text);
+           padding: 8px 16px; border-radius: 8px; font-size: 12.5px; display: none; }
+</style>
+</head>
+<body>
+<header>
+  <h1>pi-context-engine</h1>
+  <span class="sub" id="project">…</span>
+  <span class="badge" id="state"><span class="dot"></span><span id="state-text">connecting</span></span>
+  <span class="spacer"></span>
+  <span class="sub" id="counts"></span>
+  <a class="btn" href="/api/export" download>Export JSON</a>
+</header>
+<nav id="nav"></nav>
+<main id="main"><div class="empty">Loading…</div></main>
+<div id="toast"></div>
+<script>
+'use strict';
+var TABS = ['overview', 'files', 'sessions', 'memory', 'savings'];
+var state = { tab: 'overview', sessionId: null, status: null };
+var pollTimer = null;
+
+function $(id) { return document.getElementById(id); }
+function esc(s) {
+  return String(s == null ? '' : s).replace(/[&<>"']/g, function (c) {
+    return { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c];
+  });
+}
+function fmt(n) { return Number(n || 0).toLocaleString(); }
+function fmtK(n) {
+  n = Number(n || 0);
+  if (n >= 1e9) return (n / 1e9).toFixed(1) + 'B';
+  if (n >= 1e6) return (n / 1e6).toFixed(1) + 'M';
+  if (n >= 1e3) return (n / 1e3).toFixed(1) + 'k';
+  return String(n);
+}
+function fmtUsd(v) {
+  if (!isFinite(v)) return '$0';
+  if (v > 0 && v < 0.01) return '$' + v.toFixed(4);
+  return '$' + v.toFixed(2);
+}
+function fmtWhen(iso) {
+  if (!iso) return '—';
+  var d = new Date(iso);
+  if (isNaN(d)) return String(iso);
+  return d.toLocaleString();
+}
+function api(path) {
+  return fetch(path).then(function (r) {
+    if (!r.ok) return r.json().then(function (b) { throw new Error(b.error || ('HTTP ' + r.status)); });
+    return r.json();
+  });
+}
+function toast(msg) {
+  var t = $('toast');
+  t.textContent = msg;
+  t.style.display = 'block';
+  clearTimeout(toast._h);
+  toast._h = setTimeout(function () { t.style.display = 'none'; }, 3500);
+}
+function pctBar(v, max, cls) {
+  var w = max > 0 ? Math.max(1, Math.round((v / max) * 100)) : 0;
+  return '<div class="bar-track"><div class="bar-fill ' + (cls || '') + '" style="width:' + w + '%"></div></div>';
+}
+
+/* ── header / status poll ─────────────────────────────────────────── */
+function renderStatus(st) {
+  state.status = st;
+  $('project').textContent = st.project + ' · ' + st.projectDir;
+  var badge = $('state');
+  if (st.indexing) { badge.className = 'badge indexing'; $('state-text').textContent = 'indexing…'; }
+  else if (st.chunks > 0) { badge.className = 'badge live'; $('state-text').textContent = 'live'; }
+  else { badge.className = 'badge'; $('state-text').textContent = 'no index'; }
+  $('counts').textContent = fmt(st.chunks) + ' chunks · ' + fmt(st.files) + ' files';
+  if (state.tab === 'overview') renderOverview(st);
+}
+
+function pollStatus() {
+  api('/api/status').then(renderStatus).catch(function (e) {
+    $('state-text').textContent = 'offline';
+    if (e && e.message) toast(e.message);
+  });
+}
+
+/* ── tabs ─────────────────────────────────────────────────────────── */
+function renderNav() {
+  var nav = $('nav');
+  nav.innerHTML = '';
+  TABS.forEach(function (t) {
+    var b = document.createElement('button');
+    b.textContent = t.charAt(0).toUpperCase() + t.slice(1);
+    b.className = t === state.tab ? 'active' : '';
+    b.onclick = function () { switchTab(t); };
+    nav.appendChild(b);
+  });
+}
+
+function switchTab(tab) {
+  state.tab = tab;
+  renderNav();
+  $('main').innerHTML = '<div class="empty">Loading…</div>';
+  if (tab === 'overview') { if (state.status) renderOverview(state.status); else pollStatus(); }
+  else if (tab === 'files') loadFiles();
+  else if (tab === 'sessions') loadSessions();
+  else if (tab === 'memory') loadMemory();
+  else if (tab === 'savings') loadSavings();
+}
+
+function setMain(html) { $('main').innerHTML = html; }
+
+/* ── overview ─────────────────────────────────────────────────────── */
+function donut(pct) {
+  var r = 52, c = 2 * Math.PI * r;
+  var p = Math.max(0, Math.min(100, pct || 0));
+  return '<svg width="130" height="130" viewBox="0 0 130 130">' +
+    '<circle cx="65" cy="65" r="' + r + '" fill="none" stroke="#21262d" stroke-width="14"/>' +
+    '<circle cx="65" cy="65" r="' + r + '" fill="none" stroke="#3fb950" stroke-width="14" ' +
+    'stroke-linecap="round" stroke-dasharray="' + (c * p / 100).toFixed(1) + ' ' + c.toFixed(1) + '" ' +
+    'transform="rotate(-90 65 65)"/>' +
+    '<text x="65" y="62" text-anchor="middle" fill="#e6edf3" font-size="24" font-weight="650">' + p + '%</text>' +
+    '<text x="65" y="82" text-anchor="middle" fill="#8b949e" font-size="10">tokens saved</text></svg>';
+}
+
+function renderOverview(st) {
+  var s = st.stats;
+  var pct = s.savingsPct == null ? 0 : s.savingsPct;
+  setMain(
+    '<div class="grid" style="margin-bottom:14px">' +
+      '<div class="panel"><div class="donut-wrap">' + donut(pct) +
+        '<div class="donut-legend">' +
+          '<div><b>' + fmtK(s.fullFileTokensSaved) + '</b> input tokens saved <span class="muted">(full-file baseline)</span></div>' +
+          '<div class="muted">' + fmt(s.fullFileTokens) + ' full-file → ' + fmt(s.servedTokens) + ' served</div>' +
+          '<div class="muted">' + fmt(s.queries) + ' quer' + (s.queries === 1 ? 'y' : 'ies') + ' recorded' +
+            (s.savingsPct == null ? ' — savings appear after the first context_search' : '') + '</div>' +
+        '</div></div></div>' +
+      '<div class="grid cards">' +
+        card('Chunks', fmt(st.chunks), st.files + ' files indexed') +
+        card('Queries', fmt(s.queries), 'this project, all sessions') +
+        card('Served', fmtK(s.servedTokens), 'raw would be ' + fmtK(s.rawTokens)) +
+        card('Index state', st.indexing ? 'Indexing…' : (st.chunks > 0 ? 'Live' : 'Empty'),
+             'watch ' + (st.config.watch ? 'on' : 'off') + ' · auto ' + (st.config.autoIndex ? 'on' : 'off')) +
+      '</div>' +
+    '</div>' +
+    '<div class="panel"><h2>Configuration</h2><div class="cfg-list">' +
+      cfg('Embedding', st.config.embeddingModel) +
+      cfg('Chunking', st.config.chunking) +
+      cfg('Compression', st.config.compression) +
+      cfg('Top-K', st.config.topK) +
+      cfg('Rerank', st.config.rerank) +
+      cfg('Storage', '<span class="path">' + esc(st.storageDir) + '</span>') +
+    '</div></div>'
+  );
+}
+function card(k, v, s) {
+  return '<div class="card"><div class="k">' + k + '</div><div class="v">' + v + '</div>' +
+         (s ? '<div class="s">' + s + '</div>' : '') + '</div>';
+}
+function cfg(k, v) { return '<div>' + esc(k) + ': <b>' + v + '</b></div>'; }
+
+/* ── files ────────────────────────────────────────────────────────── */
+function loadFiles() {
+  api('/api/files').then(function (d) {
+    if (d.files.length === 0) { setMain('<div class="empty">No files indexed yet.</div>'); return; }
+    var max = d.files[0].chunks;
+    var rows = d.files.map(function (f) {
+      return '<tr><td class="path">' + esc(f.filePath) + '</td>' +
+        '<td class="num" style="width:70px">' + fmt(f.chunks) + '</td>' +
+        '<td style="width:180px">' + pctBar(f.chunks, max) + '</td></tr>';
+    }).join('');
+    setMain('<div class="panel"><h2>' + fmt(d.total) + ' files · ' + fmt(d.chunks) + ' chunks</h2>' +
+      '<table><tr><th>File</th><th class="num">Chunks</th><th></th></tr>' + rows + '</table></div>');
+  }).catch(errPanel);
+}
+
+/* ── sessions ─────────────────────────────────────────────────────── */
+function loadSessions() {
+  api('/api/sessions').then(function (d) {
+    if (d.sessions.length === 0) { setMain('<div class="empty">No sessions recorded yet.</div>'); return; }
+    var items = d.sessions.map(function (s) {
+      var active = s.id === d.activeSessionId;
+      return '<div class="sess-item' + (s.id === state.sessionId ? ' active' : '') + '" data-id="' + esc(s.id) + '">' +
+        '<div><b>' + esc(s.project) + '</b> <span class="muted">· ' + esc(s.status) +
+          (active ? ' · current' : '') + '</span></div>' +
+        '<div class="when">' + fmtWhen(s.started_at) + ' · ' + s.promptCount + (s.promptCount === 1 ? ' prompt' : ' prompts') +
+          (s.rollup ? ' · ' + esc(String(s.rollup).slice(0, 80)) : '') + '</div></div>';
+    }).join('');
+    setMain('<div class="grid two-col"><div class="grid" id="sess-list" style="gap:8px">' + items + '</div>' +
+            '<div class="panel" id="sess-detail"><div class="empty">Select a session</div></div></div>');
+    Array.prototype.forEach.call(document.querySelectorAll('.sess-item'), function (el) {
+      el.onclick = function () { openSession(el.getAttribute('data-id')); };
+    });
+    if (!state.sessionId) openSession(d.sessions[0].id, true);
+    else openSession(state.sessionId, true);
+  }).catch(errPanel);
+}
+
+function openSession(id, silent) {
+  state.sessionId = id;
+  Array.prototype.forEach.call(document.querySelectorAll('.sess-item'), function (el) {
+    el.className = 'sess-item' + (el.getAttribute('data-id') === id ? ' active' : '');
+  });
+  api('/api/sessions/' + encodeURIComponent(id)).then(function (d) {
+    var box = $('sess-detail');
+    if (!box) return;
+    var html = '';
+    if (d.session) {
+      html += '<h2>' + esc(d.session.project) + ' · ' + esc(d.session.status) + '</h2>' +
+        '<div class="muted" style="font-size:12px;margin-bottom:8px">' + fmtWhen(d.session.started_at) +
+        ' → ' + (d.session.ended_at ? fmtWhen(d.session.ended_at) : 'open') + '</div>';
+      if (d.session.rollup) html += '<div class="turn">' + esc(d.session.rollup) + '</div>';
+    }
+    if (d.turns.length === 0 && d.events.length === 0) {
+      html += '<div class="empty">No turns or events captured for this session.</div>';
+    }
+    if (d.turns.length > 0) {
+      html += '<h2 style="margin-top:14px">Turns</h2>';
+      d.turns.forEach(function (t) {
+        html += '<div class="turn"><div class="tier">turn ' + t.promptNumber + ' · ' + esc(t.tier) + '</div>' +
+                esc(t.summary) + '</div>';
+      });
+    }
+    if (d.events.length > 0) {
+      html += '<h2 style="margin-top:14px">' + d.events.length + ' tool events</h2><div>';
+      d.events.forEach(function (e) {
+        html += '<span class="ev" title="' + esc(e.createdAt) + '">' + esc(e.tool) + '#' + e.id +
+                (e.hasPayload ? '' : ' ·') + '</span>';
+      });
+      html += '</div><div class="muted" style="font-size:11px;margin-top:6px">· = payload aged out, summary only</div>';
+    }
+    box.innerHTML = html;
+  }).catch(function (e) { if (!silent) toast(e.message); });
+}
+
+/* ── memory ───────────────────────────────────────────────────────── */
+function loadMemory() {
+  api('/api/decisions').then(function (d) {
+    var html = '<div class="grid two-col"><div class="panel"><h2>Decisions</h2>';
+    if (d.decisions.length === 0 && d.consolidated.length === 0) {
+      html += '<div class="empty">No recorded decisions yet. The agent saves them with record_decision.</div>';
+    }
+    d.decisions.forEach(function (x) {
+      html += '<div class="decision"><div>' + esc(x.decision) +
+        ' <span class="muted">· ' + esc(x.source) + '</span></div>' +
+        '<div class="why">' + esc(x.reason) + '</div>' +
+        '<div class="when">' + esc(x.createdAt) + '</div></div>';
+    });
+    d.consolidated.forEach(function (x) {
+      html += '<div class="decision"><div>' + esc(x.decision) + ' <span class="muted">· archive</span></div>' +
+        '<div class="why">' + esc(x.reason) + '</div></div>';
+    });
+    html += '</div><div class="panel"><h2>Code areas</h2>';
+    if (d.codeAreas.length === 0) html += '<div class="empty">No recorded code areas yet.</div>';
+    else {
+      html += '<table><tr><th>File</th><th>Description</th></tr>';
+      d.codeAreas.forEach(function (x) {
+        html += '<tr><td class="path">' + esc(x.filePath) + '</td><td>' + esc(x.description) + '</td></tr>';
+      });
+      html += '</table>';
+    }
+    html += '</div></div>';
+    setMain(html);
+  }).catch(errPanel);
+}
+
+/* ── savings ──────────────────────────────────────────────────────── */
+function loadSavings() {
+  api('/api/savings').then(function (d) {
+    var t = d.totals;
+    var html = '<div class="grid cards" style="margin-bottom:14px">' +
+      card('Saved', fmtK(t.savedTokens), 'full-file baseline') +
+      card('Estimated value', fmtUsd(t.savedUsd), d.pricing.model + ' input @ $' + d.pricing.inputUsdPer1M + '/1M') +
+      card('Savings rate', t.savingsPct == null ? '—' : t.savingsPct + '%', 'served vs full files') +
+      '</div>';
+    if (d.buckets.length > 0) {
+      var max = Math.max.apply(null, d.buckets.map(function (b) { return b.saved; }));
+      var rows = d.buckets.map(function (b) {
+        return '<tr><td>' + esc(b.bucket) + '</td><td class="num">' + fmt(b.calls) + '</td>' +
+          '<td class="num">' + fmtK(b.baseline) + '</td><td class="num">' + fmtK(b.served) + '</td>' +
+          '<td class="num">' + fmtK(b.saved) + '</td><td class="num">' + fmtUsd(b.savedUsd) + '</td>' +
+          '<td style="width:160px">' + pctBar(b.saved, max, 'green') + '</td></tr>';
+      }).join('');
+      html += '<div class="panel" style="margin-bottom:14px"><h2>By bucket</h2><table>' +
+        '<tr><th>Bucket</th><th class="num">Calls</th><th class="num">Baseline</th><th class="num">Served</th>' +
+        '<th class="num">Saved</th><th class="num">Value</th><th></th></tr>' + rows + '</table></div>';
+    }
+    if (d.byDay.length > 0) {
+      var dmax = Math.max.apply(null, d.byDay.map(function (x) { return x.saved; }));
+      var cols = d.byDay.map(function (x) {
+        var h = dmax > 0 ? Math.max(2, Math.round((x.saved / dmax) * 100)) : 2;
+        return '<div class="col" title="' + x.day + ': ' + fmt(x.saved) + ' tokens"><div style="height:' + h + '%"></div></div>';
+      }).join('');
+      html += '<div class="panel"><h2>Saved tokens · last 30 days</h2><div class="vbars">' + cols + '</div>' +
+        '<div class="muted" style="display:flex;justify-content:space-between;font-size:11px;margin-top:6px">' +
+        '<span>' + esc(d.byDay[0].day) + '</span><span>' + esc(d.byDay[d.byDay.length - 1].day) + '</span></div></div>';
+    }
+    if (d.buckets.length === 0 && d.byDay.length === 0) {
+      html = '<div class="empty">No savings recorded yet — they accumulate as the agent uses context_search.</div>';
+    }
+    setMain(html);
+  }).catch(errPanel);
+}
+
+function errPanel(e) {
+  setMain('<div class="empty">Failed to load: ' + esc(e && e.message ? e.message : e) + '</div>');
+}
+
+/* ── boot ─────────────────────────────────────────────────────────── */
+renderNav();
+pollStatus();
+setInterval(pollStatus, 5000);
+</script>
+</body>
+</html>`;

package/src/dashboard/server.ts

@@ -0,0 +1,204 @@
+/**
+ * Local read-only dashboard server.
+ *
+ * Binds 127.0.0.1 only, serves GET/HEAD requests exclusively, and validates
+ * the Host header so a page loaded from any other origin (including a
+ * DNS-rebinding domain pointing at 127.0.0.1) gets rejected. There are no
+ * mutating endpoints by design — every state change goes through pi
+ * commands, so no CSRF/token machinery is needed.
+ */
+import http from "node:http";
+import type { ContextEngine } from "../engine.js";
+import {
+	decisionsPayload,
+	exportPayload,
+	filesPayload,
+	sessionsPayload,
+	statusPayload,
+	timelinePayload,
+	savingsPayload,
+	type ExtDashboardState,
+} from "./api.js";
+import { PAGE_HTML } from "./page.js";
+
+export interface DashboardServerOptions {
+	/** Live-engine accessor; returning null makes every /api route report 503. */
+	engine: () => ContextEngine | null;
+	/** Live background-indexing flag for the status poll. */
+	indexing: () => boolean;
+	/** TCP port; 0 (default) picks a free port. */
+	port?: number;
+	log?: (msg: string, level: "info" | "warning") => void;
+}
+
+const MAX_SESSION_ID_CHARS = 200;
+
+const sendJson = (res: http.ServerResponse, code: number, body: unknown, extra: Record<string, string> = {}): void => {
+	const text = JSON.stringify(body);
+	res.writeHead(code, {
+		"Content-Type": "application/json; charset=utf-8",
+		"Cache-Control": "no-store",
+		...extra,
+	});
+	res.end(text);
+};
+
+const clampLimit = (raw: string | null, fallback: number, max: number): number => {
+	const n = Number(raw);
+	if (!Number.isFinite(n) || n <= 0) return fallback;
+	return Math.min(Math.floor(n), max);
+};
+
+export class DashboardServer {
+	private server: http.Server | null = null;
+	private baseUrlValue: string | null = null;
+
+	get url(): string | null {
+		return this.baseUrlValue;
+	}
+
+	get running(): boolean {
+		return this.server !== null;
+	}
+
+	/** Idempotent: returns the existing URL when already listening. */
+	start(options: DashboardServerOptions): Promise<string> {
+		if (this.server && this.baseUrlValue) return Promise.resolve(this.baseUrlValue);
+		return new Promise((resolve, reject) => {
+			const server = http.createServer((req, res) => {
+				try {
+					this.handle(req, res, options);
+				} catch (err) {
+					// handle() is sync-only except for the async payload builders it
+					// routes through sendPayload; this is a last-resort guard.
+					sendJson(res, 500, { error: "internal error" });
+					options.log?.(`dashboard request failed: ${(err as Error).message}`, "warning");
+				}
+			});
+			server.on("clientError", (_err, socket) => {
+				// Malformed HTTP (scanners, port probes): drop the socket, never crash.
+				if (socket.writable) socket.end("HTTP/1.1 400 Bad Request\r\n\r\n");
+				else socket.destroy();
+			});
+			server.on("error", (err) => {
+				this.server = null;
+				this.baseUrlValue = null;
+				reject(err);
+			});
+			const port = options.port ?? 0;
+			server.listen(port, "127.0.0.1", () => {
+				const address = server.address();
+				if (!address || typeof address === "string") {
+					reject(new Error("dashboard server got an unexpected address"));
+					server.close();
+					return;
+				}
+				this.server = server;
+				this.baseUrlValue = `http://127.0.0.1:${address.port}`;
+				resolve(this.baseUrlValue);
+			});
+		});
+	}
+
+	async stop(): Promise<void> {
+		const server = this.server;
+		if (!server) return;
+		this.server = null;
+		this.baseUrlValue = null;
+		// Node 18.2+: terminate keep-alive sockets so close() is deterministic
+		// even with a browser tab still polling.
+		(server as unknown as { closeAllConnections?: () => void }).closeAllConnections?.();
+		await new Promise<void>((resolve) => {
+			server.close(() => resolve());
+		});
+	}
+
+	private allowedHost(hostHeader: string | undefined, port: number): boolean {
+		if (!hostHeader) return false;
+		const normalized = hostHeader.trim().toLowerCase();
+		return normalized === `127.0.0.1:${port}` || normalized === `localhost:${port}`;
+	}
+
+	private handle(req: http.IncomingMessage, res: http.ServerResponse, options: DashboardServerOptions): void {
+		const method = (req.method ?? "GET").toUpperCase();
+		if (method !== "GET" && method !== "HEAD") {
+			res.setHeader("Allow", "GET, HEAD");
+			sendJson(res, 405, { error: "read-only dashboard: only GET is supported" });
+			return;
+		}
+		if (req.headers.upgrade) {
+			sendJson(res, 426, { error: "upgrades not supported" });
+			return;
+		}
+		const address = this.server?.address();
+		const port = address && typeof address !== "string" ? address.port : 0;
+		if (!this.allowedHost(req.headers.host, port)) {
+			sendJson(res, 403, { error: "forbidden host" });
+			return;
+		}
+
+		const url = new URL(req.url ?? "/", `http://127.0.0.1:${port}`);
+		const route = url.pathname;
+
+		if (route === "/" || route === "/index.html") {
+			res.writeHead(200, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store" });
+			res.end(method === "HEAD" ? undefined : PAGE_HTML);
+			return;
+		}
+
+		const eng = options.engine();
+		if (!eng) {
+			sendJson(res, 503, { error: "no active context engine — open the dashboard from a pi session in a project" });
+			return;
+		}
+		const ext: ExtDashboardState = { indexing: options.indexing() };
+
+		void (async (): Promise<void> => {
+			switch (route) {
+				case "/api/status":
+					sendJson(res, 200, statusPayload(eng, ext));
+					return;
+				case "/api/savings":
+					sendJson(res, 200, await savingsPayload(eng));
+					return;
+				case "/api/files":
+					sendJson(res, 200, filesPayload(eng, clampLimit(url.searchParams.get("limit"), 500, 5000)));
+					return;
+				case "/api/sessions":
+					sendJson(res, 200, sessionsPayload(eng, clampLimit(url.searchParams.get("limit"), 50, 500)));
+					return;
+				case "/api/decisions":
+					sendJson(res, 200, decisionsPayload(eng, clampLimit(url.searchParams.get("limit"), 100, 500)));
+					return;
+				case "/api/export":
+					sendJson(res, 200, await exportPayload(eng, ext), {
+						"Content-Disposition": `attachment; filename="context-engine-export-${eng.projectName}.json"`,
+					});
+					return;
+				default:
+					break;
+			}
+			const sessionMatch = /^\/api\/sessions\/([^/]+)$/.exec(route);
+			if (sessionMatch) {
+				let sessionId: string;
+				try {
+					sessionId = decodeURIComponent(sessionMatch[1] ?? "");
+				} catch {
+					sendJson(res, 400, { error: "malformed session id" });
+					return;
+				}
+				if (!sessionId || sessionId.length > MAX_SESSION_ID_CHARS || /[\0-\x1f\x7f]/.test(sessionId)) {
+					sendJson(res, 400, { error: "malformed session id" });
+					return;
+				}
+				sendJson(res, 200, timelinePayload(eng, sessionId));
+				return;
+			}
+			sendJson(res, 404, { error: `unknown route ${route}` });
+		})().catch((err: unknown) => {
+			if (!res.headersSent) sendJson(res, 500, { error: "internal error" });
+			else res.end();
+			options.log?.(`dashboard request failed: ${(err as Error).message}`, "warning");
+		});
+	}
+}

package/src/extension.ts

@@ -10,10 +10,12 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import fs from "node:fs";
 import path from "node:path";
+import { spawn } from "node:child_process";
 import { ContextEngine, isPceConfig } from "./engine.js";
 import { applyContextSearchGuidance } from "./guidance.js";
 import { ProjectWatcher } from "./indexer/watcher.js";
 import { AutomaticIndexFileLimitError } from "./indexer/pipeline.js";
+import { DashboardServer } from "./dashboard/server.js";
 
 /** Tools whose payloads are worth capturing for session timelines. */
 const CAPTURED_TOOLS = new Set(["bash", "read", "edit", "write", "grep", "find", "ls"]);
@@ -66,6 +68,14 @@ export default function contextEngineExtension(pi: ExtensionAPI) {
 	let watcherKickPending = false;
 	let watcherNotify: ((msg: string, level: "info" | "warning") => void) | undefined;
 
+	/**
+	 * Read-only web dashboard (config `dashboard.port`, 0 = free port). Owned
+	 * by this closure like the watcher: it must outlive individual command
+	 * invocations, reference the LIVE engine on every request (engine
+	 * instances are replaced per session), and stop on session_shutdown.
+	 */
+	let dashboard: DashboardServer | null = null;
+
 	/**
 	 * Watcher-triggered incremental reindex. Unlike `kickBackgroundIndex` this
 	 * calls `reindex({ automatic: true })` directly — the watcher must re-fire
@@ -604,6 +614,46 @@ export default function contextEngineExtension(pi: ExtensionAPI) {
 		},
 	});
 
+	pi.registerCommand("context-dashboard", {
+		description: "Open the read-only web dashboard (index health, files, sessions, memory, savings) in your browser",
+		handler: async (_args, ctx) => {
+			const openBrowser = (url: string): void => {
+				const cmd = process.platform === "win32" ? "cmd.exe" : process.platform === "darwin" ? "open" : "xdg-open";
+				const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+				try {
+					spawn(cmd, args, { detached: true, stdio: "ignore" }).unref();
+				} catch {
+					// best-effort: the URL is printed either way
+				}
+			};
+			let url = dashboard?.url ?? null;
+			if (!dashboard || !url) {
+				const eng = getEngine(ctx.cwd);
+				dashboard = new DashboardServer();
+				try {
+					url = await dashboard.start({
+						engine: () => engine,
+						indexing: () => indexInFlight,
+						port: eng.config.dashboardPort,
+					});
+				} catch (err) {
+					dashboard = null;
+					ctx.ui.notify(
+						`⚠ Dashboard failed to start: ${(err as Error).message}. ` +
+							`If dashboard.port is set, another process may be using it.`,
+						"warning",
+					);
+					return;
+				}
+			}
+			openBrowser(url);
+			ctx.ui.notify(
+				`✓ Dashboard: ${url} (read-only, localhost only — stops when this session ends)`,
+				"info",
+			);
+		},
+	});
+
 	/* ── Lifecycle hooks (replace upstream's curl-based hooks) ───────────── */
 
 	pi.on("session_start", async (_event, ctx) => {
@@ -705,6 +755,11 @@ export default function contextEngineExtension(pi: ExtensionAPI) {
 		stopWatcher();
 		watcherNotify = undefined;
 		automaticIndexBlock = null;
+		if (dashboard) {
+			const d = dashboard;
+			dashboard = null;
+			await d.stop().catch(() => undefined);
+		}
 		await engine?.shutdown().catch(() => undefined);
 		engine = null;
 	});

package/src/memory/db.ts

@@ -571,6 +571,168 @@ CREATE VIRTUAL TABLE IF NOT EXISTS turn_summaries_vec USING vec0(embedding float
 		return out;
 	}
 
+	// ── Read-only views (dashboard) ───────────────────────────────────────
+	// These never write and never touch the savings ledger — they exist so the
+	// web dashboard can render history without going through the text renderers
+	// (which record progressive_disclosure savings as a side effect).
+
+	/** Recent sessions, newest first, with prompt/turn counts. */
+	listSessions(limit = 50): {
+		id: string;
+		project: string;
+		started_at: string;
+		ended_at: string | null;
+		status: string;
+		promptCount: number;
+		rollup: string | null;
+	}[] {
+		try {
+			const rows = this.db
+				.prepare(
+					`SELECT s.id, s.project, s.started_at, s.ended_at, s.status, s.rollup_summary,
+						(SELECT COUNT(*) FROM prompts p WHERE p.session_id = s.id) AS prompt_count
+					 FROM sessions s ORDER BY s.started_at_epoch DESC LIMIT ?`,
+				)
+				.all(Math.max(1, Math.min(limit, 500))) as {
+				id: string;
+				project: string;
+				started_at: string;
+				ended_at: string | null;
+				status: string;
+				rollup_summary: string | null;
+				prompt_count: number | null;
+			}[];
+			return rows.map((r) => ({
+				id: r.id,
+				project: r.project,
+				started_at: r.started_at,
+				ended_at: r.ended_at,
+				status: r.status,
+				promptCount: Number(r.prompt_count ?? 0),
+				rollup: r.rollup_summary,
+			}));
+		} catch {
+			return [];
+		}
+	}
+
+	/** Turn summaries + tool-event activity for one session, in turn order. */
+	sessionDetail(
+		sessionId: string,
+		turnLimit = 200,
+	): {
+		turns: { promptNumber: number; tier: string; summary: string }[];
+		events: { id: number; tool: string; promptNumber: number; createdAt: string; hasPayload: boolean }[];
+	} {
+		const empty = { turns: [], events: [] as { id: number; tool: string; promptNumber: number; createdAt: string; hasPayload: boolean }[] };
+		try {
+			const turns = this.db
+				.prepare(
+					"SELECT prompt_number, tier, summary FROM turn_summaries WHERE session_id = ? ORDER BY prompt_number ASC LIMIT ?",
+				)
+				.all(sessionId, Math.max(1, Math.min(turnLimit, 500))) as {
+				prompt_number: number;
+				tier: string;
+				summary: string;
+			}[];
+			const events = this.db
+				.prepare(
+					`SELECT te.id, te.tool_name, te.prompt_number, te.created_at, (te.payload_id IS NOT NULL) AS has_payload
+					 FROM tool_events te WHERE te.session_id = ? ORDER BY te.id ASC LIMIT ?`,
+				)
+				.all(sessionId, Math.max(1, Math.min(turnLimit * 20, 2000))) as {
+				id: number;
+				tool_name: string;
+				prompt_number: number;
+				created_at: string;
+				has_payload: number;
+			}[];
+			return {
+				turns: turns.map((t) => ({ promptNumber: t.prompt_number, tier: t.tier, summary: t.summary })),
+				events: events.map((e) => ({
+					id: e.id,
+					tool: e.tool_name,
+					promptNumber: e.prompt_number,
+					createdAt: e.created_at,
+					hasPayload: Number(e.has_payload) === 1,
+				})),
+			};
+		} catch {
+			return empty;
+		}
+	}
+
+	/** Recent decisions, newest first. */
+	listDecisions(limit = 100): { id: number; decision: string; reason: string; source: string; createdAt: string }[] {
+		try {
+			const rows = this.db
+				.prepare("SELECT id, decision, reason, source, created_at FROM decisions ORDER BY created_at_epoch DESC LIMIT ?")
+				.all(Math.max(1, Math.min(limit, 500))) as {
+				id: number;
+				decision: string;
+				reason: string;
+				source: string;
+				created_at: string;
+			}[];
+			return rows.map((r) => ({ id: r.id, decision: r.decision, reason: r.reason, source: r.source, createdAt: r.created_at }));
+		} catch {
+			return [];
+		}
+	}
+
+	/** Recent code areas, newest first. */
+	listCodeAreas(limit = 100): { id: number; filePath: string; description: string; source: string; createdAt: string }[] {
+		try {
+			const rows = this.db
+				.prepare("SELECT id, file_path, description, source, created_at FROM code_areas ORDER BY created_at_epoch DESC LIMIT ?")
+				.all(Math.max(1, Math.min(limit, 500))) as {
+				id: number;
+				file_path: string;
+				description: string;
+				source: string;
+				created_at: string;
+			}[];
+			return rows.map((r) => ({ id: r.id, filePath: r.file_path, description: r.description, source: r.source, createdAt: r.created_at }));
+		} catch {
+			return [];
+		}
+	}
+
+	/** Raw savings events, newest first. */
+	recentSavings(limit = 200): { bucket: string; baseline: number; served: number; ts: number }[] {
+		try {
+			const rows = this.db
+				.prepare("SELECT bucket, baseline, served, ts FROM savings_log ORDER BY ts DESC, id DESC LIMIT ?")
+				.all(Math.max(1, Math.min(limit, 2000))) as { bucket: string; baseline: number; served: number; ts: number }[];
+			return rows.map((r) => ({ bucket: r.bucket, baseline: r.baseline, served: r.served, ts: r.ts }));
+		} catch {
+			return [];
+		}
+	}
+
+	/** Savings per local calendar day (oldest → newest) for trend charts. */
+	savingsByDay(days = 30): { day: string; baseline: number; served: number }[] {
+		const out: { day: string; baseline: number; served: number }[] = [];
+		try {
+			const cutoff = epochSeconds() - Math.max(1, Math.min(days, 365)) * 86400;
+			const rows = this.db
+				.prepare("SELECT ts, baseline, served FROM savings_log WHERE ts >= ? ORDER BY ts ASC")
+				.all(cutoff) as { ts: number; baseline: number; served: number }[];
+			const byDay = new Map<string, { baseline: number; served: number }>();
+			for (const r of rows) {
+				const day = new Date(r.ts * 1000).toISOString().slice(0, 10);
+				const acc = byDay.get(day) ?? { baseline: 0, served: 0 };
+				acc.baseline += r.baseline;
+				acc.served += r.served;
+				byDay.set(day, acc);
+			}
+			for (const [day, v] of [...byDay.entries()].sort()) out.push({ day, ...v });
+		} catch {
+			// empty series
+		}
+		return out;
+	}
+
 	// ── Retention ─────────────────────────────────────────────────────────
 
 	pruneOldPayloads(days = 30): { payloadsPruned: number; bytesFreedEstimate: number } {