bareloop 0.32.0 → 0.34.0

package/types/authorjob.d.ts

@@ -82,6 +82,7 @@ export function refuseLockedKind(kind: string): Refusal;
  *   verdictType?: string|null,
  *   questions?: Record<string|number, string>|null, generate?: Function, provider?: any,
  *   seedRef?: string|null, scout?: any, listing?: any, ceilingUsd?: number|null, judgeModel?: string|null,
+ *   rates?: {in: number, out: number}|null,
  *   onPhase?: (phase: string, data?: any) => void,
  *   onCall?: (call: {label: string, costUsd: number|null, unpricedRounds: number}) => void,
  *   seedFn?: Function, scoutFn?: Function, listingFn?: Function,
@@ -94,7 +95,7 @@ export function refuseLockedKind(kind: string): Refusal;
  *   closeDecl: any, seedRef: string|null, authoring: any, judged: any, reds: Red[],
  *   stop: string|null, cost: any, interview: any, confirmed: any}>}
  */
-export function authorCloseForJob({ answers, repoPath, lang, verdictType, questions, generate, provider, seedRef, scout, listing, ceilingUsd, writeScope, judgeModel, onPhase, onCall, seedFn, scoutFn, listingFn, authorFn, authorOpts, signerFix, proposeFn, compileOpts, ask, confirmGenerate, isRepo, langResult, }: {
+export function authorCloseForJob({ answers, repoPath, lang, verdictType, questions, generate, provider, seedRef, scout, listing, ceilingUsd, rates, writeScope, judgeModel, onPhase, onCall, seedFn, scoutFn, listingFn, authorFn, authorOpts, signerFix, proposeFn, compileOpts, ask, confirmGenerate, isRepo, langResult, }: {
     answers: Record<string | number, any>;
     repoPath?: string | null;
     lang: string;
@@ -107,6 +108,10 @@ export function authorCloseForJob({ answers, repoPath, lang, verdictType, questi
     listing?: any;
     ceilingUsd?: number | null;
     judgeModel?: string | null;
+    rates?: {
+        in: number;
+        out: number;
+    } | null;
     onPhase?: (phase: string, data?: any) => void;
     onCall?: (call: {
         label: string;

package/types/authorscout.d.ts

@@ -93,13 +93,14 @@ export function defaultSurveyor({ workdir, granted, auditPath, ctx }: {
  *   rounds?: number, minBytes?: number, blobMax?: number, maxTokens?: number, ctx?: boolean,
  *   attempts?: number, ceilingUsd?: number|null, callTimeoutMs?: number,
  *   onCall?: (call: {label: string, costUsd: number|null, unpricedRounds: number}) => void,
- *   createLoop?: (o: {system: string, policy: any, onLlmResult: any, provider: any}) => any,
+ *   createLoop?: (o: {system: string, policy: any, onLlmResult: any, provider: any, rates?: {in: number, out: number}}) => any,
+ *   rates?: {in: number, out: number}|null,
  *   createSurveyor?: (o: {workdir: string, granted: readonly string[], ctx: boolean}) => Promise<any>}} o
  * @returns {Promise<Survey & {raw: string, raws: ReturnType<typeof scrubRaw>[],
  *   calls: {label: string, costUsd: number|null, unpricedRounds: number}[],
  *   budgetStop: 'cap-halt'|'pricing-red'|null}>}
  */
-export function runAuthorScout({ workdir, provider, rounds, minBytes, blobMax, maxTokens, ctx, attempts, ceilingUsd, callTimeoutMs, onCall, createLoop, createSurveyor, }: {
+export function runAuthorScout({ workdir, provider, rounds, minBytes, blobMax, maxTokens, ctx, attempts, ceilingUsd, callTimeoutMs, onCall, createLoop, rates, createSurveyor, }: {
     workdir: string;
     provider?: any;
     rounds?: number;
@@ -120,7 +121,15 @@ export function runAuthorScout({ workdir, provider, rounds, minBytes, blobMax, m
         policy: any;
         onLlmResult: any;
         provider: any;
+        rates?: {
+            in: number;
+            out: number;
+        };
     }) => any;
+    rates?: {
+        in: number;
+        out: number;
+    } | null;
     createSurveyor?: (o: {
         workdir: string;
         granted: readonly string[];

package/types/bundlerun.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `bareloop run <bundleDir> --repo <path> [--budget N] [--wall MIN] [--approve <bundleHash>]`
+ * `bareloop run <bundleDir> --resume <runid> [--repo <path>] [--budget N] [--wall MIN] [--approve <bundleHash>]`
+ * @param {string[]} args
+ * @param {{
+ *   out: (s: string) => void, err: (s: string) => void, cwd: string,
+ *   env: Record<string,string|undefined>, now: () => number, deps: any, keysHome?: string,
+ *   parseFlags: (a: string[]) => { positional: string[], flags: Record<string, string|true> },
+ *   printReds: (reds: import('./bundle.js').Red[], err: (s: string) => void) => void,
+ * }} ctx
+ * @returns {Promise<number>}
+ */
+export function bundleMain(args: string[], { out, err, cwd, env, now, deps, keysHome, parseFlags, printReds, }: {
+    out: (s: string) => void;
+    err: (s: string) => void;
+    cwd: string;
+    env: Record<string, string | undefined>;
+    now: () => number;
+    deps: any;
+    keysHome?: string;
+    parseFlags: (a: string[]) => {
+        positional: string[];
+        flags: Record<string, string | true>;
+    };
+    printReds: (reds: import("./bundle.js").Red[], err: (s: string) => void) => void;
+}): Promise<number>;

package/types/invoke.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The command that runs `flow`, spelled the way the caller reached this flow: `bareloop <flow>`
+ * when `invokedAs` names the CLI, else the source-tree script.
+ * @param {Flow} flow @param {string|undefined} invokedAs
+ * @returns {string}
+ */
+export function commandFor(flow: Flow, invokedAs: string | undefined): string;
+export type Flow = "run-u" | "interview" | "author";

package/types/judged.d.ts

@@ -229,7 +229,7 @@ export function locatePrompt(card: any): string;
  * On every route out, red or clean, `onCost` fires exactly once with the honest
  * read: a paid call that leaves no meter record is F12 wearing a judge's coat.
  * @param {{artifactText: string, card: any, loopFactory: (o: {provider?: any, system: string}) => any,
- *   maxTokens?: number, attempt?: number, onCost?: (c: {costUsd: number|null, unpricedRounds: number}) => void,
+ *   maxTokens?: number, attempt?: number, onCost?: (c: {costUsd: number|null, unpricedRounds: number, rateSource?: string|null}) => void,
  *   callBounds?: {timeoutMs?: number, deadlineMs?: number}}} o
  * @returns {Promise<{ok: boolean, facts: any|null, red: {axis: string, detail: string}|null,
  *   costUsd: number|null, unpricedRounds: number, truncated: boolean, parseError: boolean,
@@ -247,6 +247,7 @@ export function runLocate({ artifactText, card, loopFactory, maxTokens, attempt,
     onCost?: (c: {
         costUsd: number | null;
         unpricedRounds: number;
+        rateSource?: string | null;
     }) => void;
     callBounds?: {
         timeoutMs?: number;
@@ -382,10 +383,16 @@ export const JUDGE_RULE_IDS: readonly string[];
 export const CALIBRATION_SIZE: 10;
 /** the two verdicts a case may expect — `decide()`'s own closed set */
 export const CASE_VERDICTS: readonly string[];
-export function defaultJudgeLoop({ provider, system }: {
+export function defaultJudgeLoop({ provider, system, rates }: {
     provider: any;
     system: string;
-}): import("bare-agent").Loop;
+    rates?: {
+        in: number;
+        out: number;
+    } | null;
+}): {
+    run: (msgs: any[], tools: any[], opts?: any) => Promise<any>;
+};
 export type RuleRed = {
     fn: string;
     why: string;

package/types/monthly.d.ts

@@ -29,27 +29,30 @@ export function legTokens(records: any[]): number;
 /**
  * Every listed run as one {@link Leg}. The ONE reader the month total, the all-time total
  * and the per-provider figures share.
- * @param {{ home?: string, now?: () => number, resumingSpine?: string|null }} [opts] `now` = the clock for the in-flight test; `resumingSpine` = the spine a resume continues: that leg reserves its spend only, never its unspent cap (the resume's own leg cap is that remainder)
+ * @param {{ home?: string, now?: () => number, aboveRunid?: string, thisMonthOnly?: boolean }} [opts] `now` = the clock for the no-pid in-flight test; `aboveRunid` = read only the runs listed EARLIER in the file than that run (a claim yields to the claims above it, never below); `thisMonthOnly` = do not parse the spine of a run listed in another local month (the refusal check drops it anyway) unless its claim is still held
  * @returns {Leg[]}
  */
 export function readLegs(opts?: {
     home?: string;
     now?: () => number;
-    resumingSpine?: string | null;
+    aboveRunid?: string;
+    thisMonthOnly?: boolean;
 }): Leg[];
 /**
- * @param {{ home?: string, now?: () => number, resumingSpine?: string|null }} [opts] `resumingSpine`: see {@link readLegs}
- * @returns {{ usd: number, atLeast: boolean, runs: number, reservedUsd: number }} `usd` = real spend (the Money tab's figure); `reservedUsd` = the same with in-flight runs at their cap (the refusal check's)
+ * @param {{ home?: string, now?: () => number, aboveRunid?: string }} [opts] `aboveRunid`: see {@link readLegs}
+ * @returns {{ usd: number, atLeast: boolean, runs: number, reservedUsd: number, heldUsd: number, heldRuns: number }} `usd` = real spend (the Money tab's figure); `reservedUsd` = the same with in-flight runs at their cap (the refusal check's); `heldUsd` = what in-progress runs set aside beyond what they have spent (`reservedUsd - usd`), over `heldRuns` runs
  */
 export function monthSpend(opts?: {
     home?: string;
     now?: () => number;
-    resumingSpine?: string | null;
+    aboveRunid?: string;
 }): {
     usd: number;
     atLeast: boolean;
     runs: number;
     reservedUsd: number;
+    heldUsd: number;
+    heldRuns: number;
 };
 /**
  * The Money tab's figures: all-time and this-month spend, and per-provider breakdown
@@ -97,6 +100,8 @@ export function spendSummary(opts?: {
  * @property {number|null} leftUsd what is left this month (null = no limit set)
  * @property {number|null} limitUsd the person's monthly limit (null = none)
  * @property {boolean} atLeast the month's spend is a floor, so `leftUsd` is a ceiling
+ * @property {number} [heldUsd] what run(s) in progress have set aside beyond their spend so far (present when a limit is set)
+ * @property {number} [heldRuns] how many runs hold it
  */
 /**
  * The person's monthly limit off a parsed config.json: key absent (or null) = no limit (null);
@@ -108,25 +113,59 @@ export function spendSummary(opts?: {
  */
 export function monthlyLimitOf(config: Record<string, any>, home?: string): number | null;
 /**
- * Does a run with this $ cap fit in what is left this month (running jobs counted at their full cap, except the spine a resume continues — `resumingSpine` — which counts its real spend)? No limit set (key absent or null) = ok, no check; a limit that is present but not a
+ * Does a run with this $ cap fit in what is left this month (a run still held counts at its full cap)? No limit set (key absent or null) = ok, no check; a limit that is present but not a
  * number above 0 throws `ConfigError`.
  * Compared in whole cents. Also throws `ConfigError` when config.json is unreadable — a gate
  * whose own instrument is broken refuses; it never silently runs with no limit.
- * @param {{ capUsd: number, home?: string, now?: () => number, resumingSpine?: string|null }} args
+ * @param {{ capUsd: number, home?: string, now?: () => number, aboveRunid?: string }} args `aboveRunid`: count only the claims listed above that run (a claim in progress)
  * @returns {MonthlyRoom}
  */
-export function checkMonthlyRoom({ capUsd, home, now, resumingSpine }: {
+export function checkMonthlyRoom({ capUsd, home, now, aboveRunid }: {
     capUsd: number;
     home?: string;
     now?: () => number;
-    resumingSpine?: string | null;
+    aboveRunid?: string;
 }): MonthlyRoom;
 /**
- * The ONE refusal text, everywhere (CLI, panel cap note, panel Sign refusal).
+ * The ONE refusal text, everywhere (CLI, panel cap note, panel Sign refusal). When run(s) in progress hold
+ * part of the limit, the same line says how much.
  * @param {MonthlyRoom} room
  * @returns {string|null} null when the run fits
  */
 export function monthlyRefusalText(room: MonthlyRoom): string | null;
+/**
+ * Close every claim ABOVE `aboveRunid` (file order) whose process is gone: a pid-bearing run row with no
+ * `settled` entry whose pid is not a live bareloop runner gets `{ type: 'settled', by: <closer>, reason:
+ * 'process gone', spentUsd: <its spine's floor>, spendComplete: false }` appended — so every claim gets a
+ * write-back, attributed. Two runs may both close the same dead claim; readers take the FIRST note.
+ * @param {{ home?: string, by: string, aboveRunid?: string }} args `by` = the run doing the closing
+ * @returns {number} how many notes were appended
+ */
+export function settleDeadClaims({ home, by, aboveRunid }: {
+    home?: string;
+    by: string;
+    aboveRunid?: string;
+}): number;
+/**
+ * The CLAIM (hamr 2026-09-30: whoever runs first claims the limit and holds it; no lock file, records
+ * only): the run APPENDS its row first (`row` carries its `pid` and `capUsd`), then reads the run list.
+ * Only the claims ABOVE its own row count — a live one is held at its cap (a dead one is closed with an
+ * attributed note and counts its real spend); rows below yield to it. If `capUsd` fits, it runs; if not
+ * it appends `{type:'released', reason:'refused'}` and reports the refusal, nothing spent. No limit set =
+ * no claim (`claimed: false`; the caller lists the run as it always did). An unreadable config, or a row
+ * that cannot be written, throws `ConfigError` — the gate refuses, never reads "no limit".
+ * @param {{ row: import('./runlist.js').RunRow, capUsd: number, home?: string, now?: () => number }} args
+ * @returns {{ room: MonthlyRoom, claimed: boolean }}
+ */
+export function claimRun({ row, capUsd, home, now }: {
+    row: import("./runlist.js").RunRow;
+    capUsd: number;
+    home?: string;
+    now?: () => number;
+}): {
+    room: MonthlyRoom;
+    claimed: boolean;
+};
 export type Leg = {
     /**
      * when the run was listed
@@ -189,4 +228,12 @@ export type MonthlyRoom = {
      * the month's spend is a floor, so `leftUsd` is a ceiling
      */
     atLeast: boolean;
+    /**
+     * what run(s) in progress have set aside beyond their spend so far (present when a limit is set)
+     */
+    heldUsd?: number | undefined;
+    /**
+     * how many runs hold it
+     */
+    heldRuns?: number | undefined;
 };

package/types/panel/authorroutes.d.ts

@@ -1,5 +1,20 @@
 /** @returns {string} a fresh per-process token — never persisted, never logged */
 export function mintToken(): string;
+/**
+ * The ONE Host check: the request names this panel's own bind address. A page on another
+ * origin reaching the panel through a rebound DNS name sends that name as Host, so it fails here.
+ * @param {import('node:http').IncomingMessage} req
+ * @param {{port: number}} o
+ * @returns {{ok: true}|{ok: false, reason: string}}
+ */
+export function checkHostGuard(req: import("node:http").IncomingMessage, { port }: {
+    port: number;
+}): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
 /**
  * `true` when a request may reach ANY route in this file — the token header
  * plus an Origin/Host that names this exact bind address. `req.headers`

package/types/planrun.d.ts

@@ -195,6 +195,10 @@ export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxS
  *   `false` → the drafter has no tools, so a native session would report NO cost — return a
  *   metered claude-json TEXT provider (`--output-format json`, `parse:'claude-json'`) instead,
  *   so its spend is never invisible. The Loop path (`anthropic-api`) never touches this.
+ * @param {{in: number, out: number}|null} [opts.rates] the customer's own price for the worker's key row (USD per
+ *   1K tokens, `ratesFor`) — handed to the one Loop that drives worker, scout and planner rounds, so they read
+ *   `rateSource:'caller'`; null = bare-agent's built-in guess. Not applied to a native (CLI) session, which reports its own cost.
+ * @param {{in: number, out: number}|null} [opts.judgeRates] the same, for the judge's Loop
  * @param {string|null} [opts.judgeModel] softgreen — WHICH model that judge provider drives
  *   (PRD item 32.1). Resolved by the CALLER (`resolveJudge`, src/judged.js: the spec's signed
  *   `judge` override, else the job's own worker model), never pinned in this library. It
@@ -416,7 +420,7 @@ export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxS
  *   'branch-red' | 'cap-halt' | 'wall-halt' | 'provider-red' | 'interpreter-red' |
  *   'step-stalled' | 'hitl-pause' | 'hitl-decision-red' | `step-red:<id>`
  */
-export function runPlan(job: any, { workdir, provider, nativeProvider, providerFor, judgeProvider, judgeModel, emit, remainingUsd, isUnpriced, spendComplete, capRuns, strikeLimit, closeTimeoutMs, closeDir, maxStepRounds, layerRoot, readShim, scout, scoutRounds, bridge, now, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, priorSpentUsd, reviewDoor, doorRerun, resumable }: {
+export function runPlan(job: any, { workdir, provider, nativeProvider, providerFor, judgeProvider, judgeModel, rates, judgeRates, emit, remainingUsd, isUnpriced, spendComplete, capRuns, strikeLimit, closeTimeoutMs, closeDir, maxStepRounds, layerRoot, readShim, scout, scoutRounds, bridge, now, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, priorSpentUsd, reviewDoor, doorRerun, resumable }: {
     workdir: string;
     provider: any;
     nativeProvider?: ((o: {
@@ -425,6 +429,14 @@ export function runPlan(job: any, { workdir, provider, nativeProvider, providerF
         maxTurns: number;
         hasTools: boolean;
     }) => any) | undefined;
+    rates?: {
+        in: number;
+        out: number;
+    } | null | undefined;
+    judgeRates?: {
+        in: number;
+        out: number;
+    } | null | undefined;
     judgeModel?: string | null | undefined;
     judgeProvider?: any;
     emit: (type: string, data?: object) => object;

package/types/providerrows.d.ts

@@ -23,6 +23,9 @@ export function defaultsFor(envName: string): {
  * @property {string} name the model id Chat uses ('' = not offered in Chat)
  * @property {string} provider the `src/providers.js` table entry (the API shape's id)
  * @property {string} baseUrl the saved Base URL ('' = the shape's default host)
+ * @property {unknown} [priceInPerM] the customer's own price, USD per 1M input tokens — carried RAW
+ *   (present only when the config row names it); {@link ratesFor} is the one place that validates it
+ * @property {unknown} [priceOutPerM] the same, for output tokens
  */
 /**
  * The rows: one per name in `filled`, saved entry over defaults.
@@ -122,6 +125,60 @@ export function keyNameFor(provider: string | null | undefined, baseUrl: string
  * @returns {Record<string,string|undefined>}
  */
 export function applyConfiguredKey(env: Record<string, string | undefined>, provider: string | null | undefined, baseUrl: string | null | undefined, rows: readonly KeyRow[], model?: string | null | undefined): Record<string, string | undefined>;
+/**
+ * The one readout line for a resolved customer price, preview and run tail alike:
+ * `yours: in $0.006 / out $1.20 per 1M tokens (DEEPSEEK_API_KEY row)`. A 0 / 0 price is accepted (the price
+ * is the customer's) but the line says so: every round then books $0, so spend and limits read $0.
+ * @param {{ inPerM: number, outPerM: number, envName: string }} price a {@link ratesFor} result
+ * @returns {string}
+ */
+export function priceReadout(price: {
+    inPerM: number;
+    outPerM: number;
+    envName: string;
+}): string;
+/**
+ * The customer's own price for the row a `(provider, baseUrl[, model])` identity belongs to —
+ * the SAME row match {@link keyNameFor} uses (`findRow`), so the price and the key always come
+ * from one row. `null` = no price set (the run keeps bare-agent's built-in guess, byte-identical
+ * to before). Both fields or neither, each a finite number >= 0, USD per 1M tokens; anything
+ * else throws `ConfigError` naming the row and field — a bad price never silently falls back to
+ * the guess. `rates` is bare-agent's `Loop({ rates })` shape (USD per 1K); `inPerM`/`outPerM`
+ * are what a readout prints.
+ * @param {string|null|undefined} provider
+ * @param {string|null|undefined} baseUrl
+ * @param {readonly KeyRow[]} rows
+ * @param {string|null|undefined} [model]
+ * @returns {{ rates: { in: number, out: number }, inPerM: number, outPerM: number, envName: string }|null}
+ */
+export function ratesFor(provider: string | null | undefined, baseUrl: string | null | undefined, rows: readonly KeyRow[], model?: string | null | undefined): {
+    rates: {
+        in: number;
+        out: number;
+    };
+    inPerM: number;
+    outPerM: number;
+    envName: string;
+} | null;
+/**
+ * The price a judge's rounds are booked at. A price belongs to the MODEL's row: when the judge is
+ * the worker's own provider it calls the worker's endpoint, so a row on that endpoint NAMED for the
+ * judge's model prices it ({@link ratesFor}); a judge model that is absent or names no row there
+ * keeps the worker's price (the worker's row, or none = the guess). A different provider resolves
+ * on its own default endpoint, as before. A bad price on the resolved row throws like `ratesFor`.
+ * The judge's KEY is chosen elsewhere (`applyConfiguredKey`, by the worker's model), so the two
+ * can come from different rows — same provider + endpoint, judge model naming another row.
+ * @param {{ provider: string, model?: string|null }} judge
+ * @param {string|null|undefined} workerProvider
+ * @param {string|null|undefined} workerBaseUrl
+ * @param {ReturnType<typeof ratesFor>} workerPrice what the worker's own rounds are booked at
+ * @param {readonly KeyRow[]} rows
+ * @returns {ReturnType<typeof ratesFor>}
+ */
+export function judgeRatesFor(judge: {
+    provider: string;
+    model?: string | null;
+}, workerProvider: string | null | undefined, workerBaseUrl: string | null | undefined, workerPrice: ReturnType<typeof ratesFor>, rows: readonly KeyRow[]): ReturnType<typeof ratesFor>;
 /** DeepSeek's OpenAI-shaped endpoint (the same string the panel's Model menu used). */
 export const DEEPSEEK_BASE_URL: "https://api.deepseek.com/v1";
 /**
@@ -161,4 +218,13 @@ export type KeyRow = {
      * the saved Base URL ('' = the shape's default host)
      */
     baseUrl: string;
+    /**
+     * the customer's own price, USD per 1M input tokens — carried RAW
+     * (present only when the config row names it); {@link ratesFor} is the one place that validates it
+     */
+    priceInPerM?: unknown;
+    /**
+     * the same, for output tokens
+     */
+    priceOutPerM?: unknown;
 };

package/types/providers.d.ts

@@ -52,8 +52,7 @@ export function makeProvider(providerName: string, { apiKey, model, baseUrl }?:
 }): any;
 /**
  * Build the `{provider, providerFor, judgeProvider}` triple both runners
- * need (`src/cli.js`'s `buildProviders`, `scripts/run-u.mjs`'s top-level
- * wiring) — ONE seam instead of two copies of the same construction and
+ * need (`src/authorrun.js` and `src/panel/authorsession.js` call it) — ONE seam instead of two copies of the same construction and
  * tier-memoization logic. `model`/`tierModels` are already-RESOLVED inputs
  * (the caller runs `resolveWorkerModel` itself, exactly as both runners did
  * before this factory existed — that decision stays where each runner's own

package/types/run.d.ts

@@ -34,6 +34,11 @@
  *   metered claude-json text provider for the toolless drafter); ignored on every Loop-driven provider
  * @param {(type: string, data?: object) => object} opts.emit spine emitter
  * @param {(tier: string) => any} [opts.providerFor] P: per-step model-tier provider factory (forwarded to the plan flow)
+ * @param {{in: number, out: number}|null} [opts.rates] the CUSTOMER's own price for the worker's key row
+ *   (`ratesFor`, src/providerrows.js — USD per 1K tokens), resolved once by the door and handed to every
+ *   worker/planner Loop as bare-agent's `rates` (rounds then read `rateSource:'caller'`). Absent = the
+ *   built-in guess, exactly as before. A Loop-driven provider only: a native session reports its own cost.
+ * @param {{in: number, out: number}|null} [opts.judgeRates] the same, for the judge's own key row
  * @param {string|null} [opts.judgeModel] SOFTGREEN — WHICH model the judge provider drives
  *   (PRD item 32.1), resolved by the CALLER (`resolveJudge`, src/judged.js) and passed
  *   through untouched. Travels with `judgeProvider`; absent, a judged stage stops as a
@@ -204,7 +209,7 @@
  *   deliberately NOT in the resumable/checkpoint set (`src/reuse.js`) — an
  *   unknown in-flight state is not a known-safe resume point.
  */
-export function runJob(rawSpec: object | string, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider, judgeModel, emit, capRuns, strikeLimit, shellCapUsd, closeTimeoutMs, closeDir, layerRoot, readShim, scout, bridge, draftSpentUsd, draftSpendComplete, priorSpentUsd, priorSpendComplete, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun, resumable }: {
+export function runJob(rawSpec: object | string, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider, judgeModel, rates, judgeRates, emit, capRuns, strikeLimit, shellCapUsd, closeTimeoutMs, closeDir, layerRoot, readShim, scout, bridge, draftSpentUsd, draftSpendComplete, priorSpentUsd, priorSpendComplete, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun, resumable }: {
     approvals: unknown;
     workdir: string;
     provider: any;
@@ -216,6 +221,14 @@ export function runJob(rawSpec: object | string, { approvals, workdir, provider,
     }) => any) | undefined;
     emit: (type: string, data?: object) => object;
     providerFor?: ((tier: string) => any) | undefined;
+    rates?: {
+        in: number;
+        out: number;
+    } | null | undefined;
+    judgeRates?: {
+        in: number;
+        out: number;
+    } | null | undefined;
     judgeModel?: string | null | undefined;
     judgeProvider?: any;
     capRuns?: number | undefined;

package/types/runlist.d.ts

@@ -13,7 +13,9 @@ export function runlistHome(override?: string): string;
  */
 export function runlistPath(home?: string): string;
 /**
- * @typedef {{ at: string, runid: string, job: string, spine: string, patient: string|null, via: 'run-u'|'bundle'|'backfill' }} RunRow
+ * @typedef {{ at: string, runid: string, job: string, spine: string, patient: string|null, via: 'run-u'|'bundle'|'backfill', pid?: number, capUsd?: number }} RunRow
+ * `pid`/`capUsd` (optional; older and backfilled rows carry neither): the runner's process id and the
+ * leg's $ cap — what the monthly limit holds while that pid is a live bareloop runner (src/monthly.js).
  */
 /**
  * Append one row to the run list, mkdir -p'ing the home directory first.
@@ -42,19 +44,71 @@ export function appendRun(row: RunRow, opts?: {
     appended: boolean;
     reason?: "duplicate-runid";
 };
+/**
+ * @typedef {{ runid: string, type: 'settled'|'released', by: string, at: string, reason?: string, spentUsd?: number, spendComplete?: boolean }} RunEvent
+ * A claim's write-back, appended (never rewritten) beside the run rows. `settled` = the run's claim on the
+ * monthly limit is over (`spentUsd`/`spendComplete` are its final figure, `by` is WHO wrote it: the run itself
+ * at its `job-end`, or the next run that found its process gone, `reason: 'process gone'`). `released` = the
+ * claim was taken and then given back unspent, its run never started. The month's totals keep reading real
+ * spend off the spines; an event only releases the hold and records who wrote it.
+ */
+/**
+ * Append one {@link RunEvent}. Not locked: one short line, one append. THROWS on IO failure.
+ * @param {RunEvent} event
+ * @param {{ home?: string }} [opts]
+ * @returns {void}
+ */
+export function appendRunEvent(event: RunEvent, opts?: {
+    home?: string;
+}): void;
 /**
  * Tolerant reader — reuses {@link parseJsonl} (never a second hand-rolled
  * parser). An absent file reads as an empty list, not an error: a fresh
- * install has never run `appendRun` yet.
+ * install has never run `appendRun` yet. FOLDS the file: `rows` are the RUNS
+ * only (an event line is never listed as a run, and a run whose claim was
+ * `released` never started, so it is not listed either); `events` are the
+ * write-backs, in file order.
  * @param {{ home?: string }} [opts]
- * @returns {{ rows: RunRow[], skipped: number }}
+ * @returns {{ rows: RunRow[], skipped: number, events: RunEvent[] }}
  */
 export function readRunList(opts?: {
     home?: string;
 }): {
     rows: RunRow[];
     skipped: number;
+    events: RunEvent[];
 };
+/**
+ * Is this pid a live bareloop runner? `process.kill(pid, 0)` says whether the
+ * pid exists (EPERM = it exists, just not ours); `/proc/<pid>/cmdline` says whether it is a
+ * bareloop runner — a recycled pid that now belongs to some other program is NOT. A runner is
+ * a node executable (argv[0] is `node`, `nodejs`, `node22`, ...) with a later argv entry named
+ * `bareloop`, `bareloop.mjs`, `run-u.mjs` or `u-watchdog.mjs` (the basename, so the npm bin
+ * symlink counts), or a process whose argv[0] is itself one of those names. A non-node program
+ * that merely has such a name in its arguments (`nvim /x/bareloop`, `git -C /x/bareloop`) is not
+ * a runner. Residual, accepted: a recycled pid that is a node program with such an argument
+ * still reads as a runner. The wrong direction to err is "not a runner" on a real live run — it
+ * would release that run's cap. Where `/proc` is unreadable (not Linux, or not ours) the
+ * existence test alone decides: alive. The ONE spelling — the monthly limit's holds, and
+ * `--resume`'s old-pid check share it.
+ * @param {number} pid
+ * @returns {boolean}
+ */
+export function isLiveRunner(pid: number): boolean;
+/**
+ * The ONE "is this run alive" rule, for the panel's glyph ([▶] vs [?]) and the monthly limit's hold. A
+ * row that carries its runner's `pid` is alive exactly while that pid is a live bareloop runner
+ * ({@link isLiveRunner}) however quiet its spine; only a row with NO pid (an older row) falls back to
+ * the spine-mtime rule above. A run that has ENDED (a `job-end` on its spine) is a different fact the
+ * callers read off the spine itself — this answers "is a process still running it", nothing more.
+ * @param {{ pid?: number, spine: string }} row
+ * @param {number} [nowMs] the clock for the mtime fallback
+ * @returns {boolean}
+ */
+export function runIsAlive(row: {
+    pid?: number;
+    spine: string;
+}, nowMs?: number): boolean;
 /**
  * `bareloop runs backfill <dir>` — recursively scan `dir` (bounded to
  * {@link MAX_BACKFILL_DEPTH} levels, never into `node_modules`/`.git`,
@@ -103,6 +157,10 @@ export function backfillRuns(dir: string, opts?: {
 export function formatRunRow(row: RunRow): string;
 export const DIED_MTIME_MS: number;
 export const MAX_BACKFILL_DEPTH: 6;
+/**
+ * `pid`/`capUsd` (optional; older and backfilled rows carry neither): the runner's process id and the
+ * leg's $ cap — what the monthly limit holds while that pid is a live bareloop runner (src/monthly.js).
+ */
 export type RunRow = {
     at: string;
     runid: string;
@@ -110,4 +168,22 @@ export type RunRow = {
     spine: string;
     patient: string | null;
     via: "run-u" | "bundle" | "backfill";
+    pid?: number;
+    capUsd?: number;
+};
+/**
+ * A claim's write-back, appended (never rewritten) beside the run rows. `settled` = the run's claim on the
+ * monthly limit is over (`spentUsd`/`spendComplete` are its final figure, `by` is WHO wrote it: the run itself
+ * at its `job-end`, or the next run that found its process gone, `reason: 'process gone'`). `released` = the
+ * claim was taken and then given back unspent, its run never started. The month's totals keep reading real
+ * spend off the spines; an event only releases the hold and records who wrote it.
+ */
+export type RunEvent = {
+    runid: string;
+    type: "settled" | "released";
+    by: string;
+    at: string;
+    reason?: string;
+    spentUsd?: number;
+    spendComplete?: boolean;
 };

package/types/source.d.ts

@@ -72,15 +72,20 @@ export function looksLikeRepoSource(source: string): boolean;
  * never hands a repo source's destination to `copyOut` — wiring it into
  * `writeScope` is M3/M4's job, not this one.
  * @param {{source: string, into: string, destination?: string,
- *   fetchTimeoutMs?: number}} args `fetchTimeoutMs` is test-only — production
- *   callers omit it and get `PROVIDER_TIMEOUT_MS`.
+ *   fetchTimeoutMs?: number, afterScan?: () => (void|Promise<void>)}} args
+ *   `fetchTimeoutMs` is test-only — production callers omit it and get
+ *   `PROVIDER_TIMEOUT_MS`. `afterScan` is a test seam too: called exactly once,
+ *   after the secret scan finished and before the freeze loop re-reads any
+ *   file's bytes, so a test can swap a file inside that window
+ *   deterministically. Production never sets it; absent, behaviour is unchanged.
  * @returns {Promise<{stop: null, into: string, tree: string, manifestPath: string, manifest: object}|SourceRefusal>}
  */
-export function prepareSource({ source, into, destination, fetchTimeoutMs }: {
+export function prepareSource({ source, into, destination, fetchTimeoutMs, afterScan }: {
     source: string;
     into: string;
     destination?: string;
     fetchTimeoutMs?: number;
+    afterScan?: () => (void | Promise<void>);
 }): Promise<{
     stop: null;
     into: string;