@mnemom/mnemom 0.17.34-next.2 → 0.17.34-next.3

package/dist/lib/runner/oidc.js

@@ -8,11 +8,12 @@
  * is oidc_<code> for S1's OIDC_EXCHANGE_REFUSALS, anything else oidc_unavailable. The token never
  * reaches argv, a log line or an outcome.
  *
- * S1 names the route but not its answer's field; `executor_key` is this runner's reading, open
- * with the Durable lead until S1 freezes it (no api handler exists yet to read it from).
+ * S1 names the route but not its answer's fields; `executor_key` (and `executor_id`, which binds
+ * the bundle) is this runner's reading, open with the Durable lead until S1 freezes it (no api handler exists yet to read it from).
  */
 import { OIDC_EXCHANGE_AUDIENCE, OIDC_EXCHANGE_REFUSALS, routePath, } from "../../vendor/durable-contract/index.js";
 import { errorCode } from "./executor-client.js";
+import { UUID_RE } from "./options.js";
 const unavailable = (detail) => ({
     ok: false,
     reason: "oidc_unavailable",
@@ -72,9 +73,11 @@ export async function exchangeOidc(opts) {
     }
     const body = await readJson(res);
     if (res.status === 200) {
-        const key = body?.executor_key;
+        const b = body;
+        const key = b?.executor_key;
+        const id = typeof b?.executor_id === "string" && UUID_RE.test(b.executor_id) ? b.executor_id : null;
         if (typeof key === "string" && key !== "")
-            return { ok: true, executorKey: key };
+            return { ok: true, executorKey: key, executorId: id };
         return unavailable("exchange answer has no executor_key");
     }
     const code = errorCode(body);

package/dist/lib/runner/options.d.ts

@@ -6,6 +6,8 @@
  */
 import { type RunnerFailMode } from "./settings.js";
 export declare const EXECUTOR_KEY_ENV = "MNEMOM_EXECUTOR_KEY";
+/** The enrolled executor's own id (executor-state.json `executor_id`): the bundle binds to it. */
+export declare const EXECUTOR_ID_ENV = "MNEMOM_EXECUTOR_ID";
 export declare const ACTIONS_ID_TOKEN_URL_ENV = "ACTIONS_ID_TOKEN_REQUEST_URL";
 export declare const ACTIONS_ID_TOKEN_TOKEN_ENV = "ACTIONS_ID_TOKEN_REQUEST_TOKEN";
 export interface RunFlags {
@@ -28,6 +30,8 @@ export interface RunPlan {
     failMode: RunnerFailMode;
     json: boolean;
     credential: RunCredential;
+    /** This runner's executor id, when the env names one; else the claim or exchange answer's. */
+    executorId: string | null;
     /** Warnings to print on stderr (an unknown fail mode reads as closed). */
     warnings: string[];
 }
@@ -38,4 +42,6 @@ export type RunPlanResult = {
     ok: false;
     usage: string;
 };
+/** A lowercase uuid: the executor id's only accepted form. */
+export declare const UUID_RE: RegExp;
 export declare function resolveRunPlan(flags: RunFlags, env: NodeJS.ProcessEnv): RunPlanResult;

package/dist/lib/runner/options.js

@@ -6,10 +6,14 @@
  */
 import { resolveFailMode, RUNNER_FAIL_MODE_ENV } from "./settings.js";
 export const EXECUTOR_KEY_ENV = "MNEMOM_EXECUTOR_KEY";
+/** The enrolled executor's own id (executor-state.json `executor_id`): the bundle binds to it. */
+export const EXECUTOR_ID_ENV = "MNEMOM_EXECUTOR_ID";
 export const ACTIONS_ID_TOKEN_URL_ENV = "ACTIONS_ID_TOKEN_REQUEST_URL";
 export const ACTIONS_ID_TOKEN_TOKEN_ENV = "ACTIONS_ID_TOKEN_REQUEST_TOKEN";
 const usage = (message) => ({ ok: false, usage: message });
 const set = (v) => v !== undefined && v.trim() !== "";
+/** A lowercase uuid: the executor id's only accepted form. */
+export const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 export function resolveRunPlan(flags, env) {
     if (Boolean(flags.watch) === Boolean(flags.once)) {
         return usage("mnemom agent run: give exactly one of --watch or --once");
@@ -40,8 +44,22 @@ export function resolveRunPlan(flags, env) {
         }
         credential = { kind: "executor_key", key: key.trim() };
     }
+    let executorId = null;
+    if (set(env[EXECUTOR_ID_ENV])) {
+        executorId = env[EXECUTOR_ID_ENV].trim();
+        if (!UUID_RE.test(executorId)) {
+            return usage(`mnemom agent run: ${EXECUTOR_ID_ENV} is not a lowercase uuid`);
+        }
+    }
     return {
         ok: true,
-        plan: { form, failMode: fail.mode, json: Boolean(flags.json), credential, warnings },
+        plan: {
+            form,
+            failMode: fail.mode,
+            json: Boolean(flags.json),
+            credential,
+            executorId,
+            warnings,
+        },
     };
 }

package/dist/lib/runner/phases.d.ts

@@ -5,8 +5,9 @@
  * verified bundle, in its order. A capabilities phase runs headless Claude Code with exactly the
  * tools its capability ids grant (an unknown id fails the phase; nothing is ever widened). A code
  * phase runs the bundle's JavaScript in a child node. Both get a scrubbed environment: a fresh
- * HOME, the model URL of the runner's own proxy and the model credential, never the executor key,
- * the lease key or a GitHub token.
+ * HOME, the model URL of the runner's own proxy and a fixed placeholder model key, never a real
+ * provider key, the executor key, the lease key or a GitHub token. The gateway authenticates the
+ * phase's model requests on the lease key the proxy adds, so claude only needs some key to start.
  */
 import type { ServedPhase } from "./bundle.js";
 /** W-L12's capability ids (workflow mnemom.door2 v1), and the Claude Code tools each grants. */
@@ -14,8 +15,10 @@ export declare const CAPABILITY_TOOLS: Readonly<Record<string, {
     tools: string[];
     allowed: string[];
 }>>;
-/** Env names a phase may inherit: the model credential and a working PATH. Nothing else. */
-export declare const PHASE_ENV_PASSTHROUGH: readonly ["PATH", "ANTHROPIC_API_KEY", "LANG", "TZ"];
+/** Env names a phase may inherit: a working PATH and locale. Nothing else. */
+export declare const PHASE_ENV_PASSTHROUGH: readonly ["PATH", "LANG", "TZ"];
+/** Not a secret: lets claude start; the proxy drops it before the gateway (ruling: option (i)). */
+export declare const PHASE_MODEL_KEY_PLACEHOLDER = "mnemom-runner-placeholder";
 export type ToolGrant = {
     ok: true;
     tools: string[];

package/dist/lib/runner/phases.js

@@ -5,8 +5,9 @@
  * verified bundle, in its order. A capabilities phase runs headless Claude Code with exactly the
  * tools its capability ids grant (an unknown id fails the phase; nothing is ever widened). A code
  * phase runs the bundle's JavaScript in a child node. Both get a scrubbed environment: a fresh
- * HOME, the model URL of the runner's own proxy and the model credential, never the executor key,
- * the lease key or a GitHub token.
+ * HOME, the model URL of the runner's own proxy and a fixed placeholder model key, never a real
+ * provider key, the executor key, the lease key or a GitHub token. The gateway authenticates the
+ * phase's model requests on the lease key the proxy adds, so claude only needs some key to start.
  */
 /** W-L12's capability ids (workflow mnemom.door2 v1), and the Claude Code tools each grants. */
 export const CAPABILITY_TOOLS = Object.freeze({
@@ -20,8 +21,10 @@ export const CAPABILITY_TOOLS = Object.freeze({
     // The runner opens the PR itself once every phase has passed; the model gets no tool for it.
     "pr.open": { tools: [], allowed: [] },
 });
-/** Env names a phase may inherit: the model credential and a working PATH. Nothing else. */
-export const PHASE_ENV_PASSTHROUGH = ["PATH", "ANTHROPIC_API_KEY", "LANG", "TZ"];
+/** Env names a phase may inherit: a working PATH and locale. Nothing else. */
+export const PHASE_ENV_PASSTHROUGH = ["PATH", "LANG", "TZ"];
+/** Not a secret: lets claude start; the proxy drops it before the gateway (ruling: option (i)). */
+export const PHASE_MODEL_KEY_PLACEHOLDER = "mnemom-runner-placeholder";
 export function toolsFor(capabilityIds) {
     const unknown = capabilityIds.filter((id) => !Object.hasOwn(CAPABILITY_TOOLS, id));
     if (unknown.length > 0)
@@ -54,6 +57,7 @@ export function phaseEnv(parent, home, modelUrl) {
             env[name] = v;
     }
     env.HOME = home;
+    env.ANTHROPIC_API_KEY = PHASE_MODEL_KEY_PLACEHOLDER;
     env.ANTHROPIC_BASE_URL = modelUrl;
     env.MNEMOM_RUNNER_MODEL_URL = modelUrl;
     env.CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1";

package/dist/lib/runner/proxy.d.ts

@@ -3,17 +3,21 @@
  *
  * A served phase's Claude Code (and a code phase's child) points ANTHROPIC_BASE_URL here, on
  * loopback. The proxy forwards each request to the gateway and decides every Mnemom header itself:
- * any `x-mnemom-*` the phase sent is dropped, the lease key goes in X-Mnemom-Api-Key, and the job's
+ * any `x-mnemom-*`, `x-api-key` or `authorization` the phase sent is dropped, the lease key goes in X-Mnemom-Api-Key, the job read's agent id in
+ * x-mnemom-agent-id (the gateway checks it against the lease's session), and the job's
  * sealed contract goes in `x-mnemom-contract` (exactly one, the sealed version). The phase never
  * sees the lease key. A 409 `contract_mismatch` from the gateway (34.11) is reported to the job,
  * which refetches and continues only on a higher sealed version, else fails closed.
  */
 import { request as httpRequest, type IncomingMessage, type ServerResponse } from "node:http";
 export declare const LEASE_KEY_HEADER = "x-mnemom-api-key";
+export declare const AGENT_ID_HEADER = "x-mnemom-agent-id";
 export interface ProxyState {
     /** The sealed header value to send; swapped in place after an accepted amend. */
     contractValue: string;
     leaseKey: string;
+    /** The session's agent, from the job read; always sent, a phase's own value never is. */
+    agentId: string;
 }
 export interface ForwardedRequest {
     method: string;

package/dist/lib/runner/proxy.js

@@ -3,7 +3,8 @@
  *
  * A served phase's Claude Code (and a code phase's child) points ANTHROPIC_BASE_URL here, on
  * loopback. The proxy forwards each request to the gateway and decides every Mnemom header itself:
- * any `x-mnemom-*` the phase sent is dropped, the lease key goes in X-Mnemom-Api-Key, and the job's
+ * any `x-mnemom-*`, `x-api-key` or `authorization` the phase sent is dropped, the lease key goes in X-Mnemom-Api-Key, the job read's agent id in
+ * x-mnemom-agent-id (the gateway checks it against the lease's session), and the job's
  * sealed contract goes in `x-mnemom-contract` (exactly one, the sealed version). The phase never
  * sees the lease key. A 409 `contract_mismatch` from the gateway (34.11) is reported to the job,
  * which refetches and continues only on a higher sealed version, else fails closed.
@@ -12,6 +13,7 @@ import { createServer, request as httpRequest, } from "node:http";
 import { request as httpsRequest } from "node:https";
 import { applySealedContract, CONTRACT_HEADER } from "./contract-header.js";
 export const LEASE_KEY_HEADER = "x-mnemom-api-key";
+export const AGENT_ID_HEADER = "x-mnemom-agent-id";
 /** Hop-by-hop headers (RFC 9110 7.6.1) and the ones the proxy owns. */
 const DROP = new Set([
     "connection",
@@ -23,6 +25,9 @@ const DROP = new Set([
     "trailer",
     "host",
     "content-length",
+    // The phase's model key is a placeholder; the gateway authenticates on the lease key alone.
+    "x-api-key",
+    "authorization",
 ]);
 /** Outbound headers for one request: the phase's own, minus anything the proxy decides. */
 export function outboundHeaders(incoming, state) {
@@ -34,6 +39,7 @@ export function outboundHeaders(incoming, state) {
         kept[lower] = value;
     }
     kept[LEASE_KEY_HEADER] = state.leaseKey;
+    kept[AGENT_ID_HEADER] = state.agentId;
     return applySealedContract(kept, state.contractValue);
 }
 /** The largest 409 body the proxy reads for a contract mismatch. */

package/dist/lib/scan/cost-per-pr.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Cost per merged PR and cost by PR size, for the Org Scan report. Pure: numbers in, numbers out.
+ *
+ * Source of the spend. Measured per-request cost cannot be tied to a PR with the data the scan has:
+ * the Anthropic usage reads return one whole-org total (no per-request or per-PR rows) and the Mnemom
+ * Record totals are one window sum (model cost and a request count, no PR key). So every figure here is
+ * `label: "estimate"`: the period's spend split across the merged PRs in proportion to lines changed.
+ * Each figure names the spend it was split from (`spend_source`); sources are never mixed in one report.
+ *
+ *   anthropic_usage          the whole-org Anthropic cost for the period (the CTO's admin key)
+ *   modelled_range           our modelled estimate (a low to high range, so the figures are ranges)
+ *
+ * Size is per PR, in lines changed = additions + deletions, exactly as GitHub reports them. Lockfiles and
+ * generated files are NOT excluded. small < 50; medium 50..500 inclusive; large > 500.
+ *
+ * Each size figure is the average cost of ONE PR of that size: spend * (mean lines of the bucket) /
+ * (total lines of the PRs in scope). Scope: the modelled estimate prices AI-assisted PRs only, so it is
+ * split across those only (`pr_scope: "ai_assisted"`, buckets too); the others use every merged PR
+ * (`pr_scope: "all_merged"`). `pr_count` counts PRs in that scope. Usage-key figures also carry
+ * `spend_scope: "whole_org"` (the key covers the whole organization, not just the scanned repos). The cost per merged PR is the spend over the count of merged PRs.
+ *
+ * Missing data is an absent field, never 0 or NaN: no usable spend, zero merged PRs in the period, an
+ * empty bucket, a scan that did not read every merged PR in the period, or a result past safe-integer
+ * range. Reverts are listed without sizes, so they are not counted as merged PRs here.
+ */
+import type { SpendEstimate } from "./spend/spend-estimate.js";
+/** Strictly below this is small. 50 is medium. */
+export declare const SMALL_MAX_EXCLUSIVE = 50;
+/** At or below this (and not small) is medium. 500 is medium; 501 is large. */
+export declare const MEDIUM_MAX_INCLUSIVE = 500;
+export type SizeBucket = "small" | "medium" | "large";
+export type CostSpendSourceName = "anthropic_usage" | "modelled_range";
+export interface PrSize {
+    /** YYYY-MM-DD, UTC. */
+    mergedDay: string;
+    /** additions + deletions. */
+    lines: number;
+    /** The PR carries an AI-tool mark (the same rule the modelled spend uses to count AI-assisted PRs). */
+    aiAssisted: boolean;
+}
+/** Where the spend comes from. USD, never cents. */
+export type CostSpend = {
+    source: "anthropic_usage";
+    usd: number;
+} | {
+    source: "modelled_range";
+    lowUsd: number;
+    highUsd: number;
+};
+/** One figure: a single value, or a low to high range for the modelled source. Integer cents. */
+export type PrScope = "ai_assisted" | "all_merged";
+export type CostFigure = {
+    /** "measured" is not possible with current data (see header); every figure is an estimate. */
+    label: "estimate";
+    spend_source: CostSpendSourceName;
+    /**
+     * Which PRs the average is over. The modelled estimate prices AI-assisted PRs only, so it is split
+     * across those only ("ai_assisted"); the usage key covers all spend, so they use "all_merged".
+     */
+    pr_scope: PrScope;
+    /** PRs in that scope. */
+    pr_count: number;
+    /** Present on anthropic_usage only: the key's usage is the whole organization's, not just these PRs'. */
+    spend_scope?: "whole_org";
+} & ({
+    value_cents: number;
+} | {
+    low_cents: number;
+    high_cents: number;
+});
+export interface CostPerPr {
+    cost_per_merged_pr?: CostFigure;
+    cost_by_pr_size?: Partial<Record<SizeBucket, CostFigure>>;
+}
+export declare const sizeBucket: (lines: number) => SizeBucket;
+/** Inclusive day count of YYYY-MM-DD..YYYY-MM-DD, or null if unparsable or reversed. */
+export declare function periodDays(p: {
+    start: string;
+    end: string;
+}): number | null;
+/** The period's spend in USD as [low, high]; null when there is no usable spend. */
+export declare function spendForPeriod(spend: CostSpend): [number, number] | null;
+/** The modelled estimate as a spend source, or null when the estimate is "none". */
+export declare const modelledSpend: (e: SpendEstimate) => CostSpend | null;
+/**
+ * @param prs           every merged PR the scan read, with merge day and size
+ * @param exhaustive    true only if the scan read EVERY merged PR in the period (no sample, no skipped
+ *                      large PR, none unreadable, no cap hit). Otherwise the average is not defined.
+ */
+export declare function buildCostPerPr(prs: readonly PrSize[] | undefined, period: {
+    start: string;
+    end: string;
+}, spend: CostSpend | null, exhaustive: boolean): CostPerPr;

package/dist/lib/scan/cost-per-pr.js

@@ -0,0 +1,101 @@
+/** Strictly below this is small. 50 is medium. */
+export const SMALL_MAX_EXCLUSIVE = 50;
+/** At or below this (and not small) is medium. 500 is medium; 501 is large. */
+export const MEDIUM_MAX_INCLUSIVE = 500;
+export const sizeBucket = (lines) => lines < SMALL_MAX_EXCLUSIVE ? "small" : lines <= MEDIUM_MAX_INCLUSIVE ? "medium" : "large";
+const DAY_MS = 86_400_000;
+/** Inclusive day count of YYYY-MM-DD..YYYY-MM-DD, or null if unparsable or reversed. */
+export function periodDays(p) {
+    const s = Date.parse(`${p.start}T00:00:00Z`);
+    const e = Date.parse(`${p.end}T00:00:00Z`);
+    if (!Number.isFinite(s) || !Number.isFinite(e) || e < s)
+        return null;
+    return Math.round((e - s) / DAY_MS) + 1;
+}
+const pos = (n) => typeof n === "number" && Number.isFinite(n) && n > 0;
+/** The period's spend in USD as [low, high]; null when there is no usable spend. */
+export function spendForPeriod(spend) {
+    let r;
+    if (spend.source === "anthropic_usage") {
+        if (!pos(spend.usd))
+            return null;
+        r = [spend.usd, spend.usd];
+    }
+    else {
+        if (!pos(spend.highUsd) || !(spend.lowUsd >= 0) || spend.lowUsd > spend.highUsd)
+            return null;
+        r = [spend.lowUsd, spend.highUsd];
+    }
+    return r.every((x) => Number.isFinite(x) && x * 100 <= Number.MAX_SAFE_INTEGER) ? r : null;
+}
+/** The modelled estimate as a spend source, or null when the estimate is "none". */
+export const modelledSpend = (e) => e.kind === "range" ? { source: "modelled_range", lowUsd: e.lowUsd, highUsd: e.highUsd } : null;
+/**
+ * `share` is the fraction of the period's spend one average PR here carries: always in (0, 1] by
+ * construction, and the spend is already bounded to safe-integer cents by spendForPeriod, so the
+ * rounded cents are finite safe integers without a further guard.
+ */
+function figure(spend, [low, high], count, share, scope) {
+    const c = (usd) => Math.round(usd * share * 100);
+    const base = {
+        label: "estimate",
+        spend_source: spend.source,
+        pr_scope: scope,
+        pr_count: count,
+        ...(spend.source === "anthropic_usage" ? { spend_scope: "whole_org" } : {}),
+    };
+    return spend.source === "modelled_range"
+        ? { ...base, low_cents: c(low), high_cents: c(high) }
+        : { ...base, value_cents: c(low) };
+}
+/**
+ * @param prs           every merged PR the scan read, with merge day and size
+ * @param exhaustive    true only if the scan read EVERY merged PR in the period (no sample, no skipped
+ *                      large PR, none unreadable, no cap hit). Otherwise the average is not defined.
+ */
+export function buildCostPerPr(prs, period, spend, exhaustive) {
+    if (!exhaustive || !spend || !Array.isArray(prs))
+        return {};
+    if (periodDays(period) === null)
+        return {};
+    const total = spendForPeriod(spend);
+    if (!total)
+        return {};
+    const inPeriod = prs.filter((p) => p.mergedDay >= period.start &&
+        p.mergedDay <= period.end &&
+        Number.isSafeInteger(p.lines) &&
+        p.lines >= 0);
+    // The modelled estimate is AI-tool spend, so it is split across AI-assisted PRs only; the usage key is
+    // the whole spend, so it is split across every merged PR.
+    const scope = spend.source === "modelled_range" ? "ai_assisted" : "all_merged";
+    const scoped = scope === "ai_assisted" ? inPeriod.filter((p) => p.aiAssisted) : inPeriod;
+    const n = scoped.length;
+    if (n === 0)
+        return {};
+    const out = {};
+    out.cost_per_merged_pr = figure(spend, total, n, 1 / n, scope);
+    let allLines = 0;
+    const agg = {
+        small: { n: 0, lines: 0 },
+        medium: { n: 0, lines: 0 },
+        large: { n: 0, lines: 0 },
+    };
+    for (const p of scoped) {
+        allLines += p.lines;
+        const a = agg[sizeBucket(p.lines)];
+        a.n += 1;
+        a.lines += p.lines;
+    }
+    // Splitting by lines needs lines: with none (or a sum past safe range) there is no size figure.
+    if (allLines <= 0 || !Number.isSafeInteger(allLines))
+        return out;
+    const bySize = {};
+    for (const b of ["small", "medium", "large"]) {
+        const a = agg[b];
+        if (a.n === 0)
+            continue;
+        bySize[b] = figure(spend, total, a.n, a.lines / a.n / allLines, scope);
+    }
+    out.cost_by_pr_size = bySize;
+    return out;
+}

package/dist/lib/scan/record.d.ts

@@ -4,10 +4,19 @@
  * Read-only and local: the answer is held in memory to build the report and is never uploaded or
  * stored (mnemom-api#4211: Mnemom stores no scan result).
  *
- * The window is always the last 30 days ending now (the contract's maximum). It is its own
+ * The window is the last 30 days ending now, less a one-minute margin at the start so it stays
+ * inside the API's retention floor (the contract's maximum is 30 days). It is its own
  * window, not the PR scan period, and the report labels it "last 30 days"; no other scan-window
  * number is ever produced here.
  *
+ * An org with more requests in the window than the API will total in one read (it answers 400
+ * "window holds more than N requests: narrow it") is read in pieces: the failing window is halved
+ * at its midpoint, recursively, and the pieces are summed. The API's window is half-open
+ * [from, to), so pieces [from, mid) and [mid, to) neither overlap nor leave a gap. Fan-out is
+ * bounded (RECORD_MAX_REQUESTS reads, no piece split below RECORD_MIN_SPLIT_MS per half), and a
+ * total is all or nothing: any piece that fails for any other reason makes the whole read
+ * "unavailable", never a partial sum.
+ *
  * Outcomes are a closed set, and every one has fixed text. The thrown value, the response body
  * and the credential never reach the terminal:
  *   ok            totals read and shape-checked
@@ -19,6 +28,21 @@ import { type RecordWindowTotals } from "../api.js";
 export declare const RECORD_WINDOW_DAYS = 30;
 export declare const RECORD_WINDOW_LABEL = "last 30 days";
 export declare const RECORD_TIMEOUT_MS = 10000;
+/**
+ * The API 400s a `from` earlier than its own now minus 30 days (retention floor, strict on purpose:
+ * mnemom-api#4310). Its clock runs later than ours by latency, so a window opening exactly 30 days
+ * before our now is always past that floor. Open it this much after instead; `to` stays our now
+ * (the API accepts a `to` up to 60s ahead of its clock: WINDOW_SKEW_MS in mnemom-api
+ * src/record/totals.ts). Ending at now centres the budget: the window is accepted while our clock is
+ * within 60s of the API's in either direction; ending earlier would trade away the floor side.
+ */
+export declare const RECORD_FLOOR_MARGIN_MS = 60000;
+/** Most reads one scan may make (the first full-window read included). */
+export declare const RECORD_MAX_REQUESTS = 64;
+/** Wall-clock budget for all the reads of one scan; past it the result is "unavailable". */
+export declare const RECORD_TOTAL_TIMEOUT_MS = 60000;
+/** A window is split only if both halves stay at least this long. */
+export declare const RECORD_MIN_SPLIT_MS: number;
 export declare const isOrgId: (v: unknown) => v is string;
 export declare const RECORD_AUTH_MSG = "Record totals were refused for this org. Run `mnemom login` (or set MNEMOM_API_KEY) with an owner, admin or auditor of the org passed to --org, then retry.";
 export declare class RecordAuthError extends Error {
@@ -41,6 +65,8 @@ export interface RecordDeps {
     fetchTotals?: (orgId: string, from: string, to: string, signal: AbortSignal) => Promise<unknown>;
     now?: () => number;
     timeoutMs?: number;
+    /** Budget for every read of one total together (default RECORD_TOTAL_TIMEOUT_MS). */
+    totalTimeoutMs?: number;
 }
 export declare function recordWindow(nowMs: number): RecordWindow;
 /** Shape-check the body: a malformed answer is "unavailable", never rendered. */

package/dist/lib/scan/record.js

@@ -4,10 +4,19 @@
  * Read-only and local: the answer is held in memory to build the report and is never uploaded or
  * stored (mnemom-api#4211: Mnemom stores no scan result).
  *
- * The window is always the last 30 days ending now (the contract's maximum). It is its own
+ * The window is the last 30 days ending now, less a one-minute margin at the start so it stays
+ * inside the API's retention floor (the contract's maximum is 30 days). It is its own
  * window, not the PR scan period, and the report labels it "last 30 days"; no other scan-window
  * number is ever produced here.
  *
+ * An org with more requests in the window than the API will total in one read (it answers 400
+ * "window holds more than N requests: narrow it") is read in pieces: the failing window is halved
+ * at its midpoint, recursively, and the pieces are summed. The API's window is half-open
+ * [from, to), so pieces [from, mid) and [mid, to) neither overlap nor leave a gap. Fan-out is
+ * bounded (RECORD_MAX_REQUESTS reads, no piece split below RECORD_MIN_SPLIT_MS per half), and a
+ * total is all or nothing: any piece that fails for any other reason makes the whole read
+ * "unavailable", never a partial sum.
+ *
  * Outcomes are a closed set, and every one has fixed text. The thrown value, the response body
  * and the credential never reach the terminal:
  *   ok            totals read and shape-checked
@@ -19,8 +28,23 @@ import { getRecordWindowTotals, MnemomApiError } from "../api.js";
 export const RECORD_WINDOW_DAYS = 30;
 export const RECORD_WINDOW_LABEL = "last 30 days";
 export const RECORD_TIMEOUT_MS = 10_000;
-/** `to` may not be in the future; stay a minute behind so a fast local clock cannot trip it. */
-const CLOCK_SKEW_MS = 60_000;
+/**
+ * The API 400s a `from` earlier than its own now minus 30 days (retention floor, strict on purpose:
+ * mnemom-api#4310). Its clock runs later than ours by latency, so a window opening exactly 30 days
+ * before our now is always past that floor. Open it this much after instead; `to` stays our now
+ * (the API accepts a `to` up to 60s ahead of its clock: WINDOW_SKEW_MS in mnemom-api
+ * src/record/totals.ts). Ending at now centres the budget: the window is accepted while our clock is
+ * within 60s of the API's in either direction; ending earlier would trade away the floor side.
+ */
+export const RECORD_FLOOR_MARGIN_MS = 60_000;
+/** Most reads one scan may make (the first full-window read included). */
+export const RECORD_MAX_REQUESTS = 64;
+/** Wall-clock budget for all the reads of one scan; past it the result is "unavailable". */
+export const RECORD_TOTAL_TIMEOUT_MS = 60_000;
+/** A window is split only if both halves stay at least this long. */
+export const RECORD_MIN_SPLIT_MS = 60 * 60 * 1000;
+/** The API's bigint ceiling: a larger sum cannot be a real total. */
+const MAX_MMU = 9223372036854775807n;
 const DAY_MS = 24 * 60 * 60 * 1000;
 const ORG_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
 const MMU_RE = /^(0|[1-9][0-9]{0,18})$/;
@@ -33,9 +57,9 @@ export class RecordAuthError extends Error {
     }
 }
 export function recordWindow(nowMs) {
-    const to = nowMs - CLOCK_SKEW_MS;
+    const to = nowMs;
     return {
-        from: new Date(to - RECORD_WINDOW_DAYS * DAY_MS).toISOString(),
+        from: new Date(to - RECORD_WINDOW_DAYS * DAY_MS + RECORD_FLOOR_MARGIN_MS).toISOString(),
         to: new Date(to).toISOString(),
     };
 }
@@ -60,26 +84,100 @@ export function parseWindowTotals(v) {
         as_of: o.as_of,
     };
 }
+/** The API's too-many-requests answer: a 400 saying the window holds more than N requests. */
+const isWindowTooBig = (e) => e instanceof MnemomApiError &&
+    e.effectiveStatus === 400 &&
+    /holds more than \d+ requests/.test(e.message);
+/** Latest of two as_of timestamps (a "latest row" field is combined by max, never added). */
+function laterAsOf(a, b) {
+    if (a === null)
+        return b;
+    if (b === null)
+        return a;
+    const ta = Date.parse(a);
+    const tb = Date.parse(b);
+    if (Number.isNaN(ta) || Number.isNaN(tb))
+        throw new Error("unparsable as_of");
+    return tb > ta ? b : a;
+}
+/**
+ * Add two windows' totals. Costs, charges and row counts are additive over disjoint windows (a
+ * request sits in the window of its gateway row, and its billing row follows it). `mu_charged_mmu`
+ * is null for a window with no billing row, so it is null only when every piece is null, as the
+ * API's own multi-lineage sum does. `as_of` is the latest row's time, so it is the max.
+ */
+function addTotals(a, b) {
+    const model = BigInt(a.model_cost_mmu) + BigInt(b.model_cost_mmu);
+    const mu = a.mu_charged_mmu === null && b.mu_charged_mmu === null
+        ? null
+        : BigInt(a.mu_charged_mmu ?? "0") + BigInt(b.mu_charged_mmu ?? "0");
+    const rows = a.row_count + b.row_count;
+    if (model > MAX_MMU || (mu !== null && mu > MAX_MMU) || !Number.isSafeInteger(rows)) {
+        throw new Error("summed total out of range");
+    }
+    return {
+        model_cost_mmu: model.toString(),
+        mu_charged_mmu: mu === null ? null : mu.toString(),
+        row_count: rows,
+        as_of: laterAsOf(a.as_of, b.as_of),
+    };
+}
+/** Any failure other than auth / not-in-cohort makes the whole total unavailable. */
+class SplitFailed extends Error {
+}
+class NotInCohort extends Error {
+}
 /** Never throws except RecordAuthError (401/403, fail closed). */
 export async function fetchRecordTotals(orgId, deps = {}) {
     if (!isOrgId(orgId))
         return { status: "unavailable" };
     const window = recordWindow((deps.now ?? Date.now)());
     const fetchTotals = deps.fetchTotals ?? getRecordWindowTotals;
-    const signal = AbortSignal.timeout(deps.timeoutMs ?? RECORD_TIMEOUT_MS);
+    const timeoutMs = deps.timeoutMs ?? RECORD_TIMEOUT_MS;
+    const deadline = Date.now() + (deps.totalTimeoutMs ?? RECORD_TOTAL_TIMEOUT_MS);
+    let requests = 0;
+    /** Total of [fromMs, toMs). Throws RecordAuthError, NotInCohort (root 404 only) or SplitFailed. */
+    const read = async (fromMs, toMs, root) => {
+        const left = deadline - Date.now();
+        if (requests >= RECORD_MAX_REQUESTS || left <= 0)
+            throw new SplitFailed();
+        requests += 1;
+        try {
+            const body = await fetchTotals(orgId, new Date(fromMs).toISOString(), new Date(toMs).toISOString(), AbortSignal.timeout(Math.min(timeoutMs, left)));
+            const totals = parseWindowTotals(body);
+            if (!totals)
+                throw new SplitFailed();
+            return totals;
+        }
+        catch (e) {
+            if (e instanceof MnemomApiError) {
+                const s = e.effectiveStatus;
+                if (s === 401 || s === 403)
+                    throw new RecordAuthError();
+                if (s === 404 && root)
+                    throw new NotInCohort();
+                if (isWindowTooBig(e)) {
+                    const mid = fromMs + Math.floor((toMs - fromMs) / 2);
+                    if (mid - fromMs < RECORD_MIN_SPLIT_MS || toMs - mid < RECORD_MIN_SPLIT_MS) {
+                        throw new SplitFailed();
+                    }
+                    const first = await read(fromMs, mid, false);
+                    return addTotals(first, await read(mid, toMs, false));
+                }
+            }
+            // RecordAuthError / NotInCohort / nested failures above are thrown from this handler and never land here.
+            throw new SplitFailed();
+        }
+    };
     try {
-        const body = await fetchTotals(orgId, window.from, window.to, signal);
-        const totals = parseWindowTotals(body);
-        return totals ? { status: "ok", totals, window } : { status: "unavailable" };
+        const totals = await read(Date.parse(window.from), Date.parse(window.to), true);
+        return { status: "ok", totals, window };
     }
     catch (e) {
-        if (e instanceof MnemomApiError) {
-            const s = e.effectiveStatus;
-            if (s === 401 || s === 403)
-                throw new RecordAuthError();
-            if (s === 404)
-                return { status: "not_in_cohort" };
-        }
+        if (e instanceof RecordAuthError)
+            throw e;
+        if (e instanceof NotInCohort)
+            return { status: "not_in_cohort" };
         return { status: "unavailable" };
     }
 }