supipowers 1.5.3 → 2.0.1

package/src/context-mode/metrics-store.ts

@@ -0,0 +1,765 @@
+// src/context-mode/metrics-store.ts
+//
+// Sidecar SQLite store for L1 measurement. Lives alongside `events.db` under
+// `<projectStateDir>/sessions/metrics.db`. Mirrors the `event-store.ts`
+// conventions (DELETE journal mode, WAL sidecar cleanup, idempotent migration)
+// but keeps an independent failure mode so a metrics issue cannot regress
+// event tracking.
+//
+// Hot-path contract (see design spec §3 + plan preamble):
+//   - `record(row)` is sync-looking; it appends to an in-memory queue and
+//     arms a `queueMicrotask` flush. Tests await `flushPendingForTest()`
+//     before reading durable state.
+//   - Bursts that arrive in the same microtask coalesce into one transaction.
+//   - Failures are swallowed; the in-memory failure counter combined with the
+//     persisted column lets `/supi:doctor` surface degraded sessions.
+
+import { constants, Database } from "bun:sqlite";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { isDebugEnabled } from "../debug/logger.js";
+
+export const SCHEMA_VERSION = 3;
+export const MAX_ROWS_PER_SESSION = 5000;
+export const RETENTION_DAYS = 7;
+
+export type LayerKey = "L1" | "L2" | "L3" | "L4" | "L5" | "L6" | "L7";
+
+export type ProcessorKey =
+  | "bash"
+  | "read"
+  | "search"
+  | "find"
+  | "passthrough"
+  | "omp-minimizer"
+  | "git"
+  | "test"
+  | "lint"
+  | "build"
+  | "k8s"
+  | "docker"
+  | "log"
+  | "json"
+  | "dedup"
+  | "lazy-tools"
+  | "startup-optimizer"
+  | "cache-store"
+  | "cache-spill"
+  | "cache-open"
+  | "cache-prune"
+  | "cache-clear"
+  | null;
+
+/** A single metric row pending insertion or read from the metrics table. */
+export interface MetricRow {
+  session_id: string;
+  ts: number;
+  layer: LayerKey;
+  tool: string;
+  processor: ProcessorKey;
+  before_bytes: number;
+  after_bytes: number;
+  cache_hit: 0 | 1;
+  unique_source_hash: string | null;
+  context_tokens: number | null;
+  context_window: number | null;
+  context_percent: number | null;
+}
+
+export interface SessionMetaMetrics {
+  session_id: string;
+  cwd: string;
+  started_at: number;
+  last_event_at: number;
+  row_count: number;
+  write_failures: number;
+  last_clear_at: number | null;
+}
+
+export interface ProjectMetaMetrics {
+  project_slug: string;
+  first_run_notice_shown_at: number | null;
+  last_prune_at: number | null;
+  last_clear_all_at: number | null;
+}
+
+export interface MetricsStoreOptions {
+  dbPath: string;
+  projectSlug: string;
+}
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS metrics (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  session_id TEXT NOT NULL,
+  ts INTEGER NOT NULL,
+  layer TEXT NOT NULL,
+  tool TEXT NOT NULL,
+  processor TEXT,
+  before_bytes INTEGER NOT NULL,
+  after_bytes INTEGER NOT NULL,
+  cache_hit INTEGER NOT NULL DEFAULT 0,
+  unique_source_hash TEXT,
+  context_tokens INTEGER,
+  context_window INTEGER,
+  context_percent REAL
+);
+
+CREATE INDEX IF NOT EXISTS idx_metrics_session_ts ON metrics(session_id, ts);
+CREATE INDEX IF NOT EXISTS idx_metrics_layer_tool ON metrics(layer, tool);
+
+CREATE TABLE IF NOT EXISTS session_meta_metrics (
+  session_id TEXT PRIMARY KEY,
+  cwd TEXT NOT NULL,
+  started_at INTEGER NOT NULL,
+  last_event_at INTEGER NOT NULL,
+  row_count INTEGER NOT NULL DEFAULT 0,
+  write_failures INTEGER NOT NULL DEFAULT 0,
+  last_clear_at INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS project_meta_metrics (
+  project_slug TEXT PRIMARY KEY,
+  first_run_notice_shown_at INTEGER,
+  last_prune_at INTEGER,
+  last_clear_all_at INTEGER
+);
+`;
+
+function appendTraceLine(filePath: string, entry: Record<string, unknown>): void {
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.appendFileSync(
+      filePath,
+      JSON.stringify({ ts: new Date().toISOString(), ...entry }) + "\n",
+    );
+  } catch {
+    // Trace logging must never block the primary flow.
+  }
+}
+
+export class MetricsStore {
+  readonly #dbPath: string;
+  readonly #projectSlug: string;
+  #db: Database;
+  #closed = false;
+
+  // Microtask-batched write queue + a per-burst flush promise so tests can await it.
+  #queue: MetricRow[] = [];
+  #flushScheduled = false;
+  #flushPromise: Promise<void> | null = null;
+  #flushResolve: (() => void) | null = null;
+
+  // Per-session in-memory write failures, combined with persisted column on read.
+  #inMemoryFailures = new Map<string, number>();
+
+  // Per-instance flush counter — used by tests to confirm batching works.
+  #flushCount = 0;
+
+  // Trace path is computed once on init; null when SUPI_DEBUG is unset.
+  #tracePath: string | null = null;
+
+  // Prepared statements (lazy, initialized on first use).
+  #insertStmt: ReturnType<Database["prepare"]> | null = null;
+  #upsertSessionStmt: ReturnType<Database["prepare"]> | null = null;
+  #incRowCountStmt: ReturnType<Database["prepare"]> | null = null;
+  #evictOldestStmt: ReturnType<Database["prepare"]> | null = null;
+  #updateRowCountStmt: ReturnType<Database["prepare"]> | null = null;
+  #flushTransaction: ((rows: MetricRow[]) => void) | null = null;
+
+  constructor(opts: MetricsStoreOptions) {
+    this.#dbPath = opts.dbPath;
+    this.#projectSlug = opts.projectSlug;
+    this.#db = new Database(opts.dbPath);
+  }
+
+  /** Absolute path to the on-disk SQLite file. */
+  get dbPath(): string {
+    return this.#dbPath;
+  }
+
+  /** Project slug supplied at construction (primary key into `project_meta_metrics`). */
+  get projectSlug(): string {
+    return this.#projectSlug;
+  }
+
+  /** Number of times the microtask flush function has run. Test-only. */
+  get flushCountForTest(): number {
+    return this.#flushCount;
+  }
+
+  /** Trace file path (null when `SUPI_DEBUG` is unset). Test-only. */
+  get tracePathForTest(): string | null {
+    return this.#tracePath;
+  }
+
+  init(): void {
+    try {
+      this.#ensureDeleteJournalMode();
+      // CREATE TABLE IF NOT EXISTS guards every statement in SCHEMA, so it is
+      // safe to run before #migrate(). Running the schema first means v1→vN
+      // data fixups can assume their target tables exist on every code path.
+      this.#db.exec(SCHEMA);
+      this.#migrate();
+      this.#prepareStatements();
+
+      if (isDebugEnabled()) {
+        this.#tracePath = path.join(path.dirname(this.#dbPath), "metrics-trace.jsonl");
+      }
+    } catch (error) {
+      this.close();
+      throw error;
+    }
+  }
+
+  // ── Journal mode + WAL handling (mirrors event-store.ts) ────────────
+
+  #ensureDeleteJournalMode(): void {
+    const journalMode = this.#getJournalMode();
+    if (journalMode === "delete") return;
+
+    if (journalMode === "wal") {
+      this.#cleanupWalSidecars();
+    }
+
+    try {
+      this.#db.exec("PRAGMA journal_mode = DELETE;");
+    } catch {
+      // Older WAL-backed databases can stay on WAL for this process.
+      // close() still checkpoints them so teardown and the next reopen succeed.
+    }
+  }
+
+  #getJournalMode(): string {
+    const { journal_mode } = this.#db.prepare("PRAGMA journal_mode").get() as {
+      journal_mode: string;
+    };
+    return journal_mode.toLowerCase();
+  }
+
+  #cleanupWalSidecars(): void {
+    try {
+      this.#db.fileControl(constants.SQLITE_FCNTL_PERSIST_WAL, 0);
+      this.#db.exec("PRAGMA wal_checkpoint(TRUNCATE);");
+    } catch {
+      // Best effort only: close() still releases the handle in finally.
+    }
+  }
+
+  // ── Schema migration ─────────────────────────────────────────────────
+
+  #migrate(): void {
+    const { user_version } = this.#db.prepare("PRAGMA user_version").get() as {
+      user_version: number;
+    };
+
+    if (user_version === SCHEMA_VERSION) return;
+    if (user_version > SCHEMA_VERSION) {
+      throw new Error(
+        `metrics-store: unknown schema version ${user_version} (max supported: ${SCHEMA_VERSION})`,
+      );
+    }
+
+    // v0 \u2192 v1: schema-only bump. CREATE TABLE IF NOT EXISTS already ran in
+    // init(); no data fixup is required.
+
+    // v1 \u2192 v2: OMP 14.5.12 renamed the canonical "grep" tool key to "search".
+    // Rows persisted under the old name still report `tool='grep'` and
+    // `processor='grep'` \u2014 values the type system no longer admits and which
+    // /supi:doctor / per-processor breakdowns would silently bucket under a
+    // typed-impossible key. Source hashes baked the legacy `grep:` prefix into
+    // SHA256, so they cannot collide with post-rename `search:`-prefixed
+    // hashes; the privacy contract forbids reconstructing the original path
+    // or pattern, so re-hashing is impossible. NULL is the right substitute:
+    // `getUniqueSourceShare` already excludes NULL hashes from numerator and
+    // denominator, and a NULL hash never collides with new dedup state.
+    if (user_version < 2) {
+      const tx = this.#db.transaction(() => {
+        this.#db.exec(
+          `UPDATE metrics SET unique_source_hash = NULL WHERE tool = 'grep'`,
+        );
+        this.#db.exec(
+          `UPDATE metrics SET tool = 'search' WHERE tool = 'grep'`,
+        );
+        this.#db.exec(
+          `UPDATE metrics SET processor = 'search' WHERE processor = 'grep'`,
+        );
+      });
+      tx();
+    }
+
+    // v2 → v3: OMP 14.6.0 renamed `search`/`find` tool params from
+    // `path: string` / `pattern: string` to `paths: string[]`. Source hashes
+    // computed under the old salts (`search:<single-path>:<slug>`,
+    // `find:<pattern>:<slug>`) cannot collide with the new salts
+    // (`search:<joined-paths>:<pattern>:<slug>`, `find:<joined-paths>:<slug>`)
+    // because the input strings differ; but the privacy contract forbids
+    // re-hashing, so NULL is the correct substitute. `getUniqueSourceShare`
+    // already excludes NULLs from numerator/denominator. Newly-recorded rows
+    // from this point on use the post-rename salt.
+    if (user_version < 3) {
+      this.#db.exec(
+        `UPDATE metrics SET unique_source_hash = NULL WHERE tool IN ('search', 'find')`,
+      );
+    }
+
+    this.#db.exec(`PRAGMA user_version = ${SCHEMA_VERSION};`);
+  }
+
+  // ── Prepared statements ─────────────────────────────────────────────
+
+  #prepareStatements(): void {
+    this.#insertStmt = this.#db.prepare(
+      `INSERT INTO metrics
+         (session_id, ts, layer, tool, processor, before_bytes, after_bytes,
+          cache_hit, unique_source_hash, context_tokens, context_window, context_percent)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    );
+
+    this.#upsertSessionStmt = this.#db.prepare(
+      `INSERT INTO session_meta_metrics
+         (session_id, cwd, started_at, last_event_at, row_count, write_failures, last_clear_at)
+         VALUES (?, ?, ?, ?, 0, 0, NULL)
+         ON CONFLICT(session_id) DO UPDATE SET
+           last_event_at = excluded.last_event_at`,
+    );
+
+    this.#incRowCountStmt = this.#db.prepare(
+      `UPDATE session_meta_metrics
+         SET row_count = row_count + ?, last_event_at = ?
+         WHERE session_id = ?`,
+    );
+
+    this.#updateRowCountStmt = this.#db.prepare(
+      `UPDATE session_meta_metrics
+         SET row_count = ?
+         WHERE session_id = ?`,
+    );
+
+    this.#evictOldestStmt = this.#db.prepare(
+      `DELETE FROM metrics
+         WHERE id IN (
+           SELECT id FROM metrics
+             WHERE session_id = ?
+             ORDER BY id ASC
+             LIMIT ?
+         )`,
+    );
+
+    this.#flushTransaction = this.#db.transaction((rows: MetricRow[]) => {
+      const perSession = new Map<string, number>();
+      const lastTsBySession = new Map<string, number>();
+
+      for (const row of rows) {
+        this.#insertStmt!.run(
+          row.session_id,
+          row.ts,
+          row.layer,
+          row.tool,
+          row.processor,
+          row.before_bytes,
+          row.after_bytes,
+          row.cache_hit,
+          row.unique_source_hash,
+          row.context_tokens,
+          row.context_window,
+          row.context_percent,
+        );
+
+        perSession.set(row.session_id, (perSession.get(row.session_id) ?? 0) + 1);
+        const prev = lastTsBySession.get(row.session_id);
+        if (prev === undefined || row.ts > prev) {
+          lastTsBySession.set(row.session_id, row.ts);
+        }
+      }
+
+      // Flush in-memory failures opportunistically: if persistence is healthy,
+      // promote any pending in-memory counts into the column and clear the
+      // in-memory entries so the doctor surfaces a stable number.
+      const failures = [...this.#inMemoryFailures.entries()];
+      for (const [session, count] of failures) {
+        this.#db.prepare(
+          `UPDATE session_meta_metrics
+             SET write_failures = write_failures + ?
+             WHERE session_id = ?`,
+        ).run(count, session);
+      }
+      this.#inMemoryFailures.clear();
+
+      // Bump row_count and last_event_at per session.
+      for (const [session, count] of perSession) {
+        const ts = lastTsBySession.get(session) ?? Date.now();
+        this.#incRowCountStmt!.run(count, ts, session);
+      }
+
+      // Eviction: per-session row_count cap. Read fresh count from DB to
+      // accommodate inserts that arrived in a separate transaction.
+      for (const [session] of perSession) {
+        const row = this.#db.prepare(
+          `SELECT row_count FROM session_meta_metrics WHERE session_id = ?`,
+        ).get(session) as { row_count: number } | undefined;
+        if (!row) continue;
+        const overflow = row.row_count - MAX_ROWS_PER_SESSION;
+        if (overflow > 0) {
+          this.#evictOldestStmt!.run(session, overflow);
+          this.#updateRowCountStmt!.run(MAX_ROWS_PER_SESSION, session);
+        }
+      }
+    });
+  }
+
+  // ── Session metadata ────────────────────────────────────────────────
+
+  upsertSession(opts: { session_id: string; cwd: string; ts?: number }): void {
+    const ts = opts.ts ?? Date.now();
+    this.#upsertSessionStmt!.run(opts.session_id, opts.cwd, ts, ts);
+  }
+
+  getSessionMeta(sessionId: string): SessionMetaMetrics | null {
+    const row = this.#db.prepare(
+      `SELECT session_id, cwd, started_at, last_event_at, row_count, write_failures, last_clear_at
+         FROM session_meta_metrics
+         WHERE session_id = ?`,
+    ).get(sessionId) as SessionMetaMetrics | undefined;
+    return row ?? null;
+  }
+
+  getProjectMeta(projectSlug: string): ProjectMetaMetrics | null {
+    const row = this.#db.prepare(
+      `SELECT project_slug, first_run_notice_shown_at, last_prune_at, last_clear_all_at
+         FROM project_meta_metrics
+         WHERE project_slug = ?`,
+    ).get(projectSlug) as ProjectMetaMetrics | undefined;
+    return row ?? null;
+  }
+
+  setFirstRunNoticeShown(projectSlug: string, ts?: number): void {
+    const value = ts ?? Date.now();
+    this.#db.prepare(
+      `INSERT INTO project_meta_metrics (project_slug, first_run_notice_shown_at)
+         VALUES (?, ?)
+         ON CONFLICT(project_slug) DO UPDATE SET
+           first_run_notice_shown_at = excluded.first_run_notice_shown_at`,
+    ).run(projectSlug, value);
+  }
+
+  // ── Hot-path write API ───────────────────────────────────────────────
+
+  record(row: MetricRow): void {
+    if (this.#closed) {
+      this.#bumpInMemoryFailure(row.session_id);
+      this.#trace("metrics_record_after_close", {
+        session_id: row.session_id,
+        tool: row.tool,
+      });
+      return;
+    }
+
+    this.#queue.push(row);
+    if (!this.#flushScheduled) {
+      this.#flushScheduled = true;
+      this.#flushPromise = new Promise<void>((resolve) => {
+        this.#flushResolve = resolve;
+      });
+      queueMicrotask(() => this.#flush());
+    }
+  }
+
+  /** Drain the pending microtask flush. Tests await this before reading state. */
+  async flushPendingForTest(): Promise<void> {
+    while (this.#flushScheduled) {
+      const promise = this.#flushPromise;
+      if (promise) await promise;
+      else break;
+    }
+  }
+
+  #flush(): void {
+    const rows = this.#queue;
+    this.#queue = [];
+    this.#flushScheduled = false;
+    this.#flushCount += 1;
+
+    const resolve = this.#flushResolve;
+    this.#flushResolve = null;
+    this.#flushPromise = null;
+
+    if (rows.length === 0) {
+      if (resolve) resolve();
+      return;
+    }
+
+    let attempts = 0;
+    while (true) {
+      try {
+        this.#flushTransaction!(rows);
+        for (const row of rows) {
+          this.#trace("metrics_record_flushed", {
+            tool: row.tool,
+            layer: row.layer,
+            before_bytes: row.before_bytes,
+            after_bytes: row.after_bytes,
+          });
+        }
+        break;
+      } catch (err) {
+        const code = (err as NodeJS.ErrnoException)?.code;
+        if (attempts === 0 && code === "SQLITE_BUSY") {
+          attempts += 1;
+          // Linear backoff (sleep ~5ms) before the single retry.
+          Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5);
+          continue;
+        }
+
+        for (const row of rows) {
+          this.#bumpInMemoryFailure(row.session_id);
+          this.#trace("metrics_record_failed", {
+            tool: row.tool,
+            error: (err as Error)?.message ?? String(err),
+          });
+        }
+        break;
+      }
+    }
+
+    if (resolve) resolve();
+  }
+
+  #bumpInMemoryFailure(sessionId: string): void {
+    this.#inMemoryFailures.set(sessionId, (this.#inMemoryFailures.get(sessionId) ?? 0) + 1);
+  }
+
+  #trace(event: string, data: Record<string, unknown>): void {
+    if (!this.#tracePath) return;
+    appendTraceLine(this.#tracePath, { event, ...data });
+  }
+
+  // ── Read accessors ───────────────────────────────────────────────────
+
+  getSessionTotals(sessionId: string): {
+    beforeBytes: number;
+    afterBytes: number;
+    saved: number;
+    rowCount: number;
+  } {
+    const row = this.#db.prepare(
+      `SELECT
+         COALESCE(SUM(before_bytes), 0) AS beforeBytes,
+         COALESCE(SUM(after_bytes), 0) AS afterBytes,
+         COALESCE(SUM(before_bytes - after_bytes), 0) AS saved,
+         COUNT(*) AS rowCount
+       FROM metrics
+       WHERE session_id = ?`,
+    ).get(sessionId) as {
+      beforeBytes: number;
+      afterBytes: number;
+      saved: number;
+      rowCount: number;
+    };
+    return row;
+  }
+
+  getTopProcessors(
+    sessionId: string,
+    limit: number,
+  ): Array<{ processor: string; saved: number; calls: number }> {
+    return this.#db.prepare(
+      `SELECT
+         COALESCE(processor, tool) AS processor,
+         COALESCE(SUM(before_bytes - after_bytes), 0) AS saved,
+         COUNT(*) AS calls
+       FROM metrics
+       WHERE session_id = ?
+       GROUP BY COALESCE(processor, tool)
+       ORDER BY saved DESC
+       LIMIT ?`,
+    ).all(sessionId, limit) as Array<{ processor: string; saved: number; calls: number }>;
+  }
+
+  getPerLayer(
+    sessionId: string,
+  ): Array<{ layer: string; saved: number; rows: number }> {
+    return this.#db.prepare(
+      `SELECT
+         layer,
+         COALESCE(SUM(before_bytes - after_bytes), 0) AS saved,
+         COUNT(*) AS rows
+       FROM metrics
+       WHERE session_id = ?
+       GROUP BY layer
+       ORDER BY layer ASC`,
+    ).all(sessionId) as Array<{ layer: string; saved: number; rows: number }>;
+  }
+
+  /**
+   * Unique-source share = COUNT(DISTINCT unique_source_hash) /
+   *                       COUNT(unique_source_hash).
+   * Null hashes are excluded from both numerator and denominator so that
+   * untracked sources do not skew the rot signal. Returns 0 when no rows
+   * have a non-null hash.
+   */
+  getUniqueSourceShare(sessionId: string): number {
+    const row = this.#db.prepare(
+      `SELECT
+         COUNT(DISTINCT unique_source_hash) AS distinctCount,
+         COUNT(unique_source_hash) AS totalCount
+       FROM metrics
+       WHERE session_id = ?`,
+    ).get(sessionId) as { distinctCount: number; totalCount: number };
+
+    if (row.totalCount === 0) return 0;
+    return row.distinctCount / row.totalCount;
+  }
+
+  /** Combined in-memory + persisted write-failure count for the session. */
+  getSessionWriteFailures(sessionId: string): number {
+    const inMemory = this.#inMemoryFailures.get(sessionId) ?? 0;
+    let persisted = 0;
+    try {
+      persisted = this.getSessionMeta(sessionId)?.write_failures ?? 0;
+    } catch {
+      // DB may be closed; in-memory counter still surfaces the failure.
+    }
+    return persisted + inMemory;
+  }
+
+  // ── Maintenance ─────────────────────────────────────────────────────
+
+  pruneOldSessions(retentionDays = RETENTION_DAYS, now = Date.now()): number {
+    const cutoff = now - retentionDays * 24 * 60 * 60 * 1000;
+
+    const oldSessions = this.#db.prepare(
+      `SELECT session_id FROM session_meta_metrics WHERE started_at < ?`,
+    ).all(cutoff) as Array<{ session_id: string }>;
+
+    if (oldSessions.length > 0) {
+      const placeholders = oldSessions.map(() => "?").join(",");
+      const ids = oldSessions.map((r) => r.session_id);
+      this.#db.prepare(
+        `DELETE FROM metrics WHERE session_id IN (${placeholders})`,
+      ).run(...ids);
+      this.#db.prepare(
+        `DELETE FROM session_meta_metrics WHERE session_id IN (${placeholders})`,
+      ).run(...ids);
+    }
+
+    this.#db.prepare(
+      `INSERT INTO project_meta_metrics (project_slug, last_prune_at)
+         VALUES (?, ?)
+         ON CONFLICT(project_slug) DO UPDATE SET
+           last_prune_at = excluded.last_prune_at`,
+    ).run(this.#projectSlug, now);
+
+    return oldSessions.length;
+  }
+
+  // \u2500\u2500 Clearing (used by /supi:clear) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+  /** Delete metrics rows for a single session, reset row_count, stamp last_clear_at. */
+  clearSession(sessionId: string, now = Date.now()): void {
+    const tx = this.#db.transaction(() => {
+      this.#db.prepare(`DELETE FROM metrics WHERE session_id = ?`).run(sessionId);
+      this.#db.prepare(
+        `UPDATE session_meta_metrics
+         SET row_count = 0, last_clear_at = ?
+         WHERE session_id = ?`,
+      ).run(now, sessionId);
+    });
+    tx();
+    this.#inMemoryFailures.delete(sessionId);
+  }
+
+  /** Returns one row per session in this project, ordered by started_at desc. */
+  listSessions(
+    _projectSlug: string,
+  ): Array<{ session_id: string; row_count: number; started_at: number; cwd: string }> {
+    return this.#db
+      .prepare(
+        `SELECT session_id, row_count, started_at, cwd
+         FROM session_meta_metrics
+         ORDER BY started_at DESC`,
+      )
+      .all() as Array<{
+        session_id: string;
+        row_count: number;
+        started_at: number;
+        cwd: string;
+      }>;
+  }
+
+  /** Delete all metrics rows in the project, reset every session's row_count,
+   *  preserve session metadata (`started_at`, `cwd`), and stamp
+   *  `project_meta_metrics.last_clear_all_at`.
+   *
+   *  The `projectSlug` parameter is accepted for API symmetry with the rest of
+   *  the project-meta accessors, but the store always operates on its bound
+   *  slug. Callers do not need to pass anything special: the store's own
+   *  projectSlug is the source of truth.
+   */
+  clearProject(_projectSlug?: string, now = Date.now()): void {
+    const slug = this.#projectSlug;
+    const tx = this.#db.transaction(() => {
+      this.#db.exec(`DELETE FROM metrics`);
+      this.#db.exec(`UPDATE session_meta_metrics SET row_count = 0`);
+      this.#db.prepare(
+        `INSERT INTO project_meta_metrics (project_slug, last_clear_all_at)
+         VALUES (?, ?)
+         ON CONFLICT(project_slug) DO UPDATE SET
+           last_clear_all_at = excluded.last_clear_all_at`,
+      ).run(slug, now);
+    });
+    tx();
+    this.#inMemoryFailures.clear();
+  }
+
+  close(): void {
+    if (this.#closed) return;
+
+    // Drain any queued writes synchronously before closing the DB. `record()`
+    // schedules flushes via `queueMicrotask`, so a `record()` followed by an
+    // immediate `close()` (e.g. session_shutdown after the last tool_result)
+    // would otherwise lose pending rows when the microtask later runs against
+    // a closed handle. `#flush()` already swallows write errors and bumps the
+    // in-memory failure counter, so this drain cannot throw.
+    if (this.#queue.length > 0) {
+      this.#flush();
+    }
+
+    this.#closed = true;
+
+    try {
+      try {
+        if (this.#getJournalMode() === "wal") {
+          this.#cleanupWalSidecars();
+        }
+      } catch {
+        // The DB path may already be gone during teardown.
+      }
+    } finally {
+      this.#db.close();
+    }
+  }
+}
+
+// ── Module-level singleton + test seam ─────────────────────────────────
+
+let _metricsStoreRef: MetricsStore | null = null;
+
+/** Return the active metrics store, or `null` when context-mode is disabled. */
+export function getMetricsStore(): MetricsStore | null {
+  return _metricsStoreRef;
+}
+
+/**
+ * Test-only setter. Production code wires the ref through the same path from
+ * inside `registerContextModeHooks`. The double-underscore prefix marks this
+ * as a private API; do **not** call it from product code.
+ */
+export function __setMetricsStoreForTest(store: MetricsStore | null): void {
+  _metricsStoreRef = store;
+}
+
+/** Reset module-level state. Intended for `_resetCache()` in tests. */
+export function _resetMetricsStoreCache(): void {
+  _metricsStoreRef = null;
+}