@mnemom/mnemom 0.17.37 → 0.17.38-next.0

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

@@ -15,6 +15,7 @@ import { type HttpResult, type RunnerApi } from "./executor-client.js";
 import { type OutcomeFields, type RefusedReason } from "./outcome.js";
 import { type PhaseInvocation } from "./phases.js";
 import { type ModelProxy, type ProxyState } from "./proxy.js";
+import type { RecordCommitBody } from "./record-commit.js";
 import { type RunnerFailMode } from "./settings.js";
 /** A claimed job's working copy. */
 export interface Workspace {
@@ -45,6 +46,13 @@ export interface JobDeps {
     openPr(repo: string, ws: Workspace, title: string, body: string): Promise<string>;
     /** Commits on the job branch that the base does not have; 0 means there is nothing to open. */
     commitsAhead(ws: Workspace): Promise<number>;
+    /** The working copy's HEAD sha before a phase runs; null only for a clone with no commit. Throws otherwise. */
+    headSha(ws: Workspace): Promise<string | null>;
+    /**
+     * RecordCommit/v1 bodies for the commits made since `since` (null: since the base), oldest
+     * first, under `lineageKey` and the job's repo. A commit that cannot be read is left out.
+     */
+    commitBodies(ws: Workspace, since: string | null, lineageKey: string, repo: string): Promise<RecordCommitBody[]>;
     enableAutoMerge(prUrl: string): Promise<void>;
     cleanup(ws: Workspace): Promise<void>;
 }
@@ -69,6 +77,35 @@ export declare function authRefusal(r: HttpResult): RefusedReason | null;
  * outcome. Throws only on a runner bug.
  */
 export declare function runJob(sessionId: string, opts: JobOptions, deps: JobDeps): Promise<JobResult>;
+/** What the job reported to Record's commit index; logged once, never part of the outcome. */
+export interface CommitReport {
+    reported: number;
+    /** Refused by the api (4xx other than 404) or unreachable: left out of the index. */
+    dropped: number;
+    /** Made in a phase whose model calls left no lineage key, so there was nothing to file under. */
+    unlinked: number;
+    /** Phases whose starting HEAD could not be read: their commits are never guessed at. */
+    skipped: number;
+    /** The index answered 404 (Record dark for the org): nothing more is sent for this job. */
+    dark: boolean;
+}
+/** Waits before each retry of a 429, 5xx or unreachable report; then the commit is dropped. */
+export declare const COMMIT_RETRY_MS: readonly [1000, 3000];
+/**
+ * Report the commits one phase made (ruling 34.05 (a)): each under the lineage key the gateway
+ * answered for that phase's conversation, with the lease key, from this process. Never throws and
+ * never changes the outcome; the lease key is sent only as the request credential, never logged.
+ */
+export declare function reportPhaseCommits(deps: JobDeps, report: CommitReport, p: {
+    ws: Workspace;
+    /** The HEAD before the phase; null: a clone with no commit; undefined: it could not be read. */
+    before: string | null | undefined;
+    conversationId: string;
+    proxy: Pick<ModelProxy, "lineageFor">;
+    orgId: string;
+    repo: string;
+    leaseKey: string;
+}): Promise<void>;
 /**
  * Report a failed job after claim (34.12 (6), (10)); a refusal releases the lease instead. The
  * fail reason vocabulary is the Durable lead's to rule (A3 accepts only transcript_lost today); a

package/dist/lib/runner/job.js

@@ -20,7 +20,7 @@ import { errorCode, errorDetails } from "./executor-client.js";
 import { doneOutcome, failedOutcome, phaseReason, refusedOutcome, } from "./outcome.js";
 import { planPhase } from "./phases.js";
 import { canonNodeKey, prBody } from "./pr-body.js";
-import { requestSummary } from "./proxy.js";
+import { phaseConversationId, requestSummary } from "./proxy.js";
 import { resolveMergeStrategy } from "./settings.js";
 const TOLERATED = RUNNER_OPEN_MODE_TOLERATED;
 const OPEN_MODE_RETRIES = 3;
@@ -189,6 +189,13 @@ export async function runJob(sessionId, opts, deps) {
     let leaseLost = false;
     let ws = null;
     let proxy = null;
+    const commits = {
+        reported: 0,
+        dropped: 0,
+        unlinked: 0,
+        skipped: 0,
+        dark: false,
+    };
     let heartbeat = null;
     const phaseAbort = new AbortController();
     const onStop = () => phaseAbort.abort();
@@ -303,10 +310,17 @@ export async function runJob(sessionId, opts, deps) {
             contractValue: header.value,
             leaseKey: claim.leaseKey,
             agentId: job.agent_id,
+            conversationId: phaseConversationId(sessionId, claim.epoch, phases[0].order),
         };
         proxy = await deps.startProxy(state);
         let opensPr = false;
         for (const phase of phases) {
+            state.conversationId = phaseConversationId(sessionId, claim.epoch, phase.order);
+            // undefined: the HEAD could not be read, so this phase's commits cannot be told apart.
+            const before = await deps.headSha(ws).catch((e) => {
+                deps.log(`reading HEAD before phase ${phase.order} failed: ${e.message}`);
+                return undefined;
+            });
             const planned = planPhase(phase);
             if (!planned.ok) {
                 deps.log(`phase ${phase.order} ${phase.name}: ${planned.detail}`);
@@ -354,6 +368,15 @@ export async function runJob(sessionId, opts, deps) {
                 }
                 break;
             }
+            await reportPhaseCommits(deps, commits, {
+                ws,
+                before,
+                conversationId: state.conversationId,
+                proxy,
+                orgId: bundle.org_id,
+                repo: job.repo,
+                leaseKey: claim.leaseKey,
+            });
         }
         if (opensPr) {
             try {
@@ -390,12 +413,62 @@ export async function runJob(sessionId, opts, deps) {
             await proxy.close();
             // One line per job that reached its phases: what every model request carried (W3.11).
             deps.log(`model requests: ${JSON.stringify(requestSummary(proxy.forwarded))}`);
+            deps.log(`commits reported: ${JSON.stringify(commits)}`);
         }
         // A workspace left behind never changes the outcome; it is logged for the operator.
         if (ws)
             await deps.cleanup(ws).catch((e) => deps.log(`cleanup failed: ${e.message}`));
     }
 }
+/** Waits before each retry of a 429, 5xx or unreachable report; then the commit is dropped. */
+export const COMMIT_RETRY_MS = [1_000, 3_000];
+/**
+ * Report the commits one phase made (ruling 34.05 (a)): each under the lineage key the gateway
+ * answered for that phase's conversation, with the lease key, from this process. Never throws and
+ * never changes the outcome; the lease key is sent only as the request credential, never logged.
+ */
+export async function reportPhaseCommits(deps, report, p) {
+    if (report.dark)
+        return;
+    if (p.before === undefined) {
+        report.skipped += 1;
+        deps.log(`${p.conversationId}: commits not reported, the phase's starting HEAD is unknown`);
+        return;
+    }
+    try {
+        const lineageKey = p.proxy.lineageFor(p.conversationId);
+        if (lineageKey === null) {
+            const n = (await deps.commitBodies(p.ws, p.before, "-", p.repo)).length;
+            report.unlinked += n;
+            if (n > 0)
+                deps.log(`${n} commit(s) in ${p.conversationId} have no lineage key: not reported`);
+            return;
+        }
+        for (const body of await deps.commitBodies(p.ws, p.before, lineageKey, p.repo)) {
+            let res = await deps.api.recordCommit(p.orgId, body, p.leaseKey);
+            for (const wait of COMMIT_RETRY_MS) {
+                if (!(res.status === 0 || res.status === 429 || res.status >= 500))
+                    break;
+                await deps.sleep(wait);
+                res = await deps.api.recordCommit(p.orgId, body, p.leaseKey);
+            }
+            if (res.status >= 200 && res.status < 300)
+                report.reported += 1;
+            else if (res.status === 404) {
+                report.dark = true;
+                deps.log("the commit index answered 404 (Record is off for this org): commits not reported");
+                return;
+            }
+            else {
+                report.dropped += 1;
+                deps.log(`commit ${body.sha.slice(0, 12)} not reported: ${res.code ?? res.networkError ?? res.status}`);
+            }
+        }
+    }
+    catch (e) {
+        deps.log(`commit report failed: ${e.message}`);
+    }
+}
 async function fetchBundle(deps, sessionId, claim) {
     const [jwksRes, res] = await Promise.all([
         deps.api.jwks(),

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

@@ -15,8 +15,13 @@ export declare const CAPABILITY_TOOLS: Readonly<Record<string, {
     tools: string[];
     allowed: string[];
 }>>;
-/** Env names a phase may inherit: a working PATH and locale. Nothing else. */
-export declare const PHASE_ENV_PASSTHROUGH: readonly ["PATH", "LANG", "TZ"];
+/**
+ * Env names a phase may inherit: a working PATH, the shell and locale. Nothing else. Claude Code's
+ * Bash tool needs SHELL to name a POSIX shell; without it, on an image with no bash on PATH (Alpine),
+ * every Bash call fails and a phase can write files but never commit them (door2-path image run
+ * 41940973594 ended pr_no_changes).
+ */
+export declare const PHASE_ENV_PASSTHROUGH: readonly ["PATH", "SHELL", "LANG", "TZ"];
 /** Not a secret: lets claude start; the proxy drops it before the gateway (ruling: option (i)). */
 export declare const PHASE_MODEL_KEY_PLACEHOLDER = "mnemom-runner-placeholder";
 export type ToolGrant = {

package/dist/lib/runner/phases.js

@@ -21,8 +21,13 @@ export const CAPABILITY_TOOLS = Object.freeze({
     // The runner opens the PR itself once every phase has passed; the model gets no tool for it.
     "pr.open": { tools: [], allowed: [] },
 });
-/** Env names a phase may inherit: a working PATH and locale. Nothing else. */
-export const PHASE_ENV_PASSTHROUGH = ["PATH", "LANG", "TZ"];
+/**
+ * Env names a phase may inherit: a working PATH, the shell and locale. Nothing else. Claude Code's
+ * Bash tool needs SHELL to name a POSIX shell; without it, on an image with no bash on PATH (Alpine),
+ * every Bash call fails and a phase can write files but never commit them (door2-path image run
+ * 41940973594 ended pr_no_changes).
+ */
+export const PHASE_ENV_PASSTHROUGH = ["PATH", "SHELL", "LANG", "TZ"];
 /** Not a secret: lets claude start; the proxy drops it before the gateway (ruling: option (i)). */
 export const PHASE_MODEL_KEY_PLACEHOLDER = "mnemom-runner-placeholder";
 export function toolsFor(capabilityIds) {

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

@@ -7,24 +7,39 @@
  * 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,
+ * sees the lease key. Each phase gets its own `x-mnemom-conversation-id` (from the session, lease
+ * epoch and phase order), so the gateway keys one lineage per phase instead of a body-hash one per
+ * request, and the `x-mnemom-lineage-key` it answers is kept for the phase's commit report. A 409 `contract_mismatch` from the gateway (34.11) is reported to the job,
  * which refetches and continues only on a higher sealed version, else fails closed.
  */
 import { request as httpRequest, type IncomingMessage, type ServerResponse } from "node:http";
 export declare const LEASE_KEY_HEADER = "x-mnemom-api-key";
 export declare const AGENT_ID_HEADER = "x-mnemom-agent-id";
+export declare const CONVERSATION_ID_HEADER = "x-mnemom-conversation-id";
+export declare const LINEAGE_KEY_HEADER = "x-mnemom-lineage-key";
+/**
+ * One phase's conversation id: the session, the lease epoch and the phase order, so a retried
+ * claim or another phase never shares a lineage. Within the gateway's 1-256 printable, no-`#` id.
+ */
+export declare function phaseConversationId(sessionId: string, epoch: number, order: number): string;
 export interface ProxyState {
     /** The sealed header value to send; swapped in place after an accepted amend. */
     contractValue: string;
     leaseKey: string;
     /** The session's agent, from the job read; always sent, a phase's own value never is. */
     agentId: string;
+    /** The running phase's conversation id; the job sets it before each phase. */
+    conversationId: string;
 }
 export interface ForwardedRequest {
     method: string;
     path: string;
     contract: string;
     status: number;
+    /** The conversation id the request carried. */
+    conversation: string;
+    /** The gateway's `x-mnemom-lineage-key` answer, when it sent a well-formed one. */
+    lineage: string | null;
 }
 export interface ModelProxy {
     url: string;
@@ -34,17 +49,26 @@ export interface ModelProxy {
     contractMismatch: {
         expected_version: number | null;
     } | null;
+    /** The lineage key the gateway last answered for a conversation id, or null when none came. */
+    lineageFor(conversationId: string): string | null;
     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, modelKey: string): Record<string, string | string[] | undefined>;
-/** What the job's model requests carried: each contract by its sha256, in first-seen order. */
+/**
+ * What the job's model requests carried: each contract by its sha256, in first-seen order, and the
+ * lineage key the gateway answered for each conversation (one per phase), in first-seen order.
+ */
 export interface RequestSummary {
     count: number;
     contracts: {
         contract_sha256: string;
         requests: number;
     }[];
+    lineages: {
+        conversation_id: string;
+        lineage_key: string | null;
+    }[];
 }
 /**
  * One job's forwarded requests, summarised for the operator's log and for the door2-path header

package/dist/lib/runner/proxy.js

@@ -7,7 +7,9 @@
  * 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,
+ * sees the lease key. Each phase gets its own `x-mnemom-conversation-id` (from the session, lease
+ * epoch and phase order), so the gateway keys one lineage per phase instead of a body-hash one per
+ * request, and the `x-mnemom-lineage-key` it answers is kept for the phase's commit report. A 409 `contract_mismatch` from the gateway (34.11) is reported to the job,
  * which refetches and continues only on a higher sealed version, else fails closed.
  */
 import { createServer, request as httpRequest, } from "node:http";
@@ -16,6 +18,17 @@ 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";
+export const CONVERSATION_ID_HEADER = "x-mnemom-conversation-id";
+export const LINEAGE_KEY_HEADER = "x-mnemom-lineage-key";
+/** The gateway's lineage key as echoed: short, printable, no spaces. Anything else is not kept. */
+const LINEAGE_KEY_RE = /^[\x21-\x7e]{1,256}$/;
+/**
+ * One phase's conversation id: the session, the lease epoch and the phase order, so a retried
+ * claim or another phase never shares a lineage. Within the gateway's 1-256 printable, no-`#` id.
+ */
+export function phaseConversationId(sessionId, epoch, order) {
+    return `durable-${sessionId}-e${epoch}-p${order}`;
+}
 /** Hop-by-hop headers (RFC 9110 7.6.1) and the ones the proxy owns. */
 const DROP = new Set([
     "connection",
@@ -43,8 +56,16 @@ export function outboundHeaders(incoming, state, modelKey) {
     kept[LEASE_KEY_HEADER] = state.leaseKey;
     kept["x-api-key"] = modelKey;
     kept[AGENT_ID_HEADER] = state.agentId;
+    kept[CONVERSATION_ID_HEADER] = state.conversationId;
     return applySealedContract(kept, state.contractValue);
 }
+/** The last well-formed lineage key answered for each conversation, in first-seen order. */
+function lineagesOf(forwarded) {
+    const m = new Map();
+    for (const f of forwarded)
+        m.set(f.conversation, f.lineage ?? m.get(f.conversation) ?? null);
+    return m;
+}
 /**
  * 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.
@@ -58,6 +79,10 @@ export function requestSummary(forwarded) {
     return {
         count: forwarded.length,
         contracts: [...by].map(([contract_sha256, requests]) => ({ contract_sha256, requests })),
+        lineages: [...lineagesOf(forwarded)].map(([conversation_id, lineage_key]) => ({
+            conversation_id,
+            lineage_key,
+        })),
     };
 }
 /** The largest 409 body the proxy reads for a contract mismatch. */
@@ -102,11 +127,13 @@ export async function startModelProxy(gatewayUrl, state, modelKey) {
         url: "",
         forwarded,
         contractMismatch: null,
+        lineageFor: (id) => lineagesOf(forwarded).get(id) ?? null,
         close: async () => { },
     };
     const server = createServer((req, res) => {
         const headers = outboundHeaders(req.headers, state, modelKey);
         const sent = headers[CONTRACT_HEADER];
+        const conversation = state.conversationId;
         const out = send({
             protocol: upstream.protocol,
             hostname: upstream.hostname,
@@ -116,11 +143,14 @@ export async function startModelProxy(gatewayUrl, state, modelKey) {
             headers,
         }, (up) => {
             const status = up.statusCode ?? 502;
+            const echoed = up.headers[LINEAGE_KEY_HEADER];
             forwarded.push({
                 method: req.method ?? "GET",
                 path: req.url ?? "/",
                 contract: sent,
                 status,
+                conversation,
+                lineage: typeof echoed === "string" && LINEAGE_KEY_RE.test(echoed) ? echoed : null,
             });
             if (status === 409) {
                 // Buffered to read the mismatch, up to a cap; a larger body is relayed unread.
@@ -162,6 +192,8 @@ export async function startModelProxy(gatewayUrl, state, modelKey) {
                 path: req.url ?? "/",
                 contract: sent,
                 status: 502,
+                conversation,
+                lineage: null,
             });
             upstreamFailed(res, e);
         });

package/dist/lib/runner/record-commit.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The RecordCommit/v1 body Record's commit index takes (`POST /v1/orgs/{org}/record/commits`).
+ * It lives here so the runner can type its commit report without loading the CLI's commit reporter
+ * (which spawns git and reads auth); lib/commit-report.ts re-exports both names.
+ */
+/** The commit index body's schema tag (shared with the fleet worker's reporter). */
+export declare const COMMIT_SCHEMA = "RecordCommit/v1";
+/** RecordCommit/v1: strings only, every field required; the route rejects an unknown field. */
+export interface RecordCommitBody {
+    schema: typeof COMMIT_SCHEMA;
+    lineage_key: string;
+    repo: string;
+    branch: string;
+    sha: string;
+    patch_id: string;
+}

package/dist/lib/runner/record-commit.js

@@ -0,0 +1,7 @@
+/**
+ * The RecordCommit/v1 body Record's commit index takes (`POST /v1/orgs/{org}/record/commits`).
+ * It lives here so the runner can type its commit report without loading the CLI's commit reporter
+ * (which spawns git and reads auth); lib/commit-report.ts re-exports both names.
+ */
+/** The commit index body's schema tag (shared with the fleet worker's reporter). */
+export const COMMIT_SCHEMA = "RecordCommit/v1";

package/dist/lib/scan/spend/anthropic-usage.d.ts

@@ -1,12 +1,24 @@
 export declare const ANTHROPIC_ADMIN_ORIGIN = "https://api.anthropic.com";
 export declare const ADMIN_KEY_ENV = "ANTHROPIC_ADMIN_KEY";
+/** The only paths a usage credential is ever sent to (design T18: fenced to report endpoints). */
+export declare const REPORT_PATHS: readonly string[];
+/** The fence, as one exported check so it is directly testable. Throws AnthropicUsageError for any other path. */
+export declare function assertReportPath(path: string): void;
+/** The exact auth header to send; same shape as mnemom-api src/org-scan/usage/credential-source.ts. */
+export type AnthropicAuthHeader = {
+    header: "x-api-key";
+    value: string;
+} | {
+    header: "authorization";
+    value: string;
+};
 export declare const DEFAULT_MAX_PAGES = 20;
 /** One shared deadline for a request including its retries (not N x timeout). */
 export declare const DEFAULT_TIMEOUT_MS = 15000;
 export declare const DEFAULT_MAX_RETRIES = 2;
 /** Shape check only; the key is never echoed, even on a mismatch. */
 export declare const isAdminKeyShape: (k: unknown) => k is string;
-export type UsageFailure = "key_invalid" | "key_refused" | "rate_limited" | "timeout" | "network" | "upstream" | "malformed" | "too_large";
+export type UsageFailure = "key_invalid" | "key_refused" | "token_refused" | "rate_limited" | "timeout" | "network" | "upstream" | "malformed" | "too_large";
 /** Fixed sentence for a failure reason. */
 export declare const usageFailureText: (r: UsageFailure) => string;
 /** Carries only a reason tag. Its message is the fixed sentence: nothing upstream can reach it. */
@@ -55,3 +67,10 @@ export declare function fetchMeasuredUsage(key: string | undefined, period: {
     start: string;
     end: string;
 }, deps?: AnthropicUsageDeps): Promise<MeasuredUsage>;
+/** A WIF access token as the bearer for the two report reads. Printable ASCII only, else key_invalid. */
+export declare function bearerAuth(token: string): AnthropicAuthHeader;
+/** The two reads with an already-resolved credential (pasted key or WIF bearer). Throws AnthropicUsageError only. */
+export declare function fetchMeasuredUsageWithAuth(auth: AnthropicAuthHeader, period: {
+    start: string;
+    end: string;
+}, deps?: AnthropicUsageDeps): Promise<MeasuredUsage>;

package/dist/lib/scan/spend/anthropic-usage.js

@@ -1,6 +1,11 @@
 // MNE-9298 Tier 1: the CTO's own Anthropic Admin key, used LOCALLY, to read measured usage. Port of
 // mnemom-api src/org-scan/usage/usage-client.ts (two read-only GETs: usage_report/messages grouped by
-// context_window, and cost_report) with the server-only parts (egress allowlist, WIF) dropped.
+// context_window, and cost_report) with the server-only parts (egress allowlist) dropped.
+//
+// MNE-9706: the reads take either credential, as the server's credential-source.ts does: the pasted Admin
+// key (x-api-key) or a short-lived WIF access token (Authorization: Bearer, see anthropic-wif.ts). Either
+// one is sent ONLY to the two report paths below; walk() refuses any other path (the fence, design T18:
+// Anthropic's WIF scope for these reports is org:admin, so the fence has to live here).
 //
 // The key is held in memory for the length of the two reads. It is never stored, logged, written to disk,
 // echoed, put in argv, a URL or an error message, and is sent only to api.anthropic.com (a constant, not
@@ -11,6 +16,13 @@ export const ADMIN_KEY_ENV = "ANTHROPIC_ADMIN_KEY";
 const ANTHROPIC_VERSION = "2023-06-01";
 const USAGE_PATH = "/v1/organizations/usage_report/messages";
 const COST_PATH = "/v1/organizations/cost_report";
+/** The only paths a usage credential is ever sent to (design T18: fenced to report endpoints). */
+export const REPORT_PATHS = [USAGE_PATH, COST_PATH];
+/** The fence, as one exported check so it is directly testable. Throws AnthropicUsageError for any other path. */
+export function assertReportPath(path) {
+    if (!REPORT_PATHS.includes(path))
+        throw new AnthropicUsageError("malformed");
+}
 export const DEFAULT_MAX_PAGES = 20;
 /** One shared deadline for a request including its retries (not N x timeout). */
 export const DEFAULT_TIMEOUT_MS = 15_000;
@@ -22,6 +34,7 @@ export const isAdminKeyShape = (k) => typeof k === "string" && ADMIN_KEY_RE.test
 const FAILURE_TEXT = {
     key_invalid: "The Anthropic admin key is not an Admin API key (it should start with sk-ant-admin).",
     key_refused: "Anthropic refused the admin key (401/403).",
+    token_refused: "Anthropic refused the workload identity token for the usage reports (401/403). The federation rule needs scope org:admin.",
     rate_limited: "Anthropic rate limit reached.",
     timeout: "Anthropic did not answer in time.",
     network: "Anthropic was unreachable.",
@@ -96,14 +109,14 @@ function retryWait(res, attempt) {
     return Number.isFinite(ra) && ra > 0 ? ra * 1000 : backoff(attempt);
 }
 class Reader {
-    key;
+    auth;
     fetchImpl;
     sleep;
     maxPages;
     timeoutMs;
     maxRetries;
-    constructor(key, deps) {
-        this.key = key;
+    constructor(auth, deps) {
+        this.auth = auth;
         this.fetchImpl = deps.fetchImpl ?? ((...a) => fetch(...a));
         this.sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
         this.maxPages = deps.maxPages ?? DEFAULT_MAX_PAGES;
@@ -111,6 +124,8 @@ class Reader {
         this.maxRetries = deps.maxRetries ?? DEFAULT_MAX_RETRIES;
     }
     async walk(path, base, parse, callMaxPages) {
+        // The fence: the credential goes to the two report paths and nowhere else.
+        assertReportPath(path);
         const ceiling = typeof callMaxPages === "number" && Number.isFinite(callMaxPages) && callMaxPages >= 1
             ? Math.min(this.maxPages, Math.floor(callMaxPages))
             : this.maxPages;
@@ -154,7 +169,7 @@ class Reader {
                 res = await this.fetchImpl(url, {
                     method: "GET",
                     headers: {
-                        "x-api-key": this.key,
+                        [this.auth.header]: this.auth.value,
                         "anthropic-version": ANTHROPIC_VERSION,
                         accept: "application/json",
                     },
@@ -185,7 +200,7 @@ class Reader {
             }
             await res.body?.cancel().catch(() => { });
             if (res.status === 401 || res.status === 403)
-                throw new AnthropicUsageError("key_refused");
+                throw new AnthropicUsageError(this.auth.header === "x-api-key" ? "key_refused" : "token_refused");
             const retryable = res.status === 429 || res.status >= 500;
             const wait = retryable ? retryWait(res, attempt + 1) : 0;
             if (retryable &&
@@ -209,11 +224,21 @@ export async function fetchMeasuredUsage(key, period, deps = {}) {
     const k = key?.trim();
     if (!k || !isAdminKeyShape(k))
         throw new AnthropicUsageError("key_invalid");
+    return fetchMeasuredUsageWithAuth({ header: "x-api-key", value: k }, period, deps);
+}
+/** A WIF access token as the bearer for the two report reads. Printable ASCII only, else key_invalid. */
+export function bearerAuth(token) {
+    if (!/^[\x21-\x7e]{8,4096}$/.test(token))
+        throw new AnthropicUsageError("key_invalid");
+    return { header: "authorization", value: `Bearer ${token}` };
+}
+/** The two reads with an already-resolved credential (pasted key or WIF bearer). Throws AnthropicUsageError only. */
+export async function fetchMeasuredUsageWithAuth(auth, period, deps = {}) {
     if (!validDay(period.start) || !validDay(period.end))
         throw new AnthropicUsageError("malformed");
     const startingAt = alignStartingAt(`${period.start}T00:00:00Z`);
     const endingAt = new Date(Date.parse(`${period.end}T00:00:00Z`) + DAY_MS).toISOString();
-    const reader = new Reader(k, deps);
+    const reader = new Reader(auth, deps);
     const up = new URLSearchParams({
         starting_at: startingAt,
         ending_at: endingAt,

package/dist/lib/scan/spend/anthropic-wif.d.ts

@@ -0,0 +1,42 @@
+export declare const WIF_EXCHANGE_URL = "https://api.anthropic.com/v1/oauth/token";
+export declare const WIF_ENV: {
+    readonly rule: "ANTHROPIC_FEDERATION_RULE_ID";
+    readonly org: "ANTHROPIC_ORGANIZATION_ID";
+    readonly serviceAccount: "ANTHROPIC_SERVICE_ACCOUNT_ID";
+    readonly workspace: "ANTHROPIC_WORKSPACE_ID";
+};
+/** Same ceiling the server held a WIF token to (credential-source.ts MAX_WIF_TOKEN_LIFETIME_MS). */
+export declare const MAX_WIF_TOKEN_LIFETIME_MS = 300000;
+export interface WifConfig {
+    federationRuleId: string;
+    organizationId: string;
+    serviceAccountId: string;
+    workspaceId?: string;
+}
+export type WifFailure = "config_invalid" | "assertion_unavailable" | "assertion_refused" | "exchange_refused" | "exchange_failed";
+export declare const wifFailureText: (r: WifFailure) => string;
+export declare const WIF_FALLBACK_NOTE = "Falling back to the pasted Anthropic Admin key.";
+/** Carries only a reason tag; its message is the fixed sentence. */
+export declare class WifError extends Error {
+    readonly reason: WifFailure;
+    constructor(reason: WifFailure);
+}
+/**
+ * Reads the WIF ids from env. None of the three required ids set: null (WIF is not set up, no message).
+ * Some set, or any malformed: WifError("config_invalid"), so a half-done setup is said out loud.
+ */
+export declare function readWifConfig(env: NodeJS.ProcessEnv): WifConfig | null;
+export interface WifDeps {
+    /** Step 1 seam: returns the assertion for the org. Defaults to the mnemom-api route with the CLI's auth. */
+    mintAssertion?: (orgId: string) => Promise<unknown>;
+    /** Step 2 seam: the fetch used ONLY for the Anthropic exchange. */
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}
+export interface WifAccessToken {
+    accessToken: string;
+    /** Epoch ms, clamped to MAX_WIF_TOKEN_LIFETIME_MS from receipt. */
+    expiresAt: number;
+}
+/** Steps 1 and 2. Throws WifError only. */
+export declare function obtainWifAccessToken(orgId: string, cfg: WifConfig, deps?: WifDeps): Promise<WifAccessToken>;