bareloop 0.11.0 → 0.12.0

package/types/judged.d.ts

@@ -0,0 +1,280 @@
+/**
+ * The rubric card: Q6's answer compiled into enumerated items, signed by the
+ * person and enumerated in the spec hash. `rule` selects from `JUDGE_RULES`;
+ * `text` is the signer's own words, carried so a red can be explained in them.
+ *
+ * Wherever a schema takes free text but only a closed set can satisfy it, hand
+ * over the enumerated set — so `rule` is a SELECT and `text` is the only free
+ * field, and it decides nothing.
+ * @param {any} card
+ * @returns {{ok: boolean, reds: string[]}}
+ */
+export function validateCard(card: any): {
+    ok: boolean;
+    reds: string[];
+};
+/**
+ * THE CALIBRATION SET's gate. Never throws on proposed input — every failure is a
+ * named red in the shipped `{ok, reds}` shape.
+ *
+ * A CASE is `{id, artifact, expect: {verdict, reds: [{rule, fn}]}}`:
+ *   `artifact` is REAL TEXT — what LOCATE will actually be pointed at, never a
+ *   description of it; `verdict` is what `decide()` must render; and `reds` is the
+ *   ITEMIZED expectation, because the floor is *graded correctly WITH ITEMIZED
+ *   REDS* — a pipe that reds the right case for the wrong reason has not been
+ *   calibrated, it has been lucky. `rule` selects from the CARD's own lines (the
+ *   §4.3 ceiling made mechanical: the judge only ever checks lines the card
+ *   names) and `fn` is the address `decide()` itself reports.
+ *
+ * THE SIZE and THE POLARITY are separate reds on purpose: one is hamr's
+ * threshold, the other is *the test must be able to FAIL*. A set of ten that can
+ * only pass is exactly as unusable as a set of nine, and one red for both would
+ * send an operator to fix the wrong half.
+ *
+ * `card` is REQUIRED and its absence is a red rather than a skipped check — a
+ * validator handed no card would report a set it never examined against anything.
+ * @param {any} cases @param {{card?: any}} [o]
+ * @returns {{ok: boolean, reds: {code: string, path: string, detail: string, [k: string]: any}[]}}
+ */
+export function validateCalibrationSet(cases: any, { card }?: {
+    card?: any;
+}): {
+    ok: boolean;
+    reds: {
+        code: string;
+        path: string;
+        detail: string;
+        [k: string]: any;
+    }[];
+};
+/**
+ * BOTH signed artifacts, judged independently and reported together. The card
+ * goes through `validateCard` rather than a second spelling of it.
+ * @param {{card: any, cases: any}} o
+ * @returns {{ok: boolean, reds: {code: string, path: string, detail: string, [k: string]: any}[]}}
+ */
+export function validateJudgedArtifacts({ card, cases }: {
+    card: any;
+    cases: any;
+}): {
+    ok: boolean;
+    reds: {
+        code: string;
+        path: string;
+        detail: string;
+        [k: string]: any;
+    }[];
+};
+/**
+ * A `decide()` result reduced to the shape a case STORES. ONE spelling, so the
+ * expectation a signer signs and the reading module 5 takes off the live pipe are
+ * one shape read twice rather than two that can disagree.
+ *
+ * `why` and `quote` are deliberately dropped: both are the judge's prose about
+ * one emission, no signer can predict either, and pinning them would fail an
+ * honest pipe on wording. What survives is the ADDRESS — which card line, which
+ * function — which is what "itemized reds" means.
+ * @param {any} decision
+ * @returns {{verdict: string, reds: {rule: string, fn: string}[]}}
+ */
+export function expectedOf(decision: any): {
+    verdict: string;
+    reds: {
+        rule: string;
+        fn: string;
+    }[];
+};
+/**
+ * The SHAPE gate on a locate emission, and only the shape: is this the object
+ * the rest of the pipe can read at all? A shape miss is an ARTIFACT-RED — the
+ * emission is broken and the caller may buy another one.
+ *
+ * What is deliberately NOT here: per-rule field presence, and an empty function
+ * list. Both are well-formed emissions whose CONTENT is unusable, and content
+ * is `decide()`'s to red on (contract (a)) — routing them here would let a
+ * retry ladder spend money re-asking a model that answered perfectly clearly.
+ * It takes the facts and NOTHING else — no card. The shape of a locate emission
+ * is the same shape whatever the card asked for, and a second parameter nobody
+ * reads is a signature promising a coupling that does not exist.
+ * @param {any} facts
+ * @returns {{ok: boolean, reds: string[]}}
+ */
+export function validateFacts(facts: any): {
+    ok: boolean;
+    reds: string[];
+};
+/**
+ * The locate prompt for ONE card — the only derivation in this module, and it
+ * runs card → prompt, one hop, one direction. A rule the card did not name buys
+ * no prompt tokens and produces no facts nobody reads.
+ * @param {any} card @returns {string}
+ */
+export function locatePrompt(card: any): string;
+/**
+ * ONE locate attempt. The caller owns the ladder — this function has no retry,
+ * no cap and no opinion about how many times it should be called, because a
+ * retry is a spend decision and spend decisions are the arbiter's.
+ *
+ * THE AXIS PRECEDENCE, and the order is load-bearing:
+ *   1. THE CALL FAILED → `provider-red`. A thrown or errored call has no
+ *      knowable cost, so asking the meter about it would mislabel a transport
+ *      casualty as a broken meter and send the operator to fix the wrong thing.
+ *   2. THE COST IS NULL → `pricing-red`. Checked BEFORE the emission is even
+ *      looked at: a retry of an unpriced call buys more spend nobody can see,
+ *      so this is the non-retryable stop and it outranks every retryable one.
+ *   3. TRUNCATED → `provider-red`, on its own field, never folded into a parse
+ *      error. "The model was cut off" and "the model wrote nonsense" are two
+ *      findings, and one field spelling both is how a reader confuses them.
+ *   4. UNPARSEABLE or SHAPE-BROKEN → `artifact-red`. No repair, ever.
+ *
+ * On every route out, red or clean, `onCost` fires exactly once with the honest
+ * read: a paid call that leaves no meter record is F12 wearing a judge's coat.
+ * @param {{artifactText: string, card: any, loopFactory: (o: {provider?: any, system: string}) => any,
+ *   maxTokens?: number, attempt?: number, onCost?: (c: {costUsd: number|null, unpricedRounds: number}) => void}} o
+ * @returns {Promise<{ok: boolean, facts: any|null, red: {axis: string, detail: string}|null,
+ *   costUsd: number|null, unpricedRounds: number, truncated: boolean, parseError: boolean,
+ *   raw: ReturnType<typeof scrubRaw>}>}
+ */
+export function runLocate({ artifactText, card, loopFactory, maxTokens, attempt, onCost }: {
+    artifactText: string;
+    card: any;
+    loopFactory: (o: {
+        provider?: any;
+        system: string;
+    }) => any;
+    maxTokens?: number;
+    attempt?: number;
+    onCost?: (c: {
+        costUsd: number | null;
+        unpricedRounds: number;
+    }) => void;
+}): Promise<{
+    ok: boolean;
+    facts: any | null;
+    red: {
+        axis: string;
+        detail: string;
+    } | null;
+    costUsd: number | null;
+    unpricedRounds: number;
+    truncated: boolean;
+    parseError: boolean;
+    raw: ReturnType<typeof scrubRaw>;
+}>;
+/**
+ * Render the per-item verdicts over one locate result. PURE: same input, same
+ * output, forever — which is what makes a calibration set mean anything.
+ *
+ * FIRST-RED-WINS, in SIGNED CARD ORDER. Every item is still EVALUATED after the
+ * first red (calibration demands itemized reds, not a paragraph and not a short
+ * circuit); `firstRed` is the composed stage verdict's reason, and its
+ * stability comes from the card's own order rather than from whatever order the
+ * model happened to emit its functions in.
+ *
+ * `artifactText` is OPTIONAL and its absence is honest rather than lenient:
+ * with the artifact in hand every quote a rule consumes is verified to exist in
+ * it, and without it `decide()` simply does not make a claim it cannot support.
+ * Callers that HAVE the authoritative artifact (which is every real caller,
+ * since the same text was just judged) should always pass it.
+ * @param {any} facts a `runLocate` result's `facts`, or null
+ * @param {any} card
+ * @param {{artifactText?: string|null}} [opts]
+ * @returns {{verdict: 'pass'|'red', items: {rule: string, text: string, ok: boolean, reds: RuleRed[]}[],
+ *   firstRed: string|null, reason: string|null}}
+ */
+export function decide(facts: any, card: any, { artifactText }?: {
+    artifactText?: string | null;
+}): {
+    verdict: "pass" | "red";
+    items: {
+        rule: string;
+        text: string;
+        ok: boolean;
+        reds: RuleRed[];
+    }[];
+    firstRed: string | null;
+    reason: string | null;
+};
+/**
+ * THE JUDGE MODEL, PINNED. Never agent-selectable and never a step knob: it is
+ * the only tier with established injection resistance upstream (BA-20's
+ * INJECTION_BATTERY is haiku-4.5 only), and §4.2's whole safety argument is
+ * worth exactly as much as that evidence. A judge-model bump forces a full
+ * recalibration — mandatory, per the model-bump dead-weight replay rule.
+ *
+ * THAT IS ENFORCED, not asked for, and it is enforced in three places because a
+ * rule with no wired detector is prose (F45):
+ *   1. the value here is STORED with the set it graded — `foldJudgedArtifacts`
+ *      writes it as `closeDecl.calibration.judgeModel`, inside the spec, so
+ *      `jobSpecHash` covers it by construction. Bump this constant and every
+ *      signed judged spec hashes differently: the signature dies, and re-signing
+ *      is what re-runs the calibration gate.
+ *   2. `validateCloseDecl` REQUIRES it on any stored set — a set nobody can
+ *      attribute to a tier is a floor nobody can tell apart from a bumped one.
+ *   3. `runJudgedFloor` refuses to grade when the stored tier is not this one,
+ *      naming both models. It does not degrade in either direction: grading on
+ *      the new tier judges against a floor nobody calibrated, and the old tier is
+ *      not on offer.
+ */
+export const JUDGE_MODEL: "claude-haiku-4-5";
+/**
+ * The locate call's token ceiling. The POC's two real artifacts came back well
+ * inside 2000; this doubles that for headroom on a longer artifact, and the
+ * direction is fail-safe either way — a ceiling that binds produces a TRUNCATED
+ * emission, which is a red with its own field, never a silent partial pass. A
+ * caller may override it per call; it is a default, not a threshold.
+ */
+export const JUDGE_MAX_TOKENS: 4000;
+/** the label every locate call is metered and persisted under — one spelling */
+export const LOCATE_LABEL: "judged-locate";
+/**
+ * The THREE axes a locate attempt can fail on, enumerated because the caller
+ * ROUTES on them and a route decided by reading prose is the class this
+ * programme keeps paying for. All three are shipped bareloop classes, borrowed
+ * with their existing meanings intact:
+ *   - `pricing-red`  the meter is broken. NOT retryable: a retry buys more
+ *                    spend nobody can see.
+ *   - `provider-red` the call failed or was cut off. Retryable.
+ *   - `artifact-red` the call succeeded and its emission is unusable.
+ *                    Retryable, under the CALLER's cap — this module runs one
+ *                    attempt and owns no ladder.
+ */
+export const LOCATE_AXES: Readonly<{
+    PRICING: "pricing-red";
+    PROVIDER: "provider-red";
+    ARTIFACT: "artifact-red";
+}>;
+/**
+ * THE OWNED RULE TABLE. Frozen: the rulebook is the arbiter's, and a caller that
+ * could add a rule at runtime would be authoring the arbiter.
+ * @type {Readonly<Record<string, {id: string, ask: string, check: (fn: any, lines: Set<string>|null) => RuleRed[]}>>}
+ */
+export const JUDGE_RULES: Readonly<Record<string, {
+    id: string;
+    ask: string;
+    check: (fn: any, lines: Set<string> | null) => RuleRed[];
+}>>;
+/** the enumerated set a card may name — handed over verbatim in every refusal */
+export const JUDGE_RULE_IDS: readonly string[];
+/**
+ * THE SIZE — hamr, 2026-08-18, verbatim: *"go build 10, we could double later"*.
+ *
+ * Not a number measurement found, and not one the agent may revisit: a size
+ * change is a spec-level threshold change and stays operator territory (the
+ * standing no-agent-threshold-picking rule). The second half of his sentence is
+ * part of the ruling — doubling later is explicitly allowed — which is why it is
+ * ONE constant read by the schema, the validator and the refusal alike.
+ */
+export const CALIBRATION_SIZE: 10;
+/** the two verdicts a case may expect — `decide()`'s own closed set */
+export const CASE_VERDICTS: readonly string[];
+export function defaultJudgeLoop({ provider, system }: {
+    provider: any;
+    system: string;
+}): import("bare-agent").Loop;
+export type RuleRed = {
+    fn: string;
+    why: string;
+    quote: string | null;
+};
+import { scrubRaw } from './text.js';

package/types/kinds.d.ts

@@ -1,3 +1,22 @@
+/**
+ * Does this run end at a review door? The operator's flag WINS in both
+ * directions and is never inferred: `true` opens it for any class, `false` shuts
+ * it for any class, and `null`/absent is the class default above.
+ * @param {any} job the signed spec (its `verdictType` is the class)
+ * @param {boolean|null} [reviewDoor] the operator's explicit choice, or null
+ * @returns {boolean}
+ */
+export function doorOpens(job: any, reviewDoor?: boolean | null): boolean;
+/**
+ * The stages an `accept` re-runs: the MECHANICAL ones, and never a judged floor
+ * or a person (`SEED_EXEMPT_KINDS`, ruling 8's set, for the same reason it was
+ * drawn — a machine may re-prove a machine's reading, and may not re-prove a
+ * judgment). hamr's N4 ruling: an accept re-runs the mechanical stages, because a
+ * door lives 60 days and nothing freezes a tree.
+ * @param {any[]|null|undefined} stages
+ * @returns {any[]}
+ */
+export function mechanicalStages(stages: any[] | null | undefined): any[];
 /**
  * D8's seed, READ rather than typed: HEAD at run start. A close stores the
  * counting rule and never the number (D12), so which commit the run is measured
@@ -235,6 +254,60 @@ export function normalizeHumanRuling(ruling: any): {
     } | null;
     why: string | null;
 };
+/**
+ * WHICH ANSWER IS THIS LEG ACTING ON — the fresh one, or the one the checkpoint
+ * held? F102's cure needs one seam that can say, because two callers ask the same
+ * question (`runJob` declares the fold on `job-start` before `runPlan` reads the
+ * ruling at all), and two spellings of "is this a fresh engagement" is how the
+ * record and the clock come to disagree about the same leg.
+ *
+ * THE AMBIGUITY IS REFUSED, NEVER MERGED. A checkpoint that holds a decision and a
+ * command line that carries another are two answers to one question. Merging them
+ * picks a winner nobody chose; overriding silently discards words a person typed
+ * (the F98/F28 class at a process boundary). So it comes back as a refusal that
+ * NAMES the held decision, and the operator resolves it — by answering the held
+ * one, or by starting a fresh run against the tree as it stands.
+ *
+ * `fresh` is F103's half: a `rerun` is a FRESH ENGAGEMENT (design record §3.4 —
+ * *"redo/rerun comes with new authoring for money+time and keeps accounting of
+ * this far and this session separate counters"*), and nothing else is. An `accept`
+ * commissions no work and a `pause` runs nothing, so neither opens one.
+ *
+ * A REVIEW DOOR's rerun (module 8) is the SAME fact arriving one level out, and it
+ * is folded in here rather than beside the clock, because "is this a fresh
+ * engagement" gets ONE spelling — a second one is how a record and a clock come to
+ * disagree about the same leg, which is the very thing this resolver exists to
+ * prevent. It is deliberately NOT read as a ruling: a `humanRuling` answers a
+ * close's human STAGE and is refused for a close that has none, so the door's words
+ * stay in their own parameter and only this reading is shared.
+ *
+ * PRECEDENCE, stated because both CAN be handed to one leg: a door rerun makes the
+ * engagement fresh whatever the ruling says, and the two are OR'd, never merged.
+ * Freshness is the FAIL-SAFE direction — a fresh clock costs a leg nothing, while
+ * inheriting a dead leg's wall is F103's measured, structurally-impossible
+ * engagement. The door's own validation (empty words are refused) stays where it
+ * is, at the seam that accepts it.
+ * @param {any} fresh the answer arriving on this invocation (`--decide`), or null
+ * @param {any} held the answer the CHECKPOINT carries (`readResume`'s
+ *   `restart.pendingDecision`), or null. `receivedAt` is when the PERSON said it —
+ *   carried through so the resumed leg records the receipt, not its own re-reading.
+ * @param {any} [doorRerun] MODULE 8 — the review door's rerun, when this leg IS the
+ *   fresh engagement a signer commissioned at a previous run's door. Presence is the
+ *   whole of what is read here; the words are the accepting seam's business.
+ * @returns {{ok: boolean, why: string|null, ruling: {decision: string, text: string|null}|null,
+ *   source: 'operator'|'checkpoint'|null, receivedAt: string|null, fresh: boolean}}
+ */
+export function resolveHumanRuling(fresh: any, held: any, doorRerun?: any): {
+    ok: boolean;
+    why: string | null;
+    ruling: {
+        decision: string;
+        text: string | null;
+    } | null;
+    source: "operator" | "checkpoint" | null;
+    receivedAt: string | null;
+    fresh: boolean;
+};
 /**
  * Run ONE declared stage against a workdir at a seed.
  *
@@ -350,17 +423,45 @@ export const STOP_FAULTS: Readonly<{
 }>;
 export const AGGREGATES: readonly string[];
 export const SIGNS: readonly number[];
-/** every kind this executor implements. `judged-floor` / `human-confirms`
- * are catalogue entries and are deliberately absent here: declaring one is
- * counted demand (the request-red path), and reaching one at runtime is a
- * stop — never a red, and never a silent pass. */
+/** every kind this executor implements. It is asserted EQUAL to the catalogue's
+ * own live half by the suite, both directions: a kind the catalogue offers and
+ * this executor cannot run is a close that stops at runtime, and a kind this
+ * executor runs that the catalogue never names is a capability nothing can
+ * reach. `judged-floor` joined at softgreen module 2 — the runner and the
+ * catalogue unlock in ONE commit for exactly that reason. */
 export const LIVE_KINDS: readonly string[];
+/**
+ * The judged stage's ladder: ONE attempt plus ONE retry, and no more.
+ *
+ * The POC measured a malformed emission roughly 1 in 6, which is exactly the
+ * shape a single retry buys down and a longer ladder buys nothing more of — each
+ * further attempt is another paid call against the same unchanged artifact and
+ * the same unchanged prompt. It is a CEILING the arbiter owns, never a knob a
+ * declaration can widen: a stage that could re-ask a model forever is a stage
+ * that can spend a budget without ever rendering a verdict.
+ *
+ * A `pricing-red` is never retried at all (see `runJudgedFloor`): a retry of an
+ * unpriced call only buys more spend nobody can see (F6).
+ */
+export const JUDGE_ATTEMPTS: 2;
+/**
+ * The ceiling on how many artifacts ONE judged stage may buy a judgement of —
+ * the sibling of `MAX_TERMS` and `MAX_STAGES`, and here for the same reason: a
+ * runaway list is a bill, not a red. Enforced by the catalogue's validator
+ * before any token, so a declaration that names more is refused at the gate
+ * rather than discovered at the invoice.
+ */
+export const MAX_JUDGED_PATHS: 8;
 /** RULING 8 — the stages the seed-verdict read (D12) must NOT run. A judged
  * number at seed is unstable and a person at seed is an interview, not a
  * measurement; their bar comes from calibration (soft-green) or from the person
  * themselves (hitl), never from the seed. The skip is RECORDED by name rather
  * than taken in silence (F59: absent is not empty), so `seedRead` still returns
  * one row per declared stage. */
+/** the one kind a MODEL renders. Named once for the same reason `HUMAN_KIND` is:
+ * the authoring pipeline, the card, the catalogue and the close each key a
+ * decision on it, and five literals is how they come to disagree. */
+export const JUDGED_FLOOR_KIND: "judged-floor";
 export const SEED_EXEMPT_KINDS: readonly string[];
 /** the one kind a PERSON renders — named once, because the runner keys three
  * decisions on it (is there a door to answer, which stage paused, whose ruling
@@ -377,6 +478,29 @@ export const HUMAN_KIND: "human-confirms";
  * here forces a forever-decision at the one moment the person has least reason
  * to make one. */
 export const HUMAN_DECISIONS: readonly string[];
+/** the door's record type on the spine. It is a DISPOSITION, never a verdict:
+ * hamr's law, verbatim — *"it's important not to change the loop self verdict"*.
+ * The close mints the verdict before this is written, and nothing downstream of
+ * this record may change what the ledger recorded. */
+export const REVIEW_DOOR: "review-door";
+/** the terminals a door opens on: the verdict-bearing ones, and only those. A red,
+ * a casualty and a governance halt are not offered to a person as merchandise —
+ * they are already decision-ready in their own right, with their own levers. */
+export const DOOR_OPEN_OUTCOMES: readonly string[];
+/** the classes whose door opens WITHOUT being asked for. Soft-green is here
+ * because the judge is young: its green is quarantined at mint (module 6) and a
+ * person's `accept` is the only thing that releases the credit, so a run that
+ * never offered the door would hold its own credit forever.
+ *
+ * `green` is deliberately ABSENT, and that is the one operator-facing default in
+ * this module: a green-class run behaves exactly as it always has unless the
+ * runner asks for the door (`reviewDoor: true`, `--review-door`). PRD v1.71 §3
+ * says *"the door at the end of EVERY run"* and also that a green door is
+ * NON-BLOCKING, and the two readings differ only in whether an unasked-for door
+ * appears on an existing job's spine. Flipping it is one line — adding `'green'`
+ * here — and it is hamr's to flip, not this module's to assume. A constant, never
+ * a threshold; widening it is arbiter territory. */
+export const REVIEW_DOOR_CLASSES: readonly string[];
 /**
  * The arbiter's book NAMES, one home. F98's mechanism was exactly this list
  * living as independent literals: the fence deny arrays (src/planrun.js,
@@ -405,6 +529,16 @@ export type Red = {
  * territory: a declaration parameterises kinds, never the contracts.
  * `humanRuling` is the SIGNER's answer at a hitl pause, carried in from the
  * runner — never authored, never defaulted, and absent on every ordinary run.
+ * `judgeLoop` is the PAID seam the judged stage runs its locate call through, and
+ * it is operator territory for the same reason the worker's provider is: this
+ * module owns no provider and never picks one, and the judge tier is PINNED
+ * (`JUDGE_MODEL`) rather than chosen. Absent is not a fall-back to some other
+ * model — the stage stops as a wiring gap, the same answer `runPlan` gives a
+ * native job with no native factory.
+ * `onJudgeCost` is the METER, and it is the only reason a judged stage can be
+ * funded honestly: this executor cannot reach the run's ledger, so every locate
+ * call's cost is reported OUT through it, once per call, on every route including
+ * the red ones — a paid call that leaves no meter record is F12 in a judge's coat.
  * `onStage` is a REPORTING seam and nothing else: the seed read spawns a real
  * toolchain per stage (a suite is the slow one) and a whole read is one opaque
  * await, so the shell gets told as each stage lands. It decides nothing, it is
@@ -424,6 +558,19 @@ export type Ctx = {
         decision: string;
         text?: string | null;
     } | null;
+    judgeLoop?: (o: {
+        system: string;
+    }) => any;
+    onJudgeCost?: (c: {
+        stage: string | null;
+        kind: string | null;
+        path: string;
+        attempt: number;
+        label: string;
+        model: string;
+        costUsd: number | null;
+        unpricedRounds: number;
+    }) => void;
     onStage?: (row: {
         stage: string | null;
         kind: string | null;

package/types/planrun.d.ts

@@ -140,6 +140,12 @@ 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.
  */
 export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxStepRounds: number, failure: string | null, scopes: string[] | undefined, materials?: {
     balanceUsd?: number | null;
@@ -148,7 +154,7 @@ export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxS
 }, startingDraft?: object | null, checkFacts?: {
     seedRed?: string[];
     priorChecks?: string[];
-}): string;
+}, doorNote?: string | null): 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 +173,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
@@ -306,12 +319,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, scoutRounds, bridge, now, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, priorSpentUsd, reviewDoor, doorRerun }: {
     workdir: string;
     provider: any;
     nativeProvider?: ((o: {
@@ -320,6 +361,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;
@@ -348,6 +390,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