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

package/dist/lib/runner/job.js

@@ -11,7 +11,8 @@
  * Every side effect is in `JobDeps`, so each arm is tested; `liveJobDeps` (commands/agent-run.ts)
  * is the thin driver.
  */
-import { RUNNER_OPEN_MODE_TOLERATED, claimNeedsKeyRetry, } from "../../vendor/durable-contract/index.js";
+import { EXECUTOR_WRITABLE_KINDS, RUNNER_OPEN_MODE_TOLERATED, claimNeedsKeyRetry, } from "../../vendor/durable-contract/index.js";
+import { spawnIdempotencyKey } from "./exec-append.js";
 import { canonicalJson } from "../canonical-json.js";
 import { verifyServedPhaseBundle } from "./bundle.js";
 import { sealedContractHeader } from "./contract-header.js";
@@ -133,6 +134,8 @@ async function claimSession(deps, sessionId) {
         },
     };
 }
+/** A header-safe agent id; the gateway compares it with the lease's session. */
+const AGENT_ID_RE = /^[A-Za-z0-9_.:-]{1,128}$/;
 function parseJob(body) {
     if (!body || typeof body !== "object")
         return null;
@@ -147,7 +150,11 @@ function parseJob(body) {
         return null;
     if (sha === null || version === null || typeof b.contract !== "string")
         return null;
-    return { repo, contract_sha256: sha, version, contract: b.contract };
+    // No agent id, no job: a model request without x-mnemom-agent-id would be refused anyway.
+    const agentId = str(b.agent_id);
+    if (agentId === null || !AGENT_ID_RE.test(agentId))
+        return null;
+    return { repo, agent_id: agentId, contract_sha256: sha, version, contract: b.contract };
 }
 /**
  * Run one candidate session to an outcome. Never throws for a Mnemom error: every one is an
@@ -189,15 +196,19 @@ export async function runJob(sessionId, opts, deps) {
     };
     const refuse = async (reason, detail) => {
         deps.log(`refused (${reason}): ${detail}`);
-        await reportFail(deps, sessionId, claim.epoch, "runner_refused", reason);
+        // A refusal hands the lease back: S1's fail reasons are closed, and the api refuses
+        // runner_refused as durable_reason_invalid, which left the session leased until it lapsed.
+        await release(deps, sessionId, claim.epoch);
         return { kind: "outcome", outcome: refusedOutcome(facts, reason) };
     };
     try {
         // Register the spawn, then hello: the session moves to running and the lease is ours.
         const ap = await deps.api.append(sessionId, {
-            kind: "executor.spawned",
-            detail: { spawn_id: spawnId },
+            kind: EXECUTOR_WRITABLE_KINDS[0], // executor.spawned
+            refs: { spawn_id: spawnId },
+            idempotency_key: spawnIdempotencyKey(sessionId, claim.epoch, spawnId),
             expected_epoch: claim.epoch,
+            nonce: deps.nonce,
         });
         if (!ok2xx(ap))
             return await refuse(routeRefusal(ap), `register spawn: ${ap.code ?? ap.status}`);
@@ -279,7 +290,11 @@ export async function runJob(sessionId, opts, deps) {
             await reportFail(deps, sessionId, claim.epoch, "runner_failed", reason);
             return { kind: "outcome", outcome: failedOutcome(facts, reason) };
         }
-        const state = { contractValue: header.value, leaseKey: claim.leaseKey };
+        const state = {
+            contractValue: header.value,
+            leaseKey: claim.leaseKey,
+            agentId: job.agent_id,
+        };
         proxy = await deps.startProxy(state);
         let opensPr = false;
         for (const phase of phases) {
@@ -309,7 +324,7 @@ export async function runJob(sessionId, opts, deps) {
                 if (proxy.contractMismatch && !amended) {
                     // 34.11: the charter moved. Continue only on a higher sealed version with both the job
                     // and a fresh bundle bound to it; then the phase runs again under the new seal.
-                    const next = await amendedSeal(deps, sessionId, claim, bundle);
+                    const next = await amendedSeal(deps, sessionId, claim, bundle, job.agent_id);
                     if (!next)
                         return await refuse("contract_mismatch_unrecoverable", "the amended seal did not check out");
                     state.contractValue = next.value;
@@ -333,6 +348,12 @@ export async function runJob(sessionId, opts, deps) {
         }
         if (opensPr) {
             try {
+                // Checked before the push, so an empty diff never reaches GitHub's 422 (amendment 59).
+                if ((await deps.commitsAhead(ws)) === 0) {
+                    deps.log("no commits ahead of the base: there is no PR to open");
+                    await reportFail(deps, sessionId, claim.epoch, "runner_failed", "pr_no_changes");
+                    return { kind: "outcome", outcome: failedOutcome(facts, "pr_no_changes") };
+                }
                 facts.pr_url = await deps.openPr(job.repo, ws, `mnemom: ${bundle.workflow.id} job ${sessionId.slice(0, 8)}`);
             }
             catch (e) {
@@ -381,19 +402,29 @@ async function fetchBundle(deps, sessionId, claim) {
             detail: `jwks: ${jwksRes.networkError ?? jwksRes.status}`,
         };
     }
-    if (claim.executorId === null) {
-        // No answer named this runner's executor id, so the bundle cannot be bound to the claim.
+    if (deps.executorId !== null &&
+        claim.executorId !== null &&
+        deps.executorId !== claim.executorId) {
+        return {
+            kind: "refused",
+            reason: "bundle_binding_mismatch",
+            detail: "the claim answer names another executor_id than this runner's",
+        };
+    }
+    const executorId = deps.executorId ?? claim.executorId;
+    if (executorId === null) {
+        // Neither the runner nor the claim answer names the executor id, so the bundle cannot be bound.
         return {
             kind: "refused",
             reason: "bundle_binding_mismatch",
-            detail: "the claim answer named no executor_id",
+            detail: `no executor_id: set MNEMOM_EXECUTOR_ID, the claim answer named none`,
         };
     }
     const v = verifyServedPhaseBundle(res.text, jwksRes.body, {
         org_id: orgOf(res.body),
         session_id: sessionId,
         epoch: claim.epoch,
-        executor_id: claim.executorId,
+        executor_id: executorId,
         contract_sha256: claim.contractSha256,
         contract_version: claim.contractVersion,
     }, { now: deps.now });
@@ -410,11 +441,14 @@ function orgOf(body) {
     const o = body?.org_id;
     return typeof o === "string" ? o : "";
 }
-async function amendedSeal(deps, sessionId, claim, running) {
+async function amendedSeal(deps, sessionId, claim, running, agentId) {
     const jr = await deps.api.job(sessionId);
     const job = jr.status === 200 ? parseJob(jr.body) : null;
     if (!job || job.version <= claim.contractVersion)
         return null;
+    // An amend never moves the session to another agent.
+    if (job.agent_id !== agentId)
+        return null;
     const fresh = await fetchBundle(deps, sessionId, {
         ...claim,
         contractSha256: job.contract_sha256,
@@ -438,9 +472,9 @@ function sameWork(a, b) {
         canonicalJson({ workflow: b.workflow, phases: b.phases }));
 }
 /**
- * Report a failed or refused job after claim (34.12 (6), (10)). The fail reason vocabulary is the
- * Durable lead's to rule (A3 accepts only transcript_lost today); a refused report is logged and
- * never changes the outcome, because the lease lapses on its own.
+ * 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
+ * fail the api refuses is logged and never changes the outcome, because the lease lapses on its own.
  */
 export async function reportFail(deps, sessionId, epoch, kind, reason) {
     const r = await deps.api.fail(sessionId, {
@@ -449,8 +483,17 @@ export async function reportFail(deps, sessionId, epoch, kind, reason) {
         reason: kind,
         refs: { reason },
     });
-    if (!ok2xx(r))
+    if (!ok2xx(r)) {
         deps.log(`exec_fail ${kind}/${reason}: ${errorCode(r.body) ?? r.networkError ?? r.status}`);
+        return;
+    }
+    // Amendment 59: the api decides retry or fail; the runner only says which.
+    const b = (r.body ?? {});
+    const job = `job ${sessionId.slice(0, 8)}`;
+    if (b.state === "ready" && Number.isInteger(b.attempt) && Number.isInteger(b.retries))
+        deps.log(`${job} returned to the pool for retry (attempt ${b.attempt} of ${b.retries})`);
+    else if (b.state === "failed" && Number.isInteger(b.attempt))
+        deps.log(`${job} failed after ${b.attempt} attempt${b.attempt === 1 ? "" : "s"}`);
 }
 async function release(deps, sessionId, epoch) {
     const r = await deps.api.release(sessionId, { epoch, nonce: deps.nonce });

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

@@ -8,14 +8,15 @@
  * is oidc_<code> for S1's OIDC_EXCHANGE_REFUSALS, anything else oidc_unavailable. The token never
  * reaches argv, a log line or an outcome.
  *
- * S1 names the route but not its answer's field; `executor_key` is this runner's reading, open
- * with the Durable lead until S1 freezes it (no api handler exists yet to read it from).
+ * S1 names the route but not its answer's fields; `executor_key` (and `executor_id`, which binds
+ * the bundle) is this runner's reading, open with the Durable lead until S1 freezes it (no api handler exists yet to read it from).
  */
 import { type FetchFn } from "./executor-client.js";
 import type { RefusedReason } from "./outcome.js";
 export type OidcExchange = {
     ok: true;
     executorKey: string;
+    executorId: string | null;
 } | {
     ok: false;
     reason: RefusedReason;

package/dist/lib/runner/oidc.js

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

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

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

package/dist/lib/runner/options.js

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

package/dist/lib/runner/outcome.js

@@ -6,7 +6,7 @@
  * a reason outside S1's closed lists is a bug in the runner, so `outcomeLine` throws on one rather
  * than print a line no consumer can read.
  */
-import { RUNNER_EXIT_CODES, RUNNER_FAILED_PHASE_RE, RUNNER_FAILED_REASONS, RUNNER_OUTCOME_FIELDS, RUNNER_REFUSED_REASONS, } from "../../vendor/durable-contract/index.js";
+import { isRunnerFailedReason, RUNNER_EXIT_CODES, RUNNER_OUTCOME_FIELDS, RUNNER_REFUSED_REASONS, } from "../../vendor/durable-contract/index.js";
 /** `phase_<order>_<name>`: the name lowercased, anything outside [a-z0-9_] replaced by `_`. */
 export function phaseReason(order, name) {
     return `phase_${order}_${name.toLowerCase().replace(/[^a-z0-9_]/g, "_")}`;
@@ -20,8 +20,7 @@ function reasonOk(outcome, reason) {
     if (reason === null)
         return false;
     if (outcome === "failed")
-        return (RUNNER_FAILED_REASONS.includes(reason) ||
-            RUNNER_FAILED_PHASE_RE.test(reason));
+        return isRunnerFailedReason(reason);
     return isRefusedReason(reason);
 }
 const pick = (facts, keep) => ({

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

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

package/dist/lib/runner/phases.js

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

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

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

package/dist/lib/runner/proxy.js

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

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

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

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

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