bareloop 0.30.0 → 0.32.0

package/src/authorrun.js

@@ -100,6 +100,8 @@
 //                  item 34 L17) — `run-interview.mjs` asks for it and writes it
 //                  in; a draft missing one, or naming one the provider factory
 //                  does not know, dies here loud, listing the known table.
+import { keysForDoor } from './keysfile.js';
+import { applyConfiguredKey, keyNameFor, rowsForHome } from './providerrows.js';
 import {
   readFileSync, writeFileSync, appendFileSync, mkdirSync, existsSync, renameSync, statSync,
 } from 'node:fs';
@@ -141,6 +143,7 @@ class ExitSignal extends Error {
 /**
  * @typedef {object} Deps
  * @property {Record<string,string|undefined>} [env]
+ * @property {string} [keysHome] P4a — test seam: load this home's `.env` keys file even when `env` is injected.
  * @property {NodeJS.ReadStream} [stdin]
  * @property {NodeJS.WritableStream} [stdout]
  * @property {NodeJS.WritableStream} [stderr]
@@ -162,10 +165,13 @@ class ExitSignal extends Error {
  * @returns {Promise<number>} an exit code — never calls process.exit
  */
 export async function main(argv, deps = {}) {
-  const env = deps.env ?? process.env;
+  // P4a item 1 — the keys file fills what the shell leaves unset (shell wins).
+  const keys = keysForDoor(deps);
+  const env = keys.env;
   const stdin = deps.stdin ?? process.stdin;
   const stdout = deps.stdout ?? process.stdout;
   const stderr = deps.stderr ?? process.stderr;
+  if (keys.warning && deps.env === undefined) stderr.write(`WARNING: ${keys.warning}\n`);
   const out = (/** @type {string} */ s = '') => { stdout.write(`${s}\n`); };
   const err = (/** @type {string} */ s) => { stderr.write(`${s}\n`); };
   const invokedAs = deps.invokedAs ?? 'node scripts/run-author.mjs';
@@ -348,8 +354,9 @@ export async function main(argv, deps = {}) {
   // Only meaningful for a REPO source (PRD item 33 M3 piece 4, step S6): a
   // plain folder has no genre to detect and no code-shaped manifest to walk —
   // `LANG`/`langResult` stay at their "nothing to see" values and the confirm
-  // turn further down runs with `isRepo: false` (D5), which is what already
-  // skips the repo-only "worse than before" ask and the language pick alike.
+  // turn further down runs with `isRepo: false` (D5), which is what skips
+  // the language pick (the old repo-only "worse than before" ask is retired
+  // entirely as of 2026-09-28 — see src/authorflow.js's own retirement note).
   let langResult = /** @type {ReturnType<typeof detectLanguage>|null} */ (null);
   let LANG = 'none-detected';
   if (IS_REPO_SOURCE) {
@@ -498,8 +505,12 @@ export async function main(argv, deps = {}) {
 
   // Secrets load from the environment; they never enter argv (a command line is
   // world-readable on /proc) and they are never printed.
-  const AUTHOR_ENV_KEY = /** @type {NonNullable<typeof providerEntry>} */ (providerEntry).envKey;
-  const apiKey = env[AUTHOR_ENV_KEY];
+  // P4a item 4 — the key variable the person picked in Settings (config.json) stands in for
+  // the provider's built-in one; none picked = the built-in. Names only.
+  const keyCfg = rowsForHome(keys.home);
+  const authorEnv = applyConfiguredKey(env, PROVIDER_NAME, baseUrl, keyCfg);
+  const AUTHOR_ENV_KEY = keyNameFor(PROVIDER_NAME, baseUrl, keyCfg).name;
+  const apiKey = authorEnv[/** @type {NonNullable<typeof providerEntry>} */ (providerEntry).envKey];
   if (!apiKey) { err(`${AUTHOR_ENV_KEY} not set (secrets load from the environment — never the tree, never argv)`); throw new ExitSignal(2); }
   // F181 — a key that carries a line break/control char/stray whitespace (a
   // two-line secret-store entry, e.g.) reads as "set" by the presence check
@@ -513,7 +524,7 @@ export async function main(argv, deps = {}) {
    * contract `scripts/run-u.mjs` keeps, so one story covers both surfaces. When the
    * judge IS the authoring provider this is the key already read above. */
   const judgeKeyFor = (/** @type {string} */ providerName) => (
-    env.JUDGE_API_KEY ?? env[resolveProvider(providerName).envKey]
+    env.JUDGE_API_KEY ?? (providerName === PROVIDER_NAME ? authorEnv : applyConfiguredKey(env, providerName, undefined, keyCfg))[resolveProvider(providerName).envKey]
   );
 
   /** F6 — an unpriced call makes the TOTAL unknown, and unknown is reported as
@@ -702,9 +713,10 @@ export async function main(argv, deps = {}) {
     return String(value);
   };
   /** one free-text answer, possibly several lines; a blank line ends it.
-   * `allowBlank` lets the FIRST line be blank — `worseThanBefore`'s "nothing
-   * beyond Guardrails" is a legal, non-required answer, unlike every other
-   * free-text step below.
+   * `allowBlank` lets the FIRST line be blank — kept as a general option for
+   * a future optional free-text step; every current step below passes
+   * `false` (the old "worse than before" ask, retired 2026-09-28, was the
+   * only caller that ever passed `true`).
    * @param {boolean} allowBlank @returns {Promise<string|null>} */
   const readFreeText = async (allowBlank) => {
     /** @type {string[]} */
@@ -729,11 +741,6 @@ export async function main(argv, deps = {}) {
    * @param {{kind: string, [k: string]: any}} step @returns {Promise<string|null>} */
   const ask = async (step) => {
     out('');
-    if (step.kind === 'worseThanBefore') {
-      out(step.field.prompt);
-      out('  (press Enter on a blank line for "nothing beyond Guardrails")');
-      return readFreeText(true);
-    }
     if (step.kind === 'language') {
       out(step.field.prompt);
       for (const c of step.candidates ?? []) out(`  · ${c}`);
@@ -1201,7 +1208,15 @@ export async function main(argv, deps = {}) {
         // buys a real judge call per case, so a line saying "the gates spend no
         // tokens" would have been false the moment a judged close reached here.
         out(`authoring  ${costLine(authored.cost)}`);
-        out(`total cost ${costLine(costSoFar())}${judges ? '   (includes the calibration gate\'s judge calls)' : '   (gates 1-3 spend no tokens — they run commands)'}`);
+        const totalCost = costSoFar();
+        out(`total cost ${costLine(totalCost)}${judges ? '   (includes the calibration gate\'s judge calls)' : '   (gates 1-3 spend no tokens — they run commands)'}`);
+        // hamr's ruling 2026-09-28 ("one cap covers drafting + run") — this
+        // run's own known FLOOR (never $0 on an unpriced call, F6), handed to
+        // the run-u command below as `--draft-spent-usd` so the SIGNED run's
+        // own enforced ceiling becomes Cap $ minus what THIS pipeline already
+        // spent, computed in the one place (`src/run.js`'s `remainingUsd`)
+        // that arithmetic lives — never re-derived here.
+        const draftSpentUsd = typeof totalCost.costUsd === 'number' ? totalCost.costUsd : totalCost.knownUsd;
 
         if (!signing.ok) {
           out('\nSIGNING NOT PREPARED — the close did not clear D9\'s gates. Nothing was signed and nothing was run.');
@@ -1222,8 +1237,19 @@ export async function main(argv, deps = {}) {
           // person needs to run their own job, nothing left to hand off.
           // `providerEntry.envKey` (never a hardcoded ANTHROPIC_API_KEY) is the
           // same F187 rule scripts/run-u.mjs's own hint already follows.
+          // hamr's ruling 2026-09-28 (2nd addendum) — `totalCost.costUsd === null`
+          // means this pipeline's own metered list carried at least one unpriced
+          // call (`tallyCalls`'s `spendComplete: false`), so the drafting fold is
+          // a FLOOR, and the run-u command below must say so via its own
+          // presence-flag rather than let the next leg's job-start read it as
+          // exact.
+          const draftIncomplete = totalCost.costUsd === null;
+          if (draftSpentUsd > 0) {
+            out(`\n  drafting spent ${draftIncomplete ? `at least $${draftSpentUsd.toFixed(6)}` : `$${draftSpentUsd.toFixed(6)}`} — the run's own cap is the SAME signed $${spec.budgetUsd}, `
+              + 'and run-u will enforce the remainder (Cap $ minus this) as ITS ceiling — pass --draft-spent-usd exactly as shown below, never a rounded or re-typed figure.');
+          }
           out('\nTo run it (the same signature and gates as any other job — nothing here bypasses them):');
-          out(`  ${providerEntry.envKey}=... node scripts/run-u.mjs --spec ${specFile} --approve ${hash}`);
+          out(`  ${providerEntry.envKey}=... node scripts/run-u.mjs --spec ${specFile} --approve ${hash}${draftSpentUsd > 0 ? ` --draft-spent-usd ${draftSpentUsd}${draftIncomplete ? ' --draft-spend-incomplete' : ''}` : ''}`);
           emit('author-end', { outcome: 'prepared', specHash: hash });
         }
       }

package/src/cli.js

@@ -68,6 +68,7 @@ import { panelMain } from './panel/server.js';
 // (`~/.config/bareloop/runs.jsonl`) and its backfill scan. `bareloop runs`
 // (list) and `bareloop runs backfill <dir>` (reconstruct rows from archived
 // spines already on disk) are this rung's only new commands.
+import { keysForDoor } from './keysfile.js';
 import { appendRun, readRunList, backfillRuns, formatRunRow } from './runlist.js';
 
 // The tier->model tables live in `src/providers.js` now (PRD item 28's
@@ -653,11 +654,15 @@ async function runMenu(deps, ctx) {
  * code, so `bin/bareloop.mjs` can set `process.exitCode` and let node flush
  * queued stdout on its own (F-something: `process.exit()` can discard it).
  * @param {string[]} argv
- * @param {{ env?: Record<string,string|undefined>, stdout?: any, stderr?: any, cwd?: string, provider?: any, providerFor?: any, judgeProvider?: any, judgeModel?: string|null, now?: () => number, stdin?: any, runlistHome?: string }} deps
+ * @param {{ env?: Record<string,string|undefined>, stdout?: any, stderr?: any, cwd?: string, provider?: any, providerFor?: any, judgeProvider?: any, judgeModel?: string|null, now?: () => number, stdin?: any, runlistHome?: string, keysHome?: string }} deps
  * @returns {Promise<number>}
  */
 export async function main(argv, deps = {}) {
-  const env = deps.env ?? process.env;
+  // P4a item 1 — the keys file (`~/.config/bareloop/.env`) fills what the shell leaves
+  // unset; the shell wins. An injected `deps.env` skips the file (tests never read the
+  // real one) unless `deps.keysHome` names a home.
+  const keys = keysForDoor(deps);
+  const env = keys.env;
   const stdout = deps.stdout ?? process.stdout;
   const stderr = deps.stderr ?? process.stderr;
   const cwd = deps.cwd ?? process.cwd();
@@ -667,6 +672,7 @@ export async function main(argv, deps = {}) {
   const ctx = { out, err, cwd, env, now, deps };
 
   const [cmd, ...rest] = argv;
+  if (keys.warning && cmd && ['run', 'run-u', 'interview', 'author', 'panel'].includes(cmd)) err(`WARNING: ${keys.warning}`);
   if (!cmd) return runMenu({ ...deps, stdin: deps.stdin ?? process.stdin, stdout }, ctx);
   if (cmd === 'export') return doExport(rest, ctx);
   if (cmd === 'run') return doRun(rest, ctx);
@@ -681,7 +687,7 @@ export async function main(argv, deps = {}) {
   // then `env`/`out`/`err` are overridden to the SAME resolved values every
   // other command here prints through, so `run-u`'s output lands on the
   // `stdout`/`stderr` a caller of `main` actually passed.
-  if (cmd === 'run-u') return runUMain(rest, { ...deps, env, out, err });
+  if (cmd === 'run-u') return runUMain(rest, { ...deps, env, out, err, keysHome: keys.home });
   // `bareloop interview` — the close-authoring interview (PANEL-BUILD.md P0
   // task 3/4). This flow reads a TTY (or a piped stdin) directly rather than
   // through the `out`/`err` line-functions every other command here uses, so
@@ -691,11 +697,11 @@ export async function main(argv, deps = {}) {
   // person actually typed, never a script path they never invoked and may
   // not have on disk (a branch-review nit; `scripts/run-interview.mjs` still
   // supplies none, so it keeps naming itself when run directly).
-  if (cmd === 'interview') return interviewMain(rest, { ...deps, env, stdin: deps.stdin ?? process.stdin, stdout, stderr, invokedAs: 'bareloop interview' });
+  if (cmd === 'interview') return interviewMain(rest, { ...deps, env, keysHome: keys.home, stdin: deps.stdin ?? process.stdin, stdout, stderr, invokedAs: 'bareloop interview' });
   // `bareloop author` — the authoring pipeline (scout, declaration, D9's
   // gates), same task. Same raw-stream reasoning: its one interactive seam
   // (the confirm turn) reads stdin directly. Same `invokedAs` reasoning too.
-  if (cmd === 'author') return authorMain(rest, { ...deps, env, stdin: deps.stdin ?? process.stdin, stdout, stderr, invokedAs: 'bareloop author' });
+  if (cmd === 'author') return authorMain(rest, { ...deps, env, keysHome: keys.home, stdin: deps.stdin ?? process.stdin, stdout, stderr, invokedAs: 'bareloop author' });
   // `bareloop replay` — the spine/gate-audit read side (PANEL-BUILD.md P0,
   // last of the rung's four tasks). Synchronous, file-based, no interactive
   // seam — same shape as `doHistory`/`doExport`, not the argv-owning
@@ -709,7 +715,7 @@ export async function main(argv, deps = {}) {
   // Never runs a job, spends money, or reads a key: it serves the run list
   // and spine/gate-audit reads over `127.0.0.1` only. `deps.runlistHome`
   // rides through the same injectable seam `run`/`run-u` already use.
-  if (cmd === 'panel') return panelMain(rest, { out, err, runlistHome: deps.runlistHome });
+  if (cmd === 'panel') return panelMain(rest, { out, err, runlistHome: deps.runlistHome, env: deps.env });
   err(`unknown command ${JSON.stringify(cmd)} — one of: export, run, history, run-u, interview, author, replay, runs, panel`);
   return 1;
 }

package/src/config.js

@@ -0,0 +1,135 @@
+// PANEL-BUILD.md P4a item 2 — the ONE reader/writer of `~/.config/bareloop/config.json`.
+//
+// Every panel/CLI setting lives in this one file (R5): the monthly $ limit, the
+// Anthropic balance note, and the Providers rows' Name / API shape / Base URL, per key variable.
+// Key VALUES never live here — they live in the keys file (`src/keysfile.js`) and the
+// shell env. The write path refuses a document that carries a secret-shaped string
+// (the ONE inventory: `sweepSecretLiterals`, src/validate.js).
+//
+// Shape (unknown fields are kept, never dropped):
+//   { "monthlyLimitUsd": <number>,          // absent = no limit, no check
+//     "anthropicBalanceNote": <number>,     // a typed note; no check ever reads it
+//     "keys": { "<ENV NAME>": { "name": "<model id>", "shape": "<api shape>", "baseUrl": "<url or blank>" } } }
+//
+// A missing file = defaults. An UNREADABLE file is reported (`problem`), never
+// papered over — the monthly check REFUSES on it rather than silently running with
+// no limit. Written atomically (tmp + rename), mode 600.
+import {
+  existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, chmodSync,
+} from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { sweepSecretLiterals } from './validate.js';
+
+/** A plain-words config failure (bad value, secret-shaped string, unreadable file). */
+export class ConfigError extends Error {}
+
+/**
+ * @param {string} [home] test seam; production never passes it
+ * @returns {string} `<home>/config.json`
+ */
+export function configPath(home) {
+  return join(home ?? join(homedir(), '.config', 'bareloop'), 'config.json');
+}
+
+/**
+ * @typedef {object} ConfigRead
+ * @property {Record<string, any>} config the parsed document ({} when missing/unreadable)
+ * @property {boolean} exists
+ * @property {string|null} problem plain words when the file is there but unreadable
+ */
+
+/**
+ * @param {{ home?: string }} [opts]
+ * @returns {ConfigRead}
+ */
+export function readConfig(opts = {}) {
+  const file = configPath(opts.home);
+  if (!existsSync(file)) return { config: {}, exists: false, problem: null };
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(file, 'utf8'));
+  } catch (/** @type {any} */ e) {
+    return { config: {}, exists: true, problem: `${file} is not readable JSON (${e?.code ?? 'parse error'}) — fix or remove it` };
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return { config: {}, exists: true, problem: `${file} must hold a JSON object — fix or remove it` };
+  }
+  return { config: parsed, exists: true, problem: null };
+}
+
+const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+/** the API shapes a keys row may name (the `src/providers.js` table names) */
+const SHAPE_IDS = ['anthropic-api', 'openai-api', 'gemini-api'];
+
+/**
+ * Apply a patch and write. `null` deletes a field. Top-level fields shallow-merge;
+ * `keys` merges per key variable name, then per field. Validated before anything is
+ * written; nothing is written on a refusal.
+ *
+ * Patch fields understood: `monthlyLimitUsd` (finite > 0), `anthropicBalanceNote`
+ * (finite >= 0), `keys.<ENV NAME>.{name,shape,baseUrl}` (Name = a model id, shape = a provider table name, baseUrl = blank or http(s)). Any other
+ * field is passed through untouched (kept), but the whole document is swept for
+ * secret-shaped strings first.
+ * @param {Record<string, any>} patch
+ * @param {{ home?: string }} [opts]
+ * @returns {Record<string, any>} the document as written
+ */
+export function updateConfig(patch, opts = {}) {
+  const cur = readConfig(opts);
+  if (cur.problem) throw new ConfigError(cur.problem);
+  /** @type {Record<string, any>} */
+  const next = { ...cur.config };
+  for (const [k, v] of Object.entries(patch)) {
+    if (k === 'keys') continue;
+    if (v === null) { delete next[k]; continue; }
+    if (k === 'monthlyLimitUsd' && !(typeof v === 'number' && Number.isFinite(v) && v > 0)) {
+      throw new ConfigError('monthlyLimitUsd must be a number above 0 (remove the limit to have none)');
+    }
+    if (k === 'anthropicBalanceNote' && !(typeof v === 'number' && Number.isFinite(v) && v >= 0)) {
+      throw new ConfigError('anthropicBalanceNote must be a number, 0 or more');
+    }
+    next[k] = v;
+  }
+  if (patch.keys !== undefined) {
+    if (patch.keys === null || typeof patch.keys !== 'object' || Array.isArray(patch.keys)) {
+      throw new ConfigError('keys must be an object of key variable names');
+    }
+    /** @type {Record<string, any>} */
+    const keys = { ...(next.keys && typeof next.keys === 'object' ? next.keys : {}) };
+    for (const [envName, fields] of Object.entries(patch.keys)) {
+      if (!ENV_NAME_RE.test(envName)) throw new ConfigError(`"${envName}" is not a key variable name`);
+      if (fields === null) { delete keys[envName]; continue; }
+      if (typeof fields !== 'object' || Array.isArray(fields)) throw new ConfigError(`keys.${envName} must be an object`);
+      const merged = { ...(keys[envName] && typeof keys[envName] === 'object' ? keys[envName] : {}) };
+      for (const [fk, fv] of Object.entries(/** @type {Record<string, any>} */ (fields))) {
+        if (fv === null) { delete merged[fk]; continue; }
+        if (fk === 'name' && !(typeof fv === 'string' && fv.length <= 100 && !/\s/.test(fv))) {
+          throw new ConfigError(`keys.${envName}.name must be a model id (no spaces, up to 100 characters)`);
+        }
+        if (fk === 'shape' && !SHAPE_IDS.includes(fv)) {
+          throw new ConfigError(`keys.${envName}.shape must be one of ${SHAPE_IDS.join(', ')}`);
+        }
+        if (fk === 'baseUrl' && !(typeof fv === 'string' && (fv === '' || /^https?:\/\/\S+$/.test(fv)))) {
+          throw new ConfigError(`keys.${envName}.baseUrl must be blank or an http(s) URL`);
+        }
+        merged[fk] = fv;
+      }
+      keys[envName] = merged;
+    }
+    next.keys = keys;
+  }
+  /** @type {string[]} */
+  const secretPaths = [];
+  sweepSecretLiterals(next, (_code, path) => { secretPaths.push(path); });
+  if (secretPaths.length) {
+    throw new ConfigError(`config.json never holds a key value — a secret-shaped string at ${secretPaths.join(', ')} was refused (keys live in ~/.config/bareloop/.env)`);
+  }
+  const file = configPath(opts.home);
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.tmp-${process.pid}`;
+  writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+  chmodSync(tmp, 0o600);
+  renameSync(tmp, file);
+  return next;
+}

package/src/interviewrun.js

@@ -86,6 +86,8 @@
 // question this used to ask separately is GONE, folded into Destination. A
 // non-repo source gets the form up to here and then an honest named stop:
 // bareloop has no checks for that kind of job yet (ruling 7 → M4).
+import { keysForDoor } from './keysfile.js';
+import { applyConfiguredKey, rowsForHome } from './providerrows.js';
 import {
   writeFileSync, mkdirSync, existsSync, readFileSync, statSync,
 } from 'node:fs';
@@ -123,6 +125,7 @@ class ExitSignal extends Error {
 /**
  * @typedef {object} Deps
  * @property {Record<string,string|undefined>} [env]
+ * @property {string} [keysHome] P4a — test seam: load this home's `.env` keys file even when `env` is injected.
  * @property {NodeJS.ReadStream} [stdin]
  * @property {NodeJS.WritableStream} [stdout]
  * @property {NodeJS.WritableStream} [stderr]
@@ -146,10 +149,13 @@ class ExitSignal extends Error {
  * @returns {Promise<number>} an exit code — never calls process.exit
  */
 export async function main(argv, deps = {}) {
-  const env = deps.env ?? process.env;
+  // P4a item 1 — the keys file fills what the shell leaves unset (shell wins).
+  const keys = keysForDoor(deps);
+  const env = keys.env;
   const stdin = deps.stdin ?? process.stdin;
   const stdout = deps.stdout ?? process.stdout;
   const stderr = deps.stderr ?? process.stderr;
+  if (keys.warning && deps.env === undefined) stderr.write(`WARNING: ${keys.warning}\n`);
   const spawnSyncFn = deps.spawnSync ?? realSpawnSync;
   const invokedAs = deps.invokedAs ?? 'node scripts/run-interview.mjs';
   const out = (/** @type {string} */ s = '') => { stdout.write(`${s}\n`); };
@@ -765,7 +771,9 @@ export async function main(argv, deps = {}) {
   // (a line break/control char/stray whitespace, e.g. a two-line secret-store
   // entry). A malformed key must not count as KEYED: this offer must read the
   // same "will it actually run" question run-author itself asks at its door.
-  const rawKeyValue = providerEnvKey ? env[providerEnvKey] : undefined;
+  // P4a item 4 — the key variable the person picked in Settings stands in for the built-in one
+  const keyEnv = keys.home !== undefined ? applyConfiguredKey(env, PROVIDER, draft.baseUrl, rowsForHome(keys.home)) : env;
+  const rawKeyValue = providerEnvKey ? keyEnv[providerEnvKey] : undefined;
   const keyProblem = rawKeyValue ? apiKeyProblem(rawKeyValue) : null;
   const KEYED = providerEnvKey !== null && Boolean(rawKeyValue) && !keyProblem;
   if (!KEYED) {

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 };
+}