pi-mega-compact 0.4.9 → 0.4.11

package/dist/extensions/dashboard-server.js

@@ -33,6 +33,7 @@ function readSnapshot(snapshotPath) {
             store: { checkpointCount: 0, totalTokenEstimate: 0, originalTokens: 0, tokensSaved: 0, injectedCount: 0, dedupHitRate: 0, storageDedupRate: 0, dedupCollapsed: 0 },
             crew: { activeAgents: 0, currentTurn: 0 },
             repo: { checkpointCount: 0, totalTokenEstimate: 0, originalTokens: 0, tokensSaved: 0, sessionCount: 0, dedupAttempts: 0, dedupCollapsed: 0, storageDedupRate: 0 },
+            integrity: { regionsRetained: 0, compressedOriginalBytes: 0, duplicatesCollapsed: 0, bytesPermanentlyDeleted: 0 },
         };
     }
 }
@@ -64,6 +65,10 @@ function dashboardHtml(tierName) {
   h1 .tier { background: #1f6feb; color: #fff; font-size: 11px; font-weight: 700; padding: 2px 8px; border-radius: 10px; text-transform: uppercase; letter-spacing: .5px; }
   .grid { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; margin-bottom: 20px; }
   .card { background: #161b22; border: 1px solid #30363d; border-radius: 8px; padding: 16px; }
+  .card.safe { border-color: #238636; }
+  .card.safe h2 { color: #3fb950; }
+  .safe-note { font-size: 12px; color: #8b949e; margin: 12px 0 0; line-height: 1.5; }
+  .value.ok { color: #3fb950; }
   .card h2 { font-size: 12px; text-transform: uppercase; letter-spacing: .5px; color: #8b949e; margin-bottom: 12px; font-weight: 600; }
   .meter-track { background: #21262d; border-radius: 4px; height: 20px; overflow: hidden; margin: 8px 0; }
   .meter-fill { height: 100%; border-radius: 4px; transition: width .6s ease; min-width: 2px; }
@@ -144,6 +149,16 @@ function dashboardHtml(tierName) {
       <span class="label">Storage Dedup</span><span class="value" id="rp-sdedup">0%</span>
     </div>
   </div>
+  <div class="card safe">
+    <h2>🛡 Data Safety</h2>
+    <div class="stat-grid">
+      <span class="label">Regions Retained</span><span class="value" id="ig-retained">0</span>
+      <span class="label">Compressed-Original</span><span class="value" id="ig-bytes">0 B</span>
+      <span class="label">Dedup Duplicates</span><span class="value" id="ig-dupes">0</span>
+      <span class="label">Permanently Deleted</span><span class="value ok" id="ig-deleted">0 B</span>
+    </div>
+    <p class="safe-note">Every compacted region is kept verbatim (compressed). "Drop" = removed from the live window only. We never delete your data.</p>
+  </div>
   <div class="card">
     <h2>Configuration</h2>
     <div class="conf-grid">
@@ -223,6 +238,19 @@ function dashboardHtml(tierName) {
     var rsdr = repo.storageDedupRate || 0;
     document.getElementById('rp-sdedup').textContent = (rsdr * 100 >= 10 ? Math.round(rsdr * 100) : (rsdr * 100).toFixed(1)) + '%';
 
+    // Data-safety invariant (Phase 0 — trust foundation).
+    var ig = d.integrity || { regionsRetained: 0, compressedOriginalBytes: 0, duplicatesCollapsed: 0, bytesPermanentlyDeleted: 0 };
+    function fmtBytes(b) {
+      b = b || 0;
+      if (b >= 1048576) return (b / 1048576).toFixed(1) + ' MiB';
+      if (b >= 1024) return (b / 1024).toFixed(1) + ' KiB';
+      return b + ' B';
+    }
+    document.getElementById('ig-retained').textContent = (ig.regionsRetained || 0).toLocaleString();
+    document.getElementById('ig-bytes').textContent = fmtBytes(ig.compressedOriginalBytes);
+    document.getElementById('ig-dupes').textContent = (ig.duplicatesCollapsed || 0).toLocaleString();
+    document.getElementById('ig-deleted').textContent = fmtBytes(ig.bytesPermanentlyDeleted);
+
     // Crew / agents (live sub-agent activity + turn).
     var crew = d.crew || { activeAgents: 0, currentTurn: 0 };
     document.getElementById('cr-agents').textContent = crew.activeAgents || 0;

package/dist/extensions/mega-compact.js

@@ -185,6 +185,7 @@ export default function (pi) {
             bindRepo(ctx.cwd);
         const st = store.stats(rt.sessionId);
         const repo = store.repoStats();
+        const di = store.dataInvariant();
         const armed = lastCtxPercent != null && lastCtxPercent >= config.fastGatePct;
         const ready = armed && (lastCtxTokens ?? 0) >= config.thresholdTokens;
         dashboard.snapshot({
@@ -223,6 +224,12 @@ export default function (pi) {
                 dedupCollapsed: repo.dedupCollapsed,
                 storageDedupRate: repo.storageDedupRate,
             },
+            integrity: {
+                regionsRetained: di.regionsRetained,
+                compressedOriginalBytes: di.compressedOriginalBytes,
+                duplicatesCollapsed: di.duplicatesCollapsed,
+                bytesPermanentlyDeleted: di.bytesPermanentlyDeleted,
+            },
         });
         // Live stats widget above the editor
         if (ctx) {
@@ -254,7 +261,16 @@ export default function (pi) {
             ];
             // Live "now processing" line — teal while fresh (≤4s), then the last-seen
             // action keeps the widget lively. Cleared on session reset.
-            if (currentActivity) {
+            if (tierTrace) {
+                // Per-tier dedup progress is more relevant than the last action while a
+                // compaction is mid-flight, so prefer it when fresh.
+                const fresh = Date.now() - lastActivityAt < 4000;
+                if (fresh)
+                    lines.push(`   ${tierTrace}`);
+                else if (currentActivity)
+                    lines.push(`   ${C.dim}${currentActivity}${C.reset}`);
+            }
+            else if (currentActivity) {
                 const fresh = Date.now() - lastActivityAt < 4000;
                 lines.push(`   ${fresh ? C.teal : C.dim}${currentActivity}${C.reset}`);
             }
@@ -285,6 +301,10 @@ export default function (pi) {
     // the widget is never blank. Cleared on session reset.
     let currentActivity;
     let lastActivityAt = 0;
+    // Live per-tier dedup trace (Phase 1): e.g. "L0 ✓ → L1 ✓ → L2 0.91 → stored".
+    // Built from the store's sync onTier callback during a compaction so the user
+    // watches each tier evaluate in real time. Cleared once the outcome settles.
+    let tierTrace;
     // ANSI palette for the toolbar. The pi TUI's Text component preserves ANSI
     // escape codes (see wrapTextWithAnsi), so raw escapes render as colors. No
     // chalk dependency needed — these are just strings.
@@ -323,6 +343,34 @@ export default function (pi) {
         currentTurn = 0;
         currentActivity = undefined;
         lastActivityAt = 0;
+        tierTrace = undefined;
+    }
+    /** Build the sync onTier callback that paints the live per-tier trace. */
+    function makeTierCallback(ctx) {
+        const order = ["L0", "L1", "L2", "new"];
+        const seen = new Map();
+        const glyph = (status) => status === "deduped" ? `${C.green}✓${C.reset}` :
+            status === "passed" ? `${C.dim}○${C.reset}` :
+                status === "scanning" ? `${C.amber}…${C.reset}` :
+                    `${C.cyan}●${C.reset}`;
+        return (ev) => {
+            const label = ev.tier === "new"
+                ? `${C.cyan}stored${C.reset}`
+                : `${ev.tier} ${glyph(ev.status)}` +
+                    (ev.detail ? ` ${C.gray}(${ev.detail})${C.reset}` : "");
+            // Show the most recent outcome per tier (collapses re-fires).
+            seen.set(ev.tier, label);
+            const show = [];
+            for (const t of order)
+                if (seen.has(t))
+                    show.push(seen.get(t));
+            tierTrace = `${C.teal}⚙${C.reset} ${show.join(` ${C.gray}→${C.reset} `)}`;
+            lastActivityAt = Date.now();
+            try {
+                snapshot(ctx);
+            }
+            catch { /* non-fatal */ }
+        };
     }
     /** Run the full compaction pipeline and persist a checkpoint. Returns the result. */
     function runCompact(ctx, messages, opts = {}) {
@@ -340,6 +388,7 @@ export default function (pi) {
             keepFrom,
             summary: opts.summary,
             timestamp: Date.now(),
+            onTier: makeTierCallback(ctx),
         }, store);
         if (result.skipped)
             return { skipped: true };
@@ -371,6 +420,9 @@ export default function (pi) {
             ? `♻ deduped ${fileLabel}`
             : `🗜 compacted ${result.checkpointId} · ${fileLabel}`;
         lastActivityAt = Date.now();
+        // The per-tier trace has settled into the final outcome — fold it back into
+        // the activity line and stop showing the live trace.
+        tierTrace = undefined;
         // Record session activity + a daily-log entry in the per-repo SQLite store
         // (foundation for resume-sessions / daily-log features). Best-effort — never
         // block a compaction on bookkeeping.
@@ -608,7 +660,7 @@ export default function (pi) {
         },
     });
     pi.registerCommand("mega-status", {
-        description: "Show mega-compact config and current context usage.",
+        description: "Show mega-compact config, context usage, and the data-safety invariant.",
         handler: async (_args, ctx) => {
             bindRepo(ctx.cwd);
             const usage = ctx.getContextUsage();
@@ -616,6 +668,9 @@ export default function (pi) {
             const tokens = usage?.tokens != null ? `${usage.tokens} tok` : "n/a";
             const sid = normalizeSessionId(ctx.sessionManager.getSessionId());
             const st = store.stats(sid);
+            const di = store.dataInvariant();
+            const fmtB = (b) => b >= 1_048_576 ? `${(b / 1_048_576).toFixed(1)} MiB` :
+                b >= 1024 ? `${(b / 1024).toFixed(1)} KiB` : `${b} B`;
             ctx.ui.notify(`[mega-compact] pct=${pct} tokens=${tokens} tier=${config.tier} fastGate=${config.fastGatePct}% ` +
                 `threshold=${config.thresholdTokens} auto=${config.auto} autoInline=${config.autoInline}\n` +
                 `[mega-compact] store: ${st.checkpointCount} chkpt · ` +
@@ -623,6 +678,10 @@ export default function (pi) {
                 `injected=${st.injectedCount} · dedup=${(st.dedupHitRate * 100).toFixed(0)}%\n` +
                 `[mega-compact] anchor=${config.anchorUserMessages} preserveRecent=${config.preserveRecent} ` +
                 `autoInlineK=${config.autoInlineK} dedupSim=${config.dedupSim} debug=${config.debug}\n` +
+                `[mega-compact] 🛡 data-safe: ${di.regionsRetained} regions retained ` +
+                `(${fmtB(di.compressedOriginalBytes)} compressed-original) · ` +
+                `${di.duplicatesCollapsed} dedup-duplicates collapsed · ` +
+                `${C.green}0 bytes permanently deleted${C.reset}\n` +
                 `[mega-compact] stateDir=${currentStateDir}`);
         },
     });
@@ -651,33 +710,40 @@ export default function (pi) {
     // ---- Dashboard server commands ----------------------------------------
     const portFile = join(currentStateDir, "port.pid");
     const runnerFile = join(currentStateDir, "_dashboard-runner.mjs");
+    const launchLog = join(currentStateDir, "_dashboard-launch.log");
     // Whether the runner must be spawned with --experimental-strip-types (true only
     // when we fall back to the .ts source outside node_modules; false when using
     // the shipped compiled dist/extensions/dashboard-server.js).
     let dashboardNeedsStrip = false;
-    /** Try to reach a running dashboard server. Returns { port, url } or null. */
-    async function isServerRunning() {
-        if (!existsSync(portFile))
-            return null;
-        try {
-            const info = JSON.parse(readFileSync(portFile, "utf-8"));
-            if (!info?.port)
-                return null;
-            const url = `http://localhost:${info.port}`; // guardrails-allow PREVENT-PI-004: localhost URL of the dashboard server this extension spawned
-            // Quick liveness probe
-            const res = await fetch(`${url}/api/snapshot`, { signal: AbortSignal.timeout(1500) }); // guardrails-allow PREVENT-PI-004: localhost probe to the dashboard server this extension spawned
-            if (res.ok)
-                return { port: info.port, url };
-        }
-        catch {
-            // stale or unreachable — clean up
+    // The dashboard server binds 9320–9329 (TARGET_PORT..TARGET_PORT+PORT_RANGE-1
+    // in dashboard-server.js). Probe each for a live /api/snapshot so we can detect
+    // readiness even when port.pid landed in a different state dir than we poll.
+    async function findLivePort() {
+        for (let port = 9320; port <= 9329; port++) {
             try {
-                unlinkSync(portFile);
+                const res = await fetch(`http://localhost:${port}/api/snapshot`, { signal: AbortSignal.timeout(800) }); // guardrails-allow PREVENT-PI-004: localhost liveness probe of the dashboard server this extension spawned
+                if (res.ok)
+                    return port;
             }
-            catch { /* ignore */ }
+            catch { /* not on this port — try next */ }
         }
         return null;
     }
+    /** Try to reach a running dashboard server. Returns { port, url } or null. */
+    async function isServerRunning() {
+        const port = await findLivePort();
+        if (!port) {
+            // Stale marker with no live server behind it — clean up.
+            if (existsSync(portFile)) {
+                try {
+                    unlinkSync(portFile);
+                }
+                catch { /* ignore */ }
+            }
+            return null;
+        }
+        return { port, url: `http://localhost:${port}` }; // guardrails-allow PREVENT-PI-004: localhost URL of the dashboard server this extension spawned
+    }
     /**
      * Resolve the launchable dashboard-server module.
      *
@@ -718,11 +784,16 @@ export default function (pi) {
             return false;
         dashboardNeedsStrip = resolved.needsStripTypes;
         const script = [
-            `import { launchDashboardServer } from ${JSON.stringify(resolved.entry)};`,
-            `launchDashboardServer(${JSON.stringify(currentStateDir)}).catch(err => {`,
-            `  console.error("[mega-compact] dashboard failed:", err);`,
+            `import { appendFileSync } from "node:fs";`,
+            `const __log = ${JSON.stringify(launchLog)};`,
+            `function __fail(err) {`,
+            `  const msg = "[mega-compact] dashboard failed: " + (err && err.stack ? err.stack : String(err));`,
+            `  try { appendFileSync(__log, msg + "\\n"); } catch { /* ignore */ }`,
+            `  console.error(msg);`,
             `  process.exit(1);`,
-            `});`,
+            `}`,
+            `import { launchDashboardServer } from ${JSON.stringify(resolved.entry)};`,
+            `launchDashboardServer(${JSON.stringify(currentStateDir)}).catch(__fail);`,
         ].join("\n");
         writeFileSync(runnerFile, script);
         return true;
@@ -763,24 +834,26 @@ export default function (pi) {
                 stdio: "ignore",
             });
             child.unref();
-            // Poll for port.pid (up to 5 seconds)
-            const deadline = Date.now() + 5_000;
-            let port;
+            // Poll for a live server (port 9320–9329) instead of relying solely on the
+            // port.pid marker, which can land in a different state dir than the one we
+            // poll when a prior compact left currentStateDir pointing elsewhere.
+            const deadline = Date.now() + 6_000;
+            let port = null;
             while (Date.now() < deadline) {
-                await new Promise((r) => setTimeout(r, 300));
-                if (existsSync(portFile)) {
-                    try {
-                        const raw = JSON.parse(readFileSync(portFile, "utf-8"));
-                        if (raw?.port) {
-                            port = raw.port;
-                            break;
-                        }
-                    }
-                    catch { /* keep polling */ }
-                }
+                await new Promise((resolve) => setTimeout(resolve, 300));
+                port = await findLivePort();
+                if (port)
+                    break;
             }
             if (!port) {
-                ctx.ui.notify("[mega-compact] dashboard server failed to start — check logs.");
+                let detail = "";
+                try {
+                    const log = readFileSync(launchLog, "utf-8").trim();
+                    if (log)
+                        detail = ` — ${log.split("\n").slice(-3).join("; ")}`;
+                }
+                catch { /* no log yet */ }
+                ctx.ui.notify(`[mega-compact] dashboard server failed to start${detail}. See ${launchLog}`);
                 return;
             }
             const url = `http://localhost:${port}`; // guardrails-allow PREVENT-PI-004: localhost URL of the dashboard server this extension spawned

package/dist/src/engine.js

@@ -103,6 +103,7 @@ export function compactSession(input, store = getDefaultStore()) {
         tokenEstimate: storedTokens,
         originalTokenEstimate,
         timestamp: input.timestamp ?? 0,
+        onTier: input.onTier,
     });
     return {
         skipped: false,

package/dist/src/store/phase01.test.js

@@ -0,0 +1,81 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { VectorStore } from "../vectorStore.js";
+import { dataInvariantStats } from "./sqlite.js";
+const baseTmp = mkdtempSync(join(tmpdir(), "mc-p01-"));
+let counter = 0;
+function store(opts = {}) {
+    const dir = join(baseTmp, `run-${counter++}`);
+    return { s: new VectorStore({ dedupSim: opts.dedupSim ?? 0.9, stateDir: dir }), dir };
+}
+// --- Phase 0: data-safety invariant ---------------------------------------
+test("Phase 0: every added region retains a compressed-original and deletes nothing", () => {
+    const { s, dir } = store();
+    s.add({ sessionId: "sess_a", summary: "s1", regionText: "the quick brown fox jumps", tokenEstimate: 5, originalTokenEstimate: 50, timestamp: 1 });
+    s.add({ sessionId: "sess_a", summary: "s2", regionText: "a totally different region of work", tokenEstimate: 6, originalTokenEstimate: 60, timestamp: 2 });
+    const di = dataInvariantStats(dir);
+    assert.equal(di.regionsRetained, 2, "both regions retained");
+    assert.ok(di.compressedOriginalBytes > 0, "compressed-original bytes retained");
+    assert.equal(di.bytesPermanentlyDeleted, 0, "INVARIANT: nothing permanently deleted");
+});
+test("Phase 0: dedup collapses a duplicate but original is still retained (not deleted)", () => {
+    const { s, dir } = store();
+    const text = "identical region content that will dedup on the second add";
+    s.add({ sessionId: "sess_b", summary: "s", regionText: text, tokenEstimate: 5, originalTokenEstimate: 50, timestamp: 1 });
+    const r2 = s.add({ sessionId: "sess_b", summary: "s", regionText: text, tokenEstimate: 5, originalTokenEstimate: 50, timestamp: 2 });
+    assert.equal(r2.deduped, true, "second add deduped");
+    const di = dataInvariantStats(dir);
+    assert.equal(di.bytesPermanentlyDeleted, 0, "INVARIANT: dedup never deletes data");
+    assert.ok(di.regionsRetained >= 1, "survivor region still retained");
+});
+// --- Phase 1: per-tier progress callback ----------------------------------
+test("Phase 1: onTier fires L0→L1→L2→stored for a genuinely new region", () => {
+    const { s } = store();
+    // Seed one checkpoint so L2 has something to scan against.
+    s.add({ sessionId: "sess_c", summary: "seed", regionText: "seed region alpha", timestamp: 1 });
+    const events = [];
+    s.add({
+        sessionId: "sess_c",
+        summary: "new",
+        regionText: "a brand new region beta that is not a duplicate",
+        timestamp: 2,
+        onTier: (ev) => events.push({ tier: ev.tier, status: ev.status }),
+    });
+    const tiers = events.map((e) => e.tier);
+    assert.ok(tiers.includes("L0"), "L0 fired");
+    assert.ok(tiers.includes("L1"), "L1 fired");
+    assert.ok(tiers.includes("L2"), "L2 fired");
+    assert.equal(events.at(-1)?.tier, "new", "final event is the 'new' tier");
+    assert.equal(events.at(-1)?.status, "stored", "final status is stored");
+});
+test("Phase 1: onTier reports a deduped outcome and short-circuits at the matching tier", () => {
+    const { s } = store();
+    const text = "region that will exact-dedup on the second pass";
+    s.add({ sessionId: "sess_d", summary: "s", regionText: text, timestamp: 1 });
+    const events = [];
+    const r = s.add({
+        sessionId: "sess_d",
+        summary: "s",
+        regionText: text,
+        timestamp: 2,
+        onTier: (ev) => events.push(ev),
+    });
+    assert.equal(r.deduped, true);
+    const deduped = events.find((e) => e.status === "deduped");
+    assert.ok(deduped, "a deduped event fired");
+    assert.equal(deduped?.tier, "L0", "exact duplicate short-circuits at L0");
+    // Must NOT reach the final stored event.
+    assert.ok(!events.some((e) => e.status === "stored"), "no stored event on dedup");
+});
+test("Phase 1: onTier is optional (back-compat) — add() works without it", () => {
+    const { s } = store();
+    const r = s.add({ sessionId: "sess_e", summary: "s", regionText: "no callback here", timestamp: 1 });
+    assert.equal(r.deduped, false);
+});
+process.on("exit", () => { try {
+    rmSync(baseTmp, { recursive: true, force: true });
+}
+catch { /* ignore */ } });

package/dist/src/store/sqlite.js

@@ -495,6 +495,26 @@ export function storeStats(sessionId, stateDir = getStateDir()) {
         lastSummary,
     };
 }
+export function dataInvariantStats(stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const row = db
+        .prepare(`SELECT
+         COUNT(compressed_original) AS withBlob,
+         COALESCE(SUM(LENGTH(compressed_original)),0) AS blobBytes,
+         SUM(CASE WHEN compressed_original IS NULL THEN 1 ELSE 0 END) AS noBlob
+       FROM context_chunks WHERE dedup_status != 'removed'`)
+        .get();
+    const removed = db
+        .prepare(`SELECT COUNT(*) AS c FROM context_chunks WHERE dedup_status = 'removed'`)
+        .get();
+    return {
+        regionsRetained: row.withBlob,
+        compressedOriginalBytes: row.blobBytes,
+        regionsWithoutBlob: row.noBlob ?? 0,
+        bytesPermanentlyDeleted: 0,
+        duplicatesCollapsed: removed.c,
+    };
+}
 export function repoStats(stateDir = getStateDir()) {
     const db = openStore(stateDir);
     const row = db

package/dist/src/vectorStore.js

@@ -19,7 +19,7 @@ import { isNearDuplicate } from "./dedup/l1-verify.js";
 import { mmrRerank } from "./dedup/mmr.js";
 import { topK } from "./dedup/topk.js";
 import { openBloom, saveBloom } from "./store/bloom.js";
-import { listCheckpoints, nextCheckpointId, upsertCheckpoint, loadSessionState, saveSessionState, upsertMinhashSignature, insertLshBuckets, lshCandidateChunks, setDedupStatus, addTokensSaved, getDedupStats, bumpDedupStats, repoStats as repoStatsFromStore, } from "./store/sqlite.js";
+import { listCheckpoints, nextCheckpointId, upsertCheckpoint, loadSessionState, saveSessionState, upsertMinhashSignature, insertLshBuckets, lshCandidateChunks, setDedupStatus, addTokensSaved, getDedupStats, bumpDedupStats, repoStats as repoStatsFromStore, dataInvariantStats, } from "./store/sqlite.js";
 import { migrateJsonToSqlite } from "./store/migrate.js";
 /** Default L2 semantic-dedup enable flag (trigram embedder is local, zero-network). */
 export const L2_ENABLED = true;
@@ -85,6 +85,9 @@ export class VectorStore {
         // we persist (orig − stored). Falls back to stored when orig is unknown.
         const origTokens = input.originalTokenEstimate ?? input.tokenEstimate ?? 0;
         const cfg = this.cfg;
+        // Live per-tier progress hook (Phase 1). Sync + optional; fired at each tier
+        // so the UI can paint "L0 ✓ → L1 ✓ → L2 0.91 → stored" during a compaction.
+        const onTier = input.onTier;
         // Tracks whether a tier matched while in MARK_ONLY (record-but-don't-collapse),
         // and which tier.
         let markOnly = null;
@@ -95,6 +98,7 @@ export class VectorStore {
         //    skips the scan; a hit is only a candidate, confirmed against `all` below.
         //    Gated by L0_ENABLED (Sprint 14). MARK_ONLY_L0 records the decision but
         //    does not collapse — the new region is still stored.
+        onTier?.({ tier: "L0", status: "scanning" });
         const digest = computeContentDigest(input.regionText);
         const bloom = openBloom(this.stateDir);
         if (cfg.L0_ENABLED && bloom.maybeHas(digest.contentHash)) {
@@ -112,6 +116,7 @@ export class VectorStore {
                     addTokensSaved(origTokens, this.stateDir);
                     const r = { checkpoint: contentMatch, deduped: true, reason: "contentHash" };
                     this.record("L0", "deduped", "contentHash", Date.now() - t0);
+                    onTier?.({ tier: "L0", status: "deduped", detail: "contentHash" });
                     return r;
                 }
             }
@@ -129,6 +134,7 @@ export class VectorStore {
                     addTokensSaved(origTokens, this.stateDir);
                     const r = { checkpoint: regionMatch, deduped: true, reason: "regionHash" };
                     this.record("L0", "deduped", "regionHash", Date.now() - t0);
+                    onTier?.({ tier: "L0", status: "deduped", detail: "regionHash" });
                     return r;
                 }
             }
@@ -152,14 +158,18 @@ export class VectorStore {
                     addTokensSaved(origTokens, this.stateDir);
                     const r = { checkpoint: summaryMatch, deduped: true, reason: "summaryHash" };
                     this.record("L0", "deduped", "summaryHash", Date.now() - t0);
+                    onTier?.({ tier: "L0", status: "deduped", detail: "summaryHash" });
                     return r;
                 }
             }
         }
+        // L0 did not collapse this region.
+        onTier?.({ tier: "L0", status: "passed" });
         // 2b. L1 MinHash/LSH near-duplicate dedup (Sprint 11) — catches one-word
         //     edits / rewordings that L0's exact hash misses. Cheap LSH bucket
         //     retrieval → trigram verification (pg_trgm-equivalent) as the final gate.
         //     Gated by L1_ENABLED (Sprint 14); MARK_ONLY_L1 records but doesn't collapse.
+        onTier?.({ tier: "L1", status: "scanning" });
         if (cfg.L1_ENABLED) {
             const l1 = this.findL1Duplicate(sessionId, input.regionText, all);
             if (l1 && !cfg.MARK_ONLY_L1) {
@@ -168,11 +178,13 @@ export class VectorStore {
                 bumpDedupStats(true, this.stateDir);
                 const r = { checkpoint: l1, deduped: true, reason: "l1MinHash" };
                 this.record("L1", "deduped", "l1MinHash", Date.now() - t0);
+                onTier?.({ tier: "L1", status: "deduped", detail: "l1MinHash" });
                 return r;
             }
             if (l1 && cfg.MARK_ONLY_L1)
                 markOnly = "L1";
         }
+        onTier?.({ tier: "L1", status: "passed" });
         // 3. L2 semantic dedup — catches near-identical / semantically-similar regions
         //    via cosine over the embedding. topicSummary is used for summaryHash dedup
         //    (tier 2); the vector index is keyed on the original region for backward-
@@ -183,6 +195,7 @@ export class VectorStore {
         const SIMILARITY_BUDGET_MS = cfg.SIMILARITY_BUDGET_MS;
         const simThreshold = this.l2Threshold; // from cfg.L2_COSINE (default 0.85 trigram)
         const embedding = this.embedder.embed(input.regionText);
+        onTier?.({ tier: "L2", status: "scanning" });
         if (cfg.L2_ENABLED && all.length > 0) {
             const start = Date.now();
             let timedOut = false;
@@ -204,10 +217,12 @@ export class VectorStore {
                     addTokensSaved(origTokens, this.stateDir);
                     const r = { checkpoint: nearest.checkpoint, deduped: true, reason: "contentSimilarity" };
                     this.record("L2", "deduped", "contentSimilarity", Date.now() - t0);
+                    onTier?.({ tier: "L2", status: "deduped", detail: nearest.sim.toFixed(2) });
                     return r;
                 }
                 markOnly = "L2";
             }
+            onTier?.({ tier: "L2", status: "passed", detail: `best ${nearest.sim.toFixed(2)}` });
         }
         // 4. Genuinely new — create checkpoint
         const checkpointId = nextCheckpointId(sessionId, this.stateDir);
@@ -265,6 +280,7 @@ export class VectorStore {
         }
         // Cumulative store-wide dedup accounting (attempt, not collapsed).
         bumpDedupStats(false, this.stateDir);
+        onTier?.({ tier: "new", status: "stored" });
         return { checkpoint, deduped: false };
     }
     /**
@@ -462,4 +478,8 @@ export class VectorStore {
     repoStats() {
         return repoStatsFromStore(this.stateDir);
     }
+    /** Data-safety invariant (Phase 0): regions retained vs bytes permanently deleted. */
+    dataInvariant() {
+        return dataInvariantStats(this.stateDir);
+    }
 }

package/extensions/dashboard-server.ts

@@ -96,6 +96,7 @@ function readSnapshot(snapshotPath: string) {
       store: { checkpointCount: 0, totalTokenEstimate: 0, originalTokens: 0, tokensSaved: 0, injectedCount: 0, dedupHitRate: 0, storageDedupRate: 0, dedupCollapsed: 0 },
       crew: { activeAgents: 0, currentTurn: 0 },
       repo: { checkpointCount: 0, totalTokenEstimate: 0, originalTokens: 0, tokensSaved: 0, sessionCount: 0, dedupAttempts: 0, dedupCollapsed: 0, storageDedupRate: 0 },
+      integrity: { regionsRetained: 0, compressedOriginalBytes: 0, duplicatesCollapsed: 0, bytesPermanentlyDeleted: 0 },
     } as Snapshot;
   }
 }
@@ -128,6 +129,10 @@ function dashboardHtml(tierName: string): string {
   h1 .tier { background: #1f6feb; color: #fff; font-size: 11px; font-weight: 700; padding: 2px 8px; border-radius: 10px; text-transform: uppercase; letter-spacing: .5px; }
   .grid { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; margin-bottom: 20px; }
   .card { background: #161b22; border: 1px solid #30363d; border-radius: 8px; padding: 16px; }
+  .card.safe { border-color: #238636; }
+  .card.safe h2 { color: #3fb950; }
+  .safe-note { font-size: 12px; color: #8b949e; margin: 12px 0 0; line-height: 1.5; }
+  .value.ok { color: #3fb950; }
   .card h2 { font-size: 12px; text-transform: uppercase; letter-spacing: .5px; color: #8b949e; margin-bottom: 12px; font-weight: 600; }
   .meter-track { background: #21262d; border-radius: 4px; height: 20px; overflow: hidden; margin: 8px 0; }
   .meter-fill { height: 100%; border-radius: 4px; transition: width .6s ease; min-width: 2px; }
@@ -208,6 +213,16 @@ function dashboardHtml(tierName: string): string {
       <span class="label">Storage Dedup</span><span class="value" id="rp-sdedup">0%</span>
     </div>
   </div>
+  <div class="card safe">
+    <h2>🛡 Data Safety</h2>
+    <div class="stat-grid">
+      <span class="label">Regions Retained</span><span class="value" id="ig-retained">0</span>
+      <span class="label">Compressed-Original</span><span class="value" id="ig-bytes">0 B</span>
+      <span class="label">Dedup Duplicates</span><span class="value" id="ig-dupes">0</span>
+      <span class="label">Permanently Deleted</span><span class="value ok" id="ig-deleted">0 B</span>
+    </div>
+    <p class="safe-note">Every compacted region is kept verbatim (compressed). "Drop" = removed from the live window only. We never delete your data.</p>
+  </div>
   <div class="card">
     <h2>Configuration</h2>
     <div class="conf-grid">
@@ -287,6 +302,19 @@ function dashboardHtml(tierName: string): string {
     var rsdr = repo.storageDedupRate || 0;
     document.getElementById('rp-sdedup').textContent = (rsdr * 100 >= 10 ? Math.round(rsdr * 100) : (rsdr * 100).toFixed(1)) + '%';
 
+    // Data-safety invariant (Phase 0 — trust foundation).
+    var ig = d.integrity || { regionsRetained: 0, compressedOriginalBytes: 0, duplicatesCollapsed: 0, bytesPermanentlyDeleted: 0 };
+    function fmtBytes(b) {
+      b = b || 0;
+      if (b >= 1048576) return (b / 1048576).toFixed(1) + ' MiB';
+      if (b >= 1024) return (b / 1024).toFixed(1) + ' KiB';
+      return b + ' B';
+    }
+    document.getElementById('ig-retained').textContent = (ig.regionsRetained || 0).toLocaleString();
+    document.getElementById('ig-bytes').textContent = fmtBytes(ig.compressedOriginalBytes);
+    document.getElementById('ig-dupes').textContent = (ig.duplicatesCollapsed || 0).toLocaleString();
+    document.getElementById('ig-deleted').textContent = fmtBytes(ig.bytesPermanentlyDeleted);
+
     // Crew / agents (live sub-agent activity + turn).
     var crew = d.crew || { activeAgents: 0, currentTurn: 0 };
     document.getElementById('cr-agents').textContent = crew.activeAgents || 0;

package/extensions/mega-compact.ts

@@ -214,6 +214,13 @@ interface DashboardSnapshot {
     dedupCollapsed: number;      // cumulative deduped collapses (store-wide)
     storageDedupRate: number;    // deduped / attempts, 0..1
   };
+  /** Phase 0 data-safety invariant (trust foundation). */
+  integrity: {
+    regionsRetained: number;         // checkpoints with a recoverable compressed-original
+    compressedOriginalBytes: number; // bytes of compressed-original retained (recoverable)
+    duplicatesCollapsed: number;     // dedup duplicates (original kept on survivor)
+    bytesPermanentlyDeleted: number; // ALWAYS 0 — the invariant
+  };
 }
 
 class Dashboard {
@@ -280,6 +287,7 @@ export default function (pi: ExtensionAPI) {
     if (ctx) bindRepo(ctx.cwd);
     const st = store.stats(rt.sessionId);
     const repo = store.repoStats();
+    const di = store.dataInvariant();
     const armed = lastCtxPercent != null && lastCtxPercent >= config.fastGatePct;
     const ready = armed && (lastCtxTokens ?? 0) >= config.thresholdTokens;
     dashboard.snapshot({
@@ -318,6 +326,12 @@ export default function (pi: ExtensionAPI) {
         dedupCollapsed: repo.dedupCollapsed,
         storageDedupRate: repo.storageDedupRate,
       },
+      integrity: {
+        regionsRetained: di.regionsRetained,
+        compressedOriginalBytes: di.compressedOriginalBytes,
+        duplicatesCollapsed: di.duplicatesCollapsed,
+        bytesPermanentlyDeleted: di.bytesPermanentlyDeleted,
+      },
     });
 
     // Live stats widget above the editor
@@ -350,7 +364,13 @@ export default function (pi: ExtensionAPI) {
       ];
       // Live "now processing" line — teal while fresh (≤4s), then the last-seen
       // action keeps the widget lively. Cleared on session reset.
-      if (currentActivity) {
+      if (tierTrace) {
+        // Per-tier dedup progress is more relevant than the last action while a
+        // compaction is mid-flight, so prefer it when fresh.
+        const fresh = Date.now() - lastActivityAt < 4000;
+        if (fresh) lines.push(`   ${tierTrace}`);
+        else if (currentActivity) lines.push(`   ${C.dim}${currentActivity}${C.reset}`);
+      } else if (currentActivity) {
         const fresh = Date.now() - lastActivityAt < 4000;
         lines.push(`   ${fresh ? C.teal : C.dim}${currentActivity}${C.reset}`);
       }
@@ -382,6 +402,10 @@ export default function (pi: ExtensionAPI) {
   // the widget is never blank. Cleared on session reset.
   let currentActivity: string | undefined;
   let lastActivityAt = 0;
+  // Live per-tier dedup trace (Phase 1): e.g. "L0 ✓ → L1 ✓ → L2 0.91 → stored".
+  // Built from the store's sync onTier callback during a compaction so the user
+  // watches each tier evaluate in real time. Cleared once the outcome settles.
+  let tierTrace: string | undefined;
   // ANSI palette for the toolbar. The pi TUI's Text component preserves ANSI
   // escape codes (see wrapTextWithAnsi), so raw escapes render as colors. No
   // chalk dependency needed — these are just strings.
@@ -421,6 +445,32 @@ export default function (pi: ExtensionAPI) {
     currentTurn = 0;
     currentActivity = undefined;
     lastActivityAt = 0;
+    tierTrace = undefined;
+  }
+
+  /** Build the sync onTier callback that paints the live per-tier trace. */
+  function makeTierCallback(ctx: ExtensionContext): (ev: { tier: "L0" | "L1" | "L2" | "new"; status: "scanning" | "deduped" | "passed" | "stored"; detail?: string }) => void {
+    const order: Array<"L0" | "L1" | "L2" | "new"> = ["L0", "L1", "L2", "new"];
+    const seen = new Map<string, string>();
+    const glyph = (status: string) =>
+      status === "deduped" ? `${C.green}✓${C.reset}` :
+        status === "passed" ? `${C.dim}○${C.reset}` :
+          status === "scanning" ? `${C.amber}…${C.reset}` :
+            `${C.cyan}●${C.reset}`;
+    return (ev) => {
+      const label =
+        ev.tier === "new"
+          ? `${C.cyan}stored${C.reset}`
+          : `${ev.tier} ${glyph(ev.status)}` +
+            (ev.detail ? ` ${C.gray}(${ev.detail})${C.reset}` : "");
+      // Show the most recent outcome per tier (collapses re-fires).
+      seen.set(ev.tier, label);
+      const show: string[] = [];
+      for (const t of order) if (seen.has(t)) show.push(seen.get(t)!);
+      tierTrace = `${C.teal}⚙${C.reset} ${show.join(` ${C.gray}→${C.reset} `)}`;
+      lastActivityAt = Date.now();
+      try { snapshot(ctx); } catch { /* non-fatal */ }
+    };
   }
 
   /** Run the full compaction pipeline and persist a checkpoint. Returns the result. */
@@ -445,6 +495,7 @@ export default function (pi: ExtensionAPI) {
         keepFrom,
         summary: opts.summary,
         timestamp: Date.now(),
+        onTier: makeTierCallback(ctx),
       },
       store,
     );
@@ -478,6 +529,9 @@ export default function (pi: ExtensionAPI) {
       ? `♻ deduped ${fileLabel}`
       : `🗜 compacted ${result.checkpointId} · ${fileLabel}`;
     lastActivityAt = Date.now();
+    // The per-tier trace has settled into the final outcome — fold it back into
+    // the activity line and stop showing the live trace.
+    tierTrace = undefined;
 
     // Record session activity + a daily-log entry in the per-repo SQLite store
     // (foundation for resume-sessions / daily-log features). Best-effort — never
@@ -740,7 +794,7 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.registerCommand("mega-status", {
-    description: "Show mega-compact config and current context usage.",
+    description: "Show mega-compact config, context usage, and the data-safety invariant.",
     handler: async (_args: string, ctx: ExtensionContext) => {
       bindRepo(ctx.cwd);
       const usage = ctx.getContextUsage();
@@ -748,6 +802,10 @@ export default function (pi: ExtensionAPI) {
       const tokens = usage?.tokens != null ? `${usage.tokens} tok` : "n/a";
       const sid = normalizeSessionId(ctx.sessionManager.getSessionId());
       const st = store.stats(sid);
+      const di = store.dataInvariant();
+      const fmtB = (b: number) =>
+        b >= 1_048_576 ? `${(b / 1_048_576).toFixed(1)} MiB` :
+          b >= 1024 ? `${(b / 1024).toFixed(1)} KiB` : `${b} B`;
       ctx.ui.notify(
         `[mega-compact] pct=${pct} tokens=${tokens} tier=${config.tier} fastGate=${config.fastGatePct}% ` +
           `threshold=${config.thresholdTokens} auto=${config.auto} autoInline=${config.autoInline}\n` +
@@ -756,6 +814,10 @@ export default function (pi: ExtensionAPI) {
           `injected=${st.injectedCount} · dedup=${(st.dedupHitRate * 100).toFixed(0)}%\n` +
           `[mega-compact] anchor=${config.anchorUserMessages} preserveRecent=${config.preserveRecent} ` +
           `autoInlineK=${config.autoInlineK} dedupSim=${config.dedupSim} debug=${config.debug}\n` +
+          `[mega-compact] 🛡 data-safe: ${di.regionsRetained} regions retained ` +
+          `(${fmtB(di.compressedOriginalBytes)} compressed-original) · ` +
+          `${di.duplicatesCollapsed} dedup-duplicates collapsed · ` +
+          `${C.green}0 bytes permanently deleted${C.reset}\n` +
           `[mega-compact] stateDir=${currentStateDir}`,
       );
     },
@@ -790,26 +852,36 @@ export default function (pi: ExtensionAPI) {
 
   const portFile = join(currentStateDir, "port.pid");
   const runnerFile = join(currentStateDir, "_dashboard-runner.mjs");
+  const launchLog = join(currentStateDir, "_dashboard-launch.log");
   // Whether the runner must be spawned with --experimental-strip-types (true only
   // when we fall back to the .ts source outside node_modules; false when using
   // the shipped compiled dist/extensions/dashboard-server.js).
   let dashboardNeedsStrip = false;
 
+  // The dashboard server binds 9320–9329 (TARGET_PORT..TARGET_PORT+PORT_RANGE-1
+  // in dashboard-server.js). Probe each for a live /api/snapshot so we can detect
+  // readiness even when port.pid landed in a different state dir than we poll.
+  async function findLivePort(): Promise<number | null> {
+    for (let port = 9320; port <= 9329; port++) {
+      try {
+        const res = await fetch(`http://localhost:${port}/api/snapshot`, { signal: AbortSignal.timeout(800) }); // guardrails-allow PREVENT-PI-004: localhost liveness probe of the dashboard server this extension spawned
+        if (res.ok) return port;
+      } catch { /* not on this port — try next */ }
+    }
+    return null;
+  }
+
   /** Try to reach a running dashboard server. Returns { port, url } or null. */
   async function isServerRunning(): Promise<{ port: number; url: string } | null> {
-    if (!existsSync(portFile)) return null;
-    try {
-      const info = JSON.parse(readFileSync(portFile, "utf-8"));
-      if (!info?.port) return null;
-      const url = `http://localhost:${info.port}`; // guardrails-allow PREVENT-PI-004: localhost URL of the dashboard server this extension spawned
-      // Quick liveness probe
-      const res = await fetch(`${url}/api/snapshot`, { signal: AbortSignal.timeout(1500) }); // guardrails-allow PREVENT-PI-004: localhost probe to the dashboard server this extension spawned
-      if (res.ok) return { port: info.port, url };
-    } catch {
-      // stale or unreachable — clean up
-      try { unlinkSync(portFile); } catch { /* ignore */ }
+    const port = await findLivePort();
+    if (!port) {
+      // Stale marker with no live server behind it — clean up.
+      if (existsSync(portFile)) {
+        try { unlinkSync(portFile); } catch { /* ignore */ }
+      }
+      return null;
     }
-    return null;
+    return { port, url: `http://localhost:${port}` }; // guardrails-allow PREVENT-PI-004: localhost URL of the dashboard server this extension spawned
   }
 
   /**
@@ -850,11 +922,16 @@ export default function (pi: ExtensionAPI) {
     if (!resolved) return false;
     dashboardNeedsStrip = resolved.needsStripTypes;
     const script = [
-      `import { launchDashboardServer } from ${JSON.stringify(resolved.entry)};`,
-      `launchDashboardServer(${JSON.stringify(currentStateDir)}).catch(err => {`,
-      `  console.error("[mega-compact] dashboard failed:", err);`,
+      `import { appendFileSync } from "node:fs";`,
+      `const __log = ${JSON.stringify(launchLog)};`,
+      `function __fail(err) {`,
+      `  const msg = "[mega-compact] dashboard failed: " + (err && err.stack ? err.stack : String(err));`,
+      `  try { appendFileSync(__log, msg + "\\n"); } catch { /* ignore */ }`,
+      `  console.error(msg);`,
       `  process.exit(1);`,
-      `});`,
+      `}`,
+      `import { launchDashboardServer } from ${JSON.stringify(resolved.entry)};`,
+      `launchDashboardServer(${JSON.stringify(currentStateDir)}).catch(__fail);`,
     ].join("\n");
     writeFileSync(runnerFile, script);
     return true;
@@ -900,21 +977,24 @@ export default function (pi: ExtensionAPI) {
       });
       child.unref();
 
-      // Poll for port.pid (up to 5 seconds)
-      const deadline = Date.now() + 5_000;
-      let port: number | undefined;
+      // Poll for a live server (port 9320–9329) instead of relying solely on the
+      // port.pid marker, which can land in a different state dir than the one we
+      // poll when a prior compact left currentStateDir pointing elsewhere.
+      const deadline = Date.now() + 6_000;
+      let port: number | null = null;
       while (Date.now() < deadline) {
-        await new Promise((r) => setTimeout(r, 300));
-        if (existsSync(portFile)) {
-          try {
-            const raw = JSON.parse(readFileSync(portFile, "utf-8"));
-            if (raw?.port) { port = raw.port; break; }
-          } catch { /* keep polling */ }
-        }
+        await new Promise((resolve) => setTimeout(resolve, 300));
+        port = await findLivePort();
+        if (port) break;
       }
 
       if (!port) {
-        ctx.ui.notify("[mega-compact] dashboard server failed to start — check logs.");
+        let detail = "";
+        try {
+          const log = readFileSync(launchLog, "utf-8").trim();
+          if (log) detail = ` — ${log.split("\n").slice(-3).join("; ")}`;
+        } catch { /* no log yet */ }
+        ctx.ui.notify(`[mega-compact] dashboard server failed to start${detail}. See ${launchLog}`);
         return;
       }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.4.9",
+  "version": "0.4.11",
   "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/engine.ts

@@ -38,6 +38,22 @@ export interface CompactInput {
   timestamp?: number;
   /** When true (default), use extractive summary instead of raw concatenation. */
   useExtractiveSummary?: boolean;
+  /** Sync progress callback fired by the store as each dedup tier is evaluated
+   *  (L0→L1→L2→new). Lets the UI render a live "L0 ✓ → L1 ✓ → L2 0.91 → stored"
+   *  progress line during compaction. Never awaited; must be side-effect-free-ish
+   *  and cheap. Optional; back-compat with callers that don't pass it. */
+  onTier?: (ev: TierProgress) => void;
+}
+
+/** Progress event emitted by the store as each dedup tier is evaluated. */
+export interface TierProgress {
+  /** Tier being evaluated: "L0" | "L1" | "L2" | "new". */
+  tier: "L0" | "L1" | "L2" | "new";
+  /** "scanning" while the tier is being evaluated, "deduped" when it matched,
+   *  "passed" when no match, "stored" at the final outcome. */
+  status: "scanning" | "deduped" | "passed" | "stored";
+  /** Optional detail — e.g. the L2 cosine sim ("0.91") or the dedup reason. */
+  detail?: string;
 }
 
 export interface CompactResult {
@@ -157,6 +173,7 @@ export function compactSession(input: CompactInput, store: VectorStore = getDefa
     tokenEstimate: storedTokens,
     originalTokenEstimate,
     timestamp: input.timestamp ?? 0,
+    onTier: input.onTier,
   });
 
   return {

package/src/store/phase01.test.ts

@@ -0,0 +1,88 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { VectorStore } from "../vectorStore.js";
+import { dataInvariantStats } from "./sqlite.js";
+
+const baseTmp = mkdtempSync(join(tmpdir(), "mc-p01-"));
+
+let counter = 0;
+function store(opts: { dedupSim?: number } = {}) {
+  const dir = join(baseTmp, `run-${counter++}`);
+  return { s: new VectorStore({ dedupSim: opts.dedupSim ?? 0.9, stateDir: dir }), dir };
+}
+
+// --- Phase 0: data-safety invariant ---------------------------------------
+
+test("Phase 0: every added region retains a compressed-original and deletes nothing", () => {
+  const { s, dir } = store();
+  s.add({ sessionId: "sess_a", summary: "s1", regionText: "the quick brown fox jumps", tokenEstimate: 5, originalTokenEstimate: 50, timestamp: 1 });
+  s.add({ sessionId: "sess_a", summary: "s2", regionText: "a totally different region of work", tokenEstimate: 6, originalTokenEstimate: 60, timestamp: 2 });
+  const di = dataInvariantStats(dir);
+  assert.equal(di.regionsRetained, 2, "both regions retained");
+  assert.ok(di.compressedOriginalBytes > 0, "compressed-original bytes retained");
+  assert.equal(di.bytesPermanentlyDeleted, 0, "INVARIANT: nothing permanently deleted");
+});
+
+test("Phase 0: dedup collapses a duplicate but original is still retained (not deleted)", () => {
+  const { s, dir } = store();
+  const text = "identical region content that will dedup on the second add";
+  s.add({ sessionId: "sess_b", summary: "s", regionText: text, tokenEstimate: 5, originalTokenEstimate: 50, timestamp: 1 });
+  const r2 = s.add({ sessionId: "sess_b", summary: "s", regionText: text, tokenEstimate: 5, originalTokenEstimate: 50, timestamp: 2 });
+  assert.equal(r2.deduped, true, "second add deduped");
+  const di = dataInvariantStats(dir);
+  assert.equal(di.bytesPermanentlyDeleted, 0, "INVARIANT: dedup never deletes data");
+  assert.ok(di.regionsRetained >= 1, "survivor region still retained");
+});
+
+// --- Phase 1: per-tier progress callback ----------------------------------
+
+test("Phase 1: onTier fires L0→L1→L2→stored for a genuinely new region", () => {
+  const { s } = store();
+  // Seed one checkpoint so L2 has something to scan against.
+  s.add({ sessionId: "sess_c", summary: "seed", regionText: "seed region alpha", timestamp: 1 });
+  const events: Array<{ tier: string; status: string }> = [];
+  s.add({
+    sessionId: "sess_c",
+    summary: "new",
+    regionText: "a brand new region beta that is not a duplicate",
+    timestamp: 2,
+    onTier: (ev) => events.push({ tier: ev.tier, status: ev.status }),
+  });
+  const tiers = events.map((e) => e.tier);
+  assert.ok(tiers.includes("L0"), "L0 fired");
+  assert.ok(tiers.includes("L1"), "L1 fired");
+  assert.ok(tiers.includes("L2"), "L2 fired");
+  assert.equal(events.at(-1)?.tier, "new", "final event is the 'new' tier");
+  assert.equal(events.at(-1)?.status, "stored", "final status is stored");
+});
+
+test("Phase 1: onTier reports a deduped outcome and short-circuits at the matching tier", () => {
+  const { s } = store();
+  const text = "region that will exact-dedup on the second pass";
+  s.add({ sessionId: "sess_d", summary: "s", regionText: text, timestamp: 1 });
+  const events: Array<{ tier: string; status: string; detail?: string }> = [];
+  const r = s.add({
+    sessionId: "sess_d",
+    summary: "s",
+    regionText: text,
+    timestamp: 2,
+    onTier: (ev) => events.push(ev),
+  });
+  assert.equal(r.deduped, true);
+  const deduped = events.find((e) => e.status === "deduped");
+  assert.ok(deduped, "a deduped event fired");
+  assert.equal(deduped?.tier, "L0", "exact duplicate short-circuits at L0");
+  // Must NOT reach the final stored event.
+  assert.ok(!events.some((e) => e.status === "stored"), "no stored event on dedup");
+});
+
+test("Phase 1: onTier is optional (back-compat) — add() works without it", () => {
+  const { s } = store();
+  const r = s.add({ sessionId: "sess_e", summary: "s", regionText: "no callback here", timestamp: 1 });
+  assert.equal(r.deduped, false);
+});
+
+process.on("exit", () => { try { rmSync(baseTmp, { recursive: true, force: true }); } catch { /* ignore */ } });

package/src/store/sqlite.ts

@@ -636,6 +636,49 @@ export interface RepoStats {
   storageDedupRate: number;
 }
 
+/**
+ * Data-safety invariant metrics (Phase 0 — trust foundation). Proves that every
+ * compacted region is still recoverable: we retain a compressed_original blob for
+ * each checkpoint and permanently delete nothing. "removed" rows are SemDeDup
+ * duplicates whose ORIGINAL is still retained on the surviving checkpoint — they
+ * are not data loss, so they are reported separately, not as deletions.
+ */
+export interface DataInvariantStats {
+  /** Checkpoints with a recoverable compressed_original blob. */
+  regionsRetained: number;
+  /** Total bytes of compressed_original retained (recoverable verbatim). */
+  compressedOriginalBytes: number;
+  /** Checkpoints missing a compressed_original blob (pre-blob or direct add). */
+  regionsWithoutBlob: number;
+  /** Bytes permanently deleted by the extension. ALWAYS 0 — the invariant. */
+  bytesPermanentlyDeleted: number;
+  /** Duplicate rows collapsed by dedup (original retained on the survivor). */
+  duplicatesCollapsed: number;
+}
+
+export function dataInvariantStats(stateDir: string = getStateDir()): DataInvariantStats {
+  const db = openStore(stateDir);
+  const row = db
+    .prepare(
+      `SELECT
+         COUNT(compressed_original) AS withBlob,
+         COALESCE(SUM(LENGTH(compressed_original)),0) AS blobBytes,
+         SUM(CASE WHEN compressed_original IS NULL THEN 1 ELSE 0 END) AS noBlob
+       FROM context_chunks WHERE dedup_status != 'removed'`,
+    )
+    .get() as { withBlob: number; blobBytes: number; noBlob: number };
+  const removed = db
+    .prepare(`SELECT COUNT(*) AS c FROM context_chunks WHERE dedup_status = 'removed'`)
+    .get() as { c: number };
+  return {
+    regionsRetained: row.withBlob,
+    compressedOriginalBytes: row.blobBytes,
+    regionsWithoutBlob: row.noBlob ?? 0,
+    bytesPermanentlyDeleted: 0,
+    duplicatesCollapsed: removed.c,
+  };
+}
+
 export function repoStats(stateDir: string = getStateDir()): RepoStats {
   const db = openStore(stateDir);
   const row = db

package/src/vectorStore.ts

@@ -36,6 +36,7 @@ import {
   getDedupStats,
   bumpDedupStats,
   repoStats as repoStatsFromStore,
+  dataInvariantStats,
 } from "./store/sqlite.js";
 import { migrateJsonToSqlite } from "./store/migrate.js";
 
@@ -61,6 +62,10 @@ export interface AddInput {
   /** Raw text of the compacted region — used to derive the regionHash + vector. */
   regionText: string;
   timestamp: number;
+  /** Sync progress callback fired as each dedup tier is evaluated (L0→L1→L2→new).
+   *  Lets the UI render live per-tier progress during compaction. Never awaited;
+   *  must be cheap. Optional for back-compat. */
+  onTier?: (ev: { tier: "L0" | "L1" | "L2" | "new"; status: "scanning" | "deduped" | "passed" | "stored"; detail?: string }) => void;
 }
 
 /** Default L2 semantic-dedup enable flag (trigram embedder is local, zero-network). */
@@ -150,6 +155,9 @@ export class VectorStore {
     // we persist (orig − stored). Falls back to stored when orig is unknown.
     const origTokens = input.originalTokenEstimate ?? input.tokenEstimate ?? 0;
     const cfg = this.cfg;
+    // Live per-tier progress hook (Phase 1). Sync + optional; fired at each tier
+    // so the UI can paint "L0 ✓ → L1 ✓ → L2 0.91 → stored" during a compaction.
+    const onTier = input.onTier;
     // Tracks whether a tier matched while in MARK_ONLY (record-but-don't-collapse),
     // and which tier.
     let markOnly: DedupTier | null = null;
@@ -161,6 +169,7 @@ export class VectorStore {
     //    skips the scan; a hit is only a candidate, confirmed against `all` below.
     //    Gated by L0_ENABLED (Sprint 14). MARK_ONLY_L0 records the decision but
     //    does not collapse — the new region is still stored.
+    onTier?.({ tier: "L0", status: "scanning" });
     const digest = computeContentDigest(input.regionText);
     const bloom = openBloom(this.stateDir);
     if (cfg.L0_ENABLED && bloom.maybeHas(digest.contentHash)) {
@@ -180,6 +189,7 @@ export class VectorStore {
           addTokensSaved(origTokens, this.stateDir);
           const r = { checkpoint: contentMatch, deduped: true, reason: "contentHash" };
           this.record("L0", "deduped", "contentHash", Date.now() - t0);
+          onTier?.({ tier: "L0", status: "deduped", detail: "contentHash" });
           return r;
         }
       }
@@ -197,6 +207,7 @@ export class VectorStore {
           addTokensSaved(origTokens, this.stateDir);
           const r = { checkpoint: regionMatch, deduped: true, reason: "regionHash" };
           this.record("L0", "deduped", "regionHash", Date.now() - t0);
+          onTier?.({ tier: "L0", status: "deduped", detail: "regionHash" });
           return r;
         }
       }
@@ -220,15 +231,19 @@ export class VectorStore {
           addTokensSaved(origTokens, this.stateDir);
           const r = { checkpoint: summaryMatch, deduped: true, reason: "summaryHash" };
           this.record("L0", "deduped", "summaryHash", Date.now() - t0);
+          onTier?.({ tier: "L0", status: "deduped", detail: "summaryHash" });
           return r;
         }
       }
     }
+    // L0 did not collapse this region.
+    onTier?.({ tier: "L0", status: "passed" });
 
     // 2b. L1 MinHash/LSH near-duplicate dedup (Sprint 11) — catches one-word
     //     edits / rewordings that L0's exact hash misses. Cheap LSH bucket
     //     retrieval → trigram verification (pg_trgm-equivalent) as the final gate.
     //     Gated by L1_ENABLED (Sprint 14); MARK_ONLY_L1 records but doesn't collapse.
+    onTier?.({ tier: "L1", status: "scanning" });
     if (cfg.L1_ENABLED) {
       const l1 = this.findL1Duplicate(sessionId, input.regionText, all);
       if (l1 && !cfg.MARK_ONLY_L1) {
@@ -237,10 +252,12 @@ export class VectorStore {
         bumpDedupStats(true, this.stateDir);
         const r = { checkpoint: l1, deduped: true, reason: "l1MinHash" };
         this.record("L1", "deduped", "l1MinHash", Date.now() - t0);
+        onTier?.({ tier: "L1", status: "deduped", detail: "l1MinHash" });
         return r;
       }
       if (l1 && cfg.MARK_ONLY_L1) markOnly = "L1";
     }
+    onTier?.({ tier: "L1", status: "passed" });
 
     // 3. L2 semantic dedup — catches near-identical / semantically-similar regions
     //    via cosine over the embedding. topicSummary is used for summaryHash dedup
@@ -252,6 +269,7 @@ export class VectorStore {
     const SIMILARITY_BUDGET_MS = cfg.SIMILARITY_BUDGET_MS;
     const simThreshold = this.l2Threshold; // from cfg.L2_COSINE (default 0.85 trigram)
     const embedding = this.embedder.embed(input.regionText);
+    onTier?.({ tier: "L2", status: "scanning" });
     if (cfg.L2_ENABLED && all.length > 0) {
       const start = Date.now();
       let timedOut = false;
@@ -274,10 +292,12 @@ export class VectorStore {
           addTokensSaved(origTokens, this.stateDir);
           const r = { checkpoint: nearest.checkpoint, deduped: true, reason: "contentSimilarity" };
           this.record("L2", "deduped", "contentSimilarity", Date.now() - t0);
+          onTier?.({ tier: "L2", status: "deduped", detail: nearest.sim.toFixed(2) });
           return r;
         }
         markOnly = "L2";
       }
+      onTier?.({ tier: "L2", status: "passed", detail: `best ${nearest.sim.toFixed(2)}` });
     }
 
     // 4. Genuinely new — create checkpoint
@@ -342,6 +362,7 @@ export class VectorStore {
     }
     // Cumulative store-wide dedup accounting (attempt, not collapsed).
     bumpDedupStats(false, this.stateDir);
+    onTier?.({ tier: "new", status: "stored" });
     return { checkpoint, deduped: false };
   }
 
@@ -585,4 +606,8 @@ export class VectorStore {
   repoStats(): ReturnType<typeof repoStatsFromStore> {
     return repoStatsFromStore(this.stateDir);
   }
+  /** Data-safety invariant (Phase 0): regions retained vs bytes permanently deleted. */
+  dataInvariant(): ReturnType<typeof dataInvariantStats> {
+    return dataInvariantStats(this.stateDir);
+  }
 }