bareloop 0.6.0 → 0.7.0

package/types/clock.d.ts

@@ -20,6 +20,14 @@
  * the same (raise `maxWallMs`), and the alternative — calling a governance stop
  * transport on the chance that it was — is the failure this closes.
  *
+ * BOTH derived bounds land here, because both are derived from the same wall:
+ * BA-18's idle timeout (`callTimeoutMs`) and BA-19's total-duration deadline
+ * (`callDeadlineMs`). Adding the second CODE does not widen the rule — the
+ * discriminator is still `clock.expired()`, never the code. That matters for the
+ * deadline specifically: a provider someone else constructed with its own
+ * `deadlineMs` could throw this code on a run with time left, and that is transport,
+ * exactly as it was before.
+ *
  * @param {any} err the throw as caught
  * @param {Clock} clock the run's clock
  * @returns {boolean}
@@ -35,22 +43,25 @@ export function isWallTimeout(err: any, clock: Clock): boolean;
  * @property {() => boolean} expired whether the deadline has passed (always false when unbounded)
  * @property {(closeTimeoutMs: number) => number|null} enforcedMs the HONEST worst case
  * @property {(providerDefaultMs?: number) => number} callTimeoutMs the derived per-call bound
+ * @property {() => number|null} callDeadlineMs the derived per-call TOTAL-duration ceiling; `null` when unbounded
  * @property {(closeTimeoutMs: number) => object} report one spine-safe shape carrying both numbers
  */
 /**
  * Start a wall clock for one run.
- * @param {{ maxWallMs?: number|null, closeStages?: number, now?: () => number }} [opts]
+ * @param {{ maxWallMs?: number|null, closeStages?: number, now?: () => number, priorElapsedMs?: number }} [opts]
  *   `maxWallMs`: the signed operator cap, or absent/null for an honestly unbounded
  *   run. `closeStages`: how many stages the job's close runs (W5) — each one gets
  *   the FULL `closeTimeoutMs`, so this is the multiplier on the overshoot, not a
  *   decoration. Defaults to 1, the single-predicate close. `now`: injected for
- *   tests — the default is the real clock.
+ *   tests — the default is the real clock. `priorElapsedMs`: time this attempt's
+ *   PREDECESSOR already consumed (see below).
  * @returns {Clock}
  */
-export function createClock({ maxWallMs, closeStages, now }?: {
+export function createClock({ maxWallMs, closeStages, now, priorElapsedMs }?: {
     maxWallMs?: number | null;
     closeStages?: number;
     now?: () => number;
+    priorElapsedMs?: number;
 }): Clock;
 /** BA-18's default request/idle timeout (`AnthropicProvider.timeoutMs`), the
  * ceiling every derived per-call timeout starts from. Kept in sync deliberately:
@@ -69,6 +80,13 @@ export const MIN_CALL_TIMEOUT_MS: 30000;
  * `category`, so every consumer that defaults an uncategorised throw would file
  * it as transport. */
 export const TIMEOUT_CODE: "ETIMEDOUT";
+/** bare-agent's rejection code when its TOTAL-duration deadline trips (BA-19,
+ * `provider-http.js` → `applyRequestDeadline`). A DIFFERENT code from the idle
+ * bound's on purpose — upstream splits them precisely so a consumer routing
+ * governance stops apart from transport casualties can tell which timer fired. Like
+ * `TIMEOUT_CODE` it carries no `category`, so every default-to-transport catch site
+ * would file it as a casualty. */
+export const DEADLINE_CODE: "EDEADLINE";
 export type Clock = {
     /**
      * whether the operator set a cap at all
@@ -102,6 +120,10 @@ export type Clock = {
      * the derived per-call bound
      */
     callTimeoutMs: (providerDefaultMs?: number) => number;
+    /**
+     * the derived per-call TOTAL-duration ceiling; `null` when unbounded
+     */
+    callDeadlineMs: () => number | null;
     /**
      * one spine-safe shape carrying both numbers
      */

package/types/index.d.ts

@@ -6,4 +6,7 @@ export { globToPrefix, scanSecrets } from "./validate.js";
 export { validateJob, jobSpecHash, checkApproval, checkMenu, CLOSE_TYPES, CLASS_BY_CLOSE, GOLD_COMPARE, CADENCE_UNITS, PROVIDERS, CONDITION_KEYS, TOOL_MENU, LOCKED_TOOLS, STORE_VERBS, VERDICT_TYPES, LOCKED_VERDICTS } from "./job.js";
 export { validatePlan, stageClose, EXIT_TYPES, MAX_EXITS_PER_STEP, MAX_PLAN_STEPS, WRITE_VERBS } from "./plan.js";
 export { snapshotScope, evalExits } from "./exits.js";
+export { BRIDGE_SCHEMA, validateBridge, deriveStatus, listingRow, loadGate, mintBridge, appendGreen, appendRed, loadBridge, loadRegistry, saveBridge, makeRegistry, registryExists } from "./bridges.js";
+export { renderListing, selectionPrompt } from "./selection.js";
+export { validateEnvelope, resolveTrySpec, resolveReuse, reuseSpecHash, selectBridge, runReuse, REUSE_GRADED_RED, readResume, resumeTreeGate } from "./reuse.js";
 export { classifyIncidents, foldLedger, ledgerDeltas, updateLedger, LEDGER_CLASSES } from "./ledger.js";

package/types/ladder.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Normalize a gap for comparison. Deliberately NARROW: only bytes a re-run changes
+ * on its own are removed. Error COUNTS, file names and line numbers all survive —
+ * a trajectory like "30 errors" → "22 errors" must read as two different gaps, and
+ * a normalizer that scrubbed numbers would turn the converging case this module
+ * exists to protect into an instant strike.
+ * @param {string} text @returns {string}
+ */
+export function normalizeGap(text: string): string;
+/**
+ * The comparable key for a gap: the normalized text, hashed. Hashed rather than
+ * kept whole because the seen-set lives for the whole step and a close's output
+ * can be tens of KB — and because the set holds no content, nothing here can leak
+ * model or file bytes into a record.
+ * @param {string} text @returns {string}
+ */
+export function gapKey(text: string): string;
+/**
+ * Build one ladder. ONE PER STEP: the seen-set and the strike count are the step's
+ * own history, and a ladder shared across steps would strike a fresh step for a gap
+ * an earlier one had already seen.
+ *
+ * @param {object} opts
+ * @param {number} [opts.limit] strikes that end the step (default `STRIKE_LIMIT`)
+ * @param {() => number} opts.writeCount the CUMULATIVE count of the worker's
+ *   allow-decision write/edit records so far this step (planrun reads it off the
+ *   gate audit). Required, and a throw when it is missing rather than a silent
+ *   degradation to repeats-only: a strike rule running on one of its two signals
+ *   with nothing on the record saying so is the blind-instrument class, and this
+ *   is the BA-4 param-guard class where a throw is the right answer.
+ */
+export function createLadder({ limit, writeCount }: {
+    limit?: number | undefined;
+    writeCount: () => number;
+}): {
+    /**
+     * Read one RED iteration. Called by ralph after the judge has rendered a
+     * non-green, non-fault verdict — a green never reaches here, so every reading
+     * is a failing iteration by construction.
+     * @param {{iteration: number, gap?: string}} o
+     * @returns {{governor: string, iteration: number, strike: boolean, strikes: number,
+     *   limit: number, wrote: boolean, repeatOf: number|null, distinctGaps: number}}
+     */
+    record({ iteration, gap }: {
+        iteration: number;
+        gap?: string;
+    }): {
+        governor: string;
+        iteration: number;
+        strike: boolean;
+        strikes: number;
+        limit: number;
+        wrote: boolean;
+        repeatOf: number | null;
+        distinctGaps: number;
+    };
+    /** has the step run out of strikes? */
+    struckOut: () => boolean;
+    /** the ladder's own books — counts and iteration numbers, never gap content */
+    report: () => {
+        iterations: number;
+        strikes: number;
+        limit: number;
+        distinctGaps: number;
+        repeats: {
+            at: number;
+            firstAt: number;
+        }[];
+        idle: number[];
+    };
+    /**
+     * The mechanism, in one sentence, for the replan brief. It is the only channel
+     * the redrafting planner adapts to, so it states WHICH shape ended the step and
+     * the evidence for it — never a label on its own, and never a culprit file
+     * beyond what the close itself reported (F28): the inputs here are iteration
+     * numbers and counts, so naming one is inexpressible.
+     * @returns {string}
+     */
+    brief(): string;
+};
+/**
+ * The strike ceiling. Shell-owned, exactly where the fixed count was: the runner
+ * sets it, the agent cannot express it, and it is arbiter territory — a step's own
+ * plan may not tighten it and may not raise it. Two is hamr's number.
+ */
+export const STRIKE_LIMIT: 2;

package/types/plan.d.ts

@@ -90,7 +90,7 @@ export function stageClose(close: any): any[] | null;
  * job spec. Never throws on JSON text or plain parsed data; every failure is
  * a named red. Returns the parsed plan on ok (single parse), null on any red.
  * @param {object|string} input parsed plan, or raw JSON text (parse failures are a red)
- * @param {{ job?: any, maxStepRounds?: number, scopes?: string[], capRuns?: number }} [opts] `job`: the
+ * @param {{ job?: any, maxStepRounds?: number, scopes?: string[], seedRed?: string[], priorChecks?: string[] }} [opts] `job`: the
  *   validateJob-GREEN four-field spec (the ceiling, the fence, and the checks
  *   menu all come from it — a missing or non-plan-shape job fails CLOSED);
  *   `maxStepRounds`: the shell's per-step rounds ceiling (interpret's
@@ -98,13 +98,28 @@ export function stageClose(close: any): any[] | null;
  *   `scopes`: the offered `tree-changed` menu from `legalScopes` (the SAME array
  *   the drafting prompt enumerated). Omitted, it derives from the signed
  *   writeScope — never a free-text fallback (F50).
+ *
+ *   The two shape-lottery gate rules (2026-08-04) — both keyed on RECORDED
+ *   facts, never an LLM judgment of "is this job small", and both inactive
+ *   when their fact is omitted (resume/reuse callers stay byte-identical):
+ *   `seedRed`: check names whose PREFLIGHT verdict was needs_revision. Rule
+ *   A-v2 — a seed-red check is the goal itself, not a milestone; it may only
+ *   sit on the plan's FINAL write step (`check-placement`). The $0 archive
+ *   sweep: seed-red-check-on-an-early-step has 0 honest greens ever; the one
+ *   wide closing step greens 7/7. Green-at-seed checks stay free mid-plan
+ *   (the 20 TESTGEN mid-plan greens — a guard, not a goal).
+ *   `priorChecks`: the check names the PREDECESSOR plan carried (replan gate
+ *   only). Rule B — a redraft may not drop one (`check-shed`): exits without
+ *   the check verify FORM alone, so a shed lets the run "green" unearned
+ *   (u-msdsmkid mechanism b; the 3 archived sheds were all on step-red runs).
  * @returns {{ ok: boolean, reds: Red[], plan: object|null }}
  */
-export function validatePlan(input: object | string, { job, maxStepRounds, scopes, capRuns }?: {
+export function validatePlan(input: object | string, { job, maxStepRounds, scopes, seedRed, priorChecks }?: {
     job?: any;
     maxStepRounds?: number;
     scopes?: string[];
-    capRuns?: number;
+    seedRed?: string[];
+    priorChecks?: string[];
 }): {
     ok: boolean;
     reds: Red[];

package/types/planrun.d.ts

@@ -1,3 +1,21 @@
+/**
+ * Files named in an exit gap that the step's worker never wrote — the mechanical
+ * fact behind the prose-prohibition trap (u-msdpuaej, 2026-08-03): a drafter wrote
+ * "do not modify any file outside X" into a step whose exit check judges the whole
+ * goal, the worker obeyed, and the replanner — handed the gap AND the stall note —
+ * rebuilt the same shape, because inferring "the exit reds on files this step never
+ * touched" is exactly the semantic leap that fails (F38: mechanical gaps convert,
+ * semantic ones stall; 3/3 across the mailbox class). This computes that fact from
+ * the two books that already exist: path-like tokens in the gap text (extension
+ * required — a bare `step/two` is not a file claim) suffix-matched against the F32
+ * write audit's absolute paths. Advisory-only and fail-safe: extraction that finds
+ * nothing yields no line, never a guess.
+ *
+ * @param {string | undefined} gap the step's last exit gap text
+ * @param {string[] | undefined} writes the step's cumulative write-audit paths
+ * @returns {string[]} gap-named files with no matching write, in gap order
+ */
+export function gapFilesNeverWritten(gap: string | undefined, writes: string[] | undefined): string[];
 /**
  * The plan-drafting prompt: a schema DESCRIPTION built from the live validator
  * menus — never a copyable example (the drafter must author, not echo; the
@@ -13,16 +31,26 @@
  * @param {{ balanceUsd?: number|null, remainingMs?: number|null, progress?: string }} [materials]
  *   what the run has LEFT (T/A). Omitted → no materials block at all, which is the
  *   pre-T behaviour and keeps every existing caller byte-identical.
- * @param {number} [capRuns] the shell's attempt cap — the ceiling `attempts` may only
- *   TIGHTEN. Interpolated the way every sibling bound is: `validatePlan` reds outside
- *   `1..capRuns`, and a prompt that says only "integer" spends a round teaching it.
- *   Defaults to validatePlan's own default so existing callers are unchanged.
+ * @param {object|null} [startingDraft] Layer 3 (D4) — a loaded bridge's plan, handed over
+ *   as the draft to TWEAK. Omitted/null is the COLD path and renders byte-identically to
+ *   the pre-Layer-3 prompt: the block is additive, never surgery on the prompt's interior,
+ *   so the two paths cannot drift (the F47 works-both-ways rule). Only the runner passes
+ *   it, and only for the FIRST draft phase — a replan drafts from the run's own state.
+ * @param {{ seedRed?: string[], priorChecks?: string[] }} [checkFacts] the shape-lottery
+ *   gate rules, STATED as well as enforced (the mailbox precedent: a rule only the
+ *   validator knows costs a redraft per draft). `seedRed`: preflight-red check names —
+ *   Rule A-v2's law (final write step only, framed wide). `priorChecks`: the predecessor
+ *   plan's carried checks, replan phase only — Rule B's law (keep every one). Empty/omitted
+ *   renders byte-identically to the pre-rules prompt.
  */
 export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxStepRounds: number, failure: string | null, scopes: string[] | undefined, materials?: {
     balanceUsd?: number | null;
     remainingMs?: number | null;
     progress?: string;
-}, capRuns?: number): string;
+}, startingDraft?: object | null, checkFacts?: {
+    seedRed?: string[];
+    priorChecks?: string[];
+}): string;
 /**
  * Execute a validateJob-GREEN plan-shape job (goal/verdictType/close).
  * Called by runJob after the approval gate, validation, and the smoke — this
@@ -48,7 +76,17 @@ export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxS
  * @param {(tier: string) => any} [opts.providerFor] P: per-step model-tier factory
  *   (tier ∈ STEP_MODELS → a provider). A plan naming a tier with no factory supplied is an
  *   interpreter-red STOP — never silently run the default tier as if the choice was honoured.
- * @param {number} [opts.capRuns] shell-owned per-step attempt cap
+ * @param {number} [opts.capRuns] shell-owned iteration cap, RETIRED as a governor
+ *   (v1.46 §4). It stopped bounding a plan step when the strike ladder landed, and it
+ *   stopped bounding the close-fix loop when the close trend rule did. It survives as
+ *   that loop's fallback for the ONE case the trend cannot read — a close whose output
+ *   carries no number at all — because a governor that cannot see the variable must
+ *   not be the governor, and the honest fallback is the cruder bound it replaced
+ *   rather than "unbounded". It lifts the moment a stage reports a comparable number.
+ * @param {number} [opts.strikeLimit] shell-owned STRIKE ceiling for a plan step's
+ *   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.maxStepRounds] the shell's per-step rounds ceiling (validatePlan's bound)
  * @param {number} [opts.scoutRounds] the read-only survey's round bound (F59: the LAST round is
@@ -63,15 +101,67 @@ export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxS
  *   first plan-flow job to emit `root-injected` runs the pre-registered ON-vs-OFF acceptance
  *   read (the Layer R default-flip, LAYERS.md ⚠). Excluded on native (clipipe): the native
  *   worker has no onToolResult seam, so the tee cannot settle and same-path rewrites are blind.
+ * @param {unknown} [opts.bridge] Layer 3 (D3/D4) — a bridge-v1 registry entry to REUSE as the
+ *   drafter's starting point. Absent is the COLD path and is byte-identical to the pre-Layer-3
+ *   flow. Present, the D2-split LOAD GATE runs at the door, before the close precheck and
+ *   before any token: on a pass the newest version's plan (the run-as-executed artifact)
+ *   rides into the FIRST draft prompt only; on a fail the run returns the distinct terminal
+ *   `recipe-stale` having spent nothing. Selecting the entry — the listing, the pin, the
+ *   LLM's pick — is the CALLER's, and so is falling back to cold: a silent automatic
+ *   fall-back would spend a run's budget on a decision nobody made.
+ * @param {number} [opts.priorWallMs=0] RESUME (module C) — wall time a PREVIOUS, killed
+ *   attempt of this same try already consumed, folded into the run clock (see
+ *   `createClock`'s `priorElapsedMs`). The SIGNED `maxWallMs` is never rewritten: it is in
+ *   the spec hash, and a resume that edited it would need a signature nobody typed. The
+ *   restarted attempt simply starts already partly spent, so a kill can never buy a fresh
+ *   allotment of the operator's wall.
+ * @param {any} [opts.resumeSeed] RESUME (module C v2) — the FINEST honest checkpoint of a
+ *   KILLED run of this same try, read off its own spine by `readResume` (src/reuse.js) and
+ *   by nothing else: `{ phase, plan, completedSteps: [{id, seq, by}] }`. hamr's ruling is
+ *   the whole contract — *"it should allow resume and start last step instead from the
+ *   beginning, why would i want to waste more money on something i already started"* — so
+ *   with a seed this flow re-pays for NO paid unit the dead run already bought:
+ *
+ *   - the SCOUT does not run (`scout-skipped`, never silence). Its survey is not on the
+ *     spine (only its byte count is), so the ONE consequence is stated rather than
+ *     discovered: a replan after a resume drafts from an empty survey plus the failure
+ *     brief. Re-scouting to refill it would re-pay the exact call this exists to save.
+ *   - the PLAN is not re-drafted. It is reloaded from the seed and RE-VALIDATED against
+ *     the current signed spec; a plan that no longer validates is `plan-red` by name
+ *     (`resume-plan-red`), never run. It is then emitted as this leg's own
+ *     `plan-accepted` (`phase: 'resume'`) — R1 mints a bridge version from the plan AS
+ *     EXECUTED, read back off the spine, so a leg that greens without one would mint
+ *     nothing.
+ *   - a step whose exit was already SATISFIED is skipped, in prefix order, each with its
+ *     own `step-skipped` record naming the event that proves it. Never a fake
+ *     step-start/step-end pair, and never silence: a reader must be able to tell skipped
+ *     from run (the resume-to-cap invariant).
+ *
+ *   The worker's conversation is deliberately NOT replayed — a transcript is not a
+ *   checkpoint, and every attempt is fresh by the loop's own design. Absent is the
+ *   ordinary path and is byte-identical to a run that was never killed.
+ * @param {{stage?: string|null, value?: number|null}[]} [opts.resumeGrades] RESUME — the
+ *   close GRADES the dead leg recorded, oldest first (`readResume`'s `restart.grades`).
+ *   A resumed leg is the same run continuing, so its halt readouts must judge the whole
+ *   chain: without this the trend restarts at this leg's first close and can report
+ *   `flat` — "revise the goal" — on a run that was converging when its allowance ran
+ *   out. Baselines only (src/trend.js's THE SEED): it spends none of this leg's own
+ *   bounds and mints none of its strikes. Empty/omitted is the cold path.
+ * @param {() => boolean} [opts.spendComplete] is the run's spend EXACT, or a floor? The
+ *   ledger one level up owns the answer (unpriced rounds, a self-healed stall, a mid-call
+ *   cut, an inherited resume floor); the money-halt readout states it beside the remaining
+ *   it quotes, because `budget − floor` is a CEILING and printing it bare reads as exact
+ *   (F6). Defaults to exact, which is what every pre-record caller was implicitly saying.
  * @param {() => number} [opts.now] the wall clock's time source, injected. The real clock is the
  *   default; a caller supplies this to drive time deterministically (the same seam `createClock`
  *   already exposes — a run's terminal cannot otherwise be exercised without waiting out a cap
  *   whose floor is one close timeout).
  * @returns {Promise<string>} 'green' | 'already-green' | 'escalated' | 'plan-red' |
- *   'check-red' | 'close-red' | 'close-unsupported' | 'pricing-red' | 'cap-halt' |
- *   'wall-halt' | 'provider-red' | 'interpreter-red' | 'step-stalled' | `step-red:<id>`
+ *   'check-red' | 'close-red' | 'close-unsupported' | 'recipe-stale' | 'pricing-red' |
+ *   'cap-halt' | 'wall-halt' | 'provider-red' | 'interpreter-red' | 'step-stalled' |
+ *   `step-red:<id>`
  */
-export function runPlan(job: any, { workdir, provider, nativeProvider, providerFor, emit, remainingUsd, isUnpriced, capRuns, closeTimeoutMs, maxStepRounds, layerRoot, scoutRounds, now }: {
+export function runPlan(job: any, { workdir, provider, nativeProvider, providerFor, emit, remainingUsd, isUnpriced, spendComplete, capRuns, strikeLimit, closeTimeoutMs, maxStepRounds, layerRoot, scoutRounds, bridge, now, priorWallMs, resumeSeed, resumeGrades }: {
     workdir: string;
     provider: any;
     nativeProvider?: ((o: {
@@ -85,10 +175,19 @@ export function runPlan(job: any, { workdir, provider, nativeProvider, providerF
     isUnpriced?: (() => boolean) | undefined;
     providerFor?: ((tier: string) => any) | undefined;
     capRuns?: number | undefined;
+    strikeLimit?: number | undefined;
     closeTimeoutMs?: number | undefined;
     maxStepRounds?: number | undefined;
     scoutRounds?: number | undefined;
     layerRoot?: boolean | undefined;
+    bridge?: unknown;
+    priorWallMs?: number | undefined;
+    resumeSeed?: any;
+    resumeGrades?: {
+        stage?: string | null;
+        value?: number | null;
+    }[] | undefined;
+    spendComplete?: (() => boolean) | undefined;
     now?: (() => number) | undefined;
 }): Promise<string>;
 export type CategorizedError = Error & {

package/types/ralph.d.ts

@@ -111,6 +111,26 @@ export function runStages(stages: any[], redact?: (s: string) => string, { timeo
     timeoutMs?: number;
     cwd?: string;
 }): Promise<any>;
+/**
+ * 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,
@@ -136,7 +156,28 @@ export function runStages(stages: any[], redact?: (s: string) => string, { timeo
  *   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
@@ -155,7 +196,7 @@ export function runStages(stages: any[], redact?: (s: string) => string, { timeo
  *   with zero writes, a crash stays what it always was: an instrument stop.
  * @returns {Promise<'green'|'escalated'>}
  */
-export function ralph({ middle, close, judge, capRuns, emit, redact, closeTimeoutMs, cwd, expect, judged, gapKeep, workerWrites }: {
+export function ralph({ middle, close, judge, capRuns, ladder, emit, redact, closeTimeoutMs, cwd, expect, judged, gapKeep, workerWrites }: {
     middle: (iteration: number, gap?: string) => void | Promise<void>;
     close?: string[] | undefined;
     judge?: (() => Promise<{
@@ -167,7 +208,8 @@ export function ralph({ middle, close, judge, capRuns, emit, redact, closeTimeou
         gap?: string;
         detail?: string;
     }) | undefined;
-    capRuns: number;
+    capRuns?: number | undefined;
+    ladder?: LoopGovernor | undefined;
     emit: (type: string, data?: object) => object;
     redact?: ((s: string) => string) | undefined;
     closeTimeoutMs?: number | undefined;
@@ -194,7 +236,12 @@ export function ralph({ middle, close, judge, capRuns, emit, redact, closeTimeou
  * 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 cannot see (`AWS_ACCESS_KEY_ID`).
+ *    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,
@@ -228,3 +275,34 @@ export const CLOSE_FAULTS: Record<string, {
     decision: string;
     options: string[];
 }>;
+/**
+ * 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.
+ */
+export type LoopGovernor = {
+    record: (o: {
+        iteration: number;
+        gap?: string;
+    }) => object;
+    struckOut: () => boolean;
+    report: () => {
+        strikes: number;
+        limit: number;
+        iterations: number;
+        distinctGaps?: number;
+    };
+    brief: () => string;
+    terminal?: (() => {
+        decision: string;
+        options: string[];
+    }) | undefined;
+};