bareloop 0.6.0 → 0.8.0

package/types/reuse.d.ts

@@ -0,0 +1,392 @@
+/**
+ * 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. The REPLAN ledger (`priorReplans`/`priorReplanGrantUsed`)
+ * folds on this same mechanism and deliberately not on `readGradeSeed`'s: a grade seed
+ * feeds a readout, so its documented one-leg-per-resume shortening can only under-claim
+ * a direction, while an under-claimed CEILING is a refilled allowance and every kill
+ * would buy one (PRD v1.12 — the replan bound is the RUN's).
+ *
+ * **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/run.d.ts

@@ -34,9 +34,55 @@
  *   metered claude-json text provider for the toolless drafter); ignored on every Loop-driven provider
  * @param {(type: string, data?: object) => object} opts.emit spine emitter
  * @param {(tier: string) => any} [opts.providerFor] P: per-step model-tier provider factory (forwarded to the plan flow)
- * @param {number} [opts.capRuns] shell-owned per-step attempt cap
+ * @param {number} [opts.capRuns] shell-owned iteration cap for the plan flow's
+ *   CLOSE-FIX loop (a plan STEP runs under the strike ladder instead)
+ * @param {number} [opts.strikeLimit] shell-owned strike ceiling for a plan step's ladder
  * @param {number} [opts.shellCapUsd] the shell's hard USD ceiling
  * @param {number} [opts.closeTimeoutMs] close wall-clock cap (shell territory)
+ * @param {unknown} [opts.bridge] Layer 3 — a bridge-v1 entry to reuse as the drafter's
+ *   STARTING DRAFT (design record 2026-08-01, D4), forwarded to the plan flow. Omitted is
+ *   the cold path and is byte-identical to a pre-Layer-3 run. WHICH entry (the listing, an
+ *   operator pin, the LLM's pick) is the caller's decision, and so is what to do when the
+ *   load gate refuses one: a refusal returns the distinct `recipe-stale` outcome with zero
+ *   spend rather than silently drafting cold, because starting a paid run on a decision
+ *   nobody made is the same class of error as widening a cap to manufacture a green.
+ * @param {number} [opts.priorSpentUsd=0] RESUME (module C) — money a PREVIOUS, killed
+ *   attempt of this same try already spent. It seeds the ledger, so the restarted
+ *   attempt runs under the REMAINDER of the signed `budgetUsd` and the terminal
+ *   `job-end` states the try's WHOLE spend across both attempts. hamr's ruling: "a
+ *   budget ceiling folds in prior spend so re-invoking cannot silently widen it" —
+ *   the fold is the seam precisely because the CAP is in the spec hash, so
+ *   tightening the cap instead would make a new spec version needing a signature
+ *   nobody typed. The caller reconstructs the figure from the dead run's own spine.
+ * @param {boolean} [opts.priorSpendComplete=true] RESUME — was that fold EXACT?
+ *   `readResume` reports false when any round inside the dead attempt came back
+ *   unpriced, which makes the fold a FLOOR. The unknown does not heal by being carried
+ *   forward, so it rides one-way onto every `job-end` this run emits: a total built on
+ *   a floor is a floor, and reporting it as exact is F6 in a resume's coat.
+ * @param {number} [opts.priorWallMs=0] RESUME — the same ruling in a time coat: wall
+ *   time the killed attempt already consumed, folded into the run clock so the
+ *   restart gets the remainder of the SIGNED wall, never a fresh allotment.
+ * @param {any} [opts.resumeSeed] RESUME (module C v2) — WHERE inside the killed attempt
+ *   the kill landed, read off its own spine by `readResume`: the plan it accepted and the
+ *   steps that reached their exits. Forwarded verbatim to the plan flow, which reloads
+ *   the plan instead of re-scouting and re-drafting, and skips the finished steps.
+ *   hamr's ruling: *"start last step instead from the beginning, why would i want to
+ *   waste more money on something i already started"*. Absent is the ordinary path.
+ * @param {{stage?: string|null, value?: number|null}[]} [opts.resumeGrades] RESUME — the
+ *   close grades the killed leg recorded (`readResume`'s `restart.grades`), forwarded to
+ *   the plan flow as the trend's BASELINES. A resumed run's halt readout judges the whole
+ *   chain, not just the leg: without them a leg that re-grades an unchanged tree reports
+ *   `flat` — "revise the goal" — on a run that was converging when the money ran out.
+ *   Counts and stage names only; no close bytes cross this seam. Absent 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`), forwarded to the plan flow, which seeds its ceiling with
+ *   it. Its sibling above feeds a READOUT; this one feeds a BOUND, and that is the whole
+ *   difference: `replanned`/`varianceGrantUsed` are locals in `runPlan`, so without this
+ *   every kill hands the next leg a fresh allowance of an allowance PRD v1.12 makes the
+ *   RUN's ("unlimited replanning launders thrash as adaptation"). It also rides onto this
+ *   run's `job-start` as `priorReplans`, the declared-fold precedent `priorSpentUsd`
+ *   already sets, so a resume OF a resume folds once. Absent is the cold path.
  * @param {boolean} [opts.layerRoot=false] Layer R (within-run ratchet) — shell
  *        territory, threaded to the plan flow. Defaults OFF
  *        (decided 2026-07-21): fixation is extinct on every current job (F41), so
@@ -46,10 +92,10 @@
  *        binding.)
  * @returns {Promise<string>} outcome: 'green' | 'already-green' | 'escalated' |
  *   'unapproved-spec' | 'job-red' | 'smoke-red' | 'plan-red' | 'check-red' |
- *   'close-red' | 'close-unsupported' | 'pricing-red' | 'provider-red' |
+ *   'close-red' | 'close-unsupported' | 'recipe-stale' | 'pricing-red' | 'provider-red' |
  *   'interpreter-red' | 'cap-halt' | 'wall-halt' | 'step-stalled' | `step-red:<id>`
  */
-export function runJob(rawSpec: object | string, { approvals, workdir, provider, nativeProvider, providerFor, emit, capRuns, shellCapUsd, closeTimeoutMs, layerRoot }: {
+export function runJob(rawSpec: object | string, { approvals, workdir, provider, nativeProvider, providerFor, emit, capRuns, strikeLimit, shellCapUsd, closeTimeoutMs, layerRoot, bridge, priorSpentUsd, priorSpendComplete, priorWallMs, resumeSeed, resumeGrades, resumeReplans }: {
     approvals: unknown;
     workdir: string;
     provider: any;
@@ -62,8 +108,22 @@ export function runJob(rawSpec: object | string, { approvals, workdir, provider,
     emit: (type: string, data?: object) => object;
     providerFor?: ((tier: string) => any) | undefined;
     capRuns?: number | undefined;
+    strikeLimit?: number | undefined;
     shellCapUsd?: number | undefined;
     closeTimeoutMs?: number | undefined;
+    bridge?: unknown;
+    priorSpentUsd?: number | undefined;
+    priorSpendComplete?: boolean | undefined;
+    priorWallMs?: number | undefined;
+    resumeSeed?: any;
+    resumeGrades?: {
+        stage?: string | null;
+        value?: number | null;
+    }[] | undefined;
+    resumeReplans?: {
+        count?: number;
+        grantUsed?: boolean;
+    } | null | undefined;
     layerRoot?: boolean | undefined;
 }): Promise<string>;
 export type Red = {

package/types/selection.d.ts

@@ -0,0 +1,46 @@
+/**
+ * D3's listing: what the operator inspects and what the selecting model reads — the SAME
+ * text, so the two can never be choosing from different sets.
+ *
+ * Per bridge, one compact block: name, the job sentence it greened, status, greens/reds
+ * with the last outcome, and the cost/time band of its greens.
+ *
+ * Total and never throws: a listing is a display surface, and one malformed entry must
+ * not take the whole listing down (`listingRow` holds the same contract). Deterministic
+ * by name, whatever order the entries arrived in — a set that reshuffles between calls
+ * would make one picker's answer unreadable against another's.
+ *
+ * @param {unknown} registry `loadRegistry`'s result (`{ok, reds, bridges}`) or a bare
+ *   array of entries. The RESULT form is preferred: it carries the skip reds, and the
+ *   skips are the half a bare array cannot tell you about.
+ * @returns {string}
+ */
+export function renderListing(registry: unknown): string;
+/**
+ * The SELECT-WORKFLOW prompt: the text a later module sends to ask which workflow (if
+ * any) the run should start from. Pure — it sends nothing and parses nothing.
+ *
+ * D3's two standing rules are IN the prompt rather than enforced after the fact:
+ *  - *"none matches"* is a first-class answer, and it means the agent drafts new. A picker
+ *    with no way to decline would return the closest thing on the shelf every time, which
+ *    is how a registry becomes a lookup table.
+ *  - a PINNED workflow may be refused **only explicitly, with a reason** — never silently
+ *    ignored or quietly substituted. The operator's pick is the operator's; overriding it
+ *    invisibly is the one thing a picker must not be able to do.
+ *
+ * The output contract is stated so the answer is machine-readable, but the PARSE belongs
+ * to the runner that sends this (modules 4/5) — and the runner's parser and this shape are
+ * one contract in two places, which is why the shape is spelled out here rather than left
+ * to the model.
+ *
+ * @param {string} listing `renderListing`'s text — verbatim, so the picker sees exactly
+ *   what the human inspecting the registry sees
+ * @param {string} ask the job's goal sentence, in the operator's own words
+ * @param {string|null} [pinned] the operator's PIN, stated IN the call. D3 rules that a
+ *   pin is never bypassed and never silently overridden — so the pin does not skip the
+ *   call, it enters it, and the model's only legal ways out are confirming it or
+ *   refusing it by name with a reason. Stated here rather than assembled by the runner:
+ *   a second spelling of the pin sentence is a second prompt, and the two would drift.
+ * @returns {string}
+ */
+export function selectionPrompt(listing: string, ask: string, pinned?: string | null): string;

package/types/spine.d.ts

@@ -1,6 +1,13 @@
 /**
  * Create an emitter bound to one JSONL file.
  * @param {string} file absolute path; created on first emit
+ * @param {{startSeq?: number}} [opts] `startSeq`: the last `seq` already IN the file, for a
+ *   process that CONTINUES an existing spine (a resumed run appends to the dead run's own
+ *   log — module C). `seq` is monotonic per SPINE, so a second series restarting at 1
+ *   would give one append-only log two rows with the same number and silently break every
+ *   reader that orders by it. Default 0: a fresh file, which is every other caller.
  * @returns {(type: string, data?: object) => object} emit — returns the event as written
  */
-export function makeSpine(file: string): (type: string, data?: object) => object;
+export function makeSpine(file: string, { startSeq }?: {
+    startSeq?: number;
+}): (type: string, data?: object) => object;

package/types/trend.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Read one close gap into its stage and its count. Pure, and both halves are
+ * independently nullable: a gap with no header still yields its count, a gap
+ * with no red-marked line still yields its stage.
+ * @param {string} [gap] the close's gap, exactly as `runStages` built it
+ * @returns {{stage: string|null, value: number|null}}
+ */
+export function readGrade(gap?: string): {
+    stage: string | null;
+    value: number | null;
+};
+/**
+ * Build one trend reader. ONE PER SERIES: the money readout wants the whole run's
+ * close grades (the precheck is the seed the work is measured against), while the
+ * fix governor wants only the grades its own loop produced. Two instances, one
+ * rule — never one instance with a phase field, which is how a shared reader comes
+ * to answer two questions with one number.
+ *
+ * @param {object} [opts]
+ * @param {string[]} [opts.stageOrder] the staged close's stage names IN ORDER, so
+ *   "the run got further than it ever had" is readable. Empty disables that signal
+ *   entirely (an unknown ordering is unknown, never assumed).
+ * @param {number} [opts.limit] consecutive no-progress readings that strike the
+ *   loop out (default `FIX_STRIKE_LIMIT`).
+ * @param {number|null} [opts.blindCap] the RETIRED count, kept as the bound for
+ *   the case the instrument cannot read at all. Counted in iterations PAST the
+ *   baseline, so a blind loop runs exactly the number of attempts the old fixed
+ *   count bought it. `null` = no fallback bound (money and the wall still apply).
+ * @param {{stage?: string|null, value?: number|null}[]} [opts.seed] RESUME — the
+ *   grades a PREVIOUS leg of this same run already recorded, oldest first, read off
+ *   its own spine. Baselines only (see THE SEED above). Empty/omitted is the cold
+ *   path and is byte-identical to the pre-resume reader.
+ */
+export function createTrend({ stageOrder, limit, blindCap, seed }?: {
+    stageOrder?: string[] | undefined;
+    limit?: number | undefined;
+    blindCap?: number | null | undefined;
+    seed?: {
+        stage?: string | null;
+        value?: number | null;
+    }[] | undefined;
+}): {
+    /**
+     * Read one RED close grade. A green never reaches here (both callers stop on
+     * satisfied), so every reading is a failing grade by construction.
+     * @param {{gap?: string, stage?: string|null, value?: number|null}} o either a
+     *   raw gap (parsed here) or an already-read `{stage, value}` — never both
+     *   spellings of the same reading in one call.
+     * @returns {{iteration: number, stage: string, value: number|null, improved: boolean,
+     *   comparable: boolean, noProgress: number, limit: number, stageIndex: number}}
+     */
+    record({ gap, stage, value }?: {
+        gap?: string;
+        stage?: string | null;
+        value?: number | null;
+    }): {
+        iteration: number;
+        stage: string;
+        value: number | null;
+        improved: boolean;
+        comparable: boolean;
+        noProgress: number;
+        limit: number;
+        stageIndex: number;
+    };
+    /** has the loop run out of ideas — or, while the instrument is blind, out of
+     * the count it replaced? Money and the wall are unchanged and bound it either way.
+     * The blind arm counts the streak PAST its own first reading, the same `- 1` the
+     * blind-from-birth path always used: a streak's opening grade is the baseline the
+     * blind iterations are measured from, so a never-comparable run binds on exactly
+     * the reading it always did. */
+    struckOut: () => boolean;
+    /** the reader's own books. COUNTS AND STAGE NAMES ONLY — no close bytes ever
+     * enter a record from here, because the spine is append-only forever. */
+    report: () => {
+        iterations: number;
+        strikes: number;
+        limit: number;
+        blind: boolean;
+        stages: {
+            stage: string;
+            values: number[];
+        }[];
+    };
+    /**
+     * The DECISION-READY readout (PRD v1.46 §2): which way the run was going when
+     * something cut it, in the three verdicts hamr named, and the lever each
+     * implies. The library only reports — it never adjusts a budget (hard line).
+     * @returns {{trend: 'converging'|'flat'|'unknown', motion: 'changed'|'unchanged'|null,
+     *   reading: string, lever: string, series: {stage: string, values: number[]}[]}}
+     */
+    verdict(): {
+        trend: "converging" | "flat" | "unknown";
+        motion: "changed" | "unchanged" | null;
+        reading: string;
+        lever: string;
+        series: {
+            stage: string;
+            values: number[];
+        }[];
+    };
+};
+/** The strikes that end the close-fix loop. Shell-owned, exactly where the fixed
+ * count was, and the SAME number the step ladder uses — hamr's 2. Validated by a
+ * $0 replay over all 8 archived fix loops: 0 greens harmed (every historical
+ * fix-loop green converted in <= 2 verdicts) and 1 real waste case caught
+ * (reuse-msc6w93z, dead flat at 2 errors for 7 verdicts until the wall). */
+export const FIX_STRIKE_LIMIT: 2;