bareloop 0.31.0 → 0.33.0

package/src/monthly.js

@@ -0,0 +1,422 @@
+// PANEL-BUILD.md P4a item 2 — the monthly $ limit (R1, R2, R3).
+//
+// `monthSpend` sums what this local calendar month's runs spent, read off each run's own
+// spine (the run list `~/.config/bareloop/runs.jsonl` carries no money). `checkMonthlyRoom`
+// asks whether a run's $ cap fits in what is left. It is called at the ONE run-start seam
+// both the CLI (`bareloop run-u`) and the panel (which spawns `run-u`) pass through
+// (`execute` in src/userrun.js), before any token spends, and by the panel's cap note.
+// 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).
+//
+// 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 { readConfig, configPath, ConfigError } from './config.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';
+
+// The Money tab's per-provider breakdown groups a run by the endpoint it ran on and names
+// the groups it knows the vendor of. This is HISTORY labelling for spend already recorded
+// (an archived run keeps its provider whatever Settings holds today) — not the Providers
+// rows, which come from the keys file (src/providerrows.js).
+/** @type {readonly {id: string, name: string}[]} */
+const MONEY_LABELS = Object.freeze([
+  { id: 'anthropic', name: 'Anthropic' }, { id: 'openai', name: 'OpenAI' },
+  { id: 'gemini', name: 'Gemini' }, { id: 'deepseek', name: 'DeepSeek' },
+]);
+
+/**
+ * Which known vendor a run's `(provider, baseUrl)` belongs to. `openai-api` with no override
+ * is OpenAI; with DeepSeek's host it is DeepSeek; with any OTHER override it is none (null —
+ * never silently pooled into OpenAI's figures).
+ * @param {string|null|undefined} provider
+ * @param {string|null|undefined} baseUrl
+ * @returns {string|null} a MONEY_LABELS id, or null
+ */
+function rowIdFor(provider, baseUrl) {
+  if (provider === 'anthropic-api') return 'anthropic';
+  if (provider === 'gemini-api') return 'gemini';
+  if (provider === 'openai-api') {
+    if (!baseUrl) return 'openai';
+    try {
+      const host = new URL(baseUrl).hostname;
+      if (host === 'api.deepseek.com') return 'deepseek';
+    } catch { /* an unparseable override is no known vendor */ }
+    return null;
+  }
+  return null;
+}
+
+/**
+ * One run's own spend, off its spine records: this LEG's figure (never the chain fold),
+ * plus the drafting spend the run was signed with (counted once — on the first leg only).
+ * @param {any[]} records
+ * @returns {{ usd: number, complete: boolean }}
+ */
+export function legSpend(records) {
+  const jobStart = records.find((r) => r && r.type === 'job-start') ?? null;
+  const jobEnd = records.findLast((r) => r && r.type === 'job-end') ?? null;
+  const rounds = records.filter((r) => r && SPEND_RECORD_TYPES.includes(r.type));
+  const pricedSum = rounds.reduce((a, r) => (typeof r.costUsd === 'number' && Number.isFinite(r.costUsd) ? a + r.costUsd : a), 0);
+  const unpriced = rounds.filter((r) => !(typeof r.costUsd === 'number' && Number.isFinite(r.costUsd))).length;
+  let usd = pricedSum;
+  let complete = false;
+  if (jobEnd) {
+    const eng = jobEnd.engagementSpentUsd;
+    usd = typeof eng === 'number' && Number.isFinite(eng) ? eng : pricedSum;
+    complete = jobEnd.spendComplete === true && unpriced === 0;
+  }
+  // drafting spend: a RESUMED / door-rerun leg carries the flag again but the first leg already counted it
+  const resumed = !!jobStart && 'priorSpentUsd' in jobStart;
+  if (jobStart && !resumed && typeof jobStart.draftSpentUsd === 'number' && Number.isFinite(jobStart.draftSpentUsd) && jobStart.draftSpentUsd > 0) {
+    usd += jobStart.draftSpentUsd;
+    if (jobStart.draftSpendComplete === false) complete = false;
+  }
+  return { usd, complete };
+}
+
+/**
+ * One run's wall time off its spine: job-start -> job-end when the run ended (exact), else the
+ * first -> last record floor (the SAME floor a died / still-running run's "at least" wall uses,
+ * `floorsFromRecords`). `ms` null = unknown — never 0.
+ * @param {any[]} records
+ * @returns {{ ms: number|null, complete: boolean }}
+ */
+export function legWall(records) {
+  const jobStart = records.find((r) => r && r.type === 'job-start') ?? null;
+  const jobEnd = records.findLast((r) => r && r.type === 'job-end') ?? null;
+  const a = Date.parse(jobStart?.ts);
+  const b = Date.parse(jobEnd?.ts);
+  if (jobEnd && Number.isFinite(a) && Number.isFinite(b) && b >= a) return { ms: b - a, complete: true };
+  return { ms: floorsFromRecords(records).wallFloorMs, complete: false };
+}
+
+/**
+ * Tokens a spine's rounds processed (input + output + cache read + cache write — all four,
+ * so a cache-heavy run is not under-reported), off the real `usage` field names.
+ * @param {any[]} records
+ * @returns {number}
+ */
+export function legTokens(records) {
+  let n = 0;
+  for (const r of records) {
+    if (!r || !SPEND_RECORD_TYPES.includes(r.type) || !r.usage) continue;
+    for (const k of ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheCreationTokens']) {
+      const v = r.usage[k];
+      if (typeof v === 'number' && Number.isFinite(v)) n += v;
+    }
+  }
+  return n;
+}
+
+/**
+ * @typedef {object} Leg
+ * @property {Date} at when the run was listed
+ * @property {string|null} provider job-start's provider (null = an older spine that carried none)
+ * @property {string|null} baseUrl
+ * @property {number} usd this leg's spend (a floor when `!complete`)
+ * @property {boolean} complete every figure behind `usd` is known
+ * @property {number} tokens
+ * @property {string|null} model job-start's model (older spines carry a model but no provider)
+ * @property {number|null} wallMs this leg's wall time (null = unknown; a floor when `!wallComplete`)
+ * @property {boolean} wallComplete the wall is the exact job-start -> job-end span
+ * @property {number} vouchedRounds rounds priced by a rate somebody vouched for (`provider`/`caller`)
+ * @property {number} otherRounds every other round: a built-in guess, unpriced, or no provenance on record
+ * @property {number} reservedUsd what the refusal check counts: `usd`, or the leg's cap when the run is in flight
+ * @property {boolean} unreadable the spine was missing/unreadable or the listed date was bad (spend unknown)
+ */
+
+/**
+ * What the refusal check counts for one run: its spend, unless it is IN FLIGHT (`job-start`, no
+ * `job-end`, spine written to within DIED_MTIME_MS of `nowMs`), when it is the larger of that
+ * spend and the leg's own cap — the signed `budgetUsd` on the spine's `job-start` less the fold
+ * a resumed leg inherited (`priorSpentUsd`), the same figure the run-start seam computes
+ * (`legCapUsd`, src/userrun.js). A spine that records no `budgetUsd` reserves nothing extra.
+ * @param {any[]} records
+ * @param {string} spinePath
+ * @param {number} nowMs
+ * @param {number} usd the leg's spend so far
+ * @returns {number}
+ */
+function inFlightCapUsd(records, spinePath, nowMs, usd) {
+  if (records.some((r) => r && r.type === 'job-end')) return usd;
+  const start = records.find((r) => r && r.type === 'job-start') ?? null;
+  if (!start || !(typeof start.budgetUsd === 'number' && Number.isFinite(start.budgetUsd))) return usd;
+  let mtimeMs;
+  try { mtimeMs = statSync(spinePath).mtimeMs; } catch { return usd; }
+  if (nowMs - mtimeMs > DIED_MTIME_MS) return usd; // stale — died, counts its floor
+  const fold = typeof start.priorSpentUsd === 'number' && Number.isFinite(start.priorSpentUsd) ? start.priorSpentUsd : 0;
+  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, 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: 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 };
+    // 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, reservedUsd: heldCap ?? 0 }); continue; }
+    const start = records.find((r) => r && r.type === 'job-start') ?? null;
+    const leg = legSpend(records);
+    const prov = spendProvenance(records);
+    const wall = legWall(records);
+    legs.push({
+      at,
+      model: typeof start?.model === 'string' ? start.model : null,
+      wallMs: wall.ms,
+      wallComplete: wall.complete,
+      provider: typeof start?.provider === 'string' ? start.provider : null,
+      baseUrl: typeof start?.baseUrl === 'string' ? start.baseUrl : null,
+      usd: leg.usd,
+      complete: leg.complete,
+      tokens: legTokens(records),
+      vouchedRounds: prov.vouched.rounds,
+      otherRounds: prov.guessed.rounds + prov.unpriced.rounds + prov.unknown.rounds,
+      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,
+    });
+  }
+  return legs;
+}
+
+/**
+ * @param {Date} at
+ * @param {Date} now
+ * @returns {boolean} same LOCAL calendar month
+ */
+const sameLocalMonth = (at, now) => at.getFullYear() === now.getFullYear() && at.getMonth() === now.getMonth();
+
+/**
+ * @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 = {}) {
+  const nowDate = new Date((opts.now ?? Date.now)());
+  let usd = 0;
+  let reservedUsd = 0;
+  let atLeast = false;
+  let runs = 0;
+  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; reservedUsd += leg.reservedUsd; continue; }
+    usd += leg.usd;
+    reservedUsd += leg.reservedUsd;
+    if (!leg.complete) atLeast = true;
+  }
+  return { usd, atLeast, runs, reservedUsd };
+}
+
+/**
+ * The Money tab's figures: all-time and this-month spend, and per-provider breakdown
+ * (rows from `rowIdFor`; a run on no known row lands under its own provider name, never
+ * pooled into another row). Any leg with unknown spend makes the figure it belongs to
+ * an "at least".
+ * @param {{ home?: string, now?: () => number, rows?: readonly import('./providerrows.js').KeyRow[] }} [opts] `rows` = the Providers rows: when given, `tokensByRow` sums each row's tokens
+ * @returns {{ tokensByRow: Record<string, number>, total: {usd: number, atLeast: boolean, tokens: number}, month: {usd: number, atLeast: boolean, tokens: number},
+ *   byProvider: Record<string, {label: string, monthUsd: number, monthAtLeast: boolean, totalUsd: number, totalAtLeast: boolean, tokens: number, vouchedRounds: number, otherRounds: number, monthWallMs: number|null, monthWallAtLeast: boolean, totalWallMs: number|null, totalWallAtLeast: boolean}> }}
+ */
+export function spendSummary(opts = {}) {
+  const nowDate = new Date((opts.now ?? Date.now)());
+  const total = { usd: 0, atLeast: false, tokens: 0 };
+  const month = { usd: 0, atLeast: false, tokens: 0 };
+  /** @type {Record<string, {label: string, monthUsd: number, monthAtLeast: boolean, totalUsd: number, totalAtLeast: boolean, tokens: number, vouchedRounds: number, otherRounds: number, monthWallMs: number|null, monthWallAtLeast: boolean, totalWallMs: number|null, totalWallAtLeast: boolean}>} */
+  const byProvider = {};
+  /** runs per provider in each scope, and how many had a known wall — unknown is never 0
+   * @type {Record<string, {monthRuns: number, monthKnown: number, totalKnown: number}>} */
+  const wallSeen = {};
+  /** total tokens of the runs each Providers row served (matched by shape + endpoint + model) @type {Record<string, number>} */
+  const tokensByRow = {};
+  for (const leg of readLegs({ home: opts.home })) {
+    let served = opts.rows ? findRow(opts.rows, { provider: leg.provider, baseUrl: leg.baseUrl, model: leg.model }) : null;
+    // an older spine records a model but no provider: it counts toward the row whose Name EXACTLY
+    // equals that model. Two rows sharing the Name make it ambiguous, so it counts toward neither.
+    if (opts.rows && leg.provider === null && leg.model !== null) {
+      const named = opts.rows.filter((r) => r.name === leg.model);
+      served = named.length === 1 ? named[0] : null;
+    }
+    if (served) tokensByRow[served.envName] = (tokensByRow[served.envName] ?? 0) + leg.tokens;
+    const inMonth = Number.isNaN(leg.at.getTime()) ? true : sameLocalMonth(leg.at, nowDate);
+    const id = rowIdFor(leg.provider, leg.baseUrl);
+    // an older spine carries a model but no provider: say so honestly, one row per model —
+    // never a provider guessed from the model's name
+    const notRecorded = id === null && leg.provider === null;
+    const key = id ?? (notRecorded ? `not-recorded:${leg.model ?? ''}` : `other:${leg.provider}${leg.baseUrl ? ` @ ${leg.baseUrl}` : ''}`);
+    const label = id ? (MONEY_LABELS.find((r) => r.id === id)?.name ?? id)
+      : (notRecorded ? (leg.model ? `not recorded (model ${leg.model})` : 'not recorded') : key.slice('other:'.length));
+    const p = (byProvider[key] ??= { label, monthUsd: 0, monthAtLeast: false, totalUsd: 0, totalAtLeast: false, tokens: 0, vouchedRounds: 0, otherRounds: 0, monthWallMs: 0, monthWallAtLeast: false, totalWallMs: 0, totalWallAtLeast: false });
+    const w = (wallSeen[key] ??= { monthRuns: 0, monthKnown: 0, totalKnown: 0 });
+    const unknown = leg.unreadable || !leg.complete;
+    const wallKnown = !leg.unreadable && leg.wallMs !== null;
+    const wallAtLeast = !wallKnown || !leg.wallComplete;
+    total.usd += leg.usd; total.tokens += leg.tokens; if (unknown) total.atLeast = true;
+    p.totalUsd += leg.usd; p.tokens += leg.tokens; p.vouchedRounds += leg.vouchedRounds; p.otherRounds += leg.otherRounds; if (unknown) p.totalAtLeast = true;
+    if (wallKnown) { p.totalWallMs = /** @type {number} */ (p.totalWallMs) + /** @type {number} */ (leg.wallMs); w.totalKnown += 1; }
+    if (wallAtLeast) p.totalWallAtLeast = true;
+    if (inMonth) {
+      month.usd += leg.usd; month.tokens += leg.tokens; if (unknown) month.atLeast = true;
+      p.monthUsd += leg.usd; if (unknown) p.monthAtLeast = true;
+      w.monthRuns += 1;
+      if (wallKnown) { p.monthWallMs = /** @type {number} */ (p.monthWallMs) + /** @type {number} */ (leg.wallMs); w.monthKnown += 1; }
+      if (wallAtLeast) p.monthWallAtLeast = true;
+    }
+  }
+  // runs in scope but not one with a known wall = unknown (null), never a clean 0
+  for (const [key, p] of Object.entries(byProvider)) {
+    const w = wallSeen[key];
+    if (w.totalKnown === 0) p.totalWallMs = null;
+    if (w.monthRuns > 0 && w.monthKnown === 0) p.monthWallMs = null;
+  }
+  return { tokensByRow, total, month, byProvider };
+}
+
+/**
+ * @typedef {object} MonthlyRoom
+ * @property {boolean} ok
+ * @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
+ */
+
+/**
+ * The person's monthly limit off a parsed config.json: key absent (or null) = no limit (null);
+ * a number above 0 = the limit; ANY other value present is a broken setting and throws
+ * `ConfigError` — a limit the file names but this code cannot read never reads as "no limit".
+ * @param {Record<string, any>} config
+ * @param {string} [home]
+ * @returns {number|null}
+ */
+export function monthlyLimitOf(config, home) {
+  const limit = config.monthlyLimitUsd;
+  if (limit === undefined || limit === null) return null;
+  if (typeof limit === 'number' && Number.isFinite(limit) && limit > 0) return limit;
+  const shown = typeof limit === 'number' ? String(limit) : JSON.stringify(limit);
+  throw new ConfigError(`${configPath(home)} has monthlyLimitUsd = ${shown}, which is not a number above 0 — fix it or remove the line`);
+}
+
+/**
+ * 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, aboveRunid?: string }} args `aboveRunid`: count only the claims listed above that run (a claim in progress)
+ * @returns {MonthlyRoom}
+ */
+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, 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 };
+}
+
+/**
+ * The ONE refusal text, everywhere (CLI, panel cap note, panel Sign refusal).
+ * @param {MonthlyRoom} room
+ * @returns {string|null} null when the run fits
+ */
+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/authorroutes.js

@@ -21,8 +21,13 @@ import { randomBytes } from 'node:crypto';
 import { spawn as realSpawn } from 'node:child_process';
 import { openSync } from 'node:fs';
 import { join } from 'node:path';
-import { createSession, validateJobCard, MODEL_OPTIONS } from './authorsession.js';
-import { resolveProvider, apiKeyProblem, checkProviderReachable } from '../providers.js';
+import { readFileSync } from 'node:fs';
+import { createSession, validateJobCard } from './authorsession.js';
+import { checkMonthlyRoom, monthlyRefusalText } from '../monthly.js';
+import { ConfigError } from '../config.js';
+import { keysForDoor, keysHome } from '../keysfile.js';
+import { keyNameFor, modelChoiceFor, rowsForHome, chatModels, usableKey } from '../providerrows.js';
+import { apiKeyProblem, checkProviderReachable } from '../providers.js';
 
 /** @returns {string} a fresh per-process token — never persisted, never logged */
 export function mintToken() {
@@ -68,10 +73,12 @@ const TERMINAL_PHASES = new Set(['refused', 'abandoned', 'error', 'signed', 'sig
  * deliberately has none of).
  * @param {{ port: number, token: string, env?: Record<string,string|undefined>,
  *   sessionsRoot?: string, spawnFn?: typeof realSpawn, bareloopBin?: string,
- *   jobsDir?: string, fetchImpl?: typeof fetch }} opts
+ *   jobsDir?: string, fetchImpl?: typeof fetch, home?: string }} opts
  */
 export function createAuthorRoutes(opts) {
-  const env = opts.env ?? process.env;
+  // the RAW env with the keys file re-merged on every use, so an edited file takes effect
+  // without a restart (never a start-time snapshot). An injected env with no `home` skips the file.
+  const envNow = () => keysForDoor({ env: opts.env, keysHome: opts.home }).env;
   const spawnFn = opts.spawnFn ?? realSpawn;
   const bareloopBin = opts.bareloopBin ?? new URL('../../bin/bareloop.mjs', import.meta.url).pathname;
   // TEST SEAM ONLY: a test injects a fake `fetch`-shaped function so the
@@ -111,17 +118,17 @@ export function createAuthorRoutes(opts) {
       if (req.method !== 'GET') { send(405, { ok: false, error: 'GET only' }); return true; }
       const q = new URL(/** @type {string} */ (req.url), 'http://127.0.0.1').searchParams;
       const modelId = q.get('model') ?? '';
-      const choice = MODEL_OPTIONS[modelId];
+      const rows = rowsForHome(keysHome(opts.home));
+      const choice = modelChoiceFor(rows, modelId);
       if (!choice) { send(400, { ok: false, error: `unknown model "${modelId}"` }); return true; }
-      /** @type {any} */
-      let providerEntry;
-      try { providerEntry = resolveProvider(choice.provider); } catch (e) { send(400, { ok: false, error: /** @type {Error} */ (e).message }); return true; }
-      const raw = env[providerEntry.envKey];
+      // the key of the Settings row this Name belongs to
+      const keyName = keyNameFor(choice.provider, choice.baseUrl, rows, choice.name).name;
+      const raw = envNow()[keyName];
       const problem = raw ? apiKeyProblem(raw) : null;
       const keyStatus = !raw ? 'missing' : (problem ? 'bad-shape' : 'found');
       if (keyStatus !== 'found') {
         send(200, {
-          ok: true, envKey: providerEntry.envKey, keyStatus, keyProblem: problem,
+          ok: true, envKey: keyName, keyStatus, keyProblem: problem,
           reachability: { checked: false, reachable: null, modelListed: null, status: null, note: 'no usable key to check reachability with' },
         });
         return true;
@@ -130,12 +137,12 @@ export function createAuthorRoutes(opts) {
       // `checkProviderReachable`'s own doc) — a short timeout so a flaky
       // endpoint never hangs the card.
       checkProviderReachable({
-        providerName: choice.provider, apiKey: /** @type {string} */ (raw), model: providerEntry.tiers.sonnet,
+        providerName: choice.provider, apiKey: /** @type {string} */ (usableKey(raw)), model: choice.name,
         baseUrl: choice.baseUrl, fetchImpl, timeoutMs: 4000,
       }).then((r) => {
         send(200, {
           ok: true,
-          envKey: providerEntry.envKey,
+          envKey: keyName,
           keyStatus,
           keyProblem: null,
           reachability: {
@@ -146,13 +153,39 @@ export function createAuthorRoutes(opts) {
       return true;
     }
 
+    // ── P4a: the monthly-limit note under the cap field. READ-ONLY, $0 — the same
+    // library check (`checkMonthlyRoom`, src/monthly.js) the run-start seam and the
+    // Sign refusal use, so the note the person sees is never a second opinion. The
+    // page is never the arbiter: Sign & run re-checks server-side regardless.
+    // ── P4b: Chat's Model menu IS the Settings rows (a blank Name is not offered). ──
+    if (pathname === '/api/author/models') {
+      if (req.method !== 'GET') { send(405, { ok: false, error: 'GET only' }); return true; }
+      send(200, { ok: true, models: chatModels(rowsForHome(keysHome(opts.home))) });
+      return true;
+    }
+
+    if (pathname === '/api/author/monthly-check') {
+      if (req.method !== 'GET') { send(405, { ok: false, error: 'GET only' }); return true; }
+      const q = new URL(/** @type {string} */ (req.url), 'http://127.0.0.1').searchParams;
+      const cap = Number(q.get('cap'));
+      if (!Number.isFinite(cap) || cap <= 0) { send(200, { ok: true, refusal: null }); return true; }
+      try {
+        const room = checkMonthlyRoom({ capUsd: cap, home: opts.home });
+        send(200, { ok: true, refusal: monthlyRefusalText(room), leftUsd: room.leftUsd, atLeast: room.atLeast });
+      } catch (e) {
+        if (!(e instanceof ConfigError)) throw e;
+        send(200, { ok: true, refusal: null, configProblem: e.message });
+      }
+      return true;
+    }
+
     if (pathname === '/api/author/start') {
       if (req.method !== 'POST') { send(405, { ok: false, error: 'POST only' }); return true; }
       if (hasLiveSession()) { send(409, { ok: false, error: 'an authoring session is already live — one at a time' }); return true; }
       const card = body ?? {};
-      const v = validateJobCard(card);
+      const v = validateJobCard(card, { jobsDir: opts.jobsDir, rows: rowsForHome(keysHome(opts.home)) });
       if (!v.ok) { send(400, { ok: false, error: v.error }); return true; }
-      const session = createSession(card, { env, sessionsRoot: opts.sessionsRoot });
+      const session = createSession(card, { env: envNow(), sessionsRoot: opts.sessionsRoot, ...(opts.home !== undefined ? { home: opts.home } : {}) });
       sessions.set(session.id, session);
       send(200, { ok: true, sessionId: session.id, state: session.state });
       return true;
@@ -192,7 +225,7 @@ export function createAuthorRoutes(opts) {
     }
     if (sub === 'sign') {
       const claimedHash = String(body?.specHash ?? '');
-      const r = signRun(session, claimedHash, { env, spawnFn, bareloopBin, sessionsRoot: opts.sessionsRoot });
+      const r = signRun(session, claimedHash, { env: envNow(), spawnFn, bareloopBin, sessionsRoot: opts.sessionsRoot, home: opts.home });
       send(r.ok ? 200 : 400, r);
       return true;
     }
@@ -234,13 +267,25 @@ function panelMoney2(n) {
  * it to sign"), and this is where it is checked, not trusted.
  * @param {ReturnType<typeof createSession>} session
  * @param {string} claimedHash
- * @param {{env: any, spawnFn: typeof realSpawn, bareloopBin: string, sessionsRoot?: string}} o
+ * @param {{env: any, spawnFn: typeof realSpawn, bareloopBin: string, sessionsRoot?: string, home?: string}} o
  * @returns {{ok: boolean, error?: string, job?: string}}
  */
 export function signRun(session, claimedHash, o) {
   if (session.state.phase !== 'prepared') return { ok: false, error: `session is not prepared (phase=${session.state.phase}) — nothing to sign` };
   if (!session.state.specHash || claimedHash !== session.state.specHash) return { ok: false, error: 'spec hash mismatch — refusing to sign' };
   if (!session.state.resolvedSpecPath) return { ok: false, error: 'no resolved spec on disk — refusing to sign' };
+  // P4a — the monthly $ limit REFUSES here too, server-side, before anything is spawned
+  // (the page's note is a courtesy; this is the check). Same library call, same text as
+  // the run-start seam in src/userrun.js. The session stays `prepared`, so the person can
+  // lower nothing (the cap is signed in) but may raise the limit in Settings and sign again.
+  try {
+    const spec = JSON.parse(readFileSync(session.state.resolvedSpecPath, 'utf8'));
+    const refusal = monthlyRefusalText(checkMonthlyRoom({ capUsd: Number(spec.budgetUsd), home: o.home }));
+    if (refusal !== null) return { ok: false, error: refusal };
+  } catch (e) {
+    if (e instanceof ConfigError) return { ok: false, error: `${e.message} — refusing rather than guess the monthly limit` };
+    return { ok: false, error: 'could not read the signed spec to check the monthly limit — refusing to sign' };
+  }
   const logFile = join(session.state.outDir, 'run.log');
   // array argv, never a shell string — `--approve <hash>` is a literal
   // element, checkable byte-for-byte by a test stubbing `spawnFn`, and there