faberun 0.25.0 → 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/contract/task-packet.mjs

@@ -426,8 +426,11 @@ function pathInside(path, root) {
  * @returns {string}
  */
 function renderDiscoveryPrompt(packet, nodeId) {
+  // The closed variant says what settlement accepts (engine/lifecycle.mjs):
+  // only a discovery packet with no read files owes an execution packet in
+  // artifacts[0]; one closed to its read files delivers through `output`.
   const closedContext = packet.readFiles.length
-    ? "This discovery context is read-only and closed to the listed read files. Inspect only those files and do not perform repository-wide exploration. Return the worker-result JSON object below; put exactly one execution task packet JSON string in artifacts[0]."
+    ? "This discovery context is read-only and closed to the listed read files. Inspect only those files and do not perform repository-wide exploration. Return the worker-result JSON object below; deliver your result in `output` and send `artifacts` as []."
     : "This discovery context is read-only and is the one exception to closed inspection: no read files were pre-supplied, so you may inspect the repository read-only only as needed to produce the packet. Do not edit the repository. Return the worker-result JSON object below; put exactly one execution task packet JSON string in artifacts[0].";
   const lines = [
     `# Node ${nodeId} (discovery)`,

package/src/contract/worker-result.mjs

@@ -25,6 +25,23 @@ const RESULT_LIMITS = Object.freeze({
  */
 export const DERIVED_WORKER_RESULT_FIELDS = Object.freeze(["changedFiles"]);
 
+/**
+ * A worker result that is well-formed JSON but breaks one of the byte
+ * ceilings above. Typed, not a plain TypeError, so the repair prompt can name
+ * the ceiling that was broken: observed 2026-09-25, a planning draft that
+ * copied its 38 KiB plan into `artifacts[0]` was told twice to drop markdown
+ * fences it never wrote, and repeated the copy.
+ */
+export class WorkerResultSizeError extends TypeError {
+  /** @param {string} field @param {number} limit */
+  constructor(field, limit) {
+    super(`${field} exceeds ${limit} bytes`);
+    this.name = "WorkerResultSizeError";
+    this.field = field;
+    this.limit = limit;
+  }
+}
+
 /** @typedef {"done"|"blocked_context"} WorkerResultStatus */
 
 /**
@@ -37,6 +54,20 @@ export const DERIVED_WORKER_RESULT_FIELDS = Object.freeze(["changedFiles"]);
  * @typedef {{status: WorkerResultStatus, summary: string, verification: string[], artifacts: string[], missingContext: string[], output?: Record<string, unknown>}} WorkerResult
  */
 
+/**
+ * The repair instruction for an invalid worker result: a broken byte ceiling
+ * is named, since re-emitting the same object without fences cannot fix it.
+ *
+ * @param {unknown} cause
+ * @returns {string}
+ */
+export function invalidResultRepair(cause) {
+  if (cause instanceof WorkerResultSizeError) {
+    return `the result breaks a size ceiling: ${cause.field} exceeds ${cause.limit} bytes. Keep every field within its ceiling; a node that delivers through \`output\` sends \`artifacts\` as [] and never copies \`output\` into \`artifacts\`.`;
+  }
+  return "the entire final message must be exactly the required JSON object: no markdown fences, no prose before or after it. Return it as the only content of the final message.";
+}
+
 /**
  * @param {string} value
  * @returns {WorkerResult}
@@ -45,7 +76,7 @@ export function parseWorkerResult(value) {
   if (typeof value !== "string") throw new TypeError("worker result must be JSON text");
   const maxRawBytes = RESULT_LIMITS.bytes + RESULT_LIMITS.outputBytes;
   if (Buffer.byteLength(value, "utf8") > maxRawBytes) {
-    throw new TypeError(`worker result exceeds ${maxRawBytes} bytes`);
+    throw new WorkerResultSizeError("worker result", maxRawBytes);
   }
   let parsed;
   try {
@@ -100,7 +131,7 @@ export function validateWorkerResult(value) {
   if (Object.hasOwn(record, "output") && record.output !== undefined) {
     assertObject(record.output, "worker result.output");
     if (Buffer.byteLength(JSON.stringify(record.output), "utf8") > RESULT_LIMITS.outputBytes) {
-      throw new TypeError(`worker result.output exceeds ${RESULT_LIMITS.outputBytes} bytes`);
+      throw new WorkerResultSizeError("worker result.output", RESULT_LIMITS.outputBytes);
     }
     output = /** @type {Record<string, unknown>} */ (record.output);
   }
@@ -115,7 +146,7 @@ export function validateWorkerResult(value) {
   // it is a discovery node's deliverable, not incidental prose competing with
   // summary/verification for the same 32 KiB budget.
   if (Buffer.byteLength(JSON.stringify(envelope), "utf8") > RESULT_LIMITS.bytes) {
-    throw new TypeError(`worker result exceeds ${RESULT_LIMITS.bytes} bytes`);
+    throw new WorkerResultSizeError("worker result", RESULT_LIMITS.bytes);
   }
   return output === undefined ? envelope : { ...envelope, output };
 }
@@ -165,6 +196,6 @@ function requireList(value, label, maxItems, itemBytes) {
   if (!Array.isArray(value) || value.length > maxItems) throw new TypeError(`${label} must be an array with at most ${maxItems} items`);
   for (const [index, item] of value.entries()) {
     if (typeof item !== "string") throw new TypeError(`${label}[${index}] must be a string`);
-    if (Buffer.byteLength(item, "utf8") > itemBytes) throw new TypeError(`${label}[${index}] exceeds ${itemBytes} bytes`);
+    if (Buffer.byteLength(item, "utf8") > itemBytes) throw new WorkerResultSizeError(`${label}[${index}]`, itemBytes);
   }
 }

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);
   }
 }