bareloop 0.11.0 → 0.13.0

package/types/planrun.d.ts

@@ -78,6 +78,25 @@
  * @returns {string} the labelled block, or '' when there is nothing to show
  */
 export function closeGapBlock(gap: string | null | undefined): string;
+/**
+ * BA-21 — the WRITE side of the pricing-provenance signal (read side: `rateProvenance` /
+ * `spendProvenance` in src/ledger.js). bare-agent >=0.37 rides `rateSource` beside
+ * `pricing` on every metering payload; both metering callbacks below forward it onto the
+ * spine through THIS one helper, because two sites spelling one rule are two instruments
+ * (the ripgrep fix that landed in ci.yml but not publish.yml).
+ *
+ * Forwarded VERBATIM — the write side reports what upstream said, and src/ledger.js is
+ * the one place that decides what counts as a guess. And an ABSENT provenance stays
+ * absent: a payload carrying no `rateSource` (bare-agent <0.37, and every round already
+ * in the archive) emits no field at all, so a reader sees UNKNOWN rather than a label we
+ * invented. Never defaulted to `null` here — `null` is upstream saying "nothing was
+ * priced", which is a different fact from "nobody told us".
+ * @param {any} arg an `onLlmResult` / `onTurn` payload
+ * @returns {{rateSource?: string|null}} the field to spread into the spine record
+ */
+export function rateSourceFields(arg: any): {
+    rateSource?: string | null;
+};
 /**
  * What the NEXT attempt is told about the bound that cut the previous one.
  *
@@ -140,6 +159,16 @@ export function boundedNote(bounded: {
  *   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.
+ * @param {string|null} [doorNote] MODULE 8 — the signer's own words, when a previous run
+ *   of this spec ended at the review door and they took the RERUN door. Additive and
+ *   omitted-by-default, so every existing caller renders byte-identically. It is a
+ *   REQUIREMENT the plan must meet, never a replacement for the goal: the signed goal and
+ *   the signed close are unchanged, and what the person added is what the machine could
+ *   not see.
+ * @param {boolean|'cap'|'diff'} [readShim] the read shim's ARM. Does it carry G1? Then G1
+ *   is STATED as well as enforced (the mailbox precedent again: a law only the validator
+ *   knows costs a redraft per draft). The arms without it — `false` and `'diff'` — render
+ *   byte-identically to the pre-shim prompt.
  */
 export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxStepRounds: number, failure: string | null, scopes: string[] | undefined, materials?: {
     balanceUsd?: number | null;
@@ -148,7 +177,7 @@ export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxS
 }, startingDraft?: object | null, checkFacts?: {
     seedRed?: string[];
     priorChecks?: string[];
-}): string;
+}, doorNote?: string | null, readShim?: boolean | "cap" | "diff"): string;
 /**
  * Execute a validateJob-GREEN plan-shape job (goal/verdictType/close).
  * Called by runJob after the approval gate, validation, and the smoke — this
@@ -167,6 +196,13 @@ export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxS
  *   `false` → the drafter has no tools, so a native session would report NO cost — return a
  *   metered claude-json TEXT provider (`--output-format json`, `parse:'claude-json'`) instead,
  *   so its spend is never invisible. The Loop path (`anthropic-api`) never touches this.
+ * @param {any} [opts.judgeProvider] softgreen — the provider a JUDGED close stage runs its
+ *   locate call through, pinned by the operator to `JUDGE_MODEL` (src/judged.js). Separate
+ *   from `provider`/`providerFor` on purpose: the judge tier is not a step knob and never
+ *   agent-selectable, and the worker's binding is not a legal stand-in for it. Absent is not
+ *   a fall-back — a judged stage with no seam instrument-STOPS as a wiring gap, the same
+ *   answer a native job with no `nativeProvider` gets. A close with no judged stage never
+ *   reads it.
  * @param {(type: string, data?: object) => object} opts.emit spine emitter (the caller's METERED emit)
  * @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
@@ -190,6 +226,17 @@ export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxS
  * @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|'cap'|'diff'} [opts.readShim=false] THE READ SHIM (src/readshim.js) — the
+ *   ARM to run, one of the Phase 2 pre-registration's four: `false` (A0, off — the default),
+ *   `'cap'` (A1: cap + pointer + next-unseen-slice + G1), `'diff'` (A2: the diff lever alone,
+ *   no cap, no pointer, no G1), `true` (A3: every lever). Anything else THROWS at the entry
+ *   below rather than coercing into a truthy shim — a mis-spelled arm that silently ran A3
+ *   is a corrupted battery row, invisible afterwards.
+ *   OFF is byte-identical to the pre-shim run in every observable, G1 included: the frozen
+ *   A0 baseline arm must be exactly today's behaviour, and a guard firing under a disabled
+ *   shim would quietly make the baseline a treatment arm. The default-flip waits on a paid
+ *   contrast that has not been approved (the `layerRoot` precedent, F41 — an unproven lever
+ *   ships OFF and earns its default).
  * @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
@@ -306,12 +353,40 @@ export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxS
  *   is, before anything is read at all. After the fix loop opens the ruling is gone, so once the mechanical
  *   stages pass again the run PAUSES for a second review rather than converting the same
  *   sentence forever.
+ * @param {{decision: string, text?: string|null, receivedAt?: string|null}|null} [opts.heldRuling]
+ *   F102 — the decision the CHECKPOINT carries (`readResume`'s `restart.pendingDecision`):
+ *   an answer a person already gave, on a leg that stopped before a single round was
+ *   bought for it. It is applied exactly as a fresh one is, through the same seam, so
+ *   the person is never asked the same question twice; the spine records that it came
+ *   from a record rather than from a person, and `receivedAt` says when they said it.
+ *
+ *   A leg handed BOTH is refused (`hitl-decision-red`, naming the held decision): two
+ *   answers to one question is ambiguity, and a merge would pick a winner nobody chose.
+ *   Absent is every ordinary run and every leg the operator answers directly.
+ * @param {number} [opts.priorSpentUsd=0] F103 — money the CHAIN spent before this leg,
+ *   for the `engagement` record's money half ONLY. It bounds nothing here: the wallet
+ *   is the ledger's one level up, and `remainingUsd` already nets this fold against the
+ *   signed budget on every path (the signed budget is the chain's ceiling, and a rerun
+ *   spends what remains of it — never a refill). Reporting, never governance.
+ * @param {boolean|null} [opts.reviewDoor] MODULE 8 — does this run END at the review
+ *   door (PRD v1.71 §3)? `true`/`false` is the operator's explicit choice in either
+ *   direction; absent is the CLASS default (`doorOpens`): always for soft-green,
+ *   whose credit is held until a person accepts, and never for green-class unless
+ *   asked. It changes what the run RECORDS and never what it returns — the door is
+ *   a disposition, and the loop's verdict is not the door's to touch.
+ * @param {{text: string, fromRunid?: string|null, receivedAt?: string|null}|null} [opts.doorRerun]
+ *   MODULE 8 — the signer took the RERUN door on a previous run: a FRESH ENGAGEMENT
+ *   (§3.4) against the same signed spec, carrying their words. Two things follow, and
+ *   only two: the already-green shortcut is refused (the tree passing the close is
+ *   precisely the state the person rejected), and the words reach the PLANNER as new
+ *   authoring. It is never a `humanRuling` — that answers a close's human STAGE, and
+ *   a green-class job has none. Empty words are refused at the same seam every door is.
  * @returns {Promise<string>} 'green' | 'already-green' | 'escalated' | 'plan-red' |
  *   'check-red' | 'close-red' | 'close-unsupported' | 'recipe-stale' | 'pricing-red' |
  *   'branch-red' | 'cap-halt' | 'wall-halt' | 'provider-red' | 'interpreter-red' |
  *   'step-stalled' | 'hitl-pause' | 'hitl-decision-red' | `step-red:<id>`
  */
-export function runPlan(job: any, { workdir, provider, nativeProvider, providerFor, emit, remainingUsd, isUnpriced, spendComplete, capRuns, strikeLimit, closeTimeoutMs, maxStepRounds, layerRoot, scoutRounds, bridge, now, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling }: {
+export function runPlan(job: any, { workdir, provider, nativeProvider, providerFor, judgeProvider, emit, remainingUsd, isUnpriced, spendComplete, capRuns, strikeLimit, closeTimeoutMs, maxStepRounds, layerRoot, readShim, scoutRounds, bridge, now, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, priorSpentUsd, reviewDoor, doorRerun }: {
     workdir: string;
     provider: any;
     nativeProvider?: ((o: {
@@ -320,6 +395,7 @@ export function runPlan(job: any, { workdir, provider, nativeProvider, providerF
         maxTurns: number;
         hasTools: boolean;
     }) => any) | undefined;
+    judgeProvider?: any;
     emit: (type: string, data?: object) => object;
     remainingUsd: () => number;
     isUnpriced?: (() => boolean) | undefined;
@@ -329,6 +405,7 @@ export function runPlan(job: any, { workdir, provider, nativeProvider, providerF
     closeTimeoutMs?: number | undefined;
     maxStepRounds?: number | undefined;
     scoutRounds?: number | undefined;
+    readShim?: boolean | "cap" | "diff" | undefined;
     layerRoot?: boolean | undefined;
     bridge?: unknown;
     priorWallMs?: number | undefined;
@@ -348,6 +425,18 @@ export function runPlan(job: any, { workdir, provider, nativeProvider, providerF
         decision: string;
         text?: string;
     } | null | undefined;
+    heldRuling?: {
+        decision: string;
+        text?: string | null;
+        receivedAt?: string | null;
+    } | null | undefined;
+    priorSpentUsd?: number | undefined;
+    reviewDoor?: boolean | null | undefined;
+    doorRerun?: {
+        text: string;
+        fromRunid?: string | null;
+        receivedAt?: string | null;
+    } | null | undefined;
 }): Promise<string>;
 /**
  * The recorded bound-reason's ceiling in the WORKER-facing note. The reason is a

package/types/readshim.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Resolve the `readShim` flag into its arm. THROWS on anything else — the BA-4
+ * param-guard class, and deliberately not a red.
+ *
+ * An unrecognised value is OPERATOR input, arriving before a single token is
+ * spent, and there is exactly one safe way to fail on it: loudly, at once. The
+ * failure this guard exists to prevent is `readShim: 'diff '` (or 'Diff', or
+ * 'cap+diff') coerced by truthiness into A3 — a battery row that RAN the wrong
+ * arm, recorded the arm it was asked for, and is invisible in the results
+ * afterwards. That is the blind-instrument class this programme keeps paying
+ * for, and it would corrupt the contrast rather than merely fail a run.
+ *
+ * A red was the alternative and is wrong here twice over: a red is a verdict on
+ * the AGENT's work (the plan, the artifact), and this is the operator's own
+ * argument; and a red would need a terminal outcome name, which is arbiter
+ * territory and out of this change's scope.
+ * @param {boolean|'cap'|'diff'|undefined} [flag]
+ * @returns {ReadShimArm}
+ */
+export function readShimArm(flag?: boolean | "cap" | "diff" | undefined): ReadShimArm;
+/**
+ * The persona line this arm is entitled to — empty when the arm changes nothing
+ * the worker can perceive. One arm, one line: the two are never concatenated,
+ * because a cap arm has no diff and a diff arm has no cap.
+ * @param {ReadShimArm} arm
+ * @returns {string}
+ */
+export function readShimStrategy(arm: ReadShimArm): string;
+/** @typedef {{file: string, path: string, startLine: number, endLine: number, detail: string}} StaleReq */
+/** @typedef {{text: string, outcome: 'stale-served'|'stale-absent'|'stale-past-eof'}} StaleServe */
+/**
+ * Create the shim: one delivery ledger, and the two seams that speak for it.
+ *
+ * `wrapRead` is the read tool's wrapper (the ledger's only writer). `serveStale`
+ * is the answer to a stale `ctx_get` pointer, and it deliberately holds NO
+ * reference to the ledger — see its own note. Both live in one object because
+ * they are one worker's shim: the read seam and the retrieval seam the cap
+ * steers a capped worker towards.
+ * @param {{cap?: number, arm?: ReadShimArm}} [opts] `cap`: delivery bound in bytes (the
+ *   shipped value is `READ_SHIM_CAP`; the option exists so the native path can pin the
+ *   two bounds to one number rather than two constants drifting apart). `arm`: which
+ *   levers are live (`readShimArm`). Defaults to ALL of them, so every caller written
+ *   before the arms existed keeps the behaviour it was written against.
+ */
+export function createReadShim({ cap, arm }?: {
+    cap?: number;
+    arm?: ReadShimArm;
+}): {
+    arm: ReadShimArm;
+    cap: number;
+    wrapRead: (tool: {
+        name: string;
+        execute: (args: any) => Promise<any>;
+    }) => {
+        name: string;
+        execute: (args: any) => Promise<any>;
+    };
+    serveStale: ({ file, path, startLine, endLine, detail }: StaleReq) => StaleServe | null;
+};
+/**
+ * The one-tool spelling, kept for every caller written before the shim became an
+ * object: wrap this read tool with its own private ledger and hand it back.
+ * @param {{name: string, execute: (args: any) => Promise<any>}} tool
+ * @param {{cap?: number, arm?: ReadShimArm}} [opts]
+ * @returns {{name: string, execute: (args: any) => Promise<any>}} the same tool
+ */
+export function wrapReadTool(tool: {
+    name: string;
+    execute: (args: any) => Promise<any>;
+}, opts?: {
+    cap?: number;
+    arm?: ReadShimArm;
+}): {
+    name: string;
+    execute: (args: any) => Promise<any>;
+};
+/** The delivery cap, in bytes. Equal to `NATIVE_READ_CAP` by construction — the
+ * native path's CLI display bound and this cap bound the SAME seam, so one
+ * number keeps them from double-truncating each other (see planrun's wiring). */
+export const READ_SHIM_CAP: number;
+/** The legal spellings, in one place so an error message cannot drift from the
+ * set it describes. */
+export const READ_SHIM_ARMS: readonly string[];
+/** F19 at the bound rather than the verb (the NATIVE_READ_STRATEGY precedent):
+ * a cap the worker does not know about is a worker that reads the same file
+ * three times wondering why it keeps starting over. It states the bound, what a
+ * re-read does, and the two verbs that read a symbol whole — the capability the
+ * cap makes mandatory (G1). */
+export const READ_SHIM_STRATEGY: "\nREAD LIMIT: a shell_read of a file over 24KB returns only the next 24KB of it, followed by a notice saying which bytes you got. This is NOT the whole file. Reading the same path again continues where the last read stopped, and once you hold all of it a re-read says so instead of re-sending the bytes. To read a function IN FULL, use ctx_recall(<symbol>) then ctx_get(<pointer>) \u2014 that returns the entire function however large its file is. To locate a line, use shell_grep(<pattern>). Never try to understand a large file by reading it whole.";
+/** The DIFF arm's own line. It says nothing about a 24KB limit and nothing about
+ * continuation reads, because under A2 neither exists — a persona describing
+ * machinery that is off is a lie to the worker, and a worker rationing its reads
+ * against an imaginary cap is a different treatment than the arm names.
+ *
+ * It does not repeat the steer at ctx_recall/ctx_get either: that steer is the
+ * CAP's compensation (G1's other half), and offering it here would import half
+ * of A1 into A2. The delivery itself carries `diffNotice`'s framing inline; this
+ * line exists so the first diff is not a surprise. */
+export const READ_SHIM_DIFF_STRATEGY: "\nRE-READS: if you shell_read a file you have already been shown in full and it has changed since, the result is a unified DIFF against the copy you already hold \u2014 not the file itself. It is labelled as one. Lines starting '-' were removed, '+' were added, ' ' are unchanged context; apply it to the copy you have and you hold the current file.";
+export type StaleReq = {
+    file: string;
+    path: string;
+    startLine: number;
+    endLine: number;
+    detail: string;
+};
+export type StaleServe = {
+    text: string;
+    outcome: "stale-served" | "stale-absent" | "stale-past-eof";
+};
+export type ReadShimArm = {
+    on: boolean;
+    cap: boolean;
+    pointer: boolean;
+    diff: boolean;
+    g1: boolean;
+};

package/types/reuse.d.ts

@@ -136,7 +136,8 @@ export function reuseSpecHash(resolved: {
  * @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 }`
+ *   spendComplete, candidates, quarantineSkips, listing }` — `quarantineSkips` names every
+ *   workflow held back for want of a signer's accept, with its reason (module 6)
  */
 export function selectBridge({ registry, job, ask, provider, pinned, shortlist, forceCold, exclude }: {
     registry: unknown;
@@ -164,8 +165,11 @@ export function selectBridge({ registry, job, ask, provider, pinned, shortlist,
  *  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
+ * **F45 governs the arithmetic here.** A window's spend is summed from
+ * `ACCOUNTED_ROUND_TYPES` ONLY — the ledger's OWN list (src/run.js), imported rather
+ * than re-spelled, so a record `runJob` charges and this reader has never heard of
+ * cannot silently widen a resumed run's ceiling by exactly that amount. It was one
+ * event (`worker-round`) until the close itself could spend (`judge-round`). 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)
@@ -360,6 +364,7 @@ export function resumeTreeGate({ head, seed, dirty }: {
  * @param {number} [opts.strikeLimit] forwarded (a plan step's strike ceiling)
  * @param {number} [opts.closeTimeoutMs] forwarded
  * @param {boolean} [opts.layerRoot] forwarded
+ * @param {boolean|'cap'|'diff'} [opts.readShim] the read shim's ARM (A0/A1/A2/A3), forwarded verbatim
  * @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.
@@ -393,10 +398,148 @@ export function runReuse(opts: {
     strikeLimit?: number | undefined;
     closeTimeoutMs?: number | undefined;
     layerRoot?: boolean | undefined;
+    readShim?: boolean | "cap" | "diff" | undefined;
     resume?: any;
     runJob?: typeof shippedRunJob | undefined;
     now?: (() => number) | undefined;
 }): Promise<any>;
+/**
+ * WHAT A GREEN WRITES, in ONE place. Lifted verbatim out of `runReuse`'s own
+ * closure when the U runner needed it too (2B) — two spellings of "what a green
+ * writes" would be the two-transforms class applied to the ledger itself, which is
+ * the failure `greenParts` exists one level down to prevent.
+ *
+ * Two legs, and the split is which caller already holds an entry:
+ *   - A BRIDGE IN HAND (the reuse leg) APPENDS. No shape check is needed: `runJob`'s
+ *     load gate already proved at the door, before a token, that this entry is the
+ *     same kind of recipe as this job (a mismatch returns `recipe-stale` and never
+ *     gets here).
+ *   - NO BRIDGE (the cold leg, and every U run) mints — unless a name already holds
+ *     greens, in which case it APPENDS, because a cold run of a job that already has
+ *     a bridge is another version of that workflow and overwriting it would destroy
+ *     the green that minted it.
+ *
+ * But the name is the JOB's slug, and a job's CLOSE can be re-signed under that same
+ * slug. Appending across two close shapes does two wrong things at once: it counts a
+ * green another close rendered toward this entry's distinct-patient status (a false
+ * `proven`), and it hands the load gate — which matches on exactly these stage names
+ * — a plan that satisfied a different verification. So the shape is checked with the
+ * gate's own predicate, and a mismatch neither appends NOR discards the green: it
+ * forks to a deterministic derived name, with the fork ON the record.
+ *
+ * THE HOLD IS NOT DECIDED HERE. `quarantined` comes off `greenParts` reading the
+ * class the run was signed under (`record.verdictType`, module 6), so a caller that
+ * forgets to pass it mints an UNHELD green rather than a held one — which is why
+ * both callers pass the spec's own field and never a literal.
+ *
+ * KNOWN LIMIT, named rather than discovered later: `appendGreen` carries the entry's
+ * LABEL (`goal`, `closeStageNames`, `toolsUsed`) forward untouched, so a new version
+ * whose plan uses a verb the founding green did not is not reflected in `toolsUsed`.
+ * The load gate reads that field, so the gate's verb check goes slightly stale across
+ * versions. It is not a safety hole — the gate only ever gets more permissive there,
+ * and the TWEAKED plan still passes the full `validatePlan` against the job's signed
+ * menu at draft time, which is the check that actually decides. Fixing it properly
+ * means `appendGreen` taking a label update, which is module 1's contract and hamr's
+ * call, not something to change from the caller.
+ *
+ * Returns the WRITE RECORD both runners report — never throws, and a refusal is a
+ * record with `action: 'none'` and named reds rather than an absence a reader has to
+ * branch on.
+ * @param {{registryDir: string, bridge?: any|null, meta: any, record: any}} o
+ * @returns {{name: string|null, action: string, file: string|null, reds: any[], [k: string]: any}}
+ */
+export function writeGreenRow({ registryDir, bridge, meta, record }: {
+    registryDir: string;
+    bridge?: any | null;
+    meta: any;
+    record: any;
+}): {
+    name: string | null;
+    action: string;
+    file: string | null;
+    reds: any[];
+    [k: string]: any;
+};
+/**
+ * THE U RUNNER'S TERMINAL WRITE (2B) — does the run that just ended earn a registry
+ * row, and if so, write it.
+ *
+ * `scripts/run-u.mjs` has always kept standalone bridge FILES and never a registry,
+ * so its review door could describe a held learning credit it had no row to release:
+ * `--decide accept` reached `recordDoor`, found no green row for the runid and died
+ * `no-row-for-run`. This is the row, and STORAGE IS ALL IT IS — selection, promotion
+ * and reuse execution stay parked (layer-3-reuse). Nothing here reads a row back.
+ *
+ * FOUR REFUSALS, each one a guard that already existed somewhere and is kept:
+ *   - NO REGISTRY, no row. The registry path is operator-supplied and never
+ *     conjured; without one the door says, in words, that nothing was released.
+ *   - ALREADY-GREEN mints nothing. The close was satisfied before this run did
+ *     anything, so nothing here earned a version — the reuse-credit leak block, from
+ *     the writing side rather than the door's.
+ *   - A GREEN WITH NO PLAN mints nothing. The artifact that inherits is the one that
+ *     RAN, and there is none (R1).
+ *   - A CLASS WHOSE CREDIT IS NOT HELD mints nothing HERE. That is `green` today, and
+ *     it is main's behaviour kept rather than a new rule: this runner has never
+ *     written a registry row for a green-class run, and widening what enters the
+ *     registry is a reuse-rung question, not a side effect of fixing a door. The
+ *     predicate is `quarantinesCredit` — the ONE spelling of "is this class held" —
+ *     so the row this runner mints and the row a door releases can never disagree
+ *     about which classes they are talking about.
+ *
+ * The row is born HELD for exactly the reason any judged green is: `greenParts` reads
+ * `verdictType` off the record. Nothing here sets the flag.
+ * @param {{registryDir: string|null|undefined, job: any, name: string|null,
+ *   outcome: string, plan: any, record: any}} o
+ * @returns {{minted: boolean, reason: string|null, write: any|null}}
+ */
+export function writeRunGreenRow({ registryDir, job, name, outcome, plan, record }: {
+    registryDir: string | null | undefined;
+    job: any;
+    name: string | null;
+    outcome: string;
+    plan: any;
+    record: any;
+}): {
+    minted: boolean;
+    reason: string | null;
+    write: any | null;
+};
+/**
+ * Apply a signer's door decision to the workflow a run wrote its row against:
+ * record the disposition, and — on `accept` over a HELD judged green — release the
+ * learning credit that green has been carrying unspent (PRD v1.71 §3).
+ *
+ * This is the ONE seam between a person's answer and the box. It is deliberately
+ * separate from `runReuse`: the door opens AFTER the run has ended (a green run is
+ * over, non-blocking, and the person may answer minutes or days later), so the
+ * decision cannot ride the run's own return path. The runner calls this with the
+ * runid it printed at the door.
+ *
+ * Never throws and never conjures: a missing registry, a missing entry, a
+ * malformed one and a runid with no green row all come back as named reds. The
+ * loop's verdict is untouched in every branch — this writes a disposition, never a
+ * result.
+ *
+ * @param {object} opts
+ * @param {string} opts.registryDir the operator-supplied registry directory
+ * @param {string} opts.name the workflow the run wrote to
+ * @param {string} opts.runid the RUN's id, exactly as the bridge row records it
+ * @param {string} opts.decision one of the three doors
+ * @param {string|null} [opts.at] when the person answered
+ * @returns {{ok: boolean, reds: any[], released: boolean, file: string|null}}
+ */
+export function applyDoorDecision({ registryDir, name, runid, decision, at }: {
+    registryDir: string;
+    name: string;
+    runid: string;
+    decision: string;
+    at?: string | null | undefined;
+}): {
+    ok: boolean;
+    reds: any[];
+    released: boolean;
+    file: string | null;
+};
 /** @typedef {{code: string, path: string, detail?: string}} Red */
 /**
  * The GRADED-RED set: the runJob outcomes in which the operator's close actually

package/types/reviewdoor.d.ts

@@ -0,0 +1,81 @@
+/** the door's own record, off the run's spine — the LAST one, because a run that
+ * ends at a door writes exactly one and a reader that guesses which is which is a
+ * reader that will one day answer the wrong question.
+ * @param {any[]} events the run's spine, parsed
+ * @returns {any|null} */
+export function doorRecordOf(events: any[]): any | null;
+/**
+ * IS THE DOOR STILL OPEN? The same 60-day TTL a hitl checkpoint keeps
+ * (`PAUSE_TTL_MS`) and deliberately the same NUMBER — the door replaced `cancel`
+ * precisely because an unanswered door and an unresumed pause are one state, and
+ * two TTLs for one state is how they come to disagree.
+ *
+ * An UNREADABLE stamp refuses too: unknown is not young (F6). Reading the age is
+ * not the same as deciding on it, so this states both the answer and the arithmetic.
+ * @param {any} door the door record
+ * @param {{now?: () => number, ttlMs?: number}} [opts]
+ * @returns {{ok: boolean, ageMs: number|null, ttlMs: number, detail: string}}
+ */
+export function doorAgeGate(door: any, { now, ttlMs }?: {
+    now?: () => number;
+    ttlMs?: number;
+}): {
+    ok: boolean;
+    ageMs: number | null;
+    ttlMs: number;
+    detail: string;
+};
+/**
+ * Answer a run's review door.
+ *
+ * Never throws and never conjures: a malformed decision, a run that opened no
+ * door, an expired one, a tree that moved and a registry that is not there all
+ * come back as named reds. The loop's verdict is untouched on every path — this
+ * function has no way to write one.
+ *
+ * @param {object} opts
+ * @param {any} opts.job the SIGNED spec the run was judged by (its close is what an accept re-proves)
+ * @param {string} opts.workdir the patient, as it stands NOW
+ * @param {any[]} opts.events the run's own spine, parsed
+ * @param {string} opts.decision one of the three doors
+ * @param {string|null} [opts.text] the rerun's words — the gap, and refused when empty
+ * @param {number} [opts.closeTimeoutMs] the per-stage bound for the accept's re-run
+ * @param {string|null} [opts.registryDir] the workflow registry, when the runner keeps one
+ * @param {string|null} [opts.name] the workflow this run wrote its row against
+ * @param {string|null} [opts.runid] the RUN's id, exactly as the bridge row records it
+ * @param {string|null} [opts.at] when the person answered
+ * @param {() => number} [opts.now] the clock, injected for the TTL
+ * @param {number} [opts.ttlMs]
+ * @param {((type: string, data: any) => any)|null} [opts.emit] the run's spine, to record the disposition on
+ * @returns {Promise<{ok: boolean, decision: string|null, next: string|null, released: boolean,
+ *   doorRecorded: boolean, reds: any[], mechanical: any, door: any, text: string|null,
+ *   options: string[], ttlMs: number, note: string|null}>}
+ */
+export function answerReviewDoor({ job, workdir, events, decision, text, closeTimeoutMs, registryDir, name, runid, at, now, ttlMs, emit, }: {
+    job: any;
+    workdir: string;
+    events: any[];
+    decision: string;
+    text?: string | null | undefined;
+    closeTimeoutMs?: number | undefined;
+    registryDir?: string | null | undefined;
+    name?: string | null | undefined;
+    runid?: string | null | undefined;
+    at?: string | null | undefined;
+    now?: (() => number) | undefined;
+    ttlMs?: number | undefined;
+    emit?: ((type: string, data: any) => any) | null | undefined;
+}): Promise<{
+    ok: boolean;
+    decision: string | null;
+    next: string | null;
+    released: boolean;
+    doorRecorded: boolean;
+    reds: any[];
+    mechanical: any;
+    door: any;
+    text: string | null;
+    options: string[];
+    ttlMs: number;
+    note: string | null;
+}>;

package/types/run.d.ts

@@ -34,6 +34,13 @@
  *   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 {any} [opts.judgeProvider] SOFTGREEN — the provider a JUDGED close stage runs its
+ *   locate call through, wired by the operator and PINNED to `JUDGE_MODEL` (src/judged.js:
+ *   the only tier with established injection resistance upstream). Forwarded to the plan
+ *   flow. It is its own seam and not `provider`/`providerFor`, because the judge tier is
+ *   never a step knob and never agent-selectable; absent, a judged stage instrument-stops as
+ *   a wiring gap rather than grading on whatever binding happened to be at hand. Its spend
+ *   lands on this ledger as `judge-round` (see `ACCOUNTED_ROUND_TYPES`).
  * @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
@@ -90,6 +97,19 @@
  *   collision walk would mint a `-2` beside the work the resume exists to continue. The
  *   fold's precedent exactly: the chain's state is DECLARED, never re-derived. Forwarded
  *   verbatim to the plan flow; absent is the cold path.
+ * @param {boolean|'cap'|'diff'} [opts.readShim=false] THE READ SHIM (src/readshim.js) —
+ *        WHICH ARM to run, threaded to the plan flow. The Phase 2 pre-registration's four:
+ *          `false`  A0 — off (the default)
+ *          `'cap'`  A1 — cap + pointer + next-unseen-slice + G1, no diff
+ *          `'diff'` A2 — the diff lever alone: no cap, no pointer, no G1
+ *          `true`   A3 — every lever
+ *        Anything else THROWS below, before a token is spent: a mis-spelled arm coerced
+ *        by truthiness into A3 would run one treatment under another's label and be
+ *        invisible in the results afterwards.
+ *        OFF is byte-identical to the pre-shim run in every observable (G1 included): the
+ *        frozen A0 baseline arm has to be exactly today, so a guard firing under a disabled
+ *        shim would make the baseline a treatment arm. The default-flip belongs to a
+ *        paid contrast nobody has approved yet (the `layerRoot` precedent, F41).
  * @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
@@ -102,13 +122,26 @@
  *   RESUMES a paused run and forwarded verbatim to the plan flow. Absent on every
  *   ordinary run; never authored and never defaulted (a defaulted answer to "is this
  *   done?" is the rubber-stamp the class exists to prevent, 2026-08-12 §4).
+ * @param {{decision: string, text?: string|null, receivedAt?: string|null}|null} [opts.heldRuling]
+ *   F102 — the answer the CHECKPOINT holds (`readResume`'s `restart.pendingDecision`):
+ *   a decision a person already gave on a leg that stopped before a single round was
+ *   bought for it. Forwarded verbatim; the plan flow applies it exactly as a fresh one
+ *   and refuses a leg handed both. It is also what decides whether the TIME fold this
+ *   run declares is the chain's or this engagement's (F103).
+ * @param {boolean|null} [opts.reviewDoor] MODULE 8 — does this run END at the review
+ *   door (PRD v1.71 §3)? Forwarded verbatim to the plan flow, which owns the class
+ *   default. It changes what the run RECORDS and never what it returns: the door is a
+ *   disposition and the loop's verdict is not the door's to touch.
+ * @param {{text: string, fromRunid?: string|null, receivedAt?: string|null}|null} [opts.doorRerun]
+ *   MODULE 8 — this leg IS the fresh engagement a signer commissioned at a previous
+ *   run's review door, carrying their words. Forwarded verbatim.
  * @returns {Promise<string>} outcome: 'green' | 'already-green' | 'escalated' |
  *   'unapproved-spec' | 'job-red' | 'smoke-red' | 'plan-red' | 'check-red' |
  *   'close-red' | 'close-unsupported' | 'recipe-stale' | 'branch-red' | 'pricing-red' | 'provider-red' |
  *   'interpreter-red' | 'cap-halt' | 'wall-halt' | 'step-stalled' |
  *   'hitl-pause' | 'hitl-decision-red' | `step-red:<id>`
  */
-export function runJob(rawSpec: object | string, { approvals, workdir, provider, nativeProvider, providerFor, emit, capRuns, strikeLimit, shellCapUsd, closeTimeoutMs, layerRoot, bridge, priorSpentUsd, priorSpendComplete, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling }: {
+export function runJob(rawSpec: object | string, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider, emit, capRuns, strikeLimit, shellCapUsd, closeTimeoutMs, layerRoot, readShim, bridge, priorSpentUsd, priorSpendComplete, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun }: {
     approvals: unknown;
     workdir: string;
     provider: any;
@@ -120,6 +153,7 @@ export function runJob(rawSpec: object | string, { approvals, workdir, provider,
     }) => any) | undefined;
     emit: (type: string, data?: object) => object;
     providerFor?: ((tier: string) => any) | undefined;
+    judgeProvider?: any;
     capRuns?: number | undefined;
     strikeLimit?: number | undefined;
     shellCapUsd?: number | undefined;
@@ -138,12 +172,40 @@ export function runJob(rawSpec: object | string, { approvals, workdir, provider,
         grantUsed?: boolean;
     } | null | undefined;
     resumeBranch?: string | null | undefined;
+    readShim?: boolean | "cap" | "diff" | undefined;
     layerRoot?: boolean | undefined;
     humanRuling?: {
         decision: string;
         text?: string;
     } | null | undefined;
+    heldRuling?: {
+        decision: string;
+        text?: string | null;
+        receivedAt?: string | null;
+    } | null | undefined;
+    reviewDoor?: boolean | null | undefined;
+    doorRerun?: {
+        text: string;
+        fromRunid?: string | null;
+        receivedAt?: string | null;
+    } | null | undefined;
 }): Promise<string>;
+/** @typedef {{code: string, path: string, detail?: string}} Red */
+/**
+ * THE ROUND RECORDS THE ONE LEDGER SUMS — as data, because two of them now exist
+ * and a hand-spelled condition per record is how a paid call comes to be free.
+ *
+ * `worker-round` is the attempt's own spend, metered per ROUND rather than per
+ * attempt-return (F12: a halted attempt's spend was invisible by 300×).
+ * `judge-round` is the CLOSE's, and it is the first spend a close has ever had:
+ * the judged floor (softgreen) buys a pinned locate call per artifact, and the
+ * budget-identity rule is that a budget funds the attempt PLUS its close. Both
+ * carry the honest `costUsd` — a null lands as `unpriced` and halts, never as $0.
+ *
+ * What is deliberately NOT here: `worker-result` / `worker-plan`, which are
+ * attempt TOTALS of the same rounds and would double-count.
+ */
+export const ACCOUNTED_ROUND_TYPES: readonly string[];
 export type Red = {
     code: string;
     path: string;