bareloop 0.23.0 → 0.25.0

package/src/cli.js

@@ -31,7 +31,7 @@ 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';
 
@@ -84,9 +84,34 @@ function buildProviders(apiKey, spec) {
   const MODEL = modelResolution.model;
   const tierModels = modelResolution.source === 'spec' ? { ...entry.tiers, sonnet: MODEL } : entry.tiers;
   const baseUrl = isObj(spec) && typeof spec.baseUrl === 'string' ? spec.baseUrl : undefined;
-  return buildRunnerProviders({
-    providerName, apiKey, model: MODEL, tierModels, baseUrl, judgeApiKey: apiKey, judgeModel: JUDGE_MODEL,
+  // 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> }} */
@@ -236,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) {
@@ -246,7 +276,7 @@ async function doRun(args, { out, err, cwd, env, now, deps }) {
       return 0;
     }
     try {
-      ({ provider, providerFor, judgeProvider } = buildProviders(apiKey, bundle.spec));
+      ({ 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));
@@ -338,6 +368,7 @@ async function doRun(args, { out, err, cwd, env, now, deps }) {
       provider,
       providerFor,
       judgeProvider,
+      judgeModel,
       emit,
       closeDir,
       shellCapUsd: runSpec.budgetUsd,
@@ -470,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,6 +566,7 @@ 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,
+ *   judgeModel?: string|null,
  *   onJudgeCost?: ((c: any) => void)|null,
  *   callBounds?: (() => {timeoutMs?: number, deadlineMs?: number})|null}} [opts]
  * @returns {Promise<any>}
@@ -574,7 +574,7 @@ function translate(r, redact) {
 export async function runDeclaredStages(stages, redact = (s) => s, opts = {}) {
   const {
     timeoutMs, cwd, seedRef, seedTrees: shared, gapCap, maxBuffer, baselineMode, humanRuling = null,
-    judgeLoop = null, onJudgeCost = null, callBounds = 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
@@ -604,13 +604,20 @@ 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

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;
@@ -282,3 +285,12 @@ export {
 // exists so an adopter driving `bareloop run` from their own script can do so
 // without spawning `bin/bareloop.mjs` as a child process.
 export { main as cliMain } from './cli.js';
+// PRD item 33/M2 (`docs/product/ITEM33-BUILD.md`) — the source front door. A
+// plain folder, a plain file, or one URL frozen into a hidden git tree before
+// any token spends (H1's fix: the person never sees the repo), and the
+// destination proven/copied at the two moments a runner needs them ($0
+// preflight, and once on a minted green). Exported because `scripts/prep-
+// source.mjs` and `scripts/run-u.mjs` are two separate call sites reaching
+// for the SAME functions — an adopter building a third has to reach the same
+// module, not a re-derivation of it.
+export { prepareSource, proveDestination, copyOut, readSourceManifest, frontDoorFromManifest } from './source.js';

package/src/job.js

@@ -136,8 +136,29 @@ export const CADENCE_UNITS = Object.freeze(['hour', 'day', 'week']);
 /** 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. */
-export const PROVIDERS = Object.freeze(['anthropic-api', 'openai-api', 'clipipe-subscription']);
+ * 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). */
@@ -145,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', 'baseUrl', '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 */
@@ -271,6 +295,37 @@ 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

package/src/judged.js

@@ -65,32 +65,150 @@
 
 import { createRequire } from 'node:module';
 import { extractArtifact, priceOf, scrubRaw } from './text.js';
+import { resolveProvider } from './providers.js';
 
 const require = createRequire(import.meta.url);
 
 /**
- * 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.
  *
- * 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`
+ * 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).
+ *
+ * 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';
 
+/**
+ * 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 } = {}) {
+  const nonEmpty = (/** @type {any} */ v) => typeof v === 'string' && v.trim() !== '';
+  if (specJudge !== null && typeof specJudge === 'object'
+    && nonEmpty(specJudge.provider) && nonEmpty(specJudge.model)) {
+    return { provider: specJudge.provider, model: specJudge.model };
+  }
+  if (specJudge !== undefined && specJudge !== null) {
+    // A malformed `judge` is never quietly ignored into the worker default: the
+    // spec VALIDATOR reds it (src/job.js), and reaching here with one means a
+    // caller skipped validation. Throwing beats grading under an identity the
+    // signer did not write.
+    throw new Error('[judged] spec.judge, when present, is {provider, model} with both non-empty — '
+      + `got ${JSON.stringify(specJudge)}. A malformed judge is not a request to use the worker's.`);
+  }
+  if (!nonEmpty(workerProvider) || !nonEmpty(workerModel)) {
+    throw new Error('[judged] resolveJudge needs the job\'s worker provider and model to default the judge to them '
+      + '(PRD item 32.1) — a caller that can name neither a judge nor a worker has not wired a judge, and there is '
+      + 'no library-pinned fall-back any more.');
+  }
+  return { provider: /** @type {string} */ (workerProvider), model: /** @type {string} */ (workerModel) };
+}
+
+/**
+ * `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, fallbackProviderName, resolveWorkerModelFn) {
+  const providerName = source?.provider ?? fallbackProviderName;
+  const providerEntry = resolveProvider(providerName);
+  const { model } = resolveWorkerModelFn({
+    specModel: source?.model, flagModel: undefined, defaultModel: providerEntry.tiers.sonnet,
+  });
+  return resolveJudge({ specJudge: source?.judge, workerProvider: providerName, workerModel: model });
+}
+
 /**
  * The locate call's token ceiling. The POC's two real artifacts came back well
  * inside 2000; this doubles that for headroom on a longer artifact, and the

package/src/kinds.js

@@ -66,7 +66,7 @@ import { tmpdir } from 'node:os';
 import { join, sep } from 'node:path';
 import { globToPrefix, isNonEmptyString } from './validate.js';
 import { CLOSE_ENV_DENY } from './ralph.js';
-import { runLocate, decide, validateCard, LOCATE_AXES, LOCATE_LABEL, JUDGE_MODEL } from './judged.js';
+import { runLocate, decide, validateCard, LOCATE_AXES, LOCATE_LABEL } from './judged.js';
 
 /** the close's two judgment exits — a stage's verdict, in the shape the
  * hand-written closes already spoke (exit code is truth) */
@@ -173,6 +173,46 @@ export const MAX_JUDGED_PATHS = 8;
  * decision on it, and five literals is how they come to disagree. */
 export const JUDGED_FLOOR_KIND = 'judged-floor';
 export const SEED_EXEMPT_KINDS = Object.freeze([JUDGED_FLOOR_KIND, 'human-confirms']);
+
+/**
+ * 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) {
+  const stages = closeDecl && typeof closeDecl === 'object' ? closeDecl.stages : undefined;
+  if (!Array.isArray(stages)) return [];
+  return stages.filter((s) => s !== null && typeof s === 'object' && s.kind === JUDGED_FLOOR_KIND);
+}
+
+/**
+ * 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) {
+  return judgedStages(closeDecl).length > 0;
+}
 /** the one kind a PERSON renders — named once, because the runner keys three
  * decisions on it (is there a door to answer, which stage paused, whose ruling
  * this is) and three literals is how they come to disagree */
@@ -258,6 +298,7 @@ export function mechanicalStages(stages) {
  *   gapCap?: number, maxBuffer?: number, seedTrees?: SeedTrees,
  *   humanRuling?: {decision: string, text?: string|null}|null,
  *   judgeLoop?: (o: {system: string}) => any,
+ *   judgeModel?: string,
  *   onJudgeCost?: (c: {stage: string|null, kind: string|null, path: string, attempt: number,
  *     label: string, model: string, costUsd: number|null, unpricedRounds: number}) => void,
  *   callBounds?: () => {timeoutMs?: number, deadlineMs?: number},
@@ -268,10 +309,16 @@ export function mechanicalStages(stages) {
  *   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
@@ -438,9 +485,15 @@ async function sh(cmd, args, { cwd, env: declared = {}, timeoutMs = DEFAULT_TIME
 /**
  * git, read-only, in a repository. Faults come back as `ok:false` with the
  * stderr — a caller decides whether that is a stop.
+ *
+ * Exported (PRD item 33/M2, `src/source.js`) so the hidden-git seed a plain
+ * folder/file/URL job runs against goes through the SAME spawn primitive as
+ * every other git read in this file — a second `spawn('git', …)` for the
+ * source front door would be a second instrument with its own timeout and
+ * buffer ceiling to keep in sync with this one.
  * @param {string} cwd @param {string[]} args
  */
-async function git(cwd, args) {
+export async function git(cwd, args) {
   const r = await sh('git', args, { cwd, timeoutMs: 120_000 });
   // git refusing IS "the close cannot run": the changed-set primitive is not an
   // optional enrichment, so a non-zero git carries FAILED rather than inheriting
@@ -1736,16 +1789,34 @@ async function runJudgedFloor(stage, ctx) {
   //     model on it (`validateCloseDecl`), so the runtime question is only ever WHICH
   //     model — and a stage descriptor handed straight to `runStage` by an adopter or a
   //     test is not a signed spec making a claim about a tier.
-  if (isNonEmptyString(stage.calibrationJudgeModel) && stage.calibrationJudgeModel !== JUDGE_MODEL) {
-    return stopped(stage, ctx, `INSTRUMENT: stage "${stage.name}" would grade with ${JUDGE_MODEL}, and the calibration `
-      + `set signed with this close was graded by ${stage.calibrationJudgeModel} — the judge tier moved under the `
+  //
+  // PRD item 32.1: WHICH model grades is no longer this module's constant — it is
+  // `ctx.judgeModel`, the identity the run resolved and wired (`resolveJudge`,
+  // src/judged.js: the spec's signed `judge` override, else the job's own worker
+  // model). The IDENTITY is checked before the seam and before the stamp, because
+  // an unwired identity makes both of the messages below unwritable: neither
+  // "would grade with X" nor "the judge is X" can be said by a stage that cannot
+  // name X. There is deliberately NO fall-back to `JUDGE_MODEL` here — a run that
+  // cannot say which model grades has not wired a judge, and grading under an
+  // identity nobody chose is exactly the silent-ignore class this repo refuses
+  // everywhere else.
+  if (!isNonEmptyString(ctx.judgeModel)) {
+    return stopped(stage, ctx, `INSTRUMENT: stage "${stage.name}" is a judged stage and this run wired no judge IDENTITY `
+      + '(ctx.judgeModel) — an adopter wiring gap, never a silent fall-back to a library pin. A verdict whose grader '
+      + 'cannot be named is a floor nobody can attribute, and the calibration record has nothing to compare against',
+    {}, STOP_FAULTS.FAILED);
+  }
+  const judgeModel = /** @type {string} */ (ctx.judgeModel);
+  if (isNonEmptyString(stage.calibrationJudgeModel) && stage.calibrationJudgeModel !== judgeModel) {
+    return stopped(stage, ctx, `INSTRUMENT: stage "${stage.name}" would grade with ${judgeModel}, and the calibration `
+      + `set signed with this close was graded by ${stage.calibrationJudgeModel} — the judge moved under the `
       + 'signature. A floor is worth exactly the judge that certified it, so this stops rather than grading against a '
-      + 'floor nobody calibrated: re-sign the spec with the new tier and re-run the calibration gate (recalibrate)',
-    { signedJudgeModel: stage.calibrationJudgeModel, judgeModel: JUDGE_MODEL }, STOP_FAULTS.FAILED);
+      + 'floor nobody calibrated: re-sign the spec with the new judge and re-run the calibration gate (recalibrate)',
+    { signedJudgeModel: stage.calibrationJudgeModel, judgeModel }, STOP_FAULTS.FAILED);
   }
   if (typeof ctx.judgeLoop !== 'function') {
     return stopped(stage, ctx, `INSTRUMENT: stage "${stage.name}" is a judged stage and this run wired no judge seam `
-      + `(ctx.judgeLoop) — an adopter wiring gap, never a silent fall-back: the judge is ${JUDGE_MODEL}, pinned, and a `
+      + `(ctx.judgeLoop) — an adopter wiring gap, never a silent fall-back: the judge is ${judgeModel} and a `
       + 'stage that quietly graded on whatever model was lying around would be a floor nobody calibrated',
     {}, STOP_FAULTS.FAILED);
   }
@@ -1797,7 +1868,7 @@ async function runJudgedFloor(stage, ctx) {
           if (typeof ctx.onJudgeCost !== 'function') return;
           ctx.onJudgeCost({
             stage: stage?.name ?? null, kind: stage?.kind ?? null, path: rel, attempt,
-            label: LOCATE_LABEL, model: JUDGE_MODEL, costUsd: c.costUsd, unpricedRounds: c.unpricedRounds,
+            label: LOCATE_LABEL, model: judgeModel, costUsd: c.costUsd, unpricedRounds: c.unpricedRounds,
           });
         },
       });
@@ -1848,7 +1919,7 @@ async function runJudgedFloor(stage, ctx) {
     exitCode: red ? EXIT_RED : EXIT_GREEN,
     gapLines: gap.render(),
     detail: {
-      model: JUDGE_MODEL,
+      model: judgeModel,
       card: p.card.items.map((/** @type {any} */ it) => it.rule),
       paths,
       perPath,

package/src/planrun.js

@@ -714,8 +714,15 @@ ${scoutBlob || '(no scout notes)'}`;
  *   `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
@@ -928,7 +935,7 @@ ${scoutBlob || '(no scout notes)'}`;
  *   'branch-red' | 'cap-halt' | 'wall-halt' | 'provider-red' | 'interpreter-red' |
  *   'step-stalled' | 'hitl-pause' | 'hitl-decision-red' | `step-red:<id>`
  */
-export async function runPlan(job, { workdir, provider, nativeProvider, providerFor, judgeProvider = null, emit, remainingUsd, isUnpriced = () => false, spendComplete = () => true, capRuns = 3, strikeLimit = STRIKE_LIMIT, closeTimeoutMs, closeDir = null, maxStepRounds = 40, layerRoot = false, readShim = false, scout = true, scoutRounds = SCOUT_ROUNDS, bridge = null, now, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null, heldRuling = null, priorSpentUsd = 0, reviewDoor = null, doorRerun = null, resumable = true }) {
+export async function runPlan(job, { workdir, provider, nativeProvider, providerFor, judgeProvider = null, judgeModel = null, emit, remainingUsd, isUnpriced = () => false, spendComplete = () => true, capRuns = 3, strikeLimit = STRIKE_LIMIT, closeTimeoutMs, closeDir = null, maxStepRounds = 40, layerRoot = false, readShim = false, scout = true, scoutRounds = SCOUT_ROUNDS, bridge = null, now, priorWallMs = 0, resumeSeed = null, resumeGrades = [], resumeReplans = null, resumeBranch = null, humanRuling = null, heldRuling = null, priorSpentUsd = 0, reviewDoor = null, doorRerun = null, resumable = true }) {
   // MEMORY-CACHE: what the read shim (src/readshim.js) saved THIS run, summed across
   // every mkWorker's own shim instance (scout, drafter, each step's worker, the fix
   // worker) — one accumulator closed over by all of them, because the shim's ledger
@@ -1633,6 +1640,11 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
       // an attempt's (a budget funds the attempt PLUS its close), and a null cost trips
       // the same F6 pricing halt rather than being laundered into $0.
       judgeLoop: judgeProvider ? (/** @type {{system: string}} */ o) => defaultJudgeLoop({ provider: judgeProvider, system: o.system }) : null,
+      // the seam's other half (PRD item 32.1) — WHICH model that loop drives. Passed
+      // through untouched: this module resolves no judge, exactly as it constructs no
+      // provider. `runJudgedFloor` stops as a wiring gap when it is absent rather than
+      // falling back to a library pin, so a null here is a stop and never a default.
+      ...(judgeModel === null ? {} : { judgeModel }),
       // F152/PRD 30.4 — the judge's locate call carried NO time bound at all: a
       // live endpoint that accepts and never answers hung the process forever
       // (measured), because an open socket is an active handle and no backstop