pi-mega-compact 0.4.13 → 0.4.15

package/dist/extensions/dashboard-server.js

@@ -69,6 +69,15 @@ function dashboardHtml(tierName) {
   .card.safe h2 { color: #3fb950; }
   .safe-note { font-size: 12px; color: #8b949e; margin: 12px 0 0; line-height: 1.5; }
   .value.ok { color: #3fb950; }
+  .label {
+    cursor: help;
+    border-bottom: 1px dotted #484f58;
+  }
+  .card.legend { grid-column: 1 / -1; }
+  .legend-list { margin: 0; padding-left: 18px; color: #c9d1d9; }
+  .legend-list li { margin-bottom: 8px; line-height: 1.5; }
+  .legend-list b { color: #f0f6fc; }
+  .legend-note { font-size: 12px; color: #8b949e; margin: 12px 0 0; font-style: italic; }
   .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; }
@@ -126,15 +135,15 @@ function dashboardHtml(tierName) {
   <div class="card">
     <h2>Vector Store</h2>
     <div class="stat-grid">
-      <span class="label">Checkpoints</span><span class="value" id="st-count">0</span>
-      <span class="label">Tokens Stored</span><span class="value" id="st-tokens">0</span>
-      <span class="label">Original Tokens</span><span class="value" id="st-orig">0</span>
-      <span class="label">Tokens Saved</span><span class="value" id="st-saved">0</span>
-      <span class="label">Injected</span><span class="value" id="st-injected">0</span>
-      <span class="label">Dedup Rate</span><span class="value" id="st-dedup">0%</span>
-      <span class="label">Storage Dedup</span><span class="value" id="st-sdedup">0%</span>
-      <span class="label">Collapsed</span><span class="value" id="st-collapsed">0</span>
-      <span class="label">Last ID</span><span class="value" id="st-lastid">—</span>
+      <span class="label" title="A saved summary of a chunk of your conversation that was compacted to free up space.">Checkpoints</span><span class="value" id="st-count">0</span>
+      <span class="label" title="How much conversation we are currently holding as compact summaries (the 'memory' this extension keeps). Smaller is better.">Tokens Stored</span><span class="value" id="st-tokens">0</span>
+      <span class="label" title="Total size of the original conversation text before it was compacted.">Original Tokens</span><span class="value" id="st-orig">0</span>
+      <span class="label" title="How much conversation space we have freed up for you (original size minus the compact summary we kept).">Tokens Saved</span><span class="value" id="st-saved">0</span>
+      <span class="label" title="How many times old context was automatically brought back into the conversation because it was relevant to what you were doing.">Injected</span><span class="value" id="st-injected">0</span>
+      <span class="label" title="Of the times we recalled old context, how often it was actually on-topic.">Recall Relevance</span><span class="value" id="st-dedup">0%</span>
+      <span class="label" title="How often new content matched something we already had, so we skipped storing a duplicate copy. Higher = less wasted space.">Storage Dedup</span><span class="value" id="st-sdedup">0%</span>
+      <span class="label" title="How many duplicate chunks we collapsed into one instead of storing separately.">Collapsed</span><span class="value" id="st-collapsed">0</span>
+      <span class="label" title="The ID of the most recent saved checkpoint.">Last ID</span><span class="value" id="st-lastid">—</span>
     </div>
   </div>
   <div class="card">
@@ -177,6 +186,18 @@ function dashboardHtml(tierName) {
       <span class="label">Status</span><span class="value" id="cr-status">idle</span>
     </div>
   </div>
+  <div class="card legend">
+    <h2>What these numbers mean</h2>
+    <ul class="legend-list">
+      <li><b>Tokens saved</b> — conversation space this extension has freed up for you (it compacted old text into short summaries).</li>
+      <li><b>Tokens stored</b> — how much "memory" (compact summaries) the extension is currently holding for this repo.</li>
+      <li><b>Injected</b> — times old context was automatically pasted back in because it was relevant to your current task.</li>
+      <li><b>Recall relevance</b> — of those, how often the recalled context was actually on-topic.</li>
+      <li><b>Storage dedup</b> — how often new content matched something already saved, so a duplicate copy was skipped (saves space).</li>
+      <li><b>Data safety</b> — every compacted region is kept verbatim (compressed). Nothing is permanently deleted; you can restore any of it.</li>
+    </ul>
+    <p class="legend-note">Hover any label above for a quick explanation.</p>
+  </div>
 </div>
 
 <div class="events">

package/dist/extensions/mega-compact.js

@@ -34,7 +34,9 @@ import { recallAndInline } from "../src/recall.js";
 import { autoCompactCheck } from "../src/compact.js";
 import { estimateSessionTokens } from "../src/tokens.js";
 import { normalizeSessionId } from "../src/store.js";
-import { touchSession, logDaily } from "../src/store/sqlite.js";
+import { touchSession, logDaily, listCheckpoints } from "../src/store/sqlite.js";
+import { decompressSmart } from "../src/store/compression.js";
+import { loadMetrics, fpRate, p95 } from "../src/monitoring.js";
 import { Logger } from "../src/log.js";
 import { writeFileSync, appendFileSync, readFileSync } from "node:fs";
 import { existsSync, mkdirSync, unlinkSync } from "node:fs";
@@ -258,8 +260,8 @@ export default function (pi) {
             // Phase 3 — pulsing status glyph while a compaction is in flight.
             const pulse = pulsing ? `${C.cyan}${PULSE[Math.floor(Date.now() / 250) % PULSE.length]}${C.reset} ` : "";
             const lines = [
-                ` ${C.amber}⚡ ${config.tier}${C.reset} │ ${tokStr}/${maxStr} tokens (${C.bold}${pctStr}${C.reset}) │ ${st.checkpointCount} chkpt${agentStr}${turnStr}`,
-                `   ${triggerLabel} │ ${C.magenta}dedup: ${dedupStr}${C.reset} │ ${C.gray}used:${C.reset} ${usedStr} │ ${C.gray}saved:${C.reset} ${savedStr}`,
+                ` ${C.amber}⚡ ${config.tier}${C.reset} │ ${tokStr}/${maxStr} tokens (${C.bold}${pctStr}${C.reset}) │ ${st.checkpointCount} saved${agentStr}${turnStr}`,
+                `   ${triggerLabel} │ ${C.magenta}repeat-skipped: ${dedupStr}${C.reset} │ ${C.gray}memory held:${C.reset} ${usedStr} │ ${C.gray}space freed:${C.reset} ${savedStr}`,
             ];
             // Phase 3 — compact progress bar: session tokens saved toward the rolling goal.
             if (rt.tokensSaved > 0) {
@@ -287,11 +289,16 @@ export default function (pi) {
             // Phase 3 — recall/activity ticker (most-recent first), fresh only.
             if (fresh) {
                 for (let i = ticker.length - 1; i >= 0; i--) {
-                    if (lines.length >= 10)
-                        break; // MAX_WIDGET_LINES guard
+                    if (lines.length >= 9)
+                        break; // leave room for the hint line (MAX 10)
                     lines.push(`   ${i === ticker.length - 1 ? "" : C.dim}${ticker[i].text}${C.reset}`);
                 }
             }
+            // Plain-language hint so first-time users understand the widget. Always
+            // last, dimmed. "/mega-help explains these terms."
+            if (lines.length < 10) {
+                lines.push(`   ${C.dim}auto-compresses old context to free space · nothing deleted · /mega-help${C.reset}`);
+            }
             ctx.ui.setWidget(WIDGET_KEY, lines, { placement: "aboveEditor" });
         }
     }
@@ -732,9 +739,25 @@ 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 repo = store.repoStats();
             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`;
+            // Tangible cost: turn "tokens saved" into a dollar figure + context-days
+            // extended, so the counter is concrete rather than opaque. ~$3 / 1M tok
+            // (rough blended rate); contextWindow ÷ savedRate = days of context bought.
+            const usd = (repo.tokensSaved / 1_000_000 * 3).toFixed(2);
+            const ctxWindow = usage?.contextWindow ?? 0;
+            const daysExtended = ctxWindow > 0 && repo.tokensSaved > 0
+                ? (repo.tokensSaved / ctxWindow).toFixed(1)
+                : "0";
+            const costStr = `≈ $${usd} saved · ${daysExtended} context-windows extended`;
+            // Recall-quality badge (Phase 4): trust score from monitoring metrics.
+            const m = loadMetrics(currentStateDir);
+            const fp = fpRate(m, "L2");
+            const p95L2 = p95(m.latency.L2 ?? []);
+            const relPct = (st.dedupHitRate * 100).toFixed(0);
+            const qualityStr = `recall ${relPct}% relevant · FP ${(fp * 100).toFixed(1)}% · L2 p95 ${p95L2.toFixed(0)}ms`;
             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 · ` +
@@ -746,9 +769,100 @@ export default function (pi) {
                 `(${fmtB(di.compressedOriginalBytes)} compressed-original) · ` +
                 `${di.duplicatesCollapsed} dedup-duplicates collapsed · ` +
                 `${C.green}0 bytes permanently deleted${C.reset}\n` +
+                `[mega-compact] 💰 ${costStr}\n` +
+                `[mega-compact] 🎯 ${qualityStr}\n` +
                 `[mega-compact] stateDir=${currentStateDir}`);
         },
     });
+    // ---- Phase 4: cheap standout commands (data is already persisted) -------
+    /** Resolve a checkpoint by id (or "recent"/"last") from this session's store. */
+    function findCheckpoint(sid, ref) {
+        const all = listCheckpoints(sid, currentStateDir);
+        if (all.length === 0)
+            return undefined;
+        if (!ref || ref === "recent" || ref === "last")
+            return all[all.length - 1];
+        return all.find((c) => c.checkpointId === ref) ?? all.find((c) => c.checkpointId.endsWith(ref));
+    }
+    pi.registerCommand("mega-restore", {
+        description: "Re-inject a checkpoint's verbatim original region into context. Usage: /mega-restore <chkpt|recent>",
+        handler: async (args, ctx) => {
+            bindRepo(ctx.cwd);
+            const sid = normalizeSessionId(ctx.sessionManager.getSessionId());
+            const cp = findCheckpoint(sid, args.trim());
+            if (!cp) {
+                ctx.ui.notify(`[mega-compact] no checkpoint found${args.trim() ? ` for "${args.trim()}"` : ""} in this session. Try /mega-history.`);
+                return;
+            }
+            if (!cp.compressedOriginal) {
+                ctx.ui.notify(`[mega-compact] ${cp.checkpointId} has no recoverable original (pre-blob or direct add). Cannot restore verbatim.`);
+                return;
+            }
+            const original = decompressSmart(cp.compressedOriginal).toString("utf-8");
+            // Re-inject verbatim via before_agent_start (PREVENT-PI-003) — never
+            // touches live messages, only prepends the restored region to systemPrompt.
+            pendingRecallBlock = `The following compacted context was RESTORED from checkpoint ${cp.checkpointId} (verbatim original region):\n\n${original}`;
+            const files = cp.filesModified?.length ? cp.filesModified.join(", ") : "(no files captured)";
+            ctx.ui.notify(`[mega-compact] ♻ restored ${cp.checkpointId} — ${original.length} chars re-injected on next turn.\n` +
+                `[mega-compact] files: ${files}`);
+            dashboard.event("restore", { checkpointId: cp.checkpointId, chars: original.length });
+        },
+    });
+    pi.registerCommand("mega-history", {
+        description: "List this session's checkpoints (id, date, files, tokens). Usage: /mega-history",
+        handler: async (_args, ctx) => {
+            bindRepo(ctx.cwd);
+            const sid = normalizeSessionId(ctx.sessionManager.getSessionId());
+            const all = listCheckpoints(sid, currentStateDir);
+            if (all.length === 0) {
+                ctx.ui.notify("[mega-compact] no checkpoints in this session yet.");
+                return;
+            }
+            const rows = all.map((c) => {
+                const when = c.timestamp ? new Date(c.timestamp).toISOString().slice(0, 16).replace("T", " ") : "—";
+                const files = c.filesModified?.length ? c.filesModified.map((f) => f.split("/").pop()).join(", ") : "—";
+                const orig = c.originalTokenEstimate ?? 0;
+                const stored = c.tokenEstimate ?? 0;
+                const saved = Math.max(0, orig - stored);
+                return `  ${c.checkpointId}  ${when}  ${C.cyan}${saved}t saved${C.reset}  ${files}`;
+            });
+            ctx.ui.notify(`[mega-compact] ${all.length} checkpoint(s) in this session:\n` + rows.join("\n") +
+                `\n[mega-compact] /mega-view <chkpt> to see the original region · /mega-restore <chkpt> to re-inject it`);
+        },
+    });
+    pi.registerCommand("mega-view", {
+        description: "Show a checkpoint's verbatim original region. Usage: /mega-view <chkpt|recent>",
+        handler: async (args, ctx) => {
+            bindRepo(ctx.cwd);
+            const sid = normalizeSessionId(ctx.sessionManager.getSessionId());
+            const cp = findCheckpoint(sid, args.trim());
+            if (!cp) {
+                ctx.ui.notify(`[mega-compact] no checkpoint found${args.trim() ? ` for "${args.trim()}"` : ""}. Try /mega-history.`);
+                return;
+            }
+            if (!cp.compressedOriginal) {
+                ctx.ui.notify(`[mega-compact] ${cp.checkpointId} summary:\n${cp.summary.slice(0, 500)}${cp.summary.length > 500 ? "…" : ""}\n(no verbatim original stored)`);
+                return;
+            }
+            const original = decompressSmart(cp.compressedOriginal).toString("utf-8");
+            ctx.ui.notify(`[mega-compact] ${cp.checkpointId} — original region (${original.length} chars):\n` +
+                `${original.slice(0, 1500)}${original.length > 1500 ? "\n…(truncated)" : ""}`);
+        },
+    });
+    pi.registerCommand("mega-help", {
+        description: "Plain-language glossary of what mega-compact's stats mean.",
+        handler: async (_args, ctx) => {
+            ctx.ui.notify(`[mega-compact] glossary — what the numbers mean:\n` +
+                `• token — a chunk of text (~4 chars). Context window = how much text fits in memory at once.\n` +
+                `• space freed — how much conversation we've compressed away to make room (the win).\n` +
+                `• memory held — how much compact summary we're currently keeping as your 'notes'.\n` +
+                `• saved checkpoint — a compact summary of an old conversation chunk we stored.\n` +
+                `• repeat-skipped — how often new text matched something we already had, so we didn't store a duplicate.\n` +
+                `• injected — times we pasted an old saved note back into the chat because it was relevant.\n` +
+                `• recall relevance — of those, how often the note was actually on-topic.\n` +
+                `• data safety — every compressed region is kept verbatim; nothing is permanently deleted. /mega-restore brings any of it back.`);
+        },
+    });
     pi.registerCommand("mega-tier", {
         description: "Show or change the compaction tier at runtime. Usage: /mega-tier [low|medium|high|ultra|mega]",
         handler: async (args, ctx) => {

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

@@ -0,0 +1,54 @@
+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 { listCheckpoints, dataInvariantStats } from "./sqlite.js";
+import { decompressSmart, compressSmart } from "./compression.js";
+const baseTmp = mkdtempSync(join(tmpdir(), "mc-p04-"));
+let counter = 0;
+function store(opts = {}) {
+    const dir = join(baseTmp, `run-${counter++}`);
+    return { s: new VectorStore({ dedupSim: opts.dedupSim ?? 0.9, stateDir: dir }), dir };
+}
+test("Phase 4: added checkpoint is listed and its compressed-original round-trips", () => {
+    const { s, dir } = store();
+    const original = "the original region text that gets compacted and must be restorable verbatim";
+    const r = s.add({ sessionId: "sess_a", summary: "s", regionText: original, tokenEstimate: 5, originalTokenEstimate: 60, timestamp: 1 });
+    const all = listCheckpoints("sess_a", dir);
+    assert.equal(all.length, 1, "one checkpoint listed");
+    const cp = all[0];
+    assert.ok(cp.compressedOriginal, "compressed-original blob present");
+    // The DR/restore path: decompressSmart must return the exact original.
+    const restored = decompressSmart(cp.compressedOriginal).toString("utf-8");
+    assert.equal(restored, original, "restored verbatim === original");
+    assert.equal(cp.checkpointId, r.checkpoint.checkpointId);
+});
+test("Phase 4: findCheckpoint-by-id resolves a listed checkpoint", () => {
+    const { s, dir } = store();
+    s.add({ sessionId: "sess_b", summary: "s1", regionText: "region one text content here", tokenEstimate: 4, originalTokenEstimate: 40, timestamp: 1 });
+    const r2 = s.add({ sessionId: "sess_b", summary: "s2", regionText: "region two text content here different", tokenEstimate: 4, originalTokenEstimate: 45, timestamp: 2 });
+    const all = listCheckpoints("sess_b", dir);
+    assert.equal(all.length, 2);
+    const wanted = all.find((c) => c.checkpointId === r2.checkpoint.checkpointId);
+    assert.ok(wanted, "checkpoint resolved by id");
+    assert.ok(wanted.compressedOriginal, "has restorable original");
+});
+test("Phase 4: dataInvariantStats sanity for restore trust (0 deleted)", () => {
+    const { s, dir } = store();
+    s.add({ sessionId: "sess_c", summary: "s", regionText: "retained region body text", tokenEstimate: 5, originalTokenEstimate: 50, timestamp: 1 });
+    const di = dataInvariantStats(dir);
+    assert.equal(di.regionsRetained, 1);
+    assert.ok(di.compressedOriginalBytes > 0);
+    assert.equal(di.bytesPermanentlyDeleted, 0);
+});
+test("Phase 4: compressSmart/decompressSmart round-trips arbitrary text", () => {
+    const text = "x".repeat(2000);
+    const back = decompressSmart(compressSmart(Buffer.from(text, "utf-8"))).toString("utf-8");
+    assert.equal(back, text);
+});
+process.on("exit", () => { try {
+    rmSync(baseTmp, { recursive: true, force: true });
+}
+catch { /* ignore */ } });

package/extensions/dashboard-server.ts

@@ -133,6 +133,15 @@ function dashboardHtml(tierName: string): string {
   .card.safe h2 { color: #3fb950; }
   .safe-note { font-size: 12px; color: #8b949e; margin: 12px 0 0; line-height: 1.5; }
   .value.ok { color: #3fb950; }
+  .label {
+    cursor: help;
+    border-bottom: 1px dotted #484f58;
+  }
+  .card.legend { grid-column: 1 / -1; }
+  .legend-list { margin: 0; padding-left: 18px; color: #c9d1d9; }
+  .legend-list li { margin-bottom: 8px; line-height: 1.5; }
+  .legend-list b { color: #f0f6fc; }
+  .legend-note { font-size: 12px; color: #8b949e; margin: 12px 0 0; font-style: italic; }
   .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; }
@@ -190,15 +199,15 @@ function dashboardHtml(tierName: string): string {
   <div class="card">
     <h2>Vector Store</h2>
     <div class="stat-grid">
-      <span class="label">Checkpoints</span><span class="value" id="st-count">0</span>
-      <span class="label">Tokens Stored</span><span class="value" id="st-tokens">0</span>
-      <span class="label">Original Tokens</span><span class="value" id="st-orig">0</span>
-      <span class="label">Tokens Saved</span><span class="value" id="st-saved">0</span>
-      <span class="label">Injected</span><span class="value" id="st-injected">0</span>
-      <span class="label">Dedup Rate</span><span class="value" id="st-dedup">0%</span>
-      <span class="label">Storage Dedup</span><span class="value" id="st-sdedup">0%</span>
-      <span class="label">Collapsed</span><span class="value" id="st-collapsed">0</span>
-      <span class="label">Last ID</span><span class="value" id="st-lastid">—</span>
+      <span class="label" title="A saved summary of a chunk of your conversation that was compacted to free up space.">Checkpoints</span><span class="value" id="st-count">0</span>
+      <span class="label" title="How much conversation we are currently holding as compact summaries (the 'memory' this extension keeps). Smaller is better.">Tokens Stored</span><span class="value" id="st-tokens">0</span>
+      <span class="label" title="Total size of the original conversation text before it was compacted.">Original Tokens</span><span class="value" id="st-orig">0</span>
+      <span class="label" title="How much conversation space we have freed up for you (original size minus the compact summary we kept).">Tokens Saved</span><span class="value" id="st-saved">0</span>
+      <span class="label" title="How many times old context was automatically brought back into the conversation because it was relevant to what you were doing.">Injected</span><span class="value" id="st-injected">0</span>
+      <span class="label" title="Of the times we recalled old context, how often it was actually on-topic.">Recall Relevance</span><span class="value" id="st-dedup">0%</span>
+      <span class="label" title="How often new content matched something we already had, so we skipped storing a duplicate copy. Higher = less wasted space.">Storage Dedup</span><span class="value" id="st-sdedup">0%</span>
+      <span class="label" title="How many duplicate chunks we collapsed into one instead of storing separately.">Collapsed</span><span class="value" id="st-collapsed">0</span>
+      <span class="label" title="The ID of the most recent saved checkpoint.">Last ID</span><span class="value" id="st-lastid">—</span>
     </div>
   </div>
   <div class="card">
@@ -241,6 +250,18 @@ function dashboardHtml(tierName: string): string {
       <span class="label">Status</span><span class="value" id="cr-status">idle</span>
     </div>
   </div>
+  <div class="card legend">
+    <h2>What these numbers mean</h2>
+    <ul class="legend-list">
+      <li><b>Tokens saved</b> — conversation space this extension has freed up for you (it compacted old text into short summaries).</li>
+      <li><b>Tokens stored</b> — how much "memory" (compact summaries) the extension is currently holding for this repo.</li>
+      <li><b>Injected</b> — times old context was automatically pasted back in because it was relevant to your current task.</li>
+      <li><b>Recall relevance</b> — of those, how often the recalled context was actually on-topic.</li>
+      <li><b>Storage dedup</b> — how often new content matched something already saved, so a duplicate copy was skipped (saves space).</li>
+      <li><b>Data safety</b> — every compacted region is kept verbatim (compressed). Nothing is permanently deleted; you can restore any of it.</li>
+    </ul>
+    <p class="legend-note">Hover any label above for a quick explanation.</p>
+  </div>
 </div>
 
 <div class="events">

package/extensions/mega-compact.ts

@@ -37,7 +37,9 @@ import { recallAndInline } from "../src/recall.js";
 import { autoCompactCheck } from "../src/compact.js";
 import { estimateSessionTokens } from "../src/tokens.js";
 import { normalizeSessionId } from "../src/store.js";
-import { touchSession, logDaily } from "../src/store/sqlite.js";
+import { touchSession, logDaily, listCheckpoints } from "../src/store/sqlite.js";
+import { decompressSmart } from "../src/store/compression.js";
+import { loadMetrics, fpRate, p95 } from "../src/monitoring.js";
 import { Logger } from "../src/log.js";
 import type { EngineMessage } from "../src/types.js";
 import { writeFileSync, appendFileSync, readFileSync } from "node:fs";
@@ -361,8 +363,8 @@ export default function (pi: ExtensionAPI) {
       // Phase 3 — pulsing status glyph while a compaction is in flight.
       const pulse = pulsing ? `${C.cyan}${PULSE[Math.floor(Date.now() / 250) % PULSE.length]}${C.reset} ` : "";
       const lines = [
-        ` ${C.amber}⚡ ${config.tier}${C.reset} │ ${tokStr}/${maxStr} tokens (${C.bold}${pctStr}${C.reset}) │ ${st.checkpointCount} chkpt${agentStr}${turnStr}`,
-        `   ${triggerLabel} │ ${C.magenta}dedup: ${dedupStr}${C.reset} │ ${C.gray}used:${C.reset} ${usedStr} │ ${C.gray}saved:${C.reset} ${savedStr}`,
+        ` ${C.amber}⚡ ${config.tier}${C.reset} │ ${tokStr}/${maxStr} tokens (${C.bold}${pctStr}${C.reset}) │ ${st.checkpointCount} saved${agentStr}${turnStr}`,
+        `   ${triggerLabel} │ ${C.magenta}repeat-skipped: ${dedupStr}${C.reset} │ ${C.gray}memory held:${C.reset} ${usedStr} │ ${C.gray}space freed:${C.reset} ${savedStr}`,
       ];
       // Phase 3 — compact progress bar: session tokens saved toward the rolling goal.
       if (rt.tokensSaved > 0) {
@@ -387,10 +389,15 @@ export default function (pi: ExtensionAPI) {
       // Phase 3 — recall/activity ticker (most-recent first), fresh only.
       if (fresh) {
         for (let i = ticker.length - 1; i >= 0; i--) {
-          if (lines.length >= 10) break; // MAX_WIDGET_LINES guard
+          if (lines.length >= 9) break; // leave room for the hint line (MAX 10)
           lines.push(`   ${i === ticker.length - 1 ? "" : C.dim}${ticker[i].text}${C.reset}`);
         }
       }
+      // Plain-language hint so first-time users understand the widget. Always
+      // last, dimmed. "/mega-help explains these terms."
+      if (lines.length < 10) {
+        lines.push(`   ${C.dim}auto-compresses old context to free space · nothing deleted · /mega-help${C.reset}`);
+      }
       ctx.ui.setWidget(WIDGET_KEY, lines, { placement: "aboveEditor" });
     }
   }
@@ -869,10 +876,26 @@ 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 repo = store.repoStats();
       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`;
+      // Tangible cost: turn "tokens saved" into a dollar figure + context-days
+      // extended, so the counter is concrete rather than opaque. ~$3 / 1M tok
+      // (rough blended rate); contextWindow ÷ savedRate = days of context bought.
+      const usd = (repo.tokensSaved / 1_000_000 * 3).toFixed(2);
+      const ctxWindow = usage?.contextWindow ?? 0;
+      const daysExtended = ctxWindow > 0 && repo.tokensSaved > 0
+        ? (repo.tokensSaved / ctxWindow).toFixed(1)
+        : "0";
+      const costStr = `≈ $${usd} saved · ${daysExtended} context-windows extended`;
+      // Recall-quality badge (Phase 4): trust score from monitoring metrics.
+      const m = loadMetrics(currentStateDir);
+      const fp = fpRate(m, "L2");
+      const p95L2 = p95(m.latency.L2 ?? []);
+      const relPct = (st.dedupHitRate * 100).toFixed(0);
+      const qualityStr = `recall ${relPct}% relevant · FP ${(fp * 100).toFixed(1)}% · L2 p95 ${p95L2.toFixed(0)}ms`;
       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` +
@@ -885,11 +908,114 @@ export default function (pi: ExtensionAPI) {
           `(${fmtB(di.compressedOriginalBytes)} compressed-original) · ` +
           `${di.duplicatesCollapsed} dedup-duplicates collapsed · ` +
           `${C.green}0 bytes permanently deleted${C.reset}\n` +
+          `[mega-compact] 💰 ${costStr}\n` +
+          `[mega-compact] 🎯 ${qualityStr}\n` +
           `[mega-compact] stateDir=${currentStateDir}`,
       );
     },
   });
 
+  // ---- Phase 4: cheap standout commands (data is already persisted) -------
+
+  /** Resolve a checkpoint by id (or "recent"/"last") from this session's store. */
+  function findCheckpoint(sid: string, ref: string) {
+    const all = listCheckpoints(sid, currentStateDir);
+    if (all.length === 0) return undefined;
+    if (!ref || ref === "recent" || ref === "last") return all[all.length - 1];
+    return all.find((c) => c.checkpointId === ref) ?? all.find((c) => c.checkpointId.endsWith(ref));
+  }
+
+  pi.registerCommand("mega-restore", {
+    description: "Re-inject a checkpoint's verbatim original region into context. Usage: /mega-restore <chkpt|recent>",
+    handler: async (args: string, ctx: ExtensionContext) => {
+      bindRepo(ctx.cwd);
+      const sid = normalizeSessionId(ctx.sessionManager.getSessionId());
+      const cp = findCheckpoint(sid, args.trim());
+      if (!cp) {
+        ctx.ui.notify(`[mega-compact] no checkpoint found${args.trim() ? ` for "${args.trim()}"` : ""} in this session. Try /mega-history.`);
+        return;
+      }
+      if (!cp.compressedOriginal) {
+        ctx.ui.notify(`[mega-compact] ${cp.checkpointId} has no recoverable original (pre-blob or direct add). Cannot restore verbatim.`);
+        return;
+      }
+      const original = decompressSmart(cp.compressedOriginal).toString("utf-8");
+      // Re-inject verbatim via before_agent_start (PREVENT-PI-003) — never
+      // touches live messages, only prepends the restored region to systemPrompt.
+      pendingRecallBlock = `The following compacted context was RESTORED from checkpoint ${cp.checkpointId} (verbatim original region):\n\n${original}`;
+      const files = cp.filesModified?.length ? cp.filesModified.join(", ") : "(no files captured)";
+      ctx.ui.notify(
+        `[mega-compact] ♻ restored ${cp.checkpointId} — ${original.length} chars re-injected on next turn.\n` +
+        `[mega-compact] files: ${files}`,
+      );
+      dashboard.event("restore", { checkpointId: cp.checkpointId, chars: original.length });
+    },
+  });
+
+  pi.registerCommand("mega-history", {
+    description: "List this session's checkpoints (id, date, files, tokens). Usage: /mega-history",
+    handler: async (_args: string, ctx: ExtensionContext) => {
+      bindRepo(ctx.cwd);
+      const sid = normalizeSessionId(ctx.sessionManager.getSessionId());
+      const all = listCheckpoints(sid, currentStateDir);
+      if (all.length === 0) {
+        ctx.ui.notify("[mega-compact] no checkpoints in this session yet.");
+        return;
+      }
+      const rows = all.map((c) => {
+        const when = c.timestamp ? new Date(c.timestamp).toISOString().slice(0, 16).replace("T", " ") : "—";
+        const files = c.filesModified?.length ? c.filesModified.map((f) => f.split("/").pop()).join(", ") : "—";
+        const orig = c.originalTokenEstimate ?? 0;
+        const stored = c.tokenEstimate ?? 0;
+        const saved = Math.max(0, orig - stored);
+        return `  ${c.checkpointId}  ${when}  ${C.cyan}${saved}t saved${C.reset}  ${files}`;
+      });
+      ctx.ui.notify(
+        `[mega-compact] ${all.length} checkpoint(s) in this session:\n` + rows.join("\n") +
+        `\n[mega-compact] /mega-view <chkpt> to see the original region · /mega-restore <chkpt> to re-inject it`,
+      );
+    },
+  });
+
+  pi.registerCommand("mega-view", {
+    description: "Show a checkpoint's verbatim original region. Usage: /mega-view <chkpt|recent>",
+    handler: async (args: string, ctx: ExtensionContext) => {
+      bindRepo(ctx.cwd);
+      const sid = normalizeSessionId(ctx.sessionManager.getSessionId());
+      const cp = findCheckpoint(sid, args.trim());
+      if (!cp) {
+        ctx.ui.notify(`[mega-compact] no checkpoint found${args.trim() ? ` for "${args.trim()}"` : ""}. Try /mega-history.`);
+        return;
+      }
+      if (!cp.compressedOriginal) {
+        ctx.ui.notify(`[mega-compact] ${cp.checkpointId} summary:\n${cp.summary.slice(0, 500)}${cp.summary.length > 500 ? "…" : ""}\n(no verbatim original stored)`);
+        return;
+      }
+      const original = decompressSmart(cp.compressedOriginal).toString("utf-8");
+      ctx.ui.notify(
+        `[mega-compact] ${cp.checkpointId} — original region (${original.length} chars):\n` +
+        `${original.slice(0, 1500)}${original.length > 1500 ? "\n…(truncated)" : ""}`,
+      );
+    },
+  });
+
+  pi.registerCommand("mega-help", {
+    description: "Plain-language glossary of what mega-compact's stats mean.",
+    handler: async (_args: string, ctx: ExtensionContext) => {
+      ctx.ui.notify(
+        `[mega-compact] glossary — what the numbers mean:\n` +
+        `• token — a chunk of text (~4 chars). Context window = how much text fits in memory at once.\n` +
+        `• space freed — how much conversation we've compressed away to make room (the win).\n` +
+        `• memory held — how much compact summary we're currently keeping as your 'notes'.\n` +
+        `• saved checkpoint — a compact summary of an old conversation chunk we stored.\n` +
+        `• repeat-skipped — how often new text matched something we already had, so we didn't store a duplicate.\n` +
+        `• injected — times we pasted an old saved note back into the chat because it was relevant.\n` +
+        `• recall relevance — of those, how often the note was actually on-topic.\n` +
+        `• data safety — every compressed region is kept verbatim; nothing is permanently deleted. /mega-restore brings any of it back.`,
+      );
+    },
+  });
+
   pi.registerCommand("mega-tier", {
     description: "Show or change the compaction tier at runtime. Usage: /mega-tier [low|medium|high|ultra|mega]",
     handler: async (args: string, ctx: ExtensionContext) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.4.13",
+  "version": "0.4.15",
   "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/phase04.test.ts

@@ -0,0 +1,58 @@
+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 { listCheckpoints, dataInvariantStats } from "./sqlite.js";
+import { decompressSmart, compressSmart } from "./compression.js";
+
+const baseTmp = mkdtempSync(join(tmpdir(), "mc-p04-"));
+
+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 };
+}
+
+test("Phase 4: added checkpoint is listed and its compressed-original round-trips", () => {
+  const { s, dir } = store();
+  const original = "the original region text that gets compacted and must be restorable verbatim";
+  const r = s.add({ sessionId: "sess_a", summary: "s", regionText: original, tokenEstimate: 5, originalTokenEstimate: 60, timestamp: 1 });
+  const all = listCheckpoints("sess_a", dir);
+  assert.equal(all.length, 1, "one checkpoint listed");
+  const cp = all[0];
+  assert.ok(cp.compressedOriginal, "compressed-original blob present");
+  // The DR/restore path: decompressSmart must return the exact original.
+  const restored = decompressSmart(cp.compressedOriginal!).toString("utf-8");
+  assert.equal(restored, original, "restored verbatim === original");
+  assert.equal(cp.checkpointId, r.checkpoint.checkpointId);
+});
+
+test("Phase 4: findCheckpoint-by-id resolves a listed checkpoint", () => {
+  const { s, dir } = store();
+  s.add({ sessionId: "sess_b", summary: "s1", regionText: "region one text content here", tokenEstimate: 4, originalTokenEstimate: 40, timestamp: 1 });
+  const r2 = s.add({ sessionId: "sess_b", summary: "s2", regionText: "region two text content here different", tokenEstimate: 4, originalTokenEstimate: 45, timestamp: 2 });
+  const all = listCheckpoints("sess_b", dir);
+  assert.equal(all.length, 2);
+  const wanted = all.find((c) => c.checkpointId === r2.checkpoint.checkpointId)!;
+  assert.ok(wanted, "checkpoint resolved by id");
+  assert.ok(wanted.compressedOriginal, "has restorable original");
+});
+
+test("Phase 4: dataInvariantStats sanity for restore trust (0 deleted)", () => {
+  const { s, dir } = store();
+  s.add({ sessionId: "sess_c", summary: "s", regionText: "retained region body text", tokenEstimate: 5, originalTokenEstimate: 50, timestamp: 1 });
+  const di = dataInvariantStats(dir);
+  assert.equal(di.regionsRetained, 1);
+  assert.ok(di.compressedOriginalBytes > 0);
+  assert.equal(di.bytesPermanentlyDeleted, 0);
+});
+
+test("Phase 4: compressSmart/decompressSmart round-trips arbitrary text", () => {
+  const text = "x".repeat(2000);
+  const back = decompressSmart(compressSmart(Buffer.from(text, "utf-8"))).toString("utf-8");
+  assert.equal(back, text);
+});
+
+process.on("exit", () => { try { rmSync(baseTmp, { recursive: true, force: true }); } catch { /* ignore */ } });