@mnemom/mnemom 0.17.7 → 0.17.8

package/dist/lib/agent.js

@@ -452,32 +452,59 @@ export const CONTEXT_TAIL_BUDGET_KEY = "CONTEXT_RUNTIME_TAIL_BUDGET_TOKENS";
 export const CONTEXT_READ_CACHE_KEY = "CONTEXT_RUNTIME_READ_CACHE_TOKENS";
 export const CONTEXT_HEAD_RECLAIM_KEY = "CONTEXT_RUNTIME_HEAD_BREAKPOINT_RECLAIM";
 /**
- * The gateway key the `adaptive` context profile sets (allow-listed per session): turns on the
- * size-banded fold policy. Only the literal `banded` enables it; the band thresholds and budgets
- * stay at the gateway's own defaults.
+ * The gateway key that turns the size-banded fold policy on or off (allow-listed per session).
+ * Only the literal `banded` enables it; any other value — the profiles send `off` — disables it,
+ * and a session's value replaces the cell's own. The band thresholds and budgets stay at the
+ * gateway's own defaults.
  */
 export const CONTEXT_SIZE_POLICY_KEY = "CONTEXT_RUNTIME_SIZE_POLICY";
+/**
+ * The two gateway env keys the `compaction_intercept` setting turns on for a single session
+ * (payload-bound fix; both default OFF on the gateway, both read from the per-session overlay):
+ *   - `GATEWAY_USAGE_REAL_SIZE` — report the size of the body the client actually sent (the
+ *     REAL, unfolded context) in the last `usage.iterations` entry, so Claude Code's own
+ *     auto-compact threshold (its 1M default, or the user's `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` /
+ *     `CLAUDE_CODE_AUTO_COMPACT_WINDOW` / `autoCompactWindow`) fires as it would without the fold;
+ *   - `GATEWAY_COMPACTION_INTERCEPT` — answer the client's compaction request at once from the
+ *     gateway's own fold digest (no model call), so the compaction never blocks the user.
+ * Sent together, value `"on"`, when the `compaction_intercept` setting is on
+ * (`resolveCompactionIntercept`) OR when `--compact-at` arms a target below 1M (below) — a
+ * target cannot be honored without both. The `off` context profile sends both as `"off"`.
+ */
+export const USAGE_REAL_SIZE_KEY = "GATEWAY_USAGE_REAL_SIZE";
+export const COMPACTION_INTERCEPT_KEY = "GATEWAY_COMPACTION_INTERCEPT";
 /**
  * The named presets for how the gateway folds a session's context (`--context-profile`,
- * launcher.toml `context_profile`, `MNEMOM_AGENT_CONTEXT_PROFILE`):
- *   - `off`        → `CONTEXT_RUNTIME_ENABLED: "false"` — compaction is left to the coding agent
- *                    (the same bytes `--no-context` has always sent).
- *   - `balanced`   → NO fold keys: the gateway's own defaults stand. The default.
- *   - `aggressive` → a smaller tail budget + read cache and head-breakpoint reclaim on: folds
- *                    earlier and keeps a tighter working set.
+ * launcher.toml `context_profile`, `MNEMOM_AGENT_CONTEXT_PROFILE`). Choosing NONE sends no fold
+ * key at all and the cell's own default decides (see `resolveContextProfile`). A chosen profile
+ * is complete on its own, so a change to a cell's default can never change what it means:
+ *   - `off`        → `CONTEXT_RUNTIME_ENABLED: "false"` plus `GATEWAY_USAGE_REAL_SIZE: "off"` and
+ *                    `GATEWAY_COMPACTION_INTERCEPT: "off"` — compaction is left to the coding agent
+ *                    and never intercepted, even on a cell whose default turns the intercept on.
+ *                    The gateway already skips the intercept with the fold off, but the real-size
+ *                    usage rewrite is not gated on the fold, so `off` turns both off by name.
+ *   - `balanced`   → `CONTEXT_RUNTIME_SIZE_POLICY: "off"` — the cell's own fold budgets, never
+ *                    the size bands, even on a cell whose default is adaptive.
+ *   - `aggressive` → a smaller tail budget + read cache and head-breakpoint reclaim on, size
+ *                    policy off: folds earlier and keeps a tighter working set at every size.
  *   - `adaptive`   → `CONTEXT_RUNTIME_SIZE_POLICY: "banded"` — the gateway picks the fold by the
  *                    conversation's original size: no fold below 200k tokens, the aggressive
- *                    budgets from 200k to 1M, balanced above. Opt-in; never the default.
+ *                    budgets from 200k to 1M, balanced above.
  */
 export const CONTEXT_PROFILES = ["off", "balanced", "aggressive", "adaptive"];
 /** The per-session env overlay each profile expands to (key order is the wire order). */
 const CONTEXT_PROFILE_CONFIG = {
-    off: [[CONTEXT_RUNTIME_KEY, "false"]],
-    balanced: [],
+    off: [
+        [CONTEXT_RUNTIME_KEY, "false"],
+        [USAGE_REAL_SIZE_KEY, "off"],
+        [COMPACTION_INTERCEPT_KEY, "off"],
+    ],
+    balanced: [[CONTEXT_SIZE_POLICY_KEY, "off"]],
     aggressive: [
         [CONTEXT_TAIL_BUDGET_KEY, "60000"],
         [CONTEXT_READ_CACHE_KEY, "8000"],
         [CONTEXT_HEAD_RECLAIM_KEY, "true"],
+        [CONTEXT_SIZE_POLICY_KEY, "off"],
     ],
     adaptive: [[CONTEXT_SIZE_POLICY_KEY, "banded"]],
 };
@@ -490,21 +517,6 @@ const CONTEXT_PROFILE_CONFIG = {
  * header without the tool.
  */
 export const CONTEXT_HANDOFF_KEY = "CONTEXT_HANDOFF_ENABLED";
-/**
- * The two gateway env keys the `compaction_intercept` setting turns on for a single session
- * (payload-bound fix; both default OFF on the gateway, both read from the per-session overlay):
- *   - `GATEWAY_USAGE_REAL_SIZE` — report the size of the body the client actually sent (the
- *     REAL, unfolded context) in the last `usage.iterations` entry, so Claude Code's own
- *     auto-compact threshold (its 1M default, or the user's `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` /
- *     `CLAUDE_CODE_AUTO_COMPACT_WINDOW` / `autoCompactWindow`) fires as it would without the fold;
- *   - `GATEWAY_COMPACTION_INTERCEPT` — answer the client's compaction request at once from the
- *     gateway's own fold digest (no model call), so the compaction never blocks the user.
- * Sent together, value `"on"`, when the `compaction_intercept` setting is on
- * (`resolveCompactionIntercept`) OR when `--compact-at` arms a target below 1M (below) — a
- * target cannot be honored without both.
- */
-export const USAGE_REAL_SIZE_KEY = "GATEWAY_USAGE_REAL_SIZE";
-export const COMPACTION_INTERCEPT_KEY = "GATEWAY_COMPACTION_INTERCEPT";
 // ---------------------------------------------------------------------------
 // Compaction target (`--compact-at`, launcher.toml `compact_at`, MNEMOM_COMPACT_AT)
 // ---------------------------------------------------------------------------
@@ -651,6 +663,28 @@ export function assertCompactAtCompatible(opts) {
             "enable compaction-intercept`), or pass --compact-at off.");
     }
 }
+/**
+ * The `off` context profile turns the fold off, and the compaction intercept answers a compaction
+ * from that fold, so `off` sends the intercept and real-size keys as `"off"`. An explicit
+ * `--compaction-intercept` or `--compact-at <N>` in the same launch asks for the opposite —
+ * refuse rather than silently drop the flag. A standing intercept or target (environment or
+ * launcher.toml) is not refused: the session's `off` wins and `buildSessionConfig` leaves it out.
+ * `compactionIntercept` / `compactAt` here are the raw flag values (`undefined` when not passed).
+ */
+export function assertOffProfileCompatible(opts) {
+    if (opts.profile !== "off")
+        return;
+    const flag = opts.compactionIntercept === true
+        ? "--compaction-intercept"
+        : typeof opts.compactAt === "number"
+            ? "--compact-at"
+            : null;
+    if (flag === null)
+        return;
+    throw new Error(`mnemom agent: context profile off and ${flag} disagree — with the fold off the gateway has ` +
+        `no fold to answer a compaction from, so off sends the compaction intercept off. Drop ` +
+        `${flag}, or choose another --context-profile.`);
+}
 /**
  * `200000` → `"200k"`, anything not k-aligned → the bare digits. Every real caller only ever
  * passes a `parseCompactAt`-validated value, which is bounded to
@@ -910,17 +944,20 @@ export function parseContextProfile(raw, source) {
     throw new Error(`${source} must be one of ${CONTEXT_PROFILES.join(", ")} (got '${raw}').`);
 }
 /**
- * Which context profile this launch runs under. Precedence, highest wins:
+ * Which context profile this launch runs under, or `null` when none was chosen anywhere — then
+ * no fold key is sent and the cell's own default decides. Precedence, highest wins:
  *   1. `--no-context` — always `off`. Combined with an explicit `--context-profile
  *      balanced|aggressive|adaptive` it is a CONFLICT and the launch refuses (never a silent override);
  *      `--context-profile off` agrees with it.
  *   2. an explicit `--context-profile <profile>` flag (`--context` alongside it is fine — the
  *      profile wins);
- *   3. `MNEMOM_AGENT_CONTEXT_PROFILE` (which `applyConfigToEnv` sets from the `context_profile`
+ *   3. `resumed`: the profile the session this launch resumes ran under (from the session
+ *      ledger), so a resume keeps that session's own choice over the saved default;
+ *   4. `MNEMOM_AGENT_CONTEXT_PROFILE` (which `applyConfigToEnv` sets from the `context_profile`
  *      config key) — an invalid value is an error, never a silent default;
- *   4. the folding boolean when NO profile is set anywhere: `context = false` in launcher.toml
+ *   5. the folding boolean when NO profile is set anywhere: `context = false` in launcher.toml
  *      (→ `MNEMOM_AGENT_CONTEXT`, see `resolveContextFold`) means `off`;
- *   5. `balanced` (the default).
+ *   6. `null` — unset, the cell default.
  */
 export function resolveContextProfile(opts) {
     if (opts.context === false) {
@@ -931,34 +968,44 @@ export function resolveContextProfile(opts) {
     }
     if (opts.contextProfile !== undefined)
         return opts.contextProfile;
+    if (opts.resumed)
+        return opts.resumed;
     const raw = (opts.env?.MNEMOM_AGENT_CONTEXT_PROFILE ?? "").trim();
     if (raw !== "")
         return parseContextProfile(raw, "MNEMOM_AGENT_CONTEXT_PROFILE");
     if (!resolveContextFold({ context: opts.context, env: opts.env }))
         return "off";
-    return "balanced";
+    return null;
 }
 /**
  * The decoded per-session env overlay for this launch — the `config` object of the
  * `x-mnemom-session-config` payload, in wire order: the profile's keys first
- * (`CONTEXT_RUNTIME_ENABLED` for `off`; the three fold-tuning keys for `aggressive`;
- * `CONTEXT_RUNTIME_SIZE_POLICY` for `adaptive`; nothing for `balanced`), then `CONTEXT_HANDOFF_ENABLED: "true"` when context handoff is ON, then
+ * (`CONTEXT_RUNTIME_ENABLED: "false"` + real-size and intercept `"off"` for `off`; the three fold-tuning keys + size policy off for
+ * `aggressive`; size policy off for `balanced`; size policy banded for `adaptive`; nothing when
+ * no profile was chosen), then `CONTEXT_HANDOFF_ENABLED: "true"` when context handoff is ON, then
  * `GATEWAY_USAGE_REAL_SIZE: "on"` + `GATEWAY_COMPACTION_INTERCEPT: "on"` when EITHER the
  * `compaction_intercept` setting is ON OR `--compact-at` arms a target below 1M (the target
  * cannot be honored without the intercept), then `GATEWAY_COMPACTION_UPLOAD_TARGET_TOKENS: "<N>"`
- * when a target is set. Empty for `balanced` with everything off — the common case, where no
- * header is sent at all. Exported so `--dry-run` can list exactly what the header carries.
+ * when a target is set. The `off` profile wins over the intercept and the target: a session with
+ * no fold never has its compaction intercepted (`assertOffProfileCompatible` refuses the explicit
+ * flag pair; a standing intercept or target from the environment or launcher.toml is dropped).
+ * Empty with no profile chosen and everything off — the common case, where
+ * no header is sent at all. Exported so `--dry-run` can list exactly what the header carries.
  */
 export function buildSessionConfig(opts) {
     const config = {};
-    for (const [k, v] of CONTEXT_PROFILE_CONFIG[opts.profile])
-        config[k] = v;
+    if (opts.profile !== null) {
+        for (const [k, v] of CONTEXT_PROFILE_CONFIG[opts.profile])
+            config[k] = v;
+    }
     if (opts.contextHandoff)
         config[CONTEXT_HANDOFF_KEY] = "true";
     const hasCompactionTarget = opts.compactAt !== undefined && opts.compactAt !== null;
     // A target needs the compaction intercept + real-size rewrite to arm (#2216) — without them
     // the upload-target key is silently inert (compaction-align.ts: "armed only inside the
     // intercept"). Deliberately NOT GATEWAY_COMPACTION_REFOLD — a separate, costlier opt-in.
+    if (opts.profile === "off")
+        return config;
     if (opts.compactionIntercept || hasCompactionTarget) {
         config[USAGE_REAL_SIZE_KEY] = "on";
         config[COMPACTION_INTERCEPT_KEY] = "on";
@@ -984,11 +1031,12 @@ export function buildSessionConfigPayload(opts) {
 }
 /**
  * The `x-mnemom-session-config` value for this launch, or `undefined` when there is
- * nothing to override (the gateway's own defaults stand — `balanced` with everything else off,
- * byte-identical to a launch before profiles existed). Independent overlays:
+ * nothing to override (the cell's own defaults stand — no profile chosen with everything else
+ * off, byte-identical to a launch before profiles existed). Independent overlays:
  *   - the context profile (`buildSessionConfig`): `off` → `CONTEXT_RUNTIME_ENABLED: "false"`,
- *     `aggressive` → the three fold-tuning keys, `adaptive` → `CONTEXT_RUNTIME_SIZE_POLICY:
- *     "banded"`, `balanced` → nothing;
+ *     `aggressive` → the three fold-tuning keys + `CONTEXT_RUNTIME_SIZE_POLICY: "off"`,
+ *     `balanced` → `CONTEXT_RUNTIME_SIZE_POLICY: "off"`, `adaptive` →
+ *     `CONTEXT_RUNTIME_SIZE_POLICY: "banded"`, none chosen → nothing;
  *   - `compactionIntercept: true` → `GATEWAY_USAGE_REAL_SIZE` + `GATEWAY_COMPACTION_INTERCEPT`
  *     `"on"` (the `compaction_intercept` setting);
  *   - `compactAt: <N>` (`--compact-at`, below 1M) → the SAME two intercept keys plus

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)) {