faberun 0.25.1 → 0.26.0

package/src/cli/plan.mjs

@@ -15,8 +15,11 @@ import { validateFinalVerification, validateSharedVerification } from "../contra
 import { colorLevel, statusToken } from "./brand.mjs";
 import { delay } from "../util.mjs";
 import { runPlanningPipeline } from "../plan/pipeline.mjs";
+import { parseAnswerFlags, resolvePlanningPipeline } from "../plan/resolve.mjs";
+import { resolveReviewerList } from "../plan/reviewer.mjs";
 import { campaignTree, runDirectory } from "../run/paths.mjs";
 import { readCampaign } from "../campaign/record.mjs";
+import { readUserConfig } from "../host/config.mjs";
 
 /** How often a foreground `plan` polls a launched stage's run directory. */
 const DEFAULT_POLL_MS = 1_000;
@@ -56,6 +59,21 @@ export function parseRuntimeDefaults(value) {
   return result;
 }
 
+/**
+ * `--reviewers <a,b>`: the planner's own ordered reviewer list (R19),
+ * separate from `--runtime-defaults judge=` and from the frozen contract's
+ * R18 judge list even when an operator names the same runtime id in both.
+ *
+ * @param {string|undefined} value
+ * @returns {string[]|undefined}
+ */
+export function parseReviewerList(value) {
+  if (value === undefined) return undefined;
+  const ids = value.split(",").map((id) => id.trim()).filter(Boolean);
+  if (ids.length === 0) throw new Error("--reviewers needs at least one runtime id");
+  return ids;
+}
+
 /**
  * @param {unknown} value
  * @returns {number}
@@ -126,10 +144,11 @@ export function loadVerificationSuites(path) {
 
 /**
  * @param {string} target
- * @param {{campaign?: string, phase?: string, "review-rounds"?: string, "approve-below"?: string, "runtime-defaults"?: string, runtimes?: string, verification?: string, package?: string, "targeted-fix"?: boolean, detach?: boolean, json?: boolean}} values
+ * @param {{campaign?: string, phase?: string, "review-rounds"?: string, "approve-below"?: string, "runtime-defaults"?: string, reviewers?: string, runtimes?: string, verification?: string, package?: string, "targeted-fix"?: boolean, detach?: boolean, resolve?: string, answer?: string[], json?: boolean}} values
  * @returns {Promise<void>}
  */
 export async function planCli(target, values) {
+  if (typeof values.resolve === "string" && values.resolve) return await resolvePlanCli(values);
   const specPath = resolve(target);
   if (typeof values.campaign !== "string" || !values.campaign) throw new Error("plan requires --campaign <id>");
   const campaignId = values.campaign;
@@ -137,6 +156,9 @@ export async function planCli(target, values) {
   const reviewRounds = reviewRoundsOf(values["review-rounds"]);
   const approveBelow = /** @type {"standard"|"high"|"none"|undefined} */ (values["approve-below"]);
   const runtimeDefaults = parseRuntimeDefaults(values["runtime-defaults"]);
+  // R19: the planner's own reviewer list, never `runtimeDefaults.judge` --
+  // `--reviewers` wins over the machine's own `config.reviewers` default.
+  const reviewers = resolveReviewerList({ reviewers: parseReviewerList(values.reviewers) }, readUserConfig(process.env));
   const runtimes = typeof values.runtimes === "string" && values.runtimes
     ? loadRuntimesCatalogue(values.runtimes)
     : DISCOVERY_RUNTIME_DEFINITIONS;
@@ -149,6 +171,7 @@ export async function planCli(target, values) {
     const argv = ["plan", specPath, "--campaign", campaignId, "--phase", phase, "--review-rounds", String(reviewRounds)];
     if (approveBelow !== undefined) argv.push("--approve-below", approveBelow);
     if (values["runtime-defaults"] !== undefined) argv.push("--runtime-defaults", values["runtime-defaults"]);
+    if (values.reviewers !== undefined) argv.push("--reviewers", values.reviewers);
     if (typeof values.runtimes === "string" && values.runtimes) argv.push("--runtimes", resolve(values.runtimes));
     if (typeof values.verification === "string" && values.verification) argv.push("--verification", resolve(values.verification));
     if (packageMode !== "implementation") argv.push("--package", packageMode);
@@ -194,6 +217,7 @@ export async function planCli(target, values) {
       reviewRounds,
       approveBelow,
       runtimeDefaults,
+      reviewers,
       runtimes,
       verification,
       targetedFix: values["targeted-fix"] === true,
@@ -222,14 +246,62 @@ export async function planCli(target, values) {
     return;
   }
   if (result.status === "contested") {
-    process.stdout.write(`[plan] ${campaignId} phase ${phase} contested after ${result.round} round(s) · ${result.findings.length} finding(s) · ${result.planPath}\n`);
-    process.exitCode = 1;
+    renderContested(campaignId, phase, result);
     return;
   }
   for (const warning of result.warnings) process.stdout.write(`${statusToken("warn", colorLevel(process.env, process.stdout.isTTY))} ${warning}\n`);
   process.stdout.write(`[plan] ${campaignId} phase ${phase} frozen · approved ${result.approved} · ${result.contractPath}\n`);
 }
 
+/**
+ * `faberun plan --resolve <plan-dir> --answer <finding-id>=accept|reject:<reason>`
+ * (R9): apply the operator's decisions to a contested plan's open critical
+ * findings and resume straight to sizing/routing/freeze, without redrafting
+ * or asking a provider anything. `--campaign`/`--phase`/the spec positional
+ * are not needed here — everything this needs is the resume context the
+ * contest already wrote to `plan.json` (`src/plan/contest.mjs`).
+ *
+ * @param {{resolve?: string, answer?: string[], json?: boolean}} values
+ * @returns {Promise<void>}
+ */
+async function resolvePlanCli(values) {
+  const plansDir = resolve(/** @type {string} */ (values.resolve));
+  const rawAnswers = values.answer ?? [];
+  if (rawAnswers.length === 0) throw new Error("--resolve requires at least one --answer <finding-id>=accept or --answer <finding-id>=reject:<reason>");
+  const answers = parseAnswerFlags(rawAnswers);
+  const result = await resolvePlanningPipeline({ plansDir, cwd: process.cwd(), answers });
+  if (values.json === true) {
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    return;
+  }
+  if (result.status === "contested") {
+    renderContested(undefined, undefined, result);
+    return;
+  }
+  for (const warning of result.warnings) process.stdout.write(`${statusToken("warn", colorLevel(process.env, process.stdout.isTTY))} ${warning}\n`);
+  process.stdout.write(`[plan] resolved · frozen · approved ${result.approved} · ${result.contractPath}\n`);
+}
+
+/**
+ * A contested result's console rendering: the summary line, then every
+ * critical finding with its id, the node or requirement it concerns, and
+ * what would resolve it (R9's own words for what the output must list), and
+ * the exact command to answer it.
+ *
+ * @param {string|undefined} campaignId
+ * @param {string|undefined} phase
+ * @param {import("../plan/contest.mjs").ContestedPipelineResult} result
+ * @returns {void}
+ */
+function renderContested(campaignId, phase, result) {
+  const criticalFindings = result.findings.filter((finding) => finding.severity === "critical");
+  const label = campaignId ? `${campaignId} phase ${phase} ` : "";
+  process.stdout.write(`[plan] ${label}contested after ${result.round} round(s) · ${criticalFindings.length} critical finding(s) · ${result.planPath}\n`);
+  for (const finding of criticalFindings) process.stdout.write(`  - ${finding.id} (${finding.nodeId}): ${finding.text}\n`);
+  process.stdout.write(`[plan] resolve with: faberun plan --resolve ${result.plansDir} --answer <finding-id>=accept or --answer <finding-id>=reject:<reason>\n`);
+  process.exitCode = 1;
+}
+
 /**
  * Where a detached planning run records why it never came up. It sits beside
  * the phase's durable plan artifacts rather than in the disposable scratch

package/src/cli/setup.mjs

@@ -26,6 +26,7 @@ import {
   discoverRuntimes,
   strongest,
 } from "../engine/runtime-discovery.mjs";
+import { effectiveProvider } from "../contract/provider.mjs";
 import { boundedGitSync } from "../repo/worktree.mjs";
 import { colorLevel, renderBanner, statusToken } from "./brand.mjs";
 import { packageVersion } from "../host/package.mjs";
@@ -46,6 +47,8 @@ import { discoverSkillTargets, registerSkills } from "./skills.mjs";
  * @property {string} [harnesses]
  * @property {string} [worker]
  * @property {string} [judge]
+ * @property {string} [judges] comma-separated ordered runtime ids for the machine's R18 judge-list default; unset keeps whatever the existing config already declared
+ * @property {string} [reviewers] comma-separated ordered runtime ids for the machine's R19 reviewer-list default (`faberun plan --reviewers`); unset keeps whatever the existing config already declared
  * @property {boolean} [skill] whether to register the faberun skill (default true)
  * @property {boolean} [json]
  * @property {NodeJS.ProcessEnv} [env]
@@ -166,11 +169,15 @@ export async function setupCommand(options = {}) {
       }
     }
 
+    const selectedJudges = splitHarnesses(options.judges ?? "").length ? splitHarnesses(options.judges ?? "") : kept.judges;
+    const selectedReviewers = splitHarnesses(options.reviewers ?? "").length ? splitHarnesses(options.reviewers ?? "") : kept.reviewers;
     const config = {
       schemaVersion: /** @type {1} */ (1),
       harnesses: selectedHarnesses,
       worker: selectedWorker,
       judge: selectedJudge,
+      ...(selectedJudges.length ? { judges: selectedJudges } : {}),
+      ...(selectedReviewers.length ? { reviewers: selectedReviewers } : {}),
       updatedAt: new Date().toISOString(),
     };
     writeUserConfig(env, config);
@@ -270,10 +277,10 @@ function missingEnvKeys(runtime, env) {
  *
  * @param {UserConfig|null} existing
  * @param {Record<string, RuntimeAvailability>} availability
- * @returns {{harnesses: string[], worker: string, judge: string}}
+ * @returns {{harnesses: string[], worker: string, judge: string, judges: string[], reviewers: string[]}}
  */
 export function mergeExistingConfig(existing, availability) {
-  if (!existing) return { harnesses: [], worker: "", judge: "" };
+  if (!existing) return { harnesses: [], worker: "", judge: "", judges: [], reviewers: [] };
   const availableHarnesses = new Set(
     Object.entries(DISCOVERY_RUNTIME_DEFINITIONS)
       .filter(([id]) => availability[id]?.available === true)
@@ -286,6 +293,12 @@ export function mergeExistingConfig(existing, availability) {
     harnesses: existing.harnesses.filter((harness) => availableHarnesses.has(harness)),
     worker: existing.worker && candidateIds.has(existing.worker) ? existing.worker : "",
     judge: existing.judge && candidateIds.has(existing.judge) ? existing.judge : "",
+    // The judge and reviewer lists are static, operator-declared orderings
+    // (D9, D11): unlike the single worker/judge default, an entry discovery
+    // cannot currently reach is not dropped, since each list's own selection
+    // already skips a refused entry at every read.
+    judges: Array.isArray(existing.judges) ? existing.judges : [],
+    reviewers: Array.isArray(existing.reviewers) ? existing.reviewers : [],
   };
 }
 
@@ -314,7 +327,9 @@ function keptJudgeDefault(kept, workerId, candidates) {
  * @returns {string}
  */
 function defaultJudge(workerId, candidates) {
-  const vendor = DISCOVERY_RUNTIME_DEFINITIONS[workerId]?.vendor;
+  const worker = DISCOVERY_RUNTIME_DEFINITIONS[workerId];
+  if (worker === undefined) return "";
+  const vendor = effectiveProvider(worker);
   if (vendor === undefined) return "";
   return strongest(candidates, vendor)?.id ?? "";
 }
@@ -328,8 +343,10 @@ function defaultJudge(workerId, candidates) {
  * @returns {boolean}
  */
 function crossVendor(judgeId, workerId) {
-  const judgeVendor = DISCOVERY_RUNTIME_DEFINITIONS[judgeId]?.vendor;
-  const workerVendor = DISCOVERY_RUNTIME_DEFINITIONS[workerId]?.vendor;
+  const judge = DISCOVERY_RUNTIME_DEFINITIONS[judgeId];
+  const worker = DISCOVERY_RUNTIME_DEFINITIONS[workerId];
+  const judgeVendor = judge && effectiveProvider(judge);
+  const workerVendor = worker && effectiveProvider(worker);
   return Boolean(judgeVendor && workerVendor && judgeVendor !== workerVendor);
 }
 

package/src/cli.mjs

@@ -23,6 +23,7 @@ import {
   writeTextAtomic,
 } from "./run/store.mjs";
 import { runDirectory, runsRoot } from "./run/paths.mjs";
+import { pruneIntegratedRunWorktrees } from "./repo/worktree-prune.mjs";
 import { migrateRunState } from "./run/migrate.mjs";
 import {
   acquire as acquireLock,
@@ -112,6 +113,7 @@ export const COMMAND_OPTIONS = {
   update: { check: { type: "boolean" }, json: { type: "boolean" } },
   project: { from: { type: "string" } },
   migrate: { cwd: { type: "string" } },
+  prune: { cwd: { type: "string" }, parked: { type: "boolean" }, json: { type: "boolean" } },
   setup: { yes: { type: "boolean" }, harnesses: { type: "string" }, worker: { type: "string" }, judge: { type: "string" }, "no-skill": { type: "boolean" }, json: { type: "boolean" } },
   init: { cwd: { type: "string" }, yes: { type: "boolean" }, "no-skill": { type: "boolean" }, agentkit: { type: "boolean" }, greenfield: { type: "boolean" }, stable: { type: "boolean" }, json: { type: "boolean" } },
   metrics: METRICS_OPTIONS,
@@ -121,11 +123,14 @@ export const COMMAND_OPTIONS = {
     "review-rounds": { type: "string" },
     "approve-below": { type: "string" },
     "runtime-defaults": { type: "string" },
+    reviewers: { type: "string" },
     runtimes: { type: "string" },
     verification: { type: "string" },
     package: { type: "string" },
     "targeted-fix": { type: "boolean" },
     detach: { type: "boolean" },
+    resolve: { type: "string" },
+    answer: { type: "string", multiple: true },
     json: { type: "boolean" },
   },
 };
@@ -156,7 +161,13 @@ function parseCli(argv, quiet = false) {
   if (command === "setup" && parsed.positionals.length !== 0) return null;
   if (command === "init" && parsed.positionals.length !== 0) return null;
   if (command === "migrate" && parsed.positionals.length !== 0) return null;
-  if (command !== "doctor" && command !== "models" && command !== "bulk-read" && command !== "next" && command !== "update" && command !== "setup" && command !== "init" && command !== "migrate" && parsed.positionals.length !== 1) return null;
+  if (command === "prune" && parsed.positionals.length !== 0) return null;
+  // `plan --resolve <plan-dir>` (R9) takes no spec positional: everything a
+  // fresh `plan` reads from it and its flags is already on the contested
+  // plan.json the run it resumes wrote.
+  if (command === "plan" && typeof parsed.values.resolve === "string" && parsed.values.resolve !== "") {
+    if (parsed.positionals.length !== 0) return null;
+  } else if (command !== "doctor" && command !== "models" && command !== "bulk-read" && command !== "next" && command !== "update" && command !== "setup" && command !== "init" && command !== "migrate" && command !== "prune" && parsed.positionals.length !== 1) return null;
   return {
     command,
     target: parsed.positionals[0],
@@ -310,6 +321,13 @@ async function main(argv) {
     process.stdout.write(`[migrate] ${result.legacy} -> ${result.target} · ${runs}, ${campaigns}\n`);
     return;
   }
+  if (command === "prune") {
+    const cwd = resolve(typeof values.cwd === "string" ? values.cwd : ".");
+    const pruned = pruneIntegratedRunWorktrees(cwd, runsRoot(cwd), { parked: values.parked === true });
+    if (values.json === true) process.stdout.write(`${JSON.stringify({ pruned }, null, 2)}\n`);
+    else process.stdout.write(`${prunedLine(pruned)}\n`);
+    return;
+  }
   if (!target) { usage(); return; }
   if (command === "project") {
     const record = reassociateProject(faberunHome(process.env), target, {
@@ -334,6 +352,12 @@ async function main(argv) {
     const contractFromCwd = relative(contract.cwd, absolute);
     const contractIgnore = contractFromCwd && !contractFromCwd.startsWith("..") && !isAbsolute(contractFromCwd) ? [contractFromCwd] : [];
     assertLaunchBaseClean(contract.cwd, baseRef, { ignorePaths: contractIgnore });
+    // Every launch releases the worktrees of runs that have already landed,
+    // so a long campaign does not carry them until `campaign close`.
+    if (!hasDetachedBootstrapNonce()) {
+      const pruned = pruneIntegratedRunWorktrees(contract.cwd, runsRoot(contract.cwd));
+      if (pruned.length) process.stdout.write(`${prunedLine(pruned)}\n`);
+    }
     if (values.detach === true) {
       if (existsSync(runDir)) throw new Error(`run already exists: ${runDir}`);
       for (const warning of [...contract.warnings, ...reusedDoneWarnings(contract)]) process.stdout.write(`${advisoryToken()} ${warning}\n`);
@@ -487,6 +511,16 @@ function advisoryToken() {
   return statusToken("warn", colorLevel(process.env, process.stdout.isTTY));
 }
 
+/**
+ * @param {import("./repo/worktree-prune.mjs").PrunedRun[]} pruned
+ * @returns {string}
+ */
+function prunedLine(pruned) {
+  if (!pruned.length) return "[prune] no finished, integrated run holds a worktree";
+  const removed = pruned.reduce((sum, run) => sum + run.removed, 0);
+  return `[prune] released ${removed} worktree${removed === 1 ? "" : "s"} of ${pruned.length} integrated run${pruned.length === 1 ? "" : "s"} · each kept under refs/faberun-archive/`;
+}
+
 /**
  * The foreground launch command is the only moment an operator is present, so
  * it is where the no-transport warning belongs. A detached controller's stdio

package/src/contract/definition-of-done.mjs

@@ -14,7 +14,7 @@ import { rejectUnknown, requireId, requireString } from "./assert.mjs";
 /**
  * @param {unknown} value
  * @param {string} label
- * @param {{verificationCount?: number, recordableCount?: number}} [options]
+ * @param {{verificationCount?: number, recordableCount?: number, commands?: {argv: string[]}[], nodeId?: string}} [options]
  * @returns {DefinitionOfDoneItem[]}
  */
 export function validateDefinitionOfDone(value, label, options = {}) {
@@ -80,7 +80,7 @@ export function judgmentReasonWarnings(items, index) {
 /**
  * @param {unknown} value
  * @param {string} label
- * @param {{verificationCount?: number, recordableCount?: number}} options
+ * @param {{verificationCount?: number, recordableCount?: number, commands?: {argv: string[]}[], nodeId?: string}} options
  * @returns {DefinitionOfDoneProof}
  */
 function validateProof(value, label, options) {
@@ -100,20 +100,60 @@ function validateProof(value, label, options) {
 
 /**
  * A `verification` proof reuses a recorded controller verification result by
- * position, never by comparing command strings: a joined argv loses argument
- * boundaries and shell semantics, so the reference is the only sound name.
+ * position. It is authored as either the zero-based index or, when the
+ * node's verification commands are known to the caller (`options.commands`),
+ * the exact text of one of them -- the shape a planning model actually wrote
+ * (measured in `choose-the-judges` R5). A text ref is resolved to its index
+ * and normalized the same way a numeric ref is, so nothing downstream ever
+ * compares command strings again.
  *
  * @param {unknown} value
  * @param {string} label
- * @param {{verificationCount?: number, recordableCount?: number}} options
+ * @param {{verificationCount?: number, recordableCount?: number, commands?: {argv: string[]}[], nodeId?: string}} options
  * @returns {string}
  */
 function validateVerificationRef(value, label, options) {
+  if (typeof value === "string" && options.commands !== undefined && !isIndexLike(value)) {
+    return resolveTextRef(value, label, options);
+  }
   const text = typeof value === "number" ? String(value) : value;
-  if (typeof text !== "string" || !/^\d+$/u.test(text.trim())) {
-    throw new TypeError(`${label}.ref must be the zero-based index of a verification command`);
+  if (!isIndexLike(text)) {
+    throw new TypeError(`${label}.ref must be the zero-based index of a verification command, or the exact text of one`);
+  }
+  return checkedIndex(Number.parseInt(/** @type {string} */ (text).trim(), 10), label, options);
+}
+
+/** @param {unknown} text @returns {boolean} */
+function isIndexLike(text) {
+  return typeof text === "string" && /^\d+$/u.test(text.trim());
+}
+
+/**
+ * @param {string} value
+ * @param {string} label
+ * @param {{verificationCount?: number, recordableCount?: number, commands?: {argv: string[]}[], nodeId?: string}} options
+ * @returns {string}
+ */
+function resolveTextRef(value, label, options) {
+  const commands = /** @type {{argv: string[]}[]} */ (options.commands);
+  const index = commands.findIndex((command) => command.argv.join(" ") === value);
+  if (index === -1) {
+    const node = options.nodeId ?? "this node";
+    const existing = commands.length === 0
+      ? "(no verification commands)"
+      : commands.map((command, position) => `${position}: ${command.argv.join(" ")}`).join("\n");
+    throw new TypeError(`${label}.ref "${value}" names no verification command of ${node}; its verification commands are:\n${existing}`);
   }
-  const index = Number.parseInt(text, 10);
+  return checkedIndex(index, label, options);
+}
+
+/**
+ * @param {number} index
+ * @param {string} label
+ * @param {{verificationCount?: number, recordableCount?: number}} options
+ * @returns {string}
+ */
+function checkedIndex(index, label, options) {
   if (typeof options.verificationCount === "number" && index >= options.verificationCount) {
     throw new TypeError(`${label}.ref ${index} names no verification command: the packet declares ${options.verificationCount}`);
   }

package/src/contract/human-step.mjs

@@ -0,0 +1,54 @@
+/**
+ * Validation for a node's `humanStep` field (R16): the operator-only step and
+ * its command a requirement's `constraints` declared (`plan/human-step.mjs`
+ * detects it; `plan/freeze.mjs` stamps it onto the node that carries the
+ * requirement). Split from `contract/index.mjs`, mirroring
+ * `judge-independence.mjs`, because the shape that turns a node into a stop
+ * belongs with the field that declares it, not the general node-parsing loop.
+ */
+import { assertObject, boundedString, rejectUnknown } from "./assert.mjs";
+
+/** The fields a node's `humanStep` declaration carries. */
+const HUMAN_STEP_FIELDS = new Set(["step", "command"]);
+
+/** Bound on each of `step` and `command`, matching the operator-answer ceiling this stop is paired with (`engine/retry.mjs`'s `Previous attempt` section). */
+const HUMAN_STEP_MAX_BYTES = 4096;
+
+/** The error code a `humanStep` node stops with once its dependencies are done, never dispatched to a provider. */
+export const HUMAN_STEP_ERROR_CODE = "human_step_pending";
+
+/**
+ * @param {unknown} value
+ * @param {string} label
+ * @returns {{step: string, command: string}|undefined}
+ */
+export function validateHumanStep(value, label) {
+  if (value === undefined) return undefined;
+  assertObject(value, label);
+  const record = /** @type {Record<string, unknown>} */ (value);
+  rejectUnknown(record, HUMAN_STEP_FIELDS, label);
+  boundedString(record.step, `${label}.step`, HUMAN_STEP_MAX_BYTES);
+  boundedString(record.command, `${label}.command`, HUMAN_STEP_MAX_BYTES);
+  return { step: /** @type {string} */ (record.step), command: /** @type {string} */ (record.command) };
+}
+
+/**
+ * The attention message naming the step and its command: `state.error.message`
+ * carries this verbatim, so every existing attention surface (the final
+ * report, the run's stdout line, a resume's attention print) names both
+ * without reading the contract a second time.
+ *
+ * @param {{step: string, command: string}} humanStep
+ * @returns {string}
+ */
+export function humanStepAttentionMessage(humanStep) {
+  return `${humanStep.step} — run \`${humanStep.command}\``;
+}
+
+/**
+ * @param {{status?: string, error?: {code?: string}|null}} state
+ * @returns {boolean}
+ */
+export function isHumanStepPending(state) {
+  return state.status === "blocked" && state.error?.code === HUMAN_STEP_ERROR_CODE;
+}

package/src/contract/index.mjs

@@ -14,6 +14,9 @@ import { stableJson } from "../util.mjs";
 import { assertObject, boundedString, nonNegativeInteger, nonNegativeNumber, positiveInteger, positiveNumber, rejectUnknown, requireId, requireString } from "./assert.mjs";
 import { validateMetadata } from "./schema-version.mjs";
 import { assertRuntimeExecutesCommands, judgeWriteWarnings, requireRuntime, validateRuntime } from "./runtime.mjs";
+import { validateJudgeList } from "./judges.mjs";
+import { markSameProviderReviewNodes, validateJudgeIndependence } from "./judge-independence.mjs";
+import { validateHumanStep } from "./human-step.mjs";
 import { validateSourceIdentity } from "../repo/source-identity.mjs";
 import { commandCoverageWarnings, ignoreSourceWriteWarnings, mirrorCoverageWarnings, unsnapshottedWriteWarnings } from "../repo/declared-paths.mjs";
 import { crossNodeScopeFindings, scopeClosureFindings } from "../repo/scope-closure.mjs";
@@ -33,13 +36,14 @@ const WRITE_FILE_LINE_WARN_MARGIN = 100;
 const CONTRACT_FIELDS = new Set([
   "schemaVersion", "contractVersion", "id", "campaignId", "goal", "cwd", "sourceIdentity",
   "maxParallel", "pollIntervalMs", "stallTimeoutSec", "timeoutSec", "maxTurns", "phaseSessionReuse",
-  "runtimeDefaults", "runtimes", "nodes", "warnings", "finalVerification", "sharedVerification", "nodeAdvisory",
+  "runtimeDefaults", "runtimes", "nodes", "warnings", "finalVerification", "sharedVerification", "nodeAdvisory", "judges",
+  "judgeIndependence",
 ]);
 const DEFAULTS_FIELDS = new Set(["worker", "judge"]);
 const NODE_FIELDS = new Set([
   "id", "type", "phase", "requirementIds", "runtime", "dependsOn", "taskPacket", "taskPacketFile", "prompt", "promptFile",
   "definitionOfDone", "gate", "timeoutSec", "maxTurns",
-  "requiredCapabilities", "packetHash", "sourceIdentity", "replayPolicy",
+  "requiredCapabilities", "packetHash", "sourceIdentity", "replayPolicy", "sameProviderReview", "humanStep",
 ]);
 const REPLAY_POLICIES = new Set(["safe", "reconcile", "never"]);
 /**
@@ -68,9 +72,9 @@ const GATE_REVIEWS = new Set(["none", "advisory", "blocking"]);
 
 /** @typedef {{enabled: boolean, review?: ("none"|"advisory"|"blocking"), runtime?: string, failOn?: ("minor"|"major"|"critical")[], maxRevisions?: number, requiredCapabilities?: CapabilityRequirements, skipWhen?: {verificationGreen: true, maxChangedPaths: number}}} ValidatedGate */
 
-/** @typedef {{id: string, type: string, phase: string, requirementIds?: string[], runtime?: string, dependsOn: string[], taskPacket: TaskPacket, taskPacketFile?: string, prompt: string, definitionOfDone: import("./definition-of-done.mjs").DefinitionOfDoneItem[], gate: ValidatedGate, timeoutSec?: number, maxTurns?: number, requiredCapabilities: CapabilityRequirements, packetHash: string, sourceIdentity: SourceIdentity, replayPolicy: "safe"|"reconcile"|"never"}} ValidatedNode */
+/** @typedef {{id: string, type: string, phase: string, requirementIds?: string[], runtime?: string, dependsOn: string[], taskPacket: TaskPacket, taskPacketFile?: string, prompt: string, definitionOfDone: import("./definition-of-done.mjs").DefinitionOfDoneItem[], gate: ValidatedGate, timeoutSec?: number, maxTurns?: number, requiredCapabilities: CapabilityRequirements, packetHash: string, sourceIdentity: SourceIdentity, replayPolicy: "safe"|"reconcile"|"never", sameProviderReview: boolean, humanStep?: {step: string, command: string}}} ValidatedNode */
 
-/** @typedef {{schemaVersion: number, contractVersion: string, id: string, campaignId: string, goal: string, cwd: string, sourceIdentity: SourceIdentity, runtimes: Record<string, ValidatedRuntime>, runtimeDefaults: {worker?: string, judge?: string}, nodes: ValidatedNode[], maxParallel: number, pollIntervalMs: number, stallTimeoutSec: number, timeoutSec: number, maxTurns: number, phaseSessionReuse: boolean, finalVerification?: VerificationCommand[], sharedVerification?: VerificationCommand[], nodeAdvisory?: NodeAdvisoryPolicy, warnings: string[]}} ValidatedContract */
+/** @typedef {{schemaVersion: number, contractVersion: string, id: string, campaignId: string, goal: string, cwd: string, sourceIdentity: SourceIdentity, runtimes: Record<string, ValidatedRuntime>, runtimeDefaults: {worker?: string, judge?: string}, judges?: string[], judgeIndependence?: "same-vendor", nodes: ValidatedNode[], maxParallel: number, pollIntervalMs: number, stallTimeoutSec: number, timeoutSec: number, maxTurns: number, phaseSessionReuse: boolean, finalVerification?: VerificationCommand[], sharedVerification?: VerificationCommand[], nodeAdvisory?: NodeAdvisoryPolicy, warnings: string[]}} ValidatedContract */
 /** @typedef {{costUsd?: number, durationSec?: number}} NodeAdvisoryPolicy */
 
 /** @typedef {"pending"|"running"|"done"|"no-op"|"blocked"|"failed"|"exhausted"|"stalled"|"canceled"} NodeStatus */
@@ -95,10 +99,12 @@ const GATE_REVIEWS = new Set(["none", "advisory", "blocking"]);
 /** @typedef {{available: boolean, exhaustedUntil: string|null, reason: string}} RuntimeAvailability */
 /** @typedef {{runtimeId: string, exhaustedUntil: string|null}} TierExhaustionCandidate */
 /** @typedef {{role: "worker"|"judge", candidates: TierExhaustionCandidate[]}} TierExhaustion */
-/** @typedef {{history: RoutingHistoryEntry[], currentOverride: RoutingOverride|null, assignments?: RuntimeAssignments, availability?: Record<string, RuntimeAvailability>, tierExhaustion?: TierExhaustion, tierExhaustionCycle?: number}} RoutingState */
+/** @typedef {{id: string, reason: string}} JudgeSkip */
+/** @typedef {{list: string[], chosen: string|null, skipped: JudgeSkip[]}} JudgeListState */
+/** @typedef {{history: RoutingHistoryEntry[], currentOverride: RoutingOverride|null, assignments?: RuntimeAssignments, availability?: Record<string, RuntimeAvailability>, tierExhaustion?: TierExhaustion, tierExhaustionCycle?: number, judgeList?: JudgeListState}} RoutingState */
 /** @typedef {{revision?: number, heartbeatCount: number, dryHeartbeatCount: number, progressSignature?: string|null, lastHeartbeatAt: string|null, lastProgressAt: string|null, nextCheckAt?: string|null}} ProgressState */
 /** @typedef {{status: "unassigned"|"provisioning"|"ready"|"failed"|"removed", path: string|null, branch: string|null, commit: string|null, baseSha?: string|null, sealedSha?: string|null, sealError?: string|null, previousAttempt?: number|null}} WorktreeState */
-/** @typedef {{schemaVersion: number, contractVersion: string, id: string, type: string, sourceIdentity: SourceIdentity, packetHash: string, requirementIds?: string[], status: NodeStatus, phase: NodePhase, attempt: number, revisions: number, judgeFailures?: number, review?: ("none"|"advisory"|"blocking"), runtime: RuntimeSnapshot|null, blockedBy: string[], startedAt: string|null, updatedAt: string, result: unknown, gate: GateResult|null, error: SnapshotError|null, usage?: Usage, costUsd?: number, routing?: RoutingState|null, progress?: ProgressState|null, worktree?: WorktreeState|null, integratedHead?: string|null, invocations?: Invocation[], executionOverrides?: ExecutionOverride[], verification?: VerificationState|null, scope?: BoundedScope|null, scopeFindings?: ScopeFindings|null, verificationArtifacts?: string[], previousAttempt?: string, sessionPolicy?: {forceFresh?: boolean}|null, declaredReadBytes?: number|null}} NodeSnapshot */
+/** @typedef {{schemaVersion: number, contractVersion: string, id: string, type: string, sourceIdentity: SourceIdentity, packetHash: string, requirementIds?: string[], status: NodeStatus, phase: NodePhase, attempt: number, revisions: number, judgeFailures?: number, review?: ("none"|"advisory"|"blocking"), runtime: RuntimeSnapshot|null, blockedBy: string[], startedAt: string|null, updatedAt: string, result: unknown, gate: GateResult|null, error: SnapshotError|null, usage?: Usage, costUsd?: number, routing?: RoutingState|null, progress?: ProgressState|null, worktree?: WorktreeState|null, integratedHead?: string|null, invocations?: Invocation[], executionOverrides?: ExecutionOverride[], verification?: VerificationState|null, scope?: BoundedScope|null, scopeFindings?: ScopeFindings|null, verificationArtifacts?: string[], previousAttempt?: string, sessionPolicy?: {forceFresh?: boolean}|null, declaredReadBytes?: number|null, sameProviderReview?: boolean}} NodeSnapshot */
 /** @typedef {{path: string, sha: string}} ControllerIdentity */
 /** @typedef {{schemaVersion: number, contractVersion: string, pid: number, processStartToken: string|null, startedAt: string, sourceIdentity: SourceIdentity, controllerIdentity?: ControllerIdentity, integrationRef?: string, identityWarnings?: string[], relaunchCount?: number, lastRelaunchProgressAt?: string|null, attention?: {code: string, message: string, at: string}|null, contractDigest?: string, scopeDecision?: ScopeDecision, autoRetries?: Record<string, {code: string, at: string}>}} RunMetadata */
 /** @typedef {{at: string, base: string|null, dirtyTreeFingerprint: string|null}} ScopeDecision */
@@ -160,6 +166,8 @@ export function validateContract(raw, contractPath, options = {}) {
   rejectUnknown(defaults, DEFAULTS_FIELDS, "contract.runtimeDefaults");
   if (defaults.worker !== undefined) requireRuntime(runtimes, defaults.worker, "runtimeDefaults.worker");
   if (defaults.judge !== undefined) requireRuntime(runtimes, defaults.judge, "runtimeDefaults.judge");
+  const judges = validateJudgeList(raw.judges, runtimes, "contract.judges");
+  const judgeIndependence = validateJudgeIndependence(raw.judgeIndependence, "contract.judgeIndependence");
 
   if (!Array.isArray(raw.nodes) || raw.nodes.length === 0) {
     throw new TypeError("contract.nodes must be a non-empty array");
@@ -244,6 +252,7 @@ export function validateContract(raw, contractPath, options = {}) {
       ? undefined
       : positiveInteger(node.maxTurns, `nodes[${index}].maxTurns`);
     const replayPolicy = validateReplayPolicy(node.replayPolicy, `nodes[${index}]`);
+    const humanStep = validateHumanStep(node.humanStep, `nodes[${index}].humanStep`);
     return /** @type {ValidatedNode} */ ({
       ...node,
       dependsOn,
@@ -257,6 +266,11 @@ export function validateContract(raw, contractPath, options = {}) {
       timeoutSec,
       maxTurns,
       replayPolicy,
+      // Flipped true below, once the worker/judge vendor check has run for
+      // every node: same-vendor mode (R20) is only known admissible after
+      // that pass reads the pair's declared tiers.
+      sameProviderReview: false,
+      ...(humanStep === undefined ? {} : { humanStep }),
     });
   });
 
@@ -290,38 +304,9 @@ export function validateContract(raw, contractPath, options = {}) {
     }
   }
 
-  // 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 rather than left to reach dispatch.
-  // 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`).
-  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 workerVendor = runtimes[/** @type {string} */ (workerRuntimeId)].vendor;
-    const judgeVendor = runtimes[/** @type {string} */ (judgeRuntimeId)].vendor;
-    if (workerVendor === judgeVendor) {
-      throw new TypeError(`nodes[${index}] worker runtime ${workerRuntimeId} and judge runtime ${judgeRuntimeId} share vendor ${workerVendor}`);
-    }
-    const seenFallbacks = new Set([/** @type {string} */ (workerRuntimeId)]);
-    let fallbackId = runtimes[/** @type {string} */ (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) {
-        throw new TypeError(`nodes[${index}] worker runtime ${workerRuntimeId} fallback runtime ${fallbackId} and judge runtime ${judgeRuntimeId} share vendor ${fallbackVendor}`);
-      }
-      fallbackId = runtimes[fallbackId].fallback;
-    }
-  }
+  // See `markSameProviderReviewNodes` for the vendor-conflict refusal and
+  // R20's same-vendor opt-in that relaxes it.
+  markSameProviderReviewNodes(nodes, runtimes, defaults, judgeIndependence);
 
   // Every worker prompt tells the worker to run its packet verification.
   // Refuse a statically known permission mode that makes that instruction
@@ -403,6 +388,8 @@ export function validateContract(raw, contractPath, options = {}) {
     cwd,
     runtimes,
     runtimeDefaults: /** @type {{worker?: string, judge?: string}} */ (defaults),
+    judges,
+    judgeIndependence,
     nodes,
     maxParallel: validateMaxParallel(raw.maxParallel ?? 1),
     pollIntervalMs: positiveInteger(raw.pollIntervalMs ?? 1_000, "contract.pollIntervalMs"),