bareloop 0.5.1 → 0.7.0

package/types/index.d.ts

@@ -1,11 +1,12 @@
 export { makeSpine } from "./spine.js";
 export { runPlan } from "./planrun.js";
 export { runJob } from "./run.js";
-export { ralph, runClose, CLOSE_FAULTS } from "./ralph.js";
-export { validateConfig, diffPaths, globToPrefix, scanSecrets, LOOP_SHAPES, SLOTS, VERBS } from "./validate.js";
-export { validateJob, jobSpecHash, checkApproval, CLOSE_TYPES, CLASSES, CLASS_BY_CLOSE, GOLD_COMPARE, CADENCE_UNITS, PROVIDERS, CONDITION_KEYS, STEP_MODES, TOOL_MENU, LOCKED_TOOLS, VERDICT_TYPES, LOCKED_VERDICTS } from "./job.js";
-export { validatePlan, EXIT_TYPES, MAX_EXITS_PER_STEP, MAX_PLAN_STEPS, WRITE_VERBS } from "./plan.js";
+export { ralph, runClose, runStages, CLOSE_FAULTS } from "./ralph.js";
+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 { interpret, STALL_REDS } from "./interpret.js";
-export { extractRules, MAX_RULES, MAX_RULE_CHARS } from "./extract.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/job.d.ts

@@ -17,9 +17,52 @@ export function validateJob(input: object | string, { shellCapUsd }?: {
     job: object | null;
 };
 /**
- * Content hash of a job spec — what an approval record binds to. Any edit to
- * the spec changes the hash, so an edited spec is unapproved by construction
- * (interview decision #1: human signs, always, once per spec VERSION).
+ * The staged close (PRD v1.28) — the close is an ORDERED LIST of named stages,
+ * and the check menu DERIVES from it. The principle: *the user authors the
+ * destination, never the road.* A user who cannot describe a workflow can still
+ * say what done looks like, and everything downstream of that is derived — which
+ * is why `checks[]` no longer exists as a field (hamr: *"there shouldn't be user
+ * authoring anywhere, that defies the point of bareloop"*).
+ *
+ * Two stage classes cannot be handed to the agent as a mid-build ruler, and F58
+ * measured both against a real close:
+ *  - a PRECONDITION ("the seed commit exists") is not a ruler for the work; run
+ *    as a check it passes instantly and teaches nothing. It sets `offer: false`.
+ *  - a stage that reads what an EARLIER stage built ("the public API matches the
+ *    emitted declarations") reds on its own for a reason that has nothing to do
+ *    with the worker's edit. It names `needs`, and picking it runs that chain first.
+ * Everything else is offerable: derivation gave job #5 SEVEN rulers where the
+ * operator had hand-carved three (F58) — removing the operator does not cost the
+ * agent rulers, it hands it more.
+ *
+ * The `needs` expansion is TRANSITIVE (fixed point, not one level): a
+ * prerequisite may itself name one, and running an incomplete chain reproduces
+ * the exact false-red `needs` exists to remove, one level deeper. The expanded
+ * chain is ordered by the CLOSE, never by the order names were typed —
+ * validateStagedClose forces `needs` to name EARLIER stages, so close order IS
+ * a topological order. A `needs` cycle is inexpressible in a validated close for
+ * that same reason; the walk is still cycle-safe by construction (each stage is
+ * collected at most once), because a pure exported helper must terminate on
+ * whatever it is handed rather than hang the runner before any token burns.
+ *
+ * @param {any[]} close the validated stage list
+ * @returns {{name: string, run: any[]}[]} offerable stages, each with the ordered
+ *   chain that must run for it (prerequisites first, the stage itself last)
+ */
+export function checkMenu(close: any[]): {
+    name: string;
+    run: any[];
+}[];
+/**
+ * Content hash of a job spec — what an approval record binds to. Any SEMANTIC
+ * edit changes the hash, so a spec whose meaning moved is unapproved by
+ * construction (interview decision #1: human signs, always, once per spec
+ * VERSION). Not every BYTE edit: the hash is taken over the RESOLVED spec
+ * (resolveSpec), so writing today's full TOOL_MENU into a spec that omitted
+ * `tools` is hash-neutral — the two spell the same ceiling, and that identity
+ * is the point of MED-1, since it is what pins WHICH menu the signature covers.
+ * The direction that matters still bites: the menu itself changing (or the
+ * explicit list changing) moves the resolved form, and the hash with it.
  * @param {object} job
  * @returns {string} sha256 hex
  */
@@ -35,8 +78,11 @@ export function jobSpecHash(job: object): string;
  */
 export function checkApproval(job: object, approvals: unknown): boolean;
 export const CLOSE_TYPES: readonly string[];
-export const CLASSES: readonly string[];
-/** the hierarchy: which verdict classes a close type may claim (PRD §7) */
+/** the hierarchy: which verdict classes a close type may claim (PRD §7). Read by
+ * the verdictType check — a declared verdict may not demand a class its close
+ * type cannot legally claim (green-on-rubric is laundering). The `CLASSES`
+ * vocabulary export went with steps[] (PRD v1.32): a class was a STEP field, and
+ * nothing declares one now. */
 export const CLASS_BY_CLOSE: Readonly<{
     predicate: readonly string[];
     gold: readonly string[];
@@ -44,8 +90,6 @@ export const CLASS_BY_CLOSE: Readonly<{
     hitl: readonly string[];
 }>;
 export const GOLD_COMPARE: readonly string[];
-/** step middle modes (2b): text = single-target artifact; tools = Gate-governed file tools */
-export const STEP_MODES: readonly string[];
 /** the tool grant menu (2b interview #1): read/grep/write, plus the two litectx
  * RETRIEVAL verbs (F19) — `run` stays locked-but-listed; a spec requesting it
  * reds, and that red IS the request-red evidence admission waits on (curation
@@ -65,8 +109,39 @@ export const STEP_MODES: readonly string[];
  * WRITE-class verb judged by the SAME writeScope fence as `write` (bareguard
  * action type 'edit'). Admitted because whole-file rewrite is measurably
  * unreliable at size (F31: 4 of 5 big-file whole-writes broke the tree) and
- * taxes output tokens ∝ file size. It admits no execution either. */
+ * taxes output tokens ∝ file size. It admits no execution either.
+ *
+ * P (design record 2026-07-28, hamr: full catalog) widened the menu to the four
+ * components — write · select · compress · isolate — every verb an EXISTING
+ * litectx implementation (menu-is-inventory). impact/related/recent/compress/
+ * peek are read-only like the retrieval pair; stash/remember/forget are
+ * STORE-writes (`.litectx`, never the tree — own gate action types, and the U
+ * runner deletes the store at reset so cold stays cold). None admits execution:
+ * the `run` lock is untouched. */
 export const TOOL_MENU: readonly string[];
+/** the write-class split the validator and the scout filter read: tree writes
+ * (writeScope fence) vs store writes (isolate) — NEITHER is read-capable. */
+export const WRITE_VERBS: readonly string[];
+export const STORE_VERBS: readonly string[];
+/**
+ * The floor for `maxWallMs`: one default close timeout (`runClose`'s 120_000).
+ * Addendum 1 MEASURED that a wall deadline can only be read BETWEEN rounds —
+ * `loop.stop()` does not cut an in-flight call (fired at 500ms, returned at
+ * 4,018ms) — so enforcement is `maxWallMs + closeStages × closeTimeoutMs` (W5: a
+ * staged close runs every stage under the FULL timeout, ralph.js `runStages`).
+ * Under this floor the overshoot exceeds the budget itself and the advertised
+ * number would be more wrong than right, which is the advertised-must-equal-
+ * enforced line.
+ *
+ * The VALUE is a one-stage, default-timeout floor and is deliberately left alone —
+ * a threshold is operator territory, not something this module re-derives from a
+ * spec's own stage count. It therefore bounds only the degenerate case; a job with
+ * many stages or a raised `closeTimeoutMs` can still sit far above it while its
+ * overshoot dwarfs its cap. The clock reports that honestly (`closeStages` and
+ * `enforcedMs` are both on the `wall-clock` record) rather than the floor pretending
+ * to prevent it.
+ */
+export const MIN_WALL_MS: 120000;
 /** locked-but-listed tools: real capabilities deliberately outside the grant
  * menu. Requesting one is a DISTINCT `request-red` (module 4) — the ledger
  * counts admission demand, and a generic invalid-value would bury it as a typo. */

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/ledger.d.ts

@@ -3,7 +3,9 @@
  * bareloop vocabulary). Deliberate exclusions — bare cap-halt (a budget story),
  * close-verdict reds and artifact-red (worker stories, the §5b line), gate-red
  * (governance working as intended), pr-red (operator environment, not a suite
- * lib), smoke-red escalations (already counted via primitive-smoke), hitl-close
+ * lib), smoke-red escalations (already counted via primitive-smoke), step-stalled
+ * (our own fuse firing on an ABSENCE of beats — no observed lib failure to file),
+ * hitl-close
  * and close-unsupported (by design) — classify to nothing.
  * @param {any[]} events one spine's parsed events, in seq order
  * @param {{spine?: string}} [opts] spine id stamped into samples

package/types/plan.d.ts

@@ -1,3 +1,29 @@
+/**
+ * The MENU of legal `tree-changed` scopes — choose-don't-describe (design record
+ * §4, hamr's correction: *"did agent choose from a list or not?"*).
+ *
+ * F60 measured 13 of 18 validator reds as ONE class: the agent writes
+ * `scope: "src/*.js"`, the grammar accepts only a trailing `/**` or `/*`, and
+ * each red costs a redraft call. Teaching the rule in the prompt or widening the
+ * grammar both leave the agent authoring a free-text string and guessing its
+ * shape. Enumerating instead makes an illegal scope INEXPRESSIBLE.
+ *
+ * This is the only producer of scope menus, and it filters by the signed fence —
+ * so a menu entry that escapes containment cannot be constructed, rather than
+ * being caught by a downstream check. `globToPrefix` is untouched: this changes
+ * what the agent is OFFERED, never what the fence ENFORCES.
+ *
+ * @param {string[]} writeScope the signed fence entries (always offerable — they
+ *   cover directories a step has not created yet, which `snapshotScope` treats
+ *   as an empty snapshot)
+ * @param {string[]} [dirs] workdir-relative directories discovered under the
+ *   fence; each becomes `<dir>/**`
+ * @param {number} [cap] the menu bound; `Infinity` asks for the UNCAPPED set, so
+ *   a caller can report how many entries the cap dropped (no silent caps — a menu
+ *   that reads as complete when it is not is the blind-instrument class)
+ * @returns {string[]} the offerable scopes, deduped, shallowest-first, capped
+ */
+export function legalScopes(writeScope: string[], dirs?: string[], cap?: number): string[];
 /**
  * F49 — a heuristic reject for the catastrophic-backtracking footgun: an
  * unbounded quantifier applied to a group whose body itself repeats unboundedly
@@ -34,22 +60,66 @@
  * @returns {boolean} true iff a nested unbounded quantifier is present
  */
 export function hasNestedQuantifier(src: string): boolean;
+/**
+ * The close, as the ordered STAGE LIST the plan flow actually executes (PRD
+ * v1.28). A staged close is already that list; the legacy object form is the
+ * ONE-stage list it stands for, named `close`. Anything else — a gold, rubric or
+ * hitl close, which names no command to run — is null, and the runner escalates
+ * `close-unsupported` before any tokens.
+ *
+ * W4 — this is the ONE staging, and it exists because there used to be two. The
+ * runner synthesized the single stage and derived its check menu from THAT, while
+ * `planPrompt` and `validatePlan` called `checkMenu` on the RAW spec — where an
+ * object close is not an array, so the menu came back empty. The result was a
+ * runner announcing and preflighting a stage the drafter was never offered and the
+ * validator would have redded `check-unknown`. Same class as the two-transforms
+ * defects before it: the fix is one derivation every consumer calls, not three
+ * copies kept in step by comment.
+ *
+ * Lives here rather than beside `checkMenu` in job.js only because job.js owns the
+ * SIGNED vocabulary and this is the consumer-side reading of it; `plan.js` is the
+ * lowest module every check-menu consumer already imports (planrun imports plan,
+ * never the reverse), so it is the one place all three can share without a cycle.
+ * @param {any} close the spec's `close` field, any shape
+ * @returns {any[]|null} the stage list, or null when the close names no command
+ */
+export function stageClose(close: any): any[] | null;
 /** @typedef {{code: string, path: string, detail?: string, verb?: string}} Red */
 /**
  * Validate an agent-authored plan (`schema: "plan-v1"`) against the SIGNED
  * 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 }} [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
- *   tool-mode TURNS_PER_ATTEMPT) — a step may tighten it, never exceed it.
+ *   tool-mode TURNS_PER_ATTEMPT) — a step may tighten it, never exceed it;
+ *   `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 }?: {
+export function validatePlan(input: object | string, { job, maxStepRounds, scopes, seedRed, priorChecks }?: {
     job?: any;
     maxStepRounds?: number;
+    scopes?: string[];
+    seedRed?: string[];
+    priorChecks?: string[];
 }): {
     ok: boolean;
     reds: Red[];
@@ -65,13 +135,22 @@ export const MAX_EXITS_PER_STEP: 2;
 /** plan size bound — per-step rounds bound the spend, but an unbounded step
  * COUNT is still an unbounded claim on the wallet; same 8 as loop.maxIterations */
 export const MAX_PLAN_STEPS: 8;
-/** the write-class verbs (BA-13: `edit` is judged by the same fence as
- * `write`) — a step granting one is a WRITE step for the F17 pairing rule
- * and the v1.18 target requirement */
-export const WRITE_VERBS: readonly string[];
+export { WRITE_VERBS };
+/** scope-menu bound: the menu is a PROMPT ingredient on every draft and
+ * redraft, so an unbounded repo would price the drafting call by its directory
+ * count. Shallow entries survive the cap (see `legalScopes`) because they are
+ * the useful ones — a deep leaf is reachable via its parent. */
+export const MAX_SCOPE_MENU: 24;
+/** P (design record 2026-07-28): the signed per-step model-tier menu. Closed by
+ * construction — the agent picks a tier, never names an arbitrary model string
+ * (the tier→model mapping and any effort params are the RUNNER's, per provider).
+ * opus is deliberately absent: reserved for fresh builds hamr explicitly assigns,
+ * never plan-selectable. */
+export const STEP_MODELS: readonly string[];
 export type Red = {
     code: string;
     path: string;
     detail?: string;
     verb?: string;
 };
+import { WRITE_VERBS } from './job.js';

package/types/planrun.d.ts

@@ -1,5 +1,58 @@
 /**
- * Execute a validateJob-GREEN plan-shape job (goal/verdictType/close/checks[]).
+ * 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
+ * run.js draftPrompt precedent). Check NAMES only: a check's command is
+ * arbiter territory the planner never sees.
+ * @param {any} job @param {string} scoutBlob @param {any[]|null} reds
+ * @param {number} maxStepRounds @param {string|null} failure replan context
+ * @param {string[]|undefined} scopes the offered `tree-changed` menu (`legalScopes`).
+ *   Choose-don't-describe (§4): the agent picks a value, never authors a glob and
+ *   guesses its shape. Omitted, it derives from the signed fence — the SAME
+ *   fail-closed derivation `validatePlan` uses, so prompt and validator can never
+ *   disagree about what was offered.
+ * @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 {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;
+}, 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
  * function owns the plan flow only; the caller owns the job-end record and the
  * one ledger (every provider round is emitted here as `worker-round`, which
@@ -20,9 +73,25 @@
  * @param {() => number} opts.remainingUsd the one wallet: what is left of the signed budget right now
  * @param {() => boolean} [opts.isUnpriced] has any round come back with a null cost? (F6) — the
  *   plan flow bails IN-FLIGHT on the first unpriced round instead of burning the whole plan
- * @param {number} [opts.capRuns] shell-owned per-step attempt cap
+ * @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 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
+ *   reserved — a scout that spends every round on tools gets one toolless round to write its
+ *   survey, because the bound halts it mid-tool-use and text is its only deliverable)
  * @param {boolean} [opts.layerRoot=false] Layer R — the within-run ratchet (src/root.js),
  *   scoped PER STEP's ralph loop (each micro-wheel is the Layer-1 atom). Shell-assembled from
  *   the step's own books: per-attempt write-sets from the F32 workerWrites audit (teed for
@@ -32,11 +101,67 @@
  *   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' |
- *   'provider-red' | 'interpreter-red' | `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, emit, remainingUsd, isUnpriced, capRuns, closeTimeoutMs, maxStepRounds, layerRoot }: {
+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: {
@@ -48,10 +173,22 @@ export function runPlan(job: any, { workdir, provider, nativeProvider, emit, rem
     emit: (type: string, data?: object) => object;
     remainingUsd: () => number;
     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 & {
     category?: string;