bareloop 0.22.0 → 0.24.0

package/src/calibrate.js

@@ -46,7 +46,9 @@
 //     calibration becomes a refusal, exactly as D9's other three gates work.
 //   * IT PICKS NO NUMBER. The size is `CALIBRATION_SIZE` (hamr's), the floor is
 //     all-of-them (hamr's), the ladder is `JUDGE_ATTEMPTS` (operator-confirmed),
-//     and the model is `JUDGE_MODEL` (pinned). Nothing here invents a threshold.
+//     and the model is the run's RESOLVED judge identity, handed in (PRD item
+//     32.1) rather than pinned in this library. Nothing here invents a threshold
+//     and nothing here picks a judge.
 //   * IT OWNS NO PROVIDER. The judge seam arrives as `judgeLoop`; an absent one
 //     is a WIRING GAP that stops the gate, never a silent skip — a judged close
 //     signed off a calibration nobody ran is the exact state this gate exists to
@@ -58,11 +60,12 @@
 
 import { createHash } from 'node:crypto';
 import {
-  JUDGE_MODEL, LOCATE_LABEL, LOCATE_AXES, CALIBRATION_SIZE,
+  LOCATE_LABEL, LOCATE_AXES, CALIBRATION_SIZE,
   runLocate, decide, expectedOf, validateCard, validateCalibrationSet,
 } from './judged.js';
 import { JUDGE_ATTEMPTS } from './kinds.js';
 import { tallyCalls } from './text.js';
+import { PROVIDER_TIMEOUT_MS } from './clock.js';
 
 /** @typedef {{code: string, path: string, detail: string, [k: string]: any}} Red */
 
@@ -308,11 +311,11 @@ export function factsResist(facts, gold, artifactText) {
  * when the model is malforming, which is the worst moment for a paid ladder to be
  * unbounded. A stop comes back as its own field rather than as a `red`: a ceiling
  * is the OPERATOR's governance, never the transport's casualty.
- * @param {{artifactText: string, card: any, judgeLoop: Function, attempts: number,
+ * @param {{artifactText: string, card: any, judgeLoop: Function, judgeModel: string, attempts: number,
  *   meter: (c: any) => void, id: string, kind: string,
  *   capStop: () => 'cap-halt'|'pricing-red'|null}} o
  */
-async function pipeOnce({ artifactText, card, judgeLoop, attempts, meter, id, kind, capStop }) {
+async function pipeOnce({ artifactText, card, judgeLoop, judgeModel, attempts, meter, id, kind, capStop }) {
   /** @type {any} */
   let last = null;
   /** @type {any[]} */
@@ -330,8 +333,17 @@ async function pipeOnce({ artifactText, card, judgeLoop, attempts, meter, id, ki
       card,
       loopFactory: /** @type {any} */ (judgeLoop),
       attempt,
+      // F152/PRD 30.4 — this module's own header already names the hazard ("a
+      // dead socket") as one of its three CASUALTY readings, but with no bound
+      // at all a truly silent judge endpoint never reaches that reading — it
+      // hangs the authoring process forever instead (measured). The gate runs
+      // at draft/sign time, which has no wall clock to derive a bound from (the
+      // authoring pipeline's only ceiling is money, `ceilingUsd`/`capStop`), so
+      // this reuses the same idle-timeout default the run path falls back to
+      // when ITS OWN wall is unbounded (`PROVIDER_TIMEOUT_MS`, src/clock.js).
+      callBounds: { timeoutMs: PROVIDER_TIMEOUT_MS },
       onCost: (c) => meter({
-        id, kind, attempt, label: CALIBRATION_LABEL, model: JUDGE_MODEL,
+        id, kind, attempt, label: CALIBRATION_LABEL, model: judgeModel,
         costUsd: c.costUsd, unpricedRounds: c.unpricedRounds,
       }),
     });
@@ -371,7 +383,13 @@ async function pipeOnce({ artifactText, card, judgeLoop, attempts, meter, id, ki
  * graded one: `ok` is false, the cases nobody bought are absent rather than recorded
  * as failures, and `casualty` stays null — the transport was fine, the operator's own
  * governance stopped the gate.
- * @param {{cases: any, card: any, judgeLoop: Function|null,
+ * `judgeModel` is REQUIRED and has no default (PRD item 32.1). It is the identity
+ * the caller resolved (`resolveJudge`, src/judged.js) and it is what the graded set
+ * is STAMPED with — `setHash` folds it in, so a set certified by one judge cannot be
+ * mistaken for the same set certified by another. A default here would be the silent
+ * fall-back the whole judge-identity change exists to remove: a gate that grades
+ * under a model nobody named certifies a floor nobody can attribute.
+ * @param {{cases: any, card: any, judgeLoop: Function|null, judgeModel: string,
  *   onCost?: (c: any) => void, attempts?: number, battery?: any[], batteryCard?: any,
  *   capStop?: () => 'cap-halt'|'pricing-red'|null}} o
  * @returns {Promise<{ok: boolean, stop: string|null, casualty: any,
@@ -382,12 +400,25 @@ async function pipeOnce({ artifactText, card, judgeLoop, attempts, meter, id, ki
  *   costUsd: number|null, knownUsd: number, spendComplete: boolean, calls: any[]}>}
  */
 export async function runCalibration({
-  cases, card, judgeLoop, onCost = () => {},
+  cases, card, judgeLoop, judgeModel, onCost = () => {},
   attempts = JUDGE_ATTEMPTS,
   battery = /** @type {any[]} */ (/** @type {unknown} */ (INJECTION_LOCATE_BATTERY)),
   batteryCard = INJECTION_CARD,
   capStop = () => null,
 }) {
+  // The mandatory-identity throw guards a REAL judge seam graded under nobody's
+  // name — it does not apply when there is no seam at all. A caller wiring no
+  // `judgeLoop` (an adopter who has not connected a judge yet) legitimately hands
+  // in no `judgeModel` either, and that case is the WIRING-GAP `no-judge` stop
+  // below, returned as a red rather than thrown. Throwing here ahead of that
+  // check would make the wiring-gap stop unreachable through its own documented
+  // path — `prepareSigning` (src/authorjob.js) draws exactly this same line with
+  // its own `judgeLoop !== null` guard, and this function has to agree with it.
+  if (typeof judgeLoop === 'function' && (typeof judgeModel !== 'string' || judgeModel.trim() === '')) {
+    throw new Error('[calibrate] runCalibration needs the resolved judgeModel (PRD item 32.1): the graded set is '
+      + 'STAMPED with the judge that certified it, and a set nobody can attribute is a floor nobody can tell apart '
+      + 'from one graded by a different model. There is no library pin to fall back to.');
+  }
   /** @type {any[]} */
   const calls = [];
   /** @param {any} c */
@@ -403,7 +434,7 @@ export async function runCalibration({
     return /** @type {any} */ ({
       ok: false, stop: null, casualty: null, graded: [], failures: [],
       injection: { styles: [], allResisted: false, leaks: [] },
-      reds: [], judgeModel: JUDGE_MODEL,
+      reds: [], judgeModel,
       cardHash: null, casesHash: null, setHash: null,
       costUsd: t.costUsd, knownUsd: t.knownUsd, spendComplete: t.spendComplete, calls: calls.map((c) => ({ ...c })),
       ...extra,
@@ -454,7 +485,7 @@ export async function runCalibration({
         code: 'no-judge-seam',
         path: 'judgeLoop',
         detail: `the calibration gate runs ${CALIBRATION_SIZE} real locate calls plus ${battery.length} injection `
-          + `artifacts through ${JUDGE_MODEL}, and no judge seam was wired. An absent seam is an adopter wiring gap and `
+          + `artifacts through ${judgeModel}, and no judge seam was wired. An absent seam is an adopter wiring gap and `
           + 'never a fall-back: a gate that grades nothing would certify every close it was asked about',
       }],
     });
@@ -462,7 +493,7 @@ export async function runCalibration({
 
   const cardHash = artifactHash(card);
   const casesHash = artifactHash(cases);
-  const setHash = artifactHash({ card, cases, judgeModel: JUDGE_MODEL });
+  const setHash = artifactHash({ card, cases, judgeModel });
   const stamped = { cardHash, casesHash, setHash };
 
   // ── the signed ten ────────────────────────────────────────────────────────
@@ -470,7 +501,7 @@ export async function runCalibration({
   const graded = [];
   for (const c of cases) {
     const r = await pipeOnce({
-      artifactText: String(c.artifact), card, judgeLoop: /** @type {Function} */ (judgeLoop),
+      artifactText: String(c.artifact), card, judgeLoop: /** @type {Function} */ (judgeLoop), judgeModel,
       attempts, meter, id: String(c.id), kind: 'case', capStop,
     });
     // the ceiling, ahead of the casualty branch: a call nobody funded is not a call
@@ -517,7 +548,7 @@ export async function runCalibration({
   const styles = [];
   for (const b of battery) {
     const r = await pipeOnce({
-      artifactText: b.artifact, card: batteryCard, judgeLoop: /** @type {Function} */ (judgeLoop),
+      artifactText: b.artifact, card: batteryCard, judgeLoop: /** @type {Function} */ (judgeLoop), judgeModel,
       attempts, meter, id: b.id, kind: 'injection', capStop,
     });
     if (r.budget) {

package/src/cardauthor.js

@@ -60,10 +60,10 @@
 // pipe produces are one shape read twice (module 5 compares them mechanically).
 
 import {
-  JUDGE_RULE_IDS, JUDGE_RULES, CALIBRATION_SIZE, CASE_VERDICTS, validateJudgedArtifacts, JUDGE_MODEL,
+  JUDGE_RULE_IDS, JUDGE_RULES, CALIBRATION_SIZE, CASE_VERDICTS, validateJudgedArtifacts,
 } from './judged.js';
 import { askStructured, makeCostBook } from './authorflow.js';
-import { JUDGED_FLOOR_KIND } from './kinds.js';
+import { judgedStages } from './kinds.js';
 import { isObj, redactSecrets } from './validate.js';
 
 /** @typedef {{code: string, path: string, detail: string, [k: string]: any}} Red */
@@ -363,15 +363,16 @@ export function signJudgedArtifacts({ proposal, fix = null }) {
  *   - THE CASES land beside the stages as `calibration.cases` — a close-level
  *     artifact, because the set calibrates the RULER and not one stage's params,
  *     and because module 5's gate reads it before any stage runs.
- *   - THE JUDGE MODEL lands beside them as `calibration.judgeModel`, and it is the
- *     PIN (`JUDGE_MODEL`) rather than anything a caller may name. A calibration set
- *     is only worth the tier that graded it — §4.2's whole safety argument is worth
- *     exactly as much as BA-20's injection evidence, which is haiku-4.5's alone — so
- *     the set has to carry which tier certified it or nothing downstream can tell a
- *     signed floor from a bumped one. Storing it HERE, inside the spec, is what makes
- *     a bump flip `jobSpecHash`: the signature dies, the signer re-signs, and a
- *     re-sign is a re-run of the calibration gate. That is the docstring on
- *     `JUDGE_MODEL` finally given a detector instead of a promise (F45).
+ *   - THE JUDGE MODEL lands beside them as `calibration.judgeModel`. Since PRD item
+ *     32.1 that is the RESOLVED judge identity the caller hands in (`resolveJudge`,
+ *     src/judged.js — the spec's signed `judge` override, else the job's own worker
+ *     model), not a library pin. A calibration set is only worth the judge that
+ *     graded it, so the set has to carry which judge certified it or nothing
+ *     downstream can tell a signed floor from a moved one. Storing it HERE, inside
+ *     the spec, is what makes a judge change flip `jobSpecHash`: the signature dies,
+ *     the signer re-signs, and a re-sign is a re-run of the calibration gate. It is
+ *     REQUIRED, with no default — a set stamped with a model nobody named is exactly
+ *     the unattributable floor this field exists to prevent (F45).
  *
  * A card with NOWHERE TO LAND THROWS. It is a caller's own broken input — a
  * signed rubric folded into a close with no judged ruler — and there is no safe
@@ -380,20 +381,26 @@ export function signJudgedArtifacts({ proposal, fix = null }) {
  * The input is never mutated: a closeDecl is a signed artefact and rewriting a
  * caller's copy in place is how two readers come to disagree about what was
  * signed.
- * @param {any} closeDecl @param {{card: any, cases: any[]}} o
+ * @param {any} closeDecl @param {{card: any, cases: any[], judgeModel: string}} o
  * @returns {any} a new closeDecl
  */
-export function foldJudgedArtifacts(closeDecl, { card, cases }) {
+export function foldJudgedArtifacts(closeDecl, { card, cases, judgeModel }) {
+  if (typeof judgeModel !== 'string' || judgeModel.trim() === '') {
+    throw new Error('[cardauthor] foldJudgedArtifacts needs the resolved judgeModel (PRD item 32.1): the stored set '
+      + 'carries the judge that certified it, and there is no library pin to fall back to.');
+  }
   const out = structuredClone(closeDecl);
-  const stages = Array.isArray(out?.stages) ? out.stages : [];
-  const judged = stages.filter((/** @type {any} */ s) => isObj(s) && s.kind === JUDGED_FLOOR_KIND);
+  // `judgedStages` filters `out`'s OWN stage objects, so the card assignment
+  // below mutates the clone in place — the reason this reads `out`, not the
+  // caller's `closeDecl`.
+  const judged = judgedStages(out);
   if (judged.length !== 1) {
     throw new Error(`[cardauthor] the signed card folds into the close's ONE judged-floor stage, and this close has `
       + `${judged.length} — a rubric with nowhere to land is signed evidence nothing reads, and a second judged stage `
       + 'is a second bar for one verdict');
   }
   judged[0].params = { ...(isObj(judged[0].params) ? judged[0].params : {}), card: structuredClone(card) };
-  out.calibration = { cases: structuredClone(cases), judgeModel: JUDGE_MODEL };
+  out.calibration = { cases: structuredClone(cases), judgeModel };
   return out;
 }
 

package/src/cli.js

@@ -19,7 +19,6 @@
 // run, never the unresolved bundleHash. `history.jsonl` records both hashes
 // side by side (POC fact 2) so the pairing can never drift silently.
 
-import { createRequire } from 'node:module';
 import { createInterface } from 'node:readline/promises';
 import { hostname } from 'node:os';
 import { execFileSync } from 'node:child_process';
@@ -32,17 +31,15 @@ import {
 
 import {
   exportBundle, readBundle, resolveBundleSpec, checkEnvelope, bless, verifyBlessing, appendHistory, checkBundleDeps,
-  runJob, makeSpine, loadRegistry, listingRow, jobSpecHash, resolveWorkerModel, JUDGE_MODEL,
+  runJob, makeSpine, loadRegistry, listingRow, jobSpecHash, resolveWorkerModel, resolveJudge,
 } from './index.js';
+import { resolveProvider, buildRunnerProviders } from './providers.js';
 
-const require = createRequire(import.meta.url);
-
-// The runner's own tier menu, the same spelling `scripts/run-u.mjs` uses (not
-// exported from `src/` — the tier->model mapping is runner territory, not the
-// library's). A `bareloop run` has no `--model` flag (not in the frozen
-// spec), so `flagModel` is always undefined and only the spec's own `model`
-// (if signed) or this default is ever in play.
-const DEFAULT_TIER_MODELS = { sonnet: 'claude-sonnet-5', haiku: 'claude-haiku-4-5-20251001' };
+// The tier->model tables live in `src/providers.js` now (PRD item 28's
+// factory) — one seam instead of a copy hardcoded in each runner. A
+// `bareloop run` has no `--model` flag (not in the frozen spec), so
+// `flagModel` is always undefined below and only the spec's own `model`
+// (if signed) or the resolved provider's default tier is ever in play.
 
 /** @param {unknown} v @returns {v is Record<string, any>} */
 const isObj = (v) => typeof v === 'object' && v !== null;
@@ -58,20 +55,63 @@ const isObj = (v) => typeof v === 'object' && v !== null;
  * @param {any} spec the (already `$BARELOOP_BUNDLE`-resolved) bundle spec
  */
 function buildProviders(apiKey, spec) {
-  const { AnthropicProvider } = require('bare-agent/providers');
+  // `bareloop run`'s frozen key contract (module header above) is
+  // ANTHROPIC_API_KEY only — this `apiKey` is always that key. A bundle
+  // whose spec names a provider that reads a DIFFERENT env key therefore
+  // has no seam into this flow yet, and the one thing this must never do is
+  // construct that provider with the Anthropic key: the run would fail at
+  // the first call with a vendor 401, which reads as a credential problem
+  // rather than as the unbuilt seam it actually is. So it REFUSES here, at
+  // $0, naming the key it would have needed. Widening the contract (a
+  // signed per-provider key story) is PRD item 28 part (2)/(3), the
+  // arbiter's, not this factory rewire's — the runner that actually fires
+  // openai-api jobs today is `scripts/run-u.mjs`, which IS key-aware.
+  const providerName = isObj(spec) && typeof spec.provider === 'string' ? spec.provider : 'anthropic-api';
+  const entry = resolveProvider(providerName);
+  if (entry.envKey !== 'ANTHROPIC_API_KEY') {
+    throw new Error(
+      `bareloop run: this bundle's spec names provider "${providerName}", which reads `
+      + `${entry.envKey}. The bundle runner's key contract is ANTHROPIC_API_KEY only, so it `
+      + 'refuses rather than calling that provider with the wrong key (PRD item 28 part 2 — '
+      + 'a signed per-provider key story is not built). Run this job through scripts/run-u.mjs.',
+    );
+  }
   const modelResolution = resolveWorkerModel({
     specModel: isObj(spec) && typeof spec.model === 'string' ? spec.model : undefined,
     flagModel: undefined,
-    defaultModel: DEFAULT_TIER_MODELS.sonnet,
+    defaultModel: entry.tiers.sonnet,
   });
   const MODEL = modelResolution.model;
-  const provider = new AnthropicProvider({ apiKey, model: MODEL });
-  const TIER_MODELS = modelResolution.source === 'spec' ? { ...DEFAULT_TIER_MODELS, sonnet: MODEL } : DEFAULT_TIER_MODELS;
-  /** @type {Record<string, any>} */
-  const tierCache = {};
-  const providerFor = (/** @type {string} */ tier) => (tierCache[tier] ??= (TIER_MODELS[/** @type {keyof typeof TIER_MODELS} */ (tier)] === MODEL ? provider : new AnthropicProvider({ apiKey, model: TIER_MODELS[/** @type {keyof typeof TIER_MODELS} */ (tier)] })));
-  const judgeProvider = new AnthropicProvider({ apiKey, model: JUDGE_MODEL });
-  return { provider, providerFor, judgeProvider };
+  const tierModels = modelResolution.source === 'spec' ? { ...entry.tiers, sonnet: MODEL } : entry.tiers;
+  const baseUrl = isObj(spec) && typeof spec.baseUrl === 'string' ? spec.baseUrl : undefined;
+  // THE JUDGE, RESOLVED RATHER THAN PINNED (PRD item 32.1/32.2). The bundle
+  // runner's key contract is `ANTHROPIC_API_KEY`-only and the refusal above has
+  // already established that the WORKER provider reads that key — so a judge
+  // defaulting to the worker's own identity reads the same key by construction,
+  // and a signed `judge` naming a different provider would need a key this
+  // runner does not have. That case refuses here, at $0, by name — the same
+  // shape and the same reason as the worker refusal above, never a call made
+  // with the wrong vendor's key.
+  const judge = resolveJudge({
+    specJudge: isObj(spec) ? spec.judge : undefined,
+    workerProvider: providerName,
+    workerModel: MODEL,
+  });
+  const judgeEntry = resolveProvider(judge.provider);
+  if (judgeEntry.envKey !== 'ANTHROPIC_API_KEY') {
+    throw new Error(
+      `bareloop run: this bundle's spec names judge provider "${judge.provider}", which reads `
+      + `${judgeEntry.envKey}. The bundle runner's key contract is ANTHROPIC_API_KEY only, so it `
+      + 'refuses rather than calling that provider with the wrong key. Run this job through scripts/run-u.mjs.',
+    );
+  }
+  return {
+    ...buildRunnerProviders({
+      providerName, apiKey, model: MODEL, tierModels, baseUrl,
+      judgeApiKey: apiKey, judgeModel: judge.model, judgeProviderName: judge.provider, judgeBaseUrl: baseUrl,
+    }),
+    judgeModel: judge.model,
+  };
 }
 
 /** @param {string[]} args @returns {{ positional: string[], flags: Record<string, string|true> }} */
@@ -221,6 +261,11 @@ async function doRun(args, { out, err, cwd, env, now, deps }) {
   // provider (the test seam). Absent and no injected provider: print the
   // operator questions (the bundle's own README) and the hash, spend nothing.
   let { provider, providerFor, judgeProvider } = deps;
+  // the judge IDENTITY travels with the judge PROVIDER (PRD item 32.1). A test
+  // injecting `deps.judgeProvider` may name it too; absent, it is resolved
+  // alongside the real providers below, and a judged stage with neither stops as
+  // a wiring gap rather than grading under a name nobody wrote.
+  let judgeModel = /** @type {string|null} */ (deps.judgeModel ?? null);
   if (!provider) {
     const apiKey = env.ANTHROPIC_API_KEY;
     if (!apiKey) {
@@ -230,7 +275,13 @@ async function doRun(args, { out, err, cwd, env, now, deps }) {
       out(`bundleHash: ${bundle.manifest.bundleHash}`);
       return 0;
     }
-    ({ provider, providerFor, judgeProvider } = buildProviders(apiKey, bundle.spec));
+    try {
+      ({ provider, providerFor, judgeProvider, judgeModel } = buildProviders(apiKey, bundle.spec));
+    } catch (e) {
+      // a refusal from the key contract above: name it and spend nothing
+      err(String(/** @type {any} */ (e)?.message ?? e));
+      return 1;
+    }
   }
 
   // 4. blessing.
@@ -317,6 +368,7 @@ async function doRun(args, { out, err, cwd, env, now, deps }) {
       provider,
       providerFor,
       judgeProvider,
+      judgeModel,
       emit,
       closeDir,
       shellCapUsd: runSpec.budgetUsd,
@@ -449,7 +501,7 @@ async function runMenu(deps, ctx) {
  * code, so `bin/bareloop.mjs` can set `process.exitCode` and let node flush
  * queued stdout on its own (F-something: `process.exit()` can discard it).
  * @param {string[]} argv
- * @param {{ env?: Record<string,string|undefined>, stdout?: any, stderr?: any, cwd?: string, provider?: any, providerFor?: any, judgeProvider?: any, now?: () => number, stdin?: any }} deps
+ * @param {{ env?: Record<string,string|undefined>, stdout?: any, stderr?: any, cwd?: string, provider?: any, providerFor?: any, judgeProvider?: any, judgeModel?: string|null, now?: () => number, stdin?: any }} deps
  * @returns {Promise<number>}
  */
 export async function main(argv, deps = {}) {

package/src/declaredclose.js

@@ -68,7 +68,7 @@
 // once instead of once-per-invocation, but `runPlan` has a dozen return paths and
 // a leaked worktree outlives the process that made it.
 
-import { runStage, makeSeedTrees, STOP_FAULTS, EXIT_RED, JUDGED_FLOOR_KIND } from './kinds.js';
+import { runStage, makeSeedTrees, STOP_FAULTS, EXIT_RED, JUDGED_FLOOR_KIND, judgedStages } from './kinds.js';
 import {
   validateDeclaration, classGuards, genreOwnedEnvNames, ungroundedGenreEnv, GENRE_LANGUAGES, TYPES_GENRE,
   VERDICT_CLASSES, LIVE_CLASSES, NEVER_OFFERED_KINDS,
@@ -424,8 +424,7 @@ export function validateCloseDecl(closeDecl, opts = {}) {
   // redded here — making the set MANDATORY is the signing gate's call, and
   // module 5 owns it.
   if (closeDecl.calibration !== undefined) {
-    const judged = (Array.isArray(closeDecl.stages) ? closeDecl.stages : [])
-      .filter((/** @type {any} */ s) => isObj(s) && s.kind === JUDGED_FLOOR_KIND);
+    const judged = judgedStages(closeDecl);
     if (!isObj(closeDecl.calibration)) {
       red('invalid-value', `${at}.calibration`, 'the frozen calibration set, as an object carrying `cases`');
     } else if (judged.length !== 1) {
@@ -567,13 +566,15 @@ function translate(r, redact) {
  *   seedTrees?: any, gapCap?: number, maxBuffer?: number, baselineMode?: 'auto'|'worktree',
  *   humanRuling?: {decision: string, text?: string|null}|null,
  *   judgeLoop?: ((o: {system: string}) => any)|null,
- *   onJudgeCost?: ((c: any) => void)|null}} [opts]
+ *   judgeModel?: string|null,
+ *   onJudgeCost?: ((c: any) => void)|null,
+ *   callBounds?: (() => {timeoutMs?: number, deadlineMs?: number})|null}} [opts]
  * @returns {Promise<any>}
  */
 export async function runDeclaredStages(stages, redact = (s) => s, opts = {}) {
   const {
     timeoutMs, cwd, seedRef, seedTrees: shared, gapCap, maxBuffer, baselineMode, humanRuling = null,
-    judgeLoop = null, onJudgeCost = null,
+    judgeLoop = null, judgeModel = null, onJudgeCost = null, callBounds = null,
   } = opts;
   if (!isNonEmptyString(cwd) || !isNonEmptyString(seedRef)) {
     // Refuse rather than guess. A declared close measures against a SEED; a
@@ -603,14 +604,27 @@ export async function runDeclaredStages(stages, redact = (s) => s, opts = {}) {
     // human stage reads the absence as "nobody has answered yet", which is the
     // whole of what a pause means.
     humanRuling,
-    // THE PAID SEAM and THE METER, both operator territory and both absent on
-    // every mechanical close. A judged stage with no seam STOPS as a wiring gap
-    // rather than falling back to some other model (M1 owns no provider and the
-    // judge tier is pinned), and every locate call it does buy is reported OUT
-    // through the meter so the run's ONE ledger can see it — a close has cost $0
-    // until this kind, and a budget must fund the attempt PLUS its close.
+    // THE PAID SEAM, THE IDENTITY and THE METER, all operator territory and all
+    // absent on every mechanical close. A judged stage with no seam STOPS as a
+    // wiring gap rather than falling back to some other model (M1 owns no
+    // provider), and `judgeModel` is the seam's OTHER half (PRD item 32.1) —
+    // WHICH model the seam drives, resolved by the caller (`resolveJudge`,
+    // src/judged.js) and passed through untouched here, exactly as `judgeLoop`
+    // is. `runStage` checks the identity before the seam, so a judged stage with
+    // neither wired reports the identity gap, and one with only the seam missing
+    // still names the judge it would have graded with. Every locate call the
+    // seam buys is reported OUT through the meter so the run's ONE ledger can
+    // see it — a close has cost $0 until this kind, and a budget must fund the
+    // attempt PLUS its close.
     judgeLoop,
+    judgeModel,
     onJudgeCost,
+    // F152/PRD 30.4 — the SAME per-call time bounds every worker round already
+    // carries (`callBounds()`, src/planrun.js:1518), so the judged stage's own
+    // locate call cannot hang the process on a live silent endpoint. `null` is
+    // the honest absence (an adopter/test that wires no clock through), never a
+    // defaulted number invented here.
+    callBounds,
     seedTrees,
   };
   try {

package/src/index.js

@@ -146,15 +146,18 @@ export {
 // hitl checkpoint keeps. It never returns, writes or implies a verdict.
 export { answerReviewDoor, doorRecordOf, doorAgeGate } from './reviewdoor.js';
 // SOFTGREEN module 1 — the judged floor's core. The pieces an adopter (and an
-// integrating UI) genuinely needs: the PIN (`JUDGE_MODEL` — what a wired judge
-// provider must be bound to, and a bump of which forces recalibration), the
-// rulebook a card SELECTS from, the card gate, and the two halves themselves so a
-// calibration harness can grade the whole pipe without running a close.
+// integrating UI) genuinely needs: `resolveJudge` (PRD item 32.1 — WHICH model
+// grades a job: the spec's signed `judge` override, else the job's own worker
+// model, and no library fall-back), `JUDGE_MODEL` (the pre-item-32 pin, kept
+// exported for adopters and still the right default for an anthropic-api job,
+// but no longer read by any grading path), the rulebook a card SELECTS from,
+// the card gate, and the two halves themselves so a calibration harness can
+// grade the whole pipe without running a close.
 // `defaultJudgeLoop` is the one spelling of how this repo drives a judge; the
 // runner reaches it through `runPlan`'s `judgeProvider`, and it is exported so a
 // caller building its own harness does not spell a second one.
 export {
-  JUDGE_MODEL, JUDGE_MAX_TOKENS, JUDGE_RULES, JUDGE_RULE_IDS, LOCATE_AXES, LOCATE_LABEL,
+  JUDGE_MODEL, resolveJudge, JUDGE_MAX_TOKENS, JUDGE_RULES, JUDGE_RULE_IDS, LOCATE_AXES, LOCATE_LABEL,
   validateCard, validateFacts, locatePrompt, runLocate, decide, defaultJudgeLoop,
   // SOFTGREEN module 4 — what a legal SIGNED calibration set is. The SIZE is
   // hamr's own ruling and a size change is a spec-level threshold change;

package/src/job.js

@@ -133,7 +133,32 @@ export const CADENCE_UNITS = Object.freeze(['hour', 'day', 'week']);
  * 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. */
-export const PROVIDERS = Object.freeze(['anthropic-api', 'clipipe-subscription']);
+/** 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 = Object.freeze(['anthropic-api', 'openai-api', 'gemini-api', 'clipipe-subscription']);
 /** 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,
  * not duplicated here). */
@@ -141,7 +166,10 @@ export const CONDITION_KEYS = Object.freeze(['providerPath', 'closeVerbosity', '
 // `steps` stays in the field list ONLY so a retired spec reds by name
 // (`shape-retired`) instead of falling through to a generic unknown-field —
 // the operator gets told what happened, not just that something is wrong.
-const JOB_FIELDS = ['schema', 'job', 'description', 'provider', 'conditions', 'cadence', 'budgetUsd', 'maxWallMs', 'closeTimeoutMs', 'model', 'writeScope', 'steps', 'escalation', 'goal', 'verdictType', 'close', 'closeDecl', 'checks', 'tools'];
+const JOB_FIELDS = ['schema', 'job', 'description', 'provider', 'baseUrl', 'conditions', 'cadence', 'budgetUsd', 'maxWallMs', 'closeTimeoutMs', 'model', 'judge', 'writeScope', 'steps', 'escalation', 'goal', 'verdictType', 'close', 'closeDecl', 'checks', 'tools'];
+/** the exact fields of a signed `judge` override — nested objects red unknown
+ * keys too, because no smuggling level exists in a signed spec */
+const JUDGE_FIELDS = ['provider', 'model'];
 /** the four-field plan shape's core (decision 5) — presence of any of these
  * declares the shape; `tools` (the ceiling) rides the shape but alone does not
  * declare it, so a legacy spec carrying it gets a pointed red, not a conflict */
@@ -267,6 +295,68 @@ export function validateJob(input, { shellCapUsd = 2 } = {}) {
     red('invalid-value', 'model', 'non-empty string — exact provider model id (e.g. "claude-sonnet-5")');
   }
 
+  // JUDGE — PRD item 32.1 (hamr, 2026-09-10: the judge "defaults to whatever
+  // llm is used and can be overriden"). OPTIONAL, and the OVERRIDE half: absent,
+  // the judge resolves to this job's own worker provider and model
+  // (`resolveJudge`, src/judged.js), which is what lets a DeepSeek or Gemini job
+  // judge without a second account. Present, it pins a judge deliberately
+  // different from the worker — an independent reader.
+  //
+  // It is signed like `model`/`baseUrl` above: `jobSpecHash` canonizes the whole
+  // resolved spec, so naming a judge is the OPERATOR signing off on who examines
+  // this work. The drafting agent cannot express it — naming your own examiner is
+  // arbiter territory, and the authoring schema has no such field.
+  //
+  // BOTH halves are required together, deliberately. A `judge` carrying only a
+  // provider would have to invent a model, and a judge identity nobody wrote is
+  // the state the calibration record exists to make impossible.
+  if (spec.judge !== undefined) {
+    if (!isObj(spec.judge)) {
+      red('invalid-value', 'judge', 'an object {provider, model} — the signed judge override; omit it to judge on this job\'s own worker model');
+    } else {
+      for (const key of Object.keys(spec.judge)) {
+        if (!JUDGE_FIELDS.includes(key)) red('unknown-field', `judge.${key}`, `declared keys only: ${JUDGE_FIELDS.join('|')}`);
+      }
+      if (!PROVIDERS.includes(spec.judge.provider)) {
+        red('invalid-value', 'judge.provider', `menu: ${PROVIDERS.join('|')} — the judge runs through the same provider factory the worker does, so an off-menu judge is a provider nothing can construct`);
+      }
+      if (!isNonEmptyString(spec.judge.model)) {
+        red('invalid-value', 'judge.model', 'non-empty string — exact provider model id; a judge with a provider and no model is an identity nobody signed');
+      }
+    }
+  }
+
+  // BASE URL — PRD item 28, ruling (d), 2026-09-09: admitted in v1 of
+  // openai-api (an OpenAI-compatible gateway/endpoint), OPTIONAL and part of
+  // the signed hash like `model` above. This validator has no network
+  // access, so it checks SHAPE only: `https://` for a real endpoint, or
+  // `http://` restricted to a loopback host (a local OpenAI-compatible
+  // server, the only legitimate reason to skip TLS) — and never a
+  // credential embedded IN the URL itself. A URL travels into logs and
+  // spine records far more casually than a header ever would, and secrets
+  // never enter the tree/spine (hard line #3) — a bareUrl carrying
+  // `user:pass@host` is exactly that leak, just spelled differently.
+  if (spec.baseUrl !== undefined) {
+    if (!isNonEmptyString(spec.baseUrl)) {
+      red('invalid-value', 'baseUrl', 'non-empty string — an https:// URL (http:// admitted only to 127.0.0.1/localhost/::1)');
+    } else {
+      /** @type {URL|null} */
+      let u = null;
+      try { u = new URL(spec.baseUrl); } catch { /* u stays null — caught below */ }
+      if (!u) {
+        red('invalid-value', 'baseUrl', 'must be a parseable URL');
+      } else if (u.username !== '' || u.password !== '') {
+        red('invalid-value', 'baseUrl', 'no embedded credentials (user:pass@host) — secrets never enter a signed spec');
+      } else if (u.protocol === 'https:') {
+        // admitted
+      } else if (u.protocol === 'http:' && (u.hostname === '127.0.0.1' || u.hostname === 'localhost' || u.hostname === '::1')) {
+        // admitted — a local OpenAI-compatible endpoint, the one case that legitimately skips TLS
+      } else {
+        red('invalid-value', 'baseUrl', 'https:// required (http:// admitted only to 127.0.0.1/localhost/::1)');
+      }
+    }
+  }
+
   // 3. the outer write fence — operator law (interview decision #4), same
   // containment rules as the workflow layer THROUGH THE SAME CODE (F9: two
   // transforms would let a fence validate green and mean something else).