bareloop 0.6.0 → 0.8.0

package/types/planrun.d.ts

@@ -1,3 +1,83 @@
+/**
+ * This step's own last EXIT results, rendered for the REPLAN brief.
+ *
+ * The label says exits and not "the close", and the distinction is the whole of one
+ * fix: `res.gap` is `lastGap`, the join of EVERY failing exit's detail in exit order.
+ * With `MAX_EXITS_PER_STEP` at 2 and the mandatory `tree-changed` pairing on a write
+ * step, a step that wrote nothing leads the block with the EVALUATOR's own prose
+ * (`0 files changed under src/** …`) — captured verbatim from a real replan prompt,
+ * under a label reading "the verification's own output". The close stage's output is
+ * one of the details here, never reliably all of them. The payload is left alone: "the
+ * step wrote nothing" is exactly what a replanner should be told, and stripping it to
+ * make an old label true would trade a real fact for a tidy sentence.
+ *
+ * u-mshcpdg4: a run one strict error from done, killed with $1.10 and 82 seconds
+ * unspent. The close named the remaining work exactly — `src/recurse.js(978,115)`
+ * — and the worker read that every attempt. The REPLANNER, which is the component
+ * that chooses which files the next plan targets, was handed only the trend line
+ * (`still progressing — typecheck 30 → 15 → 15 → 1`): converging, and silent about
+ * WHERE. It re-targeted `src/loop.js`, already at zero errors; that step wrote
+ * nothing and struck out. F85 gave the brief the trajectory; this gives it the
+ * artifact the trajectory is a summary OF.
+ *
+ * Handed over as TEXT, never as a parsed file list, and the trap is worth naming
+ * because the parse is the obvious-looking fix: line 1 of that very gap reads
+ * `reports 1 error(s) in src/recurse.js, src/loop.js` — every file in SCOPE — and
+ * only line 2 names the culprit. The `never wrote` advisory that used to sit here
+ * did exactly that parse, and on this gap it resolved to `src/loop.js` — the file
+ * already CLEAN — then said so as a directive beside the artifact that said the
+ * opposite. It was deleted with this change (hamr, 2026-08-05): two readers of one
+ * question, the parsed one wrong, is the same failure the variance meter just had.
+ * Nothing generic can tell a summary line from a detail line, and the
+ * shapes differ per close anyway (tsc file:line, pytest test ids, a count close
+ * that names no file at all). A model reading the artifact can make that
+ * distinction; a regex reproduces the bug. So: no extraction, no digest, no
+ * inference — the artifact, bounded and scrubbed.
+ *
+ * Two boundaries, both reused rather than respelled:
+ *   - SCRUB. A prompt is an egress point and this repo has ONE secret inventory
+ *     (`SECRET_PATTERNS` via `redactSecrets`). The gap arrives already scrubbed
+ *     from `judge`, which makes this defense in depth rather than the only guard —
+ *     and defense in depth at the egress is exactly where it belongs, because the
+ *     next caller of this helper will not remember the upstream one.
+ *   - BOUND, and it is a BACKSTOP rather than an envelope. What arrives here has
+ *     ALREADY been bounded: `runClose` ran `boundGap` with the stage's own `gapKeep`,
+ *     which deliberately rescues the `not ok`/`FAILED` names out of the elided middle
+ *     — the mechanical gap F46's conversion mechanism feeds the worker. Re-bounding
+ *     that with a fresh 400/1500 envelope deletes exactly those names a second time,
+ *     which is F28 reintroduced; measured on a 120-red-line close output, the first
+ *     bound rescued 78 names and this one dropped 12 of them. src/exits.js states the
+ *     same rule for the same artifact one seam earlier, and this now uses ITS number:
+ *     `CHECK_GAP_MAX`, imported rather than respelled, so the two seams cannot drift
+ *     on how big a check gap may be. Under it the gap passes through VERBATIM.
+ *
+ *     A backstop is still needed, and the headroom is why the ceiling is not smaller.
+ *     `res.gap` is `lastGap`, the JOIN of up to `MAX_EXITS_PER_STEP` failing exit
+ *     details, and the check-passes branch slices EACH at `CHECK_GAP_MAX` — so what
+ *     arrives is bounded per detail, never in total. Measured, the real maximum is
+ *     comfortably under: `runClose`'s own envelope tops out at ~10.1KB (400 head +
+ *     8192 keep + 1500 tail + labels), and joined with a `tree-changed` line that is
+ *     ~10.2KB, so the shipped path passes through untouched with ~1.8KB to spare. The
+ *     backstop therefore fires only where src/exits.js says it should: a seam that
+ *     returned something never bounded at all.
+ *
+ *     Over the line `boundGap` runs with `REPLAN_GAP_KEEP`, the same envelope the
+ *     close path uses, and every trim announces itself (F28). Note what that keep-set
+ *     cannot do: `\S` matches every non-blank line, so the keep block degenerates into
+ *     "the first 50 lines" and re-surfaces nothing from the middle. That is the honest
+ *     limit of a red-set that cannot know the stage's own pattern (see
+ *     `REPLAN_GAP_KEEP`), and it is affordable precisely because it now applies only
+ *     to a gap nothing upstream ever bounded — on that gap ANY envelope loses names,
+ *     and the choice is a bounded prompt over an unbounded one.
+ *
+ * No gap → the empty string, so the brief renders byte-identically to the pre-F86
+ * one. A labelled empty section would be an invitation to explain an absence the
+ * run never observed (a stall never judged its exits at all).
+ *
+ * @param {string | null | undefined} gap the step's last exit gap text
+ * @returns {string} the labelled block, or '' when there is nothing to show
+ */
+export function closeGapBlock(gap: string | null | 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 +93,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 +138,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 +163,101 @@ 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 {{count?: number, grantUsed?: boolean}|null} [opts.resumeReplans] RESUME — the
+ *   replan LEDGER the chain has already spent (`readResume`'s `restart.replans` /
+ *   `restart.replanGrantUsed`), seeding the ceiling below. `resumeGrades`' sibling and
+ *   deliberately NOT its twin: a grade seed feeds a READOUT, this one feeds a BOUND.
+ *
+ *   Without it the ceiling is reborn on every call, and a resume is another call:
+ *   measured, a leg that spent both replans and step-redded handed its checkpoint to a
+ *   second leg that replanned twice more. Two became four by being killed once, which is
+ *   the creep the latch exists to make impossible ("unlimited replanning launders thrash
+ *   as adaptation", PRD v1.12).
+ *
+ *   WHY THIS SEED SPENDS THE LEG'S BOUND WHERE `resumeGrades` DOES NOT. src/trend.js's
+ *   THE SEED refuses to seed the fix loop's ITERATIONS from history "because the leg's
+ *   own bounds must not be spent by history" — and that is right, because an attempt
+ *   allowance is a LEG bound: a restarted leg buys its own attempts with its own money.
+ *   The replan ceiling is a RUN bound by doctrine. It bounds how many times the WORKFLOW
+ *   may be redrawn before redrawing it is thrash, and that question spans exactly the
+ *   chain the halt readout already spans. The two seeds therefore disagree on purpose;
+ *   they are not the same rule applied inconsistently.
+ *
+ *   CHAIN SEMANTICS, and the one place this differs from the grade seed's mechanism.
+ *   `readGradeSeed`'s documented KNOWN LIMIT is that it reads ONE spine, so a resume of a
+ *   resume inherits leg 2's grades and not leg 1's — the chain shortens by one leg per
+ *   resume, which is fail-safe for a READOUT (a shorter chain can only under-claim a
+ *   direction). It is the DANGEROUS direction for a ceiling: an under-claimed ledger is a
+ *   refilled allowance, and every kill would buy one. So this seed does NOT reuse that
+ *   mechanism. It follows the MONEY fold instead (`priorSpentUsd`, `try-start`/
+ *   `job-start`): each leg DECLARES the ledger it inherited on its own spine, and the
+ *   next reader adds only that leg's own `replan` records to the declared number. Leg 3
+ *   therefore inherits the whole chain, not leg 2's slice.
+ *
+ *   `count` seeds `replans` (and, above zero, latches `replanned`); `grantUsed` seeds the
+ *   F85-C variance latch, so a killed leg cannot re-earn an extra the arbiter has already
+ *   granted. Null/omitted is the cold path and is byte-identical to a run nobody resumed.
+ * @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, resumeReplans }: {
     workdir: string;
     provider: any;
     nativeProvider?: ((o: {
@@ -85,10 +271,23 @@ 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;
+    resumeReplans?: {
+        count?: number;
+        grantUsed?: boolean;
+    } | null | undefined;
+    spendComplete?: (() => boolean) | undefined;
     now?: (() => number) | undefined;
 }): Promise<string>;
 export type CategorizedError = Error & {

package/types/ralph.d.ts

@@ -111,6 +111,42 @@ export function runStages(stages: any[], redact?: (s: string) => string, { timeo
     timeoutMs?: number;
     cwd?: string;
 }): Promise<any>;
+/**
+ * Bound an over-long close stream to a head sample + elided middle + tail. When
+ * `keepPattern` is set (F28), lines of the WHOLE stream matching it are also
+ * carried in a clearly-delimited block between head and tail — capped — so the
+ * failing-test names buried in the middle still reach the worker.
+ * Exported for the ONE reason `GAP_KEEP_TRIM_MARKER` above is: a second consumer
+ * that needs a gap bounded must reuse THIS envelope, not spell its own. A private
+ * copy would be a second truncation scheme, and the two would drift on exactly the
+ * property that matters — whether the red lines survive, and whether the trim
+ * announces itself (F28: silent truncation is the disease this function cures).
+ * The close path is unchanged: `runClose` still calls it with the stage's own
+ * `gapKeep`, byte-identically.
+ * @param {string} s the (redacted) close output
+ * @param {string} [keepPattern] regex source; matching lines survive the elision
+ */
+export function boundGap(s: string, keepPattern?: string): 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.
+ *
+ * @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 +172,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 +212,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 +224,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 +252,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 +291,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;
+};