pi-mega-compact 0.7.8 → 0.7.9

package/src/store/sqlite/global-index.ts

@@ -0,0 +1,305 @@
+/**
+ * global-index.ts — machine-wide index DB (repo registry + injected-set).
+ *
+ * A single SQLite DB, separate from every per-repo store, that aggregates one
+ * row per repo this machine has run on. The multi-repo dashboard (Summary /
+ * All-repos tabs) reads it so ONE dashboard can show every repo's checkpoints,
+ * tokens saved, and active model — instead of a per-repo dashboard that only
+ * ever sees the repo it was launched from.
+ *
+ * Written by every pi process on repo-switch (bindRepo) + model capture; read by
+ * the dashboard server. Concurrency across 10+ pi processes is handled by WAL +
+ * infrequent idempotent upserts (ON CONFLICT). Fully local (PREVENT-PI-004).
+ */
+import { DatabaseSync } from "node:sqlite";
+import { existsSync, mkdirSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+
+/** Resolve the machine-wide index directory (env-overridable). */
+export function getIndexDir(): string {
+  const override = process.env.MEGACOMPACT_INDEX_DIR;
+  if (override && override.trim() !== "") return override;
+  // homedir() can throw in exotic sandboxes; fall back to tmpdir.
+  try {
+    return join(homedir(), ".mega-compact-index");
+  } catch {
+    return join(tmpdir(), ".mega-compact-index");
+  }
+}
+
+let indexCache: DatabaseSync | undefined;
+let indexCacheDir: string | undefined;
+
+/** Open (or reuse) the machine-wide index DB. WAL for concurrent writers. */
+export function openIndexStore(indexDir: string = getIndexDir()): DatabaseSync {
+  if (indexCache && indexCacheDir === indexDir) return indexCache;
+  if (!existsSync(indexDir)) mkdirSync(indexDir, { recursive: true });
+  const iddb = new DatabaseSync(join(indexDir, "index.sqlite"));
+  iddb.exec("PRAGMA journal_mode = WAL");
+  iddb.exec("PRAGMA busy_timeout = 3000"); // tolerate brief cross-process write contention
+  iddb.exec(`
+    CREATE TABLE IF NOT EXISTS repo_registry (
+      repo_root                 TEXT PRIMARY KEY,
+      display_name              TEXT,
+      state_dir                 TEXT NOT NULL,
+      first_seen                INTEGER,
+      last_seen                 INTEGER,
+      last_compacted_at         INTEGER,
+      checkpoint_count          INTEGER DEFAULT 0,
+      tokens_saved              INTEGER DEFAULT 0,
+      compressed_original_bytes INTEGER DEFAULT 0,
+      provider                  TEXT,
+      provider_name             TEXT,
+      model_name                TEXT,
+      input_rate                REAL,
+      output_rate               REAL,
+      model_captured_at         INTEGER
+    );
+    CREATE INDEX IF NOT EXISTS idx_registry_last_seen ON repo_registry(last_seen DESC);
+    -- S18: machine-wide injected-set. A foreign checkpoint injected in repo A is
+    -- recorded here so repo B's recall never re-injects it. Keyed by checkpoint
+    -- + session (a checkpoint may be injected once per session); repo_id is the
+    -- source repo (the foreign repo's stateDir) for tracking/source labels.
+    -- PRAMETERIZED queries (PREVENT-002); local node:sqlite (PREVENT-PI-004).
+    CREATE TABLE IF NOT EXISTS injected_global (
+      checkpoint_id TEXT NOT NULL,
+      repo_id       TEXT NOT NULL,
+      session_id    TEXT NOT NULL,
+      injected_at   INTEGER NOT NULL,
+      PRIMARY KEY (checkpoint_id, session_id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_injected_global_cid ON injected_global(checkpoint_id);
+  `);
+  indexCache = iddb;
+  indexCacheDir = indexDir;
+  return iddb;
+}
+
+/** One row of the global repo registry (multi-repo dashboard source). */
+export interface RepoRegistryRow {
+  repoRoot: string;
+  displayName: string;
+  stateDir: string;
+  firstSeen: number;
+  lastSeen: number;
+  lastCompactedAt: number | null;
+  checkpointCount: number;
+  tokensSaved: number;
+  compressedOriginalBytes: number;
+  provider: string | null;
+  providerName: string | null;
+  modelName: string | null;
+  inputRate: number | null;
+  outputRate: number | null;
+  modelCapturedAt: number | null;
+}
+
+/**
+ * Upsert a repo's aggregate stats into the global index. Called on repo-switch
+ * (infrequent). Preserves first_seen + the model columns on update (model is
+ * written separately by recordRepoModel so we never clobber it here with nulls).
+ */
+export function upsertRepoRegistry(
+  row: {
+    repoRoot: string;
+    displayName: string;
+    stateDir: string;
+    checkpointCount: number;
+    tokensSaved: number;
+    compressedOriginalBytes: number;
+    lastCompactedAt?: number | null;
+    // The fields below are optional passthroughs so test fixtures and the
+    // /api/repos active-window filter can seed them directly. They're also
+    // written by other paths (recordRepoModel, registry refresh) — passing
+    // them here is harmless because the ON CONFLICT clause keeps first_seen
+    // and the model columns from being clobbered.
+    firstSeen?: number;
+    lastSeen?: number;
+    provider?: string | null;
+    providerName?: string | null;
+    modelName?: string | null;
+    inputRate?: number | null;
+    outputRate?: number | null;
+    modelCapturedAt?: number | null;
+  },
+  indexDir: string = getIndexDir(),
+): void {
+  const db = openIndexStore(indexDir);
+  const now = Date.now();
+  db.prepare(
+    `INSERT INTO repo_registry
+       (repo_root, display_name, state_dir, first_seen, last_seen, last_compacted_at,
+        checkpoint_count, tokens_saved, compressed_original_bytes,
+        provider, provider_name, model_name, input_rate, output_rate, model_captured_at)
+     VALUES (@repo_root, @display_name, @state_dir, @first_seen, @last_seen, @last_compacted_at,
+             @checkpoint_count, @tokens_saved, @compressed_original_bytes,
+             @provider, @provider_name, @model_name, @input_rate, @output_rate, @model_captured_at)
+     ON CONFLICT(repo_root) DO UPDATE SET
+       display_name = excluded.display_name,
+       state_dir = excluded.state_dir,
+       last_seen = COALESCE(excluded.last_seen, @now),
+       last_compacted_at = COALESCE(excluded.last_compacted_at, repo_registry.last_compacted_at),
+       checkpoint_count = excluded.checkpoint_count,
+       tokens_saved = excluded.tokens_saved,
+       compressed_original_bytes = excluded.compressed_original_bytes,
+       provider = COALESCE(excluded.provider, repo_registry.provider),
+       provider_name = COALESCE(excluded.provider_name, repo_registry.provider_name),
+       model_name = COALESCE(excluded.model_name, repo_registry.model_name),
+       input_rate = COALESCE(excluded.input_rate, repo_registry.input_rate),
+       output_rate = COALESCE(excluded.output_rate, repo_registry.output_rate),
+       model_captured_at = COALESCE(excluded.model_captured_at, repo_registry.model_captured_at)`,
+  ).run({
+    repo_root: row.repoRoot,
+    display_name: row.displayName,
+    state_dir: row.stateDir,
+    now,
+    first_seen: row.firstSeen ?? null,
+    last_seen: row.lastSeen ?? null,
+    last_compacted_at: row.lastCompactedAt ?? null,
+    checkpoint_count: row.checkpointCount,
+    tokens_saved: row.tokensSaved,
+    compressed_original_bytes: row.compressedOriginalBytes,
+    provider: row.provider ?? null,
+    provider_name: row.providerName ?? null,
+    model_name: row.modelName ?? null,
+    input_rate: row.inputRate ?? null,
+    output_rate: row.outputRate ?? null,
+    model_captured_at: row.modelCapturedAt ?? null,
+  });
+}
+
+/**
+ * Record the active model/provider for a repo in the global index (denormalized
+ * so the All-repos table shows model without opening each repo's DB). Upserts a
+ * bare registry row if the repo isn't registered yet.
+ */
+export function recordRepoModel(
+  repoRoot: string,
+  model: {
+    provider: string;
+    providerName: string | null;
+    modelName: string | null;
+    inputRate: number;
+    outputRate: number;
+    stateDir: string;
+    displayName: string;
+  },
+  indexDir: string = getIndexDir(),
+): void {
+  const db = openIndexStore(indexDir);
+  const now = Date.now();
+  db.prepare(
+    `INSERT INTO repo_registry
+       (repo_root, display_name, state_dir, first_seen, last_seen,
+        provider, provider_name, model_name, input_rate, output_rate, model_captured_at)
+     VALUES (@repo_root, @display_name, @state_dir, @now, @now,
+             @provider, @provider_name, @model_name, @input_rate, @output_rate, @now)
+     ON CONFLICT(repo_root) DO UPDATE SET
+       last_seen = excluded.last_seen,
+       provider = excluded.provider,
+       provider_name = excluded.provider_name,
+       model_name = excluded.model_name,
+       input_rate = excluded.input_rate,
+       output_rate = excluded.output_rate,
+       model_captured_at = excluded.model_captured_at`,
+  ).run({
+    repo_root: repoRoot,
+    display_name: model.displayName,
+    state_dir: model.stateDir,
+    now,
+    provider: model.provider,
+    provider_name: model.providerName,
+    model_name: model.modelName,
+    input_rate: model.inputRate,
+    output_rate: model.outputRate,
+  });
+}
+
+function mapRegistryRow(row: any): RepoRegistryRow {
+  return {
+    repoRoot: row.repo_root,
+    displayName: row.display_name ?? "",
+    stateDir: row.state_dir,
+    firstSeen: row.first_seen ?? 0,
+    lastSeen: row.last_seen ?? 0,
+    lastCompactedAt: row.last_compacted_at ?? null,
+    checkpointCount: row.checkpoint_count ?? 0,
+    tokensSaved: row.tokens_saved ?? 0,
+    compressedOriginalBytes: row.compressed_original_bytes ?? 0,
+    provider: row.provider ?? null,
+    providerName: row.provider_name ?? null,
+    modelName: row.model_name ?? null,
+    inputRate: row.input_rate ?? null,
+    outputRate: row.output_rate ?? null,
+    modelCapturedAt: row.model_captured_at ?? null,
+  };
+}
+
+/** All registered repos, most-recently-seen first. */
+export function listRepoRegistry(indexDir: string = getIndexDir()): RepoRegistryRow[] {
+  const db = openIndexStore(indexDir);
+  const rows = db.prepare("SELECT * FROM repo_registry ORDER BY last_seen DESC").all() as any[];
+  return rows.map(mapRegistryRow);
+}
+
+/** A single repo's registry row, or undefined. */
+export function getRepoRegistry(repoRoot: string, indexDir: string = getIndexDir()): RepoRegistryRow | undefined {
+  const db = openIndexStore(indexDir);
+  const row = db.prepare("SELECT * FROM repo_registry WHERE repo_root = ?").get(repoRoot) as any;
+  return row ? mapRegistryRow(row) : undefined;
+}
+
+/** Close the cached index connection (test teardown only). */
+export function closeIndexStore(): void {
+  if (indexCache) {
+    indexCache.close();
+    indexCache = undefined;
+    indexCacheDir = undefined;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// S18: machine-wide injected-set (cross-repo dedup markers)
+//
+// A foreign checkpoint injected in repo A is recorded here so repo B's recall
+// never re-injects it (a stronger, machine-wide version of the per-session
+// injected-set in the local store). Keyed by (checkpoint_id, session_id); the
+// session_id here is the RECEIVING session, so the same foreign checkpoint can
+// be injected into different sessions but never twice into the same one.
+// PRAMETERIZED queries (PREVENT-002); local node:sqlite + WAL (PREVENT-PI-004),
+// multi-process safe.
+// ---------------------------------------------------------------------------
+
+/** Record that a (foreign) checkpoint was injected into `sessionId`. Idempotent. */
+export function markInjectedGlobal(
+  checkpointId: string,
+  repoId: string,
+  sessionId: string,
+  indexDir: string = getIndexDir(),
+): void {
+  const db = openIndexStore(indexDir);
+  db.prepare(
+    "INSERT OR IGNORE INTO injected_global (checkpoint_id, repo_id, session_id, injected_at) VALUES ($cid, $rid, $sid, $ts)",
+  ).run({ $cid: checkpointId, $rid: repoId, $sid: sessionId, $ts: Date.now() });
+}
+
+/** True when a checkpoint was already injected into `sessionId` (machine-wide). */
+export function wasInjectedGlobal(
+  checkpointId: string,
+  sessionId: string,
+  indexDir: string = getIndexDir(),
+): boolean {
+  const db = openIndexStore(indexDir);
+  const row = db.prepare(
+    "SELECT 1 FROM injected_global WHERE checkpoint_id = $cid AND session_id = $sid LIMIT 1",
+  ).get({ $cid: checkpointId, $sid: sessionId }) as { "1": number } | undefined;
+  return row !== undefined;
+}
+
+/** Count of cross-repo injections recorded (for /mega-status stats). */
+export function countInjectedGlobal(indexDir: string = getIndexDir()): number {
+  const db = openIndexStore(indexDir);
+  const row = db.prepare("SELECT COUNT(*) AS n FROM injected_global").get() as { n: number } | undefined;
+  return row?.n ?? 0;
+}

package/src/store/sqlite/maintenance.ts

@@ -0,0 +1,294 @@
+/**
+ * maintenance.ts — S27 Task 10 DB maintenance / housekeeping primitives.
+ *
+ * All pi-agnostic, all parameterized (PREVENT-002), all local (PREVENT-PI-004).
+ * Exposed via the /mega-db-* slash commands in extensions/mega-db-cmds.ts.
+ */
+import { statSync } from "node:fs";
+import { join } from "node:path";
+import { getStateDir } from "../../store.js";
+import { openStore, withTx } from "./utils.js";
+
+/** Per-table row counts + DB file sizes for the /mega-db-stats command. */
+export interface DbStats {
+  /** Row count per table (keys are table names that exist in this DB). */
+  tableCounts: Record<string, number>;
+  /** Bytes used by the main DB file on disk. */
+  dbBytes: number;
+  /** Bytes used by the -wal sidecar file (0 if absent). */
+  walBytes: number;
+  /** Bytes used by the -shm sidecar file (0 if absent). */
+  shmBytes: number;
+  /** SQLite page size in bytes. */
+  pageSize: number;
+  /** Total pages (freelist + in-use). */
+  pageCount: number;
+  /** Freelist pages (reusable by VACUUM). */
+  freelistPages: number;
+  /** WAL frame count from PRAGMA wal_info (best-effort; 0 if unsupported). */
+  walFrames: number;
+}
+
+const DB_TABLE_NAMES = [
+  "context_chunks",
+  "session_state",
+  "raw_transcript",
+  "checkpoint_epochs",
+  "dedup_mirror",
+  "memories",
+  "dedup_stats",
+  "daily_log",
+] as const;
+
+function fileSizeIfExists(path: string): number {
+  try {
+    const st = statSync(path);
+    return st.size;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Gather DB stats for /mega-db-stats: per-table row counts, disk footprint
+ * (main + WAL + SHM), page count, freelist, WAL frame count.
+ *
+ * Read-only: no PRAGMA writes, no VACUUM. Safe to call any time.
+ */
+export function getDbStats(stateDir: string = getStateDir()): DbStats {
+  const db = openStore(stateDir);
+  const tableCounts: Record<string, number> = {};
+  for (const t of DB_TABLE_NAMES) {
+    try {
+      const row = db.prepare(`SELECT COUNT(*) AS c FROM ${t}`).get() as { c: number } | undefined;
+      if (row) tableCounts[t] = row.c;
+    } catch {
+      // Table doesn't exist on this DB (e.g. raw_transcript on a pre-S27 store).
+      // Skip silently — /mega-db-stats lists only tables that exist.
+    }
+  }
+  const pageStat = db.prepare("PRAGMA page_count").get() as { page_count?: number } | undefined;
+  const freelistStat = db.prepare("PRAGMA freelist_count").get() as { freelist_count?: number } | undefined;
+  const pageSizeStat = db.prepare("PRAGMA page_size").get() as { page_size?: number } | undefined;
+  let walFrames = 0;
+  try {
+    const walInfo = db.prepare("PRAGMA wal_info").get() as { frames?: number } | undefined;
+    walFrames = walInfo?.frames ?? 0;
+  } catch {
+    // node:sqlite may not expose wal_info on all versions; not fatal.
+  }
+  const dbPath = join(stateDir, "sqlite.db");
+  return {
+    tableCounts,
+    dbBytes: fileSizeIfExists(dbPath),
+    walBytes: fileSizeIfExists(`${dbPath}-wal`),
+    shmBytes: fileSizeIfExists(`${dbPath}-shm`),
+    pageSize: pageSizeStat?.page_size ?? 0,
+    pageCount: pageStat?.page_count ?? 0,
+    freelistPages: freelistStat?.freelist_count ?? 0,
+    walFrames,
+  };
+}
+
+/** Result of a prune / VACUUM / checkpoint operation (reclaimed bytes). */
+export interface MaintenanceResult {
+  /** Rows deleted (prune) or pages reclaimed (VACUUM / checkpoint). */
+  affected: number;
+  /** Bytes reclaimed on disk (best-effort: post-op size minus pre-op size). */
+  reclaimedBytes: number;
+  /** Human-readable summary line for the command output. */
+  summary: string;
+}
+
+/**
+ * Prune raw_transcript + checkpoint_epochs rows older than `daysOld`.
+ * Uses `message_timestamp` (raw_transcript) and `created_at` (epochs), both
+ * epoch-ms. Returns the total deleted rows + reclaimed disk bytes.
+ *
+ * PREVENT-002: parameterized. PREVENT-PI-004: local SQLite only.
+ */
+export function pruneOldRows(stateDir: string = getStateDir(), daysOld = 30): MaintenanceResult {
+  const db = openStore(stateDir);
+  const cutoff = Date.now() - daysOld * 86_400_000;
+  const beforeBytes = fileSizeIfExists(join(stateDir, "sqlite.db"));
+  // raw_transcript: message_timestamp may be NULL (pre-S27 rows); those use
+  // the row's insertion order implicitly via seq, so we prune NULL-ts rows
+  // only when the whole session is older than the cutoff (join via session_id
+  // to checkpoint_epochs.created_at). Simpler: prune NULL-ts rows older than
+  // cutoff by falling back to the MIN(created_at) of their epoch.
+  // Delete raw_transcript rows whose message_timestamp is older than cutoff,
+  // OR whose message_timestamp is NULL and the session's latest epoch is older.
+  const delRt = db.prepare(
+    `DELETE FROM raw_transcript
+     WHERE message_timestamp IS NOT NULL AND message_timestamp < ?
+        OR (message_timestamp IS NULL
+            AND session_id IN (
+              SELECT session_id FROM checkpoint_epochs
+              GROUP BY session_id HAVING MAX(created_at) < ?
+            ))`,
+  ).run(cutoff, cutoff) as { changes?: number } | undefined;
+  const rtDeleted = delRt?.changes ?? 0;
+  // checkpoint_epochs: created_at is NOT NULL.
+  const delEp = db.prepare(`DELETE FROM checkpoint_epochs WHERE created_at < ?`).run(cutoff) as {
+    changes?: number;
+  } | undefined;
+  const epDeleted = delEp?.changes ?? 0;
+  // dedup_mirror: cascade-delete orphan rows whose ref_count has dropped to 0
+  // after the raw_transcript deletes. Safe even if FK is off (raw_transcript has
+  // no FK to dedup_mirror; ref_count is maintained by the dedup pipeline).
+  const delDedup = db.prepare(`DELETE FROM dedup_mirror WHERE ref_count <= 0`).run() as {
+    changes?: number;
+  } | undefined;
+  const dedupDeleted = delDedup?.changes ?? 0;
+  const afterBytes = fileSizeIfExists(join(stateDir, "sqlite.db"));
+  const total = rtDeleted + epDeleted + dedupDeleted;
+  return {
+    affected: total,
+    reclaimedBytes: Math.max(0, beforeBytes - afterBytes),
+    summary: `pruned ${rtDeleted} raw_transcript + ${epDeleted} epochs + ${dedupDeleted} dedup_mirror rows older than ${daysOld}d`,
+  };
+}
+
+/**
+ * Force a WAL checkpoint (TRUNCATE mode) so the -wal sidecar is reclaimed.
+ * Returns the WAL bytes reclaimed (pre-wal size minus post-wal size).
+ */
+export function checkpointWal(stateDir: string = getStateDir()): MaintenanceResult {
+  const db = openStore(stateDir);
+  const dbPath = join(stateDir, "sqlite.db");
+  const beforeWal = fileSizeIfExists(`${dbPath}-wal`);
+  // PRAGMA wal_checkpoint(TRUNCATE) blocks until all frames are folded into the
+  // main db and the WAL file is truncated to 0 bytes.
+  const res = db.prepare("PRAGMA wal_checkpoint(TRUNCATE)").get() as {
+    busy?: number;
+    log?: number;
+    checkpointed?: number;
+  } | undefined;
+  const afterWal = fileSizeIfExists(`${dbPath}-wal`);
+  const reclaimed = Math.max(0, beforeWal - afterWal);
+  return {
+    affected: res?.checkpointed ?? 0,
+    reclaimedBytes: reclaimed,
+    summary: `wal_checkpoint(TRUNCATE): ${res?.checkpointed ?? 0} frames folded, WAL ${beforeWal}→${afterWal} bytes${res?.busy ? " (busy: " + res.busy + ")" : ""}`,
+  };
+}
+
+/**
+ * VACUUM the main DB file (rebuilds pages, reclaims freelist space).
+ * Heavy: briefly doubles disk usage. Run only when freelist is large or the
+ * user explicitly invokes /mega-db-vacuum.
+ */
+export function vacuumDb(stateDir: string = getStateDir()): MaintenanceResult {
+  const db = openStore(stateDir);
+  const dbPath = join(stateDir, "sqlite.db");
+  const beforeBytes = fileSizeIfExists(dbPath);
+  db.exec("VACUUM"); // VACUUM cannot be parameterized; it rewrites the whole DB.
+  const afterBytes = fileSizeIfExists(dbPath);
+  const reclaimed = Math.max(0, beforeBytes - afterBytes);
+  return {
+    affected: 0,
+    reclaimedBytes: reclaimed,
+    summary: `VACUUM: db ${beforeBytes}→${afterBytes} bytes (reclaimed ${reclaimed})`,
+  };
+}
+
+/**
+ * Run `PRAGMA integrity_check` and return the result lines.
+ * Returns ["ok"] when the DB is healthy; otherwise returns the error lines.
+ */
+export function integrityCheck(stateDir: string = getStateDir()): string[] {
+  const db = openStore(stateDir);
+  const rows = db.prepare("PRAGMA integrity_check").all() as Array<{ integrity_check: string }> | undefined;
+  return (rows ?? []).map((r) => r.integrity_check);
+}
+
+/** Reconcile drift in dedup_mirror.ref_count vs actual raw_transcript refs. */
+export interface DedupReconcileResult {
+  /** Rows whose ref_count was corrected. */
+  fixedRefCount: number;
+  /** Orphan dedup_mirror rows (content_hash with 0 raw_transcript refs) deleted. */
+  orphansDeleted: number;
+  /** raw_transcript rows whose content_ref was NULL but now set (backfill). */
+  refsBackfilled: number;
+}
+
+/**
+ * Reconcile dedup_mirror vs raw_transcript after pruning or crashes:
+ *   1. Recompute ref_count = COUNT(raw_transcript rows pointing at this hash).
+ *   2. Delete orphan dedup_mirror rows whose recomputed ref_count is 0.
+ *   3. Backfill raw_transcript.content_ref for rows still storing inline bytes.
+ *
+ * Idempotent. Read-modify-write within a single transaction (withTx).
+ */
+export function reconcileDedupMirror(stateDir: string = getStateDir()): DedupReconcileResult {
+  const db = openStore(stateDir);
+  const result: DedupReconcileResult = { fixedRefCount: 0, orphansDeleted: 0, refsBackfilled: 0 };
+  withTx(db, () => {
+    // 1. Recompute ref_count for every dedup_mirror row from the actual
+    //    raw_transcript references.
+    const recompute = db.prepare(
+      `UPDATE dedup_mirror AS dm
+       SET ref_count = COALESCE((
+         SELECT COUNT(*) FROM raw_transcript rt WHERE rt.content_ref = dm.content_hash
+       ), 0)
+       WHERE dm.ref_count != COALESCE((
+         SELECT COUNT(*) FROM raw_transcript rt WHERE rt.content_ref = dm.content_hash
+       ), 0)`,
+    ).run() as { changes?: number } | undefined;
+    result.fixedRefCount = recompute?.changes ?? 0;
+    // 2. Delete orphan dedup_mirror rows (no raw_transcript refs).
+    const delOrphans = db.prepare(
+      `DELETE FROM dedup_mirror
+       WHERE content_hash NOT IN (SELECT DISTINCT content_ref FROM raw_transcript WHERE content_ref IS NOT NULL)`,
+    ).run() as { changes?: number } | undefined;
+    result.orphansDeleted = delOrphans?.changes ?? 0;
+    // 3. Backfill content_ref for rows still storing inline content_bytes (no
+    //    ref yet). Only safe when a matching dedup_mirror row exists; otherwise
+    //    we'd need to insert one, which is the dedup pipeline's job, not the
+    //    reconciler's.
+    const backfill = db.prepare(
+      `UPDATE raw_transcript AS rt
+       SET content_ref = (
+         SELECT dm.content_hash FROM dedup_mirror dm WHERE dm.content_bytes = rt.content_bytes
+       )
+       WHERE rt.content_ref IS NULL
+         AND EXISTS (SELECT 1 FROM dedup_mirror dm WHERE dm.content_bytes = rt.content_bytes)`,
+    ).run() as { changes?: number } | undefined;
+    result.refsBackfilled = backfill?.changes ?? 0;
+  });
+  return result;
+}
+
+/**
+ * One-shot auto-maintenance pass for the session_start hook: prune old rows,
+ * checkpoint the WAL if it's grown large, and (only if the DB is huge) VACUUM.
+ * Best-effort: swallows errors so a session never fails to start over a
+ * housekeeping hiccup. Returns a short summary for the diagnostic log.
+ */
+export function autoMaintain(stateDir: string = getStateDir()): string {
+  try {
+    const stats = getDbStats(stateDir);
+    const parts: string[] = [];
+    // Prune rows older than 30d (default retention).
+    const prune = pruneOldRows(stateDir, 30);
+    if (prune.affected > 0) parts.push(`pruned ${prune.affected}`);
+    // Checkpoint the WAL if it's over 10 MB (avoid pathological WAL growth).
+    if (stats.walBytes > 10 * 1024 * 1024) {
+      const ck = checkpointWal(stateDir);
+      if (ck.reclaimedBytes > 0) parts.push(`wal -${ck.reclaimedBytes}B`);
+    }
+    // VACUUM only if the DB is over 100 MB AND freelist is >20% of pages.
+    if (
+      stats.dbBytes > 100 * 1024 * 1024 &&
+      stats.pageCount > 0 &&
+      stats.freelistPages / stats.pageCount > 0.2
+    ) {
+      const v = vacuumDb(stateDir);
+      if (v.reclaimedBytes > 0) parts.push(`vacuum -${v.reclaimedBytes}B`);
+    }
+    return parts.length ? `auto-maintain: ${parts.join(", ")}` : "auto-maintain: nothing to do";
+  } catch (err) {
+    // Never block session start over housekeeping.
+    return `auto-maintain: skipped (${(err as Error).message})`;
+  }
+}