bareloop 0.31.0 → 0.32.0

package/src/keysfile.js

@@ -0,0 +1,156 @@
+// PANEL-BUILD.md P4a item 1 — the keys file loader (`~/.config/bareloop/.env`).
+//
+// Key VALUES live only in this file (chmod 600, outside any repo) and in the shell
+// environment — never in config.json, the spine, runs.jsonl, a log, or a page.
+// This is the ONE reader of that file. Plain `NAME=value` lines (an optional
+// `export ` prefix, `#` full-line comments, one pair of matching quotes around the
+// value); no dependency.
+//
+// Precedence: the SHELL wins. An explicit `export FOO=…` beats the file; the file
+// only fills names the shell leaves unset (or empty). The merged env is a NEW
+// object — `process.env` is never mutated.
+//
+// Values leave this module in exactly one place: the `env` of `loadKeysEnv`, which
+// goes to provider construction. Everything else it returns (`names`, `warning`) is
+// value-free by construction, and a parse problem never quotes the offending line.
+import { existsSync, readFileSync, statSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+/**
+ * `~/.config/bareloop` (or the injected override) — same home every other
+ * per-person file (runs.jsonl, config.json) lives in.
+ * @param {string} [home] test seam; production never passes it
+ * @returns {string}
+ */
+export function keysHome(home) {
+  return home ?? join(homedir(), '.config', 'bareloop');
+}
+
+/**
+ * @param {string} [home]
+ * @returns {string} `<home>/.env`
+ */
+export function keysFilePath(home) {
+  return join(keysHome(home), '.env');
+}
+
+const NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * Parse the file's text. Lines that are not `NAME=value` are skipped silently
+ * (never echoed — a malformed line may hold a secret).
+ * @param {string} text
+ * @returns {Record<string,string>}
+ */
+export function parseKeysText(text) {
+  /** @type {Record<string,string>} */
+  const out = {};
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line === '' || line.startsWith('#')) continue;
+    const body = line.startsWith('export ') ? line.slice(7).trimStart() : line;
+    const eq = body.indexOf('=');
+    if (eq <= 0) continue;
+    const name = body.slice(0, eq).trim();
+    if (!NAME_RE.test(name)) continue;
+    let value = body.slice(eq + 1).trim();
+    if (value.length >= 2 && (value[0] === '"' || value[0] === "'") && value.endsWith(value[0])) {
+      value = value.slice(1, -1);
+    }
+    out[name] = value;
+  }
+  return out;
+}
+
+/**
+ * The NAMES in the file that carry a non-empty value, in file order — the Providers rows
+ * (an empty preset line is not a row). Names only; a missing/unreadable file = none.
+ * @param {string} [home]
+ * @returns {string[]}
+ */
+export function filledKeyNames(home) {
+  try {
+    return Object.entries(parseKeysText(readFileSync(keysFilePath(home), 'utf8'))).filter(([, v]) => v !== '').map(([n]) => n);
+  } catch { return []; }
+}
+
+/**
+ * Create the keys file with the five empty preset lines when — and only when — it does not
+ * exist (mode 600). An existing file is never touched.
+ * @param {readonly string[]} presetNames the names to seed, in order
+ * @param {string} [home]
+ * @returns {boolean} true if it was created
+ */
+export function ensureKeysFile(presetNames, home) {
+  const file = keysFilePath(home);
+  if (existsSync(file)) return false;
+  mkdirSync(keysHome(home), { recursive: true });
+  try {
+    writeFileSync(file, presetNames.map((n) => `${n}=\n`).join(''), { mode: 0o600, flag: 'wx' });
+  } catch (/** @type {any} */ e) {
+    if (e?.code === 'EEXIST') return false; // lost a race: the file is there, untouched
+    throw e;
+  }
+  return true;
+}
+
+/**
+ * @typedef {object} KeysLoad
+ * @property {boolean} exists the file is there
+ * @property {string[]} names the NAMES the file defines (sorted; never values)
+ * @property {string|null} warning a plain-words warning (file readable by others, or
+ *   unreadable), else null — a warning, never a refusal
+ * @property {Record<string,string|undefined>} env shell env with the file filling the
+ *   names the shell does not set. THE ONLY place values leave this module.
+ */
+
+/**
+ * Load the keys file over an env. Missing file is fine (no names, env unchanged).
+ * @param {{ env?: Record<string,string|undefined>, home?: string }} [opts]
+ * @returns {KeysLoad}
+ */
+export function loadKeysEnv(opts = {}) {
+  const base = opts.env ?? process.env;
+  const file = keysFilePath(opts.home);
+  if (!existsSync(file)) return { exists: false, names: [], warning: null, env: { ...base } };
+  /** @type {string|null} */
+  let warning = null;
+  try {
+    const mode = statSync(file).mode & 0o777;
+    if ((mode & 0o077) !== 0) {
+      warning = `${file} is readable by other users (mode ${mode.toString(8)}) — run: chmod 600 ${file}`;
+    }
+  } catch { /* the read below reports it */ }
+  /** @type {Record<string,string>} */
+  let parsed = {};
+  try {
+    parsed = parseKeysText(readFileSync(file, 'utf8'));
+  } catch (/** @type {any} */ e) {
+    return { exists: true, names: [], warning: `${file} could not be read (${e?.code ?? 'error'})`, env: { ...base } };
+  }
+  /** @type {Record<string,string|undefined>} */
+  const env = { ...base };
+  for (const [name, value] of Object.entries(parsed)) {
+    if (!env[name]) env[name] = value;
+  }
+  return { exists: true, names: Object.keys(parsed).sort(), warning, env };
+}
+
+/**
+ * The door helper the CLI and the panel call: load the file only when the caller is
+ * on the REAL environment (no injected env) or names a keys home explicitly — so a
+ * test that injects `env` alone never reads the real `~/.config/bareloop/.env`.
+ * @param {{ env?: Record<string,string|undefined>, keysHome?: string }} deps
+ * @returns {KeysLoad & { env: Record<string,string|undefined>, home: string|undefined }}
+ *   `home` = the home the file was loaded from (the real `~/.config/bareloop` when none was
+ *   injected) — or `undefined` when loading was skipped (injected env, no keysHome). The
+ *   door passes it on so config.json (src/config.js) is read from the SAME place, and never
+ *   from the real home in a test.
+ */
+export function keysForDoor(deps) {
+  if (deps.env !== undefined && deps.keysHome === undefined) {
+    return { exists: false, names: [], warning: null, env: deps.env, home: undefined };
+  }
+  return { ...loadKeysEnv({ env: deps.env, home: deps.keysHome }), home: keysHome(deps.keysHome) };
+}

package/src/ledger.js

@@ -506,3 +506,29 @@ export function spendProvenance(events) {
   }
   return out;
 }
+
+/**
+ * The priced-rounds spend floor + first-record→last-record wall floor,
+ * derived straight off the spine's raw records — the same derivation a
+ * died run's "at least …" figures use, factored out so build item 6
+ * (2026-09-28) can hand a genuinely-still-running spine the identical
+ * floor instead of "unknown" on the Run tab, without a second copy of this
+ * math.
+ * @param {any[]} records raw parsed spine records
+ * @returns {{spendFloorUsd: number|null, wallFloorMs: number|null}}
+ */
+export function floorsFromRecords(records) {
+  let spendSum = 0;
+  let pricedCount = 0;
+  for (const r of records) {
+    if (!r || typeof r !== 'object' || !SPEND_RECORD_TYPES.includes(r.type)) continue; // worker-result echoes excluded by construction — not a spend type
+    if (typeof r.costUsd === 'number' && Number.isFinite(r.costUsd)) { spendSum += r.costUsd; pricedCount += 1; }
+  }
+  const spendFloorUsd = pricedCount > 0 ? spendSum : null;
+
+  const withTs = records.filter((r) => r && typeof r === 'object' && typeof r.ts === 'string');
+  const firstMs = withTs.length ? Date.parse(withTs[0].ts) : NaN;
+  const lastMs = withTs.length ? Date.parse(withTs[withTs.length - 1].ts) : NaN;
+  const wallFloorMs = Number.isFinite(firstMs) && Number.isFinite(lastMs) && lastMs >= firstMs ? lastMs - firstMs : null;
+  return { spendFloorUsd, wallFloorMs };
+}

package/src/monthly.js

@@ -0,0 +1,352 @@
+// 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).
+//
+// 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`).
+//
+// 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 { 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));
+}
+
+/**
+ * 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)
+ * @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;
+  /** @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; }
+    /** @type {any[]} */
+    let records;
+    try { records = parseJsonl(row.spine).records; } catch { legs.push(base); 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: resuming !== null && resolve(row.spine) === resuming ? leg.usd : 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, 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)
+ */
+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, resumingSpine: opts.resumingSpine })) {
+    // 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; }
+    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 (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
+ * 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
+ * @returns {MonthlyRoom}
+ */
+export function checkMonthlyRoom({ capUsd, home, now, resumingSpine }) {
+  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 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)`;
+}