bareloop 0.30.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/planrun.js

@@ -3864,7 +3864,41 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
       blindCap: capRuns,
       directions: stageDirections,
     });
-    fixTrend.record({ gap: post.gap ?? '' });
+    // F198: feed the STRUCTURED {stage, value} a declared close already produced
+    // (`closeGrade`, src/declaredclose.js) rather than re-parsing `post.gap` through
+    // `readGrade`'s `\bred\b` scan — a declared close's own gap prose never carries
+    // that word, so the text path read every declared grade as an uncomparable
+    // null. `post` IS `lastCloseVerdict` here (this is the opening grade, straight
+    // off `judgeClose()`, before any crash-message substitution can occur), so
+    // `closeGrade(post)` is exact. `readGrade` stays the fallback INSIDE
+    // `trend.record` for a command close, where `closeGrade` returns `{gap}` only.
+    fixTrend.record(closeGrade(post));
+    // F198 item 2 — TRACE: before this, `middle` (below) handed the fix worker
+    // ONLY the current gap (this iteration's raw close output, or the previous
+    // attempt's — planrun.js's `await w.ask([...])` at the end of `middle`) and
+    // never any history of prior grades. Nothing else about the close's own
+    // numbers travelled between tries.
+    //
+    // The fix: a FACTS-ONLY number history, one entry per grade fixTrend has
+    // already read (never advice, never model-generated text — a prompt
+    // register change, `src/promptregisters.js`'s inventory, `src/planrun.js`
+    // already listed there). `checksHistory` is the "N passed of M declared"
+    // count per grade: N counts the satisfied stages on each declared verdict's
+    // own `stages` list (first-red-wins, so that list holds only the stages that
+    // RAN), and M is the DECLARED stage count (`stagedClose.length`, the same
+    // one source `createTrend`'s stageOrder reads) — never the ran count, or a
+    // 7-stage close red at stage 2 would read "1/2" instead of "1/7". Nothing a
+    // command close's verdict carries, so it stays empty there and the line is
+    // simply omitted. The per-stage number history rides on `fixTrend.report()`
+    // already, so nothing new is stored for that half.
+    /** @type {string[]} */
+    const checksHistory = [];
+    const pushChecks = (/** @type {any} */ v) => {
+      if (Array.isArray(v?.stages)) {
+        checksHistory.push(`${v.stages.filter((/** @type {any} */ s) => s.verdict === 'satisfied').length}/${stagedClose.length}`);
+      }
+    };
+    pushChecks(post);
     /** ralph's `ladder` seam, filled by the trend reader instead of the step
      * ladder's repeat/write pair. ONE exhaustion terminal, two triggers (ralph's own
      * rule): the category stays `cap-halt` and the outcome stays `escalated`, so the
@@ -3883,7 +3917,15 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
         if (lastCloseVerdict?.verdict === HUMAN_PAUSE) {
           return { governor: 'close-trend', trend: 'unknown', reading: 'the close is waiting on a person — not a grade', iteration: o.iteration, paused: true };
         }
-        return { governor: 'close-trend', ...fixTrend.record({ gap: o.gap }), iteration: o.iteration };
+        // Same structured-first read as the seed above. `lastCloseVerdict` is THIS
+        // iteration's verdict (judge() ran immediately before ralph calls this
+        // record) UNLESS a worker-crash overwrote `gap` with a synthetic message
+        // (src/ralph.js) that no longer matches `lastCloseVerdict.gap` — guarded by
+        // the equality check so a crash still reads through the text fallback on
+        // its own synthetic gap, exactly as before.
+        const graded = lastCloseVerdict && lastCloseVerdict.gap === o.gap ? closeGrade(lastCloseVerdict) : { gap: o.gap };
+        if (lastCloseVerdict && lastCloseVerdict.gap === o.gap) pushChecks(lastCloseVerdict);
+        return { governor: 'close-trend', ...fixTrend.record(graded), iteration: o.iteration };
       },
       struckOut: fixTrend.struckOut,
       report: fixTrend.report,
@@ -3897,9 +3939,12 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
             : `${rep.strikes}/${rep.limit} strikes — the fix loop stopped making progress against the close's own numbers (${t.reading}). Continue, change approach, or stop?`,
           options: [
             'revise the goal/spec so the work is reachable (a spec edit, so the new hash needs re-approval)',
-            resumable
-              ? 'top up budgetUsd and rerun with --resume, if the trend above says it was still converging'
-              : 'resume is `run-u`-only in v1 — top up budgetUsd and re-fire the bundle from the start, if the trend above says it was still converging',
+            // F197/mul5fofw — this terminal is ONE exhaustion terminal, and ralph.js
+            // hardcodes its outcome as `escalated` (a GRADED RED, src/reuse.js's
+            // `REUSE_GRADED_RED`: the close rendered a verdict and it was red).
+            // `escalated` is a graded red, never a checkpoint (F197) — `--resume`
+            // refuses it, so the sentence states that plainly.
+            'this cannot be resumed — the close already rendered its verdict against the tree; revise the goal/spec and rerun fresh (a new hash needs re-approval)',
             'abandon the task',
           ],
         };
@@ -3996,12 +4041,23 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
         })
         : null;
       if (rootInj) emit('root-injected', { phase: 'fix', ...rootInj.event });
+      // F198 item 2 — the facts-only history: JOINED numbers only, no prose the
+      // model didn't already earn by writing the close's own output. `values`
+      // joins with `→` (fixTrend's own vocabulary), stages join with `·`; a
+      // stage this leg has read only once still shows its one number (no arrow),
+      // which is still a fact the worker did not otherwise have.
+      const checksFact = checksHistory.length > 0 ? `checks passed ${checksHistory.join(' → ')}` : null;
+      const stageFacts = fixTrend.report().stages
+        .filter((s) => s.values.length > 0)
+        .map((s) => `${s.stage} ${s.values.join(' → ')}`);
+      const factsLine = [checksFact, ...stageFacts].filter(Boolean).join(' · ');
       await w.ask([
         'The job\'s final verification is failing. Fix the repository so it passes.',
         `Repository root (absolute): ${workdir}\nEvery path you pass to a tool MUST be absolute and inside this root.`,
         artifacts.length > 0 && `Working context (read-only) — the plan's steps produced:\n${artifacts.map((a) => `[${a.id}] ${a.text}`).join('\n\n')}`,
         !gap && post.gap && `The verification's output on the tree as it stands (not an attempt of yours):\n${post.gap}`,
         gap && `Previous attempt failed the verification:\n${gap}`,
+        factsLine && `The close's own numbers so far, oldest first (facts only — no advice):\n${factsLine}`,
         rootInj && rootInj.note,
       ].filter(Boolean).join('\n\n'));
     };

package/src/promptregisters.js

@@ -76,6 +76,9 @@ export const PROMPT_REGISTERS = Object.freeze([
 
   // src/planrun.js — the native-surface read-truncation strategy line
   Object.freeze({ file: 'src/planrun.js', name: 'NATIVE_READ_STRATEGY' }),
+  // src/planrun.js — the fix loop's facts-only close-grade history line
+  // (F198 item 2), built inline inside `middle` and appended to `w.ask([...])`
+  Object.freeze({ file: 'src/planrun.js', name: 'middle()\'s facts-only "The close\'s own numbers so far" block (inline template, not a const)' }),
 
   // src/authoring.js — the types-genre close template, interpolated verbatim
   // into the authoring prompt (src/authorflow.js's assembled system message,

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

@@ -320,6 +320,90 @@ export function buildRunnerProviders({
   return { provider, providerFor, judgeProvider };
 }
 
+/**
+ * A `providerName`'s own models-list GET endpoint — the shape this
+ * function's ONE caller (`checkProviderReachable`, below) needs and nothing
+ * else reads: `anthropic-api` and `openai-api` (the panel's Model select,
+ * PANEL-BUILD.md P3 build item 7) are the only two shapes this build knows
+ * how to ask, both a plain unauthenticated-body GET with the key in a
+ * header — never a completion/chat endpoint, so this never spends a token.
+ * @param {string} providerName
+ * @param {string} [baseUrl]
+ * @returns {{url: string, headers: Record<string,string>}|null} `null` when
+ *   this provider's models-list shape is not known (never guessed at)
+ */
+function modelsListRequest(providerName, baseUrl) {
+  if (providerName === 'anthropic-api') {
+    return {
+      url: `${baseUrl || 'https://api.anthropic.com/v1'}/models`,
+      headers: { 'x-api-key': '', 'anthropic-version': '2023-06-01' },
+    };
+  }
+  if (providerName === 'openai-api') {
+    return { url: `${baseUrl || 'https://api.openai.com/v1'}/models`, headers: {} };
+  }
+  return null;
+}
+
+/**
+ * $0 reachability check: a GET against `providerName`'s own models-list
+ * endpoint, server-side, with the key in a header — NEVER a completion
+ * request, so it never spends a token (PANEL-BUILD.md P3 build item 7: "the
+ * person must get feedback BEFORE drafting if the chosen model can't
+ * work"). Reused, unmodified, by the panel's model-readiness route today
+ * (`src/panel/authorroutes.js`) and by the future Settings providers
+ * table's own "test" column (PANEL-BUILD.md P4) — ONE function, not two
+ * hand-typed copies of the same probe.
+ *
+ * NEVER returns the key, never logs it — the key only ever appears in a
+ * request header sent straight to the provider's own host.
+ * @param {object} o
+ * @param {string} o.providerName
+ * @param {string} o.apiKey
+ * @param {string} [o.model] when given, the response is also checked for this model id
+ * @param {string} [o.baseUrl]
+ * @param {typeof fetch} [o.fetchImpl] TEST SEAM — defaults to the real global `fetch`
+ * @param {number} [o.timeoutMs] defaults to 4000 — a flaky endpoint must never hang the caller
+ * @returns {Promise<{reachable: boolean, modelListed: boolean|null, status: string, note: string|null}>}
+ */
+export async function checkProviderReachable({
+  providerName, apiKey, model, baseUrl, fetchImpl = fetch, timeoutMs = 4000,
+}) {
+  const req = modelsListRequest(providerName, baseUrl);
+  if (!req) {
+    return {
+      reachable: false, modelListed: null, status: 'unsupported-provider',
+      note: `no models-list check known for "${providerName}"`,
+    };
+  }
+  const headers = { ...req.headers };
+  if (providerName === 'anthropic-api') headers['x-api-key'] = apiKey;
+  else headers.Authorization = `Bearer ${apiKey}`;
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    // GET ONLY — no body, no completion/chat call, no tokens spent.
+    const res = await fetchImpl(req.url, { method: 'GET', headers, signal: controller.signal });
+    if (!res.ok) {
+      return { reachable: false, modelListed: null, status: `HTTP ${res.status}`, note: `models list returned HTTP ${res.status}` };
+    }
+    /** @type {any} */
+    let body = null;
+    try { body = await res.json(); } catch { body = null; }
+    const ids = Array.isArray(body?.data) ? body.data.map((/** @type {any} */ m) => m?.id).filter(Boolean) : [];
+    const modelListed = model ? ids.includes(model) : null;
+    return { reachable: true, modelListed, status: 'ok', note: null };
+  } catch (/** @type {any} */ e) {
+    const cls = e?.name === 'AbortError' ? 'timeout' : (e?.code || e?.name || 'network-error');
+    // 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);
+  }
+}
+
 /**
  * The launch-time warning lines for an ADMITTED-PENDING-PROBE provider, or
  * `null` when the provider has paid for its own end-to-end probe (and for an