bareloop 0.22.0 → 0.24.0

package/src/planrun.js

@@ -43,6 +43,8 @@ import {
 } from './kinds.js';
 import { workBranchName, prepareWorkBranch } from './workbranch.js';
 import { TRANSPORT_MAX_ATTEMPTS, isTransportFailure } from './transport.js';
+import { isRateLimited, rateLimitWaitMs, statedWaitMs } from './ratelimit.js';
+import { setTimeout as sleepMs } from 'node:timers/promises';
 import { checkCloseAbsolutePaths, checkCloseByteSignature, checkStageByteSignature, checkCloseDirRequired } from './close-integrity.js';
 import { resolveCloseTimeoutMs, closeTimeoutBanner, TIMING_PREFLIGHT_CEILING_MS } from './closetimeout.js';
 
@@ -72,21 +74,44 @@ const { Loop, Retry, wireGate, HaltError } = require('bare-agent');
 const transportRetry = new Retry({ maxAttempts: TRANSPORT_MAX_ATTEMPTS, retryOn: isTransportFailure, timeout: 0 });
 
 /**
- * Wrap a Loop provider's `generate` so a single transport-class throw (fetch
- * itself throwing — no HTTP response was ever produced) gets ONE retry via
- * `transportRetry`, and the outcome is reported once the retry is settled.
- * Every other property of `baseProvider` (`.name`, `.model`, `.ownsCycle`,
- * `.policy`) passes through unchanged — bare-agent's Loop reads those
- * directly (src/loop.js).
+ * Wrap a Loop provider's `generate` with TWO independent, one-shot retry
+ * ladders: F115's transport-class retry (unchanged), and PRD item 28's
+ * parked (a/b) ruling — hamr's verbatim call: "do a/b as a fallback, and
+ * verify/validate + no regression" — a bounded retry on an HTTP 429 that
+ * honours the vendor's OWN stated wait (src/ratelimit.js). Every other
+ * property of `baseProvider` (`.name`, `.model`, `.ownsCycle`, `.policy`)
+ * passes through unchanged — bare-agent's Loop reads those directly
+ * (src/loop.js).
  *
- * F64 carve-out: a wall-DERIVED timeout (bare-agent's own `ETIMEDOUT`/
- * `EDEADLINE`, thrown because `clock.callTimeoutMs()` told the provider to
- * cut the call — `isWallTimeout`, src/clock.js) is doctrine's governance
- * stop, never a transport casualty, and retrying it would both mis-spend a
- * round the operator's clock already ended and corrupt `categorize`'s own
- * classification (which reads the SAME error a moment later). So the
- * per-call `retryOn` here is `isTransportFailure(err) && !isWallTimeout(err,
- * clock)` — the clock's verdict always wins over the transport shape.
+ * The two budgets are independent — one transport retry AND one rate-limit
+ * retry may both occur across a single `generate()` call's lifetime, but
+ * each at most once. This is a FALLBACK, not the primary answer: the
+ * primary answer (F139) is picking a worker model with adequate rate
+ * headroom; this softens the failure mode when that was not enough, it does
+ * not replace it.
+ *
+ * F64 carve-out (both ladders): a wall-DERIVED timeout (bare-agent's own
+ * `ETIMEDOUT`/`EDEADLINE`, thrown because `clock.callTimeoutMs()` told the
+ * provider to cut the call — `isWallTimeout`, src/clock.js) is doctrine's
+ * governance stop, never a casualty to retry, and retrying it would both
+ * mis-spend a round the operator's clock already ended and corrupt
+ * `categorize`'s own classification (which reads the SAME error a moment
+ * later). The wall always wins over either retry shape: before EITHER retry,
+ * `isWallTimeout` must be false, and before sleeping for a rate-limit retry,
+ * the run must have MORE time left than the wait would cost
+ * (`clock.remainingMs() > waitMs`) — a wait that would run past the
+ * deadline is not honoured; the run ends on the operator's clock instead of
+ * sleeping past it.
+ *
+ * `spendComplete` note (the one place the two ladders differ): a transport
+ * throw's first attempt may already have been billed (fetch failing after
+ * the request left the socket), so F115 floors `spendComplete` for the rest
+ * of the run regardless of `recovered` (src/run.js reads the `transport-retry`
+ * record's presence for this). A 429, in contrast, is a REFUSAL — the vendor
+ * rejected the request before processing it — so nothing can have been
+ * billed, and a `rate-limit-retry` record does NOT floor `spendComplete`
+ * (src/run.js only watches for `transport-retry`; this is a stated
+ * assumption, not independently measured against a real provider).
  *
  * Scope note: this wraps the ONE seam that builds every worker Loop
  * (scout/drafter/step-worker/fix-worker, planrun.js `newLoop` ~line 2240) —
@@ -103,38 +128,110 @@ const transportRetry = new Retry({ maxAttempts: TRANSPORT_MAX_ATTEMPTS, retryOn:
  * @param {(s: string) => string} scrub
  * @param {import('./clock.js').Clock} clock
  */
-function withTransportRetry(baseProvider, phase, emit, scrub, clock) {
+// F146/F149 (PRD item 30.5) — every provider construction site in this repo now
+// passes `exposeErrorBody: true` (bare-agent's providers), which attaches the
+// parsed upstream error body as `err.body` on an HTTP throw. The body often
+// carries the ONE sentence that names what actually broke — the category and
+// HTTP status alone never do (F146: Qwen's `HTTP 400` said nothing on its own;
+// its body said "System message must be at the beginning"). This was PARKED
+// (2026-09-05 design note) because a raw body can echo the API key straight
+// back — so it goes through `redactSecrets`, the ONE secret shape inventory
+// (`SECRET_PATTERNS`/`scanSecrets`/`redactSecrets`, `src/validate.js`),
+// REGARDLESS of whatever `scrub` a caller has in scope, and is bounded at
+// `BODY_MAX` chars (600 — bounded like every other detail this file emits:
+// `CHECK_GAP_MAX`, `SCOUT_BLOB_MAX`) so one oversized body can never blow a
+// record open. Only this redacted, capped STRING ever rides an emit — the raw
+// `e.body` object itself must never reach a spine record.
+const BODY_MAX = 600;
+const BODY_MARKER = ' — body: ';
+/** @param {any} e @returns {string} '' when there is no body, else ' — body: <redacted, ≤BODY_MAX chars>' */
+const bodySuffix = (e) => {
+  if (e?.body === undefined) return '';
+  let raw;
+  try { raw = JSON.stringify(e.body); } catch { raw = String(e.body); }
+  return `${BODY_MARKER}${redactSecrets(raw).slice(0, BODY_MAX)}`;
+};
+
+function withProviderRetries(baseProvider, phase, emit, scrub, clock) {
   return new Proxy(baseProvider, {
     get(target, prop, receiver) {
       if (prop !== 'generate') return Reflect.get(target, prop, receiver);
       return async (...args) => {
-        let attempts = 0;
-        let firstErr = null;
-        const fn = async () => {
-          attempts += 1;
+        // Each budget is consumed at most once across the WHOLE call,
+        // however many times the two ladders alternate.
+        let transportBudget = 1;
+        let rateLimitBudget = 1;
+
+        /**
+         * One "transport-protected" attempt: calls `target.generate` through
+         * the shared `transportRetry` instance, which itself may retry once
+         * for a transport-class throw — but only while `transportBudget`
+         * is still available, so a SECOND pass through this function (after
+         * a rate-limit sleep) cannot spend a transport retry twice.
+         */
+        const attemptWithTransport = async () => {
+          let calls = 0;
+          /** @type {any} */
+          let firstErr = null;
+          const fn = async () => {
+            calls += 1;
+            try {
+              return await target.generate(...args);
+            } catch (err) {
+              if (calls === 1) firstErr = err;
+              throw err;
+            }
+          };
           try {
-            return await target.generate(...args);
+            const result = await transportRetry.call(fn, {
+              retryOn: (err) => transportBudget > 0 && isTransportFailure(err) && !isWallTimeout(err, clock),
+            });
+            if (calls > 1) {
+              transportBudget -= 1;
+              const message = String(firstErr?.message ?? firstErr ?? '').slice(0, 200) + bodySuffix(firstErr);
+              emit('transport-retry', { phase, attempt: 1, error: scrub(message), recovered: true });
+            }
+            return result;
           } catch (err) {
-            if (attempts === 1) firstErr = err;
+            if (calls > 1) {
+              transportBudget -= 1;
+              const message = String(firstErr?.message ?? firstErr ?? '').slice(0, 200) + bodySuffix(firstErr);
+              emit('transport-retry', { phase, attempt: 1, error: scrub(message), recovered: false });
+            }
             throw err;
           }
         };
-        // `recovered` is knowable only once the retried attempt has settled
-        // (succeeded or exhausted the budget) — emit exactly once, here,
-        // after the outcome is known, never speculatively before it.
-        const report = (recovered) => {
-          if (attempts <= 1) return; // no retry happened — nothing to report
-          const message = String(firstErr?.message ?? firstErr ?? '').slice(0, 200);
-          emit('transport-retry', { phase, attempt: 1, error: scrub(message), recovered });
+
+        /** The whole call, recursing (at most once) through a rate-limit sleep. */
+        const attempt = async () => {
+          try {
+            return await attemptWithTransport();
+          } catch (err) {
+            if (rateLimitBudget <= 0 || !isRateLimited(err) || isWallTimeout(err, clock)) throw err;
+
+            const waitMs = rateLimitWaitMs(err);
+            const remainingMs = clock.remainingMs();
+            // The wall always wins: no retry when nothing parses to an
+            // honourable wait, and none when the run has no more time left
+            // than the wait itself would cost.
+            if (waitMs == null || (remainingMs !== Infinity && remainingMs <= waitMs)) throw err;
+
+            rateLimitBudget -= 1;
+            const stated = statedWaitMs(err);
+            const message = String(err?.message ?? err ?? '').slice(0, 200) + bodySuffix(err);
+            await sleepMs(waitMs, undefined, { ref: false });
+            try {
+              const result = await attempt();
+              emit('rate-limit-retry', { phase, attempt: 1, statedMs: stated, waitedMs: waitMs, error: scrub(message), recovered: true });
+              return result;
+            } catch (err2) {
+              emit('rate-limit-retry', { phase, attempt: 1, statedMs: stated, waitedMs: waitMs, error: scrub(message), recovered: false });
+              throw err2;
+            }
+          }
         };
-        try {
-          const result = await transportRetry.call(fn, { retryOn: (err) => isTransportFailure(err) && !isWallTimeout(err, clock) });
-          report(true);
-          return result;
-        } catch (err) {
-          report(false);
-          throw err;
-        }
+
+        return attempt();
       };
     },
   });
@@ -617,8 +714,15 @@ ${scoutBlob || '(no scout notes)'}`;
  *   `false` → the drafter has no tools, so a native session would report NO cost — return a
  *   metered claude-json TEXT provider (`--output-format json`, `parse:'claude-json'`) instead,
  *   so its spend is never invisible. The Loop path (`anthropic-api`) never touches this.
+ * @param {string|null} [opts.judgeModel] softgreen — WHICH model that judge provider drives
+ *   (PRD item 32.1). Resolved by the CALLER (`resolveJudge`, src/judged.js: the spec's signed
+ *   `judge` override, else the job's own worker model), never pinned in this library. It
+ *   travels with `judgeProvider` or the judged stage stops as a wiring gap: a verdict whose
+ *   grader cannot be named is a floor nobody can attribute.
  * @param {any} [opts.judgeProvider] softgreen — the provider a JUDGED close stage runs its
- *   locate call through, pinned by the operator to `JUDGE_MODEL` (src/judged.js). Separate
+ *   locate call through, built by the CALLER from the RESOLVED judge identity (PRD item
+ *   32.1: `resolveJudge`, src/judged.js — the spec's signed `judge` override, else the job's
+ *   own worker provider and model), never pinned in this library. Separate
  *   from `provider`/`providerFor` on purpose: the judge tier is not a step knob and never
  *   agent-selectable, and the worker's binding is not a legal stand-in for it. Absent is not
  *   a fall-back — a judged stage with no seam instrument-STOPS as a wiring gap, the same
@@ -831,7 +935,7 @@ ${scoutBlob || '(no scout notes)'}`;
  *   'branch-red' | 'cap-halt' | 'wall-halt' | 'provider-red' | 'interpreter-red' |
  *   'step-stalled' | 'hitl-pause' | 'hitl-decision-red' | `step-red:<id>`
  */
-export async function runPlan(job, { workdir, provider, nativeProvider, providerFor, judgeProvider = null, emit, remainingUsd, isUnpriced = () => false, spendComplete = () => true, capRuns = 3, strikeLimit = STRIKE_LIMIT, closeTimeoutMs, closeDir = null, maxStepRounds = 40, layerRoot = false, readShim = false, scout = true, scoutRounds = SCOUT_ROUNDS, bridge = null, now, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null, heldRuling = null, priorSpentUsd = 0, reviewDoor = null, doorRerun = null, resumable = true }) {
+export async function runPlan(job, { workdir, provider, nativeProvider, providerFor, judgeProvider = null, judgeModel = null, emit, remainingUsd, isUnpriced = () => false, spendComplete = () => true, capRuns = 3, strikeLimit = STRIKE_LIMIT, closeTimeoutMs, closeDir = null, maxStepRounds = 40, layerRoot = false, readShim = false, scout = true, scoutRounds = SCOUT_ROUNDS, bridge = null, now, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null, heldRuling = null, priorSpentUsd = 0, reviewDoor = null, doorRerun = null, resumable = true }) {
   // MEMORY-CACHE: what the read shim (src/readshim.js) saved THIS run, summed across
   // every mkWorker's own shim instance (scout, drafter, each step's worker, the fix
   // worker) — one accumulator closed over by all of them, because the shim's ledger
@@ -1432,6 +1536,17 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
    * transport-debugging option list for a run that simply ran out of time. A
    * thrower that named its own category keeps it (the standing typed-attribution
    * rule); only an UNNAMED throw is classified here.
+   *
+   * F146/F149 — this is also the ONE place a categorized error's `.message` gets
+   * the redacted upstream body appended (`bodySuffix`, above). Every downstream
+   * reader of a categorized error's message — `relay()`'s `detail` here, AND
+   * ralph.js's own mid-step dumb-passthrough catch (`detail: String(e.message ||
+   * e)`) reading the SAME error `mkWorker`'s `ask`/`askFrom` threw after routing
+   * it through this function — gets the sentence for free, without ralph.js
+   * importing anything (it stays stdlib-only, PRD §4: fixed, deliberately dumb).
+   * `relay()` re-categorizes an error its own `ask`/`askFrom` already ran through
+   * here, so this must be IDEMPOTENT: `BODY_MARKER` guards a second pass over the
+   * same error from doubling the suffix.
    * @param {any} e
    * @returns {{ err: CategorizedError, category: string }} the same throw, stamped,
    *   plus the category as a plain string (so a caller reading it never has to
@@ -1442,6 +1557,10 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
     const category = e instanceof HaltError ? 'cap-halt'
       : (err.category ?? (isWallTimeout(err, clock) ? 'wall-halt' : 'provider-red'));
     err.category = category;
+    if (typeof err.message === 'string' && !err.message.includes(BODY_MARKER)) {
+      const suffix = bodySuffix(err);
+      if (suffix) err.message += suffix;
+    }
     return { err, category };
   };
 
@@ -1521,6 +1640,18 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
       // an attempt's (a budget funds the attempt PLUS its close), and a null cost trips
       // the same F6 pricing halt rather than being laundered into $0.
       judgeLoop: judgeProvider ? (/** @type {{system: string}} */ o) => defaultJudgeLoop({ provider: judgeProvider, system: o.system }) : null,
+      // the seam's other half (PRD item 32.1) — WHICH model that loop drives. Passed
+      // through untouched: this module resolves no judge, exactly as it constructs no
+      // provider. `runJudgedFloor` stops as a wiring gap when it is absent rather than
+      // falling back to a library pin, so a null here is a stop and never a default.
+      ...(judgeModel === null ? {} : { judgeModel }),
+      // F152/PRD 30.4 — the judge's locate call carried NO time bound at all: a
+      // live endpoint that accepts and never answers hung the process forever
+      // (measured), because an open socket is an active handle and no backstop
+      // can fire on it. The SAME derivation every worker round already uses,
+      // handed through as the FUNCTION (not a snapshot) so a retried locate call
+      // re-reads the remaining time rather than reusing the first attempt's.
+      callBounds,
       onJudgeCost: (/** @type {any} */ c) => emit('judge-round', {
         stage: c.stage, path: c.path, attempt: c.attempt, label: c.label, model: c.model,
         costUsd: c.costUsd, unpricedRounds: c.unpricedRounds,
@@ -2456,7 +2587,7 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
     // re-spends a subscription turn, not a metered fetch) and is out of scope.
     const loopProvider = native
       ? /** @type {any} */ (nativeProvider)({ policy, maxTurns, hasTools: false })
-      : withTransportRetry(workerProvider ?? provider, phase, emit, scrub, clock);
+      : withProviderRetries(workerProvider ?? provider, phase, emit, scrub, clock);
     // F66 — the stall watchdog. bare-agent's `timeoutMs` bounds socket INACTIVITY,
     // not call duration (provider-http.js `req.setTimeout` resets on every byte),
     // so a connection that stays alive while producing nothing is invisible to it:
@@ -2498,7 +2629,7 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
     const newLoop = (gen) => {
       /** @type {any} */
       let self = null;
-      /** @param {{costUsd?: number|null, pricing?: string|null, rateSource?: string|null, usage?: any, kind?: string}} arg */
+      /** @param {{costUsd?: number|null, pricing?: string|null, rateSource?: string|null, usage?: any, kind?: string, stopReason?: string|null}} arg */
       const metered = async (arg) => {
         // The meter fires for EVERY generation, live or abandoned. An orphaned round
         // was really billed, and spend that no instrument sees is the one thing this
@@ -2519,6 +2650,14 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
           ...rateSourceFields(arg),
           tokens: (arg?.usage?.inputTokens ?? 0) + (arg?.usage?.outputTokens ?? 0),
           usage: usageOf(arg?.usage),
+          // PRD item 28 — BA-13: bare-agent's Loop surfaces the round's own neutral
+          // stop reason ('end_turn'|'max_tokens'|'tool_use'|'refusal'|…) on EVERY
+          // onLlmResult call, forwarded verbatim. REPORT-ONLY (nothing here acts on
+          // it — the Loop itself already refuses to execute a 'max_tokens' round's
+          // tool calls, BA-6); null when bare-agent didn't say (pre-BA-13, or a
+          // non-string value), never invented — the same honesty rule every other
+          // provenance field on this record already follows.
+          stopReason: typeof arg?.stopReason === 'string' ? arg.stopReason : null,
         });
         // Everything BELOW here belongs to the live call only. A superseded call must
         // not beat the watch (that is the whole watchdog), must not spend the step's
@@ -2571,7 +2710,17 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
      */
     const askFrom = async (msgs, prompt) => {
       try {
-        return await stallWatch.watch((gen) => newLoop(gen).run([...msgs, { role: 'user', content: prompt }], [], { cacheMessages: true, maxTokens: 32000, ...callBounds() }));
+        // `msgs` is a prior `loop.run()`'s returned transcript, which already has
+        // the Loop's `system` PREPENDED (bare-agent Loop.run, loop.js ~482-486).
+        // The new Loop built below is constructed with the same `system` and would
+        // prepend it again, leaving two identical system messages at index 0/1.
+        // Real OpenAI tolerates that; vLLM-class OpenAI-compatible backends 400 on
+        // it ("System message must be at the beginning") — captured evidence:
+        // bareloop-patients/spines-poc-openai/qwen-failing-request-x760ei99.json.
+        // bare-agent's own Loop.chat() (loop.js ~1321) strips a leading system
+        // message before re-running for exactly this reason; do the same here.
+        const rest = msgs[0]?.role === 'system' ? msgs.slice(1) : msgs;
+        return await stallWatch.watch((gen) => newLoop(gen).run([...rest, { role: 'user', content: prompt }], [], { cacheMessages: true, maxTokens: 32000, ...callBounds() }));
       } catch (e) {
         throw categorize(e).err;
       }
@@ -2618,6 +2767,10 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
    * worker does, so this path needs the same split or it is the blinder route),
    * and transport. */
   const relay = (/** @type {any} */ e, /** @type {string} */ phase) => {
+    // categorize(e) mutates e.message in place (guarded, idempotent) with the
+    // redacted body suffix — never re-append it here, or a caller whose thrown
+    // error already went through categorize() once (mkWorker's ask/askFrom)
+    // would double it.
     const { category } = categorize(e);
     const detail = String(e?.message ?? e);
     if (category === 'cap-halt') {

package/src/providers.js

@@ -0,0 +1,301 @@
+// Provider factory (PRD item 28, shape (1)): ONE seam mapping a job spec's
+// `provider` name to the bare-agent constructor it drives, the env var
+// carrying its key, and the per-tier model table — including any
+// provider-specific request-key gating. Before this module existed, both
+// runners constructed `AnthropicProvider` BY NAME (`src/cli.js`'s
+// `buildProviders`, `scripts/run-u.mjs`'s top-level wiring) and any second
+// provider would have meant scattering `if (provider === …)` across both.
+//
+// hamr's ruling (PRD 30.7, 2026-09-09): `deepseek-chat` is THE secondary
+// provider — "settle on one secondary/replacement for claude … don't
+// pickpocket random models". This table is not a menu of half-tested
+// models; it is exactly the two provider identities the PROVIDERS menu
+// (`src/job.js`) admits.
+//
+// What this module is NOT: it never RESOLVES a judge identity itself (that
+// stays arbiter territory, `resolveJudge`/`resolveJobJudge` in
+// src/judged.js — the spec's signed `judge` override, else the job's own
+// worker provider and model, PRD item 32) — it only CONSTRUCTS the judge
+// provider object from an identity the caller already resolved
+// (`buildRunnerProviders`, below); it never prices a round (F113: rates
+// passthrough is dead), and never decides a budget.
+
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { AnthropicProvider, OpenAIProvider, GeminiProvider } = require('bare-agent/providers');
+
+/**
+ * Today's anthropic-api tier table — EXACTLY the `DEFAULT_TIER_MODELS` both
+ * runners hardcoded before this factory existed. Any change to these two
+ * values is a change to shipped anthropic-api behaviour, not a refactor.
+ */
+export const ANTHROPIC_TIER_MODELS = Object.freeze({
+  sonnet: 'claude-sonnet-5',
+  haiku: 'claude-haiku-4-5-20251001',
+});
+
+/**
+ * DeepSeek (F149/F150) is a SINGLE model, not a tiered family — hamr's
+ * ruling above: one secondary provider, not a menu. Both tiers map to the
+ * same model id ON PURPOSE: `resolveWorkerModel`/a runner's `providerFor
+ * (tier)` only ever LOOK UP a tier's model id (src/job.js:818-827,
+ * scripts/run-u.mjs's `providerFor`) — neither assumes the tiers name
+ * different models — so repeating the one id is the honest representation
+ * of a single-model provider, not a second model masquerading as `haiku`.
+ * If DeepSeek (or a future openai-api entrant) ever ships a genuinely
+ * cheaper tier model, this is where it would earn its own `haiku` id.
+ */
+export const OPENAI_TIER_MODELS = Object.freeze({
+  sonnet: 'deepseek-chat',
+  haiku: 'deepseek-chat',
+});
+
+/**
+ * Gemini (PRD item 31.3, hamr 2026-09-09: "anthropic, openai, gemini drop
+ * ollama for now"). Two real tiers, unlike DeepSeek's single model: `flash` is
+ * the cheap tier by design, so `haiku` maps to it honestly rather than
+ * repeating one id.
+ *
+ * ADMITTED-PENDING-PROBE. The probe rule stands (PRD item 28 ruling (d),
+ * 2026-09-09): no endpoint is in the menu without its own clean paid probe,
+ * and `gemini-api` has ZERO runs. `anthropic-api` is the original (~167
+ * archived runs) and `openai-api` was probed green through the shipped runner
+ * (run mtu12vks, $1.64/$4, F157); gemini owes that fire and has not paid it.
+ * `PROBE_STATUS` below is the machine-readable form of that debt — nothing in
+ * here silently pretends the provider is proven.
+ */
+export const GEMINI_TIER_MODELS = Object.freeze({
+  sonnet: 'gemini-2.5-pro',
+  haiku: 'gemini-2.5-flash',
+});
+
+/**
+ * Which admitted providers have paid for their own end-to-end probe, and which
+ * have not. Read by the runner to print a loud marker; never read to REFUSE —
+ * hamr admitted gemini to the menu, and a table that quietly withheld it would
+ * be a second, invisible ruling. An unprobed provider runs, and says so.
+ * @type {Readonly<Record<string, {probed: boolean, evidence: string}>>}
+ */
+export const PROBE_STATUS = Object.freeze({
+  'anthropic-api': Object.freeze({ probed: true, evidence: 'the original surface — ~167 archived runs' }),
+  'openai-api': Object.freeze({ probed: true, evidence: 'run mtu12vks, green through scripts/run-u.mjs, $1.64/$4 (F157)' }),
+  'gemini-api': Object.freeze({ probed: false, evidence: 'ZERO runs — admitted to the menu, owes its own paid probe (PRD item 31.3)' }),
+});
+
+/**
+ * Per-MODEL request-key gating (F149, live-measured 2026-09-09): DeepSeek
+ * silently IGNORES the modern `max_completion_tokens` key — asked for 64
+ * output tokens, it returned 665/608 — and only honours the legacy
+ * `max_tokens` key. `bare-agent`'s `OpenAIProvider` already exposes the
+ * switch (`legacyMaxTokens`, BA-24; no model-name sniffing inside
+ * bare-agent itself — "the caller declares the dialect"), so THIS table is
+ * bareloop's routing of it, keyed per model, never a global default. An
+ * output cap that does not bind is a money hazard: a reasoning model can
+ * run to its own ceiling on every round, silently, so getting this wrong
+ * for even one model defeats every budget that model's tier sets.
+ *
+ * A model with no entry here gets `{}` — bare-agent's own default
+ * (`max_completion_tokens`, GPT-5-safe) applies, unmodified.
+ */
+const OPENAI_MODEL_OPTIONS = Object.freeze({
+  'deepseek-chat': Object.freeze({ legacyMaxTokens: true }),
+});
+
+/**
+ * @typedef {object} ProviderTableEntry
+ * @property {new (options: any) => any} ctor the bare-agent provider class
+ * @property {string} envKey the environment variable this provider reads its key from
+ * @property {Readonly<Record<string, string>>} tiers tier name -> model id
+ * @property {string} endpointKey the CONSTRUCTOR OPTION NAME this provider reads its endpoint from — NOT assumed to be `baseUrl` (see below)
+ * @property {(model: string|undefined) => Record<string, any>} paramsFor per-model request-key/param gating, applied on TOP of {exposeErrorBody:true, apiKey, model, <endpointKey>?}
+ */
+
+// ── WHY `endpointKey` IS A FIELD AND NOT THE LITERAL `baseUrl` ──────────────
+//
+// hamr's framing for this item was "api + api shape + endpoint" (PRD 31.3), and
+// the endpoint half is the one that does NOT generalize. Read from bare-agent's
+// own constructors, not assumed:
+//
+//   AnthropicProvider  `baseUrl`  (provider-anthropic.js:49)
+//   OpenAIProvider     `baseUrl`  (provider-openai.js:76)
+//   GeminiProvider     `baseUrl`  (provider-gemini.js:47)
+//   OllamaProvider     `url`      (provider-ollama.js:32)  <- and NO apiKey at all
+//
+// Every one of these constructors defaults its endpoint when the option is
+// absent and none of them validate unknown option names. So passing `baseUrl`
+// to Ollama would not throw: it would be IGNORED, the provider would default to
+// `http://localhost:11434`, and the run would quietly talk to the wrong machine.
+// That is the F149 class exactly — DeepSeek silently ignoring
+// `max_completion_tokens` and returning 665 tokens for a 64-token cap — where a
+// silently-dropped option produces a plausible-looking run against a
+// configuration nobody chose.
+//
+// Ollama is NOT admitted today (hamr, 2026-09-09: "drop ollama for now"), so
+// this field currently reads `baseUrl` for all three entries and its value is
+// never exercised against a second spelling. It is here anyway, because the
+// alternative is a hardcoded `baseUrl` that is correct for exactly as long as
+// the menu holds only http-shaped API providers, and the FIRST thing that
+// changes when Ollama is admitted is the one line nobody would think to look at.
+
+/** @type {Readonly<Record<string, ProviderTableEntry>>} */
+const PROVIDER_TABLE = Object.freeze({
+  'anthropic-api': Object.freeze({
+    ctor: AnthropicProvider,
+    envKey: 'ANTHROPIC_API_KEY',
+    tiers: ANTHROPIC_TIER_MODELS,
+    endpointKey: 'baseUrl',
+    // Anthropic has only ever had one request key for the output cap
+    // (`max_tokens`) — nothing to gate here, ever (unlike OpenAI-shaped
+    // backends, which fork on `max_tokens` vs `max_completion_tokens`).
+    paramsFor: () => ({}),
+  }),
+  'openai-api': Object.freeze({
+    ctor: OpenAIProvider,
+    envKey: 'OPENAI_API_KEY',
+    tiers: OPENAI_TIER_MODELS,
+    endpointKey: 'baseUrl',
+    paramsFor: (model) => OPENAI_MODEL_OPTIONS[/** @type {string} */ (model)] ?? {},
+  }),
+  'gemini-api': Object.freeze({
+    ctor: GeminiProvider,
+    envKey: 'GEMINI_API_KEY',
+    tiers: GEMINI_TIER_MODELS,
+    endpointKey: 'baseUrl',
+    // Gemini carries no `max_tokens`/`max_completion_tokens` fork of its own —
+    // bare-agent's GeminiProvider maps the cap internally. Nothing to gate, and
+    // an empty object is the honest statement of that, not an omission.
+    paramsFor: () => ({}),
+  }),
+});
+
+/**
+ * Look up a provider's table entry. Throws a NAMED error on an unrecognized
+ * provider — never a silent default (the `resolveRates`-style-substring-
+ * match lesson: a forward hazard even at zero observed rounds, MEMORY.md).
+ * `src/job.js`'s `PROVIDERS` menu is the one place a spec's `provider`
+ * field is validated; this is the runtime construction seam it feeds.
+ * @param {string} providerName
+ * @returns {ProviderTableEntry}
+ */
+export function resolveProvider(providerName) {
+  const entry = PROVIDER_TABLE[/** @type {keyof typeof PROVIDER_TABLE} */ (providerName)];
+  if (!entry) {
+    throw new Error(
+      `src/providers.js: unknown provider "${providerName}" — no silent default. `
+      + `Known providers: ${Object.keys(PROVIDER_TABLE).join(', ')}`,
+    );
+  }
+  return entry;
+}
+
+/**
+ * Construct ONE provider instance for `providerName`/`model`, applying
+ * `exposeErrorBody: true` (F153 — every constructed provider, unconditionally)
+ * and the model's own request-key gating (`paramsFor`). `baseUrl` (PRD item
+ * 28, ruling (d), 2026-09-09: admitted in v1) is forwarded only when given —
+ * every provider constructor here defaults it on its own when absent.
+ * @param {string} providerName
+ * @param {{apiKey?: string, model?: string, baseUrl?: string}} [options]
+ */
+export function makeProvider(providerName, { apiKey, model, baseUrl } = {}) {
+  const entry = resolveProvider(providerName);
+  return new entry.ctor({
+    exposeErrorBody: true,
+    apiKey,
+    model,
+    // the endpoint goes in under THIS PROVIDER'S OWN OPTION NAME, never a
+    // hardcoded `baseUrl` (PRD item 31.3). The spec field stays `baseUrl` for
+    // everyone — one name for the person writing the job — and the translation
+    // to the constructor's spelling happens here, once. A provider whose option
+    // is spelled differently would otherwise IGNORE the endpoint silently and
+    // run against its own default; see the note above the table.
+    ...(baseUrl !== undefined ? { [entry.endpointKey]: baseUrl } : {}),
+    ...entry.paramsFor(model),
+  });
+}
+
+/**
+ * Build the `{provider, providerFor, judgeProvider}` triple both runners
+ * need (`src/cli.js`'s `buildProviders`, `scripts/run-u.mjs`'s top-level
+ * wiring) — ONE seam instead of two copies of the same construction and
+ * tier-memoization logic. `model`/`tierModels` are already-RESOLVED inputs
+ * (the caller runs `resolveWorkerModel` itself, exactly as both runners did
+ * before this factory existed — that decision stays where each runner's own
+ * `--model` flag/spec precedence lives, not duplicated in here).
+ *
+ * THE JUDGE IS NO LONGER PINNED TO ANTHROPIC (PRD item 32.2, hamr 2026-09-10:
+ * *"what i care about is that judge becomes llm agnostic and not set to one
+ * model or provider"*). It is constructed through this same factory, from a
+ * `judgeProviderName`/`judgeModel` pair the CALLER resolved (`resolveJudge`,
+ * src/judged.js — the spec's signed `judge` override, else the job's own worker
+ * provider and model). Item 28's pin, and item 28 part (2)'s deferral of a
+ * signed `judge:{provider,model}` field, both close here.
+ *
+ * `judgeApiKey` stays a SEPARATE argument rather than being derived: the judge
+ * may legitimately be a different provider from the worker, and reading its key
+ * for it would put a second env-var reader in a module whose whole job is to
+ * have exactly one. The caller reads the resolved judge provider's own `envKey`
+ * and hands the key in — the same contract the worker key already has here.
+ * @param {object} args
+ * @param {string} args.providerName spec.provider (or the anthropic-api default)
+ * @param {string|undefined} args.apiKey the WORKER's key, read from the provider's own `envKey`
+ * @param {string} args.model the already-resolved worker model id
+ * @param {Readonly<Record<string, string>>} args.tierModels the already-resolved tier -> model map (spec override folded in by the caller)
+ * @param {string|undefined} [args.baseUrl] spec.baseUrl, if any
+ * @param {string|undefined} args.judgeApiKey the judge's own key, read by the caller from the RESOLVED judge provider's `envKey`
+ * @param {string} args.judgeModel the resolved judge model id
+ * @param {string} [args.judgeProviderName] the resolved judge provider name; defaults to `providerName` (the job's own worker provider), which is `resolveJudge`'s own default
+ * @param {string|undefined} [args.judgeBaseUrl] the judge provider's endpoint, when it takes one
+ */
+export function buildRunnerProviders({
+  providerName, apiKey, model, tierModels, baseUrl, judgeApiKey, judgeModel,
+  judgeProviderName = providerName, judgeBaseUrl = undefined,
+}) {
+  const provider = makeProvider(providerName, { apiKey, model, baseUrl });
+  /** @type {Record<string, any>} */
+  const tierCache = {};
+  const providerFor = (/** @type {string} */ tier) => (tierCache[tier] ??= (
+    tierModels[tier] === model
+      ? provider
+      : makeProvider(providerName, { apiKey, model: tierModels[tier], baseUrl })
+  ));
+  // the judge goes through the SAME table as the worker — one place names a
+  // provider identity, which is the entire reason this factory exists. Reusing
+  // the worker instance when the identity matches exactly is not an optimisation
+  // for its own sake: a second instance against the same endpoint/model is a
+  // second prompt-cache prefix, and cache writes are ~41% of the bill.
+  const judgeProvider = (judgeProviderName === providerName && judgeModel === model && judgeApiKey === apiKey
+    && judgeBaseUrl === baseUrl)
+    ? provider
+    : makeProvider(judgeProviderName, { apiKey: judgeApiKey, model: judgeModel, baseUrl: judgeBaseUrl });
+  return { provider, providerFor, judgeProvider };
+}
+
+/**
+ * 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
+ * off-table name — an unknown provider is `resolveProvider`'s named throw to
+ * report, never this function's warning to soften).
+ *
+ * This lives here, next to `PROBE_STATUS`, rather than inline in the runner,
+ * for one reason: inline it was UNTESTABLE. `scripts/run-u.mjs` reaches this
+ * point only with a real job row (a machine-local patient path) and a real
+ * signed spec, so nothing in the suite could reach the branch, and a warning
+ * nothing executes drifts exactly the way the green-only prose did (item 31.2).
+ *
+ * It never REFUSES, and it never returns a shape a caller can mistake for a
+ * refusal: hamr admitted `gemini-api` to the menu, and a probe table that
+ * quietly withheld it would be a second ruling nobody made.
+ * @param {string} providerName
+ * @returns {string[]|null} lines to print, in order, or null when there is nothing to say
+ */
+export function probeWarningLines(providerName) {
+  const probe = PROBE_STATUS[/** @type {keyof typeof PROBE_STATUS} */ (providerName)];
+  if (!probe || probe.probed !== false) return null;
+  return [
+    `⚠  UNPROVEN PROVIDER — "${providerName}" is on the menu but has never been probed end to end.`,
+    `   ${probe.evidence}`,
+    '   It will run. Nothing has shown that it CAN run this job to a close-rendered verdict.',
+  ];
+}