bareloop 0.21.0 → 0.23.0

package/src/planrun.js

@@ -43,6 +43,10 @@ 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';
 
 const require = createRequire(import.meta.url);
 const { Loop, Retry, wireGate, HaltError } = require('bare-agent');
@@ -70,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) —
@@ -101,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();
       };
     },
   });
@@ -640,7 +739,14 @@ ${scoutBlob || '(no scout notes)'}`;
  *   ladder (src/ladder.js). Arbiter territory exactly as the count it replaced was —
  *   the runner sets it, the plan cannot express it, and no step may tighten or raise
  *   it.
- * @param {number} [opts.closeTimeoutMs] close/check wall-clock cap (shell territory)
+ * @param {number} [opts.closeTimeoutMs] close/check wall-clock cap (shell territory).
+ *   OPTIONAL as of PRD item 27/M3: absent, this run autosets it from a $0 seed
+ *   timing pass (or the spec's own signed `closeTimeoutMs` override) — an
+ *   explicit value here still wins outright (backward compatibility/test
+ *   control only, F133: `scripts/run-u.mjs`/`src/cli.js` never pass this).
+ * @param {string|null} [opts.closeDir] the close's own books directory (PRD
+ *   item 27/M3 Part B), forwarded to every close invocation as
+ *   `BARELOOP_CLOSE_DIR`
  * @param {number} [opts.maxStepRounds] the shell's per-step rounds ceiling (validatePlan's bound)
  * @param {boolean} [opts.scout=true] operator-only switch (docs/product/SCOUT-CONTRAST.md):
  *        `false` on a FRESH run (no `resumeSeed`) skips the survey entirely — `scoutBlob`
@@ -811,12 +917,18 @@ ${scoutBlob || '(no scout notes)'}`;
  *   precisely the state the person rejected), and the words reach the PLANNER as new
  *   authoring. It is never a `humanRuling` — that answers a close's human STAGE, and
  *   a green-class job has none. Empty words are refused at the same seam every door is.
+ * @param {boolean} [opts.resumable=true] PRD item 27(c)/F130 — does THIS runner
+ *   support `--resume`? Forwarded verbatim from `runJob`; `run-u.mjs` leaves it at
+ *   the default (byte-identical to before this param existed), the bundle CLI
+ *   passes `false` so the three `--resume`-naming readouts below (`MONEY_OPTIONS`,
+ *   the resume-plan-red option, the fix-loop terminal) say "resume is `run-u`-only
+ *   in v1" instead of naming a flag that would fail if typed.
  * @returns {Promise<string>} 'green' | 'already-green' | 'escalated' | 'plan-red' |
  *   'check-red' | 'close-red' | 'close-unsupported' | 'recipe-stale' | 'pricing-red' |
  *   '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, 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 }) {
+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 }) {
   // 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
@@ -916,6 +1028,159 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
     return 'close-unsupported';
   }
 
+  // ── close-absolute-path (PRD item 27(c), F129's general fix): the SAME
+  // detector `src/bundle.js` already applies at export time, now applied for
+  // EVERY job at run start, before the close-first precheck and before any
+  // provider call. A close script whose CONTENT bakes in an absolute path
+  // that exists on disk judges the wrong tree by construction (F129) — the
+  // spec's own `cmd` field naming the script is the address and stays legal;
+  // only the script's bytes are judged. `readCloseScripts`/
+  // `checkCloseAbsolutePaths` live in `src/close-integrity.js` so this and
+  // `exportBundle` never drift into two spellings of the same rule.
+  {
+    const integrity = checkCloseAbsolutePaths(job, workdir);
+    if (!integrity.ok) {
+      const detail = integrity.reds.map((r) => `${r.stage}: "${r.literal}"`).join('; ');
+      emit('escalation', {
+        category: 'close-absolute-path', decisionReady: true,
+        decision: 'A close script bakes in an absolute path that exists on disk — it would judge the wrong tree by construction (F129), so nothing was run and nothing was spent.',
+        options: ['fix the close script to read the cwd it is given, never a baked-in path', 'abandon the task'],
+        detail,
+      });
+      return 'close-absolute-path';
+    }
+  }
+
+  // ── close-tampered (PRD item 27/M2, N4's own general fix): the job's
+  // signature covers a close STAGE's byte-exact CONTENT (`close[].sha256`),
+  // not only the `cmd` path naming it — `jobSpecHash` already covers this
+  // field with no hash-function change (it sits inside the signed spec), so
+  // the only thing left to verify is that the SCRIPT ON DISK still is what
+  // was signed. Same seam as `close-absolute-path` immediately above (run
+  // start, $0, before the close-first precheck and before any provider
+  // call) and the same detector module — `checkCloseByteSignature` reuses
+  // `readCloseScripts`, so this and the runtime re-verify inside
+  // `runCloseStages` below can never drift into two spellings of "which
+  // bytes were signed".
+  {
+    const sig = checkCloseByteSignature(job, workdir);
+    if (!sig.ok) {
+      const detail = sig.reds.map((r) => `${r.stage}: expected ${r.expected.slice(0, 12)}… got ${r.actual ? `${r.actual.slice(0, 12)}…` : '<unreadable>'}`).join('; ');
+      emit('escalation', {
+        category: 'close-tampered', decisionReady: true,
+        decision: "A close script's bytes no longer match its signed sha256 — it would run something other than what was approved, so nothing was run and nothing was spent.",
+        options: ['restore the close script to its signed bytes', 're-sign the close if the change is intentional (a new spec hash needs re-approval)', 'abandon the task'],
+        detail,
+      });
+      return 'close-tampered';
+    }
+  }
+
+  // ── close-dir-required (PRD item 27/M3 Part B): a close script that reads
+  // its own books directory (`BARELOOP_CLOSE_DIR`) and gets none would run
+  // silently against `undefined` — refuse at the same $0 seam as the two
+  // checks immediately above, before any tokens spend.
+  {
+    const dirCheck = checkCloseDirRequired(job, workdir, closeDir);
+    if (!dirCheck.ok) {
+      const detail = dirCheck.reds.map((r) => `${r.stage}: ${r.path}`).join('; ');
+      emit('escalation', {
+        category: 'close-dir-required', decisionReady: true,
+        decision: 'A close script reads BARELOOP_CLOSE_DIR (its own books directory, deliberately outside the patient tree) but the runner was given none — nothing was run and nothing was spent.',
+        options: ['run this job through a runner that sets closeDir (run-u.mjs, or the bundle CLI)', 'abandon the task'],
+        detail,
+      });
+      return 'close-dir-required';
+    }
+  }
+
+  // ── close timeout: autoset + signed override (PRD item 27/M3). hamr,
+  // 2026-09-06: "both … autoset and can be override, same like api pricing".
+  // Constants (`CLOSE_TIMEOUT_FLOOR_MS`, `CLOSE_TIMEOUT_K`) are hamr's own
+  // arbiter constants (2026-09-07) — never agent- or adopter-settable.
+  //
+  // Precedence, all $0, before any provider call:
+  //   1. an EXPLICIT `closeTimeoutMs` runtime option (the pre-M3 shell/test
+  //      knob) wins outright — kept for backward compatibility and for tests
+  //      that force a specific close-timeout scenario; it is never the signed
+  //      spec field and prints its own honest word rather than "signed
+  //      override". F133 (run mtqwmb9l): this used to also be how
+  //      `scripts/run-u.mjs` fed its OWN pre-resolved ceiling through, which
+  //      printed the number correctly here but under the wrong word
+  //      ("explicit runner override") beside run-u's own already-correct
+  //      "estimated"/"signed override" line — two banners for one number,
+  //      the second one lying about its source. Fixed by making this the
+  //      ONLY caller of `closeTimeoutMs` an operator/runner is meant to use:
+  //      `run-u.mjs` no longer resolves-and-passes it at all (see its own
+  //      comment); this tier is test/back-compat-only again.
+  //   2. the SIGNED spec field `job.closeTimeoutMs` — the operator's own
+  //      number, which may legally sit above OR below the autoset estimate
+  //      (F113's rates-passthrough shape).
+  //   3. AUTOSET — a $0 timing pass runs every stage once (ignoring verdicts;
+  //      first-red-wins stays for the real precheck below), under the
+  //      generous provisional ceiling `TIMING_PREFLIGHT_CEILING_MS` so a
+  //      genuinely hung stage still ends. `max(FLOOR, K × slowest)` becomes
+  //      the ceiling every close run in this call uses, and a stage that
+  //      timed out DURING THE TIMING PASS is `close-timing-red` — the close
+  //      cannot run on this machine, and the provider was never called.
+  //
+  // The pass is SKIPPED whenever an override already exists (case 1 or 2):
+  // running every stage a second time just to throw the reading away would
+  // waste real machine time before any provider call, and — measured risk —
+  // a close stage a test or an operator deliberately made slow/hanging would
+  // then block for up to 10 minutes for no purpose. "Guesstimate only when no
+  // rate is given" is the same doctrine F113 already applies to pricing.
+  {
+    const explicitOverride = typeof closeTimeoutMs === 'number' && Number.isFinite(closeTimeoutMs) ? closeTimeoutMs : null;
+    if (explicitOverride !== null) {
+      // A caller-passed runtime option wins outright and skips the timing
+      // pass entirely — this is the pre-M3 shell/test knob (backward
+      // compatibility only, F133: no production runner passes this anymore —
+      // `scripts/run-u.mjs` and `src/cli.js` both leave this call site
+      // nothing to autoset from but the autoset/signed-override tiers below).
+      closeTimeoutMs = explicitOverride;
+      emit('close-timing', { perStage: [], slowestMs: null, slowestName: null, ceilingMs: closeTimeoutMs, source: 'explicit' });
+      console.log(closeTimeoutBanner({ ceilingMs: closeTimeoutMs, source: 'explicit' }));
+    } else {
+      const resolved = await resolveCloseTimeoutMs({ job, stages: stagedClose, cwd: workdir, redact: scrub });
+      if (resolved.timedOut) {
+        // `timedOut` is only ever true alongside a real `timing` reading
+        // (`resolveCloseTimeoutMs` never sets one without the other) — the
+        // cast states that correlation for the checker, which cannot infer
+        // it across the two independent optional fields on its own.
+        const timing = /** @type {NonNullable<typeof resolved.timing>} */ (resolved.timing);
+        const detail = timing.perStage.filter((s) => s.timedOut).map((s) => s.name).join(', ');
+        emit('close-timing', { perStage: timing.perStage, slowestMs: timing.slowestMs, slowestName: timing.slowestName, ceilingMs: null, source: 'estimated' });
+        emit('escalation', {
+          category: 'close-timing-red', decisionReady: true,
+          decision: `A close stage did not finish within the timing preflight's own ceiling (${TIMING_PREFLIGHT_CEILING_MS}ms) — the close cannot run on this machine in a boundable time, so nothing was run and nothing was spent.`,
+          options: ['investigate why the stage hangs (infra/network/resource issue)', 'sign an explicit closeTimeoutMs override once the real duration is known', 'abandon the task'],
+          detail,
+        });
+        return 'close-timing-red';
+      }
+      closeTimeoutMs = /** @type {number} */ (resolved.closeTimeoutMs);
+      emit('close-timing', { ...(resolved.timing ?? { perStage: [], slowestMs: null, slowestName: null, anyTimedOut: false }), ceilingMs: closeTimeoutMs, source: resolved.source });
+      console.log(closeTimeoutBanner({ ceilingMs: closeTimeoutMs, source: resolved.source, slowestMs: resolved.timing?.slowestMs, slowestName: resolved.timing?.slowestName }));
+    }
+  }
+
+  // ── the wall must be able to fund at least one close under the EFFECTIVE
+  // ceiling just computed (PRD item 27/M3): `job.maxWallMs`'s own static
+  // floor (`MIN_WALL_MS`, src/job.js) assumed the library's un-autoset
+  // default — with autoset, the real per-stage ceiling is only known here, at
+  // run start, so the honest shape is a run-start check, never a silent
+  // clamp (a budget under one close cannot fund its own close, verbatim the
+  // reasoning `maxWallMs`'s own validator red already states).
+  if (typeof job.maxWallMs === 'number' && job.maxWallMs < closeTimeoutMs) {
+    emit('escalation', {
+      category: 'wall-under-close-timeout', decisionReady: true,
+      decision: `maxWallMs (${job.maxWallMs}ms) is under the effective close timeout (${closeTimeoutMs}ms) — a budget under one close cannot fund its own close, so nothing was run and nothing was spent.`,
+      options: ['raise maxWallMs to at least the printed close timeout and rerun (a spec edit, so the new hash needs re-approval)', 'sign a lower closeTimeoutMs override if the measured duration allows it (same re-approval)', 'abandon the task'],
+    });
+    return 'wall-under-close-timeout';
+  }
+
   // ── THE SIGNER'S ANSWER (N4 §1.4), read before anything costs anything.
   //
   // Three gates, and each refuses rather than guesses. A decision that is not one
@@ -1264,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
@@ -1274,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 };
   };
 
@@ -1300,6 +1580,13 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
     'revise the goal/spec so the work fits the time (same re-approval)',
     'abandon the task',
   ];
+  /** PRD item 27(c)/F130 — the honest escalation tail. `run-u.mjs` supports
+   * `--resume`; the exported bundle CLI does not (v1) and would print a flag
+   * that fails if typed. `resumable` (default `true`, `run-u`'s existing
+   * lines unchanged) picks which sentence names the resume lever. */
+  const resumeToCapNote = resumable
+    ? 'top up budgetUsd and rerun with --resume (resume-to-cap; a spec edit, so the new hash needs re-approval)'
+    : 'resume is `run-u`-only in v1 — top up budgetUsd and re-fire the bundle from the start (a spec edit, so the new hash needs re-approval)';
   /** MONEY's levers (PRD v1.46 §2), the same three shapes the wall's are, because a
    * money cut is the same KIND of stop: the run is out of an operator-owned
    * allowance, not out of capability, and the last verdict rendered stands. hamr's
@@ -1310,12 +1597,12 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
    * hash, so raising it is a new spec version somebody signs — the library only ever
    * names the lever, and never adjusts a budget itself (the permanent hard line). */
   const MONEY_OPTIONS = [
-    'top up budgetUsd and rerun with --resume (resume-to-cap; a spec edit, so the new hash needs re-approval)',
+    resumeToCapNote,
     'revise the goal/spec so the work fits the budget (same re-approval)',
     'abandon the task',
   ];
 
-  const closeOpts = { timeoutMs: closeTimeoutMs, cwd: workdir };
+  const closeOpts = { timeoutMs: closeTimeoutMs, cwd: workdir, closeDir };
   /** D8 — the DECLARED close's seed, filled in below before anything runs.
    * `null` for a command close, which has no baseline to measure against. */
   /** @type {{seedRef: string}|null} */
@@ -1329,7 +1616,7 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
    * The command path is byte-identical to what it was: same call, same options.
    * @param {any[]} stages
    */
-  const runCloseStages = (stages) => (declared
+  const runCloseStagesInner = (stages) => (declared
     ? runDeclaredStages(stages, scrub, {
       ...closeOpts,
       seedRef: /** @type {any} */ (declaredCtx).seedRef,
@@ -1346,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,
@@ -1359,6 +1653,34 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
       }),
     })
     : runStages(stages, scrub, closeOpts));
+  /**
+   * PRD item 27/M2 — the re-verify that runs before EVERY close run, precheck
+   * included: `runCloseStagesInner` is the ONE seam every close execution in
+   * this runner goes through (the precheck's `judgeClose`, the preflight
+   * loop, the check-passes seam, and the close-fix loop via its own `judge`
+   * seam), so wrapping it here covers all of them without threading a
+   * verify call through each call site separately — the same reasoning
+   * `checkCloseAbsolutePaths`'s run-start placement already relies on (W4:
+   * "the staging itself lives in ONE place").
+   *
+   * A mismatch never reaches the executor: it returns a `close-tampered`
+   * verdict in the SAME shape `runClose`/`runStages` render (`{verdict,
+   * stage, detail}`), so every downstream reader that already keys off
+   * `Object.hasOwn(CLOSE_FAULTS, v.verdict)` (the precheck, the preflight
+   * loop, the post-fix read, and ralph's own judge-fault routing) treats it
+   * exactly like `crashed`/`timed-out`/`killed` — a forbidden-zone outcome,
+   * never retried, never fed back as a gap.
+   * @param {any[]} stages
+   */
+  const runCloseStages = async (stages) => {
+    const sig = checkStageByteSignature(stages, workdir);
+    if (!sig.ok) {
+      const r = sig.reds[0];
+      const detail = sig.reds.map((rr) => `${rr.stage}: expected ${rr.expected.slice(0, 12)}… got ${rr.actual ? `${rr.actual.slice(0, 12)}…` : '<unreadable>'}`).join('; ');
+      return { verdict: 'close-tampered', stage: r?.stage, detail };
+    }
+    return runCloseStagesInner(stages);
+  };
   /** @type {string|undefined} the stage that rendered the LAST close verdict (Layer R's red-set source) */
   let closeStage;
   /** @type {any} the LAST close verdict itself (W-2). A wall stop KEEPS the grade
@@ -2253,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:
@@ -2295,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
@@ -2316,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
@@ -2368,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;
       }
@@ -2415,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') {
@@ -3462,7 +3806,9 @@ 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)',
-            'top up budgetUsd and rerun with --resume, if the trend above says it was still converging',
+            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',
             'abandon the task',
           ],
         };
@@ -3576,7 +3922,7 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
       // is not passed — it survives only inside the governor, as the bound for the
       // case the trend instrument is blind.
       middle, judge: async () => judgeClose(), ladder: fixGovernor, emit: emitL, redact: scrub,
-      closeTimeoutMs, cwd: workdir, workerWrites: w.workerWrites,
+      closeTimeoutMs, cwd: workdir, workerWrites: w.workerWrites, closeDir,
     });
   } catch (e) {
     planExecuted();