pi-mega-compact 0.7.4 → 0.7.6

package/README.md

@@ -6,15 +6,18 @@ sessions into a **local SQLite store** and offers **deduped inline recall** —
 running **locally inside the extension**, with **no remote MCP server** and
 **zero network calls at runtime** (PREVENT-PI-004).
 
-> **Current version:** `v0.6.9` — storage backend is **`node:sqlite`**
+> **Current version:** `v0.7.5` — storage backend is **`node:sqlite`**
 > (`DatabaseSync`, a Node ≥22.13 built-in), replacing the old `better-sqlite3`
 > native addon and the per-session gzipped JSON checkpoint files. **Zero native
-> build step, fully local, zero network at runtime.** Legacy
-> `.checkpoints.json.gz` snapshots are retained as disaster-recovery fallbacks
-> and auto-imported on first run. The S24 line ties auto-compact, the tier
-> label, trim depth, and durable-memory review to one **unified pressure
-> signal**, adds a **cross-repo memory-RAG index**, and relieves context
-> **during team runs** (not just at the end).
+> build step, fully local, zero network at runtime.** S27 added a **raw-transcript
+> mirror + dedup pipeline** (byte-stable prompt cache via deterministic epoch
+> nonce) and **DB maintenance /commands** (`/mega-db-stats` · `prune` ·
+> `vacuum` · `check` · `reconcile`) plus best-effort auto-maintenance on
+> `session_start`. Legacy `.checkpoints.json.gz` snapshots are retained as
+> disaster-recovery fallbacks and auto-imported on first run. The S24 line ties
+> auto-compact, the tier label, trim depth, and durable-memory review to one
+> **unified pressure signal**, adds a **cross-repo memory-RAG index**, and
+> relieves context **during team runs** (not just at the end).
 
 ---
 
@@ -234,6 +237,11 @@ The commands (slash commands inside pi):
 | `/mega-view <chkpt\|recent>` | Show a checkpoint's verbatim original region. |
 | `/mega-help` | Explain the toolbar widget terms (live tier, gate, dedup, tokens saved). |
 | `/mega-compat-check` | Detect extension conflicts (duplicate commands / overlapping handlers) across installed pi extensions. |
+| `/mega-db-stats` | Show mega-compact SQLite DB stats: table row counts, disk footprint (db + WAL + SHM), page count, freelist %, WAL frames. Read-only; safe any time. |
+| `/mega-db-prune [days]` | DELETE `raw_transcript` + `checkpoint_epochs` rows older than N days (default 30) + orphan `dedup_mirror` rows. Reports deleted counts + reclaimed bytes. |
+| `/mega-db-vacuum` | `VACUUM` the DB (rebuild pages, reclaim freelist). Heavy: briefly doubles disk usage. |
+| `/mega-db-check` | `PRAGMA integrity_check` + `wal_checkpoint(TRUNCATE)`. Fold the WAL into the main file and verify DB health. Use after a crash. |
+| `/mega-db-reconcile` | Fix `dedup_mirror.ref_count` drift vs actual `raw_transcript` refs, delete orphan dedup rows, backfill missing `content_ref`. Run after `/mega-db-prune` or a crash. |
 
 The **tier** you see in the toolbar and dashboard is a *live pressure band* (`low` → `medium` → `high` → `ultra` → `mega`) that climbs automatically as your context window fills and falls back as it's relieved — it is driven by `currentTokens / effectiveThreshold`, not a manual setting. The base compaction *threshold* is set by `MEGACOMPACT_TIER` at startup as a **% of the model context window** (`low` 50% · `medium` 60% · `high` 70% · `ultra` 70% · `mega` 75%; default `low`) — the fire point is `tierPct × contextWindow`, so it always lands below pi's native ~80% auto-compaction (any model size). The old static token amounts (50k/100k/200k/1M/10M) are now only the boot fallback used before the first context event reports a window. `/mega-tier` was removed in v0.6.0. Higher pressure also deepens the live trim and reviews durable memory more often — the whole system reacts as one.
 | `/mega-dashboard` | Start the **localhost-only** live dashboard and open it in a browser (token gauge, store stats, live event stream, per-repo + cross-repo drift). |
@@ -259,6 +267,13 @@ Above the pi editor the extension shows a compact widget:
 - **Dedup hit rate** — % of checkpoints collapsed as duplicates
 - **Active agents / turn** — sub-agent count and conversation turn (when > 0)
 
+> **DB housekeeping** — `/mega-db-stats` / `prune` / `vacuum` / `check` / `reconcile`
+> give you manual control over the SQLite store. In addition, a best-effort
+> **auto-maintenance** pass runs on `session_start`: it prunes rows older than
+> 30d, checkpoints the WAL if it's over 10 MB, and VACUUMs if the DB is over
+> 100 MB AND the freelist is >20% of pages. It never blocks session start and
+> logs a one-line summary to the diagnostic log. (v0.7.5+)
+
 ---
 
 ## Configuration (env-backed)

package/dist/extensions/mega-compact.js

@@ -30,6 +30,7 @@ import { registerEventHandlers } from "./mega-events.js";
 import { registerCommands } from "./mega-commands.js";
 import { registerDashboardCommands } from "./mega-dashboard-cmds.js";
 import { registerConflictCommands } from "./mega-conflict-cmds.js";
+import { registerDbCommands } from "./mega-db-cmds.js";
 export default function (pi) {
     const config = loadConfig();
     const runtime = new MegaRuntime(config);
@@ -37,4 +38,5 @@ export default function (pi) {
     registerCommands(pi, runtime, config);
     registerDashboardCommands(pi, runtime);
     registerConflictCommands(pi, runtime);
+    registerDbCommands(pi, runtime);
 }

package/dist/extensions/mega-db-cmds.js

@@ -0,0 +1,85 @@
+/**
+ * mega-db-cmds.ts — S27 Task 10 DB maintenance /commands.
+ *
+ * Registers /mega-db-stats, /mega-db-prune, /mega-db-vacuum, /mega-db-check,
+ * /mega-db-reconcile slash commands backed by the maintenance primitives in
+ * src/store/sqlite.ts. All operations are local SQLite (PREVENT-PI-004) with
+ * parameterized queries (PREVENT-002).
+ *
+ * Auto-maintenance (prune + WAL checkpoint) also runs once per session_start
+ * via the wiring in mega-events.ts (best-effort, non-blocking).
+ */
+import { getDbStats, pruneOldRows, checkpointWal, vacuumDb, integrityCheck, reconcileDedupMirror, } from "../src/store/sqlite.js";
+/** Format a byte count as a human-readable string (KB / MB / GB). */
+function fmtBytes(n) {
+    if (n < 1024)
+        return `${n}B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)}KB`;
+    if (n < 1024 * 1024 * 1024)
+        return `${(n / (1024 * 1024)).toFixed(1)}MB`;
+    return `${(n / (1024 * 1024 * 1024)).toFixed(2)}GB`;
+}
+/** Register the /mega-db-* maintenance commands. */
+export function registerDbCommands(pi, runtime) {
+    const stateDir = runtime.currentStateDir;
+    pi.registerCommand("mega-db-stats", {
+        description: "Show mega-compact SQLite DB stats: table row counts, disk footprint (db + WAL + SHM), page count, freelist, WAL frames.",
+        handler: async (_args, ctx) => {
+            const s = getDbStats(stateDir);
+            ctx.ui.notify(`[mega-compact] DB stats — ${stateDir}`);
+            ctx.ui.notify(`  main: ${fmtBytes(s.dbBytes)}  wal: ${fmtBytes(s.walBytes)}  shm: ${fmtBytes(s.shmBytes)}`);
+            ctx.ui.notify(`  pages: ${s.pageCount} (${s.pageSize}B each), freelist: ${s.freelistPages} (${s.pageCount > 0 ? ((s.freelistPages / s.pageCount) * 100).toFixed(1) : "0"}% reusable), wal frames: ${s.walFrames}`);
+            const tableLines = Object.entries(s.tableCounts)
+                .sort((a, b) => b[1] - a[1])
+                .map(([t, c]) => `  ${t.padEnd(22)} ${String(c).padStart(8)}`);
+            if (tableLines.length === 0) {
+                ctx.ui.notify("  (no tables populated yet)");
+            }
+            else {
+                ctx.ui.notify("  table row counts:");
+                for (const l of tableLines)
+                    ctx.ui.notify(l);
+            }
+        },
+    });
+    pi.registerCommand("mega-db-prune", {
+        description: "Prune raw_transcript + checkpoint_epochs + orphan dedup_mirror rows older than N days (default 30). Usage: /mega-db-prune [days]",
+        handler: async (args, ctx) => {
+            const days = Number.parseInt(args.trim().split(/\s+/)[0] ?? "30", 10);
+            const d = Number.isFinite(days) && days > 0 ? days : 30;
+            const r = pruneOldRows(stateDir, d);
+            ctx.ui.notify(`[mega-compact] ${r.summary} (reclaimed ${fmtBytes(r.reclaimedBytes)})`);
+        },
+    });
+    pi.registerCommand("mega-db-vacuum", {
+        description: "VACUUM the mega-compact SQLite DB (rebuild pages, reclaim freelist space). Heavy: briefly doubles disk usage.",
+        handler: async (_args, ctx) => {
+            const r = vacuumDb(stateDir);
+            ctx.ui.notify(`[mega-compact] ${r.summary}`);
+        },
+    });
+    pi.registerCommand("mega-db-check", {
+        description: "Run PRAGMA integrity_check + a WAL checkpoint on the mega-compact SQLite DB. Use after a crash or to fold the WAL into the main file.",
+        handler: async (_args, ctx) => {
+            const lines = integrityCheck(stateDir);
+            const healthy = lines.length === 1 && lines[0] === "ok";
+            ctx.ui.notify(`[mega-compact] integrity_check: ${healthy ? "✓ ok" : `⚠ ${lines.length} issue(s)`}`);
+            if (!healthy) {
+                for (const l of lines.slice(0, 10))
+                    ctx.ui.notify(`  ${l}`);
+                if (lines.length > 10)
+                    ctx.ui.notify(`  … and ${lines.length - 10} more`);
+            }
+            const ck = checkpointWal(stateDir);
+            ctx.ui.notify(`[mega-compact] ${ck.summary}`);
+        },
+    });
+    pi.registerCommand("mega-db-reconcile", {
+        description: "Reconcile dedup_mirror.ref_count vs actual raw_transcript refs: fix drift, delete orphan dedup rows, backfill missing content_ref. Run after /mega-db-prune or a crash.",
+        handler: async (_args, ctx) => {
+            const r = reconcileDedupMirror(stateDir);
+            ctx.ui.notify(`[mega-compact] dedup reconcile: fixed ${r.fixedRefCount} ref_count drift, deleted ${r.orphansDeleted} orphan(s), backfilled ${r.refsBackfilled} content_ref`);
+        },
+    });
+}

package/dist/extensions/mega-events.js

@@ -7,7 +7,7 @@
  * sync and delegates the heavy lifting to the pipeline + command modules.
  */
 import { normalizeSessionId } from "../src/store.js";
-import { openStore, appendRawTranscript, writeCheckpointEpoch } from "../src/store/sqlite.js";
+import { openStore, appendRawTranscript, writeCheckpointEpoch, autoMaintain } from "../src/store/sqlite.js";
 import { epochIdFor } from "../src/mirror/epoch.js";
 import { autoCompactCheck } from "../src/compact.js";
 import { estimateSessionTokens, estimateBlockTokens } from "../src/tokens.js";
@@ -116,6 +116,18 @@ export function registerEventHandlers(pi, runtime, config) {
                 runtime.logger.warn("memory-recall skipped", { err: String(err) });
             }
         }
+        // S27 Task 10: best-effort auto-maintenance on session start (prune rows
+        // older than 30d, checkpoint WAL if >10MB, VACUUM if DB >100MB + >20%
+        // freelist). Never blocks session start — swallows errors and logs a
+        // one-line summary for diagnostics.
+        try {
+            const m = autoMaintain(runtime.currentStateDir);
+            if (m && !m.endsWith("nothing to do"))
+                runtime.logger.info("db-auto-maintain", { result: m });
+        }
+        catch (e) {
+            runtime.logger.warn("db-auto-maintain-fail", { error: String(e) });
+        }
         runtime.dashboard.event("session_start", {
             reason: event.reason,
             sessionId: runtime.rt.sessionId,

package/dist/src/store/sqlite.dbmaint.test.js

@@ -0,0 +1,158 @@
+/**
+ * Tests for S27 Task 10 DB maintenance primitives.
+ *
+ * Covers getDbStats, pruneOldRows, checkpointWal, vacuumDb, integrityCheck,
+ * reconcileDedupMirror, autoMaintain. All against a tmp SQLite store.
+ */
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { openStore, appendRawTranscript, writeCheckpointEpoch, upsertDedupMirror, updateRawTranscriptRef, getDbStats, pruneOldRows, checkpointWal, vacuumDb, integrityCheck, reconcileDedupMirror, autoMaintain, } from "./sqlite.js";
+function makeTmp() {
+    return mkdtempSync(join(tmpdir(), "dbmaint-test-"));
+}
+function makeRow(overrides = {}) {
+    return {
+        contentHash: `hash-${Math.random().toString(36).slice(2, 10)}`,
+        sessionId: "sess-1",
+        seq: 0,
+        role: "user",
+        contentBytes: "hello world",
+        toolName: null,
+        messageTimestamp: Date.now(),
+        checkpointEpoch: "epoch-1",
+        ...overrides,
+    };
+}
+function makeEpoch(overrides = {}) {
+    return {
+        epochId: `epoch-${Math.random().toString(36).slice(2, 10)}`,
+        sessionId: "sess-1",
+        startedSeq: 0,
+        committedSeq: 10,
+        checkpointId: "cp-1",
+        cutIndex: 10,
+        summaryMessageText: "test summary",
+        createdAt: Date.now(),
+        ...overrides,
+    };
+}
+describe("DB maintenance primitives (S27 Task 10)", () => {
+    let dir;
+    let db;
+    beforeEach(() => {
+        dir = makeTmp();
+        db = openStore(dir);
+    });
+    afterEach(() => {
+        rmSync(dir, { recursive: true, force: true });
+    });
+    describe("getDbStats", () => {
+        it("returns zero counts on an empty store", () => {
+            const s = getDbStats(dir);
+            assert.equal(s.tableCounts.raw_transcript, 0);
+            assert.equal(s.tableCounts.checkpoint_epochs, 0);
+            assert.equal(s.tableCounts.dedup_mirror, 0);
+            // main DB file exists (schema was written)
+            assert.ok(s.dbBytes > 0);
+            assert.ok(s.pageSize > 0);
+            assert.ok(s.pageCount > 0);
+        });
+        it("counts rows after inserts", () => {
+            appendRawTranscript(db, makeRow());
+            appendRawTranscript(db, makeRow());
+            const s = getDbStats(dir);
+            assert.equal(s.tableCounts.raw_transcript, 2);
+        });
+    });
+    describe("pruneOldRows", () => {
+        it("deletes nothing when all rows are recent", () => {
+            appendRawTranscript(db, makeRow({ messageTimestamp: Date.now() }));
+            const r = pruneOldRows(dir, 30);
+            assert.equal(r.affected, 0);
+        });
+        it("deletes raw_transcript rows older than the cutoff", () => {
+            const oldTs = Date.now() - 31 * 86_400_000;
+            appendRawTranscript(db, makeRow({ messageTimestamp: oldTs }));
+            appendRawTranscript(db, makeRow({ messageTimestamp: Date.now() }));
+            const r = pruneOldRows(dir, 30);
+            assert.equal(r.affected, 1);
+            assert.equal(getDbStats(dir).tableCounts.raw_transcript, 1);
+        });
+        it("deletes checkpoint_epochs older than the cutoff", () => {
+            const oldTs = Date.now() - 40 * 86_400_000;
+            writeCheckpointEpoch(db, makeEpoch({ createdAt: oldTs }));
+            writeCheckpointEpoch(db, makeEpoch({ createdAt: Date.now() }));
+            const r = pruneOldRows(dir, 30);
+            assert.equal(r.affected, 1);
+            assert.equal(getDbStats(dir).tableCounts.checkpoint_epochs, 1);
+        });
+    });
+    describe("integrityCheck", () => {
+        it("returns ['ok'] on a healthy DB", () => {
+            const lines = integrityCheck(dir);
+            assert.deepEqual(lines, ["ok"]);
+        });
+    });
+    describe("checkpointWal", () => {
+        it("runs without error and reports checkpointed frames", () => {
+            const r = checkpointWal(dir);
+            assert.ok(r.summary.includes("wal_checkpoint(TRUNCATE)"));
+        });
+    });
+    describe("vacuumDb", () => {
+        it("rebuilds the DB file", () => {
+            appendRawTranscript(db, makeRow());
+            const r = vacuumDb(dir);
+            assert.ok(r.summary.includes("VACUUM"));
+            // DB file still exists after vacuum
+            assert.ok(statSync(join(dir, "sqlite.db")).size > 0);
+        });
+    });
+    describe("reconcileDedupMirror", () => {
+        it("fixes ref_count drift and deletes orphans", () => {
+            // Insert a dedup_mirror row with ref_count = 5 (drift: actual refs = 1).
+            const hash = "hash-recon-1";
+            upsertDedupMirror(db, hash, "content-bytes-1", 0);
+            // Force a drift: bump ref_count without a matching raw_transcript row.
+            db.prepare("UPDATE dedup_mirror SET ref_count = 5 WHERE content_hash = ?").run(hash);
+            // Insert one raw_transcript row pointing at it. appendRawTranscript auto-
+            // assigns seq = MAX(seq)+1 = 1 for the first row in this session.
+            appendRawTranscript(db, makeRow({ contentHash: "rt-recon-1" }));
+            updateRawTranscriptRef(db, "sess-1", 1, hash);
+            const r = reconcileDedupMirror(dir);
+            // ref_count should now be 1 (one raw_transcript row points at it).
+            const dm = db
+                .prepare("SELECT ref_count FROM dedup_mirror WHERE content_hash = ?")
+                .get(hash);
+            assert.equal(dm?.ref_count, 1);
+            assert.equal(r.fixedRefCount, 1);
+        });
+        it("deletes orphan dedup_mirror rows (no raw_transcript refs)", () => {
+            // Insert a dedup_mirror row with ref_count > 0 but NO raw_transcript ref.
+            const hash = "hash-orphan-1";
+            upsertDedupMirror(db, hash, "orphan-content", 0);
+            db.prepare("UPDATE dedup_mirror SET ref_count = 3 WHERE content_hash = ?").run(hash);
+            const r = reconcileDedupMirror(dir);
+            const exists = db
+                .prepare("SELECT 1 FROM dedup_mirror WHERE content_hash = ?")
+                .get(hash);
+            assert.equal(exists, undefined);
+            assert.ok(r.orphansDeleted > 0);
+        });
+    });
+    describe("autoMaintain", () => {
+        it("runs best-effort and returns a summary string", () => {
+            appendRawTranscript(db, makeRow());
+            const result = autoMaintain(dir);
+            assert.ok(typeof result === "string");
+            assert.ok(result.startsWith("auto-maintain:"));
+        });
+        it("reports nothing to do on a fresh empty DB", () => {
+            const result = autoMaintain(dir);
+            assert.equal(result, "auto-maintain: nothing to do");
+        });
+    });
+});

package/dist/src/store/sqlite.js

@@ -17,7 +17,7 @@
  * All queries are parameterized (PREVENT-002) — never string-concatenated.
  */
 import { DatabaseSync } from "node:sqlite";
-import { existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, statSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { getStateDir } from "../store.js";
@@ -1359,3 +1359,228 @@ export function updateRawTranscriptRef(db, sessionId, seq, contentHash) {
         "@seq": seq,
     });
 }
+const DB_TABLE_NAMES = [
+    "context_chunks",
+    "session_state",
+    "raw_transcript",
+    "checkpoint_epochs",
+    "dedup_mirror",
+    "memories",
+    "dedup_stats",
+    "daily_log",
+];
+function fileSizeIfExists(path) {
+    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 = getStateDir()) {
+    const db = openStore(stateDir);
+    const tableCounts = {};
+    for (const t of DB_TABLE_NAMES) {
+        try {
+            const row = db.prepare(`SELECT COUNT(*) AS c FROM ${t}`).get();
+            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();
+    const freelistStat = db.prepare("PRAGMA freelist_count").get();
+    const pageSizeStat = db.prepare("PRAGMA page_size").get();
+    let walFrames = 0;
+    try {
+        const walInfo = db.prepare("PRAGMA wal_info").get();
+        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,
+    };
+}
+/**
+ * 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 = getStateDir(), daysOld = 30) {
+    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);
+    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);
+    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();
+    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 = getStateDir()) {
+    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();
+    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 = getStateDir()) {
+    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 = getStateDir()) {
+    const db = openStore(stateDir);
+    const rows = db.prepare("PRAGMA integrity_check").all();
+    return (rows ?? []).map((r) => r.integrity_check);
+}
+/**
+ * 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 = getStateDir()) {
+    const db = openStore(stateDir);
+    const result = { 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();
+        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();
+        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();
+        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 = getStateDir()) {
+    try {
+        const stats = getDbStats(stateDir);
+        const parts = [];
+        // 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.message})`;
+    }
+}

package/extensions/mega-compact.ts

@@ -32,6 +32,7 @@ import { registerEventHandlers } from "./mega-events.js";
 import { registerCommands } from "./mega-commands.js";
 import { registerDashboardCommands } from "./mega-dashboard-cmds.js";
 import { registerConflictCommands } from "./mega-conflict-cmds.js";
+import { registerDbCommands } from "./mega-db-cmds.js";
 
 export default function (pi: ExtensionAPI) {
   const config = loadConfig();
@@ -40,4 +41,5 @@ export default function (pi: ExtensionAPI) {
   registerCommands(pi, runtime, config);
   registerDashboardCommands(pi, runtime);
   registerConflictCommands(pi, runtime);
+  registerDbCommands(pi, runtime);
 }

package/extensions/mega-db-cmds.ts

@@ -0,0 +1,107 @@
+/**
+ * mega-db-cmds.ts — S27 Task 10 DB maintenance /commands.
+ *
+ * Registers /mega-db-stats, /mega-db-prune, /mega-db-vacuum, /mega-db-check,
+ * /mega-db-reconcile slash commands backed by the maintenance primitives in
+ * src/store/sqlite.ts. All operations are local SQLite (PREVENT-PI-004) with
+ * parameterized queries (PREVENT-002).
+ *
+ * Auto-maintenance (prune + WAL checkpoint) also runs once per session_start
+ * via the wiring in mega-events.ts (best-effort, non-blocking).
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { MegaRuntime } from "./mega-runtime.js";
+import {
+  getDbStats,
+  pruneOldRows,
+  checkpointWal,
+  vacuumDb,
+  integrityCheck,
+  reconcileDedupMirror,
+  type DedupReconcileResult,
+} from "../src/store/sqlite.js";
+
+/** Format a byte count as a human-readable string (KB / MB / GB). */
+function fmtBytes(n: number): string {
+  if (n < 1024) return `${n}B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)}KB`;
+  if (n < 1024 * 1024 * 1024) return `${(n / (1024 * 1024)).toFixed(1)}MB`;
+  return `${(n / (1024 * 1024 * 1024)).toFixed(2)}GB`;
+}
+
+/** Register the /mega-db-* maintenance commands. */
+export function registerDbCommands(pi: ExtensionAPI, runtime: MegaRuntime): void {
+  const stateDir = runtime.currentStateDir;
+
+  pi.registerCommand("mega-db-stats", {
+    description:
+      "Show mega-compact SQLite DB stats: table row counts, disk footprint (db + WAL + SHM), page count, freelist, WAL frames.",
+    handler: async (_args: string, ctx: ExtensionContext) => {
+      const s = getDbStats(stateDir);
+      ctx.ui.notify(`[mega-compact] DB stats — ${stateDir}`);
+      ctx.ui.notify(`  main: ${fmtBytes(s.dbBytes)}  wal: ${fmtBytes(s.walBytes)}  shm: ${fmtBytes(s.shmBytes)}`);
+      ctx.ui.notify(
+        `  pages: ${s.pageCount} (${s.pageSize}B each), freelist: ${s.freelistPages} (${s.pageCount > 0 ? ((s.freelistPages / s.pageCount) * 100).toFixed(1) : "0"}% reusable), wal frames: ${s.walFrames}`,
+      );
+      const tableLines = Object.entries(s.tableCounts)
+        .sort((a, b) => b[1] - a[1])
+        .map(([t, c]) => `  ${t.padEnd(22)} ${String(c).padStart(8)}`);
+      if (tableLines.length === 0) {
+        ctx.ui.notify("  (no tables populated yet)");
+      } else {
+        ctx.ui.notify("  table row counts:");
+        for (const l of tableLines) ctx.ui.notify(l);
+      }
+    },
+  });
+
+  pi.registerCommand("mega-db-prune", {
+    description:
+      "Prune raw_transcript + checkpoint_epochs + orphan dedup_mirror rows older than N days (default 30). Usage: /mega-db-prune [days]",
+    handler: async (args: string, ctx: ExtensionContext) => {
+      const days = Number.parseInt(args.trim().split(/\s+/)[0] ?? "30", 10);
+      const d = Number.isFinite(days) && days > 0 ? days : 30;
+      const r = pruneOldRows(stateDir, d);
+      ctx.ui.notify(`[mega-compact] ${r.summary} (reclaimed ${fmtBytes(r.reclaimedBytes)})`);
+    },
+  });
+
+  pi.registerCommand("mega-db-vacuum", {
+    description:
+      "VACUUM the mega-compact SQLite DB (rebuild pages, reclaim freelist space). Heavy: briefly doubles disk usage.",
+    handler: async (_args: string, ctx: ExtensionContext) => {
+      const r = vacuumDb(stateDir);
+      ctx.ui.notify(`[mega-compact] ${r.summary}`);
+    },
+  });
+
+  pi.registerCommand("mega-db-check", {
+    description:
+      "Run PRAGMA integrity_check + a WAL checkpoint on the mega-compact SQLite DB. Use after a crash or to fold the WAL into the main file.",
+    handler: async (_args: string, ctx: ExtensionContext) => {
+      const lines = integrityCheck(stateDir);
+      const healthy = lines.length === 1 && lines[0] === "ok";
+      ctx.ui.notify(
+        `[mega-compact] integrity_check: ${healthy ? "✓ ok" : `⚠ ${lines.length} issue(s)`}`,
+      );
+      if (!healthy) {
+        for (const l of lines.slice(0, 10)) ctx.ui.notify(`  ${l}`);
+        if (lines.length > 10) ctx.ui.notify(`  … and ${lines.length - 10} more`);
+      }
+      const ck = checkpointWal(stateDir);
+      ctx.ui.notify(`[mega-compact] ${ck.summary}`);
+    },
+  });
+
+  pi.registerCommand("mega-db-reconcile", {
+    description:
+      "Reconcile dedup_mirror.ref_count vs actual raw_transcript refs: fix drift, delete orphan dedup rows, backfill missing content_ref. Run after /mega-db-prune or a crash.",
+    handler: async (_args: string, ctx: ExtensionContext) => {
+      const r: DedupReconcileResult = reconcileDedupMirror(stateDir);
+      ctx.ui.notify(
+        `[mega-compact] dedup reconcile: fixed ${r.fixedRefCount} ref_count drift, deleted ${r.orphansDeleted} orphan(s), backfilled ${r.refsBackfilled} content_ref`,
+      );
+    },
+  });
+}

package/extensions/mega-events.ts

@@ -16,7 +16,7 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import { normalizeSessionId } from "../src/store.js";
-import { openStore, appendRawTranscript, writeCheckpointEpoch, type CheckpointEpoch } from "../src/store/sqlite.js";
+import { openStore, appendRawTranscript, writeCheckpointEpoch, autoMaintain, type CheckpointEpoch } from "../src/store/sqlite.js";
 import { epochIdFor } from "../src/mirror/epoch.js";
 import { autoCompactCheck } from "../src/compact.js";
 import { estimateSessionTokens, estimateBlockTokens } from "../src/tokens.js";
@@ -158,6 +158,16 @@ export function registerEventHandlers(
 				runtime.logger.warn("memory-recall skipped", { err: String(err) });
 			}
 		}
+		// S27 Task 10: best-effort auto-maintenance on session start (prune rows
+		// older than 30d, checkpoint WAL if >10MB, VACUUM if DB >100MB + >20%
+		// freelist). Never blocks session start — swallows errors and logs a
+		// one-line summary for diagnostics.
+		try {
+			const m = autoMaintain(runtime.currentStateDir);
+			if (m && !m.endsWith("nothing to do")) runtime.logger.info("db-auto-maintain", { result: m });
+		} catch (e) {
+			runtime.logger.warn("db-auto-maintain-fail", { error: String(e) });
+		}
 		runtime.dashboard.event("session_start", {
 			reason: event.reason,
 			sessionId: runtime.rt.sessionId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.7.4",
+  "version": "0.7.6",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-2-Clause",

package/src/store/sqlite.dbmaint.test.ts

@@ -0,0 +1,193 @@
+/**
+ * Tests for S27 Task 10 DB maintenance primitives.
+ *
+ * Covers getDbStats, pruneOldRows, checkpointWal, vacuumDb, integrityCheck,
+ * reconcileDedupMirror, autoMaintain. All against a tmp SQLite store.
+ */
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  openStore,
+  appendRawTranscript,
+  writeCheckpointEpoch,
+  upsertDedupMirror,
+  updateRawTranscriptRef,
+  getDbStats,
+  pruneOldRows,
+  checkpointWal,
+  vacuumDb,
+  integrityCheck,
+  reconcileDedupMirror,
+  autoMaintain,
+  type RawTranscriptRow,
+  type CheckpointEpoch,
+} from "./sqlite.js";
+
+function makeTmp(): string {
+  return mkdtempSync(join(tmpdir(), "dbmaint-test-"));
+}
+
+function makeRow(overrides: Partial<RawTranscriptRow> = {}): RawTranscriptRow {
+  return {
+    contentHash: `hash-${Math.random().toString(36).slice(2, 10)}`,
+    sessionId: "sess-1",
+    seq: 0,
+    role: "user",
+    contentBytes: "hello world",
+    toolName: null,
+    messageTimestamp: Date.now(),
+    checkpointEpoch: "epoch-1",
+    ...overrides,
+  };
+}
+
+function makeEpoch(overrides: Partial<CheckpointEpoch> = {}): CheckpointEpoch {
+  return {
+    epochId: `epoch-${Math.random().toString(36).slice(2, 10)}`,
+    sessionId: "sess-1",
+    startedSeq: 0,
+    committedSeq: 10,
+    checkpointId: "cp-1",
+    cutIndex: 10,
+    summaryMessageText: "test summary",
+    createdAt: Date.now(),
+    ...overrides,
+  };
+}
+
+describe("DB maintenance primitives (S27 Task 10)", () => {
+  let dir: string;
+  let db: ReturnType<typeof openStore>;
+
+  beforeEach(() => {
+    dir = makeTmp();
+    db = openStore(dir);
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  describe("getDbStats", () => {
+    it("returns zero counts on an empty store", () => {
+      const s = getDbStats(dir);
+      assert.equal(s.tableCounts.raw_transcript, 0);
+      assert.equal(s.tableCounts.checkpoint_epochs, 0);
+      assert.equal(s.tableCounts.dedup_mirror, 0);
+      // main DB file exists (schema was written)
+      assert.ok(s.dbBytes > 0);
+      assert.ok(s.pageSize > 0);
+      assert.ok(s.pageCount > 0);
+    });
+
+    it("counts rows after inserts", () => {
+      appendRawTranscript(db, makeRow());
+      appendRawTranscript(db, makeRow());
+      const s = getDbStats(dir);
+      assert.equal(s.tableCounts.raw_transcript, 2);
+    });
+  });
+
+  describe("pruneOldRows", () => {
+    it("deletes nothing when all rows are recent", () => {
+      appendRawTranscript(db, makeRow({ messageTimestamp: Date.now() }));
+      const r = pruneOldRows(dir, 30);
+      assert.equal(r.affected, 0);
+    });
+
+    it("deletes raw_transcript rows older than the cutoff", () => {
+      const oldTs = Date.now() - 31 * 86_400_000;
+      appendRawTranscript(db, makeRow({ messageTimestamp: oldTs }));
+      appendRawTranscript(db, makeRow({ messageTimestamp: Date.now() }));
+      const r = pruneOldRows(dir, 30);
+      assert.equal(r.affected, 1);
+      assert.equal(getDbStats(dir).tableCounts.raw_transcript, 1);
+    });
+
+    it("deletes checkpoint_epochs older than the cutoff", () => {
+      const oldTs = Date.now() - 40 * 86_400_000;
+      writeCheckpointEpoch(db, makeEpoch({ createdAt: oldTs }));
+      writeCheckpointEpoch(db, makeEpoch({ createdAt: Date.now() }));
+      const r = pruneOldRows(dir, 30);
+      assert.equal(r.affected, 1);
+      assert.equal(getDbStats(dir).tableCounts.checkpoint_epochs, 1);
+    });
+  });
+
+  describe("integrityCheck", () => {
+    it("returns ['ok'] on a healthy DB", () => {
+      const lines = integrityCheck(dir);
+      assert.deepEqual(lines, ["ok"]);
+    });
+  });
+
+  describe("checkpointWal", () => {
+    it("runs without error and reports checkpointed frames", () => {
+      const r = checkpointWal(dir);
+      assert.ok(r.summary.includes("wal_checkpoint(TRUNCATE)"));
+    });
+  });
+
+  describe("vacuumDb", () => {
+    it("rebuilds the DB file", () => {
+      appendRawTranscript(db, makeRow());
+      const r = vacuumDb(dir);
+      assert.ok(r.summary.includes("VACUUM"));
+      // DB file still exists after vacuum
+      assert.ok(statSync(join(dir, "sqlite.db")).size > 0);
+    });
+  });
+
+  describe("reconcileDedupMirror", () => {
+    it("fixes ref_count drift and deletes orphans", () => {
+      // Insert a dedup_mirror row with ref_count = 5 (drift: actual refs = 1).
+      const hash = "hash-recon-1";
+      upsertDedupMirror(db, hash, "content-bytes-1", 0);
+      // Force a drift: bump ref_count without a matching raw_transcript row.
+      db.prepare("UPDATE dedup_mirror SET ref_count = 5 WHERE content_hash = ?").run(hash);
+      // Insert one raw_transcript row pointing at it. appendRawTranscript auto-
+      // assigns seq = MAX(seq)+1 = 1 for the first row in this session.
+      appendRawTranscript(db, makeRow({ contentHash: "rt-recon-1" }));
+      updateRawTranscriptRef(db, "sess-1", 1, hash);
+
+      const r = reconcileDedupMirror(dir);
+      // ref_count should now be 1 (one raw_transcript row points at it).
+      const dm = db
+        .prepare("SELECT ref_count FROM dedup_mirror WHERE content_hash = ?")
+        .get(hash) as { ref_count: number } | undefined;
+      assert.equal(dm?.ref_count, 1);
+      assert.equal(r.fixedRefCount, 1);
+    });
+
+    it("deletes orphan dedup_mirror rows (no raw_transcript refs)", () => {
+      // Insert a dedup_mirror row with ref_count > 0 but NO raw_transcript ref.
+      const hash = "hash-orphan-1";
+      upsertDedupMirror(db, hash, "orphan-content", 0);
+      db.prepare("UPDATE dedup_mirror SET ref_count = 3 WHERE content_hash = ?").run(hash);
+
+      const r = reconcileDedupMirror(dir);
+      const exists = db
+        .prepare("SELECT 1 FROM dedup_mirror WHERE content_hash = ?")
+        .get(hash);
+      assert.equal(exists, undefined);
+      assert.ok(r.orphansDeleted > 0);
+    });
+  });
+
+  describe("autoMaintain", () => {
+    it("runs best-effort and returns a summary string", () => {
+      appendRawTranscript(db, makeRow());
+      const result = autoMaintain(dir);
+      assert.ok(typeof result === "string");
+      assert.ok(result.startsWith("auto-maintain:"));
+    });
+
+    it("reports nothing to do on a fresh empty DB", () => {
+      const result = autoMaintain(dir);
+      assert.equal(result, "auto-maintain: nothing to do");
+    });
+  });
+});

package/src/store/sqlite.ts

@@ -18,7 +18,7 @@
  */
 
 import { DatabaseSync } from "node:sqlite";
-import { existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, statSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { getStateDir } from "../store.js";
@@ -1886,3 +1886,293 @@ export function updateRawTranscriptRef(
     "@seq": seq,
   });
 }
+
+// ---------------------------------------------------------------------------
+// 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.
+// ---------------------------------------------------------------------------
+
+/** 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})`;
+  }
+}