pi-mega-compact 0.11.2 → 0.11.4

package/dist/extensions/mega-runtime/runtime-snapshot.js

@@ -18,8 +18,8 @@
  */
 import { join } from "node:path";
 import { vectorStats, vectorRepoStats, vectorDataInvariant, } from "../../src/vectorStore.js";
-import { latestModelSnapshot, recordPerfSample, recordSessionHeartbeat, appendTokenSample, } from "../../src/store/sqlite.js";
-import { resolveRepoRoot } from "../mega-config.js";
+import { latestModelSnapshot, readLatestCacheHitPct, recordPerfSample, recordSessionHeartbeat, appendTokenSample, } from "../../src/store/sqlite.js";
+import { resolveRepoRoot, } from "../mega-config.js";
 import { computeMegaSnapshot } from "./snapshot.js";
 import { buildDashboardSnapshot } from "./dashboard-snapshot.js";
 import { materialSigImpl, embedderNameImpl, driftStatusImpl, getTurnLevelImpl, } from "./runtime-helpers.js";
@@ -134,6 +134,16 @@ export function snapshotImpl(self, ctx) {
         }
         // ── gather widget data (computed per snapshot, rendered per frame) ────
         const modelSnap = latestModelSnapshot(self.currentStateDir);
+        // Provider prompt cache hit % for the widget (B/C): latest
+        // cache_hit_pct sample. Non-fatal — one extra sync open per
+        // material-change-gated recompute, acceptably cheap.
+        let providerCachePct = 0;
+        try {
+            providerCachePct = readLatestCacheHitPct(self.currentStateDir);
+        }
+        catch {
+            /* non-fatal */
+        }
         const _snapResult = computeMegaSnapshot({
             lastCtxTokens: self.lastCtxTokens,
             lastCtxWindow: self.lastCtxWindow,
@@ -165,6 +175,7 @@ export function snapshotImpl(self, ctx) {
             ready,
             armed,
             modelSnap,
+            providerCachePct,
         });
         self.widgetData = _snapResult.widgetData;
         // S33: consume the flare after copying it into widgetData so it fires
@@ -186,8 +197,7 @@ export function snapshotImpl(self, ctx) {
         // (effectBorderSgr returns '' once expired), so this is bookkeeping to
         // free the slot and prevent a stale effect lingering between snapshots.
         if (self.activeEffect &&
-            Date.now() - self.activeEffect.startedAt >=
-                self.activeEffect.durationMs) {
+            Date.now() - self.activeEffect.startedAt >= self.activeEffect.durationMs) {
             self.activeEffect = null;
         }
         // Auto-fit: register a factory so pi re-renders the panel at the REAL

package/dist/extensions/mega-runtime/runtime.js

@@ -63,6 +63,7 @@ export class MegaRuntime {
         lastErrorText: undefined,
         errorTextRepeatCount: 0,
         poisonedAdviseSent: false,
+        providerOutageAdvised: false,
         poisonedCompactSignatures: new Set(),
         poisonedCount: 0,
     };

package/dist/extensions/mega-runtime/snapshot.js

@@ -91,7 +91,7 @@ export function computeMegaSnapshot(p) {
     // ── S31: game-mode state ──────────────────────────────────────────────
     const gs = p.getCachedGameState();
     const curLevel = p.getTurnLevel();
-    const cachePct = st.dedupHitRate * 100;
+    const cachePct = p.providerCachePct;
     const widgetData = {
         version: ownVersion(),
         tierLabel,

package/dist/extensions/mega-runtime/snapshot.test.js

@@ -0,0 +1,127 @@
+/**
+ * snapshot.test.ts — C.4 computeMegaSnapshot tests for providerCachePct
+ * and megaCacheFlare fields.
+ *
+ * Uses MEGACOMPACT_STATE_DIR + mkdtemp (G7). No pi runtime.
+ */
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { mkdtempSync, rmSync } from "node:fs";
+import { computeMegaSnapshot } from "./snapshot.js";
+function baseInput(overrides = {}) {
+    return {
+        rtTokensSaved: 1000,
+        lastCtxPercent: null,
+        lastCtxTokens: 0,
+        lastCtxWindow: 0,
+        activeAgents: 0,
+        currentTurn: 0,
+        statusKey: undefined,
+        ready: false,
+        armed: false,
+        st: {
+            totalTokenEstimate: 800,
+            originalTokens: 1200,
+            storageDedupRate: 0.12,
+            checkpointCount: 3,
+            lastCheckpointId: undefined,
+            lastSummary: undefined,
+            injectedCount: 0,
+            dedupHitRate: 0.05,
+            tokensSaved: 200,
+            dedupAttempts: 40,
+            dedupCollapsed: 5,
+        },
+        repo: {
+            tokensSaved: 5000,
+            totalTokenEstimate: 4000,
+            checkpointCount: 9,
+            sessionCount: 2,
+            originalTokens: 6000,
+            dedupAttempts: 100,
+            dedupCollapsed: 30,
+            storageDedupRate: 0.3,
+        },
+        pressureBand: "low",
+        configTier: "default",
+        modelSnap: undefined,
+        lastCompactAt: null,
+        embedderName: () => "Trigram",
+        driftStatus: () => "ok",
+        getCachedGameState: () => ({
+            game_mode_on: false,
+            theme: "transparent",
+            tui_display_mode: "full",
+        }),
+        getTurnLevel: () => 1,
+        providerCachePct: 56.2,
+        megaCacheFlare: false,
+        megaCacheFlarePct: 0,
+        levelUpFlare: false,
+        achievementFlare: false,
+        achievementFlareTitles: [],
+        activeEffect: null,
+        lastActivityAt: Date.now(),
+        ticker: [],
+        lastWhy: undefined,
+        tierTrace: undefined,
+        pulsing: false,
+        ...overrides,
+    };
+}
+describe("computeMegaSnapshot (C.4)", () => {
+    let dir;
+    before(() => {
+        dir = mkdtempSync(join(tmpdir(), "mc-snap-"));
+        process.env.MEGACOMPACT_STATE_DIR = dir;
+    });
+    after(() => {
+        delete process.env.MEGACOMPACT_STATE_DIR;
+        rmSync(dir, { recursive: true, force: true });
+    });
+    // ── C.1: providerCachePct flows into cachePct ─────────────────────────
+    it("cachePct equals providerCachePct (not dedup hit rate)", () => {
+        const res = computeMegaSnapshot(baseInput({ providerCachePct: 56.2 }));
+        assert.equal(res.widgetData.cachePct, 56.2, "cachePct is providerCachePct");
+    });
+    it("cachePct is 0 when providerCachePct is 0", () => {
+        const res = computeMegaSnapshot(baseInput({ providerCachePct: 0 }));
+        assert.equal(res.widgetData.cachePct, 0, "cachePct is 0");
+    });
+    it("cachePct is independent of dedup hit rate", () => {
+        const res = computeMegaSnapshot(baseInput({
+            providerCachePct: 12.5,
+            st: {
+                totalTokenEstimate: 99999,
+                originalTokens: 99999,
+                storageDedupRate: 0.99,
+                checkpointCount: 1,
+                lastCheckpointId: undefined,
+                lastSummary: undefined,
+                injectedCount: 0,
+                dedupHitRate: 0.05,
+                tokensSaved: 200,
+                dedupAttempts: 40,
+                dedupCollapsed: 5,
+            },
+        }));
+        assert.equal(res.widgetData.cachePct, 12.5, "cachePct ignores dedup");
+    });
+    // ── megaCacheFlare fields pass through ────────────────────────────────
+    it("megaCacheFlare + megaCacheFlarePct pass through to widgetData", () => {
+        const res = computeMegaSnapshot(baseInput({ megaCacheFlare: true, megaCacheFlarePct: 287 }));
+        assert.equal(res.widgetData.megaCacheFlare, true);
+        assert.equal(res.widgetData.megaCacheFlarePct, 287);
+    });
+    it("megaCacheFlare is false by default", () => {
+        const res = computeMegaSnapshot(baseInput());
+        assert.equal(res.widgetData.megaCacheFlare, false);
+    });
+    // ── level pass-through ────────────────────────────────────────────────
+    it("level flows from getTurnLevel", () => {
+        const res = computeMegaSnapshot(baseInput({ getTurnLevel: () => 42 }));
+        assert.equal(res.curLevel, 42);
+    });
+});

package/dist/extensions/mega-runtime/widget.js

@@ -14,7 +14,7 @@
 // barrel (`extensions/mega-runtime.ts` does `export * from "./widget.js"`) and
 // every direct consumer keep resolving the same named exports.
 export { C, PULSE, DEFAULT_PANEL_BG, EFFECT_BASE, panelBgFor, themeAnsi, sgrReset, wrapLine, panelLine, panelBar, effectBorderSgr, effectBar, fmtTokens, ramp, sinceCompactStr, } from "./widget-ansi.js";
-import { C, PULSE, DEFAULT_PANEL_BG, panelBgFor, themeAnsi, sgrReset, wrapLine, panelLine, panelBar, effectBorderSgr, effectBar, fmtTokens, ramp, sinceCompactStr } from "./widget-ansi.js";
+import { C, PULSE, DEFAULT_PANEL_BG, panelBgFor, themeAnsi, sgrReset, wrapLine, panelLine, panelBar, effectBorderSgr, effectBar, fmtTokens, ramp, sinceCompactStr, } from "./widget-ansi.js";
 // ── buildWidgetLines ───────────────────────────────────────────────────────
 // Kept as a free function (not a MegaRuntime method) so runtime.ts stays
 // focused on state management. It reads the WidgetData snapshot + the live
@@ -44,12 +44,12 @@ export function buildWidgetLines(wd, width, activeAgents) {
     // width guard + theme bg apply identically to the full panel. Level is shown
     // only when game mode is on (otherwise just the cache %).
     if (wd.tuiMode === "minimal") {
-        const lvl = wd.gameMode ? wd.level ?? 1 : undefined;
+        const lvl = wd.gameMode ? (wd.level ?? 1) : undefined;
         const cachePct = wd.cachePct ?? 0;
         const cacheStr = `${Math.round(cachePct * 10) / 10}%`;
         const accent = themeAnsi(wd.theme, "accent");
         const mega = themeAnsi(wd.theme, "mega");
-        const megaFlare = wd.gameMode && wd.megaCacheFlare && cachePct >= 100
+        const megaFlare = wd.gameMode && wd.megaCacheFlare && (wd.megaCacheFlarePct ?? 0) >= 100
             ? ` ${mega}MEGA CACHE${sgrReset(mega)}`
             : "";
         const body = lvl != null
@@ -71,7 +71,7 @@ export function buildWidgetLines(wd, width, activeAgents) {
     const lvlPrefix = wd.gameMode
         ? `${themeAnsi(wd.theme, "accent")}${wd.gameMode && wd.levelUpFlare ? "\x1b[5m" : ""}LVL ${wd.level ?? 1}${wd.gameMode && wd.levelUpFlare ? "\x1b[0m" : ""}${sgrReset(themeAnsi(wd.theme, "accent"))} `
         : "";
-    const megaFlareSuffix = wd.gameMode && wd.megaCacheFlare && (wd.cachePct ?? 0) >= 100
+    const megaFlareSuffix = wd.gameMode && wd.megaCacheFlare && (wd.megaCacheFlarePct ?? 0) >= 100
         ? `${sep}${themeAnsi(wd.theme, "mega")}MEGA CACHE! (oops, you cached so hard the dedup caught fire)${sgrReset(themeAnsi(wd.theme, "mega"))}`
         : "";
     // Build one long content line — let terminal wrap it naturally

package/dist/extensions/mega-runtime/widget.test.js

@@ -94,6 +94,8 @@ describe("buildWidgetLines (S31)", () => {
                             level: 1,
                             cachePct,
                             megaCacheFlare: flare,
+                            // C.3: flare gate reads megaCacheFlarePct, not cachePct
+                            ...(flare ? { megaCacheFlarePct: cachePct } : {}),
                         });
                         const lines = buildWidgetLines(wd, WIDTH, 0);
                         const body = contentLines(lines);
@@ -138,11 +140,21 @@ describe("buildWidgetLines (S31)", () => {
 });
 describe("buildWidgetLines ambient border effect (v0.8.3)", () => {
     const effBase = (overrides = {}) => baseWd({
-        theme: DEFAULT_THEME, tuiMode: "full", gameMode: true, level: 1, cachePct: 42, ...overrides,
+        theme: DEFAULT_THEME,
+        tuiMode: "full",
+        gameMode: true,
+        level: 1,
+        cachePct: 42,
+        ...overrides,
     });
     const isBorder = (l) => l.includes("─");
     it("activeEffect (pulse, mid-window) -> border lines carry a 256-color fg SGR", () => {
-        const ae = { type: "pulse", role: "accent", startedAt: Date.now() - 250, durationMs: 2000 };
+        const ae = {
+            type: "pulse",
+            role: "accent",
+            startedAt: Date.now() - 250,
+            durationMs: 2000,
+        };
         const lines = buildWidgetLines(effBase({ activeEffect: ae }), WIDTH, 0);
         const borders = lines.filter(isBorder);
         assert.ok(borders.length >= 2, "has top + bottom borders");
@@ -158,7 +170,12 @@ describe("buildWidgetLines ambient border effect (v0.8.3)", () => {
         }
     });
     it("expired activeEffect -> plain borders (per-frame expiry enforced)", () => {
-        const ae = { type: "pulse", role: "accent", startedAt: Date.now() - 5000, durationMs: 1000 };
+        const ae = {
+            type: "pulse",
+            role: "accent",
+            startedAt: Date.now() - 5000,
+            durationMs: 1000,
+        };
         const lines = buildWidgetLines(effBase({ activeEffect: ae }), WIDTH, 0);
         const borders = lines.filter(isBorder);
         for (const b of borders) {
@@ -167,7 +184,12 @@ describe("buildWidgetLines ambient border effect (v0.8.3)", () => {
     });
     it("activeEffect border lines are width-safe (pulse, minimal + full)", () => {
         for (const tuiMode of ["minimal", "full"]) {
-            const ae = { type: "pulse", role: "mega", startedAt: Date.now() - 100, durationMs: 2000 };
+            const ae = {
+                type: "pulse",
+                role: "mega",
+                startedAt: Date.now() - 100,
+                durationMs: 2000,
+            };
             const lines = buildWidgetLines(effBase({ activeEffect: ae, tuiMode }), 60, 0);
             for (const l of lines)
                 assert.ok(visibleWidth(l) <= 60, `width safe (${tuiMode}): ${visibleWidth(l)}`);
@@ -175,12 +197,53 @@ describe("buildWidgetLines ambient border effect (v0.8.3)", () => {
     });
     it("flash effect mid-window border carries the full base index SGR", () => {
         // Force an 'on' phase of the 120ms alternate by starting just now.
-        const ae = { type: "flash", role: "red", startedAt: Date.now(), durationMs: 1200 };
+        const ae = {
+            type: "flash",
+            role: "red",
+            startedAt: Date.now(),
+            durationMs: 1200,
+        };
         const lines = buildWidgetLines(effBase({ activeEffect: ae }), WIDTH, 0);
         const borders = lines.filter(isBorder);
         assert.ok(borders.some((b) => b.includes("\x1b[38;5;203m")), `flash-on phase uses red base 203`);
     });
 });
+describe("buildWidgetLines C.3 flare gate regression", () => {
+    const flareBase = (overrides = {}) => baseWd({
+        theme: DEFAULT_THEME,
+        tuiMode: "full",
+        gameMode: true,
+        level: 1,
+        cachePct: 42,
+        ...overrides,
+    });
+    it("flare fires when megaCacheFlarePct >= 100 even when cachePct < 100", () => {
+        // Regression: the old code read (wd.cachePct ?? 0) >= 100, so when
+        // cachePct was 56 (provider hit rate) the flare silently broke.
+        const lines = buildWidgetLines(flareBase({
+            cachePct: 56,
+            megaCacheFlare: true,
+            megaCacheFlarePct: 287,
+        }), WIDTH, 0);
+        assert.ok(lines.join("\n").includes("MEGA CACHE"), "flare fires from megaCacheFlarePct");
+    });
+    it("flare suppressed when megaCacheFlarePct < 100 even when cachePct >= 100", () => {
+        // Symmetric regression: high cachePct should NOT alone trigger flare.
+        const lines = buildWidgetLines(flareBase({
+            cachePct: 150,
+            megaCacheFlare: true,
+            megaCacheFlarePct: 42,
+        }), WIDTH, 0);
+        assert.ok(!lines.join("\n").includes("MEGA CACHE"), "no flare when megaCacheFlarePct below threshold");
+    });
+    it("flare suppressed when megaCacheFlarePct is missing (undefined)", () => {
+        const lines = buildWidgetLines(flareBase({
+            cachePct: 150,
+            megaCacheFlare: true,
+        }), WIDTH, 0);
+        assert.ok(!lines.join("\n").includes("MEGA CACHE"), "no flare without megaCacheFlarePct");
+    });
+});
 describe("buildWidgetLines footer stability (P1 — no 250ms rotation)", () => {
     // P1: the L5 ticker branch used to re-pick the head text every 250ms via
     // `step = floor(Date.now()/250)`, flipping the footer line on a 250·N ms
@@ -188,7 +251,12 @@ describe("buildWidgetLines footer stability (P1 — no 250ms rotation)", () => {
     // the SAME WidgetData at t and t+500ms (well past one rotation slot) must
     // produce byte-identical footer lines. Proves the metronome is gone.
     const stabBase = (overrides = {}) => baseWd({
-        theme: DEFAULT_THEME, tuiMode: "full", gameMode: false, level: 1, cachePct: 42, ...overrides,
+        theme: DEFAULT_THEME,
+        tuiMode: "full",
+        gameMode: false,
+        level: 1,
+        cachePct: 42,
+        ...overrides,
     });
     it("ticker footer is byte-identical across simulated frames 500ms apart", () => {
         const wd = stabBase({
@@ -220,7 +288,12 @@ describe("buildWidgetLines footer stability (P1 — no 250ms rotation)", () => {
         try {
             Date.now = () => 1_000_000;
             const before = buildWidgetLines(stabBase({ ticker: [{ text: "a", at: 1 }] }), WIDTH, 0);
-            const after = buildWidgetLines(stabBase({ ticker: [{ text: "a", at: 1 }, { text: "b", at: 2 }] }), WIDTH, 0);
+            const after = buildWidgetLines(stabBase({
+                ticker: [
+                    { text: "a", at: 1 },
+                    { text: "b", at: 2 },
+                ],
+            }), WIDTH, 0);
             assert.notDeepEqual(before, after, "footer changes when ticker grows");
         }
         finally {
@@ -230,22 +303,40 @@ describe("buildWidgetLines footer stability (P1 — no 250ms rotation)", () => {
 });
 describe("buildWidgetLines achievement flare (S35)", () => {
     const achBase = (overrides = {}) => baseWd({
-        theme: DEFAULT_THEME, tuiMode: "full", gameMode: true, level: 1, cachePct: 42, ...overrides,
+        theme: DEFAULT_THEME,
+        tuiMode: "full",
+        gameMode: true,
+        level: 1,
+        cachePct: 42,
+        ...overrides,
     });
     it("achievementFlare + titles -> renders the unlock toast line", () => {
-        const lines = buildWidgetLines(achBase({ achievementFlare: true, achievementFlareTitles: ["First Compact"] }), WIDTH, 0);
+        const lines = buildWidgetLines(achBase({
+            achievementFlare: true,
+            achievementFlareTitles: ["First Compact"],
+        }), WIDTH, 0);
         assert.ok(lines.some((l) => l.includes("Achievement unlocked: First Compact")), "toast line present");
     });
     it("achievementFlare off -> no toast line", () => {
-        const lines = buildWidgetLines(achBase({ achievementFlare: false, achievementFlareTitles: ["First Compact"] }), WIDTH, 0);
+        const lines = buildWidgetLines(achBase({
+            achievementFlare: false,
+            achievementFlareTitles: ["First Compact"],
+        }), WIDTH, 0);
         assert.ok(!lines.some((l) => l.includes("Achievement unlocked")), "no toast when flare off");
     });
     it("gameMode off -> no toast even if flare set", () => {
-        const lines = buildWidgetLines(achBase({ gameMode: false, achievementFlare: true, achievementFlareTitles: ["X"] }), WIDTH, 0);
+        const lines = buildWidgetLines(achBase({
+            gameMode: false,
+            achievementFlare: true,
+            achievementFlareTitles: ["X"],
+        }), WIDTH, 0);
         assert.ok(!lines.some((l) => l.includes("Achievement unlocked")), "no toast when game off");
     });
     it("achievement toast is width-safe", () => {
-        const lines = buildWidgetLines(achBase({ achievementFlare: true, achievementFlareTitles: ["First Compact", "Turn Veteran"] }), 60, 0);
+        const lines = buildWidgetLines(achBase({
+            achievementFlare: true,
+            achievementFlareTitles: ["First Compact", "Turn Veteran"],
+        }), 60, 0);
         for (const l of lines)
             assert.ok(visibleWidth(l) <= 60, "width safe");
     });

package/dist/src/pricing.js

@@ -0,0 +1,78 @@
+/**
+ * pricing.ts — Reusable pricing constants and cache-savings computation.
+ *
+ * Single source of truth for provider prompt-cache pricing multipliers and
+ * known model input rates. Extracted from routes-cache.ts inline arithmetic.
+ *
+ * PREVENT-PI-004: compute-only, zero network. No SQL, no IO.
+ */
+// ─── Cache Pricing Multipliers ──────────────────────────────────────────────
+/**
+ * Fraction of input cost saved per cache-read token.
+ * Cache reads cost 10% of full input → you save 90% of the input cost.
+ */
+export const CACHE_READ_MULTIPLIER = 0.9;
+/**
+ * Fraction of input cost incurred as a premium per cache-write token.
+ * Cache writes cost 125% of full input → a 25% premium over a normal input token.
+ */
+export const CACHE_WRITE_MULTIPLIER = 0.25;
+// ─── Known Model Input Rates ─────────────────────────────────────────────────
+// USD per input token. Exact-match first, then prefix-match.
+export const MODEL_INPUT_RATES = {
+    "claude-sonnet-4": 3e-6, // $3/Mtok
+    "claude-3.5-sonnet": 3e-6,
+    "claude-3-opus": 15e-6,
+    "claude-3-haiku": 0.25e-6,
+    "claude-3.5-haiku": 0.8e-6,
+    "gpt-4o": 2.5e-6,
+    "gpt-4o-mini": 0.15e-6,
+    "gpt-4-turbo": 10e-6,
+    "gpt-3.5-turbo": 0.5e-6,
+    "gemini-2.5-pro": 1.25e-6,
+    "gemini-2.5-flash": 0.15e-6,
+    "gemini-2.0-flash": 0.1e-6,
+    "deepseek-chat": 0.14e-6,
+    "deepseek-reasoner": 0.55e-6,
+    "codestral": 0.3e-6,
+    "mistral-large": 2e-6,
+    "llama-3.1-405b": 1.33e-6,
+    "llama-3.1-70b": 0.8e-6,
+    "llama-3.1-8b": 0.05e-6,
+};
+/**
+ * Look up the input-token rate (USD) for a model string.
+ * Exact match first, then prefix match (e.g. "claude-sonnet-4-20250514" → 3e-6).
+ */
+export function lookupModelInputRate(model) {
+    // exact match first
+    if (MODEL_INPUT_RATES[model] != null)
+        return MODEL_INPUT_RATES[model];
+    // prefix match
+    for (const [key, rate] of Object.entries(MODEL_INPUT_RATES)) {
+        if (model.startsWith(key))
+            return rate;
+    }
+    return undefined;
+}
+/**
+ * Compute dollar savings from provider prompt cache read/write token counts.
+ *
+ * @param totalCacheRead — total cache-read tokens over the lifetime.
+ * @param totalCacheWrite — total cache-write tokens over the lifetime.
+ * @param inputRate — the model's input-token rate in USD (e.g. 3e-6 for Sonnet).
+ * @returns `{ cacheReadSaved, cacheWriteCost, netSaved }` — or all zeros when
+ *   `inputRate` is zero or negative.
+ */
+export function computeCacheSavings(totalCacheRead, totalCacheWrite, inputRate) {
+    if (inputRate <= 0) {
+        return { cacheReadSaved: 0, cacheWriteCost: 0, netSaved: 0 };
+    }
+    const cacheReadSaved = totalCacheRead * inputRate * CACHE_READ_MULTIPLIER;
+    const cacheWriteCost = totalCacheWrite * inputRate * CACHE_WRITE_MULTIPLIER;
+    return {
+        cacheReadSaved,
+        cacheWriteCost,
+        netSaved: cacheReadSaved - cacheWriteCost,
+    };
+}

package/dist/src/store/sqlite/perf-samples.js

@@ -79,3 +79,107 @@ export function readPerfSamples(stateDir = getStateDir(), sinceTs = 0, kind) {
     }
     return out;
 }
+/**
+ * Read lifetime provider prompt cache aggregates from `perf_samples`.
+ *
+ * Aggregates `cache_creation_input_tokens` / `cache_read_input_tokens` from
+ * the `meta` JSON column of `cache_hit_pct` samples (`json_extract`,
+ * available in node:sqlite ≥22.13 / SQLite ≥3.38). Returns a zeroed
+ * `ProviderCacheLifetime` when no samples exist (never undefined).
+ */
+export function readProviderCacheLifetime(stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const rows = db
+        .prepare(`SELECT ts, meta FROM perf_samples
+       WHERE kind = ?
+       ORDER BY ts ASC`)
+        .all("cache_hit_pct");
+    if (rows.length === 0) {
+        return {
+            sampleCount: 0,
+            avgHitPct: 0,
+            totalCacheRead: 0,
+            totalCacheWrite: 0,
+            totalInput: 0,
+            firstSampleAt: null,
+            latestSampleAt: null,
+        };
+    }
+    let totalCacheRead = 0;
+    let totalCacheWrite = 0;
+    let totalInput = 0;
+    let sumHitPct = 0;
+    let hitPctCount = 0;
+    for (const r of rows) {
+        if (r.meta != null) {
+            let meta = null;
+            try {
+                meta = JSON.parse(r.meta);
+            }
+            catch {
+                meta = null;
+            }
+            if (meta != null) {
+                const cr = typeof meta.cacheRead === "number"
+                    ? meta.cacheRead
+                    : typeof meta.cache_read === "number"
+                        ? meta.cache_read
+                        : 0;
+                const cw = typeof meta.cacheWrite === "number"
+                    ? meta.cacheWrite
+                    : typeof meta.cache_write === "number"
+                        ? meta.cache_write
+                        : 0;
+                const inp = typeof meta.input === "number" ? meta.input : 0;
+                totalCacheRead += cr;
+                totalCacheWrite += cw;
+                totalInput += inp;
+                // Compute hit pct for this sample (same formula as perf-handler.ts)
+                const denom = cr + inp + cw;
+                if (denom > 0) {
+                    sumHitPct += (cr / denom) * 100;
+                    hitPctCount++;
+                }
+            }
+        }
+    }
+    return {
+        sampleCount: rows.length,
+        avgHitPct: hitPctCount > 0 ? sumHitPct / hitPctCount : 0,
+        totalCacheRead,
+        totalCacheWrite,
+        totalInput,
+        firstSampleAt: new Date(rows[0].ts).toISOString(),
+        latestSampleAt: new Date(rows[rows.length - 1].ts).toISOString(),
+    };
+}
+/**
+ * Read the most recent `cache_hit_pct` value from `perf_samples`.
+ *
+ * Returns 0 when no samples exist (never NaN/undefined). When multiple
+ * rows share the same timestamp the tie is broken by highest id (most
+ * recently inserted).
+ */
+export function readLatestCacheHitPct(stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const row = db
+        .prepare(`SELECT value FROM perf_samples
+       WHERE kind = ?
+       ORDER BY ts DESC, id DESC
+       LIMIT 1`)
+        .get("cache_hit_pct");
+    if (!row || typeof row.value !== "number" || !Number.isFinite(row.value))
+        return 0;
+    return row.value;
+}
+/**
+ * Read provider cache lifetime aggregates for a specific repo by state directory.
+ *
+ * This is a convenience alias over `readProviderCacheLifetime(stateDir)` —
+ * both open the same underlying global store database. Accepts an explicit
+ * `stateDir` rather than relying on the implicit default, making it suitable
+ * for per-repo dashboard handlers.
+ */
+export function readProviderCacheForRepo(stateDir) {
+    return readProviderCacheLifetime(stateDir);
+}