@mnemom/mnemom 0.17.7 → 0.17.8

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/dist/lib/launcher-config.d.ts

@@ -56,10 +56,11 @@ export interface LauncherConfig {
      */
     compactionIntercept?: boolean;
     /**
-     * How the gateway folds each session's context (`balanced` when unset): `off` leaves
-     * compaction to the coding agent, `balanced` keeps more earlier work verbatim, `aggressive`
-     * folds earlier with a tighter working set, `adaptive` sizes the fold to the conversation
-     * (none below 200k tokens, aggressive up to 1M, balanced above). `--context-profile` overrides it per launch.
+     * How the gateway folds each session's context (unset: nothing is sent, the gateway cell's
+     * own default decides): `off` leaves compaction to the coding agent, `balanced` keeps more
+     * earlier work verbatim, `aggressive` folds earlier with a tighter working set, `adaptive`
+     * sizes the fold to the conversation (none below 200k tokens, aggressive up to 1M, balanced
+     * above). `--context-profile` overrides it for one launch without saving anything.
      */
     contextProfile?: ContextProfile;
     /**

package/dist/lib/launcher-config.js

@@ -215,7 +215,7 @@ export const CONFIG_KEYS = [
     },
     {
         key: "context_profile",
-        describe: `How the gateway folds each session's context (${CONTEXT_PROFILES.join("|")}; balanced by default)`,
+        describe: `How the gateway folds each session's context (${CONTEXT_PROFILES.join("|")}; unset = the gateway cell's default)`,
         get: (c) => c.contextProfile,
         set: (c, v) => {
             c.contextProfile = parseContextProfile(v, "context_profile");

package/package.json

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