pi-mega-compact 0.4.0 → 0.4.2

package/README.md

@@ -115,48 +115,64 @@ OpenAI-style contract and the `MEGACOMPACT_EMBEDDING_KEY` / `MEGACOMPACT_EMBEDDI
   compile). No network call and no API key are needed at runtime.
 - A pi coding agent install that loads extensions from `~/.pi/agent/extensions/`.
 
-### From a git checkout
+### Install from npm (recommended)
 
 ```bash
-git clone https://github.com/TheArchitectit/pi-mega-compact.git \
-  ~/.pi/agent/extensions/pi-mega-compact
-cd ~/.pi/agent/extensions/pi-mega-compact
-npm install
-npm run build
+npm install pi-mega-compact
 ```
 
+This places the package in `node_modules` and exposes the extension entry at
+`node_modules/pi-mega-compact/extensions/mega-compact.ts`. Then point pi at it
+(see "Register with pi" below).
+
 ### Register with pi
 
-Either copy/link the extension into pi's extensions dir (the clone above already
-does), **or** add it to your pi config's `pi.extensions` list:
+Add the extension to your pi config's `pi.extensions` list, pointing at the
+installed entry (npm path or a symlink into pi's extensions dir — either works):
 
 ```jsonc
 {
   "pi": {
-    "extensions": ["~/.pi/agent/extensions/pi-mega-compact/extensions/mega-compact.ts"]
+    "extensions": ["pi-mega-compact/extensions/mega-compact.ts"]
   }
 }
 ```
 
-Or use the bundled helper (needs `jq`):
+Or symlink the installed package into pi's extensions dir (the simplest path if
+you run pi from the same machine):
 
 ```bash
-./install.sh          # copy into ~/.pi/agent/extensions/pi-mega-compact
-./install.sh -s       # symlink instead of copy (dev mode)
+ln -s "$(npm root)/pi-mega-compact" ~/.pi/agent/extensions/pi-mega-compact
 ```
 
+> **From a git checkout (development).** To hack on the extension, clone instead
+> and build locally:
+> ```bash
+> git clone https://github.com/TheArchitectit/pi-mega-compact.git \
+>   ~/.pi/agent/extensions/pi-mega-compact
+> cd ~/.pi/agent/extensions/pi-mega-compact
+> npm install && npm run build
+> ```
+> The bundled `./install.sh` helper (`copy`) / `./install.sh -s` (`symlink`) does
+> the same and also registers the path in pi's config (needs `jq`).
+
 ### Verify
 
 ```bash
-cd ~/.pi/agent/extensions/pi-mega-compact
-npm test          # all unit/integration tests pass (192 as of v0.2.0)
+npm test          # all unit/integration tests pass (278 as of v0.4.0)
 npm run lint      # tsc --noEmit + guardrails scan clean
 ```
 
 ### Uninstall
 
 ```bash
-rm -rf ~/.pi/agent/extensions/pi-mega-compact
+npm uninstall pi-mega-compact
+```
+
+If you symlinked it into pi's extensions dir, also remove that link:
+
+```bash
+rm -f ~/.pi/agent/extensions/pi-mega-compact
 ```
 
 Then remove the path from pi's `pi.extensions` array.

package/extensions/dashboard-server.ts

@@ -53,8 +53,26 @@ interface Snapshot {
   store: {
     checkpointCount: number;
     totalTokenEstimate: number;
+    originalTokens: number;
+    tokensSaved: number;
     injectedCount: number;
     dedupHitRate: number;
+    storageDedupRate: number;
+    dedupCollapsed: number;
+  };
+  crew: {
+    activeAgents: number;
+    currentTurn: number;
+  };
+  repo: {
+    checkpointCount: number;
+    totalTokenEstimate: number;
+    originalTokens: number;
+    tokensSaved: number;
+    sessionCount: number;
+    dedupAttempts: number;
+    dedupCollapsed: number;
+    storageDedupRate: number;
   };
 }
 
@@ -75,7 +93,9 @@ function readSnapshot(snapshotPath: string) {
       session: { id: null, state: null, persistedThisSession: false, lastCheckpointId: null, lastCompactedFrom: 0 },
       context: { tokens: null, percent: null, contextWindow: 0 },
       trigger: { armed: false, ready: false, currentTokens: null, thresholdTokens: 100_000, fastGatePct: 80 },
-      store: { checkpointCount: 0, totalTokenEstimate: 0, injectedCount: 0, dedupHitRate: 0 },
+      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 },
     } as Snapshot;
   }
 }
@@ -166,12 +186,28 @@ function dashboardHtml(tierName: string): string {
     <h2>Vector Store</h2>
     <div class="stat-grid">
       <span class="label">Checkpoints</span><span class="value" id="st-count">0</span>
-      <span class="label">Total Tokens</span><span class="value" id="st-tokens">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>
     </div>
   </div>
+  <div class="card">
+    <h2>Repo (all sessions)</h2>
+    <div class="stat-grid">
+      <span class="label">Checkpoints</span><span class="value" id="rp-count">0</span>
+      <span class="label">Tokens Stored</span><span class="value" id="rp-tokens">0</span>
+      <span class="label">Original Tokens</span><span class="value" id="rp-orig">0</span>
+      <span class="label">Tokens Saved</span><span class="value" id="rp-saved">0</span>
+      <span class="label">Sessions</span><span class="value" id="rp-sessions">0</span>
+      <span class="label">Collapsed</span><span class="value" id="rp-collapsed">0</span>
+      <span class="label">Storage Dedup</span><span class="value" id="rp-sdedup">0%</span>
+    </div>
+  </div>
   <div class="card">
     <h2>Configuration</h2>
     <div class="conf-grid">
@@ -182,6 +218,14 @@ function dashboardHtml(tierName: string): string {
       <span class="label">Anchor</span><span class="value" id="cf-anchor">—</span>
     </div>
   </div>
+  <div class="card">
+    <h2>Crew / Agents</h2>
+    <div class="stat-grid">
+      <span class="label">Active Agents</span><span class="value" id="cr-agents">0</span>
+      <span class="label">Current Turn</span><span class="value" id="cr-turn">0</span>
+      <span class="label">Status</span><span class="value" id="cr-status">idle</span>
+    </div>
+  </div>
 </div>
 
 <div class="events">
@@ -223,10 +267,33 @@ function dashboardHtml(tierName: string): string {
 
     document.getElementById('st-count').textContent = d.store.checkpointCount;
     document.getElementById('st-tokens').textContent = d.store.totalTokenEstimate.toLocaleString();
+    document.getElementById('st-orig').textContent = (d.store.originalTokens || 0).toLocaleString();
+    document.getElementById('st-saved').textContent = (d.store.tokensSaved || 0).toLocaleString();
     document.getElementById('st-injected').textContent = d.store.injectedCount;
     document.getElementById('st-dedup').textContent = Math.round(d.store.dedupHitRate * 100) + '%';
+    var sdr = d.store.storageDedupRate || 0;
+    document.getElementById('st-sdedup').textContent = (sdr * 100 >= 10 ? Math.round(sdr * 100) : (sdr * 100).toFixed(1)) + '%';
+    document.getElementById('st-collapsed').textContent = d.store.dedupCollapsed || 0;
     document.getElementById('st-lastid').textContent = d.session.lastCheckpointId || '—';
 
+    // Repo-wide (all sessions in this repo's SQLite store).
+    var repo = d.repo || { checkpointCount: 0, totalTokenEstimate: 0, originalTokens: 0, tokensSaved: 0, sessionCount: 0, dedupCollapsed: 0, storageDedupRate: 0 };
+    document.getElementById('rp-count').textContent = repo.checkpointCount;
+    document.getElementById('rp-tokens').textContent = repo.totalTokenEstimate.toLocaleString();
+    document.getElementById('rp-orig').textContent = (repo.originalTokens || 0).toLocaleString();
+    document.getElementById('rp-saved').textContent = (repo.tokensSaved || 0).toLocaleString();
+    document.getElementById('rp-sessions').textContent = repo.sessionCount || 0;
+    document.getElementById('rp-collapsed').textContent = repo.dedupCollapsed || 0;
+    var rsdr = repo.storageDedupRate || 0;
+    document.getElementById('rp-sdedup').textContent = (rsdr * 100 >= 10 ? Math.round(rsdr * 100) : (rsdr * 100).toFixed(1)) + '%';
+
+    // Crew / agents (live sub-agent activity + turn).
+    var crew = d.crew || { activeAgents: 0, currentTurn: 0 };
+    document.getElementById('cr-agents').textContent = crew.activeAgents || 0;
+    document.getElementById('cr-turn').textContent = crew.currentTurn || 0;
+    document.getElementById('cr-status').textContent = (crew.activeAgents > 0)
+      ? ('▶ ' + crew.activeAgents + ' running') : 'idle';
+
     document.getElementById('cf-tier').textContent = d.tier;
     document.getElementById('cf-threshold').textContent = d.config.thresholdTokens.toLocaleString();
     document.getElementById('cf-gate').textContent = d.config.fastGatePct + '%';

package/extensions/mega-compact.test.ts

@@ -322,9 +322,24 @@ test("state snapshot writes dashboard.json after compaction", async () => {
   const ctx = h.ctx({ getContextUsage: () => ({ tokens: 200000, contextWindow: 200000, percent: 100 }) });
   // Fire auto-trigger compaction (context event above 80% threshold)
   await h.fire("context", { type: "context", messages: h.session }, ctx);
-  const { existsSync: ex } = await import("node:fs");
+  const { existsSync: ex, readFileSync: rf } = await import("node:fs");
   const { join: j } = await import("node:path");
-  assert.ok(ex(j(h.stateDir, "dashboard.json")), "dashboard.json written after compaction");
+  const snapPath = j(h.stateDir, "dashboard.json");
+  assert.ok(ex(snapPath), "dashboard.json written after compaction");
+  const snap = JSON.parse(rf(snapPath, "utf-8"));
+  // Item B: the honest token model is wired — the original dropped region was
+  // captured (originalTokens > 0), and the saved amount never exceeds the
+  // original (saved = max(0, original − stored) ≤ original). For this tiny
+  // harness session the summary can be ≥ the region, so saved may be 0; the
+  // positive "saved > 0" case with a large region is covered by the
+  // vectorStore unit tests.
+  assert.ok(snap.store.originalTokens > 0, "snapshot.store.originalTokens captured after compaction");
+  assert.ok(
+    snap.store.originalTokens >= snap.store.tokensSaved,
+    "model invariant: original region >= tokens saved",
+  );
+  // Item A: crew (live agent) block is present in the dashboard snapshot.
+  assert.ok(snap.crew && typeof snap.crew.activeAgents === "number", "snapshot.crew.activeAgents present");
 });
 
 test("events.log receives compaction events", async () => {

package/extensions/mega-compact.ts

@@ -37,6 +37,7 @@ 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 { Logger } from "../src/log.js";
 import type { EngineMessage } from "../src/types.js";
 import { writeFileSync, appendFileSync, readFileSync } from "node:fs";
@@ -57,6 +58,7 @@ interface SessionRuntime {
   lastCompactedTokens: number;
   dedupSkips: number;       // compactions skipped because regionHash already stored
   dedupAttempts: number;    // total compaction attempts (for hit-rate denominator)
+  tokensSaved: number;      // this session-instance only: reset on session_start
 }
 
 function envFlag(name: string, fallback: number): number {
@@ -190,12 +192,28 @@ interface DashboardSnapshot {
   store: {
     checkpointCount: number;
     totalTokenEstimate: number;
+    originalTokens: number;      // Σ original dropped-region tokens (this session)
+    tokensSaved: number;         // Σ(original − stored) for this session
     injectedCount: number;
     dedupHitRate: number;
     storageDedupRate: number;
     dedupAttempts: number;
     dedupCollapsed: number;
   };
+  crew: {
+    activeAgents: number;
+    currentTurn: number;
+  };
+  repo: {
+    checkpointCount: number;     // across all sessions in this repo's store
+    totalTokenEstimate: number;  // repo-wide stored checkpoint tokens
+    originalTokens: number;      // repo-wide Σ original dropped-region tokens
+    tokensSaved: number;         // repo-wide cumulative (original − stored) + deduped orig
+    sessionCount: number;        // distinct sessions with checkpoints
+    dedupAttempts: number;       // cumulative add() calls (store-wide)
+    dedupCollapsed: number;      // cumulative deduped collapses (store-wide)
+    storageDedupRate: number;    // deduped / attempts, 0..1
+  };
 }
 
 class Dashboard {
@@ -261,6 +279,7 @@ export default function (pi: ExtensionAPI) {
   function snapshot(ctx?: ExtensionContext): void {
     if (ctx) bindRepo(ctx.cwd);
     const st = store.stats(rt.sessionId);
+    const repo = store.repoStats();
     const armed = lastCtxPercent != null && lastCtxPercent >= config.fastGatePct;
     const ready = armed && (lastCtxTokens ?? 0) >= config.thresholdTokens;
     dashboard.snapshot({
@@ -287,7 +306,18 @@ export default function (pi: ExtensionAPI) {
       },
       context: { tokens: lastCtxTokens, percent: lastCtxPercent, contextWindow: lastCtxWindow },
       trigger: { armed, ready, currentTokens: lastCtxTokens, thresholdTokens: config.thresholdTokens, fastGatePct: config.fastGatePct },
-      store: { checkpointCount: st.checkpointCount, totalTokenEstimate: st.totalTokenEstimate, injectedCount: st.injectedCount, dedupHitRate: st.dedupHitRate, storageDedupRate: st.storageDedupRate, dedupAttempts: st.dedupAttempts, dedupCollapsed: st.dedupCollapsed },
+      crew: { activeAgents, currentTurn },
+      store: { checkpointCount: st.checkpointCount, totalTokenEstimate: st.totalTokenEstimate, originalTokens: st.originalTokens, tokensSaved: rt.tokensSaved, injectedCount: st.injectedCount, dedupHitRate: st.dedupHitRate, storageDedupRate: st.storageDedupRate, dedupAttempts: st.dedupAttempts, dedupCollapsed: st.dedupCollapsed },
+      repo: {
+        checkpointCount: repo.checkpointCount,
+        totalTokenEstimate: repo.totalTokenEstimate,
+        originalTokens: repo.originalTokens,
+        tokensSaved: repo.tokensSaved,
+        sessionCount: repo.sessionCount,
+        dedupAttempts: repo.dedupAttempts,
+        dedupCollapsed: repo.dedupCollapsed,
+        storageDedupRate: repo.storageDedupRate,
+      },
     });
 
     // Live stats widget above the editor
@@ -303,7 +333,12 @@ export default function (pi: ExtensionAPI) {
       const dedupStr = storageRate * 100 >= 10
         ? `${Math.round(storageRate * 100)}%`
         : `${(storageRate * 100).toFixed(1)}%`;
-      const savedStr = st.totalTokenEstimate > 0 ? `${Math.round(st.totalTokenEstimate / 1000)}k` : "0";
+      // saved = cumulative original − stored tokens (this session). Show real
+      // token counts; use "k" only at/above 1000 so small-but-real savings are
+      // visible (previously Math.round(x/1000) rounded everything <1000 to 0).
+      const savedStr = rt.tokensSaved >= 1000
+        ? `${(rt.tokensSaved / 1000).toFixed(1)}k`
+        : `${rt.tokensSaved}`;
       const agentStr = activeAgents > 0 ? ` │ 🤖 ${activeAgents} agent${activeAgents === 1 ? "" : "s"}` : "";
       const turnStr = currentTurn > 0 ? ` │ turn ${currentTurn}` : "";
       ctx.ui.setWidget(
@@ -326,6 +361,7 @@ export default function (pi: ExtensionAPI) {
     lastCompactedTokens: 0,
     dedupSkips: 0,
     dedupAttempts: 0,
+    tokensSaved: 0,
   };
   let debounceUntil = 0;
   // Agent tracking for real-time widget updates
@@ -352,6 +388,7 @@ export default function (pi: ExtensionAPI) {
       lastCompactedTokens: 0,
       dedupSkips: 0,
       dedupAttempts: 0,
+      tokensSaved: 0,
     };
     statusKey = undefined;
     activeAgents = 0;
@@ -392,8 +429,28 @@ export default function (pi: ExtensionAPI) {
     rt.lastCompactedFrom = result.compactedFrom;
     rt.lastCompactedTokens = result.tokenEstimate;
     rt.dedupAttempts++;
+    // Honest "tokens saved" for this session-instance only:
+    //   new checkpoint      → original − stored
+    //   deduped onto existing → whole original region (nothing new stored)
+    // Resets to 0 on session_start (rt is rebuilt) — so a fresh session shows 0
+    // while the repo's cumulative saved (SQLite meta) keeps the running total.
+    const saved = result.deduped
+      ? result.originalTokenEstimate
+      : Math.max(0, result.originalTokenEstimate - result.tokenEstimate);
+    rt.tokensSaved += saved;
     if (result.deduped) rt.dedupSkips++;
 
+    // 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.
+    try {
+      const repo = resolveRepoRoot(ctx.cwd);
+      touchSession(sid, repo, currentStateDir);
+      logDaily(sid, "compact", result.checkpointId, saved, currentStateDir);
+    } catch {
+      /* non-fatal: stats bookkeeping only */
+    }
+
     // Sentinel marker: a non-LLM bookkeeping entry so subsequent triggers can
     // skip re-vectorizing an already-compacted region (zero token cost).
     pi.appendEntry(MARKER_TYPE, {
@@ -403,7 +460,6 @@ export default function (pi: ExtensionAPI) {
       deduped: result.deduped,
     });
 
-    const saved = result.tokenEstimate;
     setStatus(
       ctx,
       rt.persistedThisSession

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "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

@@ -15,7 +15,7 @@
 import { findSuperseded, supersede } from "./supersede.js";
 import { summarizeMessages, mergeCompactSummaries, formatCompactSummary } from "./compact.js";
 import { extractiveSummarize } from "./extractive.js";
-import { estimateSessionTokens } from "./tokens.js";
+import { estimateSessionTokens, estimateBlockTokens } from "./tokens.js";
 import { computeRegionHash, VectorStore, type SearchHit } from "./vectorStore.js";
 import type { EngineMessage } from "./types.js";
 
@@ -51,6 +51,11 @@ export interface CompactResult {
   summary: string;
   regionHash: string;
   tokenEstimate: number;
+  /** Token count of the original dropped region (before compaction). The honest
+   *  "tokens saved" base = originalTokenEstimate − tokenEstimate (stored), or the
+   *  full originalTokenEstimate when the region deduped onto an existing
+   *  checkpoint (nothing new stored). */
+  originalTokenEstimate: number;
   /** Index in `messages` where the compacted slice begins (for the caller to
    *  build a drop range). */
   compactedFrom: number;
@@ -87,6 +92,7 @@ export function compactSession(input: CompactInput, store: VectorStore = getDefa
       summary: "",
       regionHash: "",
       tokenEstimate: 0,
+      originalTokenEstimate: 0,
       compactedFrom,
     };
   }
@@ -105,7 +111,6 @@ export function compactSession(input: CompactInput, store: VectorStore = getDefa
   let keyDecisions: string[];
   let nextSteps: string[];
   let filesModified: string[];
-  let tokenEstimate: number;
 
   if (useExtractive && !input.summary) {
     const ext = extractiveSummarize(keep);
@@ -114,7 +119,6 @@ export function compactSession(input: CompactInput, store: VectorStore = getDefa
     keyDecisions = input.keyDecisions ?? ext.keyDecisions;
     nextSteps = input.nextSteps ?? ext.nextSteps;
     filesModified = input.filesModified ?? ext.filesModified;
-    tokenEstimate = input.tokenEstimate ?? ext.tokenEstimate;
   } else {
     const collapsed = input.summary ?? summarizeMessages(keep);
     summary = formatCompactSummary(collapsed);
@@ -122,9 +126,18 @@ export function compactSession(input: CompactInput, store: VectorStore = getDefa
     keyDecisions = input.keyDecisions ?? [];
     nextSteps = input.nextSteps ?? [];
     filesModified = input.filesModified ?? [];
-    tokenEstimate = input.tokenEstimate ?? estimateSessionTokens(compactable);
   }
 
+  // Honest "tokens saved" accounting:
+  //  - originalTokenEstimate = the dropped region's token count (what context
+  //    held before compaction) = the compacted slice's tokens.
+  //  - storedTokens = the persisted summary's token count, computed from the
+  //    actual summary string so it's honest for BOTH the extractive and legacy
+  //    COLLAPSE paths (the legacy path's fallback estimateSessionTokens is the
+  //    *original* size, not the stored size).
+  const originalTokenEstimate = estimateSessionTokens(compactable);
+  const storedTokens = estimateBlockTokens(summary);
+
   // Region text = the compacted slice, used for dedup + embedding.
   const regionText = input.regionText ?? keep.map((m) => m.text).join("\n");
   const regionHash = computeRegionHash(regionText);
@@ -137,7 +150,8 @@ export function compactSession(input: CompactInput, store: VectorStore = getDefa
     nextSteps,
     filesModified,
     regionText,
-    tokenEstimate,
+    tokenEstimate: storedTokens,
+    originalTokenEstimate,
     timestamp: input.timestamp ?? 0,
   });
 
@@ -148,7 +162,8 @@ export function compactSession(input: CompactInput, store: VectorStore = getDefa
     checkpointId: add.checkpoint.checkpointId,
     summary,
     regionHash,
-    tokenEstimate,
+    tokenEstimate: storedTokens,
+    originalTokenEstimate,
     compactedFrom,
   };
 }

package/src/store/sqlite.ts

@@ -80,6 +80,7 @@ function initSchema(db: Database.Database): void {
       files_modified     TEXT,           -- JSON array
       embedding_blob     BLOB,           -- float32 vector
       token_estimate     INTEGER,
+      original_token_estimate INTEGER,    -- dropped region size (tokens saved = orig − stored)
       timestamp          INTEGER,
       dedup_status       TEXT DEFAULT 'active',
       compressed_original BLOB           -- optional DR copy
@@ -145,6 +146,49 @@ function initSchema(db: Database.Database): void {
     );
     CREATE INDEX IF NOT EXISTS idx_raptor_session ON raptor_nodes(session_id);
     CREATE INDEX IF NOT EXISTS idx_raptor_parent ON raptor_nodes(parent_id);
+
+    -- Foundation for future features (resume sessions, daily log, lessons
+    -- learned). Scaffolded now so all store data lives in SQLite from day one;
+    -- population is minimal (touchSession / logDaily on compact) and the full
+    -- UI/recall for these lands in later sprints.
+
+    -- Per-session registry (resume + per-repo session history).
+    CREATE TABLE IF NOT EXISTS sessions (
+      session_id    TEXT PRIMARY KEY,
+      repo          TEXT,
+      started_at    INTEGER,
+      ended_at      INTEGER,
+      last_compacted_at INTEGER,
+      status        TEXT DEFAULT 'active'
+    );
+
+    -- Append-only daily activity log (the "daily log" feature seed).
+    CREATE TABLE IF NOT EXISTS daily_log (
+      id            INTEGER PRIMARY KEY AUTOINCREMENT,
+      day           TEXT NOT NULL,     -- YYYY-MM-DD
+      session_id    TEXT,
+      event         TEXT,             -- e.g. 'compact'
+      detail        TEXT,
+      tokens_saved  INTEGER DEFAULT 0,
+      ts            INTEGER
+    );
+    CREATE INDEX IF NOT EXISTS idx_daily_log_day ON daily_log(day);
+
+    -- Lessons learned (future recall/browse feature seed).
+    CREATE TABLE IF NOT EXISTS lessons (
+      id            INTEGER PRIMARY KEY AUTOINCREMENT,
+      session_id    TEXT,
+      repo          TEXT,
+      lesson        TEXT,
+      ts            INTEGER
+    );
+
+    -- FTS5 trigram virtual table (Sprint 9+ pg_trgm-equivalent verification).
+    CREATE VIRTUAL TABLE IF NOT EXISTS context_chunks_trgm USING fts5(
+      id UNINDEXED,
+      normalized_text,
+      tokenize='trigram'
+    );
   `);
   const v = db.prepare("SELECT value FROM meta WHERE key='schema_version'").get() as
     | { value: string }
@@ -152,15 +196,139 @@ function initSchema(db: Database.Database): void {
   if (!v) {
     db.prepare("INSERT INTO meta(key, value) VALUES(?, ?)").run("schema_version", String(SCHEMA_VERSION));
   }
+}
 
-  // FTS5 trigram virtual table (Sprint 9+ pg_trgm-equivalent verification).
-  db.exec(`
-    CREATE VIRTUAL TABLE IF NOT EXISTS context_chunks_trgm USING fts5(
-      id UNINDEXED,
-      normalized_text,
-      tokenize='trigram'
-    );
-  `);
+/** Read a string-valued meta key (or undefined). Used for cumulative counters. */
+export function getMeta(key: string, stateDir: string = getStateDir()): string | undefined {
+  const db = openStore(stateDir);
+  const row = db.prepare("SELECT value FROM meta WHERE key = ?").get(key) as
+    | { value: string }
+    | undefined;
+  return row?.value;
+}
+
+/**
+ * Cumulative "tokens saved" — the sum of stored checkpoint token estimates across
+ * all compactions in this store (one per repo). Persisted in the SQLite `meta`
+ * table so it survives session restarts and travels with the repo's state dir,
+ * mirroring how `storageDedupRate` is cumulative. Incremented in VectorStore.add()
+ * when a new (non-deduped) checkpoint is persisted.
+ */
+export function getTokensSaved(stateDir: string = getStateDir()): number {
+  const raw = getMeta("tokens_saved", stateDir);
+  const n = raw == null ? 0 : Number(raw);
+  return Number.isFinite(n) ? n : 0;
+}
+
+/** Add `delta` (>=0) to the cumulative tokens-saved counter. */
+export function addTokensSaved(delta: number, stateDir: string = getStateDir()): void {
+  if (!(delta > 0)) return;
+  const db = openStore(stateDir);
+  db.prepare(
+    `INSERT INTO meta(key, value) VALUES('tokens_saved', ?)
+     ON CONFLICT(key) DO UPDATE SET value = CAST(CAST(value AS INTEGER) + ? AS TEXT)`,
+  ).run(String(delta), delta);
+}
+
+/** Cumulative store-wide dedup accounting (Sprint 9+). Persisted in the SQLite
+ *  `meta` table so it survives session restarts and travels with the repo's
+ *  state dir — mirroring `tokens_saved`. Replaces the legacy JSON
+ *  `dedup-stats.json` file (all stats now live in the SQLite store). */
+export interface DedupStats {
+  /** Total add() calls (new checkpoints + deduped collapses). */
+  attempts: number;
+  /** add() calls that collapsed onto an existing checkpoint. */
+  deduped: number;
+}
+
+/** Read a store-wide integer counter from the meta table (0 if absent). */
+export function getMetaNumber(key: string, stateDir: string = getStateDir()): number {
+  const raw = getMeta(key, stateDir);
+  const n = raw == null ? 0 : Number(raw);
+  return Number.isFinite(n) ? n : 0;
+}
+
+/** Atomically add `delta` to an integer meta counter. */
+function incMeta(key: string, delta: number, stateDir: string = getStateDir()): void {
+  if (!(delta > 0)) return;
+  const db = openStore(stateDir);
+  db.prepare(
+    `INSERT INTO meta(key, value) VALUES(?, ?)
+     ON CONFLICT(key) DO UPDATE SET value = CAST(CAST(value AS INTEGER) + ? AS TEXT)`,
+  ).run(key, String(delta), delta);
+}
+
+/** Read the cumulative store-wide dedup counters. */
+export function getDedupStats(stateDir: string = getStateDir()): DedupStats {
+  return {
+    attempts: getMetaNumber("dedup_attempts", stateDir),
+    deduped: getMetaNumber("deduped", stateDir),
+  };
+}
+
+/** Increment the store-wide dedup counters for one add() call. */
+export function bumpDedupStats(deduped: boolean, stateDir: string = getStateDir()): void {
+  incMeta("dedup_attempts", 1, stateDir);
+  if (deduped) incMeta("deduped", 1, stateDir);
+}
+
+// --- Future-feature foundation (resume sessions / daily log / lessons) -------
+// Scaffolded tables + minimal helpers so all store data lives in SQLite from
+// day one. Full UI/recall for these lands in later sprints.
+
+/** Upsert a `sessions` row (resume + per-repo session history). */
+export function touchSession(
+  sessionId: string,
+  repo: string | undefined,
+  stateDir: string = getStateDir(),
+): void {
+  const db = openStore(stateDir);
+  const sid = normalizeSessionId(sessionId);
+  const existing = db
+    .prepare("SELECT started_at FROM sessions WHERE session_id = ?")
+    .get(sid) as { started_at: number | null } | undefined;
+  const now = Math.floor(Date.now() / 1000);
+  if (!existing) {
+    db.prepare(
+      `INSERT INTO sessions(session_id, repo, started_at, last_compacted_at, status)
+       VALUES(?, ?, ?, ?, 'active')`,
+    ).run(sid, repo ?? null, now, now);
+  } else {
+    db.prepare(
+      "UPDATE sessions SET last_compacted_at = ?, repo = COALESCE(?, repo), status = 'active' WHERE session_id = ?",
+    ).run(now, repo ?? null, sid);
+  }
+}
+
+/** Append a `daily_log` entry (day = YYYY-MM-DD, local-naive from Date). */
+export function logDaily(
+  sessionId: string,
+  event: string,
+  detail: string | undefined,
+  tokensSaved: number,
+  stateDir: string = getStateDir(),
+): void {
+  const db = openStore(stateDir);
+  const day = new Date().toISOString().slice(0, 10);
+  const now = Math.floor(Date.now() / 1000);
+  db.prepare(
+    `INSERT INTO daily_log(day, session_id, event, detail, tokens_saved, ts)
+     VALUES(?, ?, ?, ?, ?, ?)`,
+  ).run(day, normalizeSessionId(sessionId), event, detail ?? null, tokensSaved, now);
+}
+
+/** Append a `lessons` entry (future lessons-learned browse/recall). */
+export function addLesson(
+  sessionId: string,
+  repo: string | undefined,
+  lesson: string,
+  stateDir: string = getStateDir(),
+): void {
+  const db = openStore(stateDir);
+  const now = Math.floor(Date.now() / 1000);
+  db.prepare(
+    `INSERT INTO lessons(session_id, repo, lesson, ts) VALUES(?, ?, ?, ?)`,
+  ).run(normalizeSessionId(sessionId), repo ?? null, lesson, now);
 }
 
 /** Map a DB row to the public StoredCheckpoint shape. */
@@ -175,6 +343,7 @@ function rowToCheckpoint(row: any): StoredCheckpoint {
     nextSteps: row.next_steps ? JSON.parse(row.next_steps) : [],
     filesModified: row.files_modified ? JSON.parse(row.files_modified) : [],
     tokenEstimate: row.token_estimate ?? 0,
+    originalTokenEstimate: row.original_token_estimate ?? undefined,
     regionHash: row.region_hash ?? "",
     contentHash: row.content_hash ?? undefined,
     contentHash2: row.content_hash2 ?? undefined,
@@ -197,11 +366,11 @@ export function upsertCheckpoint(cp: StoredCheckpoint, stateDir: string = getSta
         (id, session_id, region_hash, content_hash, content_hash2, content_hash_version,
          normalized_text, summary, topic_summary, summary_hash,
          key_decisions, next_steps, files_modified, embedding_blob,
-         token_estimate, timestamp, dedup_status, compressed_original)
+         token_estimate, original_token_estimate, timestamp, dedup_status, compressed_original)
        VALUES (@id, @sid, @region_hash, @content_hash, @content_hash2, @content_hash_version,
                @normalized_text, @summary, @topic_summary, @summary_hash,
                @key_decisions, @next_steps, @files_modified, @embedding_blob,
-               @token_estimate, @timestamp, @dedup_status, @compressed_original)
+               @token_estimate, @original_token_estimate, @timestamp, @dedup_status, @compressed_original)
        ON CONFLICT(session_id, id) DO UPDATE SET
          summary=excluded.summary,
          topic_summary=excluded.topic_summary,
@@ -211,6 +380,7 @@ export function upsertCheckpoint(cp: StoredCheckpoint, stateDir: string = getSta
          files_modified=excluded.files_modified,
          embedding_blob=excluded.embedding_blob,
          token_estimate=excluded.token_estimate,
+         original_token_estimate=excluded.original_token_estimate,
          timestamp=excluded.timestamp,
          dedup_status=excluded.dedup_status,
          compressed_original=excluded.compressed_original`,
@@ -230,6 +400,7 @@ export function upsertCheckpoint(cp: StoredCheckpoint, stateDir: string = getSta
       files_modified: jsonText(cp.filesModified),
       embedding_blob: encodeEmbedding(cp.embedding ?? []),
       token_estimate: cp.tokenEstimate ?? 0,
+      original_token_estimate: cp.originalTokenEstimate ?? null,
       timestamp: cp.timestamp ?? 0,
       dedup_status: "active",
       compressed_original: cp.compressedOriginal ?? null,
@@ -423,6 +594,52 @@ export function storeStats(sessionId: string, stateDir: string = getStateDir()):
   };
 }
 
+/** Repo-wide stats — aggregates every session in this store (one per repo).
+ *  Backed by the SQLite `meta` cumulative counters (`tokens_saved`,
+ *  `dedup_attempts`, `deduped`) plus a SUM over all `context_chunks`. This is the
+ *  cumulative, resumable, cross-device view the dashboard surfaces as "Repo …". */
+export interface RepoStats {
+  /** Total checkpoints across all sessions (excludes SemDeDup-removed rows). */
+  checkpointCount: number;
+  /** Sum of all stored checkpoint token estimates (repo-wide). */
+  totalTokenEstimate: number;
+  /** Total active sessions with at least one checkpoint. */
+  sessionCount: number;
+  /** Cumulative stored-summary tokens saved (Σ stored summaries). */
+  tokensSaved: number;
+  /** Sum of original dropped-region token estimates (repo-wide). */
+  originalTokens: number;
+  /** Cumulative dedup add() attempts (store-wide). */
+  dedupAttempts: number;
+  /** Cumulative deduped collapses (store-wide). */
+  dedupCollapsed: number;
+  /** Storage dedup rate (deduped / attempts), 0..1. */
+  storageDedupRate: number;
+}
+
+export function repoStats(stateDir: string = getStateDir()): RepoStats {
+  const db = openStore(stateDir);
+  const row = db
+    .prepare(
+      `SELECT COUNT(*) AS c, COALESCE(SUM(token_estimate),0) AS tok,
+              COALESCE(SUM(original_token_estimate),0) AS orig,
+              COUNT(DISTINCT session_id) AS sessions
+       FROM context_chunks WHERE dedup_status != 'removed'`,
+    )
+    .get() as { c: number; tok: number; orig: number; sessions: number };
+  const ds = getDedupStats(stateDir);
+  return {
+    checkpointCount: row.c,
+    totalTokenEstimate: row.tok,
+    originalTokens: row.orig,
+    sessionCount: row.sessions,
+    tokensSaved: getMetaNumber("tokens_saved", stateDir),
+    dedupAttempts: ds.attempts,
+    dedupCollapsed: ds.deduped,
+    storageDedupRate: ds.attempts === 0 ? 0 : ds.deduped / ds.attempts,
+  };
+}
+
 /** Close and evict a cached connection (test teardown only). */
 export function closeStore(stateDir: string): void {
   const db = cache.get(stateDir);

package/src/store.ts

@@ -58,6 +58,9 @@ export interface StoredCheckpoint {
   nextSteps: string[];
   filesModified: string[];
   tokenEstimate: number;
+  /** Token count of the ORIGINAL dropped region (before compaction). Drives the
+   *  honest "tokens saved" = originalTokenEstimate − tokenEstimate. */
+  originalTokenEstimate?: number;
   regionHash: string;
   /** Primary content-addressable hash (full 64-hex SHA-256 of normalized text). */
   contentHash?: string;
@@ -168,25 +171,8 @@ export function saveSessionState(sessionId: string, state: SessionState, stateDi
 }
 
 /**
- * Cumulative store-wide dedup accounting. Lives outside the per-session
- * SessionState (which resets on every session instance) so the dedup rate
- * stays stable across session restarts. Persisted as plain JSON in the
- * state dir.
+ * Cumulative store-wide dedup accounting now lives in the SQLite `meta` table
+ * (see store/sqlite.ts: getDedupStats / bumpDedupStats). All store stats are
+ * SQLite-backed so they survive session restarts and travel with the repo's
+ * state dir. The legacy JSON `dedup-stats.json` path was removed.
  */
-export interface DedupStats {
-  /** Total add() calls (new checkpoints + deduped collapses). */
-  attempts: number;
-  /** add() calls that collapsed onto an existing checkpoint. */
-  deduped: number;
-}
-
-const DEDUP_STATS_FILE = "dedup-stats.json";
-
-export function loadDedupStats(stateDir: string = getStateDir()): DedupStats {
-  const file = join(stateDir, DEDUP_STATS_FILE);
-  return readGzJson<DedupStats>(file, { attempts: 0, deduped: 0 });
-}
-
-export function saveDedupStats(stats: DedupStats, stateDir: string = getStateDir()): void {
-  writeGzJson(join(stateDir, DEDUP_STATS_FILE), stats);
-}

package/src/vectorStore.test.ts

@@ -250,6 +250,59 @@ test("stats reports counts, last checkpoint, and dedup rate", () => {
   assert.ok(Math.abs(st2.dedupHitRate - 0.5) < 1e-9);
 });
 
+test("tokensSaved = original − stored per session; deduped add saves the whole region", () => {
+  const s = store();
+  // Two genuinely new checkpoints. saved = original − stored.
+  //   cp1: orig 2000, stored 500 → saved 1500
+  //   cp2: orig 3000, stored 700 → saved 2300
+  s.add({ sessionId: "sess_saved", summary: "alpha", regionText: "region alpha text", tokenEstimate: 500, originalTokenEstimate: 2000, timestamp: 1 });
+  s.add({ sessionId: "sess_saved", summary: "beta", regionText: "region beta text", tokenEstimate: 700, originalTokenEstimate: 3000, timestamp: 2 });
+  const st = s.stats("sess_saved");
+  assert.equal(st.totalTokenEstimate, 1200, "Σ stored summaries");
+  assert.equal(st.originalTokens, 5000, "Σ original region tokens");
+  assert.equal(st.tokensSaved, 3800, "per-session saved = Σ(original − stored) = 1500 + 2300");
+  assert.equal(st.dedupCollapsed, 0);
+  assert.equal(st.dedupAttempts, 2);
+
+  // A third add that dedups onto an existing region: whole original region (2000)
+  // is discarded (nothing new stored) → repo saved grows by the full original,
+  // dedupCollapsed bumps, and no new checkpoint row is created.
+  const deduped = s.add({ sessionId: "sess_saved", summary: "alpha", regionText: "region alpha text", tokenEstimate: 500, originalTokenEstimate: 2000, timestamp: 3 });
+  assert.ok(deduped.deduped, "identical region should dedup");
+  const st3 = s.stats("sess_saved");
+  // Per-session DB sum only covers stored rows (deduped adds create no row), so
+  // the per-session figure is unchanged; the deduped save lands in the repo meta.
+  assert.equal(st3.tokensSaved, 3800, "per-session DB sum unchanged by deduped add");
+  assert.equal(st3.dedupCollapsed, 1, "deduped collapse counted");
+  assert.equal(st3.dedupAttempts, 3);
+  // Repo cumulative counter DID capture the deduped region's full original size.
+  assert.equal(s.repoStats().tokensSaved, 3800 + 2000, "repo saved includes deduped original");
+});
+
+test("repoStats aggregates every session + counts deduped original tokens", () => {
+  const dir = join(baseTmp, `repo-${counter++}`);
+  const a = new VectorStore({ dedupSim: 0.9, stateDir: dir });
+  const b = new VectorStore({ dedupSim: 0.9, stateDir: dir }); // same disk store, diff instance
+  a.add({ sessionId: "sess_a", summary: "alpha", regionText: "region alpha text", tokenEstimate: 500, originalTokenEstimate: 2000, timestamp: 1 });
+  b.add({ sessionId: "sess_b", summary: "beta", regionText: "region beta text", tokenEstimate: 700, originalTokenEstimate: 3000, timestamp: 2 });
+
+  const repo = a.repoStats();
+  assert.equal(repo.checkpointCount, 2, "checkpoints across both sessions");
+  assert.equal(repo.sessionCount, 2, "two distinct sessions");
+  assert.equal(repo.totalTokenEstimate, 1200, "Σ stored");
+  assert.equal(repo.originalTokens, 5000, "Σ original");
+  assert.equal(repo.tokensSaved, 3800, "repo saved = Σ(original − stored) = 1500 + 2300");
+  assert.equal(repo.dedupCollapsed, 0);
+
+  // A deduped add into sess_a: whole original region saved, no new row.
+  const deduped = a.add({ sessionId: "sess_a", summary: "alpha", regionText: "region alpha text", tokenEstimate: 500, originalTokenEstimate: 2000, timestamp: 3 });
+  assert.ok(deduped.deduped);
+  const repo2 = a.repoStats();
+  assert.equal(repo2.tokensSaved, 3800 + 2000, "deduped collapse adds full original region to repo saved");
+  assert.equal(repo2.dedupCollapsed, 1);
+  assert.equal(repo2.checkpointCount, 2, "still two stored checkpoints");
+});
+
 test("computeRegionHash normalizes whitespace before hashing", () => {
   const h1 = computeRegionHash("foo  bar");
   const h2 = computeRegionHash("foo bar");

package/src/vectorStore.ts

@@ -14,7 +14,7 @@ import { cosineSimilarity, defaultEmbedder } from "./embedder.js";
 import { loadDedupConfig, type DedupConfigShape, type DedupTier } from "./config/dedup.js";
 import { logDecision } from "./monitoring.js";
 import type { StoredCheckpoint, SessionState } from "./store.js";
-import { getStateDir, normalizeSessionId, compressSmart, loadDedupStats, saveDedupStats } from "./store.js";
+import { getStateDir, normalizeSessionId, compressSmart } from "./store.js";
 import { computeContentDigest } from "./dedup/digest.js";
 import { minhashSignature, SIGNATURE_VERSION, NUM_HASHES } from "./dedup/l1-minhash.js";
 import { lshBands } from "./dedup/l1-lsh.js";
@@ -32,6 +32,10 @@ import {
   insertLshBuckets,
   lshCandidateChunks,
   setDedupStatus,
+  addTokensSaved,
+  getDedupStats,
+  bumpDedupStats,
+  repoStats as repoStatsFromStore,
 } from "./store/sqlite.js";
 import { migrateJsonToSqlite } from "./store/migrate.js";
 
@@ -49,6 +53,11 @@ export interface AddInput {
   nextSteps?: string[];
   filesModified?: string[];
   tokenEstimate?: number;
+  /** Token count of the ORIGINAL dropped region (before compaction). Drives the
+   *  honest "tokens saved" = originalTokenEstimate − tokenEstimate (stored), or
+   *  the full originalTokenEstimate when the region dedups (nothing new stored).
+   *  Optional for back-compat with direct add() callers; defaults to stored. */
+  originalTokenEstimate?: number;
   /** Raw text of the compacted region — used to derive the regionHash + vector. */
   regionText: string;
   timestamp: number;
@@ -136,10 +145,11 @@ export class VectorStore {
     const sessionId = normalizeSessionId(input.sessionId);
     const regionHash = computeRegionHash(input.regionText);
     const all = listCheckpoints(sessionId, this.stateDir);
+    // Honest "tokens saved" base for this region. For a deduped add the whole
+    // original region is discarded (nothing new stored); for a new checkpoint
+    // we persist (orig − stored). Falls back to stored when orig is unknown.
+    const origTokens = input.originalTokenEstimate ?? input.tokenEstimate ?? 0;
     const cfg = this.cfg;
-    // Cumulative store-wide dedup accounting (survives session resets).
-    const ds = loadDedupStats(this.stateDir);
-    ds.attempts++;
     // Tracks whether a tier matched while in MARK_ONLY (record-but-don't-collapse),
     // and which tier.
     let markOnly: DedupTier | null = null;
@@ -165,8 +175,9 @@ export class VectorStore {
         } else {
           contentMatch.timestamp = input.timestamp;
           upsertCheckpoint(contentMatch, this.stateDir);
-          ds.deduped++;
-          saveDedupStats(ds, this.stateDir);
+          bumpDedupStats(true, this.stateDir);
+          // Deduped: whole original region discarded, nothing new stored.
+          addTokensSaved(origTokens, this.stateDir);
           const r = { checkpoint: contentMatch, deduped: true, reason: "contentHash" };
           this.record("L0", "deduped", "contentHash", Date.now() - t0);
           return r;
@@ -181,8 +192,9 @@ export class VectorStore {
         if (cfg.MARK_ONLY_L0) {
           markOnly = "L0"; // fall through
         } else {
-          ds.deduped++;
-          saveDedupStats(ds, this.stateDir);
+          bumpDedupStats(true, this.stateDir);
+          // Deduped: whole original region discarded, nothing new stored.
+          addTokensSaved(origTokens, this.stateDir);
           const r = { checkpoint: regionMatch, deduped: true, reason: "regionHash" };
           this.record("L0", "deduped", "regionHash", Date.now() - t0);
           return r;
@@ -203,8 +215,9 @@ export class VectorStore {
         } else {
           summaryMatch.timestamp = input.timestamp;
           upsertCheckpoint(summaryMatch, this.stateDir);
-          ds.deduped++;
-          saveDedupStats(ds, this.stateDir);
+          bumpDedupStats(true, this.stateDir);
+          // Deduped: whole original region discarded, nothing new stored.
+          addTokensSaved(origTokens, this.stateDir);
           const r = { checkpoint: summaryMatch, deduped: true, reason: "summaryHash" };
           this.record("L0", "deduped", "summaryHash", Date.now() - t0);
           return r;
@@ -221,8 +234,7 @@ export class VectorStore {
       if (l1 && !cfg.MARK_ONLY_L1) {
         l1.timestamp = input.timestamp;
         upsertCheckpoint(l1, this.stateDir);
-        ds.deduped++;
-        saveDedupStats(ds, this.stateDir);
+        bumpDedupStats(true, this.stateDir);
         const r = { checkpoint: l1, deduped: true, reason: "l1MinHash" };
         this.record("L1", "deduped", "l1MinHash", Date.now() - t0);
         return r;
@@ -257,8 +269,9 @@ export class VectorStore {
           // Near-identical — update timestamp on existing checkpoint
           nearest.checkpoint.timestamp = input.timestamp;
           upsertCheckpoint(nearest.checkpoint, this.stateDir);
-          ds.deduped++;
-          saveDedupStats(ds, this.stateDir);
+          bumpDedupStats(true, this.stateDir);
+          // Deduped: whole original region discarded, nothing new stored.
+          addTokensSaved(origTokens, this.stateDir);
           const r = { checkpoint: nearest.checkpoint, deduped: true, reason: "contentSimilarity" };
           this.record("L2", "deduped", "contentSimilarity", Date.now() - t0);
           return r;
@@ -279,6 +292,7 @@ export class VectorStore {
       nextSteps: input.nextSteps ?? [],
       filesModified: input.filesModified ?? [],
       tokenEstimate: input.tokenEstimate ?? 0,
+      originalTokenEstimate: input.originalTokenEstimate,
       regionHash,
       contentHash: digest.contentHash,
       contentHash2: digest.contentHash2,
@@ -291,6 +305,12 @@ export class VectorStore {
     // Persistence is SQLite (store/sqlite.ts). upsertCheckpoint keeps the
     // idempotent-by-id semantics the old JSON append implied.
     upsertCheckpoint(checkpoint, this.stateDir);
+    // Cumulative "tokens saved" counter (per-repo SQLite meta). For a NEW
+    // checkpoint the saved amount is (original − stored); for a deduped add the
+    // whole original region is discarded (handled in the deduped return paths
+    // below). Survives sessions and travels with the repo.
+    const stored = input.tokenEstimate ?? 0;
+    addTokensSaved(Math.max(0, origTokens - stored), this.stateDir);
     // L1: persist this checkpoint's MinHash signature + LSH buckets so future
     // near-duplicate inserts can find it. Deterministic given the seed.
     const sig = minhashSignature(input.regionText);
@@ -320,7 +340,8 @@ export class VectorStore {
     } else {
       this.record("L0", "new", undefined, Date.now() - t0);
     }
-    saveDedupStats(ds, this.stateDir);
+    // Cumulative store-wide dedup accounting (attempt, not collapsed).
+    bumpDedupStats(false, this.stateDir);
     return { checkpoint, deduped: false };
   }
 
@@ -517,6 +538,8 @@ export class VectorStore {
     injectedCount: number;
     dedupHitRate: number; // injected / checkpoints, 0..1
     storageDedupRate: number; // deduped adds / total adds, 0..1 (cumulative)
+    tokensSaved: number; // Σ(original − stored) for this session's checkpoints
+    originalTokens: number; // Σ original region size for this session's checkpoints
     dedupAttempts: number; // cumulative add() calls (store-wide)
     dedupCollapsed: number; // cumulative deduped collapses (store-wide)
   } {
@@ -528,17 +551,38 @@ export class VectorStore {
     );
     const last = ordered[ordered.length - 1];
     const injected = state.injectedCheckpointIds.length;
-    const ds = loadDedupStats(this.stateDir);
+    const ds = getDedupStats(this.stateDir);
+    const sessionTok = cps.reduce((s, c) => s + (c.tokenEstimate ?? 0), 0);
+    const sessionOrig = cps.reduce((s, c) => s + (c.originalTokenEstimate ?? 0), 0);
+    // Per-session "tokens saved" = Σ(original − stored) over this session's
+    // stored checkpoints. Deduped adds (whole region discarded, nothing stored)
+    // are counted in the repo-wide meta counter via repoStats(); the per-session
+    // DB sum here covers the rows that exist.
+    const sessionSaved = cps.reduce(
+      (s, c) => s + Math.max(0, (c.originalTokenEstimate ?? 0) - (c.tokenEstimate ?? 0)),
+      0,
+    );
     return {
       checkpointCount: cps.length,
-      totalTokenEstimate: cps.reduce((s, c) => s + (c.tokenEstimate ?? 0), 0),
+      totalTokenEstimate: sessionTok,
       lastCheckpointId: last?.checkpointId,
       lastSummary: last?.summary,
       injectedCount: injected,
       dedupHitRate: cps.length === 0 ? 0 : injected / cps.length,
       storageDedupRate: ds.attempts === 0 ? 0 : ds.deduped / ds.attempts,
+      tokensSaved: sessionSaved,
+      originalTokens: sessionOrig,
       dedupAttempts: ds.attempts,
       dedupCollapsed: ds.deduped,
     };
   }
+
+  /**
+   * Repo-wide stats — aggregates every session in this store (one per repo).
+   * Cumulative, resumable, cross-device. Surfaces the dashboard's "Repo …"
+   * figures; distinct from {@link stats} (per-session).
+   */
+  repoStats(): ReturnType<typeof repoStatsFromStore> {
+    return repoStatsFromStore(this.stateDir);
+  }
 }