bareloop 0.31.0 → 0.32.0

package/src/panel/settingsroutes.js

@@ -0,0 +1,230 @@
+// PANEL-BUILD.md P4a — Settings routes (`/api/settings/*`). A separate module from the
+// authoring routes on purpose: the chat/authoring session can reach NO route here (it has
+// no path to this file's handlers), and every route here is behind the same human-click
+// guard (per-server-start token + Origin/Host, `checkHumanGuard`) — GET too, because the
+// pages these serve name key variables and spend.
+//
+// Providers (P4b): the rows are the keys file's filled lines; Name / API shape / Base URL save to
+// config.json `keys.<ENV NAME>` (src/providerrows.js is the one owner of the rows).
+//
+// Every write goes to `~/.config/bareloop/config.json` through `src/config.js` (the one
+// writer); the monthly limit is a person's own number, set by hand — nothing here (and
+// nothing the agent can reach) raises it on their behalf. Key VALUES never appear in any
+// response: names and found / not set only.
+import { checkHumanGuard } from './authorroutes.js';
+import { readConfig, updateConfig, ConfigError } from '../config.js';
+import { spendSummary, monthlyLimitOf } from '../monthly.js';
+import { loadKeysEnv, keysFilePath, filledKeyNames, ensureKeysFile } from '../keysfile.js';
+import { SHAPES, PRESET_KEY_NAMES, keyRows, endpointOf, defaultUrlOf, usableKey } from '../providerrows.js';
+import { apiKeyProblem, checkProviderReachable } from '../providers.js';
+
+/** DeepSeek's own balance endpoint (same host as its models list). */
+const DEEPSEEK_BALANCE_URL = 'https://api.deepseek.com/user/balance';
+
+/**
+ * @param {{ port: number, token: string, home?: string, env?: Record<string,string|undefined>,
+ *   fetchImpl?: typeof fetch, now?: () => number }} opts
+ */
+export function createSettingsRoutes(opts) {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  /** the env keys are looked up in: the door's env (shell + keys file), re-read against the
+   * keys file on every call so "Reload keys" is just another request. NAMES leave this
+   * module; values never do.
+   * @returns {ReturnType<typeof loadKeysEnv>} */
+  const keys = () => loadKeysEnv({ env: opts.env, home: opts.home });
+  /** the Providers rows: keys with a value in the file, over the saved settings
+   * @param {Record<string, any>} config */
+  const currentRows = (config) => keyRows({ filled: filledKeyNames(opts.home), config });
+  /** @param {string} u @returns {string} */
+  const hostOf = (u) => { try { return new URL(u).hostname; } catch { return ''; } };
+  /**
+   * @param {import('node:http').IncomingMessage} req
+   * @param {import('node:http').ServerResponse} res
+   * @param {string} pathname
+   * @param {any} body already-parsed JSON body (or `null`)
+   * @returns {boolean} true if this module handled the request
+   */
+  function handle(req, res, pathname, body) {
+    if (!pathname.startsWith('/api/settings')) return false;
+    const send = (/** @type {number} */ code, /** @type {any} */ obj) => {
+      const text = JSON.stringify(obj);
+      res.writeHead(code, { 'content-type': 'application/json; charset=utf-8', 'content-length': Buffer.byteLength(text) });
+      res.end(text);
+    };
+    const guard = checkHumanGuard(req, { token: opts.token, port: opts.port });
+    if (!guard.ok) { send(403, { ok: false, error: `refused — ${guard.reason}` }); return true; }
+
+    if (pathname === '/api/settings/money') {
+      if (req.method === 'GET') {
+        const cfg = readConfig({ home: opts.home });
+        const s = spendSummary({ home: opts.home, now: opts.now });
+        /** @type {number|null} */
+        let limit = null;
+        let configProblem = cfg.problem;
+        // a limit the file names but that is not a number above 0 is a problem, never "no limit"
+        try { limit = monthlyLimitOf(cfg.config, opts.home); } catch (e) {
+          if (!(e instanceof ConfigError)) throw e;
+          configProblem = e.message;
+        }
+        send(200, {
+          ok: true,
+          configProblem,
+          totalUsd: s.total.usd, totalAtLeast: s.total.atLeast,
+          monthUsd: s.month.usd, monthAtLeast: s.month.atLeast,
+          totalTokens: s.total.tokens, monthTokens: s.month.tokens,
+          monthlyLimitUsd: limit,
+          byProvider: Object.values(s.byProvider).sort((a, b) => b.totalUsd - a.totalUsd),
+        });
+        return true;
+      }
+      if (req.method === 'POST') {
+        // an empty / unparseable body, or a JSON body without the key, is NOT "clear the limit" — only
+        // an explicit null / blank clears it (that is how the auto-saving field clears it)
+        if (body === null || typeof body !== 'object' || Array.isArray(body) || !Object.hasOwn(body, 'monthlyLimitUsd')) {
+          send(400, { ok: false, error: 'send {"monthlyLimitUsd": <number above 0>} to set the limit, or null to clear it' });
+          return true;
+        }
+        // a blank / null limit removes it (no limit); anything else must be a number > 0
+        const raw = body.monthlyLimitUsd;
+        const limit = raw === null || raw === '' ? null : Number(raw);
+        if (limit !== null && !(Number.isFinite(limit) && limit > 0)) {
+          send(400, { ok: false, error: 'the monthly limit must be a number above 0 (leave it blank for no limit)' });
+          return true;
+        }
+        try {
+          updateConfig({ monthlyLimitUsd: limit }, { home: opts.home });
+        } catch (e) {
+          if (!(e instanceof ConfigError)) throw e;
+          send(400, { ok: false, error: e.message });
+          return true;
+        }
+        send(200, { ok: true, monthlyLimitUsd: limit });
+        return true;
+      }
+      send(405, { ok: false, error: 'GET or POST only' });
+      return true;
+    }
+
+    // ── Providers (P4b): one row per key in the keys file that has a value. ──
+    if (pathname === '/api/settings/providers' && req.method === 'GET') {
+      // a missing keys file is created with the five empty preset lines (never edited if present)
+      ensureKeysFile(PRESET_KEY_NAMES, opts.home);
+      const cfg = readConfig({ home: opts.home });
+      const k = keys();
+      const rows = currentRows(cfg.config);
+      const s = spendSummary({ home: opts.home, now: opts.now, rows });
+      const note = cfg.config.anthropicBalanceNote;
+      // a preset key exported only in the shell gets no row (the rows are the keys file): NAMES the
+      // person can act on, read off the RAW shell env — never a value, never a length
+      const shellEnv = opts.env ?? process.env;
+      const filled = new Set(filledKeyNames(opts.home));
+      const shellOnly = PRESET_KEY_NAMES.filter((n) => typeof shellEnv[n] === 'string' && shellEnv[n] !== '' && !filled.has(n));
+      send(200, {
+        ok: true,
+        shellOnly,
+        keysFile: { path: keysFilePath(opts.home), exists: k.exists, names: k.names, warning: k.warning },
+        configProblem: cfg.problem,
+        shapes: SHAPES.map((x) => ({ id: x.id, label: x.label })),
+        rows: rows.map((r) => {
+          const raw = k.env[r.envName];
+          const problem = raw ? apiKeyProblem(raw) : null;
+          const isDeepseek = r.provider === 'openai-api' && hostOf(endpointOf(r.provider, r.baseUrl)) === 'api.deepseek.com';
+          return {
+            envName: r.envName, name: r.name, shape: r.provider, baseUrl: r.baseUrl,
+            placeholder: defaultUrlOf(r.provider),
+            keyStatus: !raw ? 'not set' : (raw === 'null' ? 'no key needed' : (problem ? `bad shape (${problem})` : 'found')),
+            canTest: r.provider !== 'gemini-api',
+            tokens: s.tokensByRow[r.envName] ?? 0,
+            balance: r.provider === 'anthropic-api'
+              ? { kind: 'note', usd: typeof note === 'number' && Number.isFinite(note) ? note : null }
+              : (isDeepseek ? { kind: 'fetch' } : { kind: 'none' }),
+          };
+        }),
+      });
+      return true;
+    }
+
+    if (pathname === '/api/settings/providers/row' && req.method === 'POST') {
+      const row = currentRows(readConfig({ home: opts.home }).config).find((r) => r.envName === body?.envName);
+      if (!row) { send(400, { ok: false, error: 'unknown key — add NAME=key to your keys file and reload keys' }); return true; }
+      // only the three settings a row has; each is optional in the body, the whole triple is stored
+      const patch = {
+        name: typeof body?.name === 'string' ? body.name.trim() : row.name,
+        shape: typeof body?.shape === 'string' ? body.shape : row.provider,
+        baseUrl: typeof body?.baseUrl === 'string' ? body.baseUrl.trim().replace(/\/+$/, '') : row.baseUrl,
+      };
+      try {
+        updateConfig({ keys: { [row.envName]: patch } }, { home: opts.home });
+      } catch (e) {
+        if (!(e instanceof ConfigError)) throw e;
+        send(400, { ok: false, error: e.message });
+        return true;
+      }
+      send(200, { ok: true, envName: row.envName, ...patch });
+      return true;
+    }
+
+    if (pathname === '/api/settings/providers/balance-note' && req.method === 'POST') {
+      // the Anthropic balance is a NOTE the person types; no check ever reads it
+      const raw = body?.usd;
+      const usd = raw === null || raw === '' || raw === undefined ? null : Number(raw);
+      if (usd !== null && !(Number.isFinite(usd) && usd >= 0)) { send(400, { ok: false, error: 'the balance must be a number, 0 or more' }); return true; }
+      try {
+        updateConfig({ anthropicBalanceNote: usd }, { home: opts.home });
+      } catch (e) {
+        if (!(e instanceof ConfigError)) throw e;
+        send(400, { ok: false, error: e.message });
+        return true;
+      }
+      send(200, { ok: true, usd });
+      return true;
+    }
+
+    if (pathname === '/api/settings/providers/test' && req.method === 'POST') {
+      const row = currentRows(readConfig({ home: opts.home }).config).find((r) => r.envName === body?.envName);
+      if (!row) { send(400, { ok: false, error: 'unknown key' }); return true; }
+      const raw = keys().env[row.envName];
+      if (!raw) { send(200, { ok: true, reachable: false, status: 'no key', note: `${row.envName} not set`, ms: null }); return true; }
+      const problem = apiKeyProblem(raw);
+      if (problem) { send(200, { ok: true, reachable: false, status: 'bad key', note: `${row.envName} ${problem}`, ms: null }); return true; }
+      const started = Date.now();
+      // $0: one GET of the models list with THIS row's shape + URL (never a completion), key only in a header
+      checkProviderReachable({
+        providerName: row.provider, apiKey: usableKey(raw), baseUrl: row.baseUrl.trim() !== '' ? row.baseUrl : undefined, fetchImpl, timeoutMs: 4000,
+      }).then((r) => {
+        send(200, { ok: true, reachable: r.reachable, status: r.status, note: r.note, ms: Date.now() - started });
+      });
+      return true;
+    }
+
+    if (pathname === '/api/settings/providers/balance' && req.method === 'GET') {
+      // DeepSeek only: fetched server-side from the provider (key in a header, never returned)
+      const q = new URL(/** @type {string} */ (req.url), 'http://127.0.0.1').searchParams;
+      const row = currentRows(readConfig({ home: opts.home }).config).find((r) => r.envName === q.get('env'));
+      if (!row || row.provider !== 'openai-api' || hostOf(endpointOf(row.provider, row.baseUrl)) !== 'api.deepseek.com') { send(404, { ok: false, error: 'not found' }); return true; }
+      const raw = keys().env[row.envName];
+      if (!raw || apiKeyProblem(raw)) { send(200, { ok: true, text: null, note: 'no usable key' }); return true; }
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), 4000);
+      fetchImpl(DEEPSEEK_BALANCE_URL, { method: 'GET', headers: { Authorization: `Bearer ${raw}` }, signal: controller.signal })
+        .then(async (res) => {
+          if (!res.ok) { send(200, { ok: true, text: null, note: `HTTP ${res.status}` }); return; }
+          /** @type {any} */
+          let j = null;
+          try { j = await res.json(); } catch { j = null; }
+          const infos = Array.isArray(j?.balance_infos) ? j.balance_infos : [];
+          const parts = infos
+            .filter((/** @type {any} */ b) => b && typeof b.currency === 'string' && b.total_balance !== undefined)
+            .map((/** @type {any} */ b) => `${String(b.total_balance)} ${b.currency}`);
+          send(200, { ok: true, text: parts.length ? parts.join(' + ') : null, note: parts.length ? null : 'balance not reported' });
+        })
+        .catch((/** @type {any} */ e) => { send(200, { ok: true, text: null, note: `request failed: ${e?.name === 'AbortError' ? 'timeout' : (e?.code || e?.name || 'error')}` }); })
+        .finally(() => clearTimeout(timer));
+      return true;
+    }
+
+    send(404, { ok: false, error: 'not found' });
+    return true;
+  }
+  return { handle };
+}

package/src/providerrows.js

@@ -0,0 +1,217 @@
+// PANEL-BUILD.md P4b — the Providers rows, driven by the keys file. NOTHING here is a
+// hardcoded provider list: one row exists per key in `~/.config/bareloop/.env` that has a
+// value; each row's Name / API shape / Base URL come from config.json `keys.<ENV NAME>`
+// (src/config.js), else the per-name defaults below. This is NOT a new provider table:
+// a row's API shape names an entry that already exists in `src/providers.js`
+// (`PROVIDER_TABLE`), and a row's Base URL is that provider's `baseUrl` option.
+//
+// This module is also THE one owner of "model -> key + shape + URL": Chat's Model menu,
+// the author doors and the run doors all resolve through `findRow` / `keyNameFor` /
+// `applyConfiguredKey` / `modelChoiceFor` below — no second lookup exists. Key VALUES
+// never pass through here — only names.
+import { resolveProvider } from './providers.js';
+import { readConfig } from './config.js';
+import { filledKeyNames } from './keysfile.js';
+
+/** DeepSeek's OpenAI-shaped endpoint (the same string the panel's Model menu used). */
+export const DEEPSEEK_BASE_URL = 'https://api.deepseek.com/v1';
+
+/**
+ * The API shapes the dropdown offers. `id` is the `src/providers.js` table name;
+ * `defaultUrl` is the host a blank Base URL means ('' = the vendor's own, unshown).
+ * @type {readonly {id: string, label: string, defaultUrl: string}[]}
+ */
+export const SHAPES = Object.freeze([
+  Object.freeze({ id: 'anthropic-api', label: 'Anthropic', defaultUrl: 'https://api.anthropic.com/v1' }),
+  Object.freeze({ id: 'openai-api', label: 'OpenAI-compatible', defaultUrl: 'https://api.openai.com/v1' }),
+  Object.freeze({ id: 'gemini-api', label: 'Gemini', defaultUrl: '' }),
+]);
+
+/** The five empty lines a fresh keys file is created with, in this order. */
+export const PRESET_KEY_NAMES = Object.freeze(['ANTHROPIC_API_KEY', 'DEEPSEEK_API_KEY', 'OPENAI_API_KEY', 'GEMINI_API_KEY', 'LOCAL_API_KEY']);
+
+/** A local server's default endpoint: Ollama's OpenAI-compatible host (LM Studio / llama.cpp: change the URL). */
+export const LOCAL_BASE_URL = 'http://127.0.0.1:11434/v1';
+
+/**
+ * A key line whose value is the word `null` is SET and means "no real key": the row exists and
+ * the provider is handed this harmless stand-in (local servers ignore auth). It is not a
+ * secret and is never shown or logged as a key.
+ */
+export const NO_KEY_PLACEHOLDER = 'no-key-needed';
+
+/**
+ * The key value to hand a provider: the `null` marker becomes the placeholder, anything else
+ * passes through unchanged.
+ * @template {string|undefined} T
+ * @param {T} raw
+ * @returns {T|string}
+ */
+export function usableKey(raw) {
+  return raw === 'null' ? NO_KEY_PLACEHOLDER : raw;
+}
+
+/**
+ * What a key with no saved entry shows. Any name not listed is OpenAI-compatible with a
+ * blank URL and a blank Name.
+ * @param {string} envName
+ * @returns {{ name: string, shape: string, baseUrl: string }}
+ */
+export function defaultsFor(envName) {
+  switch (envName) {
+    case 'ANTHROPIC_API_KEY': return { name: 'claude-sonnet-5', shape: 'anthropic-api', baseUrl: '' };
+    case 'DEEPSEEK_API_KEY': return { name: 'deepseek-flash', shape: 'openai-api', baseUrl: DEEPSEEK_BASE_URL };
+    case 'GEMINI_API_KEY': return { name: '', shape: 'gemini-api', baseUrl: '' };
+    case 'LOCAL_API_KEY': return { name: '', shape: 'openai-api', baseUrl: LOCAL_BASE_URL };
+    default: return { name: '', shape: 'openai-api', baseUrl: '' };
+  }
+}
+
+/**
+ * @typedef {object} KeyRow
+ * @property {string} envName the key variable NAME (read-only label; never a value)
+ * @property {string} name the model id Chat uses ('' = not offered in Chat)
+ * @property {string} provider the `src/providers.js` table entry (the API shape's id)
+ * @property {string} baseUrl the saved Base URL ('' = the shape's default host)
+ */
+
+/**
+ * The rows: one per name in `filled`, saved entry over defaults.
+ * @param {{ filled: readonly string[], config: Record<string, any> }} src
+ * @returns {KeyRow[]}
+ */
+export function keyRows({ filled, config }) {
+  const saved = config?.keys && typeof config.keys === 'object' && !Array.isArray(config.keys) ? config.keys : {};
+  return filled.map((envName) => {
+    const d = defaultsFor(envName);
+    const s = saved[envName] && typeof saved[envName] === 'object' ? saved[envName] : {};
+    return {
+      envName,
+      name: typeof s.name === 'string' ? s.name : d.name,
+      provider: SHAPES.some((x) => x.id === s.shape) ? s.shape : d.shape,
+      baseUrl: typeof s.baseUrl === 'string' ? s.baseUrl : d.baseUrl,
+    };
+  });
+}
+
+/**
+ * The rows for a keys home. `undefined` home (a door that skipped the keys file) = no
+ * rows, so nothing resolves through the file and the provider's built-in variable stands.
+ * @param {string|undefined} home
+ * @returns {KeyRow[]}
+ */
+export function rowsForHome(home) {
+  if (home === undefined) return [];
+  return keyRows({ filled: filledKeyNames(home), config: readConfig({ home }).config });
+}
+
+/**
+ * @param {string} provider
+ * @returns {string} the shape's default host ('' = the vendor's own)
+ */
+export function defaultUrlOf(provider) {
+  return SHAPES.find((s) => s.id === provider)?.defaultUrl ?? '';
+}
+
+/**
+ * An endpoint in comparable form: blank = the shape's default host; scheme + host lower-cased,
+ * trailing slashes dropped.
+ * @param {string} provider
+ * @param {string|null|undefined} baseUrl
+ * @returns {string}
+ */
+export function endpointOf(provider, baseUrl) {
+  const raw = (typeof baseUrl === 'string' && baseUrl.trim() !== '' ? baseUrl : defaultUrlOf(provider)).trim();
+  if (raw === '') return '';
+  try {
+    const u = new URL(raw);
+    return `${u.protocol}//${u.host}${u.pathname.replace(/\/+$/, '')}`;
+  } catch { return raw.replace(/\/+$/, ''); }
+}
+
+/**
+ * The URL a row talks to, for display ('' = the vendor's own host, which has no URL to show).
+ * @param {KeyRow} row
+ * @returns {string}
+ */
+export function shownUrl(row) {
+  return row.baseUrl.trim() !== '' ? row.baseUrl : defaultUrlOf(row.provider);
+}
+
+/**
+ * Which row a `(provider, baseUrl[, model])` identity belongs to: the rows on that shape and
+ * endpoint; when several share it, the one whose Name is the model, else the first.
+ * @param {readonly KeyRow[]} rows
+ * @param {{ provider?: string|null, baseUrl?: string|null, model?: string|null }} id
+ * @returns {KeyRow|null}
+ */
+export function findRow(rows, { provider, baseUrl, model }) {
+  if (typeof provider !== 'string') return null;
+  const want = endpointOf(provider, baseUrl);
+  const same = rows.filter((r) => r.provider === provider && endpointOf(r.provider, r.baseUrl) === want);
+  if (same.length === 0) return null;
+  return (model ? same.find((r) => r.name === model) : undefined) ?? same[0];
+}
+
+/**
+ * What Chat's Model menu offers and how a pick resolves: the row whose Name is the model
+ * (a blank Name is never offered). `baseUrl` is absent when blank, exactly as a spec omits it.
+ * @param {readonly KeyRow[]} rows
+ * @param {string} model
+ * @returns {{ provider: string, baseUrl?: string, envName: string, name: string }|null}
+ */
+export function modelChoiceFor(rows, model) {
+  const r = model === '' ? undefined : rows.find((x) => x.name === model);
+  if (!r) return null;
+  return { provider: r.provider, ...(r.baseUrl.trim() !== '' ? { baseUrl: r.baseUrl.trim() } : {}), envName: r.envName, name: r.name };
+}
+
+/**
+ * The models Chat offers, in keys-file order.
+ * @param {readonly KeyRow[]} rows
+ * @returns {{ id: string, envName: string, shape: string }[]}
+ */
+export function chatModels(rows) {
+  return rows.filter((r) => r.name !== '').map((r) => ({
+    id: r.name, envName: r.envName, shape: SHAPES.find((s) => s.id === r.provider)?.label ?? r.provider,
+  }));
+}
+
+/**
+ * The key variable NAME a job on `(provider, baseUrl[, model])` reads: the matching row's
+ * variable, else the provider's built-in one (byte-identical to before for anything no row
+ * claims).
+ * @param {string|null|undefined} provider
+ * @param {string|null|undefined} baseUrl
+ * @param {readonly KeyRow[]} rows
+ * @param {string|null|undefined} [model]
+ * @returns {{ name: string, builtIn: string, chosen: boolean }}
+ */
+export function keyNameFor(provider, baseUrl, rows, model) {
+  const builtIn = resolveProvider(/** @type {string} */ (provider)).envKey;
+  const row = findRow(rows, { provider, baseUrl, model });
+  return row && row.envName !== builtIn
+    ? { name: row.envName, builtIn, chosen: true }
+    : { name: builtIn, builtIn, chosen: false };
+}
+
+/**
+ * The env a door hands to provider construction, with the matching row's key variable
+ * standing in for the provider's built-in one: `env[builtIn] = env[row.envName]` (the `null`
+ * no-key marker becomes {@link NO_KEY_PLACEHOLDER}). A copy — never mutates the input.
+ * No matching row and no marker = the env unchanged.
+ * @param {Record<string,string|undefined>} env
+ * @param {string|null|undefined} provider
+ * @param {string|null|undefined} baseUrl
+ * @param {readonly KeyRow[]} rows
+ * @param {string|null|undefined} [model]
+ * @returns {Record<string,string|undefined>}
+ */
+export function applyConfiguredKey(env, provider, baseUrl, rows, model) {
+  if (typeof provider !== 'string') return env;
+  let k;
+  try { k = keyNameFor(provider, baseUrl, rows, model); } catch { return env; } // unknown provider: resolveProvider's own named throw fires at its own door
+  const value = env[k.name];
+  if (!k.chosen && value !== 'null') return env;
+  return { ...env, [k.builtIn]: usableKey(value) };
+}

package/src/providers.js

@@ -396,7 +396,9 @@ export async function checkProviderReachable({
     return { reachable: true, modelListed, status: 'ok', note: null };
   } catch (/** @type {any} */ e) {
     const cls = e?.name === 'AbortError' ? 'timeout' : (e?.code || e?.name || 'network-error');
-    return { reachable: false, modelListed: null, status: String(cls), note: `request failed: ${cls}` };
+    // connection refused surfaces as fetch's bare TypeError ("fetch failed") — say it plainly
+    const refused = e?.name === 'TypeError' || e?.code === 'ECONNREFUSED' || e?.cause?.code === 'ECONNREFUSED';
+    return { reachable: false, modelListed: null, status: String(cls), note: refused ? `nothing answering at ${req.url}` : `request failed: ${cls}` };
   } finally {
     clearTimeout(timer);
   }

package/src/runlist.js

@@ -128,6 +128,19 @@ function runidForSpine(spinePath) {
   return resolveSiblings(spinePath).runId;
 }
 
+// DIED (hamr's ruling B, 2026-09-25): a run with no `job-end` never shares
+// the failed glyph — [✗] stays reserved for a run whose close/arbiter
+// actually rendered a "no" (a real result). A spine that just stops, with
+// no ending ever recorded, is a DIFFERENT fact (killed, crashed, or the
+// machine slept) and gets its own [?] glyph. The distinguishing signal is
+// the spine FILE's own mtime, never wall-clock "now minus job-start" (a
+// resumed/paused run can legitimately sit quiet for a long time without
+// having died): still fresh (written to within this window) reads as the
+// existing `running` [▶] state; older than this reads as died. Tighten-only,
+// named so a future change is a deliberate, visible edit. Lives here (not in
+// the panel) because the monthly limit reads the same rule (src/monthly.js).
+export const DIED_MTIME_MS = 10 * 60 * 1000;
+
 // A backfill scan of a real patients directory can be arbitrarily deep
 // (person-path runs archive several levels down: `<dir>/<proj>/out/
 // source-<x>/<proj>-bareloop/u-<id>.jsonl`, 4 levels under the dir a person

package/src/userrun.js

@@ -73,6 +73,10 @@ import { answerReviewDoor, doorRecordOf, doorAgeGate } from './reviewdoor.js';
 import { coldReset, moveStaleGateAudit } from './u-patient.js';
 // PANEL-BUILD.md P1 — the one run list (`~/.config/bareloop/runs.jsonl`).
 import { appendRun } from './runlist.js';
+import { keysForDoor } from './keysfile.js';
+import { checkMonthlyRoom, monthlyRefusalText } from './monthly.js';
+import { ConfigError } from './config.js';
+import { applyConfiguredKey, keyNameFor, rowsForHome } from './providerrows.js';
 // the banner's wall arithmetic, extracted so it is reachable by a test (F83): the
 // end-of-run readout sits past the approval gate, so nothing could ever drive it here
 import { wallLine, doomedResume, deathAtOf, evidencePackage, doorLines, resumeAtLines, reviewDoorPackage, runDoorLines, tokensLine, doorTimingRedLines } from './u-readout.js';
@@ -219,6 +223,8 @@ class ExitSignal extends Error {
 /**
  * @typedef {object} Deps
  * @property {Record<string,string|undefined>} [env]
+ * @property {string} [keysHome] P4a — a test seam naming the home whose `.env` keys file is loaded
+ *   even when `env` is injected; production never sets it.
  * @property {(s: string) => void} [out]
  * @property {(s: string) => void} [err]
  * @property {any} [provider] the TEST SEAM: supplying this skips the real-key
@@ -306,9 +312,19 @@ class ExitSignal extends Error {
  */
 async function execute(ctx) {
   const deps = ctx.deps ?? {};
-  const env = deps.env ?? process.env;
   const out = deps.out ?? ((/** @type {string} */ s) => { console.log(s); });
   const err = deps.err ?? ((/** @type {string} */ s) => { console.error(s); });
+  // 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 unless `deps.keysHome`
+  // names a home (a test never reads the real one). Values go only to provider
+  // construction below.
+  const keys = keysForDoor(deps);
+  const env = keys.env;
+  if (keys.warning && deps.env === undefined) err(`WARNING: ${keys.warning}`);
+  // config.json (monthly limit, chosen key variables) lives beside the run list. An injected
+  // `env` with no injected home means a test — the real ~/.config/bareloop is never read then.
+  const cfgHome = keys.home ?? deps.runlistHome;
+  const cfgOn = cfgHome !== undefined;
   /** every operator/config stop this engine makes, in one exit code — thrown,
    * never `process.exit()`'d, so this stays a library function (constraint:
    * "never process.exit() inside the library — return an exit code").
@@ -1342,22 +1358,32 @@ async function execute(ctx) {
   // the same shape src/cli.js's `doRun` already uses) — a caller that hands in
   // its own provider IS the run, so nothing here needs a real secret.
   if (!deps.provider) {
+    // P4b — the Settings row (keys file line) whose API shape + Base URL match this spec
+    // supplies the key VARIABLE, standing in for the provider's built-in one; no matching
+    // row = the built-in. Names only — values come from the
+    // env / keys file. The judge follows the worker's choice when it is the same provider
+    // (the same rule that gives it the worker's baseUrl below).
+    const keyCfg = cfgOn ? rowsForHome(cfgHome) : [];
+    const workerEnv = applyConfiguredKey(env, spec.provider, spec.baseUrl, keyCfg, spec.model);
+    const judgeEnv = judge.provider === spec.provider ? workerEnv : applyConfiguredKey(env, judge.provider, undefined, keyCfg, judge.model);
+    /** the variable NAME this worker's key is read from (the person's pick, else built-in) — for messages only */
+    const workerKeyName = keyNameFor(spec.provider, spec.baseUrl, keyCfg, spec.model).name;
     // A green anthropic-api job's behaviour is byte-identical to before: its
     // worker key IS `ANTHROPIC_API_KEY`, demanded as ever.
-    workerApiKey = env[providerEntry.envKey];
-    if (!workerApiKey) { err(`${providerEntry.envKey} not set (secrets load from the environment — never the tree)`); throw new ExitSignal(2); }
+    workerApiKey = workerEnv[providerEntry.envKey];
+    if (!workerApiKey) { err(`${workerKeyName} not set (secrets load from the environment — never the tree)`); throw new ExitSignal(2); }
     // F181 — a key that reads as "set" above can still carry a line break/
     // control char/stray whitespace (a two-line secret-store entry, e.g.) and
     // crash Node's own header-encode inside the paid span. Refuse at the SAME
     // door, before any provider is constructed; never echo the value.
     const workerKeyProblem = apiKeyProblem(workerApiKey);
-    if (workerKeyProblem) { err(`${providerEntry.envKey} ${workerKeyProblem} — refusing rather than crashing mid-call (never trimmed or repaired; fix the value at its source)`); throw new ExitSignal(2); }
+    if (workerKeyProblem) { err(`${workerKeyName} ${workerKeyProblem} — refusing rather than crashing mid-call (never trimmed or repaired; fix the value at its source)`); throw new ExitSignal(2); }
     // The judge's KEY follows the RESOLVED judge provider's own env var, with
     // `JUDGE_API_KEY` as a role-named override in front of it (PRD item 32.3). The
     // override matters most in the case this item exists for: a job whose worker and
     // judge are the SAME provider but different accounts, and the anthropic case
     // where one variable used to do two jobs.
-    judgeApiKey = env.JUDGE_API_KEY ?? env[judgeEntry.envKey];
+    judgeApiKey = env.JUDGE_API_KEY ?? judgeEnv[judgeEntry.envKey];
     if (JUDGES && !judgeApiKey) {
       err(`This job's close JUDGES (${judgedStages(spec.closeDecl).length} judged stage(s)) and its judge is ${judge.model} on ${judge.provider}${spec.judge ? ' (signed override)' : " (this job's own worker model — no `judge` override signed)"}.`);
       err(`Neither JUDGE_API_KEY nor ${judgeEntry.envKey} is set — secrets load from the environment, never the tree.`);
@@ -1377,6 +1403,34 @@ async function execute(ctx) {
     }
   }
 
+  // THE MONTHLY $ LIMIT (PANEL-BUILD.md P4a, hamr 2026-09-29: "drop time keep money") — the
+  // ONE run-start seam. Every run this door starts (the CLI's `bareloop run-u` and the panel,
+  // which spawns it) passes here after the signature and the key gates and BEFORE the run
+  // list row, the patient reset or any token: a cap larger than what is left this month does
+  // not start, and nothing is spent. This leg's exposure is the whole signed cap on a cold
+  // start (it covers drafting + run) and only the REMAINDER on a resume/door-rerun, whose
+  // earlier spend is already in the month's total (a resume's killed leg counts its real spend only,
+  // never its unspent cap — `resumingSpine` — since the remainder asked for here covers that). No limit set = no check. An unreadable
+  // config.json refuses too — a broken instrument never silently reads "no limit".
+  {
+    const foldedUsd = dead ? dead.restart.priorSpentUsd : (doorPrior?.spentUsd ?? 0);
+    const legCapUsd = Math.max(0, spec.budgetUsd - (typeof foldedUsd === 'number' && Number.isFinite(foldedUsd) ? foldedUsd : 0));
+    /** @type {string|null} */
+    let refusal = null;
+    try {
+      if (cfgOn) refusal = monthlyRefusalText(checkMonthlyRoom({ capUsd: legCapUsd, home: cfgHome, resumingSpine: deadSpineFile }));
+    } catch (e) {
+      if (!(e instanceof ConfigError)) throw e;
+      err(`${e.message} — refusing to start rather than guess the monthly limit. Nothing spent.`);
+      throw new ExitSignal(2);
+    }
+    if (refusal !== null) {
+      err(refusal);
+      err('Nothing spent. Lower the cap, or raise the monthly limit in Settings.');
+      throw new ExitSignal(2);
+    }
+  }
+
   // `wd`/`spineDir` are derived once, above the resume reader that needs them; only the
   // directory's CREATION belongs here, after the preview/approval gates have exited.
   mkdirSync(spineDir, { recursive: true });

package/types/authorrun.d.ts

@@ -1,6 +1,7 @@
 /**
  * @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]
@@ -23,6 +24,10 @@
 export function main(argv: string[], deps?: Deps): Promise<number>;
 export type Deps = {
     env?: Record<string, string | undefined> | undefined;
+    /**
+     * P4a — test seam: load this home's `.env` keys file even when `env` is injected.
+     */
+    keysHome?: string | undefined;
     stdin?: NodeJS.ReadStream | undefined;
     stdout?: NodeJS.WritableStream | undefined;
     stderr?: NodeJS.WritableStream | undefined;

package/types/cli.d.ts

@@ -3,7 +3,7 @@
  * 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 function main(argv: string[], deps?: {
@@ -18,4 +18,5 @@ export function main(argv: string[], deps?: {
     now?: () => number;
     stdin?: any;
     runlistHome?: string;
+    keysHome?: string;
 }): Promise<number>;