@mnemom/mnemom 0.17.4 → 0.17.5-next.0

package/dist/commands/agent.js

@@ -31,6 +31,7 @@ import { randomUUID } from "node:crypto";
 import { tmpdir, homedir, hostname, userInfo } from "node:os";
 import { basename, join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { statuslineLaunch } from "../lib/statusline.js";
 import { getApiUrl, getGatewayUrl, MNEMOM_DIR } from "../lib/config.js";
 import { createApiKey, getAgentByName } from "../lib/api.js";
 import { MNEMOM_KEY_STORE_FIELD, resolveAgentAuth, resolveSubscriptionMnemomKey, subscriptionChildEnv, subscriptionShape, } from "../lib/subscription-login.js";
@@ -978,6 +979,21 @@ function launchTerminal(ctx) {
     applyGatewayHintHeaders(childEnv);
     if (ctx.options.slack)
         args.push(...slackChannelArgs(sessionName));
+    // The status-bar savings counter (lib/statusline.ts). Claude Code only; the
+    // user's own statusLine keeps running in front of it.
+    if (ctx.cli.name === "claude") {
+        const sl = statuslineLaunch({
+            passthrough: ctx.options.passthrough ?? [],
+            env: childEnv,
+            cwd: process.cwd(),
+            node: process.execPath,
+            bin: join(dirname(fileURLToPath(import.meta.url)), "..", "lib", "statusline-bin.js"),
+        });
+        if (sl) {
+            args.push(...sl.args);
+            Object.assign(childEnv, sl.env);
+        }
+    }
     if (ctx.contextHint) {
         seedContextHintFlag(childEnv);
         childEnv.CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1";

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

@@ -45,6 +45,14 @@ export declare function rowCost(r: Row): number;
 export declare function actualBill(rows: readonly Row[]): number;
 /** An ungoverned request's original context = its billed prompt. */
 export declare function origContext(r: Row): number;
+/**
+ * One transcript line → its billed request, or null (not an assistant record with usage).
+ * `id` is the message id (or record uuid); null when the record carries neither.
+ */
+export declare function parseUsageLine(line: Buffer, subagent: boolean): {
+    id: string | null;
+    row: Row;
+} | 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

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

@@ -69,42 +69,37 @@ const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : 0);
 const USAGE = Buffer.from('"usage"');
 const ASSISTANT = Buffer.from('"assistant"');
 /**
- * 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.
+ * One transcript line → its billed request, or null (not an assistant record with usage).
+ * `id` is the message id (or record uuid); null when the record carries neither.
  */
-export function loadTranscript(path, seen) {
-    const byId = new Map();
-    const subagent = path.includes("/subagents/");
-    let anon = 0;
-    forEachLine(path, (line) => {
-        if (line.indexOf(USAGE) === -1 || line.indexOf(ASSISTANT) === -1)
-            return;
-        const d = parseJson(line);
-        if (!d || d.type !== "assistant")
-            return;
-        const m = d.message;
-        if (!m || typeof m !== "object")
-            return;
-        const u = m.usage;
-        if (!u || typeof u !== "object")
-            return;
-        const model = typeof m.model === "string" ? m.model : "";
-        if (!model || model.startsWith("<"))
-            return;
-        const t = isoSeconds(d.timestamp);
-        if (t === null)
-            return;
-        const cc = u.cache_creation ?? {};
-        const cw = num(u.cache_creation_input_tokens);
-        const cw1h = num(cc.ephemeral_1h_input_tokens);
-        // Older Claude Code versions omit the 5m split (or the whole cache_creation object):
-        // derive 5m as total − 1h, and never let a reported 5m share leave writes unbilled.
-        const cw5 = Math.max(num(cc.ephemeral_5m_input_tokens), cw - cw1h);
-        const id = (typeof m.id === "string" && m.id) ||
-            (typeof d.uuid === "string" && d.uuid) ||
-            `anon-${path}-${anon++}`;
-        byId.set(id, {
+export function parseUsageLine(line, subagent) {
+    if (line.indexOf(USAGE) === -1 || line.indexOf(ASSISTANT) === -1)
+        return null;
+    const d = parseJson(line);
+    if (!d || d.type !== "assistant")
+        return null;
+    const m = d.message;
+    if (!m || typeof m !== "object")
+        return null;
+    const u = m.usage;
+    if (!u || typeof u !== "object")
+        return null;
+    const model = typeof m.model === "string" ? m.model : "";
+    if (!model || model.startsWith("<"))
+        return null;
+    const t = isoSeconds(d.timestamp);
+    if (t === null)
+        return null;
+    const cc = u.cache_creation ?? {};
+    const cw = num(u.cache_creation_input_tokens);
+    const cw1h = num(cc.ephemeral_1h_input_tokens);
+    // Older Claude Code versions omit the 5m split (or the whole cache_creation object):
+    // derive 5m as total − 1h, and never let a reported 5m share leave writes unbilled.
+    const cw5 = Math.max(num(cc.ephemeral_5m_input_tokens), cw - cw1h);
+    const id = (typeof m.id === "string" && m.id) || (typeof d.uuid === "string" && d.uuid) || null;
+    return {
+        id,
+        row: {
             t,
             model,
             inp: num(u.input_tokens),
@@ -114,7 +109,22 @@ export function loadTranscript(path, seen) {
             out: num(u.output_tokens),
             mainThread: d.isSidechain !== true,
             subagent,
-        });
+        },
+    };
+}
+/**
+ * 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.
+ */
+export function loadTranscript(path, seen) {
+    const byId = new Map();
+    const subagent = path.includes("/subagents/");
+    let anon = 0;
+    forEachLine(path, (line) => {
+        const r = parseUsageLine(line, subagent);
+        if (r)
+            byId.set(r.id ?? `anon-${path}-${anon++}`, r.row);
     });
     const out = [];
     for (const [id, row] of byId) {

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

@@ -3,6 +3,11 @@
  * 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.
+ *
  * 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,
@@ -13,6 +18,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 ScopeResult, type Session } from "./scope.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";
@@ -51,6 +57,20 @@ export interface FirstRunResult {
 }
 /** Scan, classify, price and build the screen. Read-only on every transcript. */
 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.
+ */
+export declare function pricedSessions(scope: ScopeResult): Array<{
+    s: Session;
+    viaMnemom: boolean;
+}>;
+/**
+ * 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.
+ */
+export declare const LEDGER_SIGNALS: Set<string>;
 /** 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,6 +3,11 @@
  * 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.
+ *
  * 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,
@@ -95,8 +100,8 @@ export function computeFirstRun(opts = {}) {
     const counts = {
         sessions_total: scope.sessions.size,
         sessions_recent: scope.inWindow,
-        excluded_governed_or_doubt: scope.excluded.size,
-        kept: scope.kept.size,
+        governed_or_doubt: scope.excluded.size,
+        ungoverned: scope.kept.size,
     };
     for (const sigs of scope.excluded.values()) {
         for (const s of sigs)
@@ -104,10 +109,11 @@ export function computeFirstRun(opts = {}) {
     }
     // Oldest first, so a message copied into a later (resumed / forked) transcript is billed
     // once, to its origin.
-    const ordered = [...scope.kept.values()]
-        .map((s) => ({ s, m: mtimeOf(s.top) }))
-        .sort((a, b) => a.m - b.m)
-        .map((x) => x.s);
+    const priced = pricedSessions(scope);
+    counts.priced = priced.length;
+    const ordered = priced
+        .map((x) => ({ ...x, m: mtimeOf(x.s.top) }))
+        .sort((a, b) => a.m - b.m);
     const seen = new Set();
     const shapes = new Map();
     const sessions = [];
@@ -117,7 +123,7 @@ export function computeFirstRun(opts = {}) {
     // their subscription (lib/subscription-login.ts), so only they get the usage sentence.
     let orgLogin = false;
     const seatInputs = new Map();
-    ordered.forEach((s, i) => {
+    ordered.forEach(({ s, viaMnemom }, i) => {
         if (i % 25 === 0)
             opts.progress?.(`pricing sessions ${i + 1}/${ordered.length}`);
         const paths = [s.top, ...[...s.subs].sort()];
@@ -154,6 +160,7 @@ export function computeFirstRun(opts = {}) {
             end,
             actual: e.actual,
             saved: e.saved,
+            viaMnemom,
         };
         sessions.push(sc);
         if (cls === "subscription_org")
@@ -178,6 +185,27 @@ export function computeFirstRun(opts = {}) {
     };
     return { lines, audit, variation, counts, seconds: (Date.now() - t0) / 1000 };
 }
+/**
+ * The sessions the screen prices: every session in the window, one per session id (an
+ * ungoverned copy first), none without a parent transcript.
+ */
+export function pricedSessions(scope) {
+    const out = new Map();
+    for (const key of [...scope.kept.keys(), ...scope.excluded.keys()]) {
+        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)) });
+    }
+    return [...out.values()];
+}
+/**
+ * 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.
+ */
+export const LEDGER_SIGNALS = new Set(["registry_cc_id", "registry_conv_id"]);
 /** The screen's hard budget: a regression in buildScreen's line dropping must fail loudly. */
 export function assertScreenBudget(lines) {
     if (lines.length > MAX_LINES || lines.some((l) => l.length > WIDTH)) {

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

@@ -2,9 +2,11 @@
  * Which local Claude Code sessions the first-run look may count, and how each was billed.
  *
  * Operator rulings (2026-09-30 / 2026-10-01), binding:
- *   - The ONLY exclusion is "governed" (already ran through Mnemom); when in doubt,
- *     exclude. A headless `claude -p` session (entrypoint sdk-cli) is excluded: the env of
- *     the script that launched it (ANTHROPIC_BASE_URL, a proxy) is never recorded.
+ *   - "Governed" (already ran through Mnemom, or in doubt) is classified here and
+ *     recorded in the audit; since 2026-10-02 it no longer removes a session from the
+ *     priced set (index.ts pricedSessions: every session is counted). A headless
+ *     `claude -p` session (entrypoint sdk-cli) is marked: the env of the script that
+ *     launched it (ANTHROPIC_BASE_URL, a proxy) is never recorded.
  *   - Sessions are discovered in ~/.claude/projects and every ~/.claude-*\/projects.
  *   - Dollars are shown for API-billed sessions; Team / Enterprise subscription sessions
  *     (the plans `mnemom agent --auth subscription` supports) are in scope as usage-limit

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

@@ -2,9 +2,11 @@
  * Which local Claude Code sessions the first-run look may count, and how each was billed.
  *
  * Operator rulings (2026-09-30 / 2026-10-01), binding:
- *   - The ONLY exclusion is "governed" (already ran through Mnemom); when in doubt,
- *     exclude. A headless `claude -p` session (entrypoint sdk-cli) is excluded: the env of
- *     the script that launched it (ANTHROPIC_BASE_URL, a proxy) is never recorded.
+ *   - "Governed" (already ran through Mnemom, or in doubt) is classified here and
+ *     recorded in the audit; since 2026-10-02 it no longer removes a session from the
+ *     priced set (index.ts pricedSessions: every session is counted). A headless
+ *     `claude -p` session (entrypoint sdk-cli) is marked: the env of the script that
+ *     launched it (ANTHROPIC_BASE_URL, a proxy) is never recorded.
  *   - Sessions are discovered in ~/.claude/projects and every ~/.claude-*\/projects.
  *   - Dollars are shown for API-billed sessions; Team / Enterprise subscription sessions
  *     (the plans `mnemom agent --auth subscription` supports) are in scope as usage-limit

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

@@ -8,7 +8,9 @@
  * 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%.
+ *               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.
@@ -64,6 +66,8 @@ export interface SessionCost {
     end: number;
     actual: number;
     saved: number;
+    /** The launch ledger proves it ran through Mnemom: its saving is said to be SAVED. */
+    viaMnemom?: boolean;
 }
 /** A Team / Enterprise subscriber's usage, at API prices (local evidence only). */
 export interface SubUsage {

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

@@ -8,7 +8,9 @@
  * 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%.
+ *               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.
@@ -160,11 +162,33 @@ export function buildScreen(inp) {
     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.`));
+        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)}.`));
+            L.push(...wrap(`That's about ${usd(s)} less (${p}%), and you don't change how you work.`));
+        }
+        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.`));
+            if (rest < 1) {
+                L.push(...wrap(`Mnemom saved you about ${usd(via)} of it (${p}%), and you didn't change how you work.`));
+            }
+            else {
+                A("saved_rest_usd", {
+                    shown: rest,
+                    raw: saved - viaRaw,
+                    method: `${SAVED_METHOD}; the rest`,
+                });
+                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);
@@ -179,7 +203,9 @@ export function buildScreen(inp) {
             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(...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)}.`));
         L.push(...subLines(inp.sub, A));
     }
     else {

package/dist/lib/statusline-bin.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Entry for the `mnemom agent` status-bar counter (lib/statusline.ts). Claude Code runs it
+ * on every status update, so it imports only the counter — not the whole CLI.
+ */
+export {};

package/dist/lib/statusline-bin.js

@@ -0,0 +1,16 @@
+/**
+ * Entry for the `mnemom agent` status-bar counter (lib/statusline.ts). Claude Code runs it
+ * on every status update, so it imports only the counter — not the whole CLI.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { INNER_ENV, render } from "./statusline.js";
+const chunks = [];
+process.stdin.on("data", (c) => chunks.push(c));
+process.stdin.on("end", () => {
+    const line = render(Buffer.concat(chunks).toString("utf8"), {
+        stateDir: join(homedir(), ".mnemom", "statusline"),
+        inner: process.env[INNER_ENV] || undefined,
+    });
+    process.stdout.write(`${line}\n`);
+});

package/dist/lib/statusline.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The `mnemom agent` status-bar savings counter: a Claude Code statusLine command that
+ * prints "mnemom saved ~$X this session".
+ *
+ * The number is the first-run look's estimator (first-run/backtest.ts), applied live to this
+ * session's own transcript: each request priced at API list prices, times the empirical
+ * curve's lower-bound saving rate for its original context. So the counter and the
+ * first-run screen always agree, and it rounds DOWN to the cent.
+ *
+ * Claude Code runs the command on every status update with its status JSON on stdin
+ * (session_id, transcript_path, …). It must be fast, so the transcript is read
+ * incrementally: per session, a state file (~/.mnemom/statusline/<session>.json, 0600)
+ * keeps each file's byte offset and each message id's contribution, and a tick reads at
+ * most MAX_BYTES_PER_TICK of new bytes (a big resumed session catches up over ticks).
+ *
+ * A user's own statusLine is never replaced: the launch passes it in
+ * MNEMOM_STATUSLINE_INNER, it runs with the same stdin, and our segment is appended.
+ * Read-only on every transcript; no network. It lives outside lib/first-run because it runs
+ * the user's own statusLine command, and the first-run code is held to spawning nothing.
+ */
+export declare const STATE_DIR = "statusline";
+export declare const MAX_BYTES_PER_TICK: number;
+/** The launcher passes the user's own statusLine command here. */
+export declare const INNER_ENV = "MNEMOM_STATUSLINE_INNER";
+/** Set to 1 to launch without the counter. */
+export declare const NO_STATUSLINE_ENV = "MNEMOM_AGENT_NO_STATUSLINE";
+export declare const INNER_TIMEOUT_MS = 2000;
+export interface SessionState {
+    v: 1;
+    /** Byte offset read so far, per transcript file. */
+    files: Record<string, number>;
+    /** Per message id: [list-price cost, saving]. A re-written id replaces its old share. */
+    ids: Record<string, [number, number]>;
+    actual: number;
+    saved: number;
+}
+export declare function freshState(): SessionState;
+/** The main transcript, then its subagent transcripts (sorted). */
+export declare function sessionFiles(transcriptPath: string): string[];
+/**
+ * The complete lines of `path` from `offset`, at most `maxBytes` of them, and the offset
+ * after the last complete line. null: the file is unreadable or shorter than `offset`.
+ */
+export declare function readNewLines(path: string, offset: number, maxBytes: number): {
+    lines: Buffer[];
+    next: number;
+} | null;
+/** Read what is new in the session's files into `st`. A file that shrank resets the count. */
+export declare function update(st: SessionState, files: string[], maxBytes?: number): SessionState;
+/** The segment, rounded DOWN to the cent and never below $0.00. */
+export declare function segment(saved: number): string;
+export declare function loadState(path: string): SessionState;
+export declare function saveState(path: string, st: SessionState): void;
+/** Run the user's own statusLine command with the same stdin; its first line, or "". */
+export declare function runInner(command: string, input: string): string;
+export interface RenderDeps {
+    stateDir: string;
+    inner?: string;
+    runInner?: (command: string, input: string) => string;
+}
+/** Claude Code's status JSON → the one status line. Never throws. */
+export declare function render(stdin: string, deps: RenderDeps): string;
+export interface UserStatusLine {
+    command: string;
+    padding?: number;
+}
+/**
+ * The statusLine Claude Code would use without us: the first settings file (highest
+ * precedence first) that sets one. Only a `command` statusLine can be wrapped.
+ */
+export declare function userStatusLine(cwd: string, configDir: string): UserStatusLine | null;
+/**
+ * Launch args + env that add the counter, or null when it should stay off: the opt-out
+ * env, or the user passing their own --settings (two would fight over precedence).
+ */
+export declare function statuslineLaunch(o: {
+    passthrough: readonly string[];
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    home?: string;
+    node: string;
+    bin: string;
+}): {
+    args: string[];
+    env: Record<string, string>;
+} | null;

package/dist/lib/statusline.js

@@ -0,0 +1,240 @@
+/**
+ * The `mnemom agent` status-bar savings counter: a Claude Code statusLine command that
+ * prints "mnemom saved ~$X this session".
+ *
+ * The number is the first-run look's estimator (first-run/backtest.ts), applied live to this
+ * session's own transcript: each request priced at API list prices, times the empirical
+ * curve's lower-bound saving rate for its original context. So the counter and the
+ * first-run screen always agree, and it rounds DOWN to the cent.
+ *
+ * Claude Code runs the command on every status update with its status JSON on stdin
+ * (session_id, transcript_path, …). It must be fast, so the transcript is read
+ * incrementally: per session, a state file (~/.mnemom/statusline/<session>.json, 0600)
+ * keeps each file's byte offset and each message id's contribution, and a tick reads at
+ * most MAX_BYTES_PER_TICK of new bytes (a big resumed session catches up over ticks).
+ *
+ * A user's own statusLine is never replaced: the launch passes it in
+ * MNEMOM_STATUSLINE_INNER, it runs with the same stdin, and our segment is appended.
+ * Read-only on every transcript; no network. It lives outside lib/first-run because it runs
+ * the user's own statusLine command, and the first-run code is held to spawning nothing.
+ */
+import { execSync } from "node:child_process";
+import { closeSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { origContext, parseUsageLine, rowCost, ruleRate } from "./first-run/backtest.js";
+import { parseJson } from "./first-run/lines.js";
+export const STATE_DIR = "statusline";
+export const MAX_BYTES_PER_TICK = 8 * 1024 * 1024;
+/** The launcher passes the user's own statusLine command here. */
+export const INNER_ENV = "MNEMOM_STATUSLINE_INNER";
+/** Set to 1 to launch without the counter. */
+export const NO_STATUSLINE_ENV = "MNEMOM_AGENT_NO_STATUSLINE";
+export const INNER_TIMEOUT_MS = 2000;
+export function freshState() {
+    return { v: 1, files: {}, ids: {}, actual: 0, saved: 0 };
+}
+/** The main transcript, then its subagent transcripts (sorted). */
+export function sessionFiles(transcriptPath) {
+    const dir = join(transcriptPath.replace(/\.jsonl$/, ""), "subagents");
+    let subs = [];
+    try {
+        subs = readdirSync(dir)
+            .filter((f) => f.endsWith(".jsonl"))
+            .sort()
+            .map((f) => join(dir, f));
+    }
+    catch {
+        /* no subagents */
+    }
+    return [transcriptPath, ...subs];
+}
+/**
+ * The complete lines of `path` from `offset`, at most `maxBytes` of them, and the offset
+ * after the last complete line. null: the file is unreadable or shorter than `offset`.
+ */
+export function readNewLines(path, offset, maxBytes) {
+    let fd;
+    try {
+        fd = openSync(path, "r");
+    }
+    catch {
+        return null;
+    }
+    try {
+        const size = fstatSync(fd).size;
+        if (size < offset)
+            return null;
+        const n = Math.min(size - offset, maxBytes);
+        if (n <= 0)
+            return { lines: [], next: offset };
+        const buf = Buffer.allocUnsafe(n);
+        const got = readSync(fd, buf, 0, n, offset);
+        const view = buf.subarray(0, got);
+        const last = view.lastIndexOf(0x0a);
+        // One line longer than the whole budget: skip past it rather than stall forever.
+        if (last === -1)
+            return { lines: [], next: got === maxBytes ? offset + got : offset };
+        const lines = [];
+        let start = 0;
+        for (let nl = view.indexOf(0x0a); nl !== -1 && nl <= last; nl = view.indexOf(0x0a, start)) {
+            lines.push(view.subarray(start, nl));
+            start = nl + 1;
+        }
+        return { lines, next: offset + last + 1 };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** Read what is new in the session's files into `st`. A file that shrank resets the count. */
+export function update(st, files, maxBytes = MAX_BYTES_PER_TICK) {
+    let budget = maxBytes;
+    for (const f of files) {
+        if (budget <= 0)
+            break;
+        const from = st.files[f] ?? 0;
+        const r = readNewLines(f, from, budget);
+        if (r === null) {
+            if (from > 0)
+                return update(freshState(), files, maxBytes);
+            continue;
+        }
+        budget -= r.next - from;
+        const subagent = f.includes("/subagents/");
+        r.lines.forEach((line, i) => {
+            const p = parseUsageLine(line, subagent);
+            if (!p)
+                return;
+            const key = p.id ?? `anon-${f}-${from}-${i}`;
+            const cost = rowCost(p.row);
+            const saved = ruleRate(origContext(p.row)).screen * cost;
+            const prev = st.ids[key];
+            if (prev) {
+                st.actual -= prev[0];
+                st.saved -= prev[1];
+            }
+            st.ids[key] = [cost, saved];
+            st.actual += cost;
+            st.saved += saved;
+        });
+        st.files[f] = r.next;
+    }
+    return st;
+}
+/** The segment, rounded DOWN to the cent and never below $0.00. */
+export function segment(saved) {
+    const cents = Math.max(Math.floor(saved * 100 + 1e-9), 0);
+    return `mnemom saved ~$${(cents / 100).toFixed(2)} this session`;
+}
+function statePath(stateDir, sessionId) {
+    return join(stateDir, `${sessionId.replace(/[^A-Za-z0-9_-]/g, "_")}.json`);
+}
+export function loadState(path) {
+    try {
+        const v = parseJson(readFileSync(path, "utf8"));
+        if (v && v.v === 1 && v.files && v.ids)
+            return v;
+    }
+    catch {
+        /* none yet */
+    }
+    return freshState();
+}
+export function saveState(path, st) {
+    mkdirSync(join(path, ".."), { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(st), { mode: 0o600 });
+    renameSync(tmp, path);
+}
+/** Run the user's own statusLine command with the same stdin; its first line, or "". */
+export function runInner(command, input) {
+    try {
+        const out = execSync(command, {
+            input,
+            encoding: "utf8",
+            timeout: INNER_TIMEOUT_MS,
+            stdio: ["pipe", "pipe", "ignore"],
+        });
+        return (out.split("\n")[0] ?? "").trimEnd();
+    }
+    catch {
+        return "";
+    }
+}
+/** Claude Code's status JSON → the one status line. Never throws. */
+export function render(stdin, deps) {
+    const innerOut = deps.inner ? (deps.runInner ?? runInner)(deps.inner, stdin) : "";
+    let seg = "mnemom";
+    try {
+        const d = parseJson(stdin);
+        const tp = typeof d?.transcript_path === "string" ? d.transcript_path : null;
+        const sid = typeof d?.session_id === "string" && d.session_id ? d.session_id : null;
+        if (tp && sid) {
+            const path = statePath(deps.stateDir, sid);
+            const st = update(loadState(path), sessionFiles(tp));
+            seg = segment(st.saved);
+            try {
+                saveState(path, st);
+            }
+            catch {
+                /* an unwritable state dir only means the next tick re-reads */
+            }
+        }
+    }
+    catch {
+        /* the counter never breaks the status bar */
+    }
+    return innerOut ? `${innerOut} · ${seg}` : seg;
+}
+/**
+ * The statusLine Claude Code would use without us: the first settings file (highest
+ * precedence first) that sets one. Only a `command` statusLine can be wrapped.
+ */
+export function userStatusLine(cwd, configDir) {
+    for (const p of [
+        join(cwd, ".claude", "settings.local.json"),
+        join(cwd, ".claude", "settings.json"),
+        join(configDir, "settings.json"),
+    ]) {
+        let d;
+        try {
+            d = parseJson(readFileSync(p, "utf8"));
+        }
+        catch {
+            continue;
+        }
+        const sl = d?.statusLine;
+        if (!sl || typeof sl !== "object")
+            continue;
+        if (sl.type !== "command" || typeof sl.command !== "string" || !sl.command)
+            return null;
+        return typeof sl.padding === "number"
+            ? { command: sl.command, padding: sl.padding }
+            : { command: sl.command };
+    }
+    return null;
+}
+const sq = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+/**
+ * Launch args + env that add the counter, or null when it should stay off: the opt-out
+ * env, or the user passing their own --settings (two would fight over precedence).
+ */
+export function statuslineLaunch(o) {
+    if (o.env[NO_STATUSLINE_ENV] === "1")
+        return null;
+    if (o.passthrough.some((a) => a === "--settings" || a.startsWith("--settings=")))
+        return null;
+    const configDir = o.env.CLAUDE_CONFIG_DIR || join(o.home ?? homedir(), ".claude");
+    const user = userStatusLine(o.cwd, configDir);
+    const statusLine = {
+        type: "command",
+        command: `${sq(o.node)} ${sq(o.bin)}`,
+    };
+    if (user?.padding !== undefined)
+        statusLine.padding = user.padding;
+    return {
+        args: ["--settings", JSON.stringify({ statusLine })],
+        env: user ? { [INNER_ENV]: user.command } : {},
+    };
+}

package/package.json

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