bareloop 0.31.0 → 0.32.0

package/CHANGELOG.md

@@ -5,6 +5,78 @@ All notable changes to bareloop are documented here. Format:
 [SemVer](https://semver.org/spec/v2.0.0.html). Pre-1.0: **minor** = a ladder rung or
 feature lands, **patch** = docs, fixes, scaffolding.
 
+## [0.32.0] — 2026-09-29
+
+### Added
+
+- **Panel Settings (P4a)** — `~/.config/bareloop/.env` keys-file loader (shell env wins; keys
+  never reach the page), `config.json` (monthly $ limit, chosen key variables, Anthropic balance
+  note), a monthly $ limit that refuses a run start with `Max $X (monthly limit)` at both
+  `run-u` and the panel Sign & run, and a Settings view with a Money & limits tab and a Providers
+  tab (read, $0 Test, key-name dropdown). Add/edit/remove providers is P4b. There is no monthly
+  time limit. **The monthly limit is checked by `run-u` and the panel only — `bareloop run
+  <bundle>` does not check it.** An unreadable `config.json` refuses a run start; a month whose
+  spend is incomplete reads "at least".
+- **Money & limits tab** — total and this-month spend and tokens as two header tiles ($ and
+  tokens, month first), a monthly $ limit that saves on change, and a per-provider breakdown
+  table ($, wall minutes, tokens; this month and to date). Wall time is job-start to job-end
+  when the run ended, otherwise an "at least" floor; unknown is shown as unknown, never 0. A
+  spine with no recorded provider is labelled "not recorded (model X)", never guessed from the
+  model name.
+- **`replay-live --live-audit`** (`scripts/replay-live.mjs`) — opt-in: a $0 replay keeps its
+  sidecar in a scratch patient dir while it paces, so the panel's live tool-log fallback can be
+  seen on screen. Default replay is unchanged.
+- **Panel Providers tab is the keys file (P4b)** — one Settings row per key in
+  `~/.config/bareloop/.env` that has a value (the file is created with five empty preset lines,
+  `ANTHROPIC_API_KEY` / `DEEPSEEK_API_KEY` / `OPENAI_API_KEY` / `GEMINI_API_KEY` / `LOCAL_API_KEY`,
+  when missing; an existing file is never edited). Each row has an editable Name (the model id Chat
+  uses), API shape (Anthropic / OpenAI-compatible / Gemini), Base URL, a $0 Test at that shape and
+  URL, and a total Tokens used; changes save to `config.json` `keys.<ENV NAME>`. A key value of
+  `null` counts as set and means "no real key" (local servers); the provider gets a placeholder,
+  and local rounds price as an `estimated` guess, never a real $0. Reload keys re-merges the
+  keys file onto the shell environment per request, so edits and removals take effect without a
+  restart. Chat's Model menu is the Settings
+  rows, and one owner (`src/providerrows.js`) resolves model to key + shape + URL for Chat, the
+  author doors and the run doors.
+- **Providers tab names a shell-only key** — a preset key variable exported only in the shell
+  (not in the keys file) gets no row and no Chat model; the tab now says so under the table, by
+  name only (`GET /api/settings/providers` returns `shellOnly: string[]`, never a value).
+
+### Changed
+
+- **Panel: no price is displayed** — the Providers table Price column and the Chat job card's
+  Token price field are removed. Display only: cost recording, the `estimated` provenance, spend
+  sums, caps and the monthly limit are unchanged.
+- The Chat cap row is two equal full-width columns (Cap $ | Time cap) at every width.
+- `config.json` `providers.<row>.key` (P4a key-name dropdown) is replaced by
+  `keys.<ENV NAME> = { name, shape, baseUrl }`; the hardcoded `PROVIDER_ROWS` and the panel's fixed
+  `MODEL_OPTIONS` are gone.
+- **Monthly limit counts running jobs at their full cap** — a run still in flight (no `job-end`,
+  spine written to within the panel's died window) is counted against the limit at its own leg
+  cap, not its spend so far, so two runs cannot both start against a limit only one fits. A died
+  run still counts its floor. The Money tab's "$ month" stays real spend.
+
+### Fixed
+
+- **Monthly limit no longer double-counts a resume** — `run-u --resume` on a leg killed within
+  `DIED_MTIME_MS` reserved the old leg at its full cap AND asked for the remainder, so a resume
+  that fit was refused; the resumed leg now counts its real spend only
+  (`checkMonthlyRoom({ resumingSpine })`).
+- **`POST /api/settings/money` no longer clears the limit on a bad body** — an empty or
+  unparseable body, or JSON without the `monthlyLimitUsd` key, is a 400 and leaves `config.json`
+  alone; only an explicit `null` or blank clears the limit.
+- **A bad `monthlyLimitUsd` no longer reads as "no limit"** — a `monthlyLimitUsd` present in
+  `config.json` but not a number above 0 (`"50"`, `-5`, `0`, `true`, `{}`) now refuses the run
+  start and shows as a config problem on the Money tab, like an unparseable file. Absent or
+  `null` still means no limit.
+- **Panel author routes: `jobsDir` and body size** — the name-collision check's `jobsDir` test
+  seam is now server-side only (it was readable off the client's job card, so any
+  `/api/author/start` body could repoint it), and POST bodies over 1 MiB get 413 and the request
+  is destroyed (the reader had no cap and ran before the click guard).
+- **Providers Test** — a connection failure now reads "nothing answering at <URL>"; the Test
+  cell keeps a fixed width and wraps its result. **Tokens used** counts older model-only spines
+  toward the row whose Name exactly equals the model.
+
 ## [0.31.0] — 2026-09-29
 
 ### Added

package/bareloop.context.md

@@ -3302,17 +3302,17 @@ interviews of their own. All three are dispatched by name only: `bareloop run-u
   `baselineKind`/`question`: the plain-English question is derived in `src/panel/server.js`
   (`stageQuestionText`) from the signed stage's kind/params only, `null` when no honest
   wording exists (the client then shows the stage's own name). Every
-  endpoint is GET/HEAD only (anything else — including every write verb — is `405`); a URL
+  P1 endpoint is GET/HEAD only (anything else — including every write verb — is `405`, outside the
+  two human-click-guarded write families `/api/author/*` and `/api/settings/*` below); a URL
   never joins a path segment into a filesystem read — a runid is looked up in the run list
   first (`RUNID_RE`, `src/panel/server.js` — accepts a `~2`-style backfill-disambiguated
   suffix too, and every endpoint echoes back the LISTED runid, never a filename-derived one
   that can silently drop that suffix), and only the path THAT ROW stores is ever read. A
   taken port fails loudly (names the port, exit `1`) — this command never silently tries a
-  different one. No interview, no author, no run trigger, no key/`.env` ever read on this
-  path. One more caller of `src/replayio.js`/`src/runlist.js`, in-process, per the layering
+  different one. This read path runs no interview, no author and no run, and reads no key
+  value (the write families below do, server-side, and never return one). One more caller of `src/replayio.js`/`src/runlist.js`, in-process, per the layering
   law (`docs/product/PANEL-BUILD.md` §2) — the panel's HTTP handler holds no flow logic of
-  its own. Chat/Settings/authoring (P3/P4) are not built yet; the page says so rather than
-  hiding the gap.
+  its own. Chat/authoring (P3) and Settings (P4a/P4b) are built — see below.
 
 - **Panel P2 (live run view, `docs/product/PANEL-BUILD.md` Addendum 2026-09-27)** → the page
   polls, it does not push (no SSE/websocket). One `setInterval` (2s) drives two throttled
@@ -3331,14 +3331,19 @@ interviews of their own. All three are dispatched by name only: `bareloop run-u
   `resolveAuditPathForRow` (`src/panel/server.js`), the one shared owner the Run tab's tools
   summary and the Audit tab both read through — tried only while the run's own spine has no
   `job-end` yet, so a finished run never risks reading a stale leftover file at that path.
-  `scripts/replay-live.mjs <sourceSpine> <outDir> [--speed N]` is a dev-only, unshipped ($0,
+  `scripts/replay-live.mjs <sourceSpine> <outDir> [--speed N] [--live-audit]` is a dev-only, unshipped ($0,
   no provider call) instrument that paces a real archived spine's records back out under a
   new runid so the panel can be exercised against a "live" run without a paid run — it is not
   a substitute for watching a real run start-to-end, which stays a separately authorized step.
-
-- **Panel P3 (chat/authoring, `docs/product/PANEL-BUILD.md` Addendum 2026-09-27)** → the ONE
-  family of write routes the panel serves, all under `/api/author/*` (`src/panel/
-  authorroutes.js`); every other route stays GET/HEAD-only per P1's own rule. Every route
+  `--live-audit` (opt-in) puts the sidecar at a scratch patient dir during the replay so the
+  live-fallback path above is exercised, then moves it to the sibling name at the end.
+
+- **Panel P3 (chat/authoring, `docs/product/PANEL-BUILD.md` Addendum 2026-09-27)** → one of the
+  panel's TWO families of write routes (the other is `/api/settings/*`, see "Settings" below), this
+  one under `/api/author/*` (`src/panel/authorroutes.js`); every other route stays GET/HEAD-only
+  per P1's own rule. A POST body over 1 MiB is refused `413` before it is parsed, and the job
+  card's `jobsDir` (where an existing job name is looked up) is a server-side seam only, never read
+  off the client's card. Every route
   requires the human-click guard: an `x-bareloop-token` header matching a fresh token minted
   once per server start (templated into `index.html` like the port) AND an Origin/Host
   naming this exact `127.0.0.1:<port>` — a request failing either gets `403`, before the
@@ -3368,14 +3373,14 @@ interviews of their own. All three are dispatched by name only: `bareloop run-u
   [`--draft-spend-incomplete`] when the session's drafting spend is > 0 — one cap covers
   drafting + run) detached (array argv,
   never a shell string), with its own log file inside the session's own dir, and the
-  server's own environment (a key is never read into or sent to the page — a missing one
-  refuses the session at $0, naming only the env var). `src/panel/authorsession.js` takes
+  server's environment with `~/.config/bareloop/.env` merged in per request (a key is never read
+  into or sent to the page — a missing one refuses the session at $0, naming only the env var). `src/panel/authorsession.js` takes
   test-only DI seams (`scout`/`generate`/`confirmGenerate`/`authorFn`/`prepareSigningFn`) so
   a test can drive the real ask()-channel/revise/hash wiring without a live provider call;
   none of them are reachable from `authorroutes.js`'s real construction path. Sessions live
   under `~/.config/bareloop/panel-sessions/<id>/` (each one's own `resolved-spec.json` and
   `signing.json`, the two files `bareloop author` itself already writes). Edit/re-sign, the
-  `~/.config/bareloop/.env` keys-file loader, and Settings are P4, not built here.
+  `~/.config/bareloop/.env` keys-file loader, and Settings have landed (P4a/P4b — see "Settings" below).
 
 - **`bareloop run-u <flags…>`** (PANEL-BUILD.md P0 task 2/4) → the person-path run flow
   (the JOBS-table/`--spec` runner, resume, the review door — `docs/logs/FINDINGS.md`'s
@@ -3490,6 +3495,75 @@ provider but `anthropic-api`, spine bundling for `formatReplay` on the minting r
 `runid` is noted), and tarball packing — a bundle is a plain directory; use `npm pack` on it
 yourself if you want a tarball.
 
+### Settings — the keys file, `config.json`, the monthly $ limit, the Providers tab (PANEL-BUILD.md P4a, `src/keysfile.js`, `src/config.js`, `src/monthly.js`, `src/providerrows.js`, `src/panel/settingsroutes.js`)
+
+Two files in `~/.config/bareloop/`, outside any repo:
+
+- **`.env` — key VALUES only.** Plain `NAME=value` lines (optional `export `, `#` comments, one pair
+  of quotes). `loadKeysEnv({ env?, home? })` merges it over the environment; **the shell wins** —
+  the file only fills names the shell leaves unset. Mode other than 600 = a `warning` string
+  (printed on CLI start, shown in Settings), never a refusal. Values go only to provider
+  construction; the page and every log get NAMES and found / not set. `keysForDoor(deps)` is the
+  door helper: an injected `env` with no `keysHome` skips the file entirely (tests never read the
+  real one). The CLI (`run-u`, `interview`, `author`) and the panel both use it.
+- **`config.json` — every setting, never a key value.** `readConfig({ home })` /
+  `updateConfig(patch, { home })` (atomic tmp + rename, mode 600, unknown fields kept).
+  Fields: `monthlyLimitUsd` (number above 0; absent or `null` = no limit; any other value present
+  is a `ConfigError`, refused like an unreadable file), `anthropicBalanceNote` (a note the
+  person types; no check ever reads it), `keys.<ENV NAME>` = `{ name, shape, baseUrl }` (the Providers rows' settings). A secret-shaped
+  string anywhere in the document is refused on save. An unreadable file is a `problem` string and
+  a refused run start ($0), never "no limit". There is no monthly TIME limit (dropped).
+
+**Monthly $ limit.** `checkMonthlyRoom({ capUsd, home, now })` → `{ ok, leftUsd, limitUsd,
+atLeast }`; `monthlyRefusalText(room)` is the ONE spelling: `Max $<left, 2 decimals> (monthly
+limit)`. It is called at the run-start seam in `src/userrun.js` `execute` (before any token
+spends; the CLI prints it to stderr, exit 2) and at the panel's Sign & run (`signRun` in
+`src/panel/authorroutes.js`, refused server-side whatever the page shows). The page only echoes the
+same text under `#jf-cap-money` via `GET /api/author/monthly-check?cap=`. "This month" is the local
+calendar month; a died or incomplete-spend run makes the total an "at least" figure. A run still
+IN FLIGHT (`job-start`, no `job-end`, spine file written within `DIED_MTIME_MS`, `src/runlist.js`) is
+counted at its full leg cap (`budgetUsd` less `priorSpentUsd` on its `job-start`), not its spend so
+far (except the run a resume continues, which counts its real spend), so two runs cannot both start against a limit only one fits; a died run counts its floor.
+Only the refusal reserves the cap (`monthSpend().reservedUsd`); the Money tab's month figure is
+real spend.
+
+**Money & limits tab** (`GET/POST /api/settings/money`): two tiles ($ and tokens, this month / to date, a
+`≥` prefix when a figure is a floor) and a per-provider table ($, minutes, tokens; a run is grouped
+by the provider on its `job-start`, an older spine by its model). The limit field auto-saves on
+change (no Save button); blank clears it. `POST` needs an explicit `monthlyLimitUsd` key (a number
+above 0, or `null`/blank to clear) — an empty or key-less body is a `400`, never "clear the limit".
+
+**Providers tab (P4b, `src/providerrows.js`).** One row per key in `.env` that HAS A VALUE — nothing is
+hardcoded; an empty line is no row, a removed line drops its row on Reload keys. A missing `.env` is
+created (mode 600) on the first Providers read with five empty preset lines (`ANTHROPIC_API_KEY`,
+`DEEPSEEK_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `LOCAL_API_KEY`); an existing file is never
+edited. A value of `null` counts as SET and means "no real key" (the provider is handed the
+placeholder `no-key-needed`, never the word `null`). Each row: the env NAME (read-only) + found,
+**Name** (the model id Chat uses), **API shape** (Anthropic / OpenAI-compatible / Gemini), **Base
+URL** (blank = the shape's own host), **Test**, **Tokens used** (total, display only), and Balance
+(DeepSeek fetched, Anthropic a typed note). Saves on change to `config.json`
+`keys.<ENV NAME> = { name, shape, baseUrl }`. Defaults for a key with no saved entry:
+`ANTHROPIC_API_KEY` claude-sonnet-5 / Anthropic; `DEEPSEEK_API_KEY` deepseek-flash /
+OpenAI-compatible / `https://api.deepseek.com/v1`; `OPENAI_API_KEY` OpenAI-compatible;
+`GEMINI_API_KEY` Gemini; `LOCAL_API_KEY` OpenAI-compatible / `http://127.0.0.1:11434/v1` (Ollama, LM
+Studio, llama.cpp: change the URL); any other name OpenAI-compatible; Name blank until typed. **No
+price is shown anywhere** (display only — cost recording, the estimated provenance, spend sums, caps
+and the monthly limit are unchanged; a local model has no known rate, so its rounds come out as a
+non-zero loud guess, never a real $0).
+
+`providerrows.js` is the ONE owner of "model → key + shape + URL": `keyRows`, `findRow` (rows on the
+same shape + endpoint; the Name breaks a tie), `modelChoiceFor` / `chatModels` (Chat's Model menu IS
+the rows; a blank Name is not offered), `keyNameFor` / `applyConfiguredKey` (a job on `(provider,
+baseUrl[, model])` reads the matching row's variable, else the provider's built-in one). All doors
+(`run-u`, `interview`, `author`, the panel's drafting) use it. Routes (all behind the per-start token
+and Origin check; the chat can never reach them): `GET /api/settings/providers`, `POST .../row`
+(`{envName, name, shape, baseUrl}`), `POST .../balance-note`, `POST .../test` (one
+`checkProviderReachable` models-list GET at the row's shape + URL, $0; a refused connection reads
+`nothing answering at <URL>`), `GET .../balance?env=`
+(DeepSeek-hosted row, server-side), and `GET /api/author/models` (Chat's Model menu). The old
+`providers.<row>.key` config field and the key dropdown are gone. Like the authoring routes, a POST
+body over 1 MiB is refused `413`.
+
 ### The source front door — a plain folder/file/URL, no `--patient` (PRD item 33/M2, `src/source.js`)
 
 A repo job still gives `runJob` a `--patient` checkout it owns. A NON-code job (a resume, a

package/bin/bareloop.mjs

@@ -15,7 +15,6 @@ process.stdout.on('error', (e) => {
 });
 
 const code = await main(process.argv.slice(2), {
-  env: process.env,
   stdout: process.stdout,
   stderr: process.stderr,
   cwd: process.cwd(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bareloop",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Workflows that earn their own design, with receipts — agent-authored workflows for repeated, long, verifiable jobs that improve across runs under an un-gameable gate.",
   "type": "module",
   "main": "./src/index.js",

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';
@@ -499,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
@@ -514,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

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) {