faberun 0.25.1 → 0.26.0

package/src/contract/judge-independence.mjs

@@ -0,0 +1,170 @@
+/**
+ * Validation for the `judgeIndependence` contract field (R20): the opt-in
+ * that lets a same-vendor judge review a node an operator with a single
+ * provider could otherwise never gate. Split from `contract/index.mjs`,
+ * mirroring `judges.mjs` (R18), because the tier comparison and its refusal
+ * belong with the field that turns them on, not scattered through the
+ * vendor-conflict check that calls them.
+ */
+import { declaredModelTier } from "../harnesses/model-tiers.mjs";
+
+/** The only value `judgeIndependence` accepts, on the contract or the machine config. */
+export const SAME_VENDOR_REVIEW_MODE = "same-vendor";
+
+/** The label every human-facing surface uses to mark a node reviewed under the mode. */
+export const SAME_PROVIDER_REVIEW_LABEL = "same-provider review";
+
+/**
+ * @param {unknown} value
+ * @param {string} label
+ * @returns {"same-vendor"|undefined}
+ */
+export function validateJudgeIndependence(value, label) {
+  if (value === undefined) return undefined;
+  if (value !== SAME_VENDOR_REVIEW_MODE) throw new TypeError(`${label} must be "${SAME_VENDOR_REVIEW_MODE}"`);
+  return value;
+}
+
+/**
+ * Same-vendor mode's own admissibility rule for a worker/judge pair that
+ * share a vendor: a judge model absent from the declared tier table can never
+ * judge in this mode, and a judge tier below the worker's is refused, naming
+ * both. `null` means the pair is admissible.
+ *
+ * @param {{harness: string, model: string}} workerRuntime
+ * @param {{harness: string, model: string}} judgeRuntime
+ * @returns {{code: string, message: string}|null}
+ */
+export function sameVendorTierRefusal(workerRuntime, judgeRuntime) {
+  const judgeTier = declaredModelTier(judgeRuntime.harness, judgeRuntime.model);
+  if (judgeTier === null) {
+    return {
+      code: "same_vendor_judge_no_tier",
+      message: `judge model ${judgeRuntime.model} declares no tier and cannot judge in same-vendor mode`,
+    };
+  }
+  const workerTier = declaredModelTier(workerRuntime.harness, workerRuntime.model);
+  if (workerTier !== null && judgeTier < workerTier) {
+    return {
+      code: "same_vendor_judge_tier_too_low",
+      message: `judge tier ${judgeTier} (${judgeRuntime.model}) is below worker tier ${workerTier} (${workerRuntime.model})`,
+    };
+  }
+  return null;
+}
+
+/**
+ * Whether a worker runtime that actually ran and a judge runtime that
+ * actually ran are a same-provider pairing: the mode is opted in and the two
+ * share a vendor. Contract validation already refused every reachable
+ * worker/judge pairing (primary or fallback) that fails the tier rule, so
+ * this is a plain vendor comparison at dispatch time, not a second
+ * enforcement of it.
+ *
+ * @param {{judgeIndependence?: string}} contract
+ * @param {{vendor?: string}|null|undefined} workerRuntime
+ * @param {{vendor?: string}|null|undefined} judgeRuntime
+ * @returns {boolean}
+ */
+export function isSameProviderReviewPair(contract, workerRuntime, judgeRuntime) {
+  if (contract.judgeIndependence !== SAME_VENDOR_REVIEW_MODE) return false;
+  const workerVendor = workerRuntime?.vendor;
+  const judgeVendor = judgeRuntime?.vendor;
+  return Boolean(workerVendor) && workerVendor === judgeVendor;
+}
+
+/**
+ * Whether `workerRuntimeId` or its one declared fallback hop could share
+ * `judgeVendor`: the structural "this pairing might land same-provider"
+ * fact a plan-time surface (the Campaign Brief) can read before any node has
+ * run, mirroring the one-hop rule `engine/failover.mjs` enforces at dispatch.
+ * A run-time surface reading a completed node's snapshot should prefer the
+ * dynamic fact instead (`isSameProviderReviewPair` against the runtime that
+ * actually ran).
+ *
+ * @param {Record<string, {vendor?: string, fallback?: string}>} runtimes
+ * @param {string} workerRuntimeId
+ * @param {string|null|undefined} judgeVendor
+ * @returns {boolean}
+ */
+export function sharesVendorThroughFallback(runtimes, workerRuntimeId, judgeVendor) {
+  if (!judgeVendor) return false;
+  const seen = new Set([workerRuntimeId]);
+  let currentId = workerRuntimeId;
+  while (currentId !== undefined) {
+    if (runtimes[currentId]?.vendor === judgeVendor) return true;
+    const nextId = runtimes[currentId]?.fallback;
+    if (nextId === undefined || seen.has(nextId)) break;
+    seen.add(nextId);
+    currentId = nextId;
+  }
+  return false;
+}
+
+/**
+ * A gated node whose worker and judge share a vendor cannot produce an
+ * independent review -- the same vendor grading its own output is not a
+ * gate, so this is rejected outright unless `judgeIndependence` opts the
+ * contract into same-vendor mode, in which case a judge tier at or above the
+ * worker's admits the pair and marks the node `sameProviderReview` for every
+ * human-facing surface to read back. The worker's declared fallback chain is
+ * checked the same way, since it is statically known which runtime a worker
+ * failover lands on; the symmetric case -- the judge's own fallback landing
+ * on the worker's vendor -- depends on which worker runtime actually ran and
+ * is refused at execution instead (node.mjs, `judge_fallback_vendor_conflict`).
+ *
+ * Mutates and returns `nodes` in place; called once per `validateContract`.
+ *
+ * @param {{gate: {enabled: boolean, runtime?: string}, runtime?: string, sameProviderReview: boolean}[]} nodes
+ * @param {Record<string, {vendor?: string, fallback?: string, harness: string, model: string}>} runtimes
+ * @param {{worker?: string, judge?: string}} defaults
+ * @param {"same-vendor"|undefined} judgeIndependence
+ * @returns {{gate: {enabled: boolean, runtime?: string}, runtime?: string, sameProviderReview: boolean}[]}
+ */
+export function markSameProviderReviewNodes(nodes, runtimes, defaults, judgeIndependence) {
+  for (const [index, node] of nodes.entries()) {
+    if (!node.gate.enabled) continue;
+    const workerRuntimeId = node.runtime ?? defaults.worker;
+    const judgeRuntimeId = node.gate.runtime ?? defaults.judge;
+    if (!workerRuntimeId || !judgeRuntimeId) continue;
+    const workerRuntime = runtimes[workerRuntimeId];
+    const judgeRuntime = runtimes[judgeRuntimeId];
+    const workerVendor = workerRuntime.vendor;
+    const judgeVendor = judgeRuntime.vendor;
+    if (workerVendor === judgeVendor) {
+      if (judgeIndependence !== SAME_VENDOR_REVIEW_MODE) {
+        throw new TypeError(`nodes[${index}] worker runtime ${workerRuntimeId} and judge runtime ${judgeRuntimeId} share vendor ${workerVendor}`);
+      }
+      const refusal = sameVendorTierRefusal(workerRuntime, judgeRuntime);
+      if (refusal) {
+        throw new TypeError(`nodes[${index}] worker runtime ${workerRuntimeId} and judge runtime ${judgeRuntimeId} share vendor ${workerVendor}: ${refusal.message}`);
+      }
+      nodes[index] = { ...node, sameProviderReview: true };
+    }
+    const seenFallbacks = new Set([workerRuntimeId]);
+    let fallbackId = runtimes[workerRuntimeId].fallback;
+    while (fallbackId !== undefined) {
+      if (seenFallbacks.has(fallbackId)) {
+        throw new TypeError(`nodes[${index}] worker runtime ${workerRuntimeId} fallback chain cycles back to ${fallbackId}`);
+      }
+      seenFallbacks.add(fallbackId);
+      const fallbackVendor = runtimes[fallbackId].vendor;
+      if (fallbackVendor === judgeVendor) {
+        if (judgeIndependence !== SAME_VENDOR_REVIEW_MODE) {
+          throw new TypeError(`nodes[${index}] worker runtime ${workerRuntimeId} fallback runtime ${fallbackId} and judge runtime ${judgeRuntimeId} share vendor ${fallbackVendor}`);
+        }
+        const fallbackRefusal = sameVendorTierRefusal(runtimes[fallbackId], judgeRuntime);
+        if (fallbackRefusal) {
+          throw new TypeError(`nodes[${index}] worker runtime ${workerRuntimeId} fallback runtime ${fallbackId} and judge runtime ${judgeRuntimeId} share vendor ${fallbackVendor}: ${fallbackRefusal.message}`);
+        }
+        // The fallback is only reachable if it actually runs, but the tier
+        // rule above already admitted it -- so the node is marked here too,
+        // not only when the primary matches (the plan-time "could this land
+        // same-provider" fact every human-facing surface reads back).
+        nodes[index] = { ...nodes[index], sameProviderReview: true };
+      }
+      fallbackId = runtimes[fallbackId].fallback;
+    }
+  }
+  return nodes;
+}

package/src/contract/judges.mjs

@@ -0,0 +1,27 @@
+/**
+ * Validation for the `judges` contract field (R18): a static, ordered list of
+ * runtime ids the engine reads before falling back to the machine default or
+ * the single strongest cross-vendor candidate. Split from `contract/index.mjs`,
+ * which is already near this repository's 800-line ceiling.
+ */
+import { requireId } from "./assert.mjs";
+import { requireRuntime } from "./runtime.mjs";
+
+/** @typedef {import("./runtime.mjs").ValidatedRuntime} ValidatedRuntime */
+
+/**
+ * @param {unknown} value
+ * @param {Record<string, ValidatedRuntime>} runtimes
+ * @param {string} label
+ * @returns {string[]|undefined}
+ */
+export function validateJudgeList(value, runtimes, label) {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value) || value.length === 0) throw new TypeError(`${label} must be a non-empty array of runtime ids`);
+  value.forEach((id, index) => {
+    requireId(id, `${label}[${index}]`);
+    requireRuntime(runtimes, id, `${label}[${index}]`);
+  });
+  if (new Set(value).size !== value.length) throw new TypeError(`${label} must not repeat a runtime id`);
+  return /** @type {string[]} */ (value);
+}

package/src/contract/provider.mjs

@@ -0,0 +1,103 @@
+/**
+ * The canonical provider a runtime actually talks to, as opposed to its
+ * free-text `vendor` label. Split from runtime.mjs because both the contract
+ * validator and every worker-against-judge vendor comparison across `plan/`,
+ * `engine/`, `harnesses/` and `cli/` need it, and none of those layers should
+ * import the runtime schema validator just to reach it.
+ */
+import { DEFAULT_HARNESS_VENDORS } from "../harnesses/index.mjs";
+
+/** @typedef {{harness?: string, model?: string, config?: Record<string, unknown>}} ProviderInput */
+
+/**
+ * The five canonical providers a runtime can derive to. A runtime whose
+ * harness names no default and whose model matches no family below derives
+ * none of these — `replay` and `exec-jsonl` never do, since either stands in
+ * for whatever the recording or the exec'd binary actually is.
+ *
+ * @type {ReadonlyArray<"openai"|"anthropic"|"zhipu"|"deepseek"|"google">}
+ */
+const CANONICAL_PROVIDERS = Object.freeze(["openai", "anthropic", "zhipu", "deepseek", "google"]);
+
+/**
+ * Model-id family prefixes, checked before the harness default so an
+ * `agy` runtime reselling `claude-sonnet-4-6` derives `anthropic`, not `agy`'s
+ * own default of `google`.
+ *
+ * @type {ReadonlyArray<{pattern: RegExp, provider: string}>}
+ */
+const MODEL_FAMILY_PROVIDERS = Object.freeze([
+  { pattern: /^claude-|^opus\b|^sonnet\b|^fable\b|^haiku\b/iu, provider: "anthropic" },
+  { pattern: /^gpt-|^o\d/iu, provider: "openai" },
+  { pattern: /^gemini-/iu, provider: "google" },
+  { pattern: /^glm-/iu, provider: "zhipu" },
+  { pattern: /^deepseek-/iu, provider: "deepseek" },
+]);
+
+/**
+ * The harnesses whose runtime always stands in for an arbitrary provider: the
+ * recording (`replay`) or the exec'd binary (`exec-jsonl`) decide, never this
+ * module.
+ */
+const NO_CANONICAL_PROVIDER_HARNESSES = new Set(["replay", "exec-jsonl"]);
+
+/**
+ * The provider a runtime declares a route to, read from the config key its
+ * own harness uses for that: codex's `config.model_provider` (for example
+ * `deepseek`) and dsh's `config.provider` (`deepseek-official` names
+ * `deepseek`). A route naming none of the five canonical providers is not a
+ * route this function recognizes, so derivation falls through to the model's
+ * family and then the harness default.
+ *
+ * @param {ProviderInput} runtime
+ * @returns {string|null}
+ */
+function routedProvider(runtime) {
+  const config = runtime.config;
+  if (!config || typeof config !== "object") return null;
+  const route = runtime.harness === "codex"
+    ? config.model_provider
+    : runtime.harness === "dsh"
+      ? config.provider
+      : undefined;
+  if (typeof route !== "string" || route.length === 0) return null;
+  const lowered = route.toLowerCase();
+  return CANONICAL_PROVIDERS.find((provider) => lowered.includes(provider)) ?? null;
+}
+
+/**
+ * The provider a runtime actually talks to, derived in order from (1) the
+ * route it declares to another provider, (2) its model id's family, and (3)
+ * its harness's own default. `null` means none of the three named one — the
+ * two test harnesses always land here, and any other harness does too when
+ * its model matches no known family and its harness names no default.
+ *
+ * @param {ProviderInput} runtime
+ * @returns {string|null}
+ */
+export function canonicalProvider(runtime) {
+  if (!runtime || typeof runtime.harness !== "string") return null;
+  if (NO_CANONICAL_PROVIDER_HARNESSES.has(runtime.harness)) return null;
+  const routed = routedProvider(runtime);
+  if (routed) return routed;
+  const model = typeof runtime.model === "string" ? runtime.model : "";
+  const family = MODEL_FAMILY_PROVIDERS.find((entry) => entry.pattern.test(model));
+  if (family) return family.provider;
+  return /** @type {Record<string, string>} */ (DEFAULT_HARNESS_VENDORS)[runtime.harness] ?? null;
+}
+
+/**
+ * The provider identity a worker-against-judge comparison actually compares:
+ * the canonical provider when one is derivable, the declared `vendor`
+ * otherwise. Every routing and failover site that used to compare `.vendor`
+ * directly compares this instead, so a contradicting label (R18) cannot
+ * survive `validateRuntime` and reach one of them, and a runtime that
+ * bypasses validation (a raw fixture, a discovery-catalogue definition) still
+ * compares consistently rather than by accident.
+ *
+ * @param {ProviderInput & {vendor?: string}} runtime
+ * @returns {string|undefined}
+ */
+export function effectiveProvider(runtime) {
+  return canonicalProvider(runtime) ?? runtime.vendor;
+}

package/src/contract/runtime.mjs

@@ -12,6 +12,7 @@
 import { assertObject, nonNegativeNumber, positiveInteger, positiveNumber, rejectUnknown, requireId, requireString, requireStringArray, requireTimestamp } from "./assert.mjs";
 import { composeAssignments } from "../engine/runtime-discovery.mjs";
 import { harnessCapabilities, resolvePermissionExecution, resolveVendor, validateCapabilityRequirements, writesWorkspace } from "../harnesses/index.mjs";
+import { canonicalProvider } from "./provider.mjs";
 import { stableJson } from "../util.mjs";
 /** @typedef {import("./index.mjs").NodeStatus} NodeStatus */
 /** @typedef {import("../engine/runtime-discovery.mjs").RuntimeAvailability} RuntimeAvailability */
@@ -98,8 +99,24 @@ export function validateRuntime(id, runtime) {
   assertObject(runtime, `runtime ${id}`);
   rejectUnknown(runtime, RUNTIME_FIELDS, `runtime ${id}`);
   validateRuntimeValues(runtime, `runtime ${id}`, runtime.harness === "exec-jsonl");
-  const vendor = resolveVendor(/** @type {{harness: string, vendor?: string, config?: Record<string, unknown>}} */ (runtime));
-  if (!vendor) throw new TypeError(`runtime ${id} has no resolvable vendor`);
+  const typedRuntime = /** @type {{harness: string, model: string, vendor?: string, config?: Record<string, unknown>}} */ (runtime);
+  // The canonical provider derived from the route, the model's family, or the
+  // harness default outranks a declared `vendor`: a label that contradicts it
+  // is refused (R18), and the runtime's vendor becomes the derived provider
+  // rather than whatever text the contract declared. `replay` and `exec-jsonl`
+  // derive none — for those the declared vendor stands, as it always has.
+  const derived = canonicalProvider(typedRuntime);
+  const declared = typeof typedRuntime.vendor === "string" && typedRuntime.vendor.length ? typedRuntime.vendor : undefined;
+  let vendor;
+  if (derived) {
+    if (declared !== undefined && declared !== derived) {
+      throw new TypeError(`runtime ${id} declares vendor ${declared} but ${typedRuntime.harness} ${typedRuntime.model} is provider ${derived}`);
+    }
+    vendor = derived;
+  } else {
+    vendor = resolveVendor(typedRuntime);
+    if (!vendor) throw new TypeError(`runtime ${id} has no resolvable vendor`);
+  }
   const stallTimeoutSec = runtime.stallTimeoutSec ?? HARNESS_STALL_TIMEOUT_SEC[/** @type {string} */ (runtime.harness)];
   return /** @type {ValidatedRuntime} */ ({
     ...runtime,

package/src/contract/snapshot.mjs

@@ -130,6 +130,7 @@ export function validateNodeSnapshot(value, expectedNode = null) {
     "attempt", "revisions", "judgeFailures", "requirementIds", "runtime", "blockedBy", "startedAt", "updatedAt", "result", "gate", "error", "usage",
     "costUsd", "routing", "progress", "worktree", "invocations", "executionOverrides", "verification", "scope",
     "scopeFindings", "verificationArtifacts", "review", "previousAttempt", "sessionPolicy", "integratedHead", "declaredReadBytes",
+    "sameProviderReview",
   ]), "node snapshot");
   validateMetadata(value, "node snapshot");
   requireId(value.id, "node snapshot.id");
@@ -148,6 +149,11 @@ export function validateNodeSnapshot(value, expectedNode = null) {
   if (value.review !== undefined && !REVIEW_MODES.has(/** @type {string} */ (value.review))) {
     throw new TypeError("node snapshot.review is invalid");
   }
+  // R20: whether this attempt's judge was admitted under same-vendor mode,
+  // stamped by `startJudge` from the contract's own `sameProviderReview`.
+  if (value.sameProviderReview !== undefined && typeof value.sameProviderReview !== "boolean") {
+    throw new TypeError("node snapshot.sameProviderReview must be a boolean");
+  }
   requirePacketHash(value.packetHash, "node snapshot.packetHash");
   validateSourceIdentity(value.sourceIdentity, "node snapshot.sourceIdentity", { kind: "node" });
   if (value.integratedHead !== undefined && value.integratedHead !== null) boundedString(value.integratedHead, "node snapshot.integratedHead", 256);
@@ -460,13 +466,36 @@ function validateTierExhaustion(value, label) {
     if (candidate.exhaustedUntil !== null) requireTimestamp(candidate.exhaustedUntil, `${label}.candidates[${index}].exhaustedUntil`);
   }
 }
+/**
+ * The durable evidence of one node's ordered judge-list selection (R18): the
+ * list it read, the entry it chose (null once every entry is skipped), and
+ * why each earlier one was -- appended to, never replaced, across a run's
+ * hop-by-hop fallback, so an entry already skipped for cause stays skipped.
+ *
+ * @param {unknown} value
+ * @param {string} label
+ */
+function validateJudgeListState(value, label) {
+  assertObject(value, label);
+  rejectUnknown(value, new Set(["list", "chosen", "skipped"]), label);
+  if (!Array.isArray(value.list) || value.list.length === 0) throw new TypeError(`${label}.list must be a non-empty array`);
+  value.list.forEach((id, index) => requireId(id, `${label}.list[${index}]`));
+  if (value.chosen !== null) requireId(value.chosen, `${label}.chosen`);
+  if (!Array.isArray(value.skipped)) throw new TypeError(`${label}.skipped must be an array`);
+  for (const [index, entry] of value.skipped.entries()) {
+    assertObject(entry, `${label}.skipped[${index}]`);
+    rejectUnknown(entry, new Set(["id", "reason"]), `${label}.skipped[${index}]`);
+    requireId(entry.id, `${label}.skipped[${index}].id`);
+    boundedString(entry.reason, `${label}.skipped[${index}].reason`, 512);
+  }
+}
 /**
  * @param {unknown} value
  * @param {string} label
  */
 function validateRoutingState(value, label) {
   assertObject(value, label);
-  rejectUnknown(value, new Set(["history", "currentOverride", "assignments", "availability", "tierExhaustion", "tierExhaustionCycle"]), label);
+  rejectUnknown(value, new Set(["history", "currentOverride", "assignments", "availability", "tierExhaustion", "tierExhaustionCycle", "judgeList"]), label);
   if (!Array.isArray(value.history) || value.history.length > MAX_ROUTING_HISTORY) {
     throw new TypeError(`${label}.history must be an array with at most ${MAX_ROUTING_HISTORY} items`);
   }
@@ -476,6 +505,7 @@ function validateRoutingState(value, label) {
   if (value.currentOverride !== null) validateRoutingEntry(value.currentOverride, `${label}.currentOverride`, true);
   if (value.tierExhaustion !== undefined) validateTierExhaustion(value.tierExhaustion, `${label}.tierExhaustion`);
   if (value.tierExhaustionCycle !== undefined) nonNegativeInteger(value.tierExhaustionCycle, `${label}.tierExhaustionCycle`);
+  if (value.judgeList !== undefined) validateJudgeListState(value.judgeList, `${label}.judgeList`);
   if (value.assignments !== undefined) {
     assertObject(value.assignments, `${label}.assignments`);
     rejectUnknown(value.assignments, new Set(["worker", "judge", "composedWorker", "composedJudge"]), `${label}.assignments`);

package/src/engine/assignment.mjs

@@ -11,11 +11,14 @@ import { PARKED } from "./prompts.mjs";
 import { composeAssignments, discoverRuntimes } from "./runtime-discovery.mjs";
 import { readUserConfig } from "../host/config.mjs";
 import { transition } from "./state.mjs";
+import { isHumanStepPending } from "../contract/human-step.mjs";
+import { initialJudgeListState, resolveJudgeList } from "./judge-list.mjs";
 
 /** @typedef {import("../cli.mjs").LockHandle} LockHandle */
 /** @typedef {import("../contract/index.mjs").NodeSnapshot} NodeSnapshot */
 /** @typedef {import("./runtime-discovery.mjs").RuntimeAvailability} RuntimeAvailability */
 /** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
+/** @typedef {import("../contract/index.mjs").JudgeListState} JudgeListState */
 
 /**
  * Resolve role assignments once at run creation. Discovery is used only for
@@ -30,7 +33,7 @@ import { transition } from "./state.mjs";
  * observables); it widens when a reader needs the record durably.
  *
  * @param {ValidatedContract} contract
- * @returns {Promise<{assignments: Record<string, {worker: string, judge: string, composedWorker: boolean, composedJudge: boolean}>, decisions: Record<string, {worker: {strategy: string|null, reason: string}, judge: {strategy: string|null, reason: string}}>, availability: Record<string, import("./runtime-discovery.mjs").RuntimeAvailability>}>}
+ * @returns {Promise<{assignments: Record<string, {worker: string, judge: string, composedWorker: boolean, composedJudge: boolean}>, decisions: Record<string, {worker: {strategy: string|null, reason: string}, judge: {strategy: string|null, reason: string}}>, availability: Record<string, import("./runtime-discovery.mjs").RuntimeAvailability>, judgeListStates: Record<string, JudgeListState|undefined>}>}
  */
 export async function runtimeAssignments(contract) {
   const needsComposition = contract.nodes.some((node) =>
@@ -38,7 +41,27 @@ export async function runtimeAssignments(contract) {
     || (node.gate.enabled && node.gate.runtime === undefined && contract.runtimeDefaults?.judge === undefined));
   const availability = needsComposition ? await discoverRuntimes(contract.runtimes, { cwd: contract.cwd }) : {};
   const config = readUserConfig(process.env);
-  const assignments = composeAssignments(contract, availability, { config });
+  const list = resolveJudgeList(contract, config);
+  /** @type {Record<string, JudgeListState|undefined>} */
+  const judgeListStates = {};
+  // R18: an omitted judge reads the ordered list, contract over machine
+  // config, before `composeAssignments`' own single `config.judge` preference
+  // and strongest-candidate default. The callback records the evidence
+  // (`judgeListStates`) as a side effect and returns `undefined` only for a
+  // node the list does not govern (its gate is disabled), which falls through
+  // to those candidates unchanged; once the list governs, its pick is final --
+  // the whole state, so an exhausted list's thrown error can still name every
+  // skip, not just `chosen` (`null` when every entry was skipped), which
+  // `composeAssignments` must not fall through either.
+  const listJudge = list
+    ? (/** @type {{id: string, gate: {enabled: boolean}}} */ node, /** @type {string} */ workerId) => {
+      if (!node.gate.enabled) return undefined;
+      const judgeListState = initialJudgeListState(contract, list, workerId);
+      judgeListStates[node.id] = judgeListState;
+      return judgeListState;
+    }
+    : undefined;
+  const assignments = composeAssignments(contract, availability, { config, listJudge });
   /** @type {Record<string, {worker: {strategy: string|null, reason: string}, judge: {strategy: string|null, reason: string}}>} */
   const decisions = {};
   return {
@@ -54,20 +77,28 @@ export async function runtimeAssignments(contract) {
       const workerSource = node?.runtime !== undefined
         ? "node runtime"
         : contract.runtimeDefaults?.worker !== undefined ? "runtimeDefaults.worker" : null;
+      // A list state exists only when the callback actually ran for this node
+      // (composedJudge). An exhausted list (chosen null) never reaches this
+      // point at all: composeAssignments throws before this map runs rather
+      // than falling through to the discovery ranking.
+      const fromList = judgeListStates[nodeId]?.chosen === assignment.judge;
       decisions[nodeId] = {
         worker: {
           strategy: composedWorker ? "cost" : workerSource !== null ? "declared" : null,
           reason: composedWorker ? "discovery: cheapest available runtime" : /** @type {string} */ (workerSource),
         },
         judge: {
-          strategy: composedJudge ? "priority" : judgeSource !== null ? "declared" : null,
-          reason: composedJudge ? "discovery: strongest available runtime" : /** @type {string} */ (judgeSource ?? "no judge required"),
+          strategy: composedJudge ? (fromList ? "judge-list" : "priority") : judgeSource !== null ? "declared" : null,
+          reason: composedJudge
+            ? (fromList ? `judge list: chose ${assignment.judge}` : "discovery: strongest available runtime")
+            : /** @type {string} */ (judgeSource ?? "no judge required"),
         },
       };
       return [nodeId, { ...assignment, composedWorker, composedJudge }];
     })),
     decisions,
     availability,
+    judgeListStates,
   };
 }
 /**
@@ -85,6 +116,11 @@ export function blockDependents(contract, runDir, states, lock) {
     // automatic retry is still unspent is re-opened to `pending` before this
     // runs, so the dependants stay `pending`/`phase: "waiting"` until it parks.
     const blockedBy = node.dependsOn.filter((id) => PARKED.has(states.get(id)?.status ?? ""));
-    if (blockedBy.length) transition(runDir, state, "blocked", { phase: "dependency", blockedBy, error: { code: "dependency_failed", message: `blocked by ${blockedBy.join(", ")}` } }, lock);
+    // A dependant of a pending human step (R16) is waiting, not failed: the
+    // code stays `dependency_failed` so `resume --answer` re-opens it, and the
+    // message says what it waits for.
+    const waiting = blockedBy.every((id) => isHumanStepPending(/** @type {NodeSnapshot} */ (states.get(id))));
+    const message = waiting ? `waiting for human step ${blockedBy.join(", ")}` : `blocked by ${blockedBy.join(", ")}`;
+    if (blockedBy.length) transition(runDir, state, "blocked", { phase: "dependency", blockedBy, error: { code: "dependency_failed", message } }, lock);
   }
 }

package/src/engine/backoff.mjs

@@ -362,9 +362,10 @@ export function upsertTierExhaustionCandidate(existing, role, runtimeId, exhaust
  * @param {Transition} schedule
  * @param {number} [now] epoch ms the backoff window is measured from
  * @param {string|null} [exhaustedUntil] the reset instant the exhausted candidate announced, if any
- * @returns {{blocked: RouteError|null, nextRuntime: string, ruleIndex: number|undefined, revision: number, hop: number, backoffSec: number, backoffUntil: string, composed: boolean, tierExhaustion: TierExhaustion|null}}
+ * @param {{judgeListState?: import("../contract/index.mjs").JudgeListState}} [options] R18: a judge-list hop already resolved by the impure caller (`engine/judge-list.mjs`'s `nextListJudge` reads the durable refusal and usage-window stores, which this decision module never touches); its `chosen` -- possibly null, once the list is exhausted -- replaces both the declared `runtime.fallback` edge and the dynamic-tier candidate a list-driven judge would otherwise get from `nextSynthesizedRuntime`/`nextSameTierRuntime`
+ * @returns {{blocked: RouteError|null, nextRuntime: string, ruleIndex: number|undefined, revision: number, hop: number, backoffSec: number, backoffUntil: string, composed: boolean, tierExhaustion: TierExhaustion|null, judgeList?: import("../contract/index.mjs").JudgeListState}}
  */
-export function planRoute(contract, node, state, role, error, current, schedule, now = Date.now(), exhaustedUntil = null) {
+export function planRoute(contract, node, state, role, error, current, schedule, now = Date.now(), exhaustedUntil = null, options = {}) {
   const revision = state.revisions ?? 0;
   // Tier routing is scoped by generation, not revision: an invocation counts
   // as attempted here only when it ran in the current tier-exhaustion
@@ -394,17 +395,33 @@ export function planRoute(contract, node, state, role, error, current, schedule,
   // declared" — nextSynthesizedRuntime's own attempted-filter would otherwise
   // make that distinction unreachable.
   const declaredCandidate = synthesizedChain(contract, role, current)[0] ?? null;
-  const fallback = nextSynthesizedRuntime(contract, role, current, attempted)
-    ?? (dynamicComposed ? nextSameTierRuntime(contract, routing, role, current, attempted) : null);
+  // R18: once a list governs this hop (`options.judgeListState` is supplied),
+  // its precomputed pick *replaces* the declared `runtime.fallback` edge
+  // rather than following it -- the list is itself the ordering, and a list
+  // entry that happens to declare its own `fallback` must not hop there
+  // instead of the list's next eligible entry. Only when no list governs does
+  // the declared edge, then the dynamic-tier candidate, apply.
+  const judgeListState = options.judgeListState;
+  const listGoverned = judgeListState !== undefined;
+  const fallback = judgeListState !== undefined
+    ? judgeListState.chosen
+    : nextSynthesizedRuntime(contract, role, current, attempted) ?? (dynamicComposed ? nextSameTierRuntime(contract, routing, role, current, attempted) : null);
   const hop = nextHop(state, role, revision, schedule);
   const nextRuntime = schedule.kind === "reset" ? current : fallback ?? current;
+  // A list-governed hop is bounded by the list's own length (instructions
+  // R18 §4), never the one-hop cap that applies to a declared or dynamic-tier
+  // fallback, so it is exempted from the hop-cap check below exactly as a
+  // dynamic-tier fallback already is.
+  const noHopCap = dynamicComposed || listGoverned;
   const blocked = schedule.kind === "reset"
     ? null
     : fallback === null
-      ? declaredCandidate !== null && attempted.has(declaredCandidate)
-        ? { code: "provider_failover_cycle", message: `runtime ${declaredCandidate} was already attempted in ${role} revision ${revision}` }
-        : { code: dynamicComposed ? "runtime_tier_exhausted" : error.code, message: dynamicComposed ? `no available runtime remains in tier ${String(contract.runtimes[current]?.tier ?? "unknown")} for ${role}` : error.message }
-      : hop > 1 && !dynamicComposed
+      ? listGoverned
+        ? { code: "judge_list_exhausted", message: `no eligible entry remains in the judge list for ${role}` }
+        : declaredCandidate !== null && attempted.has(declaredCandidate)
+          ? { code: "provider_failover_cycle", message: `runtime ${declaredCandidate} was already attempted in ${role} revision ${revision}` }
+          : { code: dynamicComposed ? "runtime_tier_exhausted" : error.code, message: dynamicComposed ? `no available runtime remains in tier ${String(contract.runtimes[current]?.tier ?? "unknown")} for ${role}` : error.message }
+      : hop > 1 && !noHopCap
         ? { code: "provider_failover_hop_cap", message: "provider failover exceeded the one-hop cap" }
         : null;
   const backoffSec = schedule.kind === "reset"
@@ -417,7 +434,7 @@ export function planRoute(contract, node, state, role, error, current, schedule,
   const tierExhaustion = dynamicComposed
     ? upsertTierExhaustionCandidate(state.routing?.tierExhaustion, role, current, exhaustedUntil)
     : null;
-  return { blocked, nextRuntime, ruleIndex: undefined, revision, hop, backoffSec, backoffUntil, composed: composedAssignment, tierExhaustion };
+  return { blocked, nextRuntime, ruleIndex: undefined, revision, hop, backoffSec, backoffUntil, composed: composedAssignment, tierExhaustion, judgeList: options.judgeListState };
 }
 
 /**
@@ -464,6 +481,10 @@ export function buildRouting(state, { role, error, current, plan, schedule, usag
       history: [...(state.routing?.history ?? []), { ...shared, runtime: current, status, errorCode }].slice(-MAX_ROUTING_HISTORY),
       currentOverride: override,
       ...(plan.tierExhaustion ? { tierExhaustion: plan.tierExhaustion } : {}),
+      // Unlike tierExhaustion, an untouched judgeList is not deleted above: a
+      // worker exhaustion round in the same call never resolved one, and the
+      // node's own list evidence must survive it unchanged.
+      ...(plan.judgeList !== undefined ? { judgeList: plan.judgeList } : {}),
     },
     override,
     errorCode,

package/src/engine/dispatch.mjs

@@ -37,7 +37,8 @@ import { mkdirSync, statSync } from "node:fs";
 import { READ_BYTE_LIMIT, READ_LINE_LIMIT, harnessCapabilities, normalizeProviderResult, writesWorkspace } from "../harnesses/index.mjs";
 import { writeJsonAtomic } from "../run/store.mjs";
 import { judgeReaskInstruction, reviewMode } from "../contract/review-modes.mjs";
-import { routeRuntimeForState, runtimeSnapshot } from "./failover.mjs";
+import { isSameProviderReviewPair } from "../contract/judge-independence.mjs";
+import { previousAttemptRuntimeId, routeRuntimeForState, runtimeSnapshot } from "./failover.mjs";
 import { fingerprintRuntime, forceFreshSession, phaseInvocationPlan } from "./phase-session.mjs";
 
 /** @typedef {import("./phase-session.mjs").SessionPolicy} SessionPolicy */
@@ -495,6 +496,22 @@ export async function startJudge(contract, node, state, runDir, running, workerR
     /** @type {import("../contract/index.mjs").VerificationState|null} */ (state.verification),
   );
   state.review = reviewMode(node.gate);
+  // The judge candidate this attempt would actually use, and the worker
+  // runtime read off the durable invocation record rather than
+  // `state.runtime`: on the first judge dispatch of an attempt `state.runtime`
+  // still holds the worker, but `startJudge` overwrites it with the judge's
+  // own runtime below, and a bounded re-ask (review.mjs) or a judge-failure
+  // retry (settle-judge.mjs) then calls `startJudge` again with the judge
+  // already in `state.runtime` -- comparing against that would compare the
+  // judge to itself and always mark the node. The invocation record survives
+  // every such re-dispatch, so the mark reflects the pairing that ran,
+  // fallback included -- not `node.sameProviderReview`, which only says the
+  // pairing was admitted under same-vendor mode at contract validation,
+  // primary or fallback alike.
+  const judgeCandidate = routeRuntimeForState(contract, node, state, "judge");
+  const workerRuntimeId = previousAttemptRuntimeId(state, "worker");
+  const workerRuntime = workerRuntimeId ? contract.runtimes[workerRuntimeId] : state.runtime;
+  state.sameProviderReview = isSameProviderReviewPair(contract, workerRuntime, judgeCandidate);
   if (verdict.verdict === "fail") return { kind: "rejected", verdict };
   // `skipWhen` is checked before the ordinary judgment rule so a green-and-small
   // change settles mechanically even when a Definition of Done item carries
@@ -502,7 +519,7 @@ export async function startJudge(contract, node, state, runDir, running, workerR
   // and a gate whose review mode is `none` is skipped there exactly as before.
   if (judgeSkippedByScope(node, state)) return { kind: "settle", gate: verdict };
   if (!judgeRequired(node)) return { kind: "settle", gate: verdict };
-  const runtime = routeRuntimeForState(contract, node, state, "judge");
+  const runtime = judgeCandidate;
   const paths = logPaths(runDir, node.id, "judge", state.attempt);
   state.phase = "judge";
   state.runtime = runtime;