@mnemom/mnemom 0.17.32 → 0.17.34-next.1

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

@@ -0,0 +1,31 @@
+/**
+ * Thin runner settings (Doors W-L13, W4.4): what the runner does on a Mnemom error, and how a job
+ * lands once its PR is open.
+ *
+ * Fail mode (decision 20, OD-2): served-phase jobs fail CLOSED by default. A Mnemom error (claim,
+ * bundle fetch, bundle verification, the job read, the gateway) stops the job and leaves it for
+ * the lease to lapse back to ready; nothing runs unverified or ungoverned. `open` lets a job that
+ * already holds a verified bundle carry on through a transient error on a later call. It never
+ * lets an unverified bundle run: verification failures stop the job in every mode. An unknown
+ * value reads as the default, closed, with a warning, so a typo can never weaken the runner.
+ *
+ * Merge strategy (W4.4, T15): the bundle may name `merge_on_green` (our fleet) or `external`
+ * (a person merges). A bundle that names none resolves to `external`: the job opens the PR and
+ * stops.
+ */
+import type { MergeStrategy, ServedPhaseBundle } from "./bundle.js";
+export type RunnerFailMode = "closed" | "open";
+export declare const RUNNER_FAIL_MODE_ENV = "MNEMOM_RUNNER_FAIL_MODE";
+export declare const DEFAULT_RUNNER_FAIL_MODE: RunnerFailMode;
+export interface ResolvedFailMode {
+    mode: RunnerFailMode;
+    /** Set when a value was given but not recognised (the default applied). */
+    warning?: string;
+}
+/**
+ * The fail mode for one runner. Precedence: the `--fail-mode` flag, then MNEMOM_RUNNER_FAIL_MODE,
+ * then closed. Matching is case-insensitive and trims whitespace; an empty value counts as unset.
+ */
+export declare function resolveFailMode(flag: string | undefined, env: string | undefined): ResolvedFailMode;
+/** The bundle's merge strategy, `external` when it names none. */
+export declare function resolveMergeStrategy(bundle: Pick<ServedPhaseBundle, "merge_strategy">): MergeStrategy;

package/dist/lib/runner/settings.js

@@ -0,0 +1,44 @@
+/**
+ * Thin runner settings (Doors W-L13, W4.4): what the runner does on a Mnemom error, and how a job
+ * lands once its PR is open.
+ *
+ * Fail mode (decision 20, OD-2): served-phase jobs fail CLOSED by default. A Mnemom error (claim,
+ * bundle fetch, bundle verification, the job read, the gateway) stops the job and leaves it for
+ * the lease to lapse back to ready; nothing runs unverified or ungoverned. `open` lets a job that
+ * already holds a verified bundle carry on through a transient error on a later call. It never
+ * lets an unverified bundle run: verification failures stop the job in every mode. An unknown
+ * value reads as the default, closed, with a warning, so a typo can never weaken the runner.
+ *
+ * Merge strategy (W4.4, T15): the bundle may name `merge_on_green` (our fleet) or `external`
+ * (a person merges). A bundle that names none resolves to `external`: the job opens the PR and
+ * stops.
+ */
+export const RUNNER_FAIL_MODE_ENV = "MNEMOM_RUNNER_FAIL_MODE";
+export const DEFAULT_RUNNER_FAIL_MODE = "closed";
+/**
+ * The fail mode for one runner. Precedence: the `--fail-mode` flag, then MNEMOM_RUNNER_FAIL_MODE,
+ * then closed. Matching is case-insensitive and trims whitespace; an empty value counts as unset.
+ */
+export function resolveFailMode(flag, env) {
+    for (const [source, raw] of [
+        ["--fail-mode", flag],
+        [RUNNER_FAIL_MODE_ENV, env],
+    ]) {
+        if (raw === undefined)
+            continue;
+        const v = raw.trim().toLowerCase();
+        if (v === "")
+            continue;
+        if (v === "closed" || v === "open")
+            return { mode: v };
+        return {
+            mode: DEFAULT_RUNNER_FAIL_MODE,
+            warning: `${source}=${JSON.stringify(raw)} is not closed or open; failing closed`,
+        };
+    }
+    return { mode: DEFAULT_RUNNER_FAIL_MODE };
+}
+/** The bundle's merge strategy, `external` when it names none. */
+export function resolveMergeStrategy(bundle) {
+    return bundle.merge_strategy ?? "external";
+}

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

@@ -0,0 +1,35 @@
+/**
+ * Coverage caps and sampling. Port of mnemom-api src/org-scan/scan/capped-scan.ts (PR #4208).
+ *
+ * Coverage decision (Shraddha, 2026-10-28): each scan covers the last 3 months OR the last 2,000 merged
+ * PRs, whichever is MORE; above 2,000 in the window, an even deterministic sample of 2,000.
+ */
+export declare const COVERAGE_MONTHS = 3;
+export interface ScanCaps {
+    maxPrs: number;
+    /** A PR with more additions+deletions than this is skipped, never read in full. */
+    maxPrSizeLines: number;
+    /** Upstream read calls. */
+    maxReads: number;
+    /** Wall-clock budget. */
+    maxMillis: number;
+}
+export declare const DEFAULT_SCAN_CAPS: ScanCaps;
+export type StopReason = "pr-cap" | "read-cap" | "time-cap";
+/** The day `months` calendar months before `end` (YYYY-MM-DD, UTC), clamped to the month's last day. */
+export declare function monthsBefore(end: string, months: number): string;
+/** `k` items spread evenly across `items` (order kept): index floor(i*n/k). Deterministic; n <= k returns all. */
+export declare function evenSample<T>(items: readonly T[], k: number): T[];
+export declare function sanitiseCaps(c: Partial<ScanCaps>): ScanCaps;
+/** Running read budget. Every call is told how many reads it may spend (`room`). */
+export declare class Budget {
+    private caps;
+    private now;
+    private startedAt;
+    reads: number;
+    constructor(caps: ScanCaps, now: () => number, startedAt: number);
+    block(n?: number): StopReason | null;
+    room(): number;
+    overrun(): StopReason | null;
+    charge(n: number): void;
+}

package/dist/lib/scan/caps.js

@@ -0,0 +1,67 @@
+/**
+ * Coverage caps and sampling. Port of mnemom-api src/org-scan/scan/capped-scan.ts (PR #4208).
+ *
+ * Coverage decision (Shraddha, 2026-10-28): each scan covers the last 3 months OR the last 2,000 merged
+ * PRs, whichever is MORE; above 2,000 in the window, an even deterministic sample of 2,000.
+ */
+export const COVERAGE_MONTHS = 3;
+export const DEFAULT_SCAN_CAPS = {
+    maxPrs: 2_000,
+    maxPrSizeLines: 20_000,
+    maxReads: 4_500,
+    maxMillis: 15 * 60_000,
+};
+/** The day `months` calendar months before `end` (YYYY-MM-DD, UTC), clamped to the month's last day. */
+export function monthsBefore(end, months) {
+    const [y, m, d] = end.split("-").map(Number);
+    const target = new Date(Date.UTC(y, m - 1 - months, 1));
+    const last = new Date(Date.UTC(target.getUTCFullYear(), target.getUTCMonth() + 1, 0)).getUTCDate();
+    target.setUTCDate(Math.min(d, last));
+    return target.toISOString().slice(0, 10);
+}
+/** `k` items spread evenly across `items` (order kept): index floor(i*n/k). Deterministic; n <= k returns all. */
+export function evenSample(items, k) {
+    const n = items.length;
+    if (n <= k)
+        return [...items];
+    return Array.from({ length: k }, (_, i) => items[Math.floor((i * n) / k)]);
+}
+export function sanitiseCaps(c) {
+    const pos = (n, d) => typeof n === "number" && Number.isFinite(n) && n > 0 ? Math.floor(n) : d;
+    return {
+        maxPrs: pos(c.maxPrs, DEFAULT_SCAN_CAPS.maxPrs),
+        maxPrSizeLines: pos(c.maxPrSizeLines, DEFAULT_SCAN_CAPS.maxPrSizeLines),
+        maxReads: pos(c.maxReads, DEFAULT_SCAN_CAPS.maxReads),
+        maxMillis: pos(c.maxMillis, DEFAULT_SCAN_CAPS.maxMillis),
+    };
+}
+/** Running read budget. Every call is told how many reads it may spend (`room`). */
+export class Budget {
+    caps;
+    now;
+    startedAt;
+    reads = 0;
+    constructor(caps, now, startedAt) {
+        this.caps = caps;
+        this.now = now;
+        this.startedAt = startedAt;
+    }
+    block(n = 1) {
+        if (this.now() - this.startedAt >= this.caps.maxMillis)
+            return "time-cap";
+        if (this.reads + n > this.caps.maxReads)
+            return "read-cap";
+        return null;
+    }
+    room() {
+        if (this.now() - this.startedAt >= this.caps.maxMillis)
+            return 0;
+        return Math.max(0, this.caps.maxReads - this.reads);
+    }
+    overrun() {
+        return this.reads > this.caps.maxReads ? "read-cap" : null;
+    }
+    charge(n) {
+        this.reads += n;
+    }
+}

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

@@ -0,0 +1,37 @@
+/** The complete permission set a scan credential may hold. Read only. */
+export declare const SCAN_READ_PERMISSIONS: Readonly<Record<string, "read">>;
+export interface GitHubCredential {
+    /** Fixed label for diagnostics ("app", "personal"): never a token, login or URL. */
+    readonly kind: string;
+    /** A bearer token for reading `repo` (owner/name). A rejection fails that read closed. */
+    tokenFor(repo: string): Promise<string>;
+    /**
+     * The permissions GitHub granted this credential, when the source can tell. Null = unknown (for
+     * example a classic token); the scan then relies on GET-only egress and does not claim more.
+     */
+    grantedPermissions?(): Promise<Record<string, string> | null>;
+}
+/** Violations (empty when the map is exactly the read-only scan set). Port of readOnlyViolations. */
+export declare function readOnlyViolations(permissions: Record<string, string> | null | undefined): string[];
+/** owner/name, no dot-only segment. */
+export declare function isValidRepoSlug(s: unknown): s is string;
+/** Fixed-text failure: the message never carries a token, a body or a URL. */
+export declare class ScanCredentialError extends Error {
+    constructor(message: "scan credential refused" | "scan credential not configured");
+}
+/**
+ * Refuses a credential GitHub granted more than read to. Throws a fixed-text error and nothing else.
+ * Unknown (null) permissions pass: the source cannot tell, and the scan is GET-only regardless.
+ */
+export declare function assertReadOnlyCredential(c: GitHubCredential): Promise<void>;
+/** Runs `gh auth token`; resolves stdout or rejects. Injectable so tests never spawn a process. */
+export type GhTokenRunner = () => Promise<string>;
+/**
+ * The credential of whoever runs the scan: their own `gh` login. The token is fetched per read, held
+ * only in memory, never logged. Any failure (gh missing, not logged in, empty output) is the fixed
+ * "scan credential not configured"; the underlying error text is dropped.
+ */
+export declare function createGhLoginCredential(run?: GhTokenRunner): GitHubCredential;
+/** Overrides how a credential is obtained (tests, alternate sources). Null restores the gh-login default. */
+export declare function registerCredentialProvider(p: (() => Promise<GitHubCredential>) | null): void;
+export declare function resolveCredential(): Promise<GitHubCredential>;

package/dist/lib/scan/credential.js

@@ -0,0 +1,104 @@
+/**
+ * GitHubCredential: the one seam through which a local scan obtains a GitHub token.
+ *
+ * The scan core only ever sees this interface. The concrete default is the GitHub login of whoever
+ * runs the scan (`gh auth token`, see createGhLoginCredential); the server-issued App token path is
+ * retired (design owner, 2026-10-28). Port of the read-only rule in mnemom-api
+ * src/org-scan/github-scan-app.ts.
+ */
+import { execFile } from "node:child_process";
+/** The complete permission set a scan credential may hold. Read only. */
+export const SCAN_READ_PERMISSIONS = Object.freeze({
+    metadata: "read",
+    contents: "read",
+    pull_requests: "read",
+});
+/** Violations (empty when the map is exactly the read-only scan set). Port of readOnlyViolations. */
+export function readOnlyViolations(permissions) {
+    const out = [];
+    const p = permissions ?? {};
+    for (const [name, level] of Object.entries(p)) {
+        if (level !== "read")
+            out.push(`${name}:${level} is not read`);
+        if (!(name in SCAN_READ_PERMISSIONS))
+            out.push(`${name} is not in the scan permission set`);
+    }
+    for (const name of Object.keys(SCAN_READ_PERMISSIONS)) {
+        if (!(name in p))
+            out.push(`${name} missing`);
+    }
+    return out;
+}
+/** owner/name, no dot-only segment. */
+export function isValidRepoSlug(s) {
+    return (typeof s === "string" &&
+        /^[A-Za-z0-9._-]{1,100}\/[A-Za-z0-9._-]{1,100}$/.test(s) &&
+        !s.split("/").some((p) => /^\.+$/.test(p)));
+}
+/** Fixed-text failure: the message never carries a token, a body or a URL. */
+export class ScanCredentialError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ScanCredentialError";
+    }
+}
+/**
+ * Refuses a credential GitHub granted more than read to. Throws a fixed-text error and nothing else.
+ * Unknown (null) permissions pass: the source cannot tell, and the scan is GET-only regardless.
+ */
+export async function assertReadOnlyCredential(c) {
+    if (!c.grantedPermissions)
+        return;
+    let perms;
+    try {
+        perms = await c.grantedPermissions();
+    }
+    catch {
+        throw new ScanCredentialError("scan credential refused");
+    }
+    if (perms !== null && readOnlyViolations(perms).length > 0)
+        throw new ScanCredentialError("scan credential refused");
+}
+const runGhAuthToken = () => new Promise((resolve, reject) => {
+    try {
+        execFile("gh", ["auth", "token"], { shell: false, windowsHide: true, timeout: 10_000, maxBuffer: 64 * 1024 }, (err, stdout) => {
+            if (err)
+                reject(new Error("gh unavailable"));
+            else
+                resolve(String(stdout));
+        });
+    }
+    catch {
+        reject(new Error("gh unavailable"));
+    }
+});
+/**
+ * The credential of whoever runs the scan: their own `gh` login. The token is fetched per read, held
+ * only in memory, never logged. Any failure (gh missing, not logged in, empty output) is the fixed
+ * "scan credential not configured"; the underlying error text is dropped.
+ */
+export function createGhLoginCredential(run = runGhAuthToken) {
+    return {
+        kind: "gh-login",
+        async tokenFor() {
+            let out;
+            try {
+                out = (await run()).trim();
+            }
+            catch {
+                throw new ScanCredentialError("scan credential not configured");
+            }
+            if (!/^[A-Za-z0-9_.-]{10,}$/.test(out))
+                throw new ScanCredentialError("scan credential not configured");
+            return out;
+        },
+    };
+}
+let provider = null;
+/** Overrides how a credential is obtained (tests, alternate sources). Null restores the gh-login default. */
+export function registerCredentialProvider(p) {
+    provider = p;
+}
+export async function resolveCredential() {
+    return provider ? provider() : createGhLoginCredential();
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Scan failure reasons. Port of upstreamTag in mnemom-api capped-scan.ts (PRs #4221 / #4223): an
+ * exact-match table of fixed messages to fixed reason tags. The raw error message is NEVER echoed,
+ * so no token, URL or GitHub body can reach the terminal or the report. An unrecognised error maps
+ * to the generic "github" tag.
+ */
+export type FailureReason = "not_installed" | "credential" | "timeout" | "forbidden" | "rate_limited" | "github" | "network" | "invalid_input";
+export declare function classifyFailure(e: unknown): FailureReason;
+/** Fixed sentence for a reason. */
+export declare function failureText(r: FailureReason): string;

package/dist/lib/scan/failure.js

@@ -0,0 +1,43 @@
+const EXACT = new Map([
+    ["github repo not visible", "not_installed"],
+    ["scan credential refused", "credential"],
+    ["scan credential not configured", "credential"],
+    ["invalid repo", "invalid_input"],
+    ["invalid cursor", "invalid_input"],
+    ["scan read not allowed", "invalid_input"],
+    ["unexpected list shape", "github"],
+]);
+export function classifyFailure(e) {
+    if (e instanceof Error) {
+        if (e.name === "TimeoutError" || e.name === "AbortError")
+            return "timeout";
+        const exact = EXACT.get(e.message);
+        if (exact)
+            return exact;
+        const gh = /^github read failed \((\d{3})\)$/.exec(e.message);
+        if (gh) {
+            if (gh[1] === "401" || gh[1] === "403")
+                return "forbidden";
+            if (gh[1] === "429")
+                return "rate_limited";
+            return "github";
+        }
+        if (e instanceof TypeError)
+            return "network";
+    }
+    return "github";
+}
+const TEXT = {
+    not_installed: "a repo is not visible to the credential (check your GitHub access to it)",
+    credential: "the GitHub credential was refused or is not configured",
+    timeout: "GitHub did not answer in time",
+    forbidden: "GitHub refused the credential (401/403)",
+    rate_limited: "GitHub rate limit reached",
+    github: "a GitHub read failed",
+    network: "GitHub was unreachable",
+    invalid_input: "an input to the scan was invalid",
+};
+/** Fixed sentence for a reason. */
+export function failureText(r) {
+    return TEXT[r];
+}

package/dist/lib/scan/pr-source.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Read-only GitHub PR source for the local scan. Port of mnemom-api src/org-scan/scan/github-pr-source.ts
+ * (window path, PRs #4208 / #4221 / #4223).
+ *
+ * METADATA only: size counts, a CI rollup, a revert boolean and the AI tools named in the PR body.
+ * Titles and bodies are inspected in memory and dropped; author logins, branch names, and code never
+ * leave this module (PrRecord has no such field). Every call goes through `guardedGet`, which only
+ * ever issues a GET to api.github.com on an allowlisted path. Failures throw fixed-text errors:
+ * never a GitHub body, a header, a URL or the token.
+ */
+import { type GitHubCredential } from "./credential.js";
+import type { AiTool } from "./spend/prices.js";
+export declare const GITHUB_API = "https://api.github.com";
+/** Merged PRs are listed 100 at a time; a list page is one read however many PRs it holds. */
+export declare const INDEX_PAGE_SIZE = 100;
+export type CiRollup = "none" | "pending" | "success" | "failure";
+export interface PrIndexItem {
+    number: number;
+    /** YYYY-MM-DD, UTC. */
+    mergedDay: string;
+    /** YYYY-MM-DD, UTC, last activity (the listing is newest-activity first). */
+    updatedDay: string;
+    reverted: boolean;
+}
+export interface PrIndexPage {
+    items: PrIndexItem[];
+    next: string | null;
+    reads: number;
+}
+export interface PrRecord {
+    additions: number;
+    deletions: number;
+    changed_files: number;
+    ci?: CiRollup;
+    reverted: boolean;
+    /** AI tools named in the PR body, detected here so the body never leaves this module. */
+    tools: AiTool[];
+}
+export interface PrSource {
+    indexMerged(repo: string, cursor: string | null, maxReads?: number): Promise<PrIndexPage>;
+    readPr(repo: string, item: PrIndexItem, maxReads?: number): Promise<{
+        pr: PrRecord | null;
+        reads: number;
+    }>;
+}
+export interface GithubPrSourceDeps {
+    credential: GitHubCredential;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}
+/** Pure: one word from check-run conclusions. No check names, logs or URLs are kept. */
+export declare function rollupCi(runs: Array<{
+    status?: unknown;
+    conclusion?: unknown;
+}>): CiRollup;
+export declare function isAllowedScanPath(path: string): boolean;
+export declare function createGithubPrSource(deps: GithubPrSourceDeps): PrSource;

package/dist/lib/scan/pr-source.js

@@ -0,0 +1,130 @@
+/**
+ * Read-only GitHub PR source for the local scan. Port of mnemom-api src/org-scan/scan/github-pr-source.ts
+ * (window path, PRs #4208 / #4221 / #4223).
+ *
+ * METADATA only: size counts, a CI rollup, a revert boolean and the AI tools named in the PR body.
+ * Titles and bodies are inspected in memory and dropped; author logins, branch names, and code never
+ * leave this module (PrRecord has no such field). Every call goes through `guardedGet`, which only
+ * ever issues a GET to api.github.com on an allowlisted path. Failures throw fixed-text errors:
+ * never a GitHub body, a header, a URL or the token.
+ */
+import { isValidRepoSlug } from "./credential.js";
+import { detectAiTools } from "./spend/ai-tool-detect.js";
+export const GITHUB_API = "https://api.github.com";
+/** Merged PRs are listed 100 at a time; a list page is one read however many PRs it holds. */
+export const INDEX_PAGE_SIZE = 100;
+/** Pure: one word from check-run conclusions. No check names, logs or URLs are kept. */
+export function rollupCi(runs) {
+    if (runs.length === 0)
+        return "none";
+    if (runs.some((r) => r.status !== "completed"))
+        return "pending";
+    const ok = new Set(["success", "neutral", "skipped"]);
+    return runs.every((r) => typeof r.conclusion === "string" && ok.has(r.conclusion))
+        ? "success"
+        : "failure";
+}
+const isCount = (n) => typeof n === "number" && Number.isInteger(n) && n >= 0;
+const SLUG = "[A-Za-z0-9._-]{1,100}/[A-Za-z0-9._-]{1,100}";
+/** The only paths the scan may read. Anything else is refused before a request is made. */
+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$`),
+];
+export function isAllowedScanPath(path) {
+    return ALLOWED_PATHS.some((re) => re.test(path));
+}
+export function createGithubPrSource(deps) {
+    const doFetch = deps.fetchImpl ?? fetch;
+    const headers = {
+        accept: "application/vnd.github+json",
+        "x-github-api-version": "2022-11-28",
+        "user-agent": "mnemom-cli-scan/1",
+    };
+    /**
+     * `list` marks the PR list read, the first read of a repo. GitHub hides a repo the credential cannot
+     * see behind a 404, so only there is a 404 "repo not visible"; a 404 on a later detail or
+     * check-runs read is an ordinary upstream miss and keeps its numeric message (#4223).
+     */
+    async function guardedGet(path, repo, list = false) {
+        if (!isAllowedScanPath(path))
+            throw new Error("scan read not allowed");
+        const bearer = await deps.credential.tokenFor(repo);
+        const res = await doFetch(`${GITHUB_API}${path}`, {
+            method: "GET",
+            headers: { ...headers, authorization: `Bearer ${bearer}` },
+            redirect: "error",
+            signal: AbortSignal.timeout(deps.timeoutMs ?? 10_000),
+        });
+        if (!res.ok) {
+            await res.body?.cancel().catch(() => { });
+            throw new Error(list && res.status === 404
+                ? "github repo not visible"
+                : `github read failed (${res.status})`);
+        }
+        return res.json();
+    }
+    const day = (v) => {
+        const t = typeof v === "string" ? Date.parse(v) : NaN;
+        return Number.isFinite(t) ? new Date(t).toISOString().slice(0, 10) : null;
+    };
+    return {
+        async indexMerged(repo, cursor) {
+            if (!isValidRepoSlug(repo))
+                throw new Error("invalid repo");
+            const page = cursor === null ? 1 : Number(cursor);
+            if (!Number.isInteger(page) || page < 1 || page > 1000)
+                throw new Error("invalid cursor");
+            const list = (await guardedGet(`/repos/${repo}/pulls?state=closed&sort=updated&direction=desc&per_page=${INDEX_PAGE_SIZE}&page=${page}`, repo, true));
+            if (!Array.isArray(list))
+                throw new Error("unexpected list shape");
+            const items = [];
+            for (const it of list) {
+                const mergedDay = day(it.merged_at);
+                const updatedDay = day(it.updated_at);
+                if (mergedDay === null || updatedDay === null || !isCount(it.number))
+                    continue;
+                // The title is read for the revert marker only and dropped here.
+                items.push({
+                    number: it.number,
+                    mergedDay,
+                    updatedDay,
+                    reverted: typeof it.title === "string" && /^revert\b/i.test(it.title),
+                });
+            }
+            return { items, next: list.length < INDEX_PAGE_SIZE ? null : String(page + 1), reads: 1 };
+        },
+        async readPr(repo, item, maxReads = Number.POSITIVE_INFINITY) {
+            if (!isValidRepoSlug(repo))
+                throw new Error("invalid repo");
+            if (!isCount(item.number) || maxReads < 2)
+                return { pr: null, reads: 0 };
+            const detail = (await guardedGet(`/repos/${repo}/pulls/${item.number}`, repo));
+            let reads = 1;
+            let ci;
+            const sha = detail.head?.sha;
+            if (typeof sha === "string" && /^[0-9a-f]{40}$/.test(sha)) {
+                const checks = (await guardedGet(`/repos/${repo}/commits/${sha}/check-runs?per_page=100`, repo));
+                reads += 1;
+                ci = rollupCi(Array.isArray(checks.check_runs) ? checks.check_runs : []);
+            }
+            if (!isCount(detail.additions) ||
+                !isCount(detail.deletions) ||
+                !isCount(detail.changed_files))
+                return { pr: null, reads };
+            const tools = detectAiTools(detail.body);
+            return {
+                pr: {
+                    additions: detail.additions,
+                    deletions: detail.deletions,
+                    changed_files: detail.changed_files,
+                    ci,
+                    reverted: item.reverted,
+                    tools,
+                },
+                reads,
+            };
+        },
+    };
+}

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

@@ -0,0 +1,49 @@
+/**
+ * The org's Record totals for the scan preview: one read of
+ * `GET /v1/orgs/:org_id/record/totals?from=&to=` (window form, contract i2-totals-window v1.2).
+ * 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
+ * window, not the PR scan period, and the report labels it "last 30 days"; no other scan-window
+ * number is ever produced here.
+ *
+ * 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.
+ *   auth          401/403 or a missing login: throws RecordAuthError (fail closed).
+ */
+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;
+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 {
+    constructor();
+}
+export interface RecordWindow {
+    from: string;
+    to: string;
+}
+export type RecordOutcome = {
+    status: "ok";
+    totals: RecordWindowTotals;
+    window: RecordWindow;
+} | {
+    status: "not_in_cohort";
+} | {
+    status: "unavailable";
+};
+export interface RecordDeps {
+    fetchTotals?: (orgId: string, from: string, to: string, signal: AbortSignal) => Promise<unknown>;
+    now?: () => number;
+    timeoutMs?: number;
+}
+export declare function recordWindow(nowMs: number): RecordWindow;
+/** Shape-check the body: a malformed answer is "unavailable", never rendered. */
+export declare function parseWindowTotals(v: unknown): RecordWindowTotals | null;
+/** Never throws except RecordAuthError (401/403, fail closed). */
+export declare function fetchRecordTotals(orgId: string, deps?: RecordDeps): Promise<RecordOutcome>;