bareloop 0.10.0 → 0.12.0

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
@@ -211,6 +230,84 @@ export function parseValue(output: string, terms: any[], { scope, workdir }?: {
  * @returns {SeedTrees}
  */
 export function makeSeedTrees(): SeedTrees;
+/**
+ * THE SIGNER'S ANSWER, normalised at the seam that accepts it — the library half
+ * of the three-button gate (2026-08-12 §1).
+ *
+ * `null` is not a refusal: no ruling at all IS the pause path, which is how every
+ * ordinary run and every first leg of a hitl run arrives here. What is refused is
+ * an answer that is not one of the three doors, and — the case the POC's negative
+ * control measured — a `rerun` with no text. Ruling 3 makes the human's words the
+ * gap the worker converts from; an empty one launches a fix worker that re-runs
+ * as though nothing had been said, which is the failure this refusal exists for.
+ *
+ * It never throws and never repairs: a decision that cannot be read is handed
+ * back as a refusal with its reason, and the caller decides what to do about it.
+ * @param {any} ruling
+ * @returns {{ok: boolean, ruling: {decision: string, text: string|null}|null, why: string|null}}
+ */
+export function normalizeHumanRuling(ruling: any): {
+    ok: boolean;
+    ruling: {
+        decision: string;
+        text: string | null;
+    } | 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.
  *
@@ -254,13 +351,14 @@ export function seedRead(declaration: any, ctx: Ctx): Promise<StageResult[]>;
  * room would break a documented adopter contract for nothing; the new name says
  * exactly what differs. `src/declaredclose.js` is what bridges the two shapes.
  * @param {any} declaration @param {Ctx} ctx
- * @returns {Promise<{verdict: 'green'|'red'|'instrument-stop', exitCode: number, judged: boolean, firstRed: string|null, stages: StageResult[]}>}
+ * @returns {Promise<{verdict: 'green'|'red'|'instrument-stop'|'pause', exitCode: number|null, judged: boolean, firstRed: string|null, pausedAt: string|null, stages: StageResult[]}>}
  */
 export function runDeclaredClose(declaration: any, ctx: Ctx): Promise<{
-    verdict: "green" | "red" | "instrument-stop";
-    exitCode: number;
+    verdict: "green" | "red" | "instrument-stop" | "pause";
+    exitCode: number | null;
     judged: boolean;
     firstRed: string | null;
+    pausedAt: string | null;
     stages: StageResult[];
 }>;
 /** the close's two judgment exits — a stage's verdict, in the shape the
@@ -325,11 +423,84 @@ 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
+ * this is) and three literals is how they come to disagree */
+export const HUMAN_KIND: "human-confirms";
+/** the three doors the signer is offered at a hitl pause (2026-08-12 §1, doors
+ * re-cut 2026-08-17). No fourth door, and no free-text-only variant: a red that
+ * is not one of these two is not a ruling the run can act on.
+ *
+ * `cancel` was the third door and is DELETED as a concept (hamr: *"what's the
+ * point of cancel anyways? pause can resume — that would be more honest"*). The
+ * case it served — a person who looks and does not want to carry on — is a pause
+ * nobody returns to, which the 60-day checkpoint TTL retires on its own. Nothing
+ * 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,
@@ -356,6 +527,23 @@ export type Red = {
 /**
  * The arbiter's half of a stage run. Every field here is operator/runner
  * 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
+ * never consulted, and no verdict depends on it — the house pattern is
+ * `runJob`'s `emit` (the library reports, the shell prints).
  */
 export type Ctx = {
     workdir: string;
@@ -366,9 +554,40 @@ export type Ctx = {
     gapCap?: number;
     maxBuffer?: number;
     seedTrees?: SeedTrees;
+    humanRuling?: {
+        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;
+        verdict: string;
+        durationMs: number;
+    }) => void;
 };
+/**
+ * Six outcomes, and only two of them are verdicts. `pause` is N4's fifth: the
+ * close reached a stage a machine cannot render and is WAITING on a person —
+ * neither green nor red, and never graded (the F17 forbidden-zone rule applied
+ * to a non-verdict). `skipped` is the sixth and says a stage was deliberately
+ * not run at THIS reading (ruling 8's seed exemption), which is a different
+ * fact from `not-reached` (an earlier stage decided first).
+ */
 export type StageResult = {
-    verdict: "green" | "red" | "instrument-stop" | "not-reached";
+    verdict: "green" | "red" | "instrument-stop" | "not-reached" | "pause" | "skipped";
     exitCode: number | null;
     value: number | null;
     baseline: number | 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
@@ -294,12 +307,52 @@ export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxS
  *   it the deterministic name would collide with that very branch and the collision walk
  *   would mint a `-2` beside the progress the resume exists to keep. Absent is the cold
  *   path. A recorded branch that no longer exists is a STOP, never a fresh start.
+ * @param {{decision: string, text?: string}|null} [opts.humanRuling] N4 — the SIGNER's
+ *   answer at a hitl pause (2026-08-12 §1, re-cut 2026-08-17: accept | rerun <text> | pause), carried in
+ *   by the runner on the leg that RESUMES a paused run. Absent on every ordinary run and
+ *   on the leg that pauses; it is never authored, never defaulted, and never inferred.
+ *
+ *   It is spent ONCE, on this leg's close readings up to the moment the fix loop opens:
+ *   `accept` greens the human stage on fresh evidence (OPEN-3 — the mechanical stages
+ *   re-run first, because the tree can change while a run is paused), `rerun` reds it
+ *   with the human's own words as the gap, and `pause` keeps the checkpoint exactly as it
+ *   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' | `step-red:<id>`
+ *   '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 }: {
+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: {
@@ -308,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;
@@ -332,6 +386,22 @@ export function runPlan(job: any, { workdir, provider, nativeProvider, providerF
     spendComplete?: (() => boolean) | undefined;
     now?: (() => number) | undefined;
     resumeBranch?: string | null | undefined;
+    humanRuling?: {
+        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/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)
@@ -230,6 +234,43 @@ export function readResume(events: any[], { deathAt, direct, resumableOutcomes }
     direct?: boolean;
     resumableOutcomes?: string[];
 }): any;
+/**
+ * The AGE gate for a paused checkpoint — the sibling of `resumeTreeGate`, and it
+ * asks the other question a 60-day-old checkpoint raises. The tree gate asks
+ * *is this still the tree the run left?*; this asks *is this still a decision
+ * anyone is waiting on?*
+ *
+ * THREE things it deliberately does NOT do:
+ *
+ *  - it does not widen any other resume rule. The 2026-08-12 ruling is about a
+ *    person deciding, so `applies: false` on every other terminal: a cap-halt
+ *    checkpoint is a different stop under a different allowance, and quietly
+ *    ageing it out would be a governance change nobody ruled.
+ *  - it does not treat an unreadable stamp as young (F6). A checkpoint that
+ *    cannot say WHEN it paused has an unknown age, and unknown is refused rather
+ *    than rounded down to fresh — the direction that fails safe.
+ *  - it does not skip silently. An expired checkpoint comes back as a refusal
+ *    that NAMES the age and the TTL, because the operator's next move (start
+ *    fresh) depends on knowing which of the two it hit.
+ *
+ * The clock is injected for the same reason `runPlan`'s is: a rule measured in
+ * months cannot otherwise be tested at all.
+ *
+ * @param {any[]} events the paused run's own spine, parsed, in file order
+ * @param {{now?: () => number, ttlMs?: number}} [opts]
+ * @returns {{ok: boolean, applies: boolean, ageMs: number|null, ttlMs: number, pausedAt: string|null, detail: string|null}}
+ */
+export function checkpointAgeGate(events: any[], { now, ttlMs }?: {
+    now?: () => number;
+    ttlMs?: number;
+}): {
+    ok: boolean;
+    applies: boolean;
+    ageMs: number | null;
+    ttlMs: number;
+    pausedAt: string | null;
+    detail: string | null;
+};
 /**
  * The PATIENT gate for a resume, which is deliberately NOT the fresh-launch one.
  *
@@ -360,6 +401,143 @@ export function runReuse(opts: {
     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
@@ -384,6 +562,43 @@ export function runReuse(opts: {
  *    started.
  */
 export const REUSE_GRADED_RED: readonly string[];
+/**
+ * WHICH TERMINALS ARE A CHECKPOINT — the list a runner hands `readResume` as
+ * `resumableOutcomes`, minted HERE rather than in whichever script happens to
+ * launch a run.
+ *
+ * `readResume` deliberately takes it as a parameter and defaults to empty, and
+ * that stays true: the reuse loop's own semantics depend on the empty default.
+ * What did not exist was a canonical ANSWER, so `scripts/run-u.mjs` kept its own
+ * copy — and the exported bundle (PRD v1.44 §2: a thin runner with bareloop as a
+ * dependency) would have had to keep a third. The same reasoning that put the
+ * pause TTL in the library (OPEN-2, hamr, 2026-08-13) puts this here.
+ *
+ * Every entry is a stop that left WORK ON DISK and an allowance unspent — money,
+ * time, a self-healed stall, and now a person who has not answered yet. A verdict
+ * already rendered is never on this list: `green`/`escalated` are graded rows, and
+ * re-buying one would pay twice for an answer already in hand. (The signer's own
+ * `hitl-cancel` terminal used to be the other example; the door was deleted on
+ * 2026-08-17 — a person who does not want to carry on pauses, and the checkpoint
+ * they keep is retired by the TTL rather than by a terminal.)
+ *
+ * The human half is SPLICED IN from `declaredclose.js` rather than spelled again,
+ * because the try loop below reads the two halves differently and a second copy is
+ * how they would come to disagree about which member is which: the first three are
+ * allowances the loop's remaining tries are meant to spend against, and the human
+ * ones are the stop no further try can change (see `hardStop`).
+ */
+export const CHECKPOINT_OUTCOMES: readonly string[];
+/**
+ * THE PAUSE TTL (2026-08-12 §2): a hitl checkpoint is kept for 60 days.
+ *
+ * OPEN-2, RULED (hamr, in-turn, 2026-08-13): **the TTL lives in the LIBRARY**, so
+ * the exported bundle (a headless runner with bareloop as a dependency, PRD v1.44
+ * §2) inherits it instead of every runner re-implementing it. A script-only TTL
+ * would vanish on export — the one place the rule is most needed and least
+ * likely to be re-typed.
+ */
+export const PAUSE_TTL_MS: number;
 export type Red = {
     code: string;
     path: string;