bareloop 0.32.0 → 0.33.0

package/src/monthly.js

@@ -8,21 +8,22 @@
 // The limit REFUSES, never warns; the page and the chat can never raise it (a person
 // edits it by hand in Settings — src/config.js).
 //
-// A run still IN FLIGHT (a spine with `job-start`, no `job-end`, and a spine file written to
-// within DIED_MTIME_MS — the panel's own died rule) is counted at its full leg cap, not its
-// spend so far: `checkMonthlyRoom` reserves what the run may still spend, so two runs cannot
-// both start against a limit only one of them fits. A died run (stale spine) counts its floor.
-// The one exception is the spine a RESUME continues (`resumingSpine`): it counts its real spend
-// only, because the resume's own leg cap is the remainder and already covers its unspent cap.
-// Only the refusal check reserves; the Money tab keeps showing real spend (`usd`).
+// HOLD UNTIL DONE (hamr 2026-09-30): a run CLAIMS its whole leg cap when it starts (`claimRun`: append
+// the run's row FIRST, carrying its `pid` and `capUsd`, then read the list — only the claims ABOVE its row
+// count, so whoever runs first holds) and holds it until it is done. While the row's pid is a live bareloop runner the
+// run is counted at max(spend so far, capUsd) however quiet its spine; a run with a `job-end` counts
+// its real spend; a claim whose process is gone counts its floor and is settled — with an attributed
+// `settled` entry — by whichever later run finds it (the first note wins). An older row with no `pid` keeps the spine
+// mtime rule (a fresh spine, written to within DIED_MTIME_MS, is in flight). Only the refusal check
+// reserves; the Money tab keeps showing real spend (`usd`).
 //
 // Honesty: a run whose spend is not fully known (a died/still-running spine, an unpriced
 // round, a missing spine file) makes the month total an "at least" figure — never a clean
 // number. The refusal text stays exactly `Max $X (monthly limit)`; `atLeast` travels beside it.
 import { existsSync, statSync } from 'node:fs';
-import { resolve } from 'node:path';
 import { readConfig, configPath, ConfigError } from './config.js';
-import { readRunList, DIED_MTIME_MS } from './runlist.js';
+import { readRunList, appendRun, appendRunEvent, isLiveRunner, DIED_MTIME_MS } from './runlist.js';
+export { isLiveRunner };
 import { parseJsonl } from './replayio.js';
 import { SPEND_RECORD_TYPES, spendProvenance, floorsFromRecords } from './ledger.js';
 import { findRow } from './providerrows.js';
@@ -161,25 +162,44 @@ function inFlightCapUsd(records, spinePath, nowMs, usd) {
   return Math.max(usd, Math.max(0, start.budgetUsd - fold));
 }
 
+/**
+ * The rows listed EARLIER in the run list than `runid`'s own row (file order is claim order). No
+ * `runid`, or a runid not in the list, = every row.
+ * @param {import('./runlist.js').RunRow[]} rows
+ * @param {string} [runid]
+ * @returns {import('./runlist.js').RunRow[]}
+ */
+function rowsAbove(rows, runid) {
+  if (runid === undefined) return rows;
+  const i = rows.findIndex((r) => r.runid === runid);
+  return i < 0 ? rows : rows.slice(0, i);
+}
+
 /**
  * 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 }} [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)
  * @returns {Leg[]}
  */
 export function readLegs(opts = {}) {
   const nowMs = (opts.now ?? Date.now)();
-  const { rows } = readRunList({ home: opts.home });
-  const resuming = typeof opts.resumingSpine === 'string' ? resolve(opts.resumingSpine) : null;
+  const { rows: allRows, events } = readRunList({ home: opts.home });
+  const rows = rowsAbove(allRows, opts.aboveRunid);
+  const settled = new Set(events.filter((e) => e.type === 'settled').map((e) => e.runid));
   /** @type {Leg[]} */
   const legs = [];
   for (const row of rows) {
     const at = new Date(row.at);
     const base = { at, provider: null, baseUrl: null, model: null, wallMs: null, wallComplete: false, usd: 0, complete: false, tokens: 0, vouchedRounds: 0, otherRounds: 0, reservedUsd: 0, unreadable: true };
-    if (Number.isNaN(at.getTime()) || !existsSync(row.spine)) { legs.push(base); continue; }
+    // Rule 2 (hold-until-done): a row that carries its runner's `pid` is HELD at its cap while that
+    // pid is a live bareloop runner, however quiet its spine — killed = process gone, not silence.
+    // An older row with no `pid` keeps the spine-mtime rule (`inFlightCapUsd`), never guessed alive.
+    const hasPid = Number.isInteger(row.pid);
+    const heldCap = hasPid && !settled.has(row.runid) && typeof row.capUsd === 'number' && Number.isFinite(row.capUsd) && isLiveRunner(/** @type {number} */ (row.pid)) ? row.capUsd : null;
+    if (Number.isNaN(at.getTime()) || !existsSync(row.spine)) { legs.push({ ...base, reservedUsd: heldCap ?? 0 }); continue; }
     /** @type {any[]} */
     let records;
-    try { records = parseJsonl(row.spine).records; } catch { legs.push(base); continue; }
+    try { records = parseJsonl(row.spine).records; } catch { legs.push({ ...base, reservedUsd: heldCap ?? 0 }); continue; }
     const start = records.find((r) => r && r.type === 'job-start') ?? null;
     const leg = legSpend(records);
     const prov = spendProvenance(records);
@@ -196,7 +216,8 @@ export function readLegs(opts = {}) {
       tokens: legTokens(records),
       vouchedRounds: prov.vouched.rounds,
       otherRounds: prov.guessed.rounds + prov.unpriced.rounds + prov.unknown.rounds,
-      reservedUsd: resuming !== null && resolve(row.spine) === resuming ? leg.usd : inFlightCapUsd(records, row.spine, nowMs, leg.usd),
+      reservedUsd: hasPid ? (records.some((r) => r && r.type === 'job-end') || heldCap === null ? leg.usd : Math.max(leg.usd, heldCap))
+        : inFlightCapUsd(records, row.spine, nowMs, leg.usd),
       unreadable: false,
     });
   }
@@ -211,7 +232,7 @@ export function readLegs(opts = {}) {
 const sameLocalMonth = (at, now) => at.getFullYear() === now.getFullYear() && at.getMonth() === now.getMonth();
 
 /**
- * @param {{ home?: string, now?: () => number, resumingSpine?: string|null }} [opts] `resumingSpine`: see {@link readLegs}
+ * @param {{ home?: string, now?: () => number, aboveRunid?: string }} [opts] `aboveRunid`: 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)
  */
 export function monthSpend(opts = {}) {
@@ -220,12 +241,12 @@ export function monthSpend(opts = {}) {
   let reservedUsd = 0;
   let atLeast = false;
   let runs = 0;
-  for (const leg of readLegs({ home: opts.home, now: opts.now, resumingSpine: opts.resumingSpine })) {
+  for (const leg of readLegs({ home: opts.home, now: opts.now, aboveRunid: opts.aboveRunid })) {
     // an unreadable date could belong to this month — unknown, never dropped
     if (Number.isNaN(leg.at.getTime())) { atLeast = true; continue; }
     if (!sameLocalMonth(leg.at, nowDate)) continue;
     runs += 1;
-    if (leg.unreadable) { atLeast = true; continue; }
+    if (leg.unreadable) { atLeast = true; reservedUsd += leg.reservedUsd; continue; }
     usd += leg.usd;
     reservedUsd += leg.reservedUsd;
     if (!leg.complete) atLeast = true;
@@ -321,21 +342,21 @@ export function monthlyLimitOf(config, home) {
 }
 
 /**
- * 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 }) {
   const cfg = readConfig({ home });
   if (cfg.problem) throw new ConfigError(cfg.problem);
   const limit = monthlyLimitOf(cfg.config, home);
   if (limit === null) {
     return { ok: true, leftUsd: null, limitUsd: null, atLeast: false };
   }
-  const spent = monthSpend({ home, now, resumingSpine });
+  const spent = monthSpend({ home, now, aboveRunid });
   const leftCents = Math.max(0, Math.floor((limit - spent.reservedUsd) * 100 + 1e-6));
   const capCents = Math.ceil((Number.isFinite(capUsd) ? capUsd : 0) * 100 - 1e-6);
   return { ok: capCents <= leftCents, leftUsd: leftCents / 100, limitUsd: limit, atLeast: spent.atLeast };
@@ -350,3 +371,52 @@ export function monthlyRefusalText(room) {
   if (room.ok || room.leftUsd === null) return null;
   return `Max $${room.leftUsd.toFixed(2)} (monthly limit)`;
 }
+
+/**
+ * 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 }) {
+  const { rows, events } = readRunList({ home });
+  const settled = new Set(events.filter((e) => e.type === 'settled').map((e) => e.runid));
+  let n = 0;
+  for (const row of rowsAbove(rows, aboveRunid)) {
+    if (!Number.isInteger(row.pid) || settled.has(row.runid) || isLiveRunner(/** @type {number} */ (row.pid))) continue;
+    let spentUsd = 0;
+    try { spentUsd = legSpend(parseJsonl(row.spine).records).usd; } catch { /* no spine: nothing was recorded spent */ }
+    appendRunEvent({ runid: row.runid, type: 'settled', by, reason: 'process gone', spentUsd, spendComplete: false, at: new Date().toISOString() }, { home });
+    n += 1;
+  }
+  return n;
+}
+
+/**
+ * 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 }) {
+  const cfg = readConfig({ home });
+  if (cfg.problem) throw new ConfigError(cfg.problem);
+  if (monthlyLimitOf(cfg.config, home) === null) return { room: { ok: true, leftUsd: null, limitUsd: null, atLeast: false }, claimed: false };
+  try { appendRun(row, { home }); } catch (/** @type {any} */ e) {
+    throw new ConfigError(`cannot write this run's claim to the run list (${e.message})`);
+  }
+  settleDeadClaims({ home, by: row.runid, aboveRunid: row.runid });
+  const room = checkMonthlyRoom({ capUsd, home, now, aboveRunid: row.runid });
+  if (!room.ok) {
+    try { appendRunEvent({ runid: row.runid, type: 'released', by: row.runid, reason: 'refused', at: new Date().toISOString() }, { home }); } catch { /* the refusal stands; a stranded row of a dead process is closed by the next run */ }
+    return { room, claimed: false };
+  }
+  return { room, claimed: true };
+}

package/src/panel/authorsession.js

@@ -20,7 +20,8 @@
 // `src/panel/server.js`'s POST routes). Nothing here changes what a step
 // means or what an answer does — only where the answer comes from.
 
-import { applyConfiguredKey, keyNameFor, modelChoiceFor, rowsForHome } from '../providerrows.js';
+import { applyConfiguredKey, judgeRatesFor, keyNameFor, modelChoiceFor, ratesFor, rowsForHome } from '../providerrows.js';
+import { ConfigError } from '../config.js';
 import {
   mkdirSync, existsSync, writeFileSync, readdirSync,
 } from 'node:fs';
@@ -310,6 +311,15 @@ export function createSession(card, deps = {}) {
     const draftKeyName = keyNameFor(modelChoice.provider, modelChoice.baseUrl, keyCfg, modelChoice.name).name;
     const apiKey = draftEnv[providerEntry.envKey];
     if (!apiKey) { refuse(`${draftKeyName} not set. Stopped — nothing spent.`); return; }
+    // the customer's own price on this row (USD per 1M in config.json), resolved once here at $0 and
+    // handed to every model call this session makes; a bad price refuses, never falls back to the guess
+    /** @type {ReturnType<typeof ratesFor>} */
+    let draftPrice = null;
+    try { draftPrice = ratesFor(modelChoice.provider, modelChoice.baseUrl, keyCfg, modelChoice.name); } catch (e) {
+      if (!(e instanceof ConfigError)) throw e;
+      refuse(`${e.message}. Stopped — nothing spent.`);
+      return;
+    }
     const keyProblem = apiKeyProblem(apiKey);
     if (keyProblem) { refuse(`${draftKeyName} ${keyProblem}. Stopped — nothing spent.`); return; }
 
@@ -422,8 +432,8 @@ export function createSession(card, deps = {}) {
     // `provider` for the model boundary) and/or `scout` (bypassing the real
     // paid scout) so it can drive the REAL confirm turn/ask()/revise/hash
     // machinery below with a deterministic fake, never a live provider call.
-    const generate = deps.generate ?? makeLoopGenerate(provider);
-    const confirmGenerate = deps.confirmGenerate ?? makeLoopGenerate(provider, { system: CONFIRM_SYSTEM });
+    const generate = deps.generate ?? makeLoopGenerate(provider, { rates: draftPrice?.rates ?? null });
+    const confirmGenerate = deps.confirmGenerate ?? makeLoopGenerate(provider, { system: CONFIRM_SYSTEM, rates: draftPrice?.rates ?? null });
 
     state.phase = 'drafting';
     state.progressLabel = 'drafting';
@@ -437,6 +447,7 @@ export function createSession(card, deps = {}) {
       questions: questionsFor(verdictType),
       writeScope, provider, generate,
       ceilingUsd: card.capUsd,
+      rates: draftPrice?.rates ?? null,
       onPhase, onCall,
       ask, confirmGenerate, isRepo: true, langResult,
       ...(deps.scout ? { scout: deps.scout } : {}),
@@ -470,7 +481,16 @@ export function createSession(card, deps = {}) {
     const judges = closeJudges(spec.closeDecl);
     const judge = judges ? resolveJobJudge(spec, modelChoice.provider, resolveWorkerModel) : null;
     let judgeProvider = null;
+    /** @type {ReturnType<typeof ratesFor>} */
+    let judgePrice = null;
     if (judge) {
+      try {
+        judgePrice = judgeRatesFor(judge, modelChoice.provider, modelChoice.baseUrl, draftPrice, keyCfg);
+      } catch (e) {
+        if (!(e instanceof ConfigError)) throw e;
+        refuse(`${e.message} — refusing before gate 4 spends anything`);
+        return;
+      }
       const judgeKeyValue = env.JUDGE_API_KEY ?? (judge.provider === modelChoice.provider ? draftEnv : applyConfiguredKey(env, judge.provider, undefined, keyCfg, judge.model))[resolveProvider(judge.provider).envKey];
       const judgeKeyProblem = judgeKeyValue ? apiKeyProblem(judgeKeyValue) : null;
       if (!judgeKeyValue || judgeKeyProblem) {
@@ -486,7 +506,7 @@ export function createSession(card, deps = {}) {
     const signing = await prepareSigningFn({
       spec, workdir: prep.tree, seedRef: authored.seedRef, timeoutMs,
       shellCapUsd: spec.budgetUsd, ceilingUsd: card.capUsd, priorCalls: [...metered],
-      judgeLoop: judgeProvider ? (o) => defaultJudgeLoop({ provider: judgeProvider, system: o.system }) : null,
+      judgeLoop: judgeProvider ? (o) => defaultJudgeLoop({ provider: judgeProvider, system: o.system, rates: judgePrice?.rates ?? null }) : null,
       judgeModel: judge?.model ?? null,
       onJudgeCost: (c) => onCall({ label: `${c.label}:${c.id}`, costUsd: c.costUsd, unpricedRounds: c.unpricedRounds }),
     });

package/src/planrun.js

@@ -762,6 +762,10 @@ ${scoutBlob || '(no scout notes)'}`;
  *   `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
@@ -983,7 +987,7 @@ ${scoutBlob || '(no scout notes)'}`;
  *   'branch-red' | 'cap-halt' | 'wall-halt' | 'provider-red' | 'interpreter-red' |
  *   'step-stalled' | 'hitl-pause' | 'hitl-decision-red' | `step-red:<id>`
  */
-export async function runPlan(job, { workdir, provider, nativeProvider, providerFor, judgeProvider = null, judgeModel = null, emit, remainingUsd, isUnpriced = () => false, spendComplete = () => true, capRuns = 3, strikeLimit = STRIKE_LIMIT, closeTimeoutMs, closeDir = null, maxStepRounds = 40, layerRoot = false, readShim = false, scout = true, scoutRounds = SCOUT_ROUNDS, bridge = null, now, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null, heldRuling = null, priorSpentUsd = 0, reviewDoor = null, doorRerun = null, resumable = true }) {
+export async function runPlan(job, { workdir, provider, nativeProvider, providerFor, judgeProvider = null, judgeModel = null, rates = null, judgeRates = null, emit, remainingUsd, isUnpriced = () => false, spendComplete = () => true, capRuns = 3, strikeLimit = STRIKE_LIMIT, closeTimeoutMs, closeDir = null, maxStepRounds = 40, layerRoot = false, readShim = false, scout = true, scoutRounds = SCOUT_ROUNDS, bridge = null, now, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null, heldRuling = null, priorSpentUsd = 0, reviewDoor = null, doorRerun = null, resumable = true }) {
   // MEMORY-CACHE: what the read shim (src/readshim.js) saved THIS run, summed across
   // every mkWorker's own shim instance (scout, drafter, each step's worker, the fix
   // worker) — one accumulator closed over by all of them, because the shim's ledger
@@ -1687,7 +1691,7 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
       // ride, so `runJob`'s ONE ledger accounts a close's spend exactly as it accounts
       // an attempt's (a budget funds the attempt PLUS its close), and a null cost trips
       // the same F6 pricing halt rather than being laundered into $0.
-      judgeLoop: judgeProvider ? (/** @type {{system: string}} */ o) => defaultJudgeLoop({ provider: judgeProvider, system: o.system }) : null,
+      judgeLoop: judgeProvider ? (/** @type {{system: string}} */ o) => defaultJudgeLoop({ provider: judgeProvider, system: o.system, rates: judgeRates }) : null,
       // the seam's other half (PRD item 32.1) — WHICH model that loop drives. Passed
       // through untouched: this module resolves no judge, exactly as it constructs no
       // provider. `runJudgedFloor` stops as a wiring gap when it is absent rather than
@@ -2750,7 +2754,7 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
         }
         return onLlmResult(arg);
       };
-      self = new Loop({ provider: loopProvider, system, policy, onLlmResult: metered, onToolResult: onToolOutcome });
+      self = new Loop({ provider: loopProvider, system, policy, onLlmResult: metered, onToolResult: onToolOutcome, ...(rates ? { rates } : {}) });
       return self;
     };
     /** @param {string} prompt @param {typeof toolDefs} [defs] */

package/src/providerrows.js

@@ -10,7 +10,7 @@
 // `applyConfiguredKey` / `modelChoiceFor` below — no second lookup exists. Key VALUES
 // never pass through here — only names.
 import { resolveProvider } from './providers.js';
-import { readConfig } from './config.js';
+import { readConfig, ConfigError } from './config.js';
 import { filledKeyNames } from './keysfile.js';
 
 /** DeepSeek's OpenAI-shaped endpoint (the same string the panel's Model menu used). */
@@ -73,6 +73,9 @@ export function defaultsFor(envName) {
  * @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
  */
 
 /**
@@ -90,6 +93,8 @@ export function keyRows({ filled, config }) {
       name: typeof s.name === 'string' ? s.name : d.name,
       provider: SHAPES.some((x) => x.id === s.shape) ? s.shape : d.shape,
       baseUrl: typeof s.baseUrl === 'string' ? s.baseUrl : d.baseUrl,
+      ...(Object.hasOwn(s, 'priceInPerM') ? { priceInPerM: s.priceInPerM } : {}),
+      ...(Object.hasOwn(s, 'priceOutPerM') ? { priceOutPerM: s.priceOutPerM } : {}),
     };
   });
 }
@@ -215,3 +220,82 @@ export function applyConfiguredKey(env, provider, baseUrl, rows, model) {
   if (!k.chosen && value !== 'null') return env;
   return { ...env, [k.builtIn]: usableKey(value) };
 }
+
+/**
+ * A per-1M price for a readout: two decimals at least ($1.20), more when the number needs them so a
+ * tiny price never rounds to $0.00 or $0.01 ($0.006, $0.0004).
+ * @param {number} n USD per 1M tokens
+ * @returns {string}
+ */
+function perMoney(n) {
+  const shown = String(n);
+  if (!shown.includes('e') && (shown.split('.')[1] ?? '').length >= 2) return `$${shown}`;
+  if (shown.includes('e')) return `$${n.toFixed(12).replace(/0+$/, '').replace(/\.$/, '')}`;
+  return `$${n.toFixed(2)}`;
+}
+
+/**
+ * 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)`.
+ * @param {{ inPerM: number, outPerM: number, envName: string }} price a {@link ratesFor} result
+ * @returns {string}
+ */
+export function priceReadout(price) {
+  return `yours: in ${perMoney(price.inPerM)} / out ${perMoney(price.outPerM)} per 1M tokens (${price.envName} row)`;
+}
+
+/**
+ * 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, baseUrl, rows, model) {
+  const row = findRow(rows, { provider, baseUrl, model });
+  if (!row) return null;
+  const hasIn = row.priceInPerM !== undefined;
+  const hasOut = row.priceOutPerM !== undefined;
+  if (!hasIn && !hasOut) return null;
+  if (hasIn !== hasOut) {
+    throw new ConfigError(`keys.${row.envName} sets ${hasIn ? 'priceInPerM' : 'priceOutPerM'} but not ${hasIn ? 'priceOutPerM' : 'priceInPerM'} — set both prices (USD per 1M tokens) or neither`);
+  }
+  for (const field of /** @type {const} */ (['priceInPerM', 'priceOutPerM'])) {
+    const v = row[field];
+    if (!(typeof v === 'number' && Number.isFinite(v) && v >= 0)) {
+      throw new ConfigError(`keys.${row.envName}.${field} must be a number, 0 or more (USD per 1M tokens) — fix it in config.json or remove both price lines`);
+    }
+  }
+  const inPerM = /** @type {number} */ (row.priceInPerM);
+  const outPerM = /** @type {number} */ (row.priceOutPerM);
+  return { rates: { in: inPerM / 1000, out: outPerM / 1000 }, inPerM, outPerM, envName: row.envName };
+}
+
+/**
+ * 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, workerProvider, workerBaseUrl, workerPrice, rows) {
+  if (judge.provider !== workerProvider) return ratesFor(judge.provider, undefined, rows, judge.model);
+  const want = endpointOf(judge.provider, workerBaseUrl);
+  const named = judge.model ? rows.some((r) => r.provider === judge.provider && endpointOf(r.provider, r.baseUrl) === want && r.name === judge.model) : false;
+  return named ? ratesFor(judge.provider, workerBaseUrl, rows, judge.model) : workerPrice;
+}

package/src/run.js

@@ -95,6 +95,11 @@ async function primitiveSmoke(workdir) {
  *   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
@@ -265,7 +270,7 @@ async function primitiveSmoke(workdir) {
  *   deliberately NOT in the resumable/checkpoint set (`src/reuse.js`) — an
  *   unknown in-flight state is not a known-safe resume point.
  */
-export async function runJob(rawSpec, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider = null, judgeModel = null, emit, capRuns = 3, strikeLimit, shellCapUsd = 2, closeTimeoutMs, closeDir = null, layerRoot = false, readShim = false, scout = true, bridge = null, draftSpentUsd = 0, draftSpendComplete = true, priorSpentUsd = 0, priorSpendComplete = true, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null, heldRuling = null, reviewDoor = null, doorRerun = null, resumable = true }) {
+export async function runJob(rawSpec, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider = null, judgeModel = null, rates = null, judgeRates = null, emit, capRuns = 3, strikeLimit, shellCapUsd = 2, closeTimeoutMs, closeDir = null, layerRoot = false, readShim = false, scout = true, bridge = null, draftSpentUsd = 0, draftSpendComplete = true, priorSpentUsd = 0, priorSpendComplete = true, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null, heldRuling = null, reviewDoor = null, doorRerun = null, resumable = true }) {
   // THE READ SHIM's ARM, resolved at the door — the FIRST thing this entry does,
   // before the ledger, before the approval gate, before a byte of the spec is read.
   // An unrecognised spelling throws here at zero cost instead of being coerced by
@@ -532,7 +537,7 @@ export async function runJob(rawSpec, { approvals, workdir, provider, nativeProv
   // accounts it natively (F12) and the job-end money contract is unchanged.
   {
     const outcome = await runPlan(job, {
-      workdir, provider, nativeProvider, providerFor, judgeProvider, judgeModel, emit: meter, capRuns, ...(strikeLimit !== undefined ? { strikeLimit } : {}), closeTimeoutMs, closeDir, layerRoot, readShim, scout, bridge, priorWallMs: chainWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun, priorSpentUsd: chainFoldUsd, resumable,
+      workdir, provider, nativeProvider, providerFor, judgeProvider, judgeModel, rates, judgeRates, emit: meter, capRuns, ...(strikeLimit !== undefined ? { strikeLimit } : {}), closeTimeoutMs, closeDir, layerRoot, readShim, scout, bridge, priorWallMs: chainWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun, priorSpentUsd: chainFoldUsd, resumable,
       // hamr's ruling 2026-09-28 — ONE cap covers drafting + run: the run's
       // enforced ceiling is the signed `budgetUsd` (unchanged, still in the
       // spec hash) MINUS whatever drafting already spent on this job before

package/src/runlist.js

@@ -13,7 +13,7 @@
 // caller doesn't know one) — a relative path here would resolve differently
 // depending on who later reads the file. `via` says how the row was minted:
 // `'run-u'` (src/userrun.js, the person-path run), `'bundle'`
-// (src/cli.js:doRun, `bareloop run`), or `'backfill'` (`bareloop runs
+// (src/userrun.js's bundle door, `bareloop run`), or `'backfill'` (`bareloop runs
 // backfill`, reconstructed from an archived spine already on disk).
 //
 // SECRETS: a row carries only paths/ids/names — never a key, a prompt, or any
@@ -29,6 +29,7 @@
 
 import {
   existsSync, mkdirSync, appendFileSync, chmodSync, readdirSync, statSync,
+  readFileSync,
 } from 'node:fs';
 import { homedir } from 'node:os';
 import {
@@ -57,7 +58,9 @@ export function runlistPath(home) {
 }
 
 /**
- * @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).
  */
 
 /**
@@ -87,7 +90,8 @@ export function appendRun(row, opts = {}) {
   mkdirSync(home, { recursive: true, mode: 0o700 });
   if (existsSync(path)) {
     const { records } = parseJsonl(path);
-    if (records.some((r) => r && r.runid === row.runid)) {
+    // only RUN rows count: a settled/released event names the same runid for another purpose
+    if (records.some((r) => r && !r.type && r.runid === row.runid)) {
       return { appended: false, reason: 'duplicate-runid' };
     }
   }
@@ -96,18 +100,86 @@ export function appendRun(row, opts = {}) {
   return { appended: true };
 }
 
+/**
+ * @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, opts = {}) {
+  const path = runlistPath(opts.home);
+  mkdirSync(runlistHome(opts.home), { recursive: true, mode: 0o700 });
+  appendFileSync(path, `${JSON.stringify(event)}\n`);
+  try { chmodSync(path, 0o600); } catch { /* best-effort perms */ }
+}
+
 /**
  * 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 = {}) {
   const path = runlistPath(opts.home);
-  if (!existsSync(path)) return { rows: [], skipped: 0 };
+  if (!existsSync(path)) return { rows: [], skipped: 0, events: [] };
   const { records, skipped } = parseJsonl(path);
-  return { rows: records, skipped };
+  // the FIRST settle for a runid is authoritative: two runs may both close the same dead claim, and the
+  // second note is a duplicate (a `released` line likewise); file order decides, later copies are ignored
+  const seen = new Set();
+  /** @type {RunEvent[]} */
+  const events = records.filter((r) => {
+    if (!r || (r.type !== 'settled' && r.type !== 'released')) return false;
+    const key = `${r.type}:${r.runid}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+  const released = new Set(events.filter((e) => e.type === 'released').map((e) => e.runid));
+  const rows = records.filter((r) => r && !r.type && !released.has(r.runid));
+  return { rows, skipped, events };
+}
+
+/**
+ * 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) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); } catch (/** @type {any} */ e) { if (e?.code !== 'EPERM') return false; }
+  /** @type {string|null} */
+  let cmdline = null;
+  try { cmdline = readFileSync(`/proc/${pid}/cmdline`, 'utf8'); } catch { /* no /proc, or not ours */ }
+  if (cmdline === null) return true;
+  const names = ['bareloop', 'bareloop.mjs', 'run-u.mjs', 'u-watchdog.mjs'];
+  const [argv0 = '', ...rest] = cmdline.split('\0');
+  const first = basename(argv0);
+  if (names.includes(first)) return true;
+  return first.startsWith('node') && rest.some((a) => names.includes(basename(a)));
 }
 
 /**

package/src/source.js

@@ -441,11 +441,15 @@ async function fetchOnce(url, timeoutMs) {
  * 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 async function prepareSource({ source, into, destination, fetchTimeoutMs = PROVIDER_TIMEOUT_MS }) {
+export async function prepareSource({ source, into, destination, fetchTimeoutMs = PROVIDER_TIMEOUT_MS, afterScan }) {
   const intoAbs = resolve(into);
   if (existsSync(intoAbs)) {
     return refuse('into-exists', `${intoAbs} already exists — a source door writes a FRESH tree, never reuses one (the export worktree rule)`);
@@ -674,6 +678,7 @@ export async function prepareSource({ source, into, destination, fetchTimeoutMs
   // (verified: 0o755 in, 0o755 out; a plain `writeFile` defaults to 0o644),
   // so the replacement chmod's the destination from a fresh `stat` to keep
   // that behaviour unchanged.
+  if (afterScan) await afterScan();
   for (let i = 0; i < frozen.files.length; i += 1) {
     const f = frozen.files[i];
     const dest = join(treeDir, treeRel(f.rel));