@mnemom/mnemom 0.17.33 → 0.17.34-next.1

package/dist/commands/agent-share-render.d.ts

@@ -1,7 +1,7 @@
 /**
  * Bridge from `mnemom agent share` to the aip verifier (`@mnemom/aip-verifier`, aip#192/#178):
  * the renderer (`renderLines`) and claim-lint (`lintRendering`) are the ONLY source of what a
- * card may say. No word lists live here. The package is a devDependency pinned to the aip
+ * card may say. No word lists live here. The package is a runtime dependency pinned to the aip
  * release tarball and is loaded lazily, so the default CLI path never touches it; if it is
  * absent at runtime the share command fails closed with a clear message.
  */

package/dist/commands/agent-share-render.js

@@ -1,7 +1,7 @@
 /**
  * Bridge from `mnemom agent share` to the aip verifier (`@mnemom/aip-verifier`, aip#192/#178):
  * the renderer (`renderLines`) and claim-lint (`lintRendering`) are the ONLY source of what a
- * card may say. No word lists live here. The package is a devDependency pinned to the aip
+ * card may say. No word lists live here. The package is a runtime dependency pinned to the aip
  * release tarball and is loaded lazily, so the default CLI path never touches it; if it is
  * absent at runtime the share command fails closed with a clear message.
  */

package/dist/commands/agent.d.ts

@@ -25,6 +25,8 @@
  * line, or the proxy's stdin under RC). It is never logged, printed, or passed as
  * an argv value.
  */
+import { type ChildProcess } from "node:child_process";
+import { type SessionKeyDeps, type SessionKeyMintArgs, type SessionKeyRenewal } from "../lib/session-key.js";
 import { type MnemomKeyDeps } from "../lib/subscription-login.js";
 import { type SessionRecord } from "../lib/agent-ledger.js";
 import { type ExperimentalId } from "../lib/experimental.js";
@@ -447,6 +449,19 @@ export declare function rcProxyUrl(port: string, proxyCredential: string): strin
  * selectLaunchAgent). A truncated/garbled `mnm-…` throws instead of becoming a name.
  */
 export declare function resolveLaunchPin(options: Pick<AgentOptions, "agent" | "agentId">): string | undefined;
+/** The longest line the proxy sends the launcher (`remint <key id>`) is far shorter than this. */
+export declare const RC_CONTROL_LINE_MAX = 1024;
+/**
+ * Renew the Remote Control proxy's session key over its control pipe (fd 3; rc-proxy.mjs SESSION
+ * KEY RENEWAL): a `key <id> <expires> <key>` line before each expiry, a `remint <id>` line from the
+ * proxy when the gateway rejects its key, answered with a new key or `key-failed`. Renewal events
+ * go to the proxy log (the terminal belongs to Claude Code by then), as key ids and expiry times.
+ */
+export declare function startRcSessionKeyRenewal(proxy: Pick<ChildProcess, "stdio">, proxyLog: string, initial: {
+    keyId: string;
+    expiresAt: string;
+    mintArgs: SessionKeyMintArgs;
+}, makeDeps?: (say: (line: string) => void) => SessionKeyDeps): SessionKeyRenewal | undefined;
 /**
  * Locates the `handoff` MCP server (src/mcp/handoff-server.mjs in dev, dist/mcp/handoff-server.mjs
  * once built — a raw, uncompiled `.mjs` file that `copy-assets.mjs` copies verbatim, exactly like

package/dist/commands/agent.js

@@ -26,7 +26,7 @@
  * an argv value.
  */
 import { spawn, spawnSync } from "node:child_process";
-import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, renameSync, } from "node:fs";
+import { appendFileSync, chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, renameSync, } from "node:fs";
 import { randomBytes, randomUUID } from "node:crypto";
 import { tmpdir, homedir, hostname } from "node:os";
 import { basename, join, dirname } from "node:path";
@@ -39,7 +39,7 @@ import { ALLOW_AUTOCOMPACT_OFF_ENV, dropAutocompactOffEnv, hasOwnSettingsFlag, m
 import { getApiUrl, getGatewayUrl, MNEMOM_DIR } from "../lib/config.js";
 import { createApiKey } from "../lib/api.js";
 import { recordOrgFor } from "../lib/record-org.js";
-import { defaultSessionKeyDeps, mintSessionGatewayKey, revokeSessionGatewayKey, } from "../lib/session-key.js";
+import { defaultSessionKeyDeps, mintSessionGatewayKey, revokeSessionGatewayKey, startSessionKeyRenewal, } from "../lib/session-key.js";
 import { MNEMOM_KEY_STORE_FIELD, resolveAgentAuth, sayRetiredConsoleNotice, readMnemomKey, resolveSubscriptionMnemomKey, subscriptionChildEnv, subscriptionShape, } from "../lib/subscription-login.js";
 import { LEDGER_FILE, appendSessionRecord, findResumeCandidate, readSessionRecords, resolveRetentionDays, resumedContextProfile, toLedgerContract, } from "../lib/agent-ledger.js";
 import { isLoggedIn } from "../lib/auth.js";
@@ -612,6 +612,8 @@ export async function agentCommand(scenarioArg, options = {}) {
     // org is the key owner's personal org, where the agent does not exist, so the API answers 404
     // and the launch would fail closed (door1-path run 40400479127). Same read as Record's.
     let sessionKeyId;
+    // What a Remote Control launch needs to re-mint before the 24h expiry (startSessionKeyRenewal).
+    let sessionKeyRenewal;
     // One read of the served agent's org serves the mint and Record; each says why in its own
     // words when the read fails and the account org is used instead.
     let servedOrg;
@@ -632,13 +634,15 @@ export async function agentCommand(scenarioArg, options = {}) {
                 say(fmt.warn(`mnemom agent: could not read ${servedAgentId}'s org (${o.fallback}); minting the session key under ${account.orgId}.`));
             mintOrgId = o.orgId;
         }
-        const minted = await mintSessionGatewayKey(defaultSessionKeyDeps(say), {
+        const mintArgs = {
             agentId: servedAgentId,
             orgId: mintOrgId,
             sessionId: cc.id ?? undefined,
-        });
+        };
+        const minted = await mintSessionGatewayKey(defaultSessionKeyDeps(say), mintArgs);
         mnemomKey = minted.key;
         sessionKeyId = minted.keyId;
+        sessionKeyRenewal = { expiresAt: minted.expiresAt, mintArgs };
     }
     // ── 1M context window by default ── the model this launch runs on gets `[1m]` when it has no
     // window suffix and supports 1M (resolveWindowModel); an explicit choice — the
@@ -828,6 +832,7 @@ export async function agentCommand(scenarioArg, options = {}) {
         yolo,
         ccSessionId,
         sessionKeyId,
+        sessionKeyRenewal,
     });
 }
 // ───────────────────────────────────────────────────────────────────────────
@@ -1688,13 +1693,28 @@ function launchRemoteControl(ctx) {
         MNEMOM_AGENT_RC_PARENT_PID: String(process.pid),
         MNEMOM_AGENT_RC_AUTH: ctx.anthropicKey ? "api-key" : "subscription",
     };
+    // The minted key expires after 24h and an RC seat outlives that: renew it over a control pipe
+    // (fd 3) — the new key never touches argv, env or disk. Only its id and expiry ride in the env.
+    const renewing = Boolean(ctx.sessionKeyId && ctx.sessionKeyRenewal && ctx.mnemomKey);
+    if (renewing) {
+        proxyEnv.MNEMOM_AGENT_RC_CONTROL_FD = "3";
+        proxyEnv.MNEMOM_AGENT_RC_MNEMOM_KEY_ID = ctx.sessionKeyId;
+        proxyEnv.MNEMOM_AGENT_RC_MNEMOM_KEY_EXPIRES_AT = ctx.sessionKeyRenewal?.expiresAt;
+    }
     // MNE-8245 defense-in-depth: the proxy gets the session's (minted) Mnemom key on stdin only
     // and reads none of the owner's own Mnemom credential vars, so they never ride into its env.
     stripOwnerCredentialEnv(proxyEnv);
     const proxy = spawn("node", [proxyScript], {
         env: proxyEnv,
-        stdio: ["pipe", "pipe", "inherit"],
+        stdio: ["pipe", "pipe", "inherit", renewing ? "pipe" : "ignore"],
     });
+    const renewal = renewing
+        ? startRcSessionKeyRenewal(proxy, proxyLog, {
+            keyId: ctx.sessionKeyId,
+            expiresAt: ctx.sessionKeyRenewal?.expiresAt,
+            mintArgs: ctx.sessionKeyRenewal?.mintArgs,
+        })
+        : undefined;
     let stopped = false;
     const stopProxyAndTempDir = () => {
         if (!proxy.killed) {
@@ -1721,9 +1741,12 @@ function launchRemoteControl(ctx) {
         if (stopped)
             return;
         stopped = true;
+        renewal?.stop();
         stopProxyAndTempDir();
-        if (ctx.sessionKeyId) {
-            await revokeSessionGatewayKey(defaultSessionKeyDeps(say), ctx.sessionKeyId);
+        // After a renewal the proxy holds a newer key than the one minted at launch: revoke that one.
+        const keyId = renewal?.currentKeyId() ?? ctx.sessionKeyId;
+        if (keyId) {
+            await revokeSessionGatewayKey(defaultSessionKeyDeps(say), keyId);
         }
     };
     // Last-resort SYNC fallback only — Node's "exit" handlers cannot await, so this branch never
@@ -1736,6 +1759,7 @@ function launchRemoteControl(ctx) {
         if (stopped)
             return;
         stopped = true;
+        renewal?.stop();
         stopProxyAndTempDir();
     });
     // Secrets on stdin — four lines (anthropic, mnemom, openai, proxy credential). An api-key launch
@@ -1793,6 +1817,58 @@ function launchRemoteControl(ctx) {
     });
     tryStart();
 }
+/** The longest line the proxy sends the launcher (`remint <key id>`) is far shorter than this. */
+export const RC_CONTROL_LINE_MAX = 1024;
+/**
+ * Renew the Remote Control proxy's session key over its control pipe (fd 3; rc-proxy.mjs SESSION
+ * KEY RENEWAL): a `key <id> <expires> <key>` line before each expiry, a `remint <id>` line from the
+ * proxy when the gateway rejects its key, answered with a new key or `key-failed`. Renewal events
+ * go to the proxy log (the terminal belongs to Claude Code by then), as key ids and expiry times.
+ */
+export function startRcSessionKeyRenewal(proxy, proxyLog, initial, makeDeps = defaultSessionKeyDeps) {
+    const control = proxy.stdio?.[3];
+    if (!control)
+        return undefined;
+    const logLine = (line) => {
+        try {
+            appendFileSync(proxyLog, `${new Date().toISOString()} launcher: ${line}\n`);
+        }
+        catch {
+            /* best effort: the log dir may be gone at exit */
+        }
+    };
+    control.on("error", () => {
+        /* the proxy exited: the next delivery fails and is logged */
+    });
+    const renewal = startSessionKeyRenewal({
+        deps: makeDeps(logLine),
+        mintArgs: initial.mintArgs,
+        initial: { keyId: initial.keyId, expiresAt: initial.expiresAt },
+        deliver: (minted) => {
+            if (control.destroyed || !control.writable)
+                throw new Error("the proxy's control pipe is closed");
+            control.write(`key ${minted.keyId} ${minted.expiresAt} ${minted.key}\n`);
+        },
+        refuse: (reason) => {
+            if (!control.destroyed && control.writable)
+                control.write(`key-failed ${reason}\n`);
+        },
+    });
+    let buf = "";
+    control.on("data", (chunk) => {
+        buf += chunk.toString("utf8");
+        let i;
+        while ((i = buf.indexOf("\n")) >= 0) {
+            const [cmd, keyId] = buf.slice(0, i).split(" ");
+            buf = buf.slice(i + 1);
+            if (cmd === "remint")
+                void renewal.renew("rejected", keyId);
+        }
+        if (buf.length > RC_CONTROL_LINE_MAX)
+            buf = ""; // a runaway line, never a real request
+    });
+    return renewal;
+}
 function spawnRcCli(ctx) {
     // Session name for the claude.ai session list: "<agent>-<scenario>", unless
     // the caller passed their own name after `--` (`--name x`, `--name=x`, `-n x`; lifted out here).

package/dist/commands/protection.js

@@ -15,7 +15,7 @@ const OP_SEVERITIES = ["low", "medium", "high", "critical"];
 // Per ADR-037 Decision 4: deny public LLM endpoints + public DNS providers,
 // and the any-host CIDRs, at write time.
 // T8-4 (2026-05-19) extended the corpus per
-// `safe-house-hardening/audit/deny-list-completeness.md`: added emerging
+// `safe-house-hardening/audits/deny-list-completeness.md`: added emerging
 // LLM providers (Replicate, Together, Anyscale, Fireworks, xAI,
 // Perplexity, DeepSeek) and three reserved IP ranges (link-local v4/v6
 // + multicast v4).

package/dist/commands/scan.d.ts

@@ -0,0 +1,97 @@
+/**
+ * `mnemom scan`: a read-only local scan of GitHub PR metadata. Runs entirely on this machine; nothing is
+ * uploaded in this build. The share-level prompt gates what a later upload step may send, and the chosen
+ * payload is printed so the user sees exactly what would leave. Pure logic is exported so each reject
+ * arm is unit-testable without Commander (same pattern as commands/usage.ts).
+ */
+import { type GitHubCredential } from "../lib/scan/credential.js";
+import { type ScanDeps } from "../lib/scan/scan.js";
+import { type AnthropicUsageDeps } from "../lib/scan/spend/anthropic-usage.js";
+import { type RecordDeps, type RecordOutcome } from "../lib/scan/record.js";
+import { type ReportEmailDeps } from "../lib/scan/report-email.js";
+import { type ReportRecipients } from "../lib/scan/share.js";
+export interface ScanCommandOptions {
+    repos: string[];
+    period?: {
+        start: string;
+        end: string;
+    };
+    share?: string;
+    /** Report recipient. Required unless the runner is the CTO (asked when omitted). */
+    ctoEmail?: string;
+    /** Tier 2: the CTO's own monthly figure, as typed. Needs MNEMOM_ORG_SCAN_MODE=true. */
+    monthlySpend?: string;
+    /** Tier 2 without a figure on the command line: ask for one on the terminal. */
+    noAnthropicUsage?: boolean;
+    /** Tier 1: ask for the Anthropic admin key on the terminal (masked). Otherwise ANTHROPIC_ADMIN_KEY is used if set. */
+    anthropicAdminKey?: boolean;
+    /** Tier 1 result, when the caller already has it (test seam; set from the Anthropic reads otherwise). */
+    anthropicUsageUsd?: number;
+    anthropicOver200kShare?: number | null;
+    /** Test seam: the fetch behind the two Anthropic reads. */
+    anthropicDeps?: AnthropicUsageDeps;
+    /**
+     * The org the report is emailed for; inferred from the signed-in user's single non-personal org when
+     * omitted (see resolveScanOrg). The Record totals preview (MNEMOM_ORG_SCAN_MODE=true) reads ONLY an
+     * org passed explicitly here, never an inferred one: a guess could read the wrong org.
+     */
+    org?: string;
+    /** Test seam: the Record read. */
+    recordDeps?: RecordDeps;
+    /** Test seam: the report-email POST. */
+    emailDeps?: ReportEmailDeps;
+    /** Test seam: the signed-in user's orgs, used to infer --org when it is omitted. */
+    listOrgs?: () => Promise<Array<{
+        org_id: string;
+        name?: string;
+        is_personal?: boolean;
+    }>>;
+    /** Test seams. */
+    isTty?: boolean;
+    env?: NodeJS.ProcessEnv;
+    runnerEmail?: string;
+    credential?: GitHubCredential;
+    deps?: Partial<ScanDeps>;
+    now?: () => number;
+}
+/** Parses repeated/comma-separated `--repo owner/name`. Returns null on any invalid slug. */
+export declare function parseRepoFlags(raw: string[] | undefined): string[] | null;
+export declare const isEmail: (v: unknown) => v is string;
+/** The runner's email (mnemom login, else asked) and the CTO's (flag, else "are you the CTO?"). */
+export declare function resolveRecipients(o: {
+    runnerEmail?: string;
+    ctoEmail?: string;
+}): Promise<ReportRecipients>;
+/** The CTO's figure in USD, or null for none. Throws fixed text only; the input is never echoed. */
+export declare function resolveSelfReportedSpend(o: ScanCommandOptions): Promise<number | null>;
+export declare const NO_ADMIN_KEY_TERMINAL_MSG = "Set ANTHROPIC_ADMIN_KEY (there is no terminal to ask on).";
+export declare const TIER1_FALLBACK_NOTE = "Tier 1 skipped: falling back to the next tier.";
+/**
+ * Tier 1: read measured usage with the CTO's Anthropic admin key, locally. The key comes from
+ * ANTHROPIC_ADMIN_KEY or a masked prompt (--anthropic-admin-key; never a value on argv), lives only in this
+ * call, and goes only to api.anthropic.com. Returns null for "no key" and for every failure, after printing a
+ * fixed sentence: the key, the thrown value and the response never reach the terminal. The caller then falls
+ * back to tier 2, then tier 3.
+ */
+export declare function resolveMeasuredUsage(o: ScanCommandOptions, period: {
+    start: string;
+    end: string;
+}): Promise<{
+    usd: number;
+    over200kShare: number | null;
+} | null>;
+/**
+ * --org is optional only because it can be inferred: the report is emailed on every scan, so the scan
+ * needs an org. Inference uses the signed-in user's own memberships (GET /v1/orgs, personal org
+ * excluded): exactly one org is used; none, several, or a failed read stops the scan loudly BEFORE any
+ * scan work, naming the fix. It never guesses between orgs and never skips the email.
+ */
+export declare function resolveScanOrg(o: ScanCommandOptions): Promise<string>;
+export declare const INVALID_ORG_MSG = "--org must be an org id like org-1a2b3c4d.";
+/**
+ * The Record read for the preview: null when the flag gate is off (no read, no output, as before).
+ * With the gate on and no --org it is a note, not a guess. 404 becomes a note; 401/403 throw
+ * RecordAuthError (fail closed); every other failure becomes a fixed note. Nothing is stored.
+ */
+export declare function resolveRecordOutcome(o: ScanCommandOptions): Promise<RecordOutcome | "no_org" | null>;
+export declare function scanCommand(o: ScanCommandOptions): Promise<void>;

package/dist/commands/scan.js

@@ -0,0 +1,238 @@
+/**
+ * `mnemom scan`: a read-only local scan of GitHub PR metadata. Runs entirely on this machine; nothing is
+ * uploaded in this build. The share-level prompt gates what a later upload step may send, and the chosen
+ * payload is printed so the user sees exactly what would leave. Pure logic is exported so each reject
+ * arm is unit-testable without Commander (same pattern as commands/usage.ts).
+ */
+import { isValidRepoSlug, resolveCredential, } from "../lib/scan/credential.js";
+import { failureText } from "../lib/scan/failure.js";
+import { runLocalScan } from "../lib/scan/scan.js";
+import { askInput, askSelect } from "../lib/prompt.js";
+import { isSpendTiersEnabled, NOT_ENABLED_MSG, parseMonthlySpendUsd, selectSpend, SPEND_INVALID_MSG, SPEND_NO_TERMINAL_MSG, } from "../lib/scan/spend/spend-tiers.js";
+import { ADMIN_KEY_ENV, AnthropicUsageError, fetchMeasuredUsage, isAdminKeyShape, usageFailureText, } from "../lib/scan/spend/anthropic-usage.js";
+import { getAuthInfo } from "../lib/auth.js";
+import { listMyOrgs } from "../lib/api.js";
+import { fetchRecordTotals, isOrgId, } from "../lib/scan/record.js";
+import { RECORD_NO_ORG_NOTE, renderRecordSection } from "../lib/scan/report.js";
+import { buildEmailBody, buildEmailReport, DRY_RUN_MSG, UNAVAILABLE_MSG, failureMessage, ReportEmailError, sendReportEmail, } from "../lib/scan/report-email.js";
+import { buildSharePayload, parseShareLevel, promptShareLevel, } from "../lib/scan/share.js";
+/** Parses repeated/comma-separated `--repo owner/name`. Returns null on any invalid slug. */
+export function parseRepoFlags(raw) {
+    const out = (raw ?? [])
+        .flatMap((r) => r.split(","))
+        .map((r) => r.trim())
+        .filter(Boolean);
+    return out.length > 0 && out.every(isValidRepoSlug) ? out : null;
+}
+const EMAIL = /^[^\s@]{1,64}@[^\s@]{1,255}\.[^\s@]{2,63}$/;
+export const isEmail = (v) => typeof v === "string" && v.length <= 320 && EMAIL.test(v.trim());
+/** The runner's email (mnemom login, else asked) and the CTO's (flag, else "are you the CTO?"). */
+export async function resolveRecipients(o) {
+    if (o.ctoEmail !== undefined && !isEmail(o.ctoEmail))
+        throw new Error("--cto-email must be a valid email address");
+    let runner = o.runnerEmail ?? getAuthInfo()?.email ?? "";
+    if (!isEmail(runner))
+        runner = (await askInput("Your email (the report is sent to you):")).trim();
+    if (!isEmail(runner))
+        throw new Error("a valid runner email is required");
+    runner = runner.trim();
+    if (o.ctoEmail !== undefined)
+        return { runner_email: runner, cto_email: o.ctoEmail.trim() };
+    const isCto = await askSelect("Are you the CTO?", ["Yes, I am the CTO", "No, someone else is"]);
+    if (isCto === null)
+        throw new Error("--cto-email is required when you are not the CTO");
+    if (isCto.startsWith("Yes"))
+        return { runner_email: runner, cto_email: runner };
+    const cto = (await askInput("CTO email (the report is sent to them too):")).trim();
+    if (!isEmail(cto))
+        throw new Error("--cto-email is required when you are not the CTO");
+    return { runner_email: runner, cto_email: cto };
+}
+/** The CTO's figure in USD, or null for none. Throws fixed text only; the input is never echoed. */
+export async function resolveSelfReportedSpend(o) {
+    if (o.monthlySpend === undefined && !o.noAnthropicUsage)
+        return null;
+    if (!isSpendTiersEnabled(o.env))
+        throw new Error(NOT_ENABLED_MSG);
+    let text = o.monthlySpend;
+    if (text === undefined) {
+        if (!(o.isTty ?? process.stdin.isTTY))
+            throw new Error(SPEND_NO_TERMINAL_MSG);
+        text = await askInput("Approximate monthly AI spend in USD (blank to skip; kept in memory only):");
+        if (text.trim() === "")
+            return null;
+    }
+    const n = parseMonthlySpendUsd(text);
+    if (n === null)
+        throw new Error(SPEND_INVALID_MSG);
+    return n;
+}
+export const NO_ADMIN_KEY_TERMINAL_MSG = "Set ANTHROPIC_ADMIN_KEY (there is no terminal to ask on).";
+export const TIER1_FALLBACK_NOTE = "Tier 1 skipped: falling back to the next tier.";
+/**
+ * Tier 1: read measured usage with the CTO's Anthropic admin key, locally. The key comes from
+ * ANTHROPIC_ADMIN_KEY or a masked prompt (--anthropic-admin-key; never a value on argv), lives only in this
+ * call, and goes only to api.anthropic.com. Returns null for "no key" and for every failure, after printing a
+ * fixed sentence: the key, the thrown value and the response never reach the terminal. The caller then falls
+ * back to tier 2, then tier 3.
+ */
+export async function resolveMeasuredUsage(o, period) {
+    if (o.anthropicAdminKey && !isSpendTiersEnabled(o.env))
+        throw new Error(NOT_ENABLED_MSG);
+    if (!isSpendTiersEnabled(o.env) || o.noAnthropicUsage)
+        return null;
+    // An explicit typed figure is the user's choice of tier 2: an ambient env key must not override it.
+    if (o.monthlySpend !== undefined && !o.anthropicAdminKey)
+        return null;
+    let key = (o.env ?? process.env)[ADMIN_KEY_ENV];
+    if (o.anthropicAdminKey) {
+        if (!(o.isTty ?? process.stdin.isTTY))
+            throw new Error(NO_ADMIN_KEY_TERMINAL_MSG);
+        key = await askInput("Anthropic admin key (kept in memory only, sent only to Anthropic):", true);
+    }
+    if (key === undefined || key.trim() === "")
+        return null;
+    if (!isAdminKeyShape(key)) {
+        console.log(usageFailureText("key_invalid"));
+        console.log(TIER1_FALLBACK_NOTE);
+        return null;
+    }
+    try {
+        return await fetchMeasuredUsage(key, period, o.anthropicDeps);
+    }
+    catch (e) {
+        console.log(usageFailureText(e instanceof AnthropicUsageError ? e.reason : "upstream"));
+        console.log(TIER1_FALLBACK_NOTE);
+        return null;
+    }
+}
+/**
+ * --org is optional only because it can be inferred: the report is emailed on every scan, so the scan
+ * needs an org. Inference uses the signed-in user's own memberships (GET /v1/orgs, personal org
+ * excluded): exactly one org is used; none, several, or a failed read stops the scan loudly BEFORE any
+ * scan work, naming the fix. It never guesses between orgs and never skips the email.
+ */
+export async function resolveScanOrg(o) {
+    if (o.org !== undefined) {
+        if (!isOrgId(o.org))
+            throw new Error(INVALID_ORG_MSG);
+        return o.org;
+    }
+    let orgs;
+    try {
+        orgs = (await (o.listOrgs ?? listMyOrgs)()).filter((x) => !x.is_personal);
+    }
+    catch {
+        throw new Error("Could not look up your org to email the report to. Sign in with `mnemom login`, or pass --org <org_id>.");
+    }
+    if (orgs.length === 1 && isOrgId(orgs[0].org_id))
+        return orgs[0].org_id;
+    if (orgs.length === 0)
+        throw new Error("You belong to no organization, so the report has nowhere to be emailed from. Pass --org <org_id>.");
+    throw new Error(`You belong to ${orgs.length} organizations; pass --org <org_id> (${orgs.map((x) => x.org_id).join(", ")}).`);
+}
+export const INVALID_ORG_MSG = "--org must be an org id like org-1a2b3c4d.";
+/**
+ * The Record read for the preview: null when the flag gate is off (no read, no output, as before).
+ * With the gate on and no --org it is a note, not a guess. 404 becomes a note; 401/403 throw
+ * RecordAuthError (fail closed); every other failure becomes a fixed note. Nothing is stored.
+ */
+export async function resolveRecordOutcome(o) {
+    if (!isSpendTiersEnabled(o.env))
+        return null;
+    if (o.org === undefined)
+        return "no_org";
+    if (!isOrgId(o.org))
+        throw new Error(INVALID_ORG_MSG);
+    return fetchRecordTotals(o.org, o.recordDeps);
+}
+export async function scanCommand(o) {
+    if (o.share !== undefined && parseShareLevel(o.share) === null) {
+        throw new Error("--share must be one of: summary, full, none");
+    }
+    if (o.repos.length === 0)
+        throw new Error("--repo owner/name is required (repeatable)");
+    // The report is emailed on every scan, so resolve the org before any scan work; failure is loud.
+    const emailOrg = await resolveScanOrg(o);
+    if (o.ctoEmail !== undefined && !isEmail(o.ctoEmail))
+        throw new Error("--cto-email must be a valid email address");
+    const selfReported = await resolveSelfReportedSpend(o);
+    const now = o.now ?? Date.now;
+    const end = new Date(now()).toISOString().slice(0, 10);
+    const period = o.period ?? { start: end, end };
+    const measured = await resolveMeasuredUsage(o, period);
+    const credential = o.credential ?? (await resolveCredential().catch(() => null));
+    if (!credential)
+        throw new Error(failureText("credential"));
+    // Before the local scan: a refused credential fails closed without spending the GitHub reads.
+    const record = await resolveRecordOutcome(o);
+    const outcome = await runLocalScan({ credential, now, ...o.deps }, { repos: o.repos, period });
+    if (outcome.status === "withheld")
+        throw new Error(`Scan withheld: ${failureText(outcome.reason)}`);
+    const { result } = outcome;
+    console.log("Local scan (read-only)");
+    console.log(`PRs examined: ${result.totals.examined} of ${result.totals.prs} merged (${result.coverage.windowStart} to ${result.coverage.windowEnd})`);
+    console.log(`Coverage: ${result.coverage.complete ? "complete" : `partial${result.coverage.stoppedBy ? ` (stopped by ${result.coverage.stoppedBy})` : ""}`}`);
+    // Flag off: the line as before. Flag on: the tier chosen, or no line at all when evidence is thin.
+    const tiers = isSpendTiersEnabled(o.env);
+    const spend = tiers
+        ? selectSpend({
+            measuredUsd: measured?.usd ?? o.anthropicUsageUsd,
+            over200kShare: measured ? measured.over200kShare : o.anthropicOver200kShare,
+            selfReportedUsd: selfReported,
+            estimate: result.spend,
+        })
+        : null;
+    const spendLine = spend ? spend.line : result.spend.line;
+    if (spendLine !== null)
+        console.log(spendLine);
+    if (record === "no_org")
+        console.log(RECORD_NO_ORG_NOTE);
+    else if (record !== null)
+        for (const line of renderRecordSection(record))
+            console.log(line);
+    const level = parseShareLevel(o.share) ?? (await promptShareLevel());
+    // Every successful scan emails the report to the person who ran it, at every share level, no opt-out.
+    // Mnemom keeps nothing from a share=none send (the server sends the email and does nothing else).
+    const emailFailure = await emailReport(o, emailOrg, result, level, period, spend);
+    if (level === "none") {
+        console.log("Share level: nothing. No share payload is built; Mnemom keeps nothing (the report email is only sent to you).");
+        if (emailFailure)
+            throw new ReportEmailError(emailFailure);
+        return;
+    }
+    const payload = buildSharePayload(level, result, await resolveRecipients(o), spend ? (spend.shareable ? spend.line : null) : undefined);
+    console.log(`Share level: ${level}. Upload is not wired in this build; this is what would be sent:`);
+    console.log(JSON.stringify(payload, null, 2));
+    if (emailFailure)
+        throw new ReportEmailError(emailFailure);
+}
+/**
+ * Emails the report. Loud on every failure: prints the reason name, never the server's words, and
+ * returns it so the caller exits non-zero after the local report is shown.
+ */
+async function emailReport(o, org, result, level, period, spend) {
+    const fail = (f) => {
+        console.log(failureMessage(f));
+        return f;
+    };
+    const report = buildEmailReport(result, {
+        orgId: org,
+        period,
+        now: o.now ?? Date.now,
+        sendSpendRange: spend ? spend.shareable && spend.tier === 3 : true,
+    });
+    const body = buildEmailBody(report, level, result.coverage.complete, o.ctoEmail?.trim());
+    const outcome = await sendReportEmail(org, body, o.emailDeps);
+    if (outcome.status === "failed")
+        return fail(outcome.reason);
+    if (outcome.status === "unavailable") {
+        // Org Scan is off by default: the gate's 404 is not a failure and must not break the scan.
+        console.log(UNAVAILABLE_MSG);
+        return null;
+    }
+    console.log(outcome.status === "dry_run"
+        ? DRY_RUN_MSG
+        : `Report emailed to you (${outcome.recipients} recipient${outcome.recipients === 1 ? "" : "s"}).`);
+    return null;
+}

package/dist/index.js

@@ -49,6 +49,7 @@ import { wrapCommand } from "./commands/wrap.js";
 import { onboardCommand } from "./commands/onboard.js";
 import { skillsListCommand, skillsDescribeCommand } from "./commands/skills.js";
 import { usageCommand, parseNumericFlag, parseDaysFlag } from "./commands/usage.js";
+import { scanCommand, parseRepoFlags } from "./commands/scan.js";
 import { updateCommand } from "./commands/update.js";
 import { runAction } from "./lib/update/action.js";
 import { configListCommand, configGetCommand, configSetCommand, configUnsetCommand, } from "./commands/config.js";
@@ -2196,6 +2197,40 @@ program
         process.exit(1);
     }
 });
+program
+    .command("scan")
+    .description("Read-only local scan of GitHub PR metadata; the report is emailed to you every time (counts only, no repo names) and Mnemom keeps nothing at share level none")
+    .option("--repo <owner/name...>", "Repo to scan (repeatable or comma-separated)")
+    .option("--start <YYYY-MM-DD>", "Period start (default: today)")
+    .option("--end <YYYY-MM-DD>", "Period end (default: today)")
+    .option("--share <level>", "summary | full | none (default: ask)")
+    .option("--cto-email <email>", "CTO who receives the report (required unless you are the CTO; asked when omitted)")
+    .option("--monthly-spend <usd>", "Your own approximate monthly AI spend (self-reported; never sent or saved; needs MNEMOM_ORG_SCAN_MODE=true)")
+    .option("--anthropic-admin-key", "Ask (masked) for your Anthropic admin key and read measured usage with it, locally; or set ANTHROPIC_ADMIN_KEY. Never stored, logged or sent anywhere but api.anthropic.com (needs MNEMOM_ORG_SCAN_MODE=true)")
+    .option("--no-anthropic-usage", "Decline Anthropic usage and be asked for a monthly figure (needs MNEMOM_ORG_SCAN_MODE=true)")
+    .option("--org <org_id>", "Your org id; the report is emailed to you for this org (default: your only organization, else the scan stops and asks). Also selects the Record totals preview (needs MNEMOM_ORG_SCAN_MODE=true)")
+    .action(async (options) => {
+    try {
+        const repos = parseRepoFlags(options.repo);
+        if (!repos)
+            throw new Error("--repo owner/name is required (repeatable)");
+        const today = new Date().toISOString().slice(0, 10);
+        await scanCommand({
+            repos,
+            period: { start: options.start ?? options.end ?? today, end: options.end ?? today },
+            share: options.share,
+            ctoEmail: options.ctoEmail,
+            monthlySpend: options.monthlySpend,
+            noAnthropicUsage: options.anthropicUsage === false,
+            anthropicAdminKey: options.anthropicAdminKey === true,
+            org: options.org,
+        });
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : "scan failed");
+        process.exit(1);
+    }
+});
 // ============================================================================
 // update + config — CLI auto-update (channel latest|next, mode auto|notify|off)
 //

package/dist/lib/api.d.ts

@@ -450,6 +450,19 @@ export interface RecordTotals {
     row_count: number;
 }
 export declare function getRecordTotals(orgId: string, lineageKey: string, signal?: AbortSignal): Promise<RecordTotals>;
+/** The window form of the totals read (contract i2-totals-window v1.2), the fields the scan preview uses. */
+export interface RecordWindowTotals {
+    model_cost_mmu: string;
+    mu_charged_mmu: string | null;
+    row_count: number;
+    as_of: string | null;
+}
+/**
+ * GET /v1/orgs/{org_id}/record/totals?from=&to= — the org's total over a window (at most 30 days,
+ * `to` not in the future). Returns the raw body: the caller shape-checks it. A 404 means the org is
+ * not in the Record cohort.
+ */
+export declare function getRecordWindowTotals(orgId: string, from: string, to: string, signal?: AbortSignal): Promise<unknown>;
 /**
  * Report one commit to Record's commit index (Doors W1.8, lib/commit-report.ts):
  * `POST /v1/orgs/{org}/record/commits`, body RecordCommit/v1. Returns the HTTP

package/dist/lib/api.js

@@ -427,6 +427,14 @@ export async function getMe() {
 export async function getRecordTotals(orgId, lineageKey, signal) {
     return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/record/totals?lineage_key=${encodeURIComponent(lineageKey)}`, signal ? { signal } : {}, { notFoundLabel: "Record totals", fallback: "Could not read record totals" });
 }
+/**
+ * GET /v1/orgs/{org_id}/record/totals?from=&to= — the org's total over a window (at most 30 days,
+ * `to` not in the future). Returns the raw body: the caller shape-checks it. A 404 means the org is
+ * not in the Record cohort.
+ */
+export async function getRecordWindowTotals(orgId, from, to, signal) {
+    return gFetch(`/v1/orgs/${encodeURIComponent(orgId)}/record/totals?from=${encodeURIComponent(from)}&to=${encodeURIComponent(to)}`, signal ? { signal } : {}, { notFoundLabel: "Record totals", fallback: "Could not read record totals" });
+}
 /**
  * Report one commit to Record's commit index (Doors W1.8, lib/commit-report.ts):
  * `POST /v1/orgs/{org}/record/commits`, body RecordCommit/v1. Returns the HTTP