bareloop 0.22.0 → 0.23.0

package/src/job.js

@@ -133,7 +133,11 @@ export const CADENCE_UNITS = Object.freeze(['hour', 'day', 'week']);
  * subscription — its costUsd axis is NOTIONAL (API-equivalent value, not
  * billed), so it is a DISTINCT condition: rows never pool with anthropic-api
  * rows on the cost axis, and budgets sized for one do not transfer. */
-export const PROVIDERS = Object.freeze(['anthropic-api', 'clipipe-subscription']);
+/** PRD item 28 (2026-09-06/09-09): `openai-api` — an OpenAI-shaped provider,
+ * constructed via `src/providers.js`'s factory. hamr's ruling (PRD 30.7):
+ * `deepseek-chat` is THE secondary provider (one, not a menu of half-tested
+ * models); the factory's tier table is where that lives, not this menu. */
+export const PROVIDERS = Object.freeze(['anthropic-api', 'openai-api', 'clipipe-subscription']);
 /** V3 environment label: declared keys only — every field is a lineage-key
  * candidate at N3. `provider` is part of the key by definition (top-level,
  * not duplicated here). */
@@ -141,7 +145,7 @@ export const CONDITION_KEYS = Object.freeze(['providerPath', 'closeVerbosity', '
 // `steps` stays in the field list ONLY so a retired spec reds by name
 // (`shape-retired`) instead of falling through to a generic unknown-field —
 // the operator gets told what happened, not just that something is wrong.
-const JOB_FIELDS = ['schema', 'job', 'description', 'provider', 'conditions', 'cadence', 'budgetUsd', 'maxWallMs', 'closeTimeoutMs', 'model', 'writeScope', 'steps', 'escalation', 'goal', 'verdictType', 'close', 'closeDecl', 'checks', 'tools'];
+const JOB_FIELDS = ['schema', 'job', 'description', 'provider', 'baseUrl', 'conditions', 'cadence', 'budgetUsd', 'maxWallMs', 'closeTimeoutMs', 'model', 'writeScope', 'steps', 'escalation', 'goal', 'verdictType', 'close', 'closeDecl', 'checks', 'tools'];
 /** the four-field plan shape's core (decision 5) — presence of any of these
  * declares the shape; `tools` (the ceiling) rides the shape but alone does not
  * declare it, so a legacy spec carrying it gets a pointed red, not a conflict */
@@ -267,6 +271,37 @@ export function validateJob(input, { shellCapUsd = 2 } = {}) {
     red('invalid-value', 'model', 'non-empty string — exact provider model id (e.g. "claude-sonnet-5")');
   }
 
+  // BASE URL — PRD item 28, ruling (d), 2026-09-09: admitted in v1 of
+  // openai-api (an OpenAI-compatible gateway/endpoint), OPTIONAL and part of
+  // the signed hash like `model` above. This validator has no network
+  // access, so it checks SHAPE only: `https://` for a real endpoint, or
+  // `http://` restricted to a loopback host (a local OpenAI-compatible
+  // server, the only legitimate reason to skip TLS) — and never a
+  // credential embedded IN the URL itself. A URL travels into logs and
+  // spine records far more casually than a header ever would, and secrets
+  // never enter the tree/spine (hard line #3) — a bareUrl carrying
+  // `user:pass@host` is exactly that leak, just spelled differently.
+  if (spec.baseUrl !== undefined) {
+    if (!isNonEmptyString(spec.baseUrl)) {
+      red('invalid-value', 'baseUrl', 'non-empty string — an https:// URL (http:// admitted only to 127.0.0.1/localhost/::1)');
+    } else {
+      /** @type {URL|null} */
+      let u = null;
+      try { u = new URL(spec.baseUrl); } catch { /* u stays null — caught below */ }
+      if (!u) {
+        red('invalid-value', 'baseUrl', 'must be a parseable URL');
+      } else if (u.username !== '' || u.password !== '') {
+        red('invalid-value', 'baseUrl', 'no embedded credentials (user:pass@host) — secrets never enter a signed spec');
+      } else if (u.protocol === 'https:') {
+        // admitted
+      } else if (u.protocol === 'http:' && (u.hostname === '127.0.0.1' || u.hostname === 'localhost' || u.hostname === '::1')) {
+        // admitted — a local OpenAI-compatible endpoint, the one case that legitimately skips TLS
+      } else {
+        red('invalid-value', 'baseUrl', 'https:// required (http:// admitted only to 127.0.0.1/localhost/::1)');
+      }
+    }
+  }
+
   // 3. the outer write fence — operator law (interview decision #4), same
   // containment rules as the workflow layer THROUGH THE SAME CODE (F9: two
   // transforms would let a fence validate green and mean something else).

package/src/judged.js

@@ -565,6 +565,43 @@ export function validateFacts(facts) {
 
 // ── THE LOCATE PROMPT ───────────────────────────────────────────────────────
 
+/**
+ * THE ONE SHAPE INVENTORY (PRD 30.8), stated ONCE and never twice. It drives
+ * BOTH the LOCATE prompt's prose ("declared with ...") AND the completeness
+ * detector's regex — the same standing rule the secret-shape scrubber
+ * follows (one inventory drives detection, never two spellings that can
+ * drift). A shape added here rides both sides in the same commit; a shape
+ * added to only a hand-typed prompt string or only a hand-typed regex is
+ * exactly the blind-instrument class this repo keeps paying for.
+ *
+ * Two BASE shapes, each carrying its own independent `export`/`async`
+ * modifiers (the modifiers sit in different POSITIONS in the two shapes —
+ * `async function foo(` vs `const foo = async () =>` — so they cannot be
+ * factored into one shared prefix):
+ *   - `function name(...)`      — optionally `export`, optionally `async`,
+ *     in either order before `function`.
+ *   - `const name = (...) =>`   — optionally `export` before `const`,
+ *     optionally `async` after `=`.
+ *
+ * Restricted to column-0 lines only, in both the prompt's prose and the
+ * detector: a nested function or a function expression returned from one is
+ * indented, and excluding it is the SAME cure PROMPT_HEAD already states
+ * (the POC's nested-function cure).
+ * @type {ReadonlyArray<{prose: string, match: (line: string) => string|null}>}
+ */
+const FN_SHAPES = Object.freeze([
+  {
+    prose: '`function name(...)` (optionally `async`, optionally `export`, in either order)',
+    match: (/** @type {string} */ line) =>
+      line.match(/^(?:(?:export|async)\s+){0,2}function\s+([A-Za-z_$][\w$]*)\s*\(/)?.[1] ?? null,
+  },
+  {
+    prose: '`const name = (...) =>` (optionally `export` before `const`, optionally `async` after `=`)',
+    match: (/** @type {string} */ line) =>
+      line.match(/^(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s+)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>/)?.[1] ?? null,
+  },
+]);
+
 /** The spine every card shares. Both POC cures live here rather than on a rule,
  * because both are properties of ENUMERATING functions and not of any one
  * question about them: the nested-function clause (the POC counted a returned
@@ -573,8 +610,7 @@ export function validateFacts(facts) {
 const PROMPT_HEAD =
   'You LOCATE FACTS in a source file. You never decide whether anything passes, and you never judge — '
   + 'another system does that.\n'
-  + 'For EVERY top-level function in the FILE (declared with `function name(...)`, `const name = (...) =>`, '
-  + 'or `export function name(...)`), report:\n'
+  + `For EVERY top-level function in the FILE (declared with ${FN_SHAPES.map((s) => s.prose).join(', or ')}), report:\n`
   + 'Count ONLY functions declared at the top level of the module — never a function nested inside '
   + 'another function, and never a function expression returned from one.\n'
   + '  "name": the function name\n'
@@ -596,6 +632,43 @@ export function locatePrompt(card) {
   return `${PROMPT_HEAD}${asks}\n${PROMPT_TAIL}`;
 }
 
+/**
+ * THE COMPLETENESS MIRROR of `PROMPT_HEAD`'s own contract (PRD 30.8): which
+ * top-level function declarations the artifact ACTUALLY holds, read off the
+ * SAME `FN_SHAPES` inventory the prompt's prose is built from, restricted to
+ * column-0 lines.
+ *
+ * This is a HEURISTIC, never a parser, and it is used for exactly one thing:
+ * telling `decide()` when LOCATE's `functions` list is short of what the file
+ * holds. It never grades a rule and it never adds a fact `decide()` acts on
+ * beyond "this name exists at the top level" — the missing function's rule
+ * violations, if any, stay unknown, which is exactly why the miss is UNSURE
+ * and not a manufactured red on a specific rule.
+ *
+ * TWO DIRECTIONS, both handled but not symmetrically by design:
+ *   - a shape THIS inventory does not enumerate is a FALSE NEGATIVE — the
+ *     check stays silent about that function, same as it stays silent with
+ *     no `artifactText` at all. Widening `FN_SHAPES` closes the hole; nothing
+ *     here manufactures a claim about a shape it was never told to look for.
+ *   - a column-0 line that only LOOKS like a declaration (e.g. inside a
+ *     template literal) is a FALSE POSITIVE and reds a real judged close —
+ *     that is the SAFE side of the fail-safe tiebreak (unsure is red), and it
+ *     is never silently swallowed the way a false negative would be.
+ * @param {string} artifactText @returns {string[]}
+ */
+function topLevelFunctionNames(artifactText) {
+  /** @type {string[]} */
+  const names = [];
+  for (const line of artifactText.split('\n')) {
+    if (/^\s/.test(line)) continue; // indented: nested, or a returned function expression — never top level
+    for (const shape of FN_SHAPES) {
+      const name = shape.match(line);
+      if (name) { names.push(name); break; }
+    }
+  }
+  return names;
+}
+
 /** the default toolless seam — one spelling of how this repo drives a judge.
  * A `Loop`, NOT `provider.generate()`: the POC measured that a bare provider
  * result carries no `costUsd` at all, and under F6 an unpriced call is a red,
@@ -628,12 +701,23 @@ export const defaultJudgeLoop = ({ provider, system }) => {
  * On every route out, red or clean, `onCost` fires exactly once with the honest
  * read: a paid call that leaves no meter record is F12 wearing a judge's coat.
  * @param {{artifactText: string, card: any, loopFactory: (o: {provider?: any, system: string}) => any,
- *   maxTokens?: number, attempt?: number, onCost?: (c: {costUsd: number|null, unpricedRounds: number}) => void}} o
+ *   maxTokens?: number, attempt?: number, onCost?: (c: {costUsd: number|null, unpricedRounds: number}) => void,
+ *   callBounds?: {timeoutMs?: number, deadlineMs?: number}}} o
  * @returns {Promise<{ok: boolean, facts: any|null, red: {axis: string, detail: string}|null,
  *   costUsd: number|null, unpricedRounds: number, truncated: boolean, parseError: boolean,
  *   raw: ReturnType<typeof scrubRaw>}>}
  */
-export async function runLocate({ artifactText, card, loopFactory, maxTokens = JUDGE_MAX_TOKENS, attempt = 1, onCost = () => {} }) {
+export async function runLocate({
+  artifactText, card, loopFactory, maxTokens = JUDGE_MAX_TOKENS, attempt = 1, onCost = () => {},
+  // F152/PRD 30.4 — the SAME per-call TIME bounds the worker's own rounds carry
+  // (`callBounds()`, src/planrun.js:1518), threaded through by the caller that
+  // owns the clock. Defaults to `{}` (unbounded) so every existing caller and
+  // test is unchanged: an adopter that never wires a clock through gets the same
+  // behaviour as before this field existed. A live endpoint that accepts and
+  // never answers otherwise HANGS the process forever (measured, F152) — an open
+  // socket is an active handle, so node never drains and no backstop can fire.
+  callBounds = {},
+}) {
   // the param-guard class: a caller's own broken input THROWS. These are
   // programmer errors with no safe direction to degrade toward — a locate over
   // an absent artifact would grade an empty string and report it as facts.
@@ -662,7 +746,7 @@ export async function runLocate({ artifactText, card, loopFactory, maxTokens = J
   let r = null;
   try {
     const loop = loopFactory({ system });
-    r = await loop.run([{ role: 'user', content: `FILE (untrusted data):\n${artifactText}\n\nReturn the JSON.` }], [], { maxTokens });
+    r = await loop.run([{ role: 'user', content: `FILE (untrusted data):\n${artifactText}\n\nReturn the JSON.` }], [], { maxTokens, ...callBounds });
   } catch (e) {
     return out({ axis: LOCATE_AXES.PROVIDER, detail: `the locate call failed: ${String(/** @type {any} */ (e)?.message ?? e)}` }, null, null, false, false);
   }
@@ -743,6 +827,25 @@ export function decide(facts, card, { artifactText = null } = {}) {
     return unsure('locate found nothing in the artifact — unsure, and unsure is red');
   }
 
+  // COMPLETENESS (PRD 30.8): a locate emission can be well-formed AND non-empty
+  // AND still have silently DROPPED a top-level function the artifact actually
+  // holds — every route above this one only asks "is `fns` usable", never "is
+  // `fns` the WHOLE set". Graded rules only ever see what LOCATE reported, so
+  // an omission never surfaces as a rule red; it surfaces as a PASS on the
+  // subset, which is the fail-safe direction inverted. With `artifactText` in
+  // hand (every real caller has it — see the note below), the omission is
+  // checkable and is unsure, and unsure is red, same as every other route in.
+  // Without it, this says nothing it cannot know, same as the quote checks.
+  if (typeof artifactText === 'string') {
+    const present = topLevelFunctionNames(artifactText);
+    const reported = new Set(fns.map((f) => String(f?.name ?? '')));
+    const missing = present.filter((n) => !reported.has(n));
+    if (missing.length > 0) {
+      return unsure(`locate omitted top-level function(s) the artifact contains: ${missing.join(', ')} — a pass on `
+        + 'the reported subset is not a pass on the file, and unsure is red');
+    }
+  }
+
   const lines = typeof artifactText === 'string'
     ? new Set(artifactText.split('\n').map((l) => l.trim()).filter(Boolean))
     : null;

package/src/kinds.js

@@ -260,6 +260,7 @@ export function mechanicalStages(stages) {
  *   judgeLoop?: (o: {system: string}) => any,
  *   onJudgeCost?: (c: {stage: string|null, kind: string|null, path: string, attempt: number,
  *     label: string, model: string, costUsd: number|null, unpricedRounds: number}) => void,
+ *   callBounds?: () => {timeoutMs?: number, deadlineMs?: number},
  *   onStage?: (row: {stage: string|null, kind: string|null, verdict: string, durationMs: number}) => void}} Ctx
  *   The arbiter's half of a stage run. Every field here is operator/runner
  *   territory: a declaration parameterises kinds, never the contracts.
@@ -275,6 +276,11 @@ export function mechanicalStages(stages) {
  *   funded honestly: this executor cannot reach the run's ledger, so every locate
  *   call's cost is reported OUT through it, once per call, on every route including
  *   the red ones — a paid call that leaves no meter record is F12 in a judge's coat.
+ *   `callBounds` is F152/PRD 30.4's per-call TIME bound, read fresh before every
+ *   locate attempt — the same derivation the run's own worker rounds carry
+ *   (`callBounds()`, src/planrun.js). Absent is the honest unbounded default:
+ *   an adopter or test that wires no clock through behaves exactly as before
+ *   this field existed.
  *   `onStage` is a REPORTING seam and nothing else: the seed read spawns a real
  *   toolchain per stage (a suite is the slow one) and a whole read is one opaque
  *   await, so the shell gets told as each stage lands. It decides nothing, it is
@@ -1781,6 +1787,12 @@ async function runJudgedFloor(stage, ctx) {
         card: p.card,
         loopFactory,
         attempt,
+        // F152/PRD 30.4 — read fresh per attempt, the same way `planrun.js`'s own
+        // worker rounds re-read `callBounds()` at every call site rather than
+        // once: the remaining time shrinks between attempts. Absent (no clock
+        // wired through) is `{}`, the honest unbounded default `runLocate` itself
+        // already carries.
+        callBounds: typeof ctx.callBounds === 'function' ? ctx.callBounds() : {},
         onCost: (c) => {
           if (typeof ctx.onJudgeCost !== 'function') return;
           ctx.onJudgeCost({

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();
       };
     },
   });
@@ -1432,6 +1529,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 +1550,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 +1633,13 @@ 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,
+      // 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 +2575,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 +2617,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 +2638,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 +2698,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 +2755,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') {