pi-mega-compact 0.11.2 → 0.11.3

package/dist/extensions/mega-events/context-handler.js

@@ -170,30 +170,24 @@ export function registerContextHandler(pi, runtime, config) {
             runtime.diagCtxFastGate++;
             return;
         }
-        // Debounce so we don't fire on every context event past threshold.
-        const now = Date.now();
-        if (now < runtime.debounceUntil) {
-            runtime.diagCtxDebounce++;
-            return;
-        }
-        runtime.debounceUntil = now + 2000;
+        // D.2: Replay MUST be exempt from debounce — replay is free (no compute,
+        // no re-write) and prevents unnecessary KV-cache invalidation. Check
+        // replay FIRST, before debounce, so two context events <2s apart both
+        // return the cached sentinel verbatim (re-stabilises the provider prefix).
+        //
         // v0.8.6 cache-stability: replay the cached trim view when still in the
         // same compaction epoch AND context hasn't grown enough to warrant a
-        // re-compact. This stabilizes the provider KV-cache prefix (the summary +
-        // cut are reused verbatim) instead of regenerating a fresh summary +
-        // sentinel every fire, which invalidated the prefix on every other turn
-        // (the alternating cache-miss regression). Re-compact only when context
-        // grew >=10% of the window (percent basis) or >=50% of the effective
-        // threshold (token basis, when percent is unavailable). The cached `cut`
-        // is only valid while the transcript grows within the epoch — it is
-        // cleared on session_compact (durable truncation) + resetRuntime, so we
-        // never replay a stale cut into a truncated transcript (PREVENT-PI-001/002).
-        const RECOMPACT_PCT_DELTA = 10;
+        // re-compact. Re-compact only when context grew >=config.recompactPctDelta%
+        // of the window (percent basis) or >=50% of the effective threshold
+        // (token basis, when percent is unavailable). The cached `cut` is only
+        // valid while the transcript grows within the epoch — it is cleared on
+        // session_compact (durable truncation) + resetRuntime, so we never replay
+        // a stale cut into a truncated transcript (PREVENT-PI-001/002).
         if (runtime.trimCache &&
             runtime.trimCache.checkpointId === runtime.rt.lastCheckpointId &&
             runtime.trimCache.cut <= messages.length) {
             const grewEnough = pct != null && runtime.trimCache.ctxPct != null
-                ? pct - runtime.trimCache.ctxPct >= RECOMPACT_PCT_DELTA
+                ? pct - runtime.trimCache.ctxPct >= config.recompactPctDelta
                 : currentTokens - (runtime.trimCache.ctxTokens ?? 0) >=
                     runtime.effectiveThreshold * 0.5;
             if (!grewEnough) {
@@ -209,6 +203,14 @@ export function registerContextHandler(pi, runtime, config) {
             }
             // else: context grew enough → fall through to re-compact (cache is stale)
         }
+        // Debounce so we don't fire on every context event past threshold.
+        // (Replay already returned above — only fresh compacts reach this point.)
+        const now = Date.now();
+        if (now < runtime.debounceUntil) {
+            runtime.diagCtxDebounce++;
+            return;
+        }
+        runtime.debounceUntil = now + 2000;
         // Adaptive compression (Fix E): scale compression strength + keepFrom depth
         // with how close we are to the model context limit. Null-safe: when the
         // token-fallback path ran (pct unavailable) use the token-basis pressure
@@ -219,8 +221,22 @@ export function registerContextHandler(pi, runtime, config) {
         const ran = runCompact(pi, runtime, config, ctx, messages, {
             compressionPressure: pressure,
         });
+        // D.3: skip paths fall back to replay instead of returning empty.
+        // If runCompact skipped and we have a valid trimCache, replay it
+        // (free stability win) — otherwise defer to the next event.
         if (ran.skipped) {
             runtime.diagCtxRunSkipped++;
+            if (runtime.trimCache &&
+                runtime.trimCache.checkpointId === runtime.rt.lastCheckpointId &&
+                runtime.trimCache.cut <= messages.length) {
+                const recent = messages.slice(runtime.trimCache.cut); // guardrails-allow PREVENT-PI-002
+                runtime.diagLiveTrimFires++;
+                runtime.diagLiveTrimReplays++;
+                runtime.snapshot(ctx);
+                return {
+                    messages: [{ ...runtime.trimCache.summaryAgentMsg }, ...recent],
+                };
+            }
             return;
         }
         // S27 DB-mirror: write checkpoint_epoch with deterministic nonce.
@@ -277,7 +293,9 @@ export function registerContextHandler(pi, runtime, config) {
                     }
                 }
                 catch (wikiErr) {
-                    runtime.logger.warn("wiki_rebuild_failed", { error: String(wikiErr) });
+                    runtime.logger.warn("wiki_rebuild_failed", {
+                        error: String(wikiErr),
+                    });
                 }
                 // S27 Task 6: Fire-and-forget dedup pipeline.
                 // Deduplicates raw_transcript rows for the compacted range.

package/dist/extensions/mega-events/error-classifier.js

@@ -11,6 +11,25 @@
  * compact per signature). Conservative: when unsure between transient and
  * poisoned, choose transient (bounded by R1 dedup + R2 session cap).
  */
+/** R7: known-retryable transient markers — network/throughput failures that
+ *  retry can fix and /clear cannot. SINGLE SOURCE OF TRUTH: classifyError uses
+ *  this for its transient-marker stage, and the agent-handlers R3 repeat
+ *  upgrade guard uses it to keep these errors out of poisoned-context. Add new
+ *  transient phrasings HERE only.
+ *
+ *  Non-obvious alternatives:
+ *  - `time(?:d[\s-]?out|out)` covers "timeout", "timed out", "timed-out" —
+ *    "timed out" does NOT match /timeout/ (the 2026-07-30 incident phrasing).
+ *  - `etimedout` is Node's timeout errno lowercased — does NOT contain the
+ *    substring "timeout".
+ *  - `socket hang up` is Node's ECONNRESET *message*; the errno lives in
+ *    error.code, which extractErrorSignature never sees. */
+export const KNOWN_RETRYABLE_TRANSIENT_PATTERN = /max(imum)? output token|rate[\s.-]?limit|429|too many requests|overloaded|5\d\d|internal server|bad gateway|service unavailable|network|time(?:d[\s-]?out|out)|etimedout|econnreset|econnrefused|epipe|eai_again|socket hang up|premature close|other side closed|connection (lost|refused|reset|aborted?)|stream (interrupted|closed|ended|failed)|disconnected/;
+/** R7: true when the error text carries a known-retryable transient marker.
+ *  Defensively lowercases so callers can pass raw or normalized text. */
+export function isKnownRetryableTransient(text) {
+    return KNOWN_RETRYABLE_TRANSIENT_PATTERN.test(text.toLowerCase());
+}
 /** S38.2: classify a turn-end error/stop signal into a retry category.
  *
  * `length` is returned as null — S28 owns the max-output-token length stopReason
@@ -134,22 +153,14 @@ export function classifyError(message) {
     if (/too long|context window|maximum context length|context length exceeded|requires at least \d+ tokens|even after compaction|reduce the conversation|reduce your input/.test(s)) {
         return 'context-overflow';
     }
-    // --- transient (specific markers FIRST — these override poisoned signals) ---
-    // R3: network failures (timeout, ECONNRESET, 5xx, 429) MUST stay transient
-    // even when usage is 0 tokens, because they are retryable. The specific
-    // markers below return before any poisoned signal is evaluated.
-    if (/max(imum)? output token/.test(s))
-        return 'transient';
-    if (/rate[\s.-]?limit|429|too many requests/.test(s))
-        return 'transient';
-    if (/5\d\d|internal server|bad gateway|service unavailable/.test(s))
-        return 'transient';
-    // 'connection aborted' is a network failure (ECONNABORTED), NOT a user ESC
-    // (which is stopReason 'aborted', handled by the early-return above). Added
-    // so "Connection aborted by peer" stays transient under R3. ECONNRESET and
-    // common errno names are included so a bare 0-token 'ECONNRESET' turn is not
-    // misclassified as poisoned (R6: ECONNRESET → transient).
-    if (/network|timeout|econnreset|econnrefused|epipe|connection (lost|refused|reset|aborted)|stream (interrupted|closed|ended|failed)|disconnected/.test(s))
+    // --- transient (known-retryable markers FIRST — these override poisoned signals) ---
+    // R3: network/throughput failures (timeout, ECONNRESET, 5xx, 429) MUST stay
+    // transient even when usage is 0 tokens, because they are retryable and
+    // /clear cannot fix them. 'connection aborted' is a network failure
+    // (ECONNABORTED), NOT a user ESC (stopReason 'aborted', early-return above).
+    // The marker set is shared with the agent-handlers R3 repeat-upgrade guard
+    // (isKnownRetryableTransient) so the two never drift.
+    if (isKnownRetryableTransient(s))
         return 'transient';
     // --- poisoned-context (R3: ORDER AFTER specific transient markers, BEFORE
     // the generic 'error' transient fallthrough) ---

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/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,
+    };
+}