@mnemom/mnemom 0.17.34-next.4 → 0.17.35

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

@@ -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-*`, `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
+ * any `x-mnemom-*`, `x-api-key` or `authorization` the phase sent is dropped, the lease key goes in X-Mnemom-Api-Key, the runner's own
+ * Anthropic key in x-api-key (ruling 34.30.1; the phase only ever holds a placeholder), 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,
@@ -36,7 +37,20 @@ export interface ModelProxy {
     close(): Promise<void>;
 }
 /** Outbound headers for one request: the phase's own, minus anything the proxy decides. */
-export declare function outboundHeaders(incoming: IncomingMessage["headers"], state: ProxyState): Record<string, string | string[] | undefined>;
+export declare function outboundHeaders(incoming: IncomingMessage["headers"], state: ProxyState, modelKey: string): Record<string, string | string[] | undefined>;
+/** What the job's model requests carried: each contract by its sha256, in first-seen order. */
+export interface RequestSummary {
+    count: number;
+    contracts: {
+        contract_sha256: string;
+        requests: number;
+    }[];
+}
+/**
+ * One job's forwarded requests, summarised for the operator's log and for the door2-path header
+ * check (W3.11): the sha256 of each header value's decoded bytes is the contract it sealed to.
+ */
+export declare function requestSummary(forwarded: readonly ForwardedRequest[]): RequestSummary;
 /** The largest 409 body the proxy reads for a contract mismatch. */
 export declare const MISMATCH_BODY_MAX: number;
 /** The client for the gateway's scheme: TLS for https, plain only for a local http gateway. */
@@ -46,4 +60,5 @@ export declare function requestFor(protocol: string): typeof httpRequest;
  * cut, so a truncated body is never mistaken for a whole one.
  */
 export declare function upstreamFailed(res: Pick<ServerResponse, "headersSent" | "writeHead" | "end" | "destroy">, e: Error): void;
-export declare function startModelProxy(gatewayUrl: string, state: ProxyState): Promise<ModelProxy>;
+/** `modelKey` is the runner process's own ANTHROPIC_API_KEY; it never enters a phase's env. */
+export declare function startModelProxy(gatewayUrl: string, state: ProxyState, modelKey: string): Promise<ModelProxy>;

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-*`, `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
+ * any `x-mnemom-*`, `x-api-key` or `authorization` the phase sent is dropped, the lease key goes in X-Mnemom-Api-Key, the runner's own
+ * Anthropic key in x-api-key (ruling 34.30.1; the phase only ever holds a placeholder), 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,
@@ -11,6 +12,7 @@
  */
 import { createServer, request as httpRequest, } from "node:http";
 import { request as httpsRequest } from "node:https";
+import { createHash } from "node:crypto";
 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";
@@ -25,12 +27,12 @@ const DROP = new Set([
     "trailer",
     "host",
     "content-length",
-    // The phase's model key is a placeholder; the gateway authenticates on the lease key alone.
+    // The phase's model key is a placeholder; the runner's own key replaces it (34.30.1).
     "x-api-key",
     "authorization",
 ]);
 /** Outbound headers for one request: the phase's own, minus anything the proxy decides. */
-export function outboundHeaders(incoming, state) {
+export function outboundHeaders(incoming, state, modelKey) {
     const kept = {};
     for (const [name, value] of Object.entries(incoming)) {
         const lower = name.toLowerCase();
@@ -39,9 +41,25 @@ export function outboundHeaders(incoming, state) {
         kept[lower] = value;
     }
     kept[LEASE_KEY_HEADER] = state.leaseKey;
+    kept["x-api-key"] = modelKey;
     kept[AGENT_ID_HEADER] = state.agentId;
     return applySealedContract(kept, state.contractValue);
 }
+/**
+ * One job's forwarded requests, summarised for the operator's log and for the door2-path header
+ * check (W3.11): the sha256 of each header value's decoded bytes is the contract it sealed to.
+ */
+export function requestSummary(forwarded) {
+    const by = new Map();
+    for (const f of forwarded) {
+        const sha = createHash("sha256").update(Buffer.from(f.contract, "base64url")).digest("hex");
+        by.set(sha, (by.get(sha) ?? 0) + 1);
+    }
+    return {
+        count: forwarded.length,
+        contracts: [...by].map(([contract_sha256, requests]) => ({ contract_sha256, requests })),
+    };
+}
 /** The largest 409 body the proxy reads for a contract mismatch. */
 export const MISMATCH_BODY_MAX = 64 * 1024;
 function mismatchVersion(body) {
@@ -74,7 +92,8 @@ export function upstreamFailed(res, e) {
     res.writeHead(502, { "content-type": "application/json" });
     res.end(JSON.stringify({ error: { code: "runner_proxy_upstream", message: e.message } }));
 }
-export async function startModelProxy(gatewayUrl, state) {
+/** `modelKey` is the runner process's own ANTHROPIC_API_KEY; it never enters a phase's env. */
+export async function startModelProxy(gatewayUrl, state, modelKey) {
     const upstream = new URL(gatewayUrl);
     const send = requestFor(upstream.protocol);
     const basePath = upstream.pathname.replace(/\/+$/, "");
@@ -86,7 +105,7 @@ export async function startModelProxy(gatewayUrl, state) {
         close: async () => { },
     };
     const server = createServer((req, res) => {
-        const headers = outboundHeaders(req.headers, state);
+        const headers = outboundHeaders(req.headers, state, modelKey);
         const sent = headers[CONTRACT_HEADER];
         const out = send({
             protocol: upstream.protocol,

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

@@ -13,15 +13,28 @@
  * "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.
+ * bounded (the read budget scales with the depth the halving reaches, up to a hard ceiling; no
+ * piece split below RECORD_MIN_SPLIT_MS per half).
+ *
+ * A slow or failing piece must not blank all 30 days. A piece that times out, errors at the
+ * network, or gets a 429 or 5xx is retried (at most RECORD_MAX_TRIES tries, jittered exponential
+ * backoff, honoring Retry-After). A piece that still fails on a timeout, network error or 5xx is
+ * too dense to total in one read, so it is halved exactly as a 400 "narrow it" is (a 429 is rate
+ * limiting and is not halved). The same halving applies when the next wait (backoff or Retry-After)
+ * would pass RECORD_MAX_RETRY_WAIT_MS or the time left. Outage guard: while nothing at all has been
+ * read, only RECORD_MAX_FRUITLESS_SPLITS such split is allowed, so a total outage costs a bounded
+ * number of reads instead of halving down to RECORD_MIN_SPLIT_MS; once any piece has been read,
+ * halving recurses. A piece that cannot be split further (RECORD_MIN_SPLIT_MS) or that
+ * the budget never reached is left out; the readable pieces are summed and the result carries `coverage`, which
+ * says how many of the 30 days the numbers cover. Partial totals are never presented as complete.
+ * A sum that cannot be formed (an out-of-range total, an unparsable as_of) is not a slow piece but
+ * bad data, so it fails the whole read as "unavailable".
  *
  * 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
- *   not_in_cohort 404: the org is not in the Record cohort (or the org is unknown). Not an error.
- *   unavailable   anything else (429 cap, 5xx, timeout, network, off-shape body). Scan continues.
+ *   ok            totals read and shape-checked; `coverage.complete` false when pieces are missing
+ *   not_in_cohort 404 on the whole window: the org is not in the Record cohort (or unknown).
+ *   unavailable   no piece could be read at all, or the pieces could not be summed. Scan continues.
  *   auth          401/403 or a missing login: throws RecordAuthError (fail closed).
  */
 import { type RecordWindowTotals } from "../api.js";
@@ -37,12 +50,35 @@ export declare const RECORD_TIMEOUT_MS = 10000;
  * 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). */
+/**
+ * The read budget is sized to the work, not fixed. The halving tree is discovered as it is read, so
+ * the budget grows with the deepest level reached: a window that has to be halved to depth
+ * RECORD_BASE_DEPTH (63 reads) fits the base budget; each level past that doubles the reads
+ * allowed and adds RECORD_TIME_PER_LEVEL_MS of wall clock. Both are capped by a HARD CEILING
+ * (RECORD_MAX_REQUESTS_CEILING reads, RECORD_TOTAL_TIMEOUT_CEILING_MS) that no depth can exceed, so
+ * a very dense org stays bounded. What the budget does not reach is reported as uncovered days.
+ */
+export declare const RECORD_BASE_DEPTH = 5;
+/** Base read budget (the first full-window read and every retry included). */
 export declare const RECORD_MAX_REQUESTS = 64;
-/** Wall-clock budget for all the reads of one scan; past it the result is "unavailable". */
+/** Hard ceiling on reads for one scan, however deep the halving goes. */
+export declare const RECORD_MAX_REQUESTS_CEILING = 256;
+/** Base wall-clock budget for all the reads of one scan. */
 export declare const RECORD_TOTAL_TIMEOUT_MS = 60000;
+/** Wall clock added per halving level past RECORD_BASE_DEPTH. */
+export declare const RECORD_TIME_PER_LEVEL_MS = 30000;
+/** Hard ceiling on wall clock for one scan, however deep the halving goes. */
+export declare const RECORD_TOTAL_TIMEOUT_CEILING_MS = 180000;
+/** At most this many tries per piece (first try included). */
+export declare const RECORD_MAX_TRIES = 3;
+/** First backoff before jitter; doubles per retry. */
+export declare const RECORD_BACKOFF_BASE_MS = 500;
+/** A Retry-After longer than this is not waited for: the piece is left unread. */
+export declare const RECORD_MAX_RETRY_WAIT_MS = 30000;
 /** A window is split only if both halves stay at least this long. */
 export declare const RECORD_MIN_SPLIT_MS: number;
+/** Timeout/5xx splits allowed before any piece has been read (past it the API is down, not dense). */
+export declare const RECORD_MAX_FRUITLESS_SPLITS = 1;
 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 {
@@ -52,10 +88,21 @@ export interface RecordWindow {
     from: string;
     to: string;
 }
+/**
+ * How much of the window the totals cover. `complete` is false whenever any piece was left out;
+ * every consumer must check it before treating the totals as the whole 30 days.
+ */
+export interface RecordCoverage {
+    complete: boolean;
+    /** Whole days read (rounded down, so never overstated); equals days_total when complete. */
+    days_covered: number;
+    days_total: number;
+}
 export type RecordOutcome = {
     status: "ok";
     totals: RecordWindowTotals;
     window: RecordWindow;
+    coverage: RecordCoverage;
 } | {
     status: "not_in_cohort";
 } | {
@@ -65,8 +112,12 @@ 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). */
+    /** Base budget for every read of one total together (default RECORD_TOTAL_TIMEOUT_MS); scales up with depth. */
     totalTimeoutMs?: number;
+    /** Backoff wait; default setTimeout. Injected so tests do not sleep. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Jitter source in [0, 1); default Math.random. */
+    random?: () => 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

@@ -13,15 +13,28 @@
  * "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.
+ * bounded (the read budget scales with the depth the halving reaches, up to a hard ceiling; no
+ * piece split below RECORD_MIN_SPLIT_MS per half).
+ *
+ * A slow or failing piece must not blank all 30 days. A piece that times out, errors at the
+ * network, or gets a 429 or 5xx is retried (at most RECORD_MAX_TRIES tries, jittered exponential
+ * backoff, honoring Retry-After). A piece that still fails on a timeout, network error or 5xx is
+ * too dense to total in one read, so it is halved exactly as a 400 "narrow it" is (a 429 is rate
+ * limiting and is not halved). The same halving applies when the next wait (backoff or Retry-After)
+ * would pass RECORD_MAX_RETRY_WAIT_MS or the time left. Outage guard: while nothing at all has been
+ * read, only RECORD_MAX_FRUITLESS_SPLITS such split is allowed, so a total outage costs a bounded
+ * number of reads instead of halving down to RECORD_MIN_SPLIT_MS; once any piece has been read,
+ * halving recurses. A piece that cannot be split further (RECORD_MIN_SPLIT_MS) or that
+ * the budget never reached is left out; the readable pieces are summed and the result carries `coverage`, which
+ * says how many of the 30 days the numbers cover. Partial totals are never presented as complete.
+ * A sum that cannot be formed (an out-of-range total, an unparsable as_of) is not a slow piece but
+ * bad data, so it fails the whole read as "unavailable".
  *
  * 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
- *   not_in_cohort 404: the org is not in the Record cohort (or the org is unknown). Not an error.
- *   unavailable   anything else (429 cap, 5xx, timeout, network, off-shape body). Scan continues.
+ *   ok            totals read and shape-checked; `coverage.complete` false when pieces are missing
+ *   not_in_cohort 404 on the whole window: the org is not in the Record cohort (or unknown).
+ *   unavailable   no piece could be read at all, or the pieces could not be summed. Scan continues.
  *   auth          401/403 or a missing login: throws RecordAuthError (fail closed).
  */
 import { getRecordWindowTotals, MnemomApiError } from "../api.js";
@@ -37,12 +50,35 @@ export const RECORD_TIMEOUT_MS = 10_000;
  * 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). */
+/**
+ * The read budget is sized to the work, not fixed. The halving tree is discovered as it is read, so
+ * the budget grows with the deepest level reached: a window that has to be halved to depth
+ * RECORD_BASE_DEPTH (63 reads) fits the base budget; each level past that doubles the reads
+ * allowed and adds RECORD_TIME_PER_LEVEL_MS of wall clock. Both are capped by a HARD CEILING
+ * (RECORD_MAX_REQUESTS_CEILING reads, RECORD_TOTAL_TIMEOUT_CEILING_MS) that no depth can exceed, so
+ * a very dense org stays bounded. What the budget does not reach is reported as uncovered days.
+ */
+export const RECORD_BASE_DEPTH = 5;
+/** Base read budget (the first full-window read and every retry included). */
 export const RECORD_MAX_REQUESTS = 64;
-/** Wall-clock budget for all the reads of one scan; past it the result is "unavailable". */
+/** Hard ceiling on reads for one scan, however deep the halving goes. */
+export const RECORD_MAX_REQUESTS_CEILING = 256;
+/** Base wall-clock budget for all the reads of one scan. */
 export const RECORD_TOTAL_TIMEOUT_MS = 60_000;
+/** Wall clock added per halving level past RECORD_BASE_DEPTH. */
+export const RECORD_TIME_PER_LEVEL_MS = 30_000;
+/** Hard ceiling on wall clock for one scan, however deep the halving goes. */
+export const RECORD_TOTAL_TIMEOUT_CEILING_MS = 180_000;
+/** At most this many tries per piece (first try included). */
+export const RECORD_MAX_TRIES = 3;
+/** First backoff before jitter; doubles per retry. */
+export const RECORD_BACKOFF_BASE_MS = 500;
+/** A Retry-After longer than this is not waited for: the piece is left unread. */
+export const RECORD_MAX_RETRY_WAIT_MS = 30_000;
 /** A window is split only if both halves stay at least this long. */
 export const RECORD_MIN_SPLIT_MS = 60 * 60 * 1000;
+/** Timeout/5xx splits allowed before any piece has been read (past it the API is down, not dense). */
+export const RECORD_MAX_FRUITLESS_SPLITS = 1;
 /** The API's bigint ceiling: a larger sum cannot be a real total. */
 const MAX_MMU = 9223372036854775807n;
 const DAY_MS = 24 * 60 * 60 * 1000;
@@ -122,11 +158,20 @@ function addTotals(a, b) {
         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 {
+/** A sum that cannot be formed is bad data, not a slow piece: the whole read is unavailable. */
+class MergeFailed extends Error {
 }
 class NotInCohort extends Error {
 }
+/** Worth another try: a timeout or network failure, a 429, or a 5xx. Everything else is final. */
+function isTransient(e) {
+    if (e instanceof MnemomApiError) {
+        const s = e.effectiveStatus;
+        return s === 429 || s >= 500;
+    }
+    return true;
+}
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /** Never throws except RecordAuthError (401/403, fail closed). */
 export async function fetchRecordTotals(orgId, deps = {}) {
     if (!isOrgId(orgId))
@@ -134,44 +179,103 @@ export async function fetchRecordTotals(orgId, deps = {}) {
     const window = recordWindow((deps.now ?? Date.now)());
     const fetchTotals = deps.fetchTotals ?? getRecordWindowTotals;
     const timeoutMs = deps.timeoutMs ?? RECORD_TIMEOUT_MS;
-    const deadline = Date.now() + (deps.totalTimeoutMs ?? RECORD_TOTAL_TIMEOUT_MS);
+    const baseBudgetMs = deps.totalTimeoutMs ?? RECORD_TOTAL_TIMEOUT_MS;
+    const sleep = deps.sleep ?? defaultSleep;
+    const random = deps.random ?? Math.random;
+    const startedAt = Date.now();
     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;
+    let deepest = 0;
+    let sum = null;
+    let coveredMs = 0;
+    let fruitlessSplits = 0;
+    // Sized to the work (see RECORD_BASE_DEPTH), under a hard ceiling.
+    const extraLevels = () => Math.max(0, deepest - RECORD_BASE_DEPTH);
+    const maxReads = () => Math.min(RECORD_MAX_REQUESTS_CEILING, RECORD_MAX_REQUESTS * 2 ** extraLevels());
+    const budgetMs = () => Math.min(Math.max(baseBudgetMs, RECORD_TOTAL_TIMEOUT_CEILING_MS), baseBudgetMs + RECORD_TIME_PER_LEVEL_MS * extraLevels());
+    const timeLeft = () => startedAt + budgetMs() - Date.now();
+    /**
+     * Read [fromMs, toMs) and fold what is readable into `sum`. A piece that cannot be read is simply
+     * not added (and not counted as covered). Throws RecordAuthError, NotInCohort (root 404 only) or
+     * MergeFailed.
+     */
+    const read = async (fromMs, toMs, depth) => {
+        deepest = Math.max(deepest, depth);
+        // Halve at the midpoint and read both halves; a piece whose half would be under
+        // RECORD_MIN_SPLIT_MS is left unread. Reads stay under the budget and ceiling (checked per try).
+        const split = async () => {
+            const mid = fromMs + Math.floor((toMs - fromMs) / 2);
+            if (mid - fromMs < RECORD_MIN_SPLIT_MS || toMs - mid < RECORD_MIN_SPLIT_MS)
+                return;
+            await read(fromMs, mid, depth + 1);
+            await read(mid, toMs, depth + 1);
+        };
+        for (let attempt = 1; attempt <= RECORD_MAX_TRIES; attempt += 1) {
+            const left = timeLeft();
+            if (requests >= maxReads() || left <= 0)
+                return;
+            requests += 1;
+            let failure;
+            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)
+                    return; // off-shape: not retried, piece left out
+                try {
+                    sum = sum === null ? totals : addTotals(sum, totals);
+                }
+                catch {
+                    throw new MergeFailed();
+                }
+                coveredMs += toMs - fromMs;
+                return;
+            }
+            catch (e) {
+                if (e instanceof MergeFailed)
+                    throw e;
+                failure = e;
+            }
+            if (failure instanceof MnemomApiError) {
+                const s = failure.effectiveStatus;
                 if (s === 401 || s === 403)
                     throw new RecordAuthError();
-                if (s === 404 && root)
+                if (s === 404 && depth === 0)
                     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));
+                if (isWindowTooBig(failure)) {
+                    await split();
+                    return;
                 }
             }
-            // RecordAuthError / NotInCohort / nested failures above are thrown from this handler and never land here.
-            throw new SplitFailed();
+            if (!isTransient(failure))
+                return;
+            // A piece too dense to total in one read times out or 5xxs: once its tries (or its allowed
+            // wait) are used up, halve it like a 400 "narrow it". A 429 is rate limiting, not density:
+            // halving would only add reads, so it is left unread.
+            const splittable = !(failure instanceof MnemomApiError && failure.effectiveStatus === 429);
+            // Outage guard: while nothing at all has been read, one such split is allowed; a second means
+            // the API is down rather than the piece dense, and halving further would only burn the budget.
+            const giveUp = async () => {
+                if (!splittable)
+                    return;
+                if (coveredMs === 0) {
+                    if (fruitlessSplits >= RECORD_MAX_FRUITLESS_SPLITS)
+                        return;
+                    fruitlessSplits += 1;
+                }
+                await split();
+            };
+            if (attempt === RECORD_MAX_TRIES)
+                return giveUp();
+            // Jittered exponential backoff (500ms, 1s before jitter), never shorter than Retry-After.
+            const retryAfter = failure instanceof MnemomApiError ? failure.retryAfterMs : undefined;
+            const backoff = RECORD_BACKOFF_BASE_MS * 2 ** (attempt - 1) * (0.5 + 0.5 * random());
+            const wait = Math.max(backoff, retryAfter ?? 0);
+            if (wait > RECORD_MAX_RETRY_WAIT_MS || wait >= timeLeft())
+                return giveUp();
+            await sleep(wait);
         }
     };
     try {
-        const totals = await read(Date.parse(window.from), Date.parse(window.to), true);
-        return { status: "ok", totals, window };
+        await read(Date.parse(window.from), Date.parse(window.to), 0);
     }
     catch (e) {
         if (e instanceof RecordAuthError)
@@ -180,4 +284,18 @@ export async function fetchRecordTotals(orgId, deps = {}) {
             return { status: "not_in_cohort" };
         return { status: "unavailable" };
     }
+    if (sum === null)
+        return { status: "unavailable" };
+    const windowMs = Date.parse(window.to) - Date.parse(window.from);
+    const complete = coveredMs >= windowMs;
+    return {
+        status: "ok",
+        totals: sum,
+        window,
+        coverage: {
+            complete,
+            days_covered: complete ? RECORD_WINDOW_DAYS : Math.floor(coveredMs / DAY_MS),
+            days_total: RECORD_WINDOW_DAYS,
+        },
+    };
 }

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

@@ -1,13 +1,11 @@
-/**
- * Renders the scan preview report from values already in memory: the local PR scan plus the org's
- * Record totals. Pure (returns lines, prints nothing) and never persists anything. Totals are
- * labelled "last 30 days"; no other window number is invented. Money is integer millimu
- * (1 MU = 1000 mmu), formatted with BigInt so values above 2^53 stay exact.
- */
-import { type RecordOutcome } from "./record.js";
+import { type RecordCoverage, type RecordOutcome } from "./record.js";
 export declare const RECORD_NOT_AVAILABLE_NOTE = "Records not available for this org.";
 export declare const RECORD_UNAVAILABLE_NOTE = "Records could not be read right now; continuing without them.";
 export declare const RECORD_NO_ORG_NOTE = "Records skipped: pass --org <org_id> to include the org's Record totals.";
-/** "12.5 MU" from "12500". Caller guarantees a canonical mmu string. */
+/** "12.5 μ" from "12500". Caller guarantees a canonical mmu string. */
 export declare function formatMu(mmu: string): string;
+/** "$0.13 (12.5 μ)": dollars first, exact μ beside it. */
+export declare function describe(mmu: string): string;
 export declare function renderRecordSection(outcome: RecordOutcome): string[];
+/** The fixed partial-coverage sentence. */
+export declare function recordCoverageNote(c: RecordCoverage): string;

package/dist/lib/scan/report.js

@@ -1,19 +1,24 @@
 /**
  * Renders the scan preview report from values already in memory: the local PR scan plus the org's
  * Record totals. Pure (returns lines, prints nothing) and never persists anything. Totals are
- * labelled "last 30 days"; no other window number is invented. Money is integer millimu
- * (1 MU = 1000 mmu), formatted with BigInt so values above 2^53 stay exact.
+ * labelled "last 30 days"; no other window number is invented. Money is shown in dollars with the exact μ
+ * beside it (1 μ = 1 cent; the ledger unit is never printed), formatted with BigInt so values above 2^53 stay exact.
  */
+import { formatUsd } from "../conduct-receipt.js";
 import { RECORD_WINDOW_LABEL } from "./record.js";
 export const RECORD_NOT_AVAILABLE_NOTE = "Records not available for this org.";
 export const RECORD_UNAVAILABLE_NOTE = "Records could not be read right now; continuing without them.";
 export const RECORD_NO_ORG_NOTE = "Records skipped: pass --org <org_id> to include the org's Record totals.";
-/** "12.5 MU" from "12500". Caller guarantees a canonical mmu string. */
+/** "12.5 μ" from "12500". Caller guarantees a canonical mmu string. */
 export function formatMu(mmu) {
     const n = BigInt(mmu);
     const whole = (n / 1000n).toString().replace(/\B(?=(\d{3})+(?!\d))/g, ",");
     const frac = (n % 1000n).toString().padStart(3, "0").replace(/0+$/, "");
-    return `${whole}${frac ? `.${frac}` : ""} MU`;
+    return `${whole}${frac ? `.${frac}` : ""} μ`;
+}
+/** "$0.13 (12.5 μ)": dollars first, exact μ beside it. */
+export function describe(mmu) {
+    return `${formatUsd(BigInt(mmu))} (${formatMu(mmu)})`;
 }
 export function renderRecordSection(outcome) {
     if (outcome.status === "not_in_cohort")
@@ -21,10 +26,19 @@ export function renderRecordSection(outcome) {
     if (outcome.status === "unavailable")
         return [RECORD_UNAVAILABLE_NOTE];
     const t = outcome.totals;
+    const c = outcome.coverage;
+    // Partial totals are never labelled as the full window: the label and an explicit coverage line change.
+    const head = c.complete
+        ? [`Org Record (${RECORD_WINDOW_LABEL}, read from Mnemom; not stored):`]
+        : ["Org Record (partial, read from Mnemom; not stored):", `  ${recordCoverageNote(c)}`];
     return [
-        `Org Record (${RECORD_WINDOW_LABEL}, read from Mnemom; not stored):`,
-        `  Model cost: ${formatMu(t.model_cost_mmu)}`,
-        `  Charged: ${t.mu_charged_mmu === null ? "not charged" : formatMu(t.mu_charged_mmu)}`,
+        ...head,
+        `  Model cost: ${describe(t.model_cost_mmu)}`,
+        `  Charged: ${t.mu_charged_mmu === null ? "not charged" : describe(t.mu_charged_mmu)}`,
         `  Requests recorded: ${t.row_count}`,
     ];
 }
+/** The fixed partial-coverage sentence. */
+export function recordCoverageNote(c) {
+    return `Record totals cover ${c.days_covered} of ${c.days_total} days (some periods could not be read).`;
+}

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

@@ -1,10 +1,14 @@
 import type { ScanResult } from "./scan.js";
 export type ShareLevel = "summary" | "full" | "none";
+/** The level preselected at the prompt (Enter picks it). */
+export declare const DEFAULT_SHARE_LEVEL: ShareLevel;
 export declare const SHARE_OPTIONS: ReadonlyArray<{
     level: ShareLevel;
     label: string;
 }>;
-/** Asks the user. Anything but a recognised answer (cancel, EOF, noise) is "none": fail closed. */
+/** Shown just above the share prompt, so pressing Enter is an informed choice. */
+export declare const SHARE_DISCLOSURE: string;
+/** Asks the user, with Full preselected. Anything but a recognised answer (cancel, EOF, noise) is "none": fail closed. */
 export declare function promptShareLevel(): Promise<ShareLevel>;
 export declare function parseShareLevel(v: string | undefined): ShareLevel | null;
 /** Who receives the report. Sent only with a non-"none" share level. */

package/dist/lib/scan/share.js

@@ -1,16 +1,26 @@
 /**
  * Share level: what, if anything, may leave the machine. Asked before any output is built for sharing.
- * Default is summary metrics. "none" yields no payload at all.
+ * Full is the preselected choice (MNE-9619): pressing Enter at the prompt picks it. "none" yields no
+ * payload at all, and is what a cancelled, empty-piped or non-interactive prompt resolves to (fail closed).
  */
 import { askSelect } from "../prompt.js";
+/** The level preselected at the prompt (Enter picks it). */
+export const DEFAULT_SHARE_LEVEL = "full";
 export const SHARE_OPTIONS = [
-    { level: "summary", label: "Summary metrics only (counts and one estimate line; default)" },
-    { level: "full", label: "Full report (summary plus per-repo counts)" },
+    { level: "summary", label: "Summary metrics only (counts and one estimate line)" },
+    { level: "full", label: "Full report (summary plus per-repo counts; default)" },
     { level: "none", label: "Nothing (keep results on this machine)" },
 ];
-/** Asks the user. Anything but a recognised answer (cancel, EOF, noise) is "none": fail closed. */
+/** Shown just above the share prompt, so pressing Enter is an informed choice. */
+export const SHARE_DISCLOSURE = [
+    "Pressing Enter shares the Full report: the whole report, including your repo names and per-repo counts.",
+    "It is emailed to the report recipients. To share less, choose 1 (Summary: counts only, no repo names) or 3 (Nothing).",
+].join("\n");
+/** Asks the user, with Full preselected. Anything but a recognised answer (cancel, EOF, noise) is "none": fail closed. */
 export async function promptShareLevel() {
-    const answer = await askSelect("What may leave this machine?", SHARE_OPTIONS.map((o) => o.label));
+    // eslint-disable-next-line no-console -- consent text must show on stdout directly above the prompt (askSelect also prints with console.log)
+    console.log(SHARE_DISCLOSURE);
+    const answer = await askSelect("What may leave this machine?", SHARE_OPTIONS.map((o) => o.label), SHARE_OPTIONS.findIndex((o) => o.level === DEFAULT_SHARE_LEVEL));
     if (answer === null)
         return "none";
     return SHARE_OPTIONS.find((o) => o.label === answer)?.level ?? "none";