bareloop 0.11.0 → 0.12.0

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)
@@ -397,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

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
@@ -102,13 +109,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, bridge, priorSpentUsd, priorSpendComplete, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun }: {
     approvals: unknown;
     workdir: string;
     provider: any;
@@ -120,6 +140,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;
@@ -143,7 +164,34 @@ export function runJob(rawSpec: object | string, { approvals, workdir, provider,
         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;