bareloop 0.22.0 → 0.24.0

package/types/index.d.ts

@@ -15,7 +15,7 @@ export { workBranchName, prepareWorkBranch, WORK_BRANCH_PREFIX, WORK_BRANCH_RE }
 export { createReadShim, wrapReadTool, readShimArm, readShimStrategy, READ_SHIM_CAP, READ_SHIM_STRATEGY, READ_SHIM_DIFF_STRATEGY, READ_SHIM_ARMS } from "./readshim.js";
 export { runDeclaredClose, runStage, seedRead, seedAtHead, seedListing, changedSet, makeSeedTrees, LIVE_KINDS, STOP_FAULTS, JUDGED_MARKER, EXIT_GREEN, EXIT_RED, EXIT_STOP, HUMAN_DECISIONS, SEED_EXEMPT_KINDS, JUDGED_FLOOR_KIND, normalizeHumanRuling, resolveHumanRuling, JUDGE_ATTEMPTS, MAX_JUDGED_PATHS, REVIEW_DOOR, DOOR_OPEN_OUTCOMES, REVIEW_DOOR_CLASSES, doorOpens, mechanicalStages } from "./kinds.js";
 export { answerReviewDoor, doorRecordOf, doorAgeGate } from "./reviewdoor.js";
-export { JUDGE_MODEL, JUDGE_MAX_TOKENS, JUDGE_RULES, JUDGE_RULE_IDS, LOCATE_AXES, LOCATE_LABEL, validateCard, validateFacts, locatePrompt, runLocate, decide, defaultJudgeLoop, CALIBRATION_SIZE, CASE_VERDICTS, validateCalibrationSet, validateJudgedArtifacts, expectedOf } from "./judged.js";
+export { JUDGE_MODEL, resolveJudge, JUDGE_MAX_TOKENS, JUDGE_RULES, JUDGE_RULE_IDS, LOCATE_AXES, LOCATE_LABEL, validateCard, validateFacts, locatePrompt, runLocate, decide, defaultJudgeLoop, CALIBRATION_SIZE, CASE_VERDICTS, validateCalibrationSet, validateJudgedArtifacts, expectedOf } from "./judged.js";
 export { proposeJudgedArtifacts, signJudgedArtifacts, foldJudgedArtifacts, proposalSchema, proposalTool, cardCasesPrompt, PROPOSAL_TOOL_NAME, PROPOSAL_LABEL, MAX_PROPOSAL_RETRIES, COMPILE_SYSTEM } from "./cardauthor.js";
 export { runCalibration, compareExpectation, factsResist, artifactHash, INJECTION_LOCATE_BATTERY, INJECTION_CARD, CALIBRATION_LABEL, CASUALTY_AXES } from "./calibrate.js";
 export { validateDeclaration, normalizeDeclaration, KIND_CATALOGUE, CATALOGUE_KINDS, CATALOGUE_LIVE_KINDS, LOCKED_KINDS, TYPES_GENRE, TYPES_GENRE_TEMPLATE, GENRE_LANGUAGES, genreEnv, genreOwnedEnvNames, genreInstruments, DIRECTIONS, BASELINES, MAX_STAGES, VERDICT_CLASSES, LOCKED_CLASSES, LIVE_CLASSES, CLASS_BATTERIES, classGuards, classMenu, closeCeiling, NEVER_OFFERED_KINDS } from "./authoring.js";

package/types/job.d.ts

@@ -207,6 +207,31 @@ export const CADENCE_UNITS: readonly string[];
  * subscription — its costUsd axis is NOTIONAL (API-equivalent value, not
  * billed), so it is a DISTINCT condition: rows never pool with anthropic-api
  * rows on the cost axis, and budgets sized for one do not transfer. */
+/** PRD item 28 (2026-09-06/09-09): `openai-api` — an OpenAI-shaped provider,
+ * constructed via `src/providers.js`'s factory. hamr's ruling (PRD 30.7):
+ * `deepseek-chat` is THE secondary provider (one, not a menu of half-tested
+ * models); the factory's tier table is where that lives, not this menu.
+ *
+ * PRD item 31.3 (hamr, 2026-09-09: *"anthropic, openai, gemini drop ollama for
+ * now"*): `gemini-api` joins. That is bareloop matching bare-agent's own
+ * adapter surface rather than curating a shorter list — bare-agent exports four
+ * real HTTP backends (Anthropic, OpenAI, Gemini, Ollama) plus CLIPipe and the
+ * FallbackProvider composite; `provider-http.js`, `provider-stop-reason.js`,
+ * `provider-temperature.js` and `provider-usage.js` are shared HELPERS, not
+ * backends, and were miscounted as providers once — the export list, never the
+ * filenames, is the source of truth.
+ *
+ * Ollama is deliberately NOT here. Beyond hamr's word, it is the one entry
+ * whose economics differ in kind: it takes no API key and bills nothing, so
+ * every round would price at $0 through machinery that treats $0 as a real
+ * price. An unpriced round reported as free is the exact honesty violation the
+ * `?? 0` rule exists to stop, and admitting it needs that question answered
+ * first, not a menu entry.
+ *
+ * `gemini-api` is ADMITTED-PENDING-PROBE: the probe rule stands (item 28
+ * ruling (d)) and gemini has zero runs. See `PROBE_STATUS` in
+ * `src/providers.js` — a spec may name it, and the runner says out loud that
+ * nothing has proven it. */
 export const PROVIDERS: readonly string[];
 /** V3 environment label: declared keys only — every field is a lineage-key
  * candidate at N3. `provider` is part of the key by definition (top-level,

package/types/judged.d.ts

@@ -1,3 +1,102 @@
+/**
+ * RESOLVE WHICH MODEL GRADES THIS JOB (PRD item 32.1).
+ *
+ * hamr, 2026-09-10: *"what i care about is that judge becomes llm agnostic and
+ * not set to one model or provider"* — and the shape he named: *"defaults to
+ * whatever llm is used and can be overriden"*.
+ *
+ * So, in precedence order:
+ *   1. `spec.judge` — an explicit, SIGNED `{provider, model}`. This is how a run
+ *      pins a judge deliberately different from its worker (an independent
+ *      reader, or a judge whose calibration a job wants to keep while the worker
+ *      moves). It is a spec field the HUMAN signs, part of `jobSpecHash` like
+ *      every other; the drafting agent cannot express it, because naming your
+ *      own examiner is arbiter territory.
+ *   2. otherwise the job's OWN worker provider and model. A DeepSeek job judges
+ *      on DeepSeek and needs no second account — which is the whole point: after
+ *      item 31.4 a green job runs on its own key alone, and this is what lets a
+ *      JUDGED one do the same.
+ *
+ * There is deliberately NO third fallback to `JUDGE_MODEL`. A caller that cannot
+ * say which model will grade has not wired a judge, and the grading path stops
+ * as a wiring gap rather than grading under an identity nobody chose — the same
+ * answer an absent `judgeLoop` already gets. A silent default here would be the
+ * exact silent-ignore class that `endpointKey` and F149 exist to prevent, except
+ * pointed at the arbiter.
+ *
+ * SELF-GRADING is licensed by measurement, not by this function: the judge
+ * renders no verdict (it locates facts; `decide()` is deterministic), and the
+ * calibration gate — 10 cases, a 10-of-10 floor, no partial credit, cases that
+ * MUST fail — is exactly the instrument that catches a judge which cannot see
+ * failures. If a worker-family judge cannot pass its own calibration, that is
+ * the finding, and the gate refuses to sign.
+ *
+ * @param {{specJudge?: any, workerProvider?: string, workerModel?: string}} o
+ * @returns {{provider: string, model: string}}
+ */
+export function resolveJudge({ specJudge, workerProvider, workerModel }?: {
+    specJudge?: any;
+    workerProvider?: string;
+    workerModel?: string;
+}): {
+    provider: string;
+    model: string;
+};
+/**
+ * `resolveJudge` needs a worker MODEL already resolved, and an authoring
+ * pipeline has to compute one identity at TWO different moments — once at
+ * compose time, to STAMP `closeDecl.calibration.judgeModel` into the spec it
+ * is about to sign, and again at the calibration gate that grades against
+ * that stamp — from a value that is not yet a validated spec (the operator's
+ * draft) the first time and is one (the assembled spec) the second. Two
+ * hand-spelled compositions of `resolveWorkerModel` + `resolveJudge` is
+ * exactly the kind of pair that drifts (PRD F45's "a rule with no detector is
+ * prose" applies to a rule spelled TWICE just as much as to one spelled
+ * nowhere) — this is the one spelling both calls make, and it mirrors the
+ * SAME composition `scripts/run-u.mjs` applies at launch time: the named
+ * provider's own `tiers.sonnet` defaults an absent model, and a signed
+ * `judge` override wins over the worker default.
+ *
+ * `source` is read for `provider`/`model`/`judge` only, so a draft and the
+ * spec `assembleSpec` folds it into resolve identically — `assembleSpec`
+ * spreads the draft into the spec untouched on those three fields — and any
+ * draft that goes on to validate and sign therefore stamps and grades under
+ * the exact same identity `scripts/run-u.mjs` will resolve at run time.
+ *
+ * `source.provider` absent, or unresolvable, or `source.judge` malformed all
+ * THROW here exactly as `resolveProvider`/`resolveJudge` already do on their
+ * own — a caller composing this from a pre-validation draft is expected to
+ * catch that and use a placeholder, because a draft that cannot resolve here
+ * is a draft `validateJob` reds a few lines later regardless, before anything
+ * gets signed under the placeholder.
+ *
+ * `resolveWorkerModelFn` is taken as a PARAMETER rather than imported — this
+ * module cannot import `./job.js` directly: `job.js` imports
+ * `./declaredclose.js`, which imports `resolveJudge` from THIS module, and a
+ * `judged.js` → `job.js` edge would close that into a cycle. `resolveProvider`
+ * has no such conflict (`./providers.js` imports nothing local) and is
+ * imported directly.
+ *
+ * @param {{provider?: string, model?: string, judge?: any}} source draft or spec
+ * @param {string} fallbackProviderName used only when `source.provider` is absent
+ * @param {(o: {specModel?: string, flagModel?: string, defaultModel: string}) => {model: string, source: string}} resolveWorkerModelFn `resolveWorkerModel` from `./job.js`
+ * @returns {{provider: string, model: string}}
+ */
+export function resolveJobJudge(source: {
+    provider?: string;
+    model?: string;
+    judge?: any;
+}, fallbackProviderName: string, resolveWorkerModelFn: (o: {
+    specModel?: string;
+    flagModel?: string;
+    defaultModel: string;
+}) => {
+    model: string;
+    source: string;
+}): {
+    provider: string;
+    model: string;
+};
 /**
  * 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`;
@@ -130,12 +229,13 @@ export function locatePrompt(card: any): string;
  * 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
+ *   maxTokens?: number, attempt?: number, onCost?: (c: {costUsd: number|null, unpricedRounds: number}) => void,
+ *   callBounds?: {timeoutMs?: number, deadlineMs?: number}}} 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 }: {
+export function runLocate({ artifactText, card, loopFactory, maxTokens, attempt, onCost, callBounds, }: {
     artifactText: string;
     card: any;
     loopFactory: (o: {
@@ -148,6 +248,10 @@ export function runLocate({ artifactText, card, loopFactory, maxTokens, attempt,
         costUsd: number | null;
         unpricedRounds: number;
     }) => void;
+    callBounds?: {
+        timeoutMs?: number;
+        deadlineMs?: number;
+    };
 }): Promise<{
     ok: boolean;
     facts: any | null;
@@ -196,25 +300,35 @@ export function decide(facts: any, card: any, { artifactText }?: {
     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.
+ * THE JUDGE'S HISTORICAL PIN. Until PRD item 32 (2026-09-10) this constant WAS
+ * the judge: every grading path imported it, so bareloop could run a worker on
+ * any provider and still judge only on Claude.
+ *
+ * It is no longer read by any grading path. The judge identity is now RESOLVED
+ * per job (`resolveJudge` below) and travels as data — `ctx.judgeModel` into
+ * `runJudgedFloor`, an explicit argument into the calibration gate, and
+ * `closeDecl.calibration.judgeModel` into the signed spec, exactly as before.
+ * Keeping the export is deliberate: it is part of the public API
+ * (`src/index.js`) and an adopter importing it should not break on a minor.
+ * What it means now is "the judge bareloop pinned before item 32", which is
+ * still the right DEFAULT for an anthropic-api job and still the only tier with
+ * established injection resistance upstream (BA-20's `INJECTION_BATTERY` is
+ * haiku-4.5 only).
  *
- * 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`
+ * THE ENFORCEMENT IS UNCHANGED, and still lives in three wired places because a
+ * rule with no detector is prose (F45) — only the value being compared moved
+ * from this constant to the resolved identity:
+ *   1. the identity 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
+ *      `jobSpecHash` covers it by construction. Change the judge 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.
+ *      attribute to a judge is a floor nobody can tell apart from a moved one.
+ *   3. `runJudgedFloor` refuses to grade when the stored identity is not the one
+ *      about to grade, naming both. It does not degrade in either direction:
+ *      grading on the new judge judges against a floor nobody calibrated, and
+ *      the old judge is not on offer.
  */
 export const JUDGE_MODEL: "claude-haiku-4-5";
 /**

package/types/kinds.d.ts

@@ -1,3 +1,35 @@
+/**
+ * The judged stages of a close declaration, and whether it has any — the ONE
+ * spelling of "does this close ask a model to render anything?".
+ *
+ * The comment above `JUDGED_FLOOR_KIND` says five literals is how the readers
+ * come to disagree, and by PRD item 31.4 there were SIX open-coded
+ * `stages.filter(s => s.kind === JUDGED_FLOOR_KIND)` across the tree
+ * (`src/authorjob.js` twice, `src/cardauthor.js`, `src/declaredclose.js`,
+ * `scripts/run-author.mjs`, `scripts/author-readout.mjs`). 31.4 needed a
+ * seventh, in the runner, to decide whether a judge KEY is demanded — and a
+ * seventh spelling deciding a REFUSAL is the drift `scripts/run-u.mjs`'s own
+ * judge-provider comment warns about ("a second reading of the declaration
+ * that can drift from the one the runner actually executes"). So there is one
+ * reading now, and every caller shares it.
+ *
+ * Defensive on shape ON PURPOSE: callers pass raw specs read off disk and
+ * half-built drafts, not validated declarations. An absent/!object `closeDecl`
+ * or `stages` is "no judged stages", never a throw — the close VALIDATOR is
+ * what rejects a malformed declaration, and this predicate answering a
+ * question about one is not the place to re-litigate it.
+ * @param {any} closeDecl a close declaration (or anything, including undefined)
+ * @returns {any[]} the judged-floor stages, in declaration order
+ */
+export function judgedStages(closeDecl: any): any[];
+/**
+ * Does this close declaration judge — i.e. will a judge model be CALLED?
+ * The question `scripts/run-u.mjs` asks before demanding a judge key (PRD item
+ * 31.4): a job that never judges must run on its own provider's key alone.
+ * @param {any} closeDecl
+ * @returns {boolean}
+ */
+export function closeJudges(closeDecl: any): boolean;
 /**
  * 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
@@ -531,14 +563,25 @@ export type Red = {
  * 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
+ * module owns no provider and never picks one. 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.
+ * `judgeModel` is the seam's other half (PRD item 32.1): WHICH model that loop
+ * drives, resolved by the runner (`resolveJudge`, src/judged.js — the spec's signed
+ * `judge` override, else the job's own worker model) rather than pinned in this
+ * library. It is required whenever `judgeLoop` is, and for the same reason: a
+ * verdict whose grader cannot be named is a floor nobody can attribute, and the
+ * signed calibration record has nothing to compare against. The two travel
+ * together or the stage stops.
  * `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.
+ * `callBounds` is F152/PRD 30.4's per-call TIME bound, read fresh before every
+ * locate attempt — the same derivation the run's own worker rounds carry
+ * (`callBounds()`, src/planrun.js). Absent is the honest unbounded default:
+ * an adopter or test that wires no clock through behaves exactly as before
+ * this field existed.
  * `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
@@ -561,6 +604,7 @@ export type Ctx = {
     judgeLoop?: (o: {
         system: string;
     }) => any;
+    judgeModel?: string;
     onJudgeCost?: (c: {
         stage: string | null;
         kind: string | null;
@@ -571,6 +615,10 @@ export type Ctx = {
         costUsd: number | null;
         unpricedRounds: number;
     }) => void;
+    callBounds?: () => {
+        timeoutMs?: number;
+        deadlineMs?: number;
+    };
     onStage?: (row: {
         stage: string | null;
         kind: string | null;

package/types/planrun.d.ts

@@ -196,8 +196,15 @@ 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 {string|null} [opts.judgeModel] softgreen — WHICH model that judge provider drives
+ *   (PRD item 32.1). Resolved by the CALLER (`resolveJudge`, src/judged.js: the spec's signed
+ *   `judge` override, else the job's own worker model), never pinned in this library. It
+ *   travels with `judgeProvider` or the judged stage stops as a wiring gap: a verdict whose
+ *   grader cannot be named is a floor nobody can attribute.
  * @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
+ *   locate call through, built by the CALLER from the RESOLVED judge identity (PRD item
+ *   32.1: `resolveJudge`, src/judged.js — the spec's signed `judge` override, else the job's
+ *   own worker provider and model), never pinned in this library. 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
@@ -410,7 +417,7 @@ export function planPrompt(job: any, scoutBlob: string, reds: any[] | null, maxS
  *   '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, judgeProvider, emit, remainingUsd, isUnpriced, spendComplete, capRuns, strikeLimit, closeTimeoutMs, closeDir, maxStepRounds, layerRoot, readShim, scout, scoutRounds, bridge, now, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, priorSpentUsd, reviewDoor, doorRerun, resumable }: {
+export function runPlan(job: any, { workdir, provider, nativeProvider, providerFor, judgeProvider, judgeModel, emit, remainingUsd, isUnpriced, spendComplete, capRuns, strikeLimit, closeTimeoutMs, closeDir, maxStepRounds, layerRoot, readShim, scout, scoutRounds, bridge, now, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, priorSpentUsd, reviewDoor, doorRerun, resumable }: {
     workdir: string;
     provider: any;
     nativeProvider?: ((o: {
@@ -419,6 +426,7 @@ export function runPlan(job: any, { workdir, provider, nativeProvider, providerF
         maxTurns: number;
         hasTools: boolean;
     }) => any) | undefined;
+    judgeModel?: string | null | undefined;
     judgeProvider?: any;
     emit: (type: string, data?: object) => object;
     remainingUsd: () => number;

package/types/providers.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Look up a provider's table entry. Throws a NAMED error on an unrecognized
+ * provider — never a silent default (the `resolveRates`-style-substring-
+ * match lesson: a forward hazard even at zero observed rounds, MEMORY.md).
+ * `src/job.js`'s `PROVIDERS` menu is the one place a spec's `provider`
+ * field is validated; this is the runtime construction seam it feeds.
+ * @param {string} providerName
+ * @returns {ProviderTableEntry}
+ */
+export function resolveProvider(providerName: string): ProviderTableEntry;
+/**
+ * Construct ONE provider instance for `providerName`/`model`, applying
+ * `exposeErrorBody: true` (F153 — every constructed provider, unconditionally)
+ * and the model's own request-key gating (`paramsFor`). `baseUrl` (PRD item
+ * 28, ruling (d), 2026-09-09: admitted in v1) is forwarded only when given —
+ * every provider constructor here defaults it on its own when absent.
+ * @param {string} providerName
+ * @param {{apiKey?: string, model?: string, baseUrl?: string}} [options]
+ */
+export function makeProvider(providerName: string, { apiKey, model, baseUrl }?: {
+    apiKey?: string;
+    model?: string;
+    baseUrl?: string;
+}): any;
+/**
+ * Build the `{provider, providerFor, judgeProvider}` triple both runners
+ * need (`src/cli.js`'s `buildProviders`, `scripts/run-u.mjs`'s top-level
+ * wiring) — ONE seam instead of two copies of the same construction and
+ * tier-memoization logic. `model`/`tierModels` are already-RESOLVED inputs
+ * (the caller runs `resolveWorkerModel` itself, exactly as both runners did
+ * before this factory existed — that decision stays where each runner's own
+ * `--model` flag/spec precedence lives, not duplicated in here).
+ *
+ * THE JUDGE IS NO LONGER PINNED TO ANTHROPIC (PRD item 32.2, hamr 2026-09-10:
+ * *"what i care about is that judge becomes llm agnostic and not set to one
+ * model or provider"*). It is constructed through this same factory, from a
+ * `judgeProviderName`/`judgeModel` pair the CALLER resolved (`resolveJudge`,
+ * src/judged.js — the spec's signed `judge` override, else the job's own worker
+ * provider and model). Item 28's pin, and item 28 part (2)'s deferral of a
+ * signed `judge:{provider,model}` field, both close here.
+ *
+ * `judgeApiKey` stays a SEPARATE argument rather than being derived: the judge
+ * may legitimately be a different provider from the worker, and reading its key
+ * for it would put a second env-var reader in a module whose whole job is to
+ * have exactly one. The caller reads the resolved judge provider's own `envKey`
+ * and hands the key in — the same contract the worker key already has here.
+ * @param {object} args
+ * @param {string} args.providerName spec.provider (or the anthropic-api default)
+ * @param {string|undefined} args.apiKey the WORKER's key, read from the provider's own `envKey`
+ * @param {string} args.model the already-resolved worker model id
+ * @param {Readonly<Record<string, string>>} args.tierModels the already-resolved tier -> model map (spec override folded in by the caller)
+ * @param {string|undefined} [args.baseUrl] spec.baseUrl, if any
+ * @param {string|undefined} args.judgeApiKey the judge's own key, read by the caller from the RESOLVED judge provider's `envKey`
+ * @param {string} args.judgeModel the resolved judge model id
+ * @param {string} [args.judgeProviderName] the resolved judge provider name; defaults to `providerName` (the job's own worker provider), which is `resolveJudge`'s own default
+ * @param {string|undefined} [args.judgeBaseUrl] the judge provider's endpoint, when it takes one
+ */
+export function buildRunnerProviders({ providerName, apiKey, model, tierModels, baseUrl, judgeApiKey, judgeModel, judgeProviderName, judgeBaseUrl, }: {
+    providerName: string;
+    apiKey: string | undefined;
+    model: string;
+    tierModels: Readonly<Record<string, string>>;
+    baseUrl?: string | undefined;
+    judgeApiKey: string | undefined;
+    judgeModel: string;
+    judgeProviderName?: string | undefined;
+    judgeBaseUrl?: string | undefined;
+}): {
+    provider: any;
+    providerFor: (tier: string) => any;
+    judgeProvider: any;
+};
+/**
+ * The launch-time warning lines for an ADMITTED-PENDING-PROBE provider, or
+ * `null` when the provider has paid for its own end-to-end probe (and for an
+ * off-table name — an unknown provider is `resolveProvider`'s named throw to
+ * report, never this function's warning to soften).
+ *
+ * This lives here, next to `PROBE_STATUS`, rather than inline in the runner,
+ * for one reason: inline it was UNTESTABLE. `scripts/run-u.mjs` reaches this
+ * point only with a real job row (a machine-local patient path) and a real
+ * signed spec, so nothing in the suite could reach the branch, and a warning
+ * nothing executes drifts exactly the way the green-only prose did (item 31.2).
+ *
+ * It never REFUSES, and it never returns a shape a caller can mistake for a
+ * refusal: hamr admitted `gemini-api` to the menu, and a probe table that
+ * quietly withheld it would be a second ruling nobody made.
+ * @param {string} providerName
+ * @returns {string[]|null} lines to print, in order, or null when there is nothing to say
+ */
+export function probeWarningLines(providerName: string): string[] | null;
+/**
+ * Today's anthropic-api tier table — EXACTLY the `DEFAULT_TIER_MODELS` both
+ * runners hardcoded before this factory existed. Any change to these two
+ * values is a change to shipped anthropic-api behaviour, not a refactor.
+ */
+export const ANTHROPIC_TIER_MODELS: Readonly<{
+    sonnet: "claude-sonnet-5";
+    haiku: "claude-haiku-4-5-20251001";
+}>;
+/**
+ * DeepSeek (F149/F150) is a SINGLE model, not a tiered family — hamr's
+ * ruling above: one secondary provider, not a menu. Both tiers map to the
+ * same model id ON PURPOSE: `resolveWorkerModel`/a runner's `providerFor
+ * (tier)` only ever LOOK UP a tier's model id (src/job.js:818-827,
+ * scripts/run-u.mjs's `providerFor`) — neither assumes the tiers name
+ * different models — so repeating the one id is the honest representation
+ * of a single-model provider, not a second model masquerading as `haiku`.
+ * If DeepSeek (or a future openai-api entrant) ever ships a genuinely
+ * cheaper tier model, this is where it would earn its own `haiku` id.
+ */
+export const OPENAI_TIER_MODELS: Readonly<{
+    sonnet: "deepseek-chat";
+    haiku: "deepseek-chat";
+}>;
+/**
+ * Gemini (PRD item 31.3, hamr 2026-09-09: "anthropic, openai, gemini drop
+ * ollama for now"). Two real tiers, unlike DeepSeek's single model: `flash` is
+ * the cheap tier by design, so `haiku` maps to it honestly rather than
+ * repeating one id.
+ *
+ * ADMITTED-PENDING-PROBE. The probe rule stands (PRD item 28 ruling (d),
+ * 2026-09-09): no endpoint is in the menu without its own clean paid probe,
+ * and `gemini-api` has ZERO runs. `anthropic-api` is the original (~167
+ * archived runs) and `openai-api` was probed green through the shipped runner
+ * (run mtu12vks, $1.64/$4, F157); gemini owes that fire and has not paid it.
+ * `PROBE_STATUS` below is the machine-readable form of that debt — nothing in
+ * here silently pretends the provider is proven.
+ */
+export const GEMINI_TIER_MODELS: Readonly<{
+    sonnet: "gemini-2.5-pro";
+    haiku: "gemini-2.5-flash";
+}>;
+/**
+ * Which admitted providers have paid for their own end-to-end probe, and which
+ * have not. Read by the runner to print a loud marker; never read to REFUSE —
+ * hamr admitted gemini to the menu, and a table that quietly withheld it would
+ * be a second, invisible ruling. An unprobed provider runs, and says so.
+ * @type {Readonly<Record<string, {probed: boolean, evidence: string}>>}
+ */
+export const PROBE_STATUS: Readonly<Record<string, {
+    probed: boolean;
+    evidence: string;
+}>>;
+export type ProviderTableEntry = {
+    /**
+     * the bare-agent provider class
+     */
+    ctor: new (options: any) => any;
+    /**
+     * the environment variable this provider reads its key from
+     */
+    envKey: string;
+    /**
+     * tier name -> model id
+     */
+    tiers: Readonly<Record<string, string>>;
+    /**
+     * the CONSTRUCTOR OPTION NAME this provider reads its endpoint from — NOT assumed to be `baseUrl` (see below)
+     */
+    endpointKey: string;
+    /**
+     * per-model request-key/param gating, applied on TOP of {exposeErrorBody:true, apiKey, model, <endpointKey>?}
+     */
+    paramsFor: (model: string | undefined) => Record<string, any>;
+};

package/types/ratelimit.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Is `err` an HTTP 429 (rate-limited) response? True ONLY for an explicit
+ * status of 429 on the error itself. Nothing else qualifies — not message
+ * text (a message merely containing "429" is not this), not `retryable`,
+ * not any other status. Symmetric with `isTransportFailure`'s own status
+ * check (src/transport.js), just reading the opposite branch of it.
+ * @param {any} err
+ * @returns {boolean}
+ */
+export function isRateLimited(err: any): boolean;
+/**
+ * The vendor's RAW stated wait, in milliseconds, parsed straight from the
+ * error message — no default, no margin, no cap. `null` when nothing in the
+ * message matches a known shape. Exported separately from `rateLimitWaitMs`
+ * so a caller that wants to report the vendor's own number on the spine
+ * (`statedMs`) never has to re-derive it from the margin-adjusted figure.
+ *
+ * bare-agent does not expose the vendor's `retry-after` /
+ * `x-ratelimit-reset-*` response headers on the thrown error (BA-26) — the
+ * delay exists only in the vendor's English message text, so this parses
+ * that text. Verified real shape (OpenAI, run `8ev2sdkn`, 2026-09-08):
+ * "Please try again in 11.996s." This also supports "try again in 1.5
+ * seconds", "try again in 20ms", "retry after 30s", and "retry after 30
+ * seconds" — case-insensitive.
+ * @param {any} err
+ * @returns {number|null}
+ */
+export function statedWaitMs(err: any): number | null;
+/**
+ * How long to wait before retrying a 429, in milliseconds — or `null`
+ * meaning "do not retry at all" (either the parsed wait exceeds
+ * `RATE_LIMIT_MAX_WAIT_MS`, in which case waiting that long is the
+ * operator's decision, not ours).
+ *
+ * A parsed value gets `PARSED_DELAY_MARGIN_MS` added (the vendor's stated
+ * number is the earliest moment its window resets, not a safe one to fire
+ * on), capped so the margin itself can never push a parsed value over
+ * `RATE_LIMIT_MAX_WAIT_MS`. When nothing parses, `RATE_LIMIT_DEFAULT_WAIT_MS`
+ * is returned as-is, with no margin added (there is nothing to add margin
+ * to — it is already a conservative guess, not an earliest-moment reading).
+ * @param {any} err
+ * @returns {number|null}
+ */
+export function rateLimitWaitMs(err: any): number | null;
+/** The fixed retry budget: ONE extra attempt after a 429. Never read from a
+ * job spec or CLI flag — raising it is arbiter territory, mirroring
+ * transport.js's TRANSPORT_RETRIES exactly (tighten-only doctrine). */
+export const RATE_LIMIT_RETRIES: 1;
+/** bare-agent's `Retry.call` (if ever used) counts ATTEMPTS, not retries;
+ * this module's own hand-rolled ladder (src/planrun.js) does the same for
+ * symmetry with TRANSPORT_MAX_ATTEMPTS. */
+export const RATE_LIMIT_MAX_ATTEMPTS: number;
+/** The hard cap on how long we will ever wait for a vendor-stated 429 delay.
+ * A vendor asking for longer than this is not honoured — we do not retry at
+ * all in that case. Waiting that long is the operator's decision, not ours
+ * (arbiter territory: nothing here escalates the wait past what hamr set). */
+export const RATE_LIMIT_MAX_WAIT_MS: 60000;
+/** Used only when the vendor's message carries no parseable delay at all. */
+export const RATE_LIMIT_DEFAULT_WAIT_MS: 5000;

package/types/run.d.ts

@@ -34,9 +34,14 @@
  *   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 {string|null} [opts.judgeModel] SOFTGREEN — WHICH model the judge provider drives
+ *   (PRD item 32.1), resolved by the CALLER (`resolveJudge`, src/judged.js) and passed
+ *   through untouched. Travels with `judgeProvider`; absent, a judged stage stops as a
+ *   wiring gap rather than grading under an identity nobody named.
  * @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
+ *   locate call through, built by the CALLER from the RESOLVED judge identity (PRD item
+ *   32.1: `resolveJudge`/`resolveJobJudge`, src/judged.js — the spec's signed `judge`
+ *   override, else the job's own worker provider and model), never pinned. 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
@@ -167,8 +172,16 @@
  *   '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>`
+ *   NOTE: `job-end` can ALSO land with outcome 'runner-drained' (F140/PRD item
+ *   28(c)) — the `beforeExit` backstop's own terminal, emitted from OUTSIDE this
+ *   function's normal control flow when the process drains with no `job-end` at
+ *   all (a provider promise that never settled). It never appears as this
+ *   function's own RETURN value (nothing is left to receive it), only as the
+ *   spine's terminal record. Non-zero exit, `spendComplete:false` always, and
+ *   deliberately NOT in the resumable/checkpoint set (`src/reuse.js`) — an
+ *   unknown in-flight state is not a known-safe resume point.
  */
-export function runJob(rawSpec: object | string, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider, emit, capRuns, strikeLimit, shellCapUsd, closeTimeoutMs, closeDir, layerRoot, readShim, scout, bridge, priorSpentUsd, priorSpendComplete, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun, resumable }: {
+export function runJob(rawSpec: object | string, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider, judgeModel, emit, capRuns, strikeLimit, shellCapUsd, closeTimeoutMs, closeDir, layerRoot, readShim, scout, bridge, priorSpentUsd, priorSpendComplete, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun, resumable }: {
     approvals: unknown;
     workdir: string;
     provider: any;
@@ -180,6 +193,7 @@ export function runJob(rawSpec: object | string, { approvals, workdir, provider,
     }) => any) | undefined;
     emit: (type: string, data?: object) => object;
     providerFor?: ((tier: string) => any) | undefined;
+    judgeModel?: string | null | undefined;
     judgeProvider?: any;
     capRuns?: number | undefined;
     strikeLimit?: number | undefined;

package/types/transport.d.ts

@@ -2,11 +2,17 @@
  * Is `err` a transport-class failure — the request never produced an HTTP
  * response? True for: a TLS fault mid-record ("bad record mac" and kin), a
  * reset/broken/timed-out socket (ECONNRESET, EPIPE, ETIMEDOUT, ECONNREFUSED,
- * ENETUNREACH — by code on the error itself or on `err.cause`), and
- * `fetch failed` wrapping a network `cause`. False for anything carrying an
- * HTTP status (`err.status`/`err.statusCode`, 4xx/5xx/429) or an explicit
+ * ENETUNREACH — by code on the error itself or on `err.cause`), `fetch
+ * failed` wrapping a network `cause`, and — as of bare-agent 0.42.0 (BA-25)
+ * — a `ProviderError` whose `err.context.bound === 'transport'`: the
+ * response stream ended (`'aborted'`/`'error'`/premature `'close'`) after
+ * headers but before the body completed, which bare-agent itself rejects as
+ * retryable with no HTTP status. False for anything carrying an HTTP status
+ * (`err.status`/`err.statusCode`, 4xx/5xx/429) or an explicit
  * `err.retryable === false` — those are provider RESPONSES, not transport
- * casualties, and bare-agent's own policy governs them unchanged.
+ * casualties, and bare-agent's own policy governs them unchanged; both
+ * guards run BEFORE the `context.bound` check, so a status or an explicit
+ * `retryable:false` wins even if `bound` says 'transport'.
  * @param {any} err
  * @returns {boolean}
  */