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

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

@@ -0,0 +1,108 @@
+/**
+ * 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.
+ *   - 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
+ *     headroom with a clearly labelled list-price equivalent. Pro / Max are not supported
+ *     by the gateway (lib/subscription-login.ts), so they are never given a figure.
+ *
+ * Read-only on every config dir. No network. Reads only the auth SHAPE of .claude.json
+ * (oauthAccount.{organizationType, seatTier, billingType, organizationUuid,
+ * hasExtraUsageEnabled} and the COUNT of approved API keys) — never a secret or identity.
+ */
+import type { Row } from "./backtest.js";
+import { Governance } from "./governed.js";
+export interface Session {
+    key: string;
+    sid: string;
+    /** The projects/ dir the session lives in. */
+    root: string;
+    /** The project dir name (Claude Code's encoded cwd). */
+    pdir: string;
+    top: string | null;
+    subs: string[];
+    cwd?: string | null;
+    entry?: string | null;
+    firstTs?: number | null;
+}
+export type BillingClass = "api" | "subscription_org" | "subscription_consumer" | "subscription_unknown_type" | "unknown";
+export interface ScopeResult {
+    roots: string[];
+    sessions: Map<string, Session>;
+    kept: Map<string, Session>;
+    excluded: Map<string, string[]>;
+}
+/** ~/.claude/projects and ~/.claude-*\/projects that exist (realpath, de-duplicated). */
+export declare function defaultProjectRoots(home?: string): string[];
+/** Every top-level transcript and subagent transcript under the roots, grouped by session. */
+export declare function discover(roots: readonly string[]): Map<string, Session>;
+export interface ClassifyOptions {
+    home?: string;
+    /** Exclude sessions that started before this (epoch s): the ledger cannot vouch for them. */
+    notBefore?: number | null;
+    progress?: (msg: string) => void;
+}
+/** Newest mtime (epoch s) across a session's files; 0 when none can be read. */
+export declare function newestMtime(s: Session): number;
+/** Only sessions with a file written at or after `since` can hold a request in the window. */
+export declare function touchedSince(sessions: Map<string, Session>, since: number): Map<string, Session>;
+/**
+ * Kept iff NO governed signal on any of the session's files and nothing makes us unsure.
+ * The same session id in several roots: if any copy is excluded, all are; else one is kept.
+ */
+export declare function classify(sessions: Map<string, Session>, gov: Governance, opts?: ClassifyOptions): {
+    kept: Map<string, Session>;
+    excluded: Map<string, string[]>;
+};
+/** organizationType values in Claude Code 2.1.285 (binary map: claude_team → team, …). */
+export declare const ORG_SEAT_TYPES: Set<string>;
+export declare const CONSUMER_TYPES: Set<string>;
+export interface AuthShape {
+    found: boolean;
+    oauth: boolean;
+    billingType: string | null;
+    orgType: string | null;
+    seat: string | null;
+    orgUuid: string | null;
+    extraUsage: boolean | null;
+    approvedKeys: number;
+}
+/** The auth SHAPE of a config dir's .claude.json (~/.claude → ~/.claude.json). */
+export declare function authShape(configDir: string, home?: string): AuthShape;
+/**
+ * How a session was billed, from evidence only:
+ *   - Cache-TTL signature (verified in Claude Code 2.1.285): without an override the main
+ *     thread writes 1-hour cache only under a claude.ai subscription login (reason
+ *     "subscriber"); an API key gets 5m. A main-thread 1h write + a subscription login =
+ *     subscription. 5m never proves API (a subscriber in overage also gets 5m).
+ *   - No login in the config dir + approved API key(s) = api.
+ *   - Anything else = unknown (no figure).
+ * The subscription KIND is the current login's ("current account, assumed"), except a
+ * Remote Control record naming a different organization, which makes it unknown.
+ */
+export declare function billingClass(session: Session, rows: readonly Row[], shape: AuthShape): {
+    cls: BillingClass;
+    why: string;
+};
+/** The Claude config dir holding a projects/ root. */
+export declare function configDirOf(root: string): string;
+/** A readable project label: the encoded cwd without the home prefix. */
+export declare function prettyProject(pdir: string): string;
+export interface BuildOptions extends ClassifyOptions {
+    roots?: string[];
+    mnemomDir?: string;
+    tmp?: string;
+    /** Only sessions with a file written at or after this (epoch s) are looked at. */
+    since?: number;
+    /** Ledger retention in days: a session older than that cannot be vouched for. */
+    retentionDays?: number;
+    now?: number;
+}
+export declare function buildScope(opts?: BuildOptions): ScopeResult & {
+    inWindow: number;
+};

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

@@ -0,0 +1,308 @@
+/**
+ * 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.
+ *   - 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
+ *     headroom with a clearly labelled list-price equivalent. Pro / Max are not supported
+ *     by the gateway (lib/subscription-login.ts), so they are never given a figure.
+ *
+ * Read-only on every config dir. No network. Reads only the auth SHAPE of .claude.json
+ * (oauthAccount.{organizationType, seatTier, billingType, organizationUuid,
+ * hasExtraUsageEnabled} and the COUNT of approved API keys) — never a secret or identity.
+ */
+import { readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { Governance } from "./governed.js";
+import { parseJson } from "./lines.js";
+function realOrNull(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return null;
+    }
+}
+function isDir(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function list(dir) {
+    try {
+        return readdirSync(dir).sort();
+    }
+    catch {
+        return [];
+    }
+}
+/** ~/.claude/projects and ~/.claude-*\/projects that exist (realpath, de-duplicated). */
+export function defaultProjectRoots(home = homedir()) {
+    const out = [];
+    const add = (p) => {
+        const rp = realOrNull(p);
+        if (rp && isDir(rp) && !out.includes(rp))
+            out.push(rp);
+    };
+    add(join(home, ".claude", "projects"));
+    for (const d of list(home)) {
+        if (d.startsWith(".claude-"))
+            add(join(home, d, "projects"));
+    }
+    return out;
+}
+/** Every top-level transcript and subagent transcript under the roots, grouped by session. */
+export function discover(roots) {
+    const sessions = new Map();
+    const get = (root, pdir, sid) => {
+        const key = `${root}\u0000${pdir}\u0000${sid}`;
+        let s = sessions.get(key);
+        if (!s) {
+            s = { key, sid, root, pdir, top: null, subs: [] };
+            sessions.set(key, s);
+        }
+        return s;
+    };
+    for (const root of roots) {
+        for (const pdir of list(root)) {
+            // A stray file under the root lists as empty (list() never throws).
+            const full = join(root, pdir);
+            for (const f of list(full)) {
+                const p = join(full, f);
+                if (f.endsWith(".jsonl")) {
+                    get(root, pdir, f.slice(0, -6)).top = p;
+                }
+                else if (isDir(join(p, "subagents"))) {
+                    for (const sub of walkJsonl(join(p, "subagents")))
+                        get(root, pdir, f).subs.push(sub);
+                }
+            }
+        }
+    }
+    return sessions;
+}
+function walkJsonl(dir, depth = 0) {
+    const out = [];
+    if (depth > 4)
+        return out;
+    for (const f of list(dir)) {
+        const p = join(dir, f);
+        if (f.endsWith(".jsonl"))
+            out.push(p);
+        else if (isDir(p))
+            out.push(...walkJsonl(p, depth + 1));
+    }
+    return out;
+}
+/** Newest mtime (epoch s) across a session's files; 0 when none can be read. */
+export function newestMtime(s) {
+    let m = 0;
+    for (const p of [s.top, ...s.subs]) {
+        if (!p)
+            continue;
+        try {
+            m = Math.max(m, statSync(p).mtimeMs / 1000);
+        }
+        catch {
+            /* unreadable: ignored */
+        }
+    }
+    return m;
+}
+/** Only sessions with a file written at or after `since` can hold a request in the window. */
+export function touchedSince(sessions, since) {
+    const out = new Map();
+    for (const [k, s] of sessions)
+        if (newestMtime(s) >= since)
+            out.set(k, s);
+    return out;
+}
+/**
+ * Kept iff NO governed signal on any of the session's files and nothing makes us unsure.
+ * The same session id in several roots: if any copy is excluded, all are; else one is kept.
+ */
+export function classify(sessions, gov, opts = {}) {
+    const home = opts.home ?? homedir();
+    const kept = new Map();
+    const excluded = new Map();
+    const bySid = new Map();
+    let i = 0;
+    for (const [key, s] of sessions) {
+        if (++i % 200 === 0)
+            opts.progress?.(`checking sessions ${i}/${sessions.size}`);
+        if (!s.top) {
+            excluded.set(key, ["no_parent_transcript"]);
+            continue;
+        }
+        const sigs = new Set();
+        const top = gov.classify(s.top);
+        top.signals.forEach((x) => sigs.add(x));
+        s.cwd = top.cwd;
+        s.entry = top.entrypoint;
+        s.firstTs = top.firstTs;
+        if (sigs.size === 0) {
+            for (const sub of s.subs) {
+                gov.classify(sub).signals.forEach((x) => sigs.add(x));
+                if (sigs.size)
+                    break;
+            }
+        }
+        if (top.entrypoint === "sdk-cli")
+            sigs.add("headless_unproven");
+        if (top.cwd && top.cwd.startsWith(join(home, ".pegasus") + "/")) {
+            sigs.add("pegasus_host_worktree");
+        }
+        if (opts.notBefore != null && (top.firstTs === null || top.firstTs < opts.notBefore)) {
+            sigs.add("before_ledger_retention");
+        }
+        const keys = bySid.get(s.sid) ?? [];
+        keys.push(key);
+        bySid.set(s.sid, keys);
+        if (sigs.size)
+            excluded.set(key, [...sigs].sort());
+        else
+            kept.set(key, s);
+    }
+    for (const keys of bySid.values()) {
+        if (keys.length < 2)
+            continue;
+        if (keys.some((k) => excluded.has(k))) {
+            for (const k of keys) {
+                if (kept.delete(k))
+                    excluded.set(k, ["duplicate_of_excluded_copy"]);
+            }
+        }
+        else {
+            for (const k of keys.slice(1)) {
+                kept.delete(k);
+                excluded.set(k, ["duplicate_copy"]);
+            }
+        }
+    }
+    return { kept, excluded };
+}
+// ── billing ──────────────────────────────────────────────────────────────────
+/** organizationType values in Claude Code 2.1.285 (binary map: claude_team → team, …). */
+export const ORG_SEAT_TYPES = new Set(["claude_team", "claude_enterprise"]);
+export const CONSUMER_TYPES = new Set(["claude_pro", "claude_max"]);
+/** The auth SHAPE of a config dir's .claude.json (~/.claude → ~/.claude.json). */
+export function authShape(configDir, home = homedir()) {
+    const isDefault = realOrNull(configDir) === realOrNull(join(home, ".claude"));
+    const p = isDefault ? join(home, ".claude.json") : join(configDir, ".claude.json");
+    let d;
+    try {
+        d = parseJson(readFileSync(p, "utf8"));
+    }
+    catch {
+        d = null;
+    }
+    if (!d) {
+        return {
+            found: false,
+            oauth: false,
+            billingType: null,
+            orgType: null,
+            seat: null,
+            orgUuid: null,
+            extraUsage: null,
+            approvedKeys: 0,
+        };
+    }
+    const oa = d.oauthAccount ?? {};
+    const str = (v) => (typeof v === "string" ? v : null);
+    const approved = d.customApiKeyResponses?.approved;
+    return {
+        found: true,
+        oauth: Object.keys(oa).length > 0,
+        billingType: str(oa.billingType),
+        orgType: str(oa.organizationType),
+        seat: str(oa.seatTier),
+        orgUuid: str(oa.organizationUuid),
+        extraUsage: typeof oa.hasExtraUsageEnabled === "boolean" ? oa.hasExtraUsageEnabled : null,
+        approvedKeys: Array.isArray(approved) ? approved.length : 0,
+    };
+}
+const RC_ORG = /"ownerOrganizationUuid"\s*:\s*"([0-9a-f-]{36})"/;
+function rcOrg(top) {
+    let text;
+    try {
+        text = readFileSync(top, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const m = RC_ORG.exec(text);
+    return m ? m[1] : null;
+}
+/**
+ * How a session was billed, from evidence only:
+ *   - Cache-TTL signature (verified in Claude Code 2.1.285): without an override the main
+ *     thread writes 1-hour cache only under a claude.ai subscription login (reason
+ *     "subscriber"); an API key gets 5m. A main-thread 1h write + a subscription login =
+ *     subscription. 5m never proves API (a subscriber in overage also gets 5m).
+ *   - No login in the config dir + approved API key(s) = api.
+ *   - Anything else = unknown (no figure).
+ * The subscription KIND is the current login's ("current account, assumed"), except a
+ * Remote Control record naming a different organization, which makes it unknown.
+ */
+export function billingClass(session, rows, shape) {
+    const main1h = rows.some((r) => r.cw1h > 0 && r.mainThread && !r.subagent);
+    if (shape.oauth && (shape.billingType ?? "").includes("subscription")) {
+        if (!main1h) {
+            return {
+                cls: "unknown",
+                why: "subscription login; no per-session evidence of how it was billed",
+            };
+        }
+        const cls = ORG_SEAT_TYPES.has(shape.orgType ?? "")
+            ? "subscription_org"
+            : CONSUMER_TYPES.has(shape.orgType ?? "")
+                ? "subscription_consumer"
+                : "subscription_unknown_type";
+        const rc = session.top ? rcOrg(session.top) : null;
+        if (rc && shape.orgUuid && rc !== shape.orgUuid) {
+            return { cls: "unknown", why: "Remote Control record names a different organization" };
+        }
+        const tie = rc && shape.orgUuid ? "Remote Control record matches the login" : "current account, assumed";
+        return {
+            cls,
+            why: `subscription login (${shape.orgType ?? "unknown type"}) and 1-hour main-thread cache writes; ${tie}`,
+        };
+    }
+    if (!shape.oauth && shape.approvedKeys > 0) {
+        return { cls: "api", why: "no subscription login in this config dir; approved API key(s)" };
+    }
+    return { cls: "unknown", why: "no per-session evidence of how it was billed" };
+}
+/** The Claude config dir holding a projects/ root. */
+export function configDirOf(root) {
+    return dirname(root);
+}
+/** A readable project label: the encoded cwd without the home prefix. */
+export function prettyProject(pdir) {
+    const n = pdir.replace(/^-+/, "");
+    const stripped = n.replace(/^Users-[^-]+-(?:git-)?/, "").replace(/^home-[^-]+-(?:git-)?/, "");
+    return stripped || basename(pdir);
+}
+export function buildScope(opts = {}) {
+    const home = opts.home ?? homedir();
+    const now = opts.now ?? Date.now() / 1000;
+    const roots = opts.roots ?? defaultProjectRoots(home);
+    const all = discover(roots);
+    const sessions = opts.since != null ? touchedSince(all, opts.since) : all;
+    opts.progress?.(`found ${sessions.size} recent sessions`);
+    const gov = new Governance({ home, mnemomDir: opts.mnemomDir, tmp: opts.tmp });
+    // With a ledger, anything older than its retention may have been pruned from it.
+    const notBefore = opts.notBefore ??
+        (gov.registryRows > 0 && opts.retentionDays ? now - opts.retentionDays * 86400 : null);
+    const { kept, excluded } = classify(sessions, gov, { ...opts, home, notBefore });
+    return { roots, sessions: all, kept, excluded, inWindow: sessions.size };
+}

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

@@ -0,0 +1,91 @@
+/**
+ * The first-run screen: one plain terminal screen (at most 16 lines of at most 78
+ * columns, ASCII) 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.
+ *
+ * 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.
+ *   - 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. */
+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;
+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).
+ */
+export declare const FORWARD_LINE = "Long sessions are where Mnemom saves the most: about 15 to 20% in our tests.";
+/** 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. */
+export declare function sig3(x: number): number;
+/**
+ * (total shown, saved shown, with-Mnemom shown) with total - saved === with EXACTLY on
+ * screen. The implied saving is the shown saving, which never exceeds the raw saving.
+ */
+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. */
+    actual: number;
+    /** The conservative saving on those requests (backtest.estimate). */
+    saved: number;
+}
+export interface Biggest {
+    label: string | null;
+    start: number;
+    end: 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;
+}
+export interface AuditEntry {
+    shown: unknown;
+    raw: unknown;
+    method: string;
+}
+export type Audit = Record<string, AuditEntry>;
+/** -> the screen lines and the audit of every number on them. */
+export declare function buildScreen(inp: ScreenInput): {
+    lines: string[];
+    audit: Audit;
+};