@mnemom/mnemom 0.17.4-next.4 → 0.17.4-next.6

package/dist/commands/agent-setup.d.ts

@@ -74,11 +74,20 @@ export interface EnsureAgentOptions {
     gatewayHost: string;
     /** Override interactivity (defaults to isInteractive()). */
     interactive?: boolean;
+    /** Where the served-agent cache lives (defaults to ~/.mnemom). */
+    cacheDir?: string;
 }
+/** A bare launch never waits on the served-agent probe longer than this. */
+export declare const SERVED_PROBE_TIMEOUT_MS = 10000;
 export interface EnsureAgentResult {
     slug: string;
     /** true only when this call actually birthed/claimed/published. */
     provisioned: boolean;
+    /**
+     * The mnm- id the gateway serves for (key, slug), when this call learned it (a verified name
+     * match, a mismatch, or a fresh birth). Absent when it never asked the gateway.
+     */
+    agentId?: string;
 }
 /**
  * Ensure `slug` is a usable governed agent in the customer's org. Returns

package/dist/commands/agent-setup.js

@@ -26,11 +26,12 @@
 import { claimAgent, getAgentByName, getMe, getMuBalance, getMyPersonalOrg, MnemomApiError, mintProtectionCapability, putAlignmentCard, putProtectionCard, } from "../lib/api.js";
 import { getAuthInfo, isLoggedIn, loginWithBrowser, loginWithDeviceFlow, resolveAuth, } from "../lib/auth.js";
 import { getActiveOrg } from "../lib/cli-config.js";
-import { getApiUrl, getGatewayUrl, getWebsiteUrl } from "../lib/config.js";
+import { getApiUrl, getGatewayUrl, getWebsiteUrl, MNEMOM_DIR } from "../lib/config.js";
 import { fmt } from "../lib/format.js";
 import { askYesNo, isInteractive } from "../lib/prompt.js";
 import { resolveAnthropicDoor, resolveGatewayHost, sanitizeAgentName, singleCellError, } from "../lib/agent.js";
 import { configKeySpec, loadLauncherConfig, writeLauncherConfig } from "../lib/launcher-config.js";
+import { readServedAgent, servedFingerprint, writeServedAgent } from "../lib/served-agent-cache.js";
 import { deriveHashProof } from "./agents.js";
 import { birthThroughGateway } from "./wrap.js";
 import { resolveAnthropicKey } from "./agent.js";
@@ -104,6 +105,8 @@ export class AgentIdentityMismatchError extends Error {
         this.name = "AgentIdentityMismatchError";
     }
 }
+/** A bare launch never waits on the served-agent probe longer than this. */
+export const SERVED_PROBE_TIMEOUT_MS = 10_000;
 /**
  * Ensure `slug` is a usable governed agent in the customer's org. Returns
  * {provisioned:false} when it is already usable, when provisioning is not
@@ -115,33 +118,61 @@ export class AgentIdentityMismatchError extends Error {
  */
 export async function ensureGovernedAgent(opts) {
     const slug = opts.slug;
+    const cacheDir = opts.cacheDir ?? MNEMOM_DIR;
     const interactive = opts.interactive ?? isInteractive();
     // 1. Already usable? A named agent in the caller's fleet is claimed by them.
     const loggedIn = await isLoggedIn();
     if (loggedIn) {
         const existing = await getAgentByName(slug).catch(() => null);
         if (existing) {
+            // MNE-7650: the name is client-controlled and the API exposes no
+            // agent_hash, so a name match proves nothing about which agent the
+            // gateway will serve for (key, slug) — it looks agents up by
+            // hash(credential, name) only. Ask the gateway on EVERY launch, not just
+            // under --setup: the same 16-token "hello" the birth path uses answers
+            // with the served mnm- id on x-mnemom-agent. A bare launch that trusted
+            // the name recorded and reported an org agent while the gateway governed
+            // a different, unclaimed one (a second Anthropic key on a shared name).
+            //
+            // The answer is stable per (key, name, gateway), so a bare launch reuses a cached one and
+            // only probes (time-boxed) the first time; --setup always re-asks.
+            const gatewayUrl = opts.gatewayHost.replace(/\/+$/, "");
+            const fp = servedFingerprint(opts.anthropicKey, slug, gatewayUrl);
+            const cached = opts.setup === true ? null : readServedAgent(cacheDir, fp);
+            let served;
+            try {
+                served =
+                    cached ??
+                        (await birthThroughGateway(gatewayUrl, "anthropic", slug, opts.anthropicKey, {
+                            timeoutMs: opts.setup === true ? undefined : SERVED_PROBE_TIMEOUT_MS,
+                        }));
+            }
+            catch (err) {
+                // --setup must know which agent it governs; a bare launch carries on
+                // with the id unresolved rather than guessing it from the name.
+                if (opts.setup === true)
+                    throw err;
+                say(fmt.dim(`mnemom agent: couldn't confirm which agent the gateway serves for '${slug}' (${err instanceof Error ? err.message : String(err)}) — launching anyway.`));
+                return { slug, provisioned: false };
+            }
+            if (!cached)
+                writeServedAgent(cacheDir, fp, served);
+            if (served !== existing.id) {
+                if (opts.setup === true)
+                    throw new AgentIdentityMismatchError(slug, existing.id, served);
+                warnServedMismatch(slug, existing.id, served);
+                return { slug, provisioned: false, agentId: served };
+            }
             // On an EXPLICIT `mnemom agent setup`, repair/complete the cards on the
             // already-claimed agent (e.g. a protection card that failed on a prior run
             // before we minted its one-time grant). A bare launch leaves it alone.
             if (opts.setup === true) {
-                // MNE-7650: the name is client-controlled and the API exposes no
-                // agent_hash, so a name match proves nothing about which agent the
-                // gateway will serve for (key, slug) — it looks agents up by
-                // hash(credential, name) only. Ask the gateway: the same 16-token
-                // "hello" the birth path uses answers with the served mnm- id on
-                // x-mnemom-agent. Govern that agent or none.
-                const gatewayUrl = opts.gatewayHost.replace(/\/+$/, "");
-                const served = await birthThroughGateway(gatewayUrl, "anthropic", slug, opts.anthropicKey);
-                if (served !== existing.id) {
-                    throw new AgentIdentityMismatchError(slug, existing.id, served);
-                }
                 say(fmt.dim(`mnemom agent: '${slug}' is already claimed (${existing.id}, the agent the gateway serves) — refreshing its cards.`));
                 await publishDefaultCards(existing.id);
                 persistAgentSlug(slug);
-                return { slug, provisioned: true };
+                return { slug, provisioned: true, agentId: existing.id };
             }
-            return { slug, provisioned: false };
+            return { slug, provisioned: false, agentId: existing.id };
         }
     }
     // 2. Are we allowed to provision here?
@@ -186,7 +217,17 @@ export async function ensureGovernedAgent(opts) {
     await publishDefaultCards(agentId);
     // 6. Remember the slug so future launches skip straight to usable.
     persistAgentSlug(slug);
-    return { slug, provisioned: true };
+    return { slug, provisioned: true, agentId };
+}
+/**
+ * A bare launch whose name matches an org agent the gateway does NOT serve for this key. Not
+ * fatal (no --setup asked to govern it), but the user must know their governance lands on the
+ * served agent, and how to get a governed one of their own.
+ */
+function warnServedMismatch(slug, namedId, servedId) {
+    say(fmt.warn(`mnemom agent: '${slug}' in your org is ${namedId}, but the gateway serves ${servedId} for this Anthropic key + name — this session is governed as ${servedId}, which is not claimed to your org.`));
+    say(fmt.dim("  The gateway identity is hash(Anthropic key, name), so another key on the same name is a different agent. " +
+        `Use a name of your own: \`mnemom agent <scenario> --agent <unique-name> --setup\` (or claim the served one: \`mnemom agent claim ${servedId} --key <this key>\`).`));
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /**

package/dist/commands/agent.d.ts

@@ -141,6 +141,11 @@ export declare function recordSessionLaunch(ctx: {
     session: string;
     conversationId: string;
     agent: string;
+    /**
+     * The id the gateway serves, as setup learned it (null = asked, unknown). Undefined = setup
+     * never asked, so fall back to the org's name lookup.
+     */
+    agentId?: string | null;
     account: {
         orgId: string;
         orgLabel: string;

package/dist/commands/agent.js

@@ -297,19 +297,24 @@ export async function agentCommand(scenarioArg, options = {}) {
     // provisions-with-confirm when interactive; warns and continues otherwise.
     // Skipped entirely by `--no-setup`. A provisioning failure never blocks the
     // launch — it degrades to the unclaimed (fail-open) identity with a warning.
+    // The agent id the gateway serves, when setup asked it (undefined = never asked, so the ledger
+    // falls back to the org's name lookup).
+    let servedAgentId;
     if (options.setup !== false && !anthropicKey) {
         // Subscription login: the gateway creates the agent in the Mnemom key's org on the first
         // turn, so there is nothing to birth or claim here.
         say(`mnemom agent: subscription login — '${agent}' is created in your org on the first turn (identity: your Mnemom API key).`);
     }
     else if (options.setup !== false && anthropicKey) {
+        servedAgentId = null; // asked below; stays null if setup can't tell
         try {
-            await ensureGovernedAgent({
+            const ensured = await ensureGovernedAgent({
                 slug: agent,
                 anthropicKey,
                 setup: options.setup,
                 gatewayHost,
             });
+            servedAgentId = ensured.agentId ?? null;
         }
         catch (err) {
             // An identity mismatch is the one setup failure that must NOT degrade: the
@@ -368,6 +373,7 @@ export async function agentCommand(scenarioArg, options = {}) {
         session: scenario,
         conversationId,
         agent,
+        agentId: servedAgentId,
         account,
         gatewayHost,
         shape,
@@ -523,12 +529,19 @@ export async function resolveLaunchConversationId(input) {
  * ledger write failure warns to stderr and the launch proceeds regardless.
  */
 export async function recordSessionLaunch(ctx) {
+    // Never re-derive a known id from the name: the name can match an org agent the gateway does
+    // not serve for this key (MNE-7650), which is exactly what the ledger must not record.
     let agentId;
-    try {
-        agentId = (await getAgentByName(ctx.agent))?.id ?? null;
+    if (ctx.agentId !== undefined) {
+        agentId = ctx.agentId;
     }
-    catch {
-        agentId = null; // unresolvable right now — the ledger still records the launch
+    else {
+        try {
+            agentId = (await getAgentByName(ctx.agent))?.id ?? null;
+        }
+        catch {
+            agentId = null; // unresolvable right now — the ledger still records the launch
+        }
     }
     const result = appendSessionRecord({
         session: ctx.session,

package/dist/commands/wrap.d.ts

@@ -24,5 +24,7 @@ export interface WrapOptions {
     providerKey?: string;
 }
 export declare function wrapCommand(options?: WrapOptions): Promise<void>;
-export declare function birthThroughGateway(gatewayUrl: string, provider: Provider, agentName: string, providerKey: string): Promise<string>;
+export declare function birthThroughGateway(gatewayUrl: string, provider: Provider, agentName: string, providerKey: string, opts?: {
+    timeoutMs?: number;
+}): Promise<string>;
 export {};

package/dist/commands/wrap.js

@@ -199,7 +199,7 @@ async function resolveProviderKey(options, prov, nonInteractive, say) {
     return key;
 }
 // ── Birth call ────────────────────────────────────────────────────────────────
-export async function birthThroughGateway(gatewayUrl, provider, agentName, providerKey) {
+export async function birthThroughGateway(gatewayUrl, provider, agentName, providerKey, opts = {}) {
     const prov = PROVIDERS[provider];
     const authValue = provider === "openai" ? `Bearer ${providerKey}` : providerKey;
     const headers = {
@@ -235,7 +235,12 @@ export async function birthThroughGateway(gatewayUrl, provider, agentName, provi
                 messages: [{ role: "user", content: "hello" }],
             });
     }
-    const response = await fetch(url, { method: "POST", headers, body });
+    const response = await fetch(url, {
+        method: "POST",
+        headers,
+        body,
+        signal: opts.timeoutMs ? AbortSignal.timeout(opts.timeoutMs) : undefined,
+    });
     const agentId = response.headers.get(AGENT_HEADER);
     if (!response.ok && !agentId) {
         const text = await response.text().catch(() => "");

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

@@ -13,7 +13,7 @@
  * 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 Audit } from "./screen.js";
+import { type Audit, type Variation } from "./screen.js";
 export declare const STATE_FILE = "first-run.json";
 export declare const AUDIT_FILE = "first-run-audit.json";
 export declare const OFFER_TEXT: string[];
@@ -45,6 +45,7 @@ export interface ScanOptions {
 export interface FirstRunResult {
     lines: string[];
     audit: Audit;
+    variation?: Variation;
     counts: Record<string, number>;
     seconds: number;
 }

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

@@ -18,8 +18,8 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { estimate, loadTranscript, origContext, ruleRate } from "./backtest.js";
 import { analyzeSeat } from "./seat.js";
-import { authShape, billingClass, buildScope, configDirOf, prettyProject, } from "./scope.js";
-import { BIGGEST_MIN_SAVED_USD, BIGGEST_MIN_SECONDS, DAYS, MAX_LINES, WIDTH, buildScreen, labelFor, } from "./screen.js";
+import { ORG_SEAT_TYPES, authShape, billingClass, buildScope, configDirOf, prettyProject, } from "./scope.js";
+import { DAYS, MAX_LINES, WIDTH, buildScreen, labelFor, } from "./screen.js";
 export const STATE_FILE = "first-run.json";
 export const AUDIT_FILE = "first-run-audit.json";
 export const OFFER_TEXT = [
@@ -76,11 +76,6 @@ export function recordAnswer(st, ans, now) {
         out.accepted_at = iso;
     return out;
 }
-function planName(orgTypes) {
-    const names = [...orgTypes].map((t) => (t === "claude_enterprise" ? "Enterprise" : "Team"));
-    const uniq = [...new Set(names)].sort();
-    return uniq.length === 1 ? uniq[0] : "Team or Enterprise";
-}
 /** Scan, classify, price and build the screen. Read-only on every transcript. */
 export function computeFirstRun(opts = {}) {
     const t0 = Date.now();
@@ -115,13 +110,13 @@ export function computeFirstRun(opts = {}) {
         .map((x) => x.s);
     const seen = new Set();
     const shapes = new Map();
-    const api = { sessions: 0, actual: 0, saved: 0 };
-    const sub = { sessions: 0, actual: 0, saved: 0 };
+    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;
     const seatInputs = new Map();
-    const orgTypes = new Set();
-    const candidates = [];
-    let unsupported = 0;
-    let unknown = 0;
     ordered.forEach((s, i) => {
         if (i % 25 === 0)
             opts.progress?.(`pricing sessions ${i + 1}/${ordered.length}`);
@@ -137,58 +132,51 @@ export function computeFirstRun(opts = {}) {
             shape = authShape(cfg, home);
             shapes.set(cfg, shape);
         }
+        const subLogin = shape.oauth &&
+            (shape.billingType ?? "").includes("subscription") &&
+            ORG_SEAT_TYPES.has(shape.orgType ?? "");
         const { cls } = billingClass(s, rows, shape);
         counts[`billing_${cls}`] = (counts[`billing_${cls}`] ?? 0) + 1;
-        const rowsIn = rows.filter((r) => r.t >= cut);
         if (cls === "subscription_org") {
-            // subscription_org implies a known Team / Enterprise organizationType.
-            orgTypes.add(shape.orgType);
+            // Recorded in the audit only: the screen never shows a hit count or overage dollars.
             const acct = seatInputs.get(cfg) ?? { extra: shape.extraUsage, ss: [] };
             acct.ss.push({ rows, rates: rows.map((r) => ruleRate(origContext(r)).screen), paths });
             seatInputs.set(cfg, acct);
         }
+        const rowsIn = rows.filter((r) => r.t >= cut);
         if (!rowsIn.length)
             return;
-        if (cls === "subscription_consumer" || cls === "subscription_unknown_type") {
-            unsupported++;
-            return;
-        }
-        if (cls === "unknown") {
-            unknown++;
-            return;
-        }
+        // Every class is priced at API list prices; the screen says so.
         const e = estimate(rowsIn);
-        const bucket = cls === "api" ? api : sub;
-        bucket.sessions++;
-        bucket.actual += e.actual;
-        bucket.saved += e.saved;
-        // Top + subagent rows are not in one time order: take the true first and last request.
-        const start = rowsIn.reduce((m, r) => Math.min(m, r.t), Infinity);
         const end = rowsIn.reduce((m, r) => Math.max(m, r.t), -Infinity);
-        if (end - start >= BIGGEST_MIN_SECONDS && e.saved >= BIGGEST_MIN_SAVED_USD) {
-            candidates.push({
-                label: labelFor(prettyProject(s.pdir)),
-                start,
-                end,
-                actual: e.actual,
-                saved: e.saved,
-                billing: cls === "api" ? "api" : "subscription",
-            });
-        }
+        const sc = {
+            label: labelFor(prettyProject(s.pdir)),
+            end,
+            actual: e.actual,
+            saved: e.saved,
+        };
+        sessions.push(sc);
+        if (cls === "subscription_org")
+            subSessions.push(sc);
+        orgLogin ||= subLogin;
     });
     const seat = [...seatInputs.values()].map((a) => analyzeSeat(a.ss, a.extra, now));
-    const biggest = candidates.sort((a, b) => b.actual - a.actual)[0] ?? null;
-    const input = {
-        api: api.sessions ? api : null,
-        sub: sub.sessions ? { ...sub, plan: planName(orgTypes), seat } : null,
-        unsupported,
-        unknown,
-        biggest,
-    };
-    const { lines, audit } = buildScreen(input);
+    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 { lines, audit, variation } = buildScreen({ sessions, sub });
     assertScreenBudget(lines);
-    audit.seat = { shown: null, raw: seat, method: "seat.analyzeSeat per Team/Enterprise account" };
-    return { lines, audit, counts, seconds: (Date.now() - t0) / 1000 };
+    audit.seat = {
+        shown: null,
+        raw: seat,
+        method: "seat.analyzeSeat per Team/Enterprise account; recorded, never shown",
+    };
+    return { lines, audit, variation, counts, seconds: (Date.now() - t0) / 1000 };
 }
 /** The screen's hard budget: a regression in buildScreen's line dropping must fail loudly. */
 export function assertScreenBudget(lines) {

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

@@ -4,33 +4,43 @@
  * 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%.
+ *   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.
+ *
  * 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.
- *   - API-key sessions: dollars. Team / Enterprise subscription sessions: usage-limit
- *     headroom (more work per window, fewer limit stops, less overage) plus the saving
- *     at API list price, labelled as such — never a lower seat bill.
- *   - A saving that rounds below $1 gets the honest "won't change … much" line.
+ *   - 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.
  *   - No live counter is promised: `mnemom agent` has no status bar today.
  */
-import type { SeatAnalysis } from "./seat.js";
 export declare const WIDTH = 78;
 export declare const MAX_LINES = 16;
-/** Less history than this (list price, in the window) is too little to backtest. */
+/** Less history than this (API prices, in the window) is too little to backtest. */
 export declare const MIN_HISTORY_USD = 5;
-/** The biggest session is shown only if it ran this long and saved at least this much. */
-export declare const BIGGEST_MIN_SECONDS = 1800;
-export declare const BIGGEST_MIN_SAVED_USD = 5;
+/** Variation A iff the shown saving is at least this many dollars and this many percent. */
+export declare const STRONG_MIN_USD = 5;
+export declare const STRONG_MIN_PCT = 5;
 export declare const DAYS = 30;
 /**
- * Source: mnemom-adw scratchpad/wow-first-run/COST-REPORT.md, measured chain45 total
- * bill (S44 C2 fold-only -15.8%, S43 C2 -19.5%, S43 C1 -15.7%), stated as the rounded-down
- * range. The d240p1 ~45% figure is NOT used (its re-bill undercounts output).
+ * The forward line: the best finished chain45 run with its error margin (operator
+ * 2026-10-01, until something better): S43 C2 total bill -19.5% [-23.9, -14.9], Opus 5.5,
+ * n=23, 95% CI rounded to 15-25. The d240p1 ~45% figure is NOT used (its re-bill
+ * undercounts output).
  */
-export declare const FORWARD_LINE = "Long sessions are where Mnemom saves the most: about 15 to 20% in our tests.";
+export declare const FORWARD_LINE = "Long sessions are where Mnemom saves the most: about 15 to 25% in our tests.";
+/** 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. */
 export declare const LIVE_LINES: string[];
-export declare const SUPPORTED_LINE = "Mnemom works with an API key or a Claude Team or Enterprise login.";
 /** 2 significant figures, rounded DOWN; 0 below $1. */
 export declare function sig2(x: number): number;
 /** 3 significant figures, rounded DOWN; 0 below $1. */
@@ -42,41 +52,31 @@ export declare function sig3(x: number): number;
 export declare function pair(total: number, saved: number): [number, number, number];
 /** part / whole as a percentage rounded DOWN to a multiple of 5. */
 export declare function pct5(part: number, whole: number): number;
-/** Wall-clock length rounded DOWN: "11 h", "1.5 h", "40 min". */
-export declare function hoursDown(sec: number): string;
 export declare function day(t: number): string;
 export declare function usd(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[];
-export interface Totals {
-    sessions: number;
-    /** List-price cost of the requests in the window. */
+/** One kept session's requests in the window, priced at API list prices. */
+export interface SessionCost {
+    label: string | null;
+    end: number;
     actual: number;
-    /** The conservative saving on those requests (backtest.estimate). */
     saved: number;
 }
-export interface Biggest {
-    label: string | null;
-    start: number;
-    end: number;
+/** 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;
-    billing: "api" | "subscription";
 }
 export interface ScreenInput {
-    /** API-key sessions in the window (null: none). */
-    api: Totals | null;
-    /** Team / Enterprise subscription sessions in the window (null: none). */
-    sub: (Totals & {
-        plan: string;
-        seat: SeatAnalysis[];
-    }) | null;
-    /** Sessions on a plan the gateway does not support, or with no billing evidence. */
-    unsupported: number;
-    unknown: number;
-    biggest: Biggest | null;
+    /** Every kept session with requests in the window. */
+    sessions: SessionCost[];
+    /** null: not a Team / Enterprise subscriber. */
+    sub: SubUsage | null;
 }
 export interface AuditEntry {
     shown: unknown;
@@ -84,8 +84,10 @@ export interface AuditEntry {
     method: string;
 }
 export type Audit = Record<string, AuditEntry>;
-/** -> the screen lines and the audit of every number on them. */
+export type Variation = "A" | "B" | "C";
+/** -> the screen lines, the variation and the audit of every number on them. */
 export declare function buildScreen(inp: ScreenInput): {
     lines: string[];
     audit: Audit;
+    variation: Variation;
 };

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

@@ -4,38 +4,49 @@
  * 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%.
+ *   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.
+ *
  * 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.
- *   - API-key sessions: dollars. Team / Enterprise subscription sessions: usage-limit
- *     headroom (more work per window, fewer limit stops, less overage) plus the saving
- *     at API list price, labelled as such — never a lower seat bill.
- *   - A saving that rounds below $1 gets the honest "won't change … much" line.
+ *   - 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.
  *   - No live counter is promised: `mnemom agent` has no status bar today.
  */
 import { ESTIMATOR_METHOD } from "./backtest.js";
 export const WIDTH = 78;
 export const MAX_LINES = 16;
-/** Less history than this (list price, in the window) is too little to backtest. */
+/** Less history than this (API prices, in the window) is too little to backtest. */
 export const MIN_HISTORY_USD = 5;
-/** The biggest session is shown only if it ran this long and saved at least this much. */
-export const BIGGEST_MIN_SECONDS = 1800;
-export const BIGGEST_MIN_SAVED_USD = 5;
+/** Variation A iff the shown saving is at least this many dollars and this many percent. */
+export const STRONG_MIN_USD = 5;
+export const STRONG_MIN_PCT = 5;
 export const DAYS = 30;
 /**
- * Source: mnemom-adw scratchpad/wow-first-run/COST-REPORT.md, measured chain45 total
- * bill (S44 C2 fold-only -15.8%, S43 C2 -19.5%, S43 C1 -15.7%), stated as the rounded-down
- * range. The d240p1 ~45% figure is NOT used (its re-bill undercounts output).
+ * The forward line: the best finished chain45 run with its error margin (operator
+ * 2026-10-01, until something better): S43 C2 total bill -19.5% [-23.9, -14.9], Opus 5.5,
+ * n=23, 95% CI rounded to 15-25. The d240p1 ~45% figure is NOT used (its re-bill
+ * undercounts output).
  */
-export const FORWARD_LINE = "Long sessions are where Mnemom saves the most: about 15 to 20% in our tests.";
-const FORWARD_SOURCE = "COST-REPORT.md measured chain45 total bill: S44 C2 -15.8%, S43 C2 -19.5%, S43 C1 -15.7%; " +
-    "stated as 15 to 20%";
+export const FORWARD_LINE = "Long sessions are where Mnemom saves the most: about 15 to 25% in our tests.";
+const FORWARD_SOURCE = "operator 2026-10-01: S43 C2 total bill -19.5% [-23.9, -14.9] (Opus 5.5, n=23), 95% CI " +
+    "rounded to 15 to 25; measured vs stock at the 1M default";
+/** 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. */
 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.",
 ];
-export const SUPPORTED_LINE = "Mnemom works with an API key or a Claude Team or Enterprise login.";
 // ── rounding (never inflate) ─────────────────────────────────────────────────
 /** 2 significant figures, rounded DOWN; 0 below $1. */
 export function sig2(x) {
@@ -66,15 +77,6 @@ export function pct5(part, whole) {
         return 0;
     return Math.floor((100 * part) / whole / 5 + 1e-9) * 5;
 }
-/** Wall-clock length rounded DOWN: "11 h", "1.5 h", "40 min". */
-export function hoursDown(sec) {
-    const h = sec / 3600;
-    if (h >= 2)
-        return `${Math.floor(h)} h`;
-    if (h >= 1)
-        return `${(Math.floor(h * 10) / 10).toFixed(1)} h`;
-    return `${Math.max(Math.floor(sec / 60), 1)} min`;
-}
 const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
 export function day(t) {
     const d = new Date(t * 1000);
@@ -115,210 +117,94 @@ 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, requests in the " +
-    "last 30 days; 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, 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 SAVED_METHOD = `backtest.estimate(): ${ESTIMATOR_METHOD}; 2 sig figs DOWN`;
-function apiBlock(api, both, A) {
-    const [a, s, e] = pair(api.actual, api.saved);
-    const p = pct5(api.saved, api.actual);
-    const who = both ? "On your API key you spent" : "You spent";
-    A("api_spent_usd", { shown: a, raw: api.actual, method: SPENT_METHOD });
-    if (s < 1) {
-        A("api_small_saving", { shown: true, raw: api.saved, method: "saving rounds below $1" });
-        return wrap(`${who} about ${usd(a)}. Mnemom won't change your bill much.`);
-    }
-    A("api_saved_usd", { shown: s, raw: api.saved, method: SAVED_METHOD });
-    A("api_with_mnemom_usd", {
-        shown: e,
-        raw: api.actual - api.saved,
-        method: "spent shown - saved shown",
-    });
-    A("api_saved_pct", {
-        shown: p,
-        raw: (100 * api.saved) / api.actual,
-        method: "rounded DOWN to 5s",
-    });
-    const pctPart = p >= 5 ? `, ${p}%,` : "";
-    return [
-        ...wrap(`${who} about ${usd(a)}. With Mnemom: about ${usd(e)}.`),
-        ...wrap(`That's about ${usd(s)} back${pctPart} and you don't change how you work.`),
-    ];
-}
-/** The seat-evidence line: overage paid (real dollars) or limit stops. At most 2 lines. */
-function seatEvidence(seat, A) {
-    const ov = seat.flatMap((x) => (x.overage ? [x.overage] : []));
-    const paid = ov.reduce((t, o) => t + o.paidUsd, 0);
-    if (paid >= 1) {
-        const wm = ov.reduce((t, o) => t + o.withMnemomUsd, 0);
-        const [p, , w] = pair(paid, paid - wm);
-        A("seat_overage_usd", { shown: p, raw: paid, method: ov[0].method });
-        A("seat_overage_with_mnemom_usd", { shown: w, raw: wm, method: "paid shown - avoided shown" });
-        return wrap(`You paid about ${usd(p)} in extra usage. With Mnemom, about ${usd(w)} of extra usage.`);
-    }
-    const hs = seat.flatMap((x) => (x.hits ? [x.hits] : []));
-    const n = hs.reduce((t, h) => t + h.n, 0);
-    if (n < 1)
+function subLines(sub, A) {
+    if (!sub)
         return [];
-    const wm = hs.reduce((t, h) => t + h.withMnemom, 0);
-    const fewer = hs.reduce((t, h) => t + h.notInferableWithSaving, 0);
-    const hrs = Math.floor(hs.reduce((t, h) => t + h.waitedS, 0) / 3600);
-    A("seat_limit_hits", {
-        shown: n,
-        raw: n,
-        method: "Claude Code's own limit records, last 30 days",
-    });
-    A("seat_hits_with_mnemom", { shown: wm, raw: wm, method: hs[0].method });
-    A("seat_waited_hours", {
-        shown: hrs,
-        raw: hs.reduce((t, h) => t + h.waitedS, 0) / 3600,
-        method: "hours DOWN",
-    });
-    const wait = hrs >= 1 ? ` and waited about ${hrs} hour${hrs === 1 ? "" : "s"}` : "";
-    let tail = "";
-    if (wm < n)
-        tail = ` With Mnemom, about ${wm}.`;
-    else if (fewer)
-        tail = " With Mnemom, fewer.";
-    return wrap(`You hit your plan's usage limit ${n} time${n === 1 ? "" : "s"}${wait}.${tail}`);
-}
-function subBlock(sub, A) {
-    const [u, s, w] = pair(sub.actual, sub.saved);
     const p = pct5(sub.saved, sub.actual);
-    const n = sub.sessions;
-    A("sub_usage_list_usd", {
-        shown: u,
-        raw: sub.actual,
-        method: `${SPENT_METHOD}; list-price equivalent, not a bill`,
-    });
-    const head = wrap(`On your Claude ${sub.plan} plan: ${n} session${n === 1 ? "" : "s"}, about ${usd(u)} of usage at API list price.`);
-    if (s < 1) {
-        A("sub_small_saving", { shown: true, raw: sub.saved, method: "saving rounds below $1" });
-        return { lines: [...head, "Mnemom won't change your usage much."], evidence: [] };
+    const raw = sub.actual > 0 ? (100 * sub.saved) / sub.actual : 0;
+    if (p < 5) {
+        A("sub_line_omitted", { shown: true, raw, method: "usage cut rounds DOWN below 5%" });
+        return [];
     }
-    A("sub_saved_list_usd", { shown: s, raw: sub.saved, method: SAVED_METHOD });
-    A("sub_with_mnemom_list_usd", {
-        shown: w,
-        raw: sub.actual - sub.saved,
-        method: "usage shown - saved shown",
-    });
-    // Using a fraction f less per request fits 1/(1-f) - 1 >= f more work in a window; we
-    // state f itself, rounded down to 5s, which never exceeds the true headroom.
-    A("sub_headroom_pct", {
+    A("sub_usage_pct", {
         shown: p,
-        raw: (100 * sub.saved) / sub.actual,
-        method: "states the usage saving %, rounded DOWN to 5s: a lower bound on the extra work per window, " +
-            "which is saved / (usage - saved)",
+        raw,
+        method: "saving / API-price cost over the subscription sessions in the window (all sessions if " +
+            "none is tagged); cost-weighted, rounded DOWN to 5s",
     });
-    const room = p >= 5
-        ? `room for about ${p}% more work in each usage window before a limit.`
-        : "a little more room in each usage window before a limit.";
-    return {
-        lines: [
-            ...head,
-            ...wrap(`With Mnemom: about ${usd(w)} at list price (not your bill), so ${room}`),
-        ],
-        evidence: seatEvidence(sub.seat, A),
-    };
+    return wrap(`On your subscription that is about ${p}% less usage: fewer limit hits, and less ` +
+        "overage if you use extra usage.");
 }
-function biggestBlock(b, A) {
-    const [a, , e] = pair(b.actual, b.saved);
-    const hrs = hoursDown(b.end - b.start);
-    const lp = b.billing === "subscription" ? " at list price" : "";
-    A("biggest_session_usd", {
-        shown: a,
-        raw: b.actual,
-        method: "largest bill among sessions >= 30 min with >= $5 saved; 3 sig figs DOWN",
-    });
-    A("biggest_session_with_mnemom_usd", {
-        shown: e,
-        raw: b.actual - b.saved,
-        method: "its bill shown - its saving (2 sig figs DOWN)",
-    });
-    A("biggest_session_hours", {
-        shown: hrs,
-        raw: (b.end - b.start) / 3600,
-        method: "first to last request, wall clock; DOWN",
-    });
-    const head = b.label
-        ? `Your biggest session: ${b.label}, ${day(b.end)}, ${hrs}, ${usd(a)}${lp}.`
-        : `Your biggest session, on ${day(b.end)}: ${hrs}, ${usd(a)}${lp}.`;
-    const tail = b.billing === "subscription"
-        ? `With Mnemom it would have used about ${usd(e)} of that.`
-        : `With Mnemom it would have cost about ${usd(e)}.`;
-    return [...wrap(head), tail];
-}
-/** -> the screen lines and the audit of every number on them. */
+/** -> the screen lines, the variation and the audit of every number on them. */
 export function buildScreen(inp) {
     const audit = {};
     const A = (k, e) => {
         audit[k] = e;
     };
-    const apiOk = !!inp.api && inp.api.actual >= MIN_HISTORY_USD;
-    const subOk = !!inp.sub && inp.sub.actual >= MIN_HISTORY_USD;
-    const sections = [];
-    // drop: 0 = never dropped; higher = dropped first when the screen is over budget.
-    const push = (lines, drop = 0) => {
-        sections.push({ lines: ["", ...lines], drop });
-    };
-    sections.push({ lines: ["Welcome to Mnemom."], drop: 0 });
-    let anySaving = false;
-    if (apiOk || subOk) {
-        push(wrap(`We looked at your last ${DAYS} days of Claude Code. It all stayed on this machine.`));
-        // Frame the number around the biggest session: it leads.
-        if (inp.biggest)
-            push(biggestBlock(inp.biggest, A), 2);
-        else
-            A("biggest_session_omitted", {
-                shown: true,
-                raw: null,
-                method: "no session >= 30 min with >= $5 saved",
-            });
-        if (apiOk && inp.api) {
-            const lines = apiBlock(inp.api, subOk, A);
-            anySaving ||= "api_saved_usd" in audit;
-            push(lines);
-        }
-        if (subOk && inp.sub) {
-            const { lines, evidence } = subBlock(inp.sub, A);
-            anySaving ||= "sub_saved_list_usd" in audit;
-            push(lines);
-            if (evidence.length)
-                sections[sections.length - 1].lines.push(...evidence);
-        }
-        if (!anySaving) {
-            push([FORWARD_LINE], 3);
-            A("forward_range_pct", {
-                shown: "15 to 20",
-                raw: [15.7, 15.8, 19.5],
-                method: FORWARD_SOURCE,
-            });
-        }
+    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 = pct5(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 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_usd", { shown: s, raw: saved, method: SAVED_METHOD });
+        A("with_mnemom_usd", { shown: e, raw: actual - saved, method: "spent shown - saved shown" });
+        A("saved_pct", { shown: p, raw: (100 * saved) / actual, method: "rounded DOWN to 5s" });
+        L.push(...wrap(`At API prices that usage cost about ${usd(a)}. With Mnemom: about ${usd(e)}.`));
+        L.push(...wrap(`That's about ${usd(s)} less (${p}%), and you don't change how you work.`));
+        // 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)",
+        });
+        const where = big.label ? `${big.label} on ${day(big.end)}` : `on ${day(big.end)}`;
+        L.push(...wrap(`Your biggest session, ${where}: ${usd(ba)}, with Mnemom about ${usd(be)}.`));
+        L.push(...subLines(inp.sub, A));
     }
     else {
-        push(["We looked at your recent Claude Code sessions. It all stayed on this machine."]);
-        if (inp.unsupported > 0)
-            push([SUPPORTED_LINE]);
+        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."));
+        }
+        L.push(FORWARD_LINE);
+        A("forward_range_pct", {
+            shown: "15 to 25",
+            raw: [-23.9, -19.5, -14.9],
+            method: FORWARD_SOURCE,
+        });
     }
-    push(LIVE_LINES);
+    L.push("", PRICE_LINE, "", ...LIVE_LINES);
     A("sessions", {
         shown: null,
-        raw: {
-            api: inp.api?.sessions ?? 0,
-            subscription: inp.sub?.sessions ?? 0,
-            unsupported: inp.unsupported,
-            unknown: inp.unknown,
-        },
-        method: "kept (ungoverned) sessions with requests in the window, by billing class",
+        raw: ses.length,
+        method: "kept sessions with requests in the window",
     });
-    const count = () => sections.reduce((t, s) => t + s.lines.length, 0);
-    for (const level of [3, 2]) {
-        if (count() <= MAX_LINES)
-            break;
-        for (let i = sections.length - 1; i >= 0; i--) {
-            if (sections[i].drop === level)
-                sections.splice(i, 1);
-        }
-    }
-    const lines = sections.flatMap((s) => s.lines).map(clean);
-    return { lines, audit };
+    return { lines: L.map(clean), audit, variation };
 }

package/dist/lib/served-agent-cache.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Which mnm- agent the gateway serves for (Anthropic key, agent name, gateway).
+ *
+ * The gateway identity is hash(key, name), so the answer for one (key, name, gateway) is stable:
+ * once a launch has asked, later launches reuse it instead of paying for another probe
+ * completion. Entries are keyed by a one-way fingerprint and never hold the key itself (nor the
+ * sha256(key|name) claim proof). `--setup` always re-asks and overwrites.
+ */
+/**
+ * A slow KDF (scrypt), not a fast hash: the fingerprint is derived from a credential and lands on
+ * disk, so recovering the key from it must cost what guessing a password would. Name and
+ * gateway are the salt — the lookup has to be deterministic, and they make each entry unique.
+ */
+export declare function servedFingerprint(anthropicKey: string, slug: string, gateway: string): string;
+/** The cached served id, or null (missing, unreadable, or not an mnm- id). */
+export declare function readServedAgent(dir: string, fingerprint: string): string | null;
+/** Best effort: a failed write only means the next launch asks again. */
+export declare function writeServedAgent(dir: string, fingerprint: string, agentId: string): void;

package/dist/lib/served-agent-cache.js

@@ -0,0 +1,50 @@
+/**
+ * Which mnm- agent the gateway serves for (Anthropic key, agent name, gateway).
+ *
+ * The gateway identity is hash(key, name), so the answer for one (key, name, gateway) is stable:
+ * once a launch has asked, later launches reuse it instead of paying for another probe
+ * completion. Entries are keyed by a one-way fingerprint and never hold the key itself (nor the
+ * sha256(key|name) claim proof). `--setup` always re-asks and overwrites.
+ */
+import { scryptSync } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+const FILE = "served-agents.json";
+/**
+ * A slow KDF (scrypt), not a fast hash: the fingerprint is derived from a credential and lands on
+ * disk, so recovering the key from it must cost what guessing a password would. Name and
+ * gateway are the salt — the lookup has to be deterministic, and they make each entry unique.
+ */
+export function servedFingerprint(anthropicKey, slug, gateway) {
+    return scryptSync(anthropicKey, `mnemom-served-agent-v1\n${slug}\n${gateway}`, 32).toString("hex");
+}
+function readAll(dir) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(dir, FILE), "utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** The cached served id, or null (missing, unreadable, or not an mnm- id). */
+export function readServedAgent(dir, fingerprint) {
+    const id = readAll(dir)[fingerprint];
+    return typeof id === "string" && /^mnm-/.test(id) ? id : null;
+}
+/** Best effort: a failed write only means the next launch asks again. */
+export function writeServedAgent(dir, fingerprint, agentId) {
+    try {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const tmp = path.join(dir, `${FILE}.${process.pid}.tmp`);
+        fs.writeFileSync(tmp, JSON.stringify({ ...readAll(dir), [fingerprint]: agentId }, null, 2), {
+            mode: 0o600,
+        });
+        fs.renameSync(tmp, path.join(dir, FILE));
+    }
+    catch {
+        /* best effort */
+    }
+}

package/package.json

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