bareloop 0.5.1 → 0.7.0

package/types/ralph.d.ts

@@ -60,9 +60,9 @@
  *   (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: string[], redact?: (s: string) => string, { timeoutMs, cwd, expect, judged, gapKeep }?: {
     timeoutMs?: number;
@@ -73,7 +73,7 @@ export function runClose(close: string[], redact?: (s: string) => string, { time
         min: number;
     };
     gapKeep?: string;
-}): {
+}): Promise<{
     verdict: "satisfied" | "needs_revision" | "failed" | "timed-out" | "killed" | "crashed";
     gap?: string;
     exitCode?: number;
@@ -81,7 +81,56 @@ export function runClose(close: string[], redact?: (s: string) => string, { time
     detail?: string;
     judgedCount?: number | null;
     unaudited?: boolean;
-};
+}>;
+/**
+ * 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 function runStages(stages: any[], redact?: (s: string) => string, { timeoutMs, cwd }?: {
+    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,
@@ -107,7 +156,28 @@ export function runClose(close: string[], redact?: (s: string) => string, { time
  *   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
@@ -126,7 +196,7 @@ export function runClose(close: string[], redact?: (s: string) => string, { time
  *   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<{
@@ -138,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;
@@ -151,6 +222,40 @@ export function ralph({ middle, close, judge, capRuns, emit, redact, closeTimeou
     gapKeep?: string | undefined;
     workerWrites?: (() => string[]) | undefined;
 }): Promise<"green" | "escalated">;
+/**
+ * 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: Readonly<{
+    names: readonly string[];
+    prefixes: readonly string[];
+    shape: RegExp;
+}>;
 export const GAP_KEEP_TRIM_MARKER: "more elided by the";
 /**
  * The forbidden zone, named (PRD v1.11). Each row is an outcome in which the
@@ -170,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;
+};

package/types/reuse.d.ts

@@ -0,0 +1,388 @@
+/**
+ * Validate the reuse envelope — the three numbers the operator signs before the run.
+ *
+ * `{ perTryBudgetUsd, perTryWallMs, bridgeTries }`, all REQUIRED and explicit. There is
+ * no default for any of them and there will not be one: hamr's ruling on `maxWallMs`
+ * generalises — a defaulted cap is a silent second ceiling, and a cap the operator did
+ * not state is a cap nobody chose.
+ *
+ * `bridgeTries: 0` is legal and means FORCE COLD: zero stored workflows are tried, the
+ * run drafts from scratch, and no selection call is made (nothing to select among).
+ *
+ * With a `job`, the composition rule is enforced: the per-try numbers may only TIGHTEN
+ * the signed spec. A per-try budget above `job.budgetUsd`, or a per-try wall above
+ * `job.maxWallMs`, is `envelope-widens` — the runner may narrow the operator's cap, never
+ * widen it. A spec that sets NO `maxWallMs` is time-unbounded by explicit choice, so any
+ * wall is a tightening of it.
+ *
+ * @param {unknown} input the operator's envelope
+ * @param {{job?: unknown}} [opts] the SIGNED spec, when the composition is being checked
+ * @returns {{ ok: boolean, reds: Red[], envelope: any }}
+ */
+export function validateEnvelope(input: unknown, { job }?: {
+    job?: unknown;
+}): {
+    ok: boolean;
+    reds: Red[];
+    envelope: any;
+};
+/**
+ * The PER-TRY spec: the signed job with the envelope's caps written onto it. Pure — the
+ * input spec is never mutated.
+ *
+ * This is what every try actually runs, cold leg included, so "$5 and 30 mins x2 then
+ * start anew" means the same numbers all the way down.
+ *
+ * **It is a spec VERSION, not a spec edit made behind the operator's back.** When the
+ * envelope equals the spec's own numbers the result is hash-IDENTICAL and the existing
+ * approval covers it. When it tightens, the hash MOVES — and `runJob`'s approval gate
+ * refuses the run until the operator has signed that hash. That refusal is the feature:
+ * the tightened numbers are the ones enforced, so they are the ones signed.
+ *
+ * @param {object} job the signed spec
+ * @param {{perTryBudgetUsd: number, perTryWallMs: number}} envelope a validated envelope
+ * @returns {object} the per-try spec
+ */
+export function resolveTrySpec(job: object, envelope: {
+    perTryBudgetUsd: number;
+    perTryWallMs: number;
+}): object;
+/**
+ * The RESOLVED REUSE ARTIFACT — the thing the operator actually signs.
+ *
+ * The envelope is THREE numbers, and the third one is a MULTIPLIER: the worst case a
+ * reuse run authorizes is `perTryBudgetUsd × (bridgeTries + 1)`. A signature taken over
+ * the per-try spec alone covers only two of the three — `--tries 0` and `--tries 9` hash
+ * identically while authorizing ten times the spend. So the signed artifact is this
+ * WRAPPER, and `reuseSpecHash` is what an approval gate prints and compares.
+ *
+ * It is a wrapper rather than a field on the spec because `validateJob` reds every
+ * unknown top-level field: a `bridgeTries` written onto the per-try spec would flip the
+ * hash and then make every try a `job-red`. The spec half stays exactly the spec `runJob`
+ * executes, unchanged in kind.
+ *
+ * `bridgeTries` is READ ONCE, here, and the run's loop bound is read back off this same
+ * object — the number enforced and the number signed are the same number from the same
+ * place, never two reads of the envelope that a later edit could separate.
+ *
+ * @param {object} job the signed spec
+ * @param {{perTryBudgetUsd: number, perTryWallMs: number, bridgeTries: number}} envelope
+ * @returns {{schema: string, spec: any, bridgeTries: number}}
+ */
+export function resolveReuse(job: object, envelope: {
+    perTryBudgetUsd: number;
+    perTryWallMs: number;
+    bridgeTries: number;
+}): {
+    schema: string;
+    spec: any;
+    bridgeTries: number;
+};
+/**
+ * The APPROVAL HASH: one number covering all three envelope numbers.
+ *
+ * Composed from the repo's ONE spec hasher rather than re-canonizing the wrapper, so the
+ * per-try spec half is hashed exactly as `jobSpecHash` hashes it — MED-1's resolved-`tools`
+ * pinning included, and with no second canonicalizer that could drift from it. The
+ * `reuse-v1` prefix is domain separation: a reuse approval can never collide with a bare
+ * job approval.
+ *
+ * **This is a signing-SCHEME change, and it invalidates every hash signed before it — by
+ * design.** A signature that did not cover the try count never covered the run's worst
+ * case, so it is not carried forward: there is no legacy acceptance path, and re-signing
+ * once is the whole migration.
+ *
+ * @param {{spec: any, bridgeTries: number}} resolved a `resolveReuse` artifact
+ * @returns {string} sha256 hex
+ */
+export function reuseSpecHash(resolved: {
+    spec: any;
+    bridgeTries: number;
+}): string;
+/**
+ * Ask the model which stored workflow (if any) this run should start from — ONE call, on
+ * the drafter-tier provider the CALLER hands in. No provider is constructed here: the
+ * provider binding is shell territory, exactly as it is for every other call in this
+ * repo.
+ *
+ * The three operator overrides ride into the same call rather than around it:
+ *  - `forceCold` skips everything ($0, no tokens) — the operator has already decided.
+ *  - `shortlist` restricts the LISTING to those names, so the model chooses among the
+ *    operator's set and cannot reach past it.
+ *  - `pinned` does NOT bypass the call. D3: the model may refuse a pin only EXPLICITLY,
+ *    with a reason. So the pin is stated in the prompt, and if the answer names anything
+ *    other than the pin the result is `{refused: true}` — the substitute is NOT adopted,
+ *    and the decision goes back to the operator. Neither direction is silent.
+ *
+ * An EMPTY candidate set also skips the call: paying a model to pick from an empty
+ * listing buys nothing, and "there is nothing to reuse" is not a judgment call.
+ *
+ * The answer is parsed with the repo's ONE model-output parser (`extractArtifact`) and
+ * then strictly: an object with a `choice` that is null or a name FROM THE LISTING, plus
+ * a `reason`. A name that is not on the listing is a named red, never used — a picker
+ * that can name a workflow nobody offered is a picker that can reach outside the
+ * operator's set.
+ *
+ * Cost is metered and reported (F6): `costUsd` is the priced figure or an explicit null,
+ * and `spendComplete` says whether that figure is exact. A skipped call is a real 0.
+ *
+ * @param {object} opts
+ * @param {unknown} opts.registry `loadRegistry`'s result, or a bare array of entries
+ * @param {object} opts.job the job this run is signed against (only its goal is used here)
+ * @param {string} opts.ask the ask, in the operator's own words
+ * @param {any} opts.provider the drafter-tier provider binding (caller-owned)
+ * @param {string|null} [opts.pinned] the operator's pin
+ * @param {string[]|null} [opts.shortlist] the operator's shortlist
+ * @param {boolean} [opts.forceCold]
+ * @param {string[]} [opts.exclude] names already tried this run
+ * @returns {Promise<any>} `{ choice, reason, called, refused, forcedCold, red, costUsd,
+ *   spendComplete, candidates, listing }`
+ */
+export function selectBridge({ registry, job, ask, provider, pinned, shortlist, forceCold, exclude }: {
+    registry: unknown;
+    job: object;
+    ask: string;
+    provider: any;
+    pinned?: string | null | undefined;
+    shortlist?: string[] | null | undefined;
+    forceCold?: boolean | undefined;
+    exclude?: string[] | undefined;
+}): Promise<any>;
+/**
+ * Read a killed reuse run's OWN SPINE back into the state a resume continues from.
+ *
+ * hamr's checkpoint ruling is the whole contract: *"money, signature and checkpoint
+ * (starts from where it stopped) if mid loop, restart that loop"*. So this reader
+ * answers exactly four questions, and nothing else:
+ *
+ *  1. **Which tries COMPLETED** — they are never re-run, and their bridges stay
+ *     spoken for exactly as if the loop had carried on.
+ *  2. **Was the process mid-try** — a `try-start` with no matching `try-end`. That
+ *     try was never graded, so it is not consumed: it RESTARTS from its beginning.
+ *  3. **What that dead attempt already spent, in money and in wall time** — folded
+ *     into the restart so it runs under the REMAINDER of its signed per-try numbers.
+ *  4. **Which envelope this spine belongs to** — the `reuse-start` record's own
+ *     approval hash, so a resume can prove it is continuing the SAME signed run.
+ *
+ * **F45 governs the arithmetic here.** A window's spend is summed from `worker-round`
+ * ONLY — the same event `runJob`'s own ledger accounts, no other. The selection calls
+ * are real money and are counted, but as the RUN's cost and never as a try's: a
+ * picker's tokens are not a worker's, and attributing them to a try would misstate
+ * both the fold and the row. `worker-turn` (native attribution, cost null by design)
+ * is deliberately not summed, exactly as the live ledger does not sum it.
+ *
+ * **The declared fold, not a re-derivation.** A restarted try's own `try-start`
+ * carries the fold it inherited (`priorSpentUsd`/`priorWallMs`), so a resume OF a
+ * resume adds only its own new rounds. Re-deriving from the whole file would bill an
+ * abandoned attempt twice.
+ *
+ * **KNOWN LIMIT, stated rather than discovered later.** A call that was killed BEFORE it
+ * returned left no event at all — no `worker-round`, no `selection-result` — so money it
+ * may already have been billed for is not on the spine and cannot be folded. This reader
+ * can only account writers that WROTE (the same limit the runner's own guards have: a
+ * hung `generate()` leaves zero trace). The fold is therefore a floor in exactly the case
+ * `priorSpendComplete` already marks, and one lost selection call is re-paid by the
+ * resumed pick rather than silently attributed to a try.
+ *
+ * **A try whose `job-end` landed is COMPLETE, not mid-flight.** The close already
+ * rendered its verdict; restarting would pay a second time for an answer already in
+ * hand. When the death fell between that verdict and the registry write, the row that
+ * was lost is NAMED (`r1Missing`) rather than silently absent — and never re-derived,
+ * because a green's version has to be the plan AS EXECUTED and this reader is not
+ * where that is decided.
+ *
+ * **THE HALT AMENDMENT (PRD v1.46 §3).** "A landed `job-end` is COMPLETE" is true of
+ * a VERDICT, and a governance halt is not one: a money cap-halt (and, W-2-symmetric,
+ * a wall-halt) means the run ran out of an operator-owned allowance with its work on
+ * disk and its plan on the spine — the exact case hamr's ruling was about ("why would
+ * i want to waste more money on something i already started"). `resumableOutcomes`
+ * names which terminals get read that way. It is EMPTY by default, so the reuse
+ * loop's own semantics are byte-unchanged: there, a cap-halted try was graded, its
+ * registry row was written, and turning it into a restart would re-run a try whose
+ * fold leaves it no money at all and duplicate its row. Green and every red stay
+ * non-resumable under any setting — a verdict already rendered is never re-bought.
+ *
+ * **DIRECT SPINES (`direct`).** A `runJob` spine has no `reuse-start` and no try
+ * windows, so this reader saw one as "not a reuse run" and every priced round in it
+ * as a STRAY. Opted in, the run itself is read as ONE implicit try opened at
+ * `job-start` — the same window machinery, never a second reader, because the whole
+ * failure class this reader exists to survive (F45) is the writer nobody modelled.
+ * The fold it declares comes off `job-start`'s own `priorSpentUsd`, exactly as a
+ * restarted try's comes off its `try-start`: re-deriving from the file would bill an
+ * abandoned attempt twice in a chain of resumes.
+ *
+ * @param {any[]} events the dead spine's events, parsed, in file order
+ * @param {{deathAt?: number|null, direct?: boolean, resumableOutcomes?: string[]}} [opts]
+ *   `deathAt`: when the process is judged to have died (the watchdog's kill record,
+ *   which is later and better evidence than the last event). Defaults to the last
+ *   event's own timestamp — the last sign of life there is.
+ * @returns {any} `{ started, approvalHash, specHash, patient, job, bridgeTries,
+ *   perTryBudgetUsd, perTryWallMs, ended, endOutcome, greened, completed, tried,
+ *   selectionCostUsd, selectionComplete, strayRounds, r1Missing, restart, deathAtKnown,
+ *   spentUsd, spendComplete, carrySpentUsd, carrySpendComplete }`
+ */
+export function readResume(events: any[], { deathAt, direct, resumableOutcomes }?: {
+    deathAt?: number | null;
+    direct?: boolean;
+    resumableOutcomes?: string[];
+}): any;
+/**
+ * The PATIENT gate for a resume, which is deliberately NOT the fresh-launch one.
+ *
+ * A fresh reuse run refuses a dirty tree: a run that inherits the previous run's edits
+ * measures the wrong thing. A RESUME is the opposite case — the dead tries' work is real
+ * progress this run already paid for, the tries share one workdir by design, and the tree
+ * is reset between RUNS by the operator, never by the harness. So a dirty tree is exactly
+ * what a resume expects to find, and it is continued as the run left it: not reset, not
+ * refused.
+ *
+ * What IS refused is HEAD moving off the seed. That is not the run's own work — nothing
+ * in the flow commits — so it means a human committed, rebased or checked something out
+ * under the dead run. The reconstruction's premise (this tree is where try N left it) no
+ * longer holds, and that decision comes back to the operator.
+ *
+ * @param {{head: string, seed: string, dirty: string}} state as `git rev-parse HEAD` and
+ *   `git status --porcelain` report it
+ * @returns {{ok: boolean, detail: string|null}}
+ */
+export function resumeTreeGate({ head, seed, dirty }: {
+    head: string;
+    seed: string;
+    dirty: string;
+}): {
+    ok: boolean;
+    detail: string | null;
+};
+/**
+ * Run a job under the reuse envelope: select a stored workflow, try it, and — if the
+ * envelope pre-authorized it — try the next one, then draft cold.
+ *
+ * The shape, end to end:
+ *
+ * 1. **Envelope** validated against the SIGNED spec (tighten-only). A red stops here,
+ *    before the registry is read and before anything is spent.
+ * 2. **Registry** loaded from the operator-supplied directory (never a default location).
+ *    A missing directory is a named red; a malformed ENTRY is skipped, reported, and
+ *    carried into the listing so the picker is never handed a silently shorter set.
+ * 3. **Up to `bridgeTries` tries.** Each try re-runs selection against a FRESHLY RELOADED
+ *    registry with the already-tried names excluded — so the next pick sees the row the
+ *    last try just wrote, and cannot re-pick a workflow this run already spent money on.
+ *    The chosen entry rides into `runJob`, whose own load gate is the D2 shape check; a
+ *    gate refusal (`recipe-stale`) costs $0 and simply moves to the next candidate.
+ * 4. **After each try the box is written (R1)** — green appends a version + a row, a
+ *    graded red appends a row, a casualty appends a row under its own name. Saved
+ *    atomically, one write per try.
+ * 5. **A green ENDS the loop.** The job is done; there is nothing left to try.
+ * 6. **Tries exhausted → the cold leg**, under the SAME per-try numbers ("then start
+ *    anew"). Its green mints a NEW bridge named for the job slug — or appends to the
+ *    entry of that name if one already exists, because clobbering a green is exactly the
+ *    thing R1 exists to prevent.
+ *
+ * Fallthrough is automatic ONLY because the envelope pre-authorized it (D7) — that is
+ * what makes it not a per-failure nag, and it is also why nothing else here is automatic:
+ * a refused pin, an unreadable selection answer and a missing registry all STOP and hand
+ * the decision back.
+ *
+ * **RESUME (module C).** With `resume` — a `readResume` reading of the dead run's own
+ * spine — the same loop picks up where a killed run stopped: the completed tries are
+ * seeded in (never re-run, their bridges never re-offered), a try that was mid-flight is
+ * RESTARTED from its beginning against the SAME workflow and with NO second selection
+ * call (the pick was made and paid for), and it runs under the REMAINDER of its own
+ * signed per-try numbers. The remainder is expressed as a FOLD of the dead attempt's
+ * spend and wall — never as tightened caps — because the caps are in the spec hash and
+ * rewriting them would need a signature nobody typed. If the remainder cannot fund the
+ * restart the run caps honestly, having launched nothing.
+ *
+ * @param {object} opts
+ * @param {object} opts.job the signed job spec
+ * @param {unknown} opts.approvals approval records — passed straight through to `runJob`;
+ *   this module never mints one (a tightened envelope makes a NEW spec version, and the
+ *   operator signs it)
+ * @param {string} opts.registryDir the operator-supplied bridge registry
+ * @param {unknown} opts.envelope `{ perTryBudgetUsd, perTryWallMs, bridgeTries }`
+ * @param {string} opts.patient the instance this run works on — the distinct-patient
+ *   count IS the status ladder (D6/R2), so it is required and never guessed from a path
+ * @param {string} opts.workdir the run directory
+ * @param {any} opts.provider the worker provider binding
+ * @param {any} [opts.selectionProvider] the drafter-tier provider for the selection call
+ *   (defaults to `provider`)
+ * @param {(type: string, data?: object) => object} opts.emit spine emitter
+ * @param {string} [opts.ask] the ask in the operator's words (defaults to the job's goal)
+ * @param {string|null} [opts.pinned]
+ * @param {string[]|null} [opts.shortlist]
+ * @param {boolean} [opts.forceCold]
+ * @param {string} [opts.runid] the run id the bridge rows point back at (defaults to a
+ *   fresh one); the operator runner passes its own so a row names its spine file
+ * @param {any} [opts.providerFor] per-step model-tier factory, forwarded
+ * @param {any} [opts.nativeProvider] native provider factory, forwarded
+ * @param {number} [opts.capRuns] forwarded
+ * @param {number} [opts.strikeLimit] forwarded (a plan step's strike ceiling)
+ * @param {number} [opts.closeTimeoutMs] forwarded
+ * @param {boolean} [opts.layerRoot] forwarded
+ * @param {any} [opts.resume] RESUME (module C) — a `readResume` reading of the KILLED
+ *   run's own spine. Its `approvalHash` must match this run's, or the run refuses:
+ *   a resume continues ONE signed run, not any run.
+ * @param {typeof shippedRunJob} [opts.runJob] the job runner. An injected seam of the
+ *   same class as `provider`: a try is a real paid run, and the loop's own logic —
+ *   selection order, exclusion, minting, exhaustion — is not testable against one.
+ * @param {() => number} [opts.now] the clock, injected (per-try wall measurement)
+ * @returns {Promise<any>} `{ outcome, tries, selection, spentUsd, spendComplete,
+ *   bridgeWrites, decision, options, reds, triesAuthorized, triesUsed, envelope, specHash,
+ *   approvalHash }` — `specHash` is the per-try spec's (what `runJob`'s own gate reads);
+ *   `approvalHash` is the OPERATOR's, covering all three envelope numbers
+ */
+export function runReuse(opts: {
+    job: object;
+    approvals: unknown;
+    registryDir: string;
+    envelope: unknown;
+    patient: string;
+    workdir: string;
+    provider: any;
+    selectionProvider?: any;
+    emit: (type: string, data?: object) => object;
+    ask?: string | undefined;
+    pinned?: string | null | undefined;
+    shortlist?: string[] | null | undefined;
+    forceCold?: boolean | undefined;
+    runid?: string | undefined;
+    providerFor?: any;
+    nativeProvider?: any;
+    capRuns?: number | undefined;
+    strikeLimit?: number | undefined;
+    closeTimeoutMs?: number | undefined;
+    layerRoot?: boolean | undefined;
+    resume?: any;
+    runJob?: typeof shippedRunJob | undefined;
+    now?: (() => number) | undefined;
+}): Promise<any>;
+/** @typedef {{code: string, path: string, detail?: string}} Red */
+/**
+ * The GRADED-RED set: the runJob outcomes in which the operator's close actually
+ * rendered a verdict on the tree and that verdict was RED. Only these demote (D6).
+ *
+ * `escalated` is the one. It is the terminal runPlan returns when the close judged the
+ * tree, the bounded fix loop ran its attempts with money still on the table, and the
+ * close was still red — i.e. the recipe was graded by the job's own truth and failed.
+ *
+ * Everything else non-green is a CASUALTY and keeps its own name:
+ *  - `cap-halt` / `wall-halt` — governance stops. A money cut is never a capability read
+ *    (F45) and the wall keeps the verdict already minted (W-2).
+ *  - `provider-red` / `step-stalled` / `pricing-red` — transport and metering.
+ *  - `close-red` / `close-unsupported` — the close FAULTED (broken, timed out, killed,
+ *    crashed). It rendered no judgment, so its exit says nothing about the tree.
+ *  - `recipe-stale` — the load gate refused the recipe at the door, $0 spent.
+ *  - `plan-red` / `step-red:<id>` / `check-red` — the plan flow stopped before the close
+ *    ever judged. Read as evidence about the RECIPE these would be a guess; they are
+ *    recorded in full on the history row, which is where D6 puts the detail a human
+ *    reads, and the coarse status ladder is left alone.
+ *  - `unapproved-spec` / `job-red` / `smoke-red` / `interpreter-red` — the run never
+ *    started.
+ */
+export const REUSE_GRADED_RED: readonly string[];
+export type Red = {
+    code: string;
+    path: string;
+    detail?: string;
+};
+import { runJob as shippedRunJob } from './run.js';

package/types/root.d.ts

@@ -66,13 +66,21 @@ export function createRoot({ gapKeep, redact, writesInformative }?: {
      * Called at the START of attempt `iteration`, with the PREVIOUS attempt's
      * gap. Finalizes that attempt from the books, runs the detector, and
      * returns the injection for the attempt about to run — or null (inert).
-     * @param {{iteration: number, gap?: string, writes: string[]}} o
+     *
+     * `redStage`/`redKeep` are the STAGED-CLOSE seam (PRD v1.28): a close is an
+     * ordered list of named stages, the first red renders the verdict, so the
+     * pattern that designates failures belongs to whichever stage rendered it
+     * THIS attempt. Callers with a single red-set source (the per-step exit
+     * evaluator) pass neither and keep the constructor's run-wide pattern.
+     * @param {{iteration: number, gap?: string, writes: string[], redStage?: string, redKeep?: string}} o
      * @returns {null | {stage: 'summary'|'verbatim', note: string, event: object}}
      */
-    observe({ iteration, gap, writes }: {
+    observe({ iteration, gap, writes, redStage, redKeep }: {
         iteration: number;
         gap?: string;
         writes: string[];
+        redStage?: string;
+        redKeep?: string;
     }): null | {
         stage: "summary" | "verbatim";
         note: string;