@mnemom/mnemom 0.17.34 → 0.17.36

package/dist/lib/runner/pr-body.js

@@ -0,0 +1,42 @@
+/**
+ * The body of the PR `mnemom agent run` opens: the job's goal line from the sealed contract and the
+ * Canon node its seal points to, both from the job read the runner already holds (no extra call).
+ * Never the contract body or any key: the goal is the contract's `statement`, on one line and
+ * capped; the node is cited only when the job read names a well-formed one, and a job without one
+ * still opens its PR, with no citation.
+ */
+/** The goal line's cap, in characters: a PR body line, not the contract. */
+export const PR_GOAL_MAX = 280;
+/** A Canon node key as the seal stores it: no spaces, markup or line breaks. */
+const NODE_KEY_RE = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$/;
+/** The node key when well formed, else null. */
+export function canonNodeKey(v) {
+    return typeof v === "string" && NODE_KEY_RE.test(v) ? v : null;
+}
+/** The sealed contract's statement on one line, capped; null when the bytes carry none. */
+export function goalLine(contract) {
+    let obj;
+    try {
+        obj = JSON.parse(contract);
+    }
+    catch {
+        return null;
+    }
+    if (!obj || typeof obj !== "object")
+        return null;
+    const s = obj.statement;
+    if (typeof s !== "string")
+        return null;
+    const line = s.replace(/\s+/g, " ").trim();
+    if (!line)
+        return null;
+    return line.length > PR_GOAL_MAX ? `${line.slice(0, PR_GOAL_MAX - 1)}…` : line;
+}
+export function prBody(job) {
+    const goal = goalLine(job.contract);
+    const lines = [`Goal: ${goal ?? "(the sealed contract states none)"}`];
+    if (job.canon_node_key !== null)
+        lines.push("", `Canon node: \`${job.canon_node_key}\``);
+    lines.push("", "Opened by `mnemom agent run` for a sealed contract.");
+    return `${lines.join("\n")}\n`;
+}

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/pr-source.js

@@ -31,6 +31,8 @@ const ALLOWED_PATHS = [
     new RegExp(`^/repos/${SLUG}/pulls\\?state=closed&sort=updated&direction=desc&per_page=\\d{1,3}&page=\\d{1,4}$`),
     new RegExp(`^/repos/${SLUG}/pulls/\\d{1,9}$`),
     new RegExp(`^/repos/${SLUG}/commits/[0-9a-f]{40}/check-runs\\?per_page=100$`),
+    // The repo picker's one list read (MNE-9643): the repos this login can read, newest push first.
+    /^\/user\/repos\?sort=pushed&direction=desc&per_page=\d{1,3}$/,
 ];
 export function isAllowedScanPath(path) {
     return ALLOWED_PATHS.some((re) => re.test(path));

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/repo-picker.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Repo picker for `mnemom scan` when --repo is omitted on a terminal (MNE-9643). Read-only: one GET of
+ * the repos the signed-in GitHub account can read, through the same credential seam the scan uses.
+ * Only `full_name` is kept; descriptions, owners' logins beyond the slug, URLs and the token never leave
+ * this module. Failures throw fixed text (never a GitHub body, header or URL). Prompt style and fail-closed
+ * handling follow promptShareLevel in ./share.ts: no terminal, no answer, or a bad answer selects nothing.
+ */
+import { askMultiSelect } from "../prompt.js";
+import { type GitHubCredential } from "./credential.js";
+/** Most repos listed: the most recently pushed, so the list stays pickable. `--repo` names any other. */
+export declare const REPO_PICKER_LIMIT = 30;
+/** The only path the picker may read. */
+export declare const REPO_LIST_PATH = "/user/repos?sort=pushed&direction=desc&per_page=30";
+export declare const REPO_PICKER_NO_TERMINAL_HINT = "Pass --repo owner/name (repeatable), or run in a terminal to pick from your repos.";
+export declare const REPO_LIST_FAILED_MSG = "Could not list your GitHub repos. Pass --repo owner/name, or check `gh auth status`.";
+export declare const NO_REPOS_MSG = "No GitHub repos are readable by this account. Pass --repo owner/name.";
+export declare const NO_REPO_SELECTED_MSG = "No repo selected. Pass --repo owner/name, or choose at least one number from the list.";
+export interface RepoListDeps {
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}
+/** GET-only read of the repos the credential can see. Returns valid slugs only, newest push first. */
+export declare function listReadableRepos(credential: GitHubCredential, deps?: RepoListDeps): Promise<string[]>;
+/**
+ * Lists the readable repos and asks which to scan (comma-separated numbers, as the other multi-select
+ * prompts do). Throws fixed text when there is no terminal, nothing is listed, or nothing valid is chosen.
+ */
+export declare function pickRepos(credential: GitHubCredential, o: {
+    isTty: boolean;
+    deps?: RepoListDeps;
+    ask?: typeof askMultiSelect;
+}): Promise<string[]>;

package/dist/lib/scan/repo-picker.js

@@ -0,0 +1,80 @@
+/**
+ * Repo picker for `mnemom scan` when --repo is omitted on a terminal (MNE-9643). Read-only: one GET of
+ * the repos the signed-in GitHub account can read, through the same credential seam the scan uses.
+ * Only `full_name` is kept; descriptions, owners' logins beyond the slug, URLs and the token never leave
+ * this module. Failures throw fixed text (never a GitHub body, header or URL). Prompt style and fail-closed
+ * handling follow promptShareLevel in ./share.ts: no terminal, no answer, or a bad answer selects nothing.
+ */
+import { askMultiSelect } from "../prompt.js";
+import { GITHUB_API, isAllowedScanPath } from "./pr-source.js";
+import { assertReadOnlyCredential, isValidRepoSlug } from "./credential.js";
+/** Most repos listed: the most recently pushed, so the list stays pickable. `--repo` names any other. */
+export const REPO_PICKER_LIMIT = 30;
+/** The only path the picker may read. */
+export const REPO_LIST_PATH = `/user/repos?sort=pushed&direction=desc&per_page=${REPO_PICKER_LIMIT}`;
+export const REPO_PICKER_NO_TERMINAL_HINT = "Pass --repo owner/name (repeatable), or run in a terminal to pick from your repos.";
+export const REPO_LIST_FAILED_MSG = "Could not list your GitHub repos. Pass --repo owner/name, or check `gh auth status`.";
+export const NO_REPOS_MSG = "No GitHub repos are readable by this account. Pass --repo owner/name.";
+export const NO_REPO_SELECTED_MSG = "No repo selected. Pass --repo owner/name, or choose at least one number from the list.";
+/** GET-only read of the repos the credential can see. Returns valid slugs only, newest push first. */
+export async function listReadableRepos(credential, deps = {}) {
+    if (!isAllowedScanPath(REPO_LIST_PATH))
+        throw new Error(REPO_LIST_FAILED_MSG);
+    // Same order as runLocalScan: a credential GitHub granted more than read is refused before any read.
+    await assertReadOnlyCredential(credential).catch(() => {
+        throw new Error(REPO_LIST_FAILED_MSG);
+    });
+    const doFetch = deps.fetchImpl ?? fetch;
+    let res;
+    try {
+        // User-level read: there is no single repo to scope to (the gh-login credential ignores the argument).
+        const bearer = await credential.tokenFor("");
+        res = await doFetch(`${GITHUB_API}${REPO_LIST_PATH}`, {
+            method: "GET",
+            headers: {
+                accept: "application/vnd.github+json",
+                "x-github-api-version": "2022-11-28",
+                "user-agent": "mnemom-cli-scan/1",
+                authorization: `Bearer ${bearer}`,
+            },
+            redirect: "error",
+            signal: AbortSignal.timeout(deps.timeoutMs ?? 10_000),
+        });
+    }
+    catch {
+        throw new Error(REPO_LIST_FAILED_MSG);
+    }
+    if (!res.ok) {
+        await res.body?.cancel().catch(() => { });
+        throw new Error(REPO_LIST_FAILED_MSG);
+    }
+    let json;
+    try {
+        json = await res.json();
+    }
+    catch {
+        throw new Error(REPO_LIST_FAILED_MSG);
+    }
+    if (!Array.isArray(json))
+        throw new Error(REPO_LIST_FAILED_MSG);
+    const slugs = json
+        .map((r) => (r && typeof r === "object" ? r.full_name : undefined))
+        .filter(isValidRepoSlug);
+    return [...new Set(slugs)].slice(0, REPO_PICKER_LIMIT);
+}
+/**
+ * Lists the readable repos and asks which to scan (comma-separated numbers, as the other multi-select
+ * prompts do). Throws fixed text when there is no terminal, nothing is listed, or nothing valid is chosen.
+ */
+export async function pickRepos(credential, o) {
+    if (!o.isTty)
+        throw new Error(`--repo owner/name is required (repeatable). ${REPO_PICKER_NO_TERMINAL_HINT}`);
+    const repos = await listReadableRepos(credential, o.deps);
+    if (repos.length === 0)
+        throw new Error(NO_REPOS_MSG);
+    const chosen = await (o.ask ?? askMultiSelect)("Which repos should be scanned (read-only)?", repos);
+    const picked = chosen.filter((c) => repos.includes(c));
+    if (picked.length === 0)
+        throw new Error(NO_REPO_SELECTED_MSG);
+    return picked;
+}