bareloop 0.5.1 → 0.7.0

package/src/ralph.js

@@ -4,7 +4,153 @@
 // arbiter). Stateless across runs and stdlib-only by design: it must stay too
 // dumb to be gamed. Do not make it smarter.
 
-import { spawnSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
+
+// ── the close's child process, run WITHOUT freezing the host (F68) ───────────
+// The close used to run through `spawnSync`, which blocks the host event loop for
+// the child's entire duration: F68 measured 9 loop-freeze records in one green run
+// (worst 74.3s, bracketing a ~65s close exactly) and 4 more bracketing three
+// check-preflights — "the close-runner freezes the loop it reports to". While a
+// close ran, the stall fuse's timers could not fire, the lag sampler recorded a
+// block, and any in-flight instrument shared the freeze.
+//
+// ONLY THE WAIT IS ASYNC. Every observable semantic below is spawnSync's own,
+// replicated field for field, because the close is the arbiter and its reading of
+// the world must not shift by a byte:
+//   - the same `{error, status, signal, stdout, stderr}` result shape;
+//   - the same 1 MiB PER-STREAM output ceiling, reported the same way spawnSync
+//     reports it — an `ENOBUFS` error with the child killed (so an over-long close
+//     stays `failed`/broken-close, exactly as before, rather than silently
+//     becoming a red on truncated output);
+//   - the same deadline behaviour: SIGTERM at `timeoutMs`, surfaced as an
+//     `ETIMEDOUT` error (which runClose reads BEFORE any exit code, so the
+//     forbidden zone's `timed-out` band is unchanged);
+//   - the same stdin: closed immediately, so a close that reads stdin sees EOF
+//     instead of hanging on a pipe nobody will ever write to.
+// The one deliberate difference is prose: a spawn fault names itself `spawn …`
+// rather than `spawnSync …` in its message, because that is now what happened.
+// Nothing parses that string (it rides out as an escalation `detail`).
+const CLOSE_MAX_BUFFER = 1024 * 1024; // spawnSync's default maxBuffer, per stream
+const CLOSE_KILL_SIGNAL = 'SIGTERM';  // spawnSync's default killSignal
+// SIGTERM is a REQUEST, and a close is free to refuse it — a runner installing its
+// own handler, a wrapper that traps to clean up. There is no second deadline after
+// the first, so a refused SIGTERM leaves the wait below pending FOREVER: no `close`
+// event ever arrives, and the run's only remaining stop is the out-of-process
+// watchdog. The grace is the escalation — long enough for an honest close to flush
+// and leave on its own terms, then SIGKILL, which nothing can refuse. Verdict
+// semantics are untouched: the FIRST fault already named the outcome, and the kill
+// only enforces it. (spawnSync sends killSignal and then simply keeps waiting; this
+// is the one place the arbiter's clock is deliberately harder than its reference.)
+const CLOSE_KILL_GRACE_MS = 2000;
+
+/**
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {{env: NodeJS.ProcessEnv, cwd?: string, timeoutMs?: number}} o
+ * @returns {Promise<{error: (Error & {code?: string})|null, status: number|null, signal: string|null, stdout: string, stderr: string}>}
+ */
+function spawnClose(cmd, args, { env, cwd, timeoutMs }) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { env, cwd });
+    /** @type {Buffer[]} */ const outChunks = [];
+    /** @type {Buffer[]} */ const errChunks = [];
+    let outBytes = 0, errBytes = 0;
+    /** @type {(Error & {code?: string})|null} */
+    let error = null;
+    /** @type {NodeJS.Timeout|undefined} */
+    let timer;
+    /** @type {NodeJS.Timeout|undefined} */
+    let killTimer;
+
+    // The FIRST fault wins and kills the child, exactly as spawnSync does: a close
+    // that blew the buffer and then hit the deadline is one story, not two. The
+    // escalation rides inside that same first-fault-wins guard, so a child is asked
+    // once and, if it refuses, ended once.
+    const fault = (/** @type {string} */ code) => {
+      if (error) return;
+      error = Object.assign(new Error(`spawn ${cmd} ${code}`), { code, syscall: `spawn ${cmd}`, path: cmd, spawnargs: args });
+      try { child.kill(CLOSE_KILL_SIGNAL); } catch { /* already gone — nothing to kill */ }
+      // …and SIGKILL if it is still there after the grace. `unref` so this timer can
+      // never hold the host's event loop open by itself (F68's whole point) — and it
+      // is cleared on `close`, so it cannot fire at a child that already left.
+      killTimer = setTimeout(() => { try { child.kill('SIGKILL'); } catch { /* gone in the meantime */ } }, CLOSE_KILL_GRACE_MS);
+      killTimer.unref();
+    };
+
+    child.stdout.on('data', (/** @type {Buffer} */ c) => { outBytes += c.length; outChunks.push(c); if (outBytes > CLOSE_MAX_BUFFER) fault('ENOBUFS'); });
+    child.stderr.on('data', (/** @type {Buffer} */ c) => { errBytes += c.length; errChunks.push(c); if (errBytes > CLOSE_MAX_BUFFER) fault('ENOBUFS'); });
+    // A spawn failure (ENOENT, an unreadable cwd) arrives as an event here and as
+    // `result.error` in spawnSync; `close` still fires after it, so there is ONE
+    // resolution path and the promise can never be left pending.
+    child.on('error', (e) => { if (!error) error = e; });
+    child.on('close', (status, signal) => {
+      clearTimeout(timer);
+      clearTimeout(killTimer);
+      resolve({
+        error, status, signal,
+        // Concat-then-decode, never per-chunk: a multi-byte character straddling a
+        // chunk boundary must not become two replacement characters — spawnSync
+        // decodes the whole buffer once, and the judged/gapKeep patterns read this.
+        stdout: Buffer.concat(outChunks).toString('utf8'),
+        stderr: Buffer.concat(errChunks).toString('utf8'),
+      });
+    });
+    if (typeof timeoutMs === 'number' && timeoutMs > 0 && Number.isFinite(timeoutMs)) timer = setTimeout(() => fault('ETIMEDOUT'), timeoutMs);
+    // stdin closed at once (spawnSync with no `input` hands the child EOF): a close
+    // that reads stdin gets the same EOF instead of blocking on an idle pipe. The
+    // error swallow is for the ordinary case where the child has already exited.
+    child.stdin?.on('error', () => {});
+    child.stdin?.end();
+  });
+}
+
+/**
+ * What the close child must NOT be able to read (operator ruling, 2026-07-31:
+ * "strip it when unnecessary, minimize unneeded exposure").
+ *
+ * The close child executes WORKER-AUTHORED CODE. `pytest`, `npm test`, `tsc`
+ * run whatever the worker just wrote into the tree, in a child that — before
+ * this — inherited the whole operator environment, credentials included. None
+ * of git/npm/tsc/pytest/mypy needs an API key to judge a tree, so the exposure
+ * bought nothing and is removed. This is EXPOSURE REDUCTION, not a sandbox:
+ * see the threat-model note in the PRD (v1.41) and README for what remains.
+ *
+ * Two rules, deliberately kept BOTH ways round:
+ *  - `names` / `prefixes` — the knowns. A literal denylist is a chase (every
+ *    new provider mints a new variable), so it is not load-bearing on its own;
+ *    it exists for names the shape rule STRUCTURALLY cannot see — either no
+ *    `_`-bounded credential suffix at all (`AWS_ACCESS_KEY_ID`, `PGPASSWORD`,
+ *    `MYSQL_PWD`), a `*_KEY` that is not `*_API_KEY` (`SSH_PRIVATE_KEY`), or a
+ *    BARE spelling with nothing in front of the suffix (`TOKEN`, `SECRET`).
+ *    Names are matched EXACTLY, which is what keeps connection config out of
+ *    the strip (`PGHOST`, `SECRETS_DIR`, `TOKENIZERS_PARALLELISM` all survive).
+ *  - `shape` — the NAME-SHAPE rule, which is what bounds the chase: anything
+ *    whose name ends in the credential suffixes goes, whoever minted it and
+ *    whether or not anyone here has heard of it. Case-insensitive; no `g` flag,
+ *    so `.test` stays stateless and safe to reuse across every key.
+ *
+ * It is arbiter territory like the rest of this file: no drafted plan or config
+ * can express, widen, or opt out of it.
+ * @type {Readonly<{names: readonly string[], prefixes: readonly string[], shape: RegExp}>}
+ */
+export const CLOSE_ENV_DENY = Object.freeze({
+  names: Object.freeze([
+    // provider keys
+    'ANTHROPIC_API_KEY', 'OPENAI_API_KEY', 'GEMINI_API_KEY', 'GOOGLE_API_KEY',
+    'ANTHROPIC_AUTH_TOKEN', 'GITHUB_TOKEN', 'GH_TOKEN', 'NPM_TOKEN',
+    // credential spellings the shape rule structurally cannot see, because their
+    // names carry no `_`-bounded suffix (operator ruling 2026-07-31, "add", on a
+    // delta-review finding that MEASURED every one of these reaching the child).
+    // Documented tools' own variables, not invented ones:
+    'PGPASSWORD', 'PGPASSFILE', 'PGSSLKEY',   // libpq (`PGPASS` is NOT a libpq variable — the FILE is ~/.pgpass, named by PGPASSFILE)
+    'MYSQL_PWD', 'REDISCLI_AUTH',             // mysql client, redis-cli
+    'STRIPE_KEY', 'STRIPE_SECRET_KEY',        // `*_KEY` is not `*_API_KEY`: the shape rule misses it
+    'SSH_PRIVATE_KEY', 'PRIVATE_KEY', 'SECRET_KEY',
+    'TOKEN', 'SECRET', 'API_KEY', 'PASSWORD', 'PASSWD', // the bare spellings; a suffix rule needs a prefix to bound
+  ]),
+  prefixes: Object.freeze(['AWS_']),
+  shape: /(_API_KEY|_SECRET|_TOKEN|_PASSWORD|_CREDENTIALS?)$/i,
+});
 
 /**
  * Run a close command; its exit code is the verdict (hard green, PRD §4).
@@ -68,18 +214,26 @@ import { spawnSync } from 'node:child_process';
  *   (the workdir — the tree it is judging), the exit code the SIGNED spec calls
  *   success, the judgment-rendered signal, and the kept-failures pattern. All
  *   five are arbiter territory: the drafted workflow config cannot express any.
- * @returns {{verdict: 'satisfied'|'needs_revision'|'failed'|'timed-out'|'killed'|'crashed',
+ * @returns {Promise<{verdict: 'satisfied'|'needs_revision'|'failed'|'timed-out'|'killed'|'crashed',
  *   gap?: string, exitCode?: number, signal?: string, detail?: string,
- *   judgedCount?: number|null, unaudited?: boolean}}
+ *   judgedCount?: number|null, unaudited?: boolean}>}
  */
-export function runClose(close, redact = (s) => s, { timeoutMs = 120_000, cwd, expect = 0, judged, gapKeep } = {}) {
+export async function runClose(close, redact = (s) => s, { timeoutMs = 120_000, cwd, expect = 0, judged, gapKeep } = {}) {
   const env = { ...process.env };
   delete env.NODE_TEST_CONTEXT; // a `node --test` close inherits this from a test runner and silently no-ops — a fake green
-  const r = spawnSync(close[0], close.slice(1), { env, cwd, encoding: 'utf8', timeout: timeoutMs });
+  // …and the operator's credentials go with it (CLOSE_ENV_DENY above). A COPY is
+  // stripped, never `process.env` itself: the host still needs its key (bare-agent
+  // reads it every round) — only the child that runs worker-authored code is blinded.
+  for (const name of Object.keys(env)) {
+    if (CLOSE_ENV_DENY.names.includes(name)
+      || CLOSE_ENV_DENY.prefixes.some((p) => name.startsWith(p))
+      || CLOSE_ENV_DENY.shape.test(name)) delete env[name];
+  }
+  const r = await spawnClose(close[0], close.slice(1), { env, cwd, timeoutMs });
 
   // ── forbidden zone, before any exit code is believed ──────────────────────
   if (r.error) {
-    // spawnSync reports BOTH "cannot run" and "ran too long" through `error`;
+    // The runner reports BOTH "cannot run" and "ran too long" through `error`;
     // they are different human decisions, so they get different names.
     const code = /** @type {NodeJS.ErrnoException} */ (r.error).code;
     if (code === 'ETIMEDOUT') return { verdict: 'timed-out', detail: `close exceeded ${timeoutMs}ms and was killed — it never finished judging` };
@@ -131,6 +285,56 @@ export function runClose(close, redact = (s) => s, { timeoutMs = 120_000, cwd, e
   };
 }
 
+/**
+ * Run a STAGED close (PRD v1.28) — an ordered list of named command stages, run
+ * in order until one renders a verdict that is not `satisfied`. The return is
+ * runClose's own shape, so every consumer (the precheck, ralph's judge, the
+ * escalation's CLOSE_FAULTS routing) is unchanged: a staged close is still ONE
+ * verdict, not a scoreboard.
+ *
+ * Two additions, both mechanical information the worker can act on:
+ *  - `stage` names which stage rendered the verdict. The close's output must
+ *    never name the CULPRIT FILE (v1.12/F28 — the worker finds that itself), and
+ *    naming the wall it hit is the opposite of that: it is the mechanical genre
+ *    that converts (F38/F46), not the answer.
+ *  - `stages` is the ordered record of what actually ran. A stage after the
+ *    first red never runs, so a later green can never mask an earlier failure.
+ *
+ * The same function runs a DERIVED CHECK: a check is its stage's chain
+ * (`checkMenu` puts the prerequisites first), so there is one execution path for
+ * the close and for the rulers derived from it — never two, which is the F9
+ * two-transforms class applied to the arbiter.
+ *
+ * @param {any[]} stages the stage list (already validated by validateJob)
+ * @param {(s: string) => string} [redact] scrub, applied at capture on EVERY stage
+ * @param {{timeoutMs?: number, cwd?: string}} [opts]
+ * @returns {Promise<any>} runClose's verdict shape, plus `stage` and `stages`
+ */
+export async function runStages(stages, redact = (s) => s, { timeoutMs, cwd } = {}) {
+  const ran = [];
+  let last;
+  for (const st of stages) {
+    // Sequential by construction (F68): stages run one at a time under a single
+    // await, so nothing here ever has two closes in flight against one tree.
+    const r = await runClose(st.cmd.trim().split(/\s+/), redact, {
+      timeoutMs, cwd, expect: st.expect, judged: st.judged, gapKeep: st.gapKeep,
+    });
+    ran.push({ name: st.name, verdict: r.verdict, ...(r.exitCode !== undefined ? { exitCode: r.exitCode } : {}) });
+    last = r;
+    if (r.verdict !== 'satisfied') {
+      return {
+        ...r,
+        stage: st.name,
+        stages: ran,
+        // The gap says WHICH wall, then the wall's own output. A worker handed
+        // three stages' worth of output cannot tell which one it must satisfy.
+        ...(r.gap ? { gap: `close stage "${st.name}" failed:\n${r.gap}` } : {}),
+      };
+    }
+  }
+  return { ...last, stages: ran };
+}
+
 // Tail-biased bound: a test runner's useful output (the assertion diff, the
 // failing case name) is at the END; head-only truncation fed the worker the
 // preamble and dropped the cause (N2 queue, F2). Head sample kept so "what ran"
@@ -219,6 +423,27 @@ export const CLOSE_FAULTS = Object.freeze({
   },
 });
 
+/**
+ * The exhaustion-by-PROGRESS seam, as a contract rather than "whatever one module
+ * happens to return". Two governors implement it and they read different signals —
+ * the step ladder's repeats-and-writes (src/ladder.js) and the close-fix loop's
+ * per-stage graded numbers (src/trend.js) — which is the whole reason ralph takes an
+ * interface here and interprets nothing itself.
+ *
+ * `record` returns the governor's own reading, which ralph emits verbatim and never
+ * inspects; each reading names its `governor` so two instruments under one spine type
+ * can never be averaged into one number. `report` is the only shape ralph itself
+ * reads. `terminal` is optional and overrides the exhaustion PROSE only — never the
+ * category, never the outcome.
+ *
+ * @typedef {object} LoopGovernor
+ * @property {(o: {iteration: number, gap?: string}) => object} record
+ * @property {() => boolean} struckOut
+ * @property {() => {strikes: number, limit: number, iterations: number, distinctGaps?: number}} report
+ * @property {() => string} brief
+ * @property {() => {decision: string, options: string[]}} [terminal]
+ */
+
 /**
  * The loop: `while close-red and under-cap: run the middle`. Stops at first
  * green (within-run tuning past a visible close is the fit-to-pass surface,
@@ -244,7 +469,28 @@ export const CLOSE_FAULTS = Object.freeze({
  *   zone, worker-crash routing (F32), and the cap taxonomy apply unchanged.
  *   Injected by run.js only; inexpressible in any config or plan — the agent
  *   never authors its judge any more than its close.
- * @param {number} opts.capRuns budget: max middle runs
+ * @param {number} [opts.capRuns] budget: max middle runs. Required UNLESS `ladder`
+ *   is supplied — the two exhaustion rules are alternatives, never both at once.
+ *   The "unless" is ENFORCED at entry (a param guard that throws), not merely
+ *   documented: an optional-in-the-contract bound with nothing checking it made a
+ *   loop that never ran report a governance stop that never happened.
+ * @param {LoopGovernor} [opts.ladder]
+ *   the PROGRESS governor (src/ladder.js) that replaces the fixed count for a plan
+ *   STEP's micro-loop. With it, the loop is bounded by strikes rather than by a
+ *   number of runs: iterations float, and money, the wall, the variance meter and
+ *   the stall fuse keep every bit of their current authority (each still ends the
+ *   loop through the middle's own throw). Ralph still interprets nothing — it hands
+ *   the ladder the iteration's gap and reads back a boolean.
+ *
+ *   The CLOSE-FIX loop now supplies one too (PRD v1.46 §4, once its own $0 replay
+ *   over all 8 archived fix loops came back clean: 0 greens harmed, 1 waste case
+ *   caught). Its governor reads a different signal — the close's own per-stage
+ *   graded numbers (src/trend.js), not repeats and writes — which is exactly why
+ *   this is a SEAM and not a hard-coded rule: ralph still interprets nothing.
+ *   An optional `terminal()` on the governor overrides the exhaustion prose, because
+ *   the step ladder's copy offers the human a replan and there is no planner at the
+ *   close. The category and the outcome are NOT overridable: one exhaustion terminal,
+ *   two triggers.
  * @param {(type: string, data?: object) => object} opts.emit a spine emitter
  * @param {(s: string) => string} [opts.redact] source scrubber for close output
  *   (secrets never enter the spine); injected so the shell stays stdlib-only
@@ -263,8 +509,30 @@ export const CLOSE_FAULTS = Object.freeze({
  *   with zero writes, a crash stays what it always was: an instrument stop.
  * @returns {Promise<'green'|'escalated'>}
  */
-export async function ralph({ middle, close, judge, capRuns, emit, redact, closeTimeoutMs, cwd, expect, judged, gapKeep, workerWrites }) {
-  emit('run-start', { capRuns, close: judge ? 'judge:injected' : /** @type {string[]} */ (close).join(' ') });
+export async function ralph({ middle, close, judge, capRuns, ladder, emit, redact, closeTimeoutMs, cwd, expect, judged, gapKeep, workerWrites }) {
+  // PARAM GUARD (the BA-4 class — a caller's malformed argument, which is the one
+  // thing this shell throws for; a WORKER's bad reach comes back as a refusal
+  // RESULT instead, and that rule is about feedback, not about the API contract).
+  // `capRuns` became optional in this signature when `ladder` arrived, and nothing
+  // enforced the "unless". MEASURED with neither supplied: `1 <= undefined` is
+  // false, so the middle ran 0 times and ralph still emitted `cap-halt` and an
+  // escalation reading `undefined/undefined runs spent, close still red` — a
+  // governance stop narrated for a run that never happened, on the public export.
+  // A bound that reports halting a loop it never entered is exactly the
+  // blind-instrument class this repo keeps paying for, so the malformed call dies
+  // at the door instead of minting a record. The message names BOTH alternatives:
+  // either one repairs the call, and naming one would send the caller to the wrong
+  // repair.
+  if (!ladder && !(Number.isInteger(capRuns) && /** @type {number} */ (capRuns) > 0)) {
+    // quoted only for a string, so `"3"` reads as the type error it is while
+    // `NaN`/`undefined` read as themselves (JSON.stringify renders both as a lie)
+    const got = typeof capRuns === 'string' ? JSON.stringify(capRuns) : String(capRuns);
+    throw new Error(`ralph: capRuns must be a positive integer (got ${got}) unless a \`ladder\` governor is supplied — they are alternative exhaustion rules and a loop with neither cannot stop honestly`);
+  }
+  emit('run-start', {
+    ...(ladder ? { strikeLimit: ladder.report().limit } : { capRuns }),
+    close: judge ? 'judge:injected' : /** @type {string[]} */ (close).join(' '),
+  });
   // The blind spot is NAMED, never hidden: with no judgment-rendered signal this
   // close cannot tell a crash from an honest red (they are byte-identical at the
   // exit-code seam), so the record says so out loud rather than passing the exit
@@ -274,7 +542,22 @@ export async function ralph({ middle, close, judge, capRuns, emit, redact, close
   if (!judged && !judge) emit('close-unaudited', { close: /** @type {string[]} */ (close).join(' '), meaning: 'no judgment-rendered signal declared — a crash-at-load is indistinguishable from an honest red for this close' });
   const verdicts = [];
   let gap;
-  for (let iteration = 1; iteration <= capRuns; iteration++) {
+  // ONE exhaustion terminal, two triggers — the same three records in the same
+  // order either way, so the count path and the ladder path cannot drift into
+  // reporting the stop differently. The CATEGORY is `cap-halt` for both, and
+  // deliberately: downstream counts escalation categories against an executable
+  // excluded-set (ledger.js), and the step loop routes its ONE replan off exactly
+  // this name. Only the trigger changed; the taxonomy did not.
+  /** @param {number} iteration @param {object} halt @param {object} spend @param {string} decision @param {string[]} options */
+  const exhausted = (iteration, halt, spend, decision, options) => {
+    emit('cap-halt', { category: 'cap-halt', meaning: 'not under cap — not "can\'t"', ...halt });
+    emit('escalation', { category: 'cap-halt', decisionReady: true, verdicts, spend, decision, options });
+    emit('run-end', { outcome: 'escalated', iterations: iteration });
+    return /** @type {'escalated'} */ ('escalated');
+  };
+  // With a ladder the count is not the bound: the loop runs until the ladder strikes
+  // out, or until the middle throws (money, wall, variance, stall — all unchanged).
+  for (let iteration = 1; ladder || iteration <= /** @type {number} */ (capRuns); iteration++) {
     emit('iteration-start', { iteration });
     try {
       await middle(iteration, gap);
@@ -289,6 +572,36 @@ export async function ralph({ middle, close, judge, capRuns, emit, redact, close
           ['widen the write scope deliberately', 'change the middle/harness', 'abandon the task']],
         'provider-red': ['The provider path failed mid-run (transport, not logic) — no verdict exists and the spend for the failed call is unknown (F6).',
           ['retry the run', 'fix the provider binding', 'abandon the task']],
+        // A (PRD v1.27) — the METER stopped this attempt before it started: the
+        // step had already eaten a declared share of the run with its exits
+        // unmoved. Not a fault, not a cap: the caller reads this category and
+        // REPLANS, so the message must not say anything broke.
+        'step-variance': ['A step consumed a large share of the run with its exits still red — the meter stopped it before another attempt.',
+          ['let the planner re-allocate what is left (replan)', 'raise the budget and rerun', 'abandon the task']],
+        // T/F64 — the run's WALL CLOCK stopped this: either the caller's deadline
+        // came back as the provider's own timeout (F64, mid-attempt) or the caller
+        // read the clock and declined to START another attempt (W-2, between them).
+        // A governance stop either way, not a fault and not a transport casualty:
+        // the message must not send a human to debug a socket, and the remedy is the
+        // operator's cap, not a retry. The wording says neither "mid-attempt" nor
+        // "between attempts", because one entry serves both and a category that
+        // narrates the wrong half is worse than one that narrates neither.
+        // The two levers are BOTH spec edits (a changed spec hash the runner refuses
+        // until it is re-approved), and they point opposite ways — which is why the
+        // caller's detail carries the progress trend that says which one fits.
+        'wall-halt': ['The run reached its wall-clock cap — time ran out, not capability. Nothing is discarded: the last verdict rendered stands, and the stop is the checkpoint.',
+          ['raise maxWallMs and rerun (resume-to-cap; a spec edit, so the new hash needs re-approval)',
+            'revise the goal/spec so the work fits the time (same re-approval)',
+            'abandon the task']],
+        // F66 — the STALL WATCHDOG gave up: no round completed for the stall window,
+        // three times over, and reissuing the call did not recover it. It borrows both
+        // siblings' rules. Like `step-variance`, the caller reads this category and
+        // REPLANS, so the planner's lever leads. Like `wall-halt`, nothing broke — the
+        // socket stayed alive the whole time (that is the measured mechanism), so the
+        // message must not send a human to debug transport, and the default's "fix the
+        // interpreter" would aim a human at the one component that did nothing wrong.
+        'step-stalled': ['The model stopped producing rounds and reissuing the call did not recover it — a stall, not a fault.',
+          ['let the planner re-allocate what is left (replan)', 'retry the run', 'check provider status', 'abandon the task']],
       };
       // Object.hasOwn, not bare lookup: a category named after an
       // Object.prototype member ("toString") would return the inherited
@@ -311,7 +624,7 @@ export async function ralph({ middle, close, judge, capRuns, emit, redact, close
     emit('middle-done', { iteration });
     const v = judge
       ? await judge()
-      : runClose(/** @type {string[]} */ (close), redact, { timeoutMs: closeTimeoutMs ?? 120_000, cwd, expect, judged, gapKeep });
+      : await runClose(/** @type {string[]} */ (close), redact, { timeoutMs: closeTimeoutMs ?? 120_000, cwd, expect, judged, gapKeep });
     // Worker-crash attribution (F32, measured in F31: 4 of 7 battery rows). A crash is
     // still not a verdict (F17) — but a crash that FOLLOWS worker writes, on a run whose
     // precheck proved the close judged at baseline (run.js escalates a crash-at-precheck
@@ -335,30 +648,56 @@ export async function ralph({ middle, close, judge, capRuns, emit, redact, close
       gap = `Your edit CRASHED the test suite — it can no longer even load and judge (${v.detail}). `
         + `Files you have written this run: ${shown.join(', ')}${more > 0 ? ` (and ${more} more)` : ''}. `
         + 'Fix or revert your change so the suite can run again — nothing can pass while the suite cannot load.';
-      continue;
+    } else {
+      // Forbidden zone: no judgment was rendered, so there is no verdict. Escalate
+      // by the outcome's OWN name and never retry — retrying a broken arbiter is
+      // the §5b violation adaptlearn found live in its shipped shell (F25/Z-3).
+      const fault = Object.hasOwn(CLOSE_FAULTS, v.verdict) ? CLOSE_FAULTS[v.verdict] : undefined;
+      if (fault) {
+        emit('escalation', {
+          category: fault.category, decisionReady: true, verdicts,
+          spend: { runs: iteration, capRuns },
+          decision: fault.decision, options: fault.options, detail: v.detail,
+        });
+        emit('run-end', { outcome: 'escalated', iterations: iteration });
+        return 'escalated';
+      }
+      gap = v.gap; // feedback for the next middle run; the shell itself learns nothing
     }
-    // Forbidden zone: no judgment was rendered, so there is no verdict. Escalate
-    // by the outcome's OWN name and never retry — retrying a broken arbiter is
-    // the §5b violation adaptlearn found live in its shipped shell (F25/Z-3).
-    const fault = Object.hasOwn(CLOSE_FAULTS, v.verdict) ? CLOSE_FAULTS[v.verdict] : undefined;
-    if (fault) {
-      emit('escalation', {
-        category: fault.category, decisionReady: true, verdicts,
-        spend: { runs: iteration, capRuns },
-        decision: fault.decision, options: fault.options, detail: v.detail,
-      });
-      emit('run-end', { outcome: 'escalated', iterations: iteration });
-      return 'escalated';
+    // ── the ladder reads THIS red iteration, whichever gap it ended up with (a
+    // worker-crash gap is feedback the attempt really received, so it is a reading
+    // like any other). ONE call site, after both branches have settled `gap`: two
+    // would let a future branch quietly opt out of the bound.
+    if (ladder) {
+      const r = ladder.record({ iteration, gap });
+      emit('ladder', r);
+      if (ladder.struckOut()) {
+        const rep = ladder.report();
+        // The governor may name its own decision/options; it may NOT name its own
+        // category or outcome. A stop is spelled the same either way (`cap-halt`,
+        // 'escalated') because downstream counts categories against an executable
+        // excluded-set — only the PROSE a human reads is governor-specific.
+        const term = typeof ladder.terminal === 'function' ? ladder.terminal() : null;
+        return exhausted(iteration,
+          {
+            strikes: rep.strikes,
+            strikeLimit: rep.limit,
+            iterations: rep.iterations,
+            ...(rep.distinctGaps === undefined ? {} : { distinctGaps: rep.distinctGaps }),
+          },
+          { runs: iteration, strikes: rep.strikes, strikeLimit: rep.limit },
+          term?.decision ?? `${rep.strikes}/${rep.limit} strikes — the step stopped making progress. ${ladder.brief()} Continue, change approach, or stop?`,
+          term?.options ?? ['let the planner re-allocate what is left (replan)', 'change approach', 'abandon the task']);
+      }
     }
-    gap = v.gap; // feedback for the next middle run; the shell itself learns nothing
   }
-  emit('cap-halt', { category: 'cap-halt', meaning: 'not under cap — not "can\'t"', capRuns });
-  emit('escalation', {
-    category: 'cap-halt', decisionReady: true, verdicts,
-    spend: { runs: capRuns, capRuns },
-    decision: `${capRuns}/${capRuns} runs spent, close still red. Continue, change approach, or stop?`,
-    options: ['raise the cap and rerun', 'change the middle/harness', 'abandon the task'],
-  });
-  emit('run-end', { outcome: 'escalated', iterations: capRuns });
-  return 'escalated';
+  // The FIXED-COUNT exhaustion, reached only without a ladder. Both callers inside this
+  // package now supply one (the step loop's `createLadder`, the close-fix loop's
+  // progress governor), so the only route left is the public export — kept because it IS
+  // the public export, and because a `capRuns` bound with no reachable exhaustion would
+  // be a bound in name only.
+  const spent = /** @type {number} */ (capRuns);
+  return exhausted(spent, { capRuns }, { runs: spent, capRuns },
+    `${spent}/${spent} runs spent, close still red. Continue, change approach, or stop?`,
+    ['raise the cap and rerun', 'change the middle/harness', 'abandon the task']);
 }