@mnemom/mnemom 0.17.8-next.0 → 0.17.8

package/dist/lib/first-run/backtest.d.ts

@@ -13,7 +13,8 @@
  * original context is at or above the aggressive profile's fold point (its 60k tail
  * budget); smaller requests never fold, so they save 0. A flat rate over-counts mid-size
  * contexts and under-counts large ones; in aggregate that evens out. Per-size rates come
- * back once there are enough measured pairs.
+ * back once there are enough measured pairs. The token saving uses the same rule on the
+ * prompt (operator 2026-10-02: one rule for dollars and tokens).
  */
 /** One billed request, deduped by message id. `t` is epoch seconds. */
 export interface Row {
@@ -50,12 +51,24 @@ export declare function parseUsageLine(line: Buffer, subagent: boolean): {
     id: string | null;
     row: Row;
 } | null;
+/** One Claude Code compaction (`type:"system", subtype:"compact_boundary"`). */
+export interface Compaction {
+    /** Epoch seconds. */
+    t: number;
+    /** compactMetadata.preTokens / postTokens (0 when absent). */
+    pre: number;
+    post: number;
+}
+/** One transcript line → its compaction record, or null. Reads only the metadata. */
+export declare function parseCompactLine(line: Buffer): Compaction | null;
 /**
  * Billed requests of one transcript, deduped by message id (last copy wins, first-seen
  * order). With `seen`, an id already billed in an earlier transcript (a resumed / forked
  * session copies messages) is skipped, so each request is billed once, to its origin.
+ * With `compactions`, the transcript's compaction records are appended to it in the same
+ * pass (no second read of the file).
  */
-export declare function loadTranscript(path: string, seen?: Set<string>): Row[];
+export declare function loadTranscript(path: string, seen?: Set<string>, compactions?: Compaction[]): Row[];
 /** S46 C2n vs stock, median paired total-bill saving (n = 13). */
 export declare const S46_MEDIAN_SAVING = 0.238;
 /** The aggressive profile's tail budget (cli/src/lib/agent.ts): below it nothing folds. */
@@ -73,11 +86,18 @@ export declare function ruleRate(x: number): {
 export interface Estimate {
     actual: number;
     saved: number;
+    /** Tokens used: prompt + output over every request. */
+    tokens: number;
+    /** The token saving: the same flat rule on the prompt, ruleRate(prompt) x prompt. */
+    savedTokens: number;
     /** Same as `saved` now that no rate is floored (kept for the audit record). */
     rawSaved: number;
     peak: number;
     requests: number;
     notes: Partial<Record<Exclude<RateNote, null>, number>>;
 }
-/** The one swap point: rows → list-price actual and the conservative saving. */
+/**
+ * The one swap point for a session that did NOT run through Mnemom: rows → list-price
+ * actual, the conservative dollar saving (the cost curve) and the token saving.
+ */
 export declare function estimate(rows: readonly Row[]): Estimate;

package/dist/lib/first-run/backtest.js

@@ -13,7 +13,8 @@
  * original context is at or above the aggressive profile's fold point (its 60k tail
  * budget); smaller requests never fold, so they save 0. A flat rate over-counts mid-size
  * contexts and under-counts large ones; in aggregate that evens out. Per-size rates come
- * back once there are enough measured pairs.
+ * back once there are enough measured pairs. The token saving uses the same rule on the
+ * prompt (operator 2026-10-02: one rule for dollars and tokens).
  */
 import { forEachLine, isoSeconds, parseJson } from "./lines.js";
 /**
@@ -109,16 +110,39 @@ export function parseUsageLine(line, subagent) {
         },
     };
 }
+const COMPACT = Buffer.from('"compact_boundary"');
+/** One transcript line → its compaction record, or null. Reads only the metadata. */
+export function parseCompactLine(line) {
+    if (line.indexOf(COMPACT) === -1)
+        return null;
+    const d = parseJson(line);
+    if (!d || d.type !== "system" || d.subtype !== "compact_boundary")
+        return null;
+    const t = isoSeconds(d.timestamp);
+    if (t === null)
+        return null;
+    const cm = d.compactMetadata ?? {};
+    return { t, pre: num(cm.preTokens), post: num(cm.postTokens) };
+}
 /**
  * Billed requests of one transcript, deduped by message id (last copy wins, first-seen
  * order). With `seen`, an id already billed in an earlier transcript (a resumed / forked
  * session copies messages) is skipped, so each request is billed once, to its origin.
+ * With `compactions`, the transcript's compaction records are appended to it in the same
+ * pass (no second read of the file).
  */
-export function loadTranscript(path, seen) {
+export function loadTranscript(path, seen, compactions) {
     const byId = new Map();
     const subagent = path.includes("/subagents/");
     let anon = 0;
     forEachLine(path, (line) => {
+        if (compactions) {
+            const c = parseCompactLine(line);
+            if (c) {
+                compactions.push(c);
+                return;
+            }
+        }
         const r = parseUsageLine(line, subagent);
         if (r)
             byId.set(r.id ?? `anon-${path}-${anon++}`, r.row);
@@ -148,11 +172,16 @@ export function ruleRate(x) {
     }
     return { strategy: "aggressive", raw: S46_MEDIAN_SAVING, screen: S46_MEDIAN_SAVING, note: null };
 }
-/** The one swap point: rows → list-price actual and the conservative saving. */
+/**
+ * The one swap point for a session that did NOT run through Mnemom: rows → list-price
+ * actual, the conservative dollar saving (the cost curve) and the token saving.
+ */
 export function estimate(rows) {
     let actual = 0;
     let saved = 0;
     let rawSaved = 0;
+    let tokens = 0;
+    let savedTokens = 0;
     let peak = 0;
     const notes = {};
     for (const r of rows) {
@@ -164,8 +193,10 @@ export function estimate(rows) {
         actual += c;
         saved += rate.screen * c;
         rawSaved += rate.raw * c;
+        tokens += x + r.out;
+        savedTokens += rate.screen * x;
         if (rate.note)
             notes[rate.note] = (notes[rate.note] ?? 0) + 1;
     }
-    return { actual, saved, rawSaved, peak, requests: rows.length, notes };
+    return { actual, saved, tokens, savedTokens, rawSaved, peak, requests: rows.length, notes };
 }

package/dist/lib/first-run/index.d.ts

@@ -3,21 +3,30 @@
  * backtest the user's last 30 days of Claude Code sessions on this machine and show what
  * Mnemom would have saved. `mnemom agent --first-run` shows it again at any time.
  *
- * Every session in the window is priced (operator 2026-10-02: "count all sessions"),
- * including ones that already ran through Mnemom: their transcripts hold the full,
- * unfolded context the client sent. Only copies of one session are dropped. The governed
- * classification is still run, for the audit counts only.
+ * Every session in the window is priced (operator 2026-10-02: "count all sessions"), in
+ * one of two buckets (throughEvidence):
+ *   THROUGH Mnemom   a launch-ledger signal, a window / env signal, or fold evidence on
+ *                    the main thread. Its transcript does NOT hold the unfolded context:
+ *                    through the gateway the top-level `usage` is the folded, billed size
+ *                    (`usage.iterations` matches it on every one of 365k rows measured),
+ *                    so the curve cannot be applied to it. Its saving is REALIZED: a
+ *                    replay of stock Claude Code at its default window (replay.ts).
+ *   NOT through      everything else, headless, Agent-SDK and marker-only sessions
+ *                    included: the POTENTIAL saving (backtest.estimate()).
+ * Only copies of one session are dropped.
  *
- * Privacy: READ-ONLY on ~/.claude and every transcript; no network call anywhere in this
- * module tree; only token counts, model ids, timestamps and Claude Code's own limit
- * records are read. Writes only the offer state file and a local audit (both 0600,
- * under ~/.mnemom).
+ * Privacy: READ-ONLY on ~/.claude and every transcript, one pass per file; no network
+ * call anywhere in this module tree; only token counts, model ids, timestamps, Claude
+ * Code's own limit records and its compaction metadata are read.
+ *
+ * Writes only the offer state file and a local audit (both 0600, under ~/.mnemom).
  *
  * State file (~/.mnemom/first-run.json): { offers, last_offer, last_answer, accepted_at?,
  * never? }. The offer is made while neither `accepted_at` nor `never` is set:
  * Enter / y shows the screen and records acceptance; n skips until the next launch;
  * never stops asking. A non-interactive launch is never asked and writes nothing.
  */
+import { type Compaction, type Row } from "./backtest.js";
 import { type ScopeResult, type Session } from "./scope.js";
 import { type Audit, type Variation } from "./screen.js";
 export declare const STATE_FILE = "first-run.json";
@@ -59,18 +68,30 @@ export interface FirstRunResult {
 export declare function computeFirstRun(opts?: ScanOptions): FirstRunResult;
 /**
  * The sessions the screen prices: every session in the window, one per session id (an
- * ungoverned copy first), none without a parent transcript.
+ * ungoverned copy first), none without a parent transcript, with its governed signals.
  */
 export declare function pricedSessions(scope: ScopeResult): Array<{
     s: Session;
-    viaMnemom: boolean;
+    signals: string[];
 }>;
+/** `mnemom agent` recorded the session in the launch ledger. */
+export declare const LEDGER_SIGNALS: Set<string>;
 /**
- * Proof a session ran through Mnemom: `mnemom agent` recorded it in the launch ledger.
- * Every other governed signal (an Agent-SDK host, a text marker, a time window) only
- * means it may have, so those sessions are not said to have been saved on.
+ * A launch / Remote Control window match, or a settings env pointing at the gateway.
+ * These put a session in the through bucket (operator sign-off 2026-10-02: "launch
+ * ledger, OR inside a Mnemom launch window, OR shows a fold"), but they never make a
+ * saving claim: the realized saving comes only from fold drops the replay detects
+ * (replayStock caps it at 0 without one), so a window- or env-only session with no
+ * fold adds its usage to "Through Mnemom" and nothing to "That saved".
  */
-export declare const LEDGER_SIGNALS: Set<string>;
+export declare const WINDOW_SIGNALS: Set<string>;
+/**
+ * Did the session run through Mnemom, and on what evidence? A ledger or window / env
+ * signal, else fold evidence on its main thread (replay.hasFoldEvidence). A headless,
+ * Agent-SDK or marker-only session without fold evidence is NOT through: those signals
+ * only mean it may have been.
+ */
+export declare function throughEvidence(signals: readonly string[], rows: readonly Row[], comps: readonly Compaction[]): "ledger" | "window" | "folds" | null;
 /** The screen's hard budget: a regression in buildScreen's line dropping must fail loudly. */
 export declare function assertScreenBudget(lines: readonly string[]): void;
 /** A transcript's mtime (ms), 0 when it vanished since discovery (it then sorts first). */

package/dist/lib/first-run/index.js

@@ -3,15 +3,23 @@
  * backtest the user's last 30 days of Claude Code sessions on this machine and show what
  * Mnemom would have saved. `mnemom agent --first-run` shows it again at any time.
  *
- * Every session in the window is priced (operator 2026-10-02: "count all sessions"),
- * including ones that already ran through Mnemom: their transcripts hold the full,
- * unfolded context the client sent. Only copies of one session are dropped. The governed
- * classification is still run, for the audit counts only.
+ * Every session in the window is priced (operator 2026-10-02: "count all sessions"), in
+ * one of two buckets (throughEvidence):
+ *   THROUGH Mnemom   a launch-ledger signal, a window / env signal, or fold evidence on
+ *                    the main thread. Its transcript does NOT hold the unfolded context:
+ *                    through the gateway the top-level `usage` is the folded, billed size
+ *                    (`usage.iterations` matches it on every one of 365k rows measured),
+ *                    so the curve cannot be applied to it. Its saving is REALIZED: a
+ *                    replay of stock Claude Code at its default window (replay.ts).
+ *   NOT through      everything else, headless, Agent-SDK and marker-only sessions
+ *                    included: the POTENTIAL saving (backtest.estimate()).
+ * Only copies of one session are dropped.
  *
- * Privacy: READ-ONLY on ~/.claude and every transcript; no network call anywhere in this
- * module tree; only token counts, model ids, timestamps and Claude Code's own limit
- * records are read. Writes only the offer state file and a local audit (both 0600,
- * under ~/.mnemom).
+ * Privacy: READ-ONLY on ~/.claude and every transcript, one pass per file; no network
+ * call anywhere in this module tree; only token counts, model ids, timestamps, Claude
+ * Code's own limit records and its compaction metadata are read.
+ *
+ * Writes only the offer state file and a local audit (both 0600, under ~/.mnemom).
  *
  * State file (~/.mnemom/first-run.json): { offers, last_offer, last_answer, accepted_at?,
  * never? }. The offer is made while neither `accepted_at` nor `never` is set:
@@ -21,7 +29,8 @@
 import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { estimate, loadTranscript, origContext, ruleRate } from "./backtest.js";
+import { estimate, loadTranscript, origContext, ruleRate, } from "./backtest.js";
+import { defaultWindow, dominantModel, hasFoldEvidence, replayStock } from "./replay.js";
 import { analyzeSeat } from "./seat.js";
 import { ORG_SEAT_TYPES, authShape, billingClass, buildScope, configDirOf, prettyProject, } from "./scope.js";
 import { DAYS, MAX_LINES, WIDTH, buildScreen, labelFor, } from "./screen.js";
@@ -117,17 +126,22 @@ export function computeFirstRun(opts = {}) {
     const seen = new Set();
     const shapes = new Map();
     const sessions = [];
-    const subSessions = [];
     // A Team / Enterprise subscriber: a subscription-billed session, or a Team / Enterprise
     // login in any kept session's config dir. Only these plans can run through Mnemom on
     // their subscription (lib/subscription-login.ts), so only they get the usage sentence.
-    let orgLogin = false;
+    let subscriber = false;
+    let extraUsage = false;
     const seatInputs = new Map();
-    ordered.forEach(({ s, viaMnemom }, i) => {
+    ordered.forEach(({ s, signals }, i) => {
         if (i % 25 === 0)
             opts.progress?.(`pricing sessions ${i + 1}/${ordered.length}`);
         const paths = [s.top, ...[...s.subs].sort()];
-        const rows = paths.flatMap((p) => loadTranscript(p, seen));
+        // Compactions are the main thread's: read from the top transcript only.
+        const comps = [];
+        const rows = [
+            ...loadTranscript(paths[0], seen, comps),
+            ...paths.slice(1).flatMap((p) => loadTranscript(p, seen)),
+        ];
         if (!rows.length) {
             counts.no_usage = (counts.no_usage ?? 0) + 1;
             return;
@@ -152,30 +166,44 @@ export function computeFirstRun(opts = {}) {
         const rowsIn = rows.filter((r) => r.t >= cut);
         if (!rowsIn.length)
             return;
-        // Every class is priced at API list prices; the screen says so.
+        const compsIn = comps.filter((c) => c.t >= cut);
+        // Every bucket is priced at API list prices; the screen says so.
         const e = estimate(rowsIn);
         const end = rowsIn.reduce((m, r) => Math.max(m, r.t), -Infinity);
-        const sc = {
+        const via = throughEvidence(signals, rowsIn, compsIn);
+        let saved = e.saved;
+        let savedTokens = e.savedTokens;
+        if (via) {
+            counts[`through_${via}`] = (counts[`through_${via}`] ?? 0) + 1;
+            const W = defaultWindow(dominantModel(rowsIn));
+            const rp = replayStock(rowsIn, compsIn, W);
+            counts[`through_window_${W}`] = (counts[`through_window_${W}`] ?? 0) + 1;
+            counts.stock_compactions = (counts.stock_compactions ?? 0) + rp.stockCompactions;
+            counts.actual_compactions = (counts.actual_compactions ?? 0) + rp.actualCompactions;
+            if (rp.savedUsd < 0)
+                counts.through_negative = (counts.through_negative ?? 0) + 1;
+            saved = rp.savedUsd;
+            savedTokens = rp.savedTokens;
+        }
+        else {
+            counts.not_through = (counts.not_through ?? 0) + 1;
+        }
+        sessions.push({
             label: labelFor(prettyProject(s.pdir)),
             end,
             actual: e.actual,
-            saved: e.saved,
-            viaMnemom,
-        };
-        sessions.push(sc);
-        if (cls === "subscription_org")
-            subSessions.push(sc);
-        orgLogin ||= subLogin;
+            tokens: e.tokens,
+            saved,
+            savedTokens,
+            through: via !== null,
+        });
+        if (cls === "subscription_org" || subLogin) {
+            subscriber = true;
+            extraUsage ||= shape.extraUsage === true;
+        }
     });
     const seat = [...seatInputs.values()].map((a) => analyzeSeat(a.ss, a.extra, now));
-    const use = subSessions.length ? subSessions : sessions;
-    const sub = subSessions.length || orgLogin
-        ? {
-            sessions: use.length,
-            actual: use.reduce((t, r) => t + r.actual, 0),
-            saved: use.reduce((t, r) => t + r.saved, 0),
-        }
-        : null;
+    const sub = subscriber ? { extraUsage } : null;
     const { lines, audit, variation } = buildScreen({ sessions, sub });
     assertScreenBudget(lines);
     audit.seat = {
@@ -187,7 +215,7 @@ export function computeFirstRun(opts = {}) {
 }
 /**
  * The sessions the screen prices: every session in the window, one per session id (an
- * ungoverned copy first), none without a parent transcript.
+ * ungoverned copy first), none without a parent transcript, with its governed signals.
  */
 export function pricedSessions(scope) {
     const out = new Map();
@@ -195,17 +223,34 @@ export function pricedSessions(scope) {
         const s = scope.sessions.get(key);
         if (!s.top || out.has(s.sid))
             continue;
-        const sigs = scope.excluded.get(key) ?? [];
-        out.set(s.sid, { s, viaMnemom: sigs.some((x) => LEDGER_SIGNALS.has(x)) });
+        out.set(s.sid, { s, signals: scope.excluded.get(key) ?? [] });
     }
     return [...out.values()];
 }
+/** `mnemom agent` recorded the session in the launch ledger. */
+export const LEDGER_SIGNALS = new Set(["registry_cc_id", "registry_conv_id"]);
 /**
- * Proof a session ran through Mnemom: `mnemom agent` recorded it in the launch ledger.
- * Every other governed signal (an Agent-SDK host, a text marker, a time window) only
- * means it may have, so those sessions are not said to have been saved on.
+ * A launch / Remote Control window match, or a settings env pointing at the gateway.
+ * These put a session in the through bucket (operator sign-off 2026-10-02: "launch
+ * ledger, OR inside a Mnemom launch window, OR shows a fold"), but they never make a
+ * saving claim: the realized saving comes only from fold drops the replay detects
+ * (replayStock caps it at 0 without one), so a window- or env-only session with no
+ * fold adds its usage to "Through Mnemom" and nothing to "That saved".
  */
-export const LEDGER_SIGNALS = new Set(["registry_cc_id", "registry_conv_id"]);
+export const WINDOW_SIGNALS = new Set(["registry_window", "rc_proxy_window", "settings_env"]);
+/**
+ * Did the session run through Mnemom, and on what evidence? A ledger or window / env
+ * signal, else fold evidence on its main thread (replay.hasFoldEvidence). A headless,
+ * Agent-SDK or marker-only session without fold evidence is NOT through: those signals
+ * only mean it may have been.
+ */
+export function throughEvidence(signals, rows, comps) {
+    if (signals.some((x) => LEDGER_SIGNALS.has(x)))
+        return "ledger";
+    if (signals.some((x) => WINDOW_SIGNALS.has(x)))
+        return "window";
+    return hasFoldEvidence(rows, comps) ? "folds" : null;
+}
 /** The screen's hard budget: a regression in buildScreen's line dropping must fail loudly. */
 export function assertScreenBudget(lines) {
     if (lines.length > MAX_LINES || lines.some((l) => l.length > WIDTH)) {

package/dist/lib/first-run/replay.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The realized saving of a session that ran through Mnemom: a replay of what stock Claude
+ * Code would have sent.
+ *
+ * Through the gateway, a transcript's top-level `usage` is the FOLDED, billed size (over
+ * 365k rows, `usage.iterations` matches the top-level fields, so no pre-fold size is ever
+ * recorded). So the client-side size is rebuilt from the fold drops themselves, and stock
+ * Claude Code is replayed on it at its DEFAULT window for the session's model, compacting
+ * whenever it would have. The saving is what stock would have billed minus what was
+ * billed. It can be negative for a session, and is kept negative.
+ *
+ * Pure: rows and compaction records in, numbers out. No I/O.
+ */
+import { type Compaction, type Row } from "./backtest.js";
+/** Main-thread requests with a smaller prompt are side calls (title, summary): ignored. */
+export declare const SIDE_CALL_BELOW = 10000;
+/** A fold: prompt(a) - prompt(b) > this … */
+export declare const FOLD_MIN_DROP = 20000;
+/** … and prompt(b) < this x prompt(a), with no Claude Code compaction in between. */
+export declare const FOLD_MAX_RATIO = 0.7;
+/** Median post-compaction size over 1,460 observed Claude Code compactions. */
+export declare const POST_COMPACT = 17181;
+/** Output tokens of a stock compaction's summary call. */
+export declare const SUMMARY_OUT = 6000;
+export declare const WINDOW_200K = 200000;
+export declare const WINDOW_1M = 1000000;
+/**
+ * Models whose Claude Code default context window is 1M (read out of Claude Code
+ * 2.1.285's binary). Everything else, unknown models included, is 200k. The user's own
+ * autoCompactWindow is deliberately NOT read: the baseline is stock Claude Code.
+ */
+export declare const ONE_M_DEFAULT: RegExp;
+/** Claude Code's default window for a model id (a trailing `[...]` is stripped). */
+export declare function defaultWindow(model: string): number;
+/** The most frequent main-thread model (all rows when none is main); first seen wins a tie. */
+export declare function dominantModel(rows: readonly Row[]): string;
+/** The main-thread requests the replay walks: prompt >= 10k, in timestamp order. */
+export declare function replayRows(rows: readonly Row[]): Row[];
+/** A Claude Code compaction with a timestamp in [ta, tb]. */
+export declare function compactedBetween(ct: readonly number[], ta: number, tb: number): boolean;
+/** The size drop from a to b looks like a fold (the compaction check is separate). */
+export declare function isFoldDrop(a: number, b: number): boolean;
+/** Fold evidence: two consecutive main-thread requests with a fold drop and no compaction. */
+export declare function hasFoldEvidence(rows: readonly Row[], comps: readonly Compaction[]): boolean;
+export interface Replay {
+    /** The baseline window. */
+    window: number;
+    /** Σ (stock size - billed prompt) over the replayed requests. */
+    tokenDiff: number;
+    /** The same, priced at each request's cache-read rate. */
+    usdDiff: number;
+    stockCompactions: number;
+    stockCompactionUsd: number;
+    /** Claude Code compactions recorded in the session. */
+    actualCompactions: number;
+    /** Fold drops the replay found along the main thread. */
+    folds: number;
+    savedTokens: number;
+    savedUsd: number;
+}
+/**
+ * Replay stock Claude Code at window W along the session's main thread.
+ *
+ *   client = billed prompt + what the folds removed so far (reset by a real compaction;
+ *            growth during a fold request counts as 0, the conservative direction)
+ *   stock  = min(client, W) at the first request and after a reset; otherwise it grows
+ *            with client and compacts above W: count it, charge (W x cache read + 6000 x
+ *            output + 17181 x cache write 5m) at the request's model price, and continue
+ *            from 17181 + the overshoot
+ *   saved  = Σ (stock - billed) at cache read + stock compaction cost - the session's own
+ *            compactions x the mean simulated compaction cost (0 if none was simulated)
+ *
+ * The last term is deliberately CONSERVATIVE (operator 2026-10-02). At a real compaction
+ * the replay resets both worlds to the same size, so that compaction's cost is paid on
+ * both sides and cancels. Subtracting it then charges each real compaction against
+ * Mnemom a second time, at the mean simulated stock cost, which is 0 when the replay
+ * simulated none. It can only lower the saving, never raise it, and with more real
+ * compactions than simulated ones it can take the saving below 0.
+ *
+ * A REALIZED saving comes only from detected folds. With none, savedTokens and savedUsd
+ * are capped at 0: a session put through Mnemom by a ledger, window or env signal alone
+ * can never add a saving (it adds its usage to the through bucket and 0 to "That saved"),
+ * but a replay that comes out NEGATIVE (billed above stock's window) still counts against
+ * it, so the cap only ever lowers the bucket total. tokenDiff / usdDiff keep the raw values.
+ */
+export declare function replayStock(rows: readonly Row[], comps: readonly Compaction[], W: number): Replay;

package/dist/lib/first-run/replay.js

@@ -0,0 +1,162 @@
+/**
+ * The realized saving of a session that ran through Mnemom: a replay of what stock Claude
+ * Code would have sent.
+ *
+ * Through the gateway, a transcript's top-level `usage` is the FOLDED, billed size (over
+ * 365k rows, `usage.iterations` matches the top-level fields, so no pre-fold size is ever
+ * recorded). So the client-side size is rebuilt from the fold drops themselves, and stock
+ * Claude Code is replayed on it at its DEFAULT window for the session's model, compacting
+ * whenever it would have. The saving is what stock would have billed minus what was
+ * billed. It can be negative for a session, and is kept negative.
+ *
+ * Pure: rows and compaction records in, numbers out. No I/O.
+ */
+import { origContext, price } from "./backtest.js";
+/** Main-thread requests with a smaller prompt are side calls (title, summary): ignored. */
+export const SIDE_CALL_BELOW = 10_000;
+/** A fold: prompt(a) - prompt(b) > this … */
+export const FOLD_MIN_DROP = 20_000;
+/** … and prompt(b) < this x prompt(a), with no Claude Code compaction in between. */
+export const FOLD_MAX_RATIO = 0.7;
+/** Median post-compaction size over 1,460 observed Claude Code compactions. */
+export const POST_COMPACT = 17_181;
+/** Output tokens of a stock compaction's summary call. */
+export const SUMMARY_OUT = 6_000;
+export const WINDOW_200K = 200_000;
+export const WINDOW_1M = 1_000_000;
+/**
+ * Models whose Claude Code default context window is 1M (read out of Claude Code
+ * 2.1.285's binary). Everything else, unknown models included, is 200k. The user's own
+ * autoCompactWindow is deliberately NOT read: the baseline is stock Claude Code.
+ */
+export const ONE_M_DEFAULT = /^claude-(fable-5|opus-4-[6-9]|opus-[5-9]|sonnet-4-[6-9]|sonnet-[5-9])/;
+/** Claude Code's default window for a model id (a trailing `[...]` is stripped). */
+export function defaultWindow(model) {
+    return ONE_M_DEFAULT.test(model.replace(/\[[^\]]*\]$/, "")) ? WINDOW_1M : WINDOW_200K;
+}
+const isMain = (r) => r.mainThread && !r.subagent;
+/** The most frequent main-thread model (all rows when none is main); first seen wins a tie. */
+export function dominantModel(rows) {
+    const main = rows.filter(isMain);
+    const counts = new Map();
+    let best = "";
+    let bestN = 0;
+    for (const r of main.length ? main : rows) {
+        const n = (counts.get(r.model) ?? 0) + 1;
+        counts.set(r.model, n);
+        if (n > bestN) {
+            best = r.model;
+            bestN = n;
+        }
+    }
+    return best;
+}
+/** The main-thread requests the replay walks: prompt >= 10k, in timestamp order. */
+export function replayRows(rows) {
+    return rows
+        .filter((r) => isMain(r) && origContext(r) >= SIDE_CALL_BELOW)
+        .sort((a, b) => a.t - b.t);
+}
+/** A Claude Code compaction with a timestamp in [ta, tb]. */
+export function compactedBetween(ct, ta, tb) {
+    return ct.some((t) => t >= ta && t <= tb);
+}
+/** The size drop from a to b looks like a fold (the compaction check is separate). */
+export function isFoldDrop(a, b) {
+    return a - b > FOLD_MIN_DROP && b < FOLD_MAX_RATIO * a;
+}
+/** Fold evidence: two consecutive main-thread requests with a fold drop and no compaction. */
+export function hasFoldEvidence(rows, comps) {
+    const m = replayRows(rows);
+    const ct = comps.map((c) => c.t);
+    for (let i = 1; i < m.length; i++) {
+        const a = m[i - 1];
+        const b = m[i];
+        if (isFoldDrop(origContext(a), origContext(b)) && !compactedBetween(ct, a.t, b.t))
+            return true;
+    }
+    return false;
+}
+/**
+ * Replay stock Claude Code at window W along the session's main thread.
+ *
+ *   client = billed prompt + what the folds removed so far (reset by a real compaction;
+ *            growth during a fold request counts as 0, the conservative direction)
+ *   stock  = min(client, W) at the first request and after a reset; otherwise it grows
+ *            with client and compacts above W: count it, charge (W x cache read + 6000 x
+ *            output + 17181 x cache write 5m) at the request's model price, and continue
+ *            from 17181 + the overshoot
+ *   saved  = Σ (stock - billed) at cache read + stock compaction cost - the session's own
+ *            compactions x the mean simulated compaction cost (0 if none was simulated)
+ *
+ * The last term is deliberately CONSERVATIVE (operator 2026-10-02). At a real compaction
+ * the replay resets both worlds to the same size, so that compaction's cost is paid on
+ * both sides and cancels. Subtracting it then charges each real compaction against
+ * Mnemom a second time, at the mean simulated stock cost, which is 0 when the replay
+ * simulated none. It can only lower the saving, never raise it, and with more real
+ * compactions than simulated ones it can take the saving below 0.
+ *
+ * A REALIZED saving comes only from detected folds. With none, savedTokens and savedUsd
+ * are capped at 0: a session put through Mnemom by a ledger, window or env signal alone
+ * can never add a saving (it adds its usage to the through bucket and 0 to "That saved"),
+ * but a replay that comes out NEGATIVE (billed above stock's window) still counts against
+ * it, so the cap only ever lowers the bucket total. tokenDiff / usdDiff keep the raw values.
+ */
+export function replayStock(rows, comps, W) {
+    const m = replayRows(rows);
+    const ct = comps.map((c) => c.t);
+    let removed = 0;
+    let prev = null;
+    let clientPrev = 0;
+    let st = 0;
+    let tokenDiff = 0;
+    let usdDiff = 0;
+    let n = 0;
+    let ccost = 0;
+    let folds = 0;
+    for (const r of m) {
+        const p = origContext(r);
+        const [, po, pr, w5] = price(r.model);
+        let reset = prev === null;
+        if (prev !== null) {
+            if (compactedBetween(ct, prev.t, r.t)) {
+                removed = 0;
+                reset = true;
+            }
+            else if (isFoldDrop(origContext(prev), p)) {
+                removed += origContext(prev) - p;
+                folds++;
+            }
+        }
+        const client = p + removed;
+        if (reset) {
+            st = Math.min(client, W);
+        }
+        else {
+            st += Math.max(client - clientPrev, 0);
+            while (st > W) {
+                n++;
+                ccost += (W * pr + SUMMARY_OUT * po + POST_COMPACT * w5) / 1e6;
+                st = POST_COMPACT + (st - W);
+            }
+        }
+        tokenDiff += st - p;
+        usdDiff += ((st - p) * pr) / 1e6;
+        prev = r;
+        clientPrev = client;
+    }
+    // Conservative: see the doc comment. Never raises savedUsd (each >= 0).
+    const each = n ? ccost / n : 0;
+    const usd = usdDiff + ccost - comps.length * each;
+    return {
+        window: W,
+        tokenDiff,
+        usdDiff,
+        stockCompactions: n,
+        stockCompactionUsd: ccost,
+        actualCompactions: comps.length,
+        folds,
+        savedTokens: folds ? tokenDiff : Math.min(tokenDiff, 0),
+        savedUsd: folds ? usd : Math.min(usd, 0),
+    };
+}

package/dist/lib/first-run/screen.d.ts

@@ -1,34 +1,52 @@
 /**
  * The first-run screen: one plain terminal screen (at most 22 lines of at most 78
- * columns, ASCII) built from the backtest numbers. Pure — no I/O — so every layout is
+ * columns, ASCII; with the command's blank line above and below, 24 rows) built from
+ * the backtest numbers. Pure — no I/O — so every layout is
  * unit-tested. Every number on it is recorded in the audit with its raw value and
  * method.
  *
- * Exactly three variations (operator v1, 2026-10-01); every number has one source and no
- * two lines make the same claim:
- *   A  saving   the shown saving is >= $5 and >= 5%: the usage at API prices, with Mnemom,
- *               the saving, the biggest session; plus ONE subscription sentence for a Team /
- *               Enterprise subscriber whose usage cut rounds to >= 5%. Where sessions ran
- *               through Mnemom (launch ledger), that part is said to be SAVED: what it
- *               saved you, and what it would have saved on the rest (operator 2026-10-02).
- *   B  small    >= $5 of usage at API prices but a smaller saving: the usage, the honest
- *               "wouldn't have changed that much" line, and the forward line.
- *   C  none     too little history: the forward line only.
- * All three end with the price line and the live lines.
+ * Sessions come in two buckets (index.ts): THROUGH Mnemom (launch ledger, a window / env
+ * signal, or fold evidence), whose saving is REALIZED (replay.ts: stock Claude Code
+ * replayed at its default window, can be negative), and NOT through Mnemom, whose saving
+ * is the POTENTIAL one (backtest.ts: the flat S46 rule, 23.8% of every request at or
+ * above 60k, for dollars and for tokens alike). Tokens and dollars are both shown
+ * (operator 2026-10-02). Percentages drop their decimals (rounded DOWN).
  *
- * Operator rulings (2026-09-30 / 2026-10-01), binding:
- *   - Cost only. Nothing about conduct ("habits", "caught", "checked").
- *   - Round DOWN, never overstate; frame the number around the biggest session.
- *   - Every kept session is priced at API list prices whatever it was billed on, and the
- *     screen says "at API prices". A subscriber gets a usage %, never a seat bill, an
- *     overage dollar figure or a limit-hit count.
+ * Variations; every number has one source and no two lines make the same claim:
+ *   A        no through-Mnemom usage, and the potential saving qualifies: the usage in
+ *            tokens and at API prices, the cut with Mnemom, the biggest session.
+ *   mixed    both buckets have usage: one block per bucket, each with its saving line
+ *            only if that BUCKET's saving qualifies, then the largest dollar saving
+ *            across the shown buckets, worded by its bucket ("biggest saving ... of"
+ *            through, "biggest session ... less with Mnemom" not through).
+ *   through  only through-Mnemom usage: its block alone, then its biggest saving.
+ *   B        >= $5 of usage but no saving line qualifies: the usage, the honest "wouldn't
+ *            have changed that much" line (no through usage) or the bucket usage lines,
+ *            and the forward line.
+ *   C        too little history: the forward line only.
+ * A saving qualifies iff it rounds DOWN to >= $5 and its token percent to >= 5%. A
+ * Team / Enterprise subscriber also gets the subscription line whenever a saving line is
+ * shown; its overage clause only when the account has extra usage enabled. All end with
+ * the price line and the live lines.
+ *
+ * Layout (operator 2026-10-02): a blank line between every block (each bucket's usage
+ * and saving lines, the biggest line, the subscriber lines, the price line, the live
+ * lines); the saving lines are not indented.
+ *
+ * Operator rulings (2026-09-30 .. 2026-10-02), binding:
+ *   - Cost and usage only. Nothing about conduct ("habits", "caught", "checked").
+ *   - Round DOWN, never overstate. A through session's saving may be negative: the
+ *     bucket total is the honest sum, never floored per session.
+ *   - Every session is priced at API list prices whatever it was billed on, and the
+ *     screen says "at API prices". A subscriber never gets a seat bill, an overage dollar
+ *     figure or a limit-hit count.
  *   - No live counter is promised: `mnemom agent` has no status bar today.
  */
 export declare const WIDTH = 78;
 export declare const MAX_LINES = 22;
 /** Less history than this (API prices, in the window) is too little to backtest. */
 export declare const MIN_HISTORY_USD = 5;
-/** Variation A iff the shown saving is at least this many dollars and this many percent. */
+/** A saving line is shown iff its saving rounds to at least this many dollars and percent. */
 export declare const STRONG_MIN_USD = 5;
 export declare const STRONG_MIN_PCT = 5;
 export declare const DAYS = 30;
@@ -42,6 +60,14 @@ export declare const FORWARD_LINE = "Long sessions are where Mnemom saves the mo
 /** Prices, promotions and plan allocations move; the saving is in usage (operator 2026-10-01). */
 export declare const PRICE_LINE = "Prices and plan limits change. Mnemom cuts what you use, so you stay ahead.";
 /** What `mnemom agent` does today: routes through the gateway, records, keeps context lean. */
+/**
+ * The subscriber lines, fixed like the live lines: the operator's break, so the overage
+ * form reads as two lines and never as one 78-column line.
+ */
+export declare const SUB_LINES: {
+    limit: string[];
+    overage: string[];
+};
 export declare const LIVE_LINES: string[];
 /** 2 significant figures, rounded DOWN; 0 below $1. */
 export declare function sig2(x: number): number;
@@ -56,31 +82,41 @@ export declare function pair(total: number, saved: number): [number, number, num
 export declare function pctDown(part: number, whole: number): number;
 export declare function day(t: number): string;
 export declare function usd(n: number): string;
+/** A token count rounded DOWN to 2 significant figures (the number it stands for). */
+export declare function tokShown(n: number): number;
+/**
+ * A token count in words, 2 significant figures DOWN: "9.0 billion", "39 billion",
+ * "450 million", "12 thousand"; below a thousand, the plain number.
+ */
+export declare function tokens(n: number): string;
 export declare function clean(s: string): string;
 /** A short, safe project label from Claude Code's encoded project dir, or null. */
 export declare function labelFor(pretty: string): string | null;
 export declare function wrap(text: string, width?: number): string[];
-/** One kept session's requests in the window, priced at API list prices. */
+/** One session's requests in the window, priced at API list prices. */
 export interface SessionCost {
     label: string | null;
     end: number;
+    /** What it used, at API prices (through Mnemom: the folded, billed size). */
     actual: number;
+    /** Tokens it used: prompt + output. */
+    tokens: number;
+    /** Through: the realized saving vs stock Claude Code (may be negative). Not: potential. */
     saved: number;
-    /** The launch ledger proves it ran through Mnemom: its saving is said to be SAVED. */
-    viaMnemom?: boolean;
+    savedTokens: number;
+    /** It ran through Mnemom (index.ts throughEvidence). */
+    through: boolean;
 }
-/** A Team / Enterprise subscriber's usage, at API prices (local evidence only). */
-export interface SubUsage {
-    /** Subscription-billed sessions in the window (all sessions when none is tagged). */
-    sessions: number;
-    actual: number;
-    saved: number;
+/** A Team / Enterprise subscriber (local evidence only). */
+export interface SubInfo {
+    /** The account has extra usage (overage) enabled: `hasExtraUsageEnabled`. */
+    extraUsage: boolean;
 }
 export interface ScreenInput {
-    /** Every kept session with requests in the window. */
+    /** Every session with requests in the window. */
     sessions: SessionCost[];
     /** null: not a Team / Enterprise subscriber. */
-    sub: SubUsage | null;
+    sub: SubInfo | null;
 }
 export interface AuditEntry {
     shown: unknown;
@@ -88,7 +124,7 @@ export interface AuditEntry {
     method: string;
 }
 export type Audit = Record<string, AuditEntry>;
-export type Variation = "A" | "B" | "C";
+export type Variation = "A" | "mixed" | "through" | "B" | "C";
 /** -> the screen lines, the variation and the audit of every number on them. */
 export declare function buildScreen(inp: ScreenInput): {
     lines: string[];

package/dist/lib/first-run/screen.js

@@ -1,27 +1,45 @@
 /**
  * The first-run screen: one plain terminal screen (at most 22 lines of at most 78
- * columns, ASCII) built from the backtest numbers. Pure — no I/O — so every layout is
+ * columns, ASCII; with the command's blank line above and below, 24 rows) built from
+ * the backtest numbers. Pure — no I/O — so every layout is
  * unit-tested. Every number on it is recorded in the audit with its raw value and
  * method.
  *
- * Exactly three variations (operator v1, 2026-10-01); every number has one source and no
- * two lines make the same claim:
- *   A  saving   the shown saving is >= $5 and >= 5%: the usage at API prices, with Mnemom,
- *               the saving, the biggest session; plus ONE subscription sentence for a Team /
- *               Enterprise subscriber whose usage cut rounds to >= 5%. Where sessions ran
- *               through Mnemom (launch ledger), that part is said to be SAVED: what it
- *               saved you, and what it would have saved on the rest (operator 2026-10-02).
- *   B  small    >= $5 of usage at API prices but a smaller saving: the usage, the honest
- *               "wouldn't have changed that much" line, and the forward line.
- *   C  none     too little history: the forward line only.
- * All three end with the price line and the live lines.
+ * Sessions come in two buckets (index.ts): THROUGH Mnemom (launch ledger, a window / env
+ * signal, or fold evidence), whose saving is REALIZED (replay.ts: stock Claude Code
+ * replayed at its default window, can be negative), and NOT through Mnemom, whose saving
+ * is the POTENTIAL one (backtest.ts: the flat S46 rule, 23.8% of every request at or
+ * above 60k, for dollars and for tokens alike). Tokens and dollars are both shown
+ * (operator 2026-10-02). Percentages drop their decimals (rounded DOWN).
  *
- * Operator rulings (2026-09-30 / 2026-10-01), binding:
- *   - Cost only. Nothing about conduct ("habits", "caught", "checked").
- *   - Round DOWN, never overstate; frame the number around the biggest session.
- *   - Every kept session is priced at API list prices whatever it was billed on, and the
- *     screen says "at API prices". A subscriber gets a usage %, never a seat bill, an
- *     overage dollar figure or a limit-hit count.
+ * Variations; every number has one source and no two lines make the same claim:
+ *   A        no through-Mnemom usage, and the potential saving qualifies: the usage in
+ *            tokens and at API prices, the cut with Mnemom, the biggest session.
+ *   mixed    both buckets have usage: one block per bucket, each with its saving line
+ *            only if that BUCKET's saving qualifies, then the largest dollar saving
+ *            across the shown buckets, worded by its bucket ("biggest saving ... of"
+ *            through, "biggest session ... less with Mnemom" not through).
+ *   through  only through-Mnemom usage: its block alone, then its biggest saving.
+ *   B        >= $5 of usage but no saving line qualifies: the usage, the honest "wouldn't
+ *            have changed that much" line (no through usage) or the bucket usage lines,
+ *            and the forward line.
+ *   C        too little history: the forward line only.
+ * A saving qualifies iff it rounds DOWN to >= $5 and its token percent to >= 5%. A
+ * Team / Enterprise subscriber also gets the subscription line whenever a saving line is
+ * shown; its overage clause only when the account has extra usage enabled. All end with
+ * the price line and the live lines.
+ *
+ * Layout (operator 2026-10-02): a blank line between every block (each bucket's usage
+ * and saving lines, the biggest line, the subscriber lines, the price line, the live
+ * lines); the saving lines are not indented.
+ *
+ * Operator rulings (2026-09-30 .. 2026-10-02), binding:
+ *   - Cost and usage only. Nothing about conduct ("habits", "caught", "checked").
+ *   - Round DOWN, never overstate. A through session's saving may be negative: the
+ *     bucket total is the honest sum, never floored per session.
+ *   - Every session is priced at API list prices whatever it was billed on, and the
+ *     screen says "at API prices". A subscriber never gets a seat bill, an overage dollar
+ *     figure or a limit-hit count.
  *   - No live counter is promised: `mnemom agent` has no status bar today.
  */
 import { ESTIMATOR_METHOD } from "./backtest.js";
@@ -29,7 +47,7 @@ export const WIDTH = 78;
 export const MAX_LINES = 22;
 /** Less history than this (API prices, in the window) is too little to backtest. */
 export const MIN_HISTORY_USD = 5;
-/** Variation A iff the shown saving is at least this many dollars and this many percent. */
+/** A saving line is shown iff its saving rounds to at least this many dollars and percent. */
 export const STRONG_MIN_USD = 5;
 export const STRONG_MIN_PCT = 5;
 export const DAYS = 30;
@@ -45,6 +63,17 @@ const FORWARD_SOURCE = "operator 2026-10-02: S46 C2n total bill -20.9% [-25.6, -
 /** Prices, promotions and plan allocations move; the saving is in usage (operator 2026-10-01). */
 export const PRICE_LINE = "Prices and plan limits change. Mnemom cuts what you use, so you stay ahead.";
 /** What `mnemom agent` does today: routes through the gateway, records, keeps context lean. */
+/**
+ * The subscriber lines, fixed like the live lines: the operator's break, so the overage
+ * form reads as two lines and never as one 78-column line.
+ */
+export const SUB_LINES = {
+    limit: ["On your subscription, fewer tokens means more work before you hit a limit."],
+    overage: [
+        "On your subscription, fewer tokens means more work before you hit a",
+        "limit, and less overage when you go past it.",
+    ],
+};
 export const LIVE_LINES = [
     "From now on it's live: your sessions run through Mnemom, which keeps long",
     "conversations lean and puts each tool call your agent makes on the record.",
@@ -87,6 +116,26 @@ export function day(t) {
 export function usd(n) {
     return `$${Math.floor(n).toLocaleString("en-US")}`;
 }
+/** A token count rounded DOWN to 2 significant figures (the number it stands for). */
+export function tokShown(n) {
+    return n >= 1 ? sig2(n) : 0;
+}
+/**
+ * A token count in words, 2 significant figures DOWN: "9.0 billion", "39 billion",
+ * "450 million", "12 thousand"; below a thousand, the plain number.
+ */
+export function tokens(n) {
+    const v = tokShown(n);
+    for (const [u, w] of [
+        [1e9, "billion"],
+        [1e6, "million"],
+        [1e3, "thousand"],
+    ]) {
+        if (v >= u)
+            return `${v >= 10 * u ? String(v / u) : (v / u).toFixed(1)} ${w}`;
+    }
+    return String(v);
+}
 // ── output hygiene ───────────────────────────────────────────────────────────
 const SECRETS = /(sk-[A-Za-z0-9_-]{6,}|ghp_[A-Za-z0-9]{6,}|mnm_[A-Za-z0-9_-]{6,}|op:\/\/\S+|Bearer\s+\S+|\b[0-9a-f]{40,}\b|\b[A-Za-z0-9+/]{48,}={0,2})/g;
 const PATHISH = /(\/Users\/\S+|\/home\/\S+|\/private\/\S+|~\/\S+)/g;
@@ -119,27 +168,45 @@ export function wrap(text, width = WIDTH) {
         out.push(cur);
     return out;
 }
-const SPENT_METHOD = "transcript usage x Claude Code 2.1.285's price table, deduped by message id, every kept " +
-    "session's requests in the last 30 days, priced at API list prices whatever they were billed " +
-    "on; 3 sig figs DOWN; a lower bound (side calls not in transcripts are missing)";
+const SPENT_METHOD = "transcript usage x Claude Code 2.1.285's price table, deduped by message id, the bucket's " +
+    "requests in the last 30 days, priced at API list prices whatever they were billed on; 3 sig " +
+    "figs DOWN; a lower bound (side calls not in transcripts are missing)";
+const TOKENS_METHOD = "Σ (input + cache read + cache write 5m + cache write 1h + output) over the same requests; " +
+    "2 sig figs DOWN";
 const SAVED_METHOD = `backtest.estimate(): ${ESTIMATOR_METHOD}; 2 sig figs DOWN`;
+const SAVED_TOKENS_METHOD = "backtest.estimate(): ruleRate(prompt) x prompt per request (the same flat rule as the " +
+    "dollars); 2 sig figs DOWN";
+const REALIZED_METHOD = "replay.replayStock(): stock Claude Code at its default window for the session's dominant " +
+    "main-thread model, replayed on the client size rebuilt from the fold drops; Σ per session, " +
+    "negative sessions kept; 2 sig figs DOWN";
+function sum(ses) {
+    const b = { n: ses.length, usd: 0, tokens: 0, saved: 0, savedTokens: 0 };
+    for (const r of ses) {
+        b.usd += r.actual;
+        b.tokens += r.tokens;
+        b.saved += r.saved;
+        b.savedTokens += r.savedTokens;
+    }
+    return b;
+}
+/** The shown saving of a bucket, or null when it does not qualify. */
+function qualifying(saved, savedTokens, base) {
+    const u = sig2(Math.max(saved, 0));
+    const pct = pctDown(savedTokens, base);
+    if (u < STRONG_MIN_USD || pct < STRONG_MIN_PCT)
+        return null;
+    // pct >= 5 implies base > 0.
+    return { usd: u, tok: tokShown(savedTokens), pct, rawPct: (100 * savedTokens) / base };
+}
 function subLines(sub, A) {
     if (!sub)
         return [];
-    const p = pctDown(sub.saved, sub.actual);
-    const raw = sub.actual > 0 ? (100 * sub.saved) / sub.actual : 0;
-    if (p < 5) {
-        A("sub_line_omitted", { shown: true, raw, method: "usage cut below 5% (decimals dropped)" });
-        return [];
-    }
-    A("sub_usage_pct", {
-        shown: p,
-        raw,
-        method: "saving / API-price cost over the subscription sessions in the window (all sessions if " +
-            "none is tagged); cost-weighted, decimals dropped",
+    A("sub_overage_clause", {
+        shown: sub.extraUsage,
+        raw: sub.extraUsage,
+        method: "the account's hasExtraUsageEnabled (authShape().extraUsage); never a dollar figure",
     });
-    return wrap(`On your subscription that is about ${p}% less usage: fewer limit hits, and less ` +
-        "overage if you use extra usage.");
+    return sub.extraUsage ? SUB_LINES.overage : SUB_LINES.limit;
 }
 /** -> the screen lines, the variation and the audit of every number on them. */
 export function buildScreen(inp) {
@@ -148,88 +215,176 @@ export function buildScreen(inp) {
         audit[k] = e;
     };
     const ses = inp.sessions;
-    const actual = ses.reduce((t, r) => t + r.actual, 0);
-    const saved = ses.reduce((t, r) => t + r.saved, 0);
-    const [a, s, e] = pair(actual, saved);
-    const p = pctDown(saved, actual);
-    const enough = actual >= MIN_HISTORY_USD;
-    const variation = enough && s >= STRONG_MIN_USD && p >= STRONG_MIN_PCT ? "A" : enough ? "B" : "C";
-    A("variation", { shown: variation, raw: { actual, saved }, method: "see screen.ts header" });
+    const all = sum(ses);
+    const thr = sum(ses.filter((r) => r.through));
+    const not = sum(ses.filter((r) => !r.through));
+    // A bucket "has usage" when it shows at least $1 at API prices.
+    const hasThr = sig3(thr.usd) >= 1;
+    const hasNot = sig3(not.usd) >= 1;
+    const enough = all.usd >= MIN_HISTORY_USD;
+    // Through: the base is the without-Mnemom total (used + saved). Not: what was used.
+    const qThr = hasThr ? qualifying(thr.saved, thr.savedTokens, thr.tokens + thr.savedTokens) : null;
+    const qNot = hasNot ? qualifying(not.saved, not.savedTokens, not.tokens) : null;
+    const variation = !enough
+        ? "C"
+        : !qThr && !qNot
+            ? "B"
+            : !hasThr
+                ? "A"
+                : hasNot
+                    ? "mixed"
+                    : "through";
+    A("variation", {
+        shown: variation,
+        raw: { through: thr, not_through: not },
+        method: "see screen.ts header; raw = each bucket's honest sums (negative sessions kept)",
+    });
     const L = ["Welcome to Mnemom.", ""];
     L.push(...(variation === "C"
         ? wrap("We didn't find enough Claude Code history on this machine to look at.")
         : wrap(`We looked at your last ${DAYS} days of Claude Code. It all stayed on this machine.`)));
-    L.push("");
-    if (variation === "A") {
-        A("spent_usd", { shown: a, raw: actual, method: SPENT_METHOD });
-        A("saved_pct", {
-            shown: p,
-            raw: (100 * saved) / actual,
-            method: "decimals dropped (rounded DOWN)",
-        });
-        const viaRaw = ses.reduce((t, r) => t + (r.viaMnemom ? r.saved : 0), 0);
-        const via = sig2(viaRaw);
-        const rest = sig2(saved - viaRaw);
-        if (via < 1) {
-            A("saved_usd", { shown: s, raw: saved, method: SAVED_METHOD });
-            A("with_mnemom_usd", { shown: e, raw: actual - saved, method: "spent shown - saved shown" });
-            L.push(...wrap(`At API prices that usage cost about ${usd(a)}. With Mnemom: about ${usd(e)}.`));
+    /** Start a block: one blank line after whatever came before. */
+    const gap = () => {
+        if (L[L.length - 1] !== "")
             L.push("");
-            L.push(...wrap(`That's about ${usd(s)} less (${p}%), and you don't change how you work.`));
+    };
+    const usage = (key, b) => {
+        A(`${key}_tokens`, { shown: tokShown(b.tokens), raw: b.tokens, method: TOKENS_METHOD });
+        A(`${key}_usd`, { shown: sig3(b.usd), raw: b.usd, method: SPENT_METHOD });
+        return { t: tokens(b.tokens), u: usd(sig3(b.usd)) };
+    };
+    const saving = (key, b, q, method, tokMethod, base) => {
+        A(`${key}_saved_tokens`, { shown: q.tok, raw: b.savedTokens, method: tokMethod });
+        A(`${key}_saved_pct`, {
+            shown: q.pct,
+            raw: q.rawPct,
+            method: `${base}; decimals dropped (rounded DOWN)`,
+        });
+        A(`${key}_saved_usd`, { shown: q.usd, raw: b.saved, method });
+    };
+    /** The per-bucket lines; only called when the through bucket has usage. */
+    const bucketBlock = () => {
+        gap();
+        const { t, u } = usage("through", thr);
+        L.push(...wrap(`Through Mnemom: ${t} tokens, about ${u} at API prices.`));
+        if (qThr) {
+            saving("through", thr, qThr, REALIZED_METHOD, REALIZED_METHOD, "saved tokens / (used + saved)");
+            L.push(...wrap(`That saved about ${tokens(thr.savedTokens)} tokens (${qThr.pct}%), about ${usd(qThr.usd)}.`));
         }
         else {
-            const m = `${SAVED_METHOD}; sessions the launch ledger shows ran through Mnemom`;
-            A("saved_via_mnemom_usd", { shown: via, raw: viaRaw, method: m });
-            L.push(...wrap(`At API prices that usage comes to about ${usd(a)} without Mnemom.`));
-            L.push("");
-            if (rest < 1) {
-                L.push(...wrap(`Mnemom saved you about ${usd(via)} of it (${p}%), and you didn't change how you work.`));
+            A("through_saved_not_shown", {
+                shown: null,
+                raw: { usd: thr.saved, tokens: thr.savedTokens },
+                method: `below $${STRONG_MIN_USD} or ${STRONG_MIN_PCT}% after rounding DOWN`,
+            });
+        }
+        if (hasNot) {
+            gap();
+            const { t, u } = usage("not_through", not);
+            L.push(...wrap(`Not through Mnemom: ${t} tokens, about ${u} at API prices.`));
+            if (qNot) {
+                saving("not_through", not, qNot, SAVED_METHOD, SAVED_TOKENS_METHOD, "saved tokens / used");
+                L.push(...wrap(`Mnemom would have cut about ${tokens(not.savedTokens)} tokens (${qNot.pct}%), ` +
+                    `about ${usd(qNot.usd)}.`));
             }
             else {
-                A("saved_rest_usd", {
-                    shown: rest,
-                    raw: saved - viaRaw,
-                    method: `${SAVED_METHOD}; the rest`,
+                A("not_through_saved_not_shown", {
+                    shown: null,
+                    raw: { usd: not.saved, tokens: not.savedTokens },
+                    method: `below $${STRONG_MIN_USD} or ${STRONG_MIN_PCT}% after rounding DOWN`,
                 });
-                L.push(...wrap(`Mnemom saved you about ${usd(via)} of it, and would have saved about ${usd(rest)} ` +
-                    "more on the sessions that didn't run through it."));
             }
         }
-        // A has a saving, so the session with the largest saving exists and saved something.
-        const big = ses.reduce((m, r) => (r.saved > m.saved ? r : m));
-        const [ba, , be] = pair(big.actual, big.saved);
-        A("biggest_session_usd", {
-            shown: ba,
-            raw: big.actual,
-            method: "the session with the largest saving; its API-price cost, 3 sig figs DOWN",
-        });
-        A("biggest_session_with_mnemom_usd", {
-            shown: be,
-            raw: big.actual - big.saved,
-            method: "its cost shown - its saving (2 sig figs DOWN)",
-        });
-        L.push("");
-        const where = big.label ? `${big.label} on ${day(big.end)}` : `on ${day(big.end)}`;
-        L.push(...wrap(big.viaMnemom
-            ? `Your biggest session, ${where}: ${usd(ba)} without Mnemom, about ${usd(be)} with it.`
-            : `Your biggest session, ${where}: ${usd(ba)}, with Mnemom about ${usd(be)}.`));
-        const subL = subLines(inp.sub, A);
-        if (subL.length)
-            L.push("", ...subL);
+    };
+    /** The session with the largest dollar saving, if it rounds to >= $5. */
+    const biggest = (pool) => {
+        let big = null;
+        for (const r of pool)
+            if (!big || r.saved > big.saved)
+                big = r;
+        return big && sig2(big.saved) >= STRONG_MIN_USD ? big : null;
+    };
+    const where = (r) => r.label ? `${r.label} on ${day(r.end)}` : `on ${day(r.end)}`;
+    /**
+     * The biggest line, worded by the session's bucket (operator 2026-10-02): through, the
+     * realized saving of what it would have cost without Mnemom (used + saved); not
+     * through, what it cost and the would-have saving.
+     */
+    const biggestLine = (big) => {
+        gap();
+        if (big.through) {
+            const without = big.actual + big.saved;
+            const ba = sig3(without);
+            const bs = Math.min(sig2(big.saved), ba);
+            A("biggest_saving_usd", {
+                shown: bs,
+                raw: big.saved,
+                method: `the session with the largest dollar saving (${REALIZED_METHOD})`,
+            });
+            A("biggest_saving_of_usd", {
+                shown: ba,
+                raw: without,
+                method: "that session's cost without Mnemom at API prices (used + saved), 3 sig figs DOWN",
+            });
+            L.push(...wrap(`Your biggest saving, ${where(big)}: about ${usd(bs)} of ${usd(ba)}.`));
+        }
+        else {
+            const ba = sig3(big.actual);
+            const bs = Math.min(sig2(big.saved), ba);
+            A("biggest_session_usd", {
+                shown: ba,
+                raw: big.actual,
+                method: "the session with the largest saving; its API-price cost, 3 sig figs DOWN",
+            });
+            A("biggest_session_saved_usd", {
+                shown: bs,
+                raw: big.saved,
+                method: `${SAVED_METHOD}; that session`,
+            });
+            L.push(...wrap(`Your biggest session, ${where(big)}: ${usd(ba)}, about ${usd(bs)} less with Mnemom.`));
+        }
+    };
+    if (variation === "A") {
+        gap();
+        const { t, u } = usage("spent", not);
+        L.push(...wrap(`You used about ${t} tokens, about ${u} at API prices.`));
+        const q = qNot;
+        saving("spent", not, q, SAVED_METHOD, SAVED_TOKENS_METHOD, "saved tokens / used");
+        L.push(...wrap(`With Mnemom: about ${tokens(not.savedTokens)} fewer tokens (${q.pct}%), about ` +
+            `${usd(q.usd)} less.`));
+        const big = biggest(ses.filter((r) => !r.through));
+        if (big)
+            biggestLine(big);
+        gap();
+        L.push(...subLines(inp.sub, A));
+    }
+    else if (variation === "mixed" || variation === "through") {
+        bucketBlock();
+        // The largest dollar saving across the buckets whose saving line is shown.
+        const big = biggest(ses.filter((r) => (r.through ? qThr : qNot)));
+        if (big)
+            biggestLine(big);
+        gap();
+        L.push(...subLines(inp.sub, A));
     }
     else {
         if (variation === "B") {
-            A("spent_usd", { shown: a, raw: actual, method: SPENT_METHOD });
-            A("saved_usd_not_shown", {
-                shown: null,
-                raw: saved,
-                method: `below $${STRONG_MIN_USD} or ${STRONG_MIN_PCT}% after rounding DOWN`,
-            });
-            L.push(...wrap(`Your sessions used about ${usd(a)} at API prices. They stayed small, so Mnemom ` +
-                "wouldn't have changed that much."));
+            if (hasThr) {
+                bucketBlock();
+            }
+            else {
+                const { t, u } = usage("spent", all);
+                A("saved_not_shown", {
+                    shown: null,
+                    raw: { usd: all.saved, tokens: all.savedTokens },
+                    method: `below $${STRONG_MIN_USD} or ${STRONG_MIN_PCT}% after rounding DOWN`,
+                });
+                gap();
+                L.push(...wrap(`Your sessions used about ${t} tokens, about ${u} at API prices. They stayed ` +
+                    "small, so Mnemom wouldn't have changed that much."));
+            }
         }
-        if (variation === "B")
-            L.push("");
+        gap();
         L.push(...wrap(FORWARD_LINE));
         A("forward_range_pct", {
             shown: "15 to 25",
@@ -237,11 +392,12 @@ export function buildScreen(inp) {
             method: FORWARD_SOURCE,
         });
     }
-    L.push("", PRICE_LINE, "", ...LIVE_LINES);
+    gap();
+    L.push(PRICE_LINE, "", ...LIVE_LINES);
     A("sessions", {
         shown: null,
-        raw: ses.length,
-        method: "kept sessions with requests in the window",
+        raw: { all: all.n, through: thr.n, not_through: not.n },
+        method: "sessions with requests in the window, by bucket",
     });
     return { lines: L.map(clean), audit, variation };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemom/mnemom",
-  "version": "0.17.8-next.0",
+  "version": "0.17.8",
   "description": "Transparent AI agent tracing",
   "type": "module",
   "bin": {