faberun 0.25.1 → 0.26.1

package/src/engine/runtime-discovery.mjs

@@ -1,4 +1,6 @@
 import { normalizeProviderAvailability, probeRuntime } from "../harnesses/index.mjs";
+import { effectiveProvider } from "../contract/provider.mjs";
+import { SAME_VENDOR_REVIEW_MODE, sameVendorTierRefusal } from "../contract/judge-independence.mjs";
 
 // Availability normalization belongs to the adapter registry, which is where
 // each provider's own exhaustion, balance, and authentication wording is
@@ -8,7 +10,7 @@ export { exhaustedUntilOf, normalizeProviderAvailability } from "../harnesses/in
 
 /** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
 /** @typedef {{harness?: string, model?: string, vendor: string, tier?: number|string, costRank?: number, [key: string]: unknown}} RuntimeLike */
-/** @typedef {{runtimes: Record<string, RuntimeLike>, runtimeDefaults?: {worker?: string, judge?: string}, nodes?: {id: string, runtime?: string, gate: {enabled: boolean, runtime?: string}}[]}} RuntimeContract */
+/** @typedef {{runtimes: Record<string, RuntimeLike>, runtimeDefaults?: {worker?: string, judge?: string}, judgeIndependence?: string, nodes?: {id: string, runtime?: string, gate: {enabled: boolean, runtime?: string}}[]}} RuntimeContract */
 /**
  * One runtime's catalogue record: what the harness de facto reported, and
  * when. An unobservable datum is null -- never zero and never full allowance,
@@ -20,7 +22,20 @@ export { exhaustedUntilOf, normalizeProviderAvailability } from "../harnesses/in
 /** @typedef {{harness: string, model: string, vendor: string, tier: number, costRank: number, config?: Record<string, unknown>}} DiscoveryRuntime */
 /** @typedef {{id: string, runtime: RuntimeLike, order: number}} RuntimeCandidate */
 /** @typedef {import("../host/config.mjs").UserConfig} UserConfig */
-/** @typedef {{config?: UserConfig|null, onWarning?: (message: string) => void}} ComposeOptions */
+/** @typedef {{id: string, gate: {enabled: boolean, runtime?: string}}} ComposeOptionsNode */
+/**
+ * `listJudge`'s return governs precedence, not just a value: `undefined`
+ * means no list applies to this node (its gate is disabled), so
+ * `composeAssignments` falls through to its own candidates unchanged; once a
+ * list applies, its pick is final and nothing else is tried, whether that
+ * pick is a runtime id (`chosen`) or `null` for an exhausted list. The full
+ * pick, not just `chosen`, is returned so an exhausted list's thrown error can
+ * name every skipped entry and why -- an operator reading an aborted run
+ * cannot otherwise tell the list was even consulted.
+ * @typedef {{id: string, reason: string}} JudgeListSkip
+ * @typedef {{chosen: string|null, skipped: JudgeListSkip[]}} JudgeListPick
+ * @typedef {{config?: UserConfig|null, onWarning?: (message: string) => void, listJudge?: (node: ComposeOptionsNode, workerId: string, workerProvider: string|undefined) => JudgeListPick|undefined}} ComposeOptions
+ */
 
 /**
  * Candidates used when a contract omits its runtime catalogue. The catalogue
@@ -124,6 +139,16 @@ export function availableCandidates(runtimes, availability = {}) {
  * `options.onWarning`; config never overrides an explicit node, gate or
  * runtime-default declaration, and the cross-vendor judge rule still applies.
  *
+ * `options.listJudge` (R18) is asked for an omitted judge before the single
+ * `config.judge` preference and the strongest-candidate default: it is the
+ * caller's own ordered-list selection (`engine/judge-list.mjs`), kept out of
+ * this module so a list pick's refusal- and usage-window reads never import a
+ * `run/` consumer of this very function back into a cycle. Returning
+ * `undefined` -- no list governs this node -- falls through to the candidates
+ * below exactly as if it had not been asked. A governed node's pick is final
+ * instead: a string is used as-is, and `null` -- every entry was skipped --
+ * throws rather than silently falling through to a judge outside the list.
+ *
  * @param {RuntimeContract} contract
  * @param {Record<string, RuntimeAvailability>} availability
  * @param {ComposeOptions} [options]
@@ -149,21 +174,57 @@ export function composeAssignments(contract, availability = {}, options = {}) {
     const workerRuntime = contract.runtimes[worker];
     const judgeOmitted = node.gate.runtime === undefined && contract.runtimeDefaults?.judge === undefined;
     const preferredJudge = judgeOmitted ? candidateById(candidates, config?.judge) : undefined;
-    const judge = node.gate.runtime ?? contract.runtimeDefaults?.judge
-      ?? (preferredJudge && preferredJudge.runtime.vendor !== workerRuntime.vendor ? preferredJudge.id : undefined)
-      ?? strongest(candidates, workerRuntime.vendor)?.id;
+    const workerProvider = effectiveProvider(workerRuntime);
+    const declaredJudge = node.gate.runtime ?? contract.runtimeDefaults?.judge;
+    // R18: once a list governs this node (`judgeListPick` is not
+    // `undefined`), its pick is final -- a string is used as-is, and `null`
+    // (every entry skipped) must not fall through to
+    // `preferredJudge`/`strongest` below, or the node would land on a judge
+    // outside the declared list and the skip evidence `listJudge` already
+    // recorded would go unused. The thrown error itself names every skipped
+    // entry and why: this is the only trace of the list an operator reading
+    // an aborted run has, since the caller's own record of `judgeListStates`
+    // is never reached when this constructor throws before returning.
+    const judgeListPick = declaredJudge === undefined && judgeOmitted ? options.listJudge?.(node, worker, workerProvider) : undefined;
+    if (judgeListPick && judgeListPick.chosen === null) {
+      const reasons = judgeListPick.skipped.map((entry) => `${entry.id}: ${entry.reason}`).join("; ");
+      throw new Error(`runtime_assignment_judge_unavailable: every entry of the judge list is unavailable for node ${node.id} and worker ${worker} (${reasons})`);
+    }
+    // R20: in same-vendor mode a judge of the worker's own provider is
+    // admissible when it is another model at an equal or higher declared tier;
+    // the strongest such candidate is the default only when no other vendor has one.
+    const sameVendorMode = contract.judgeIndependence === SAME_VENDOR_REVIEW_MODE;
+    const judge = declaredJudge
+      ?? judgeListPick?.chosen
+      ?? (preferredJudge && effectiveProvider(preferredJudge.runtime) !== workerProvider ? preferredJudge.id : undefined)
+      ?? strongest(candidates, workerProvider)?.id
+      ?? (sameVendorMode ? strongest(candidates.filter(({ id, runtime }) => id !== worker && isTierAdmissible(workerRuntime, runtime)), undefined)?.id : undefined);
     if (node.gate.enabled && (!judge || !contract.runtimes[judge])) {
       throw new Error(`runtime_assignment_judge_unavailable: no available cross-vendor judge for node ${node.id} and worker ${worker}`);
     }
     const judgeRuntime = judge ? contract.runtimes[judge] : undefined;
-    if (node.gate.enabled && workerRuntime && judgeRuntime && judgeRuntime.vendor === workerRuntime.vendor) {
-      throw new Error(`runtime_assignment_judge_unavailable: no available cross-vendor judge for node ${node.id} and worker ${worker}`);
+    if (node.gate.enabled && workerRuntime && judgeRuntime && effectiveProvider(judgeRuntime) === workerProvider) {
+      if (!sameVendorMode) throw new Error(`runtime_assignment_judge_unavailable: no available cross-vendor judge for node ${node.id} and worker ${worker}`);
+      if (judge === worker) throw new Error(`runtime_assignment_judge_unavailable: same-vendor mode needs a judge other than worker ${worker} for node ${node.id}`);
+      const refusal = sameVendorTierRefusal(/** @type {{harness: string, model: string}} */ (workerRuntime), /** @type {{harness: string, model: string}} */ (judgeRuntime));
+      if (refusal) throw new Error(`runtime_assignment_judge_unavailable: ${refusal.message} for node ${node.id}`);
     }
     assignments[node.id] = { worker, judge: judge ?? worker };
   }
   return assignments;
 }
 
+/**
+ * @param {RuntimeLike} workerRuntime
+ * @param {RuntimeLike} judgeRuntime
+ * @returns {boolean}
+ */
+function isTierAdmissible(workerRuntime, judgeRuntime) {
+  if (typeof workerRuntime.harness !== "string" || typeof workerRuntime.model !== "string") return false;
+  if (typeof judgeRuntime.harness !== "string" || typeof judgeRuntime.model !== "string") return false;
+  return sameVendorTierRefusal({ harness: workerRuntime.harness, model: workerRuntime.model }, { harness: judgeRuntime.harness, model: judgeRuntime.model }) === null;
+}
+
 /**
  * @param {RuntimeCandidate[]} candidates
  * @param {string|undefined} id
@@ -189,12 +250,12 @@ export function nextSameTierRuntime(contract, stateRouting, role, current, attem
   const currentRuntime = contract.runtimes[current];
   if (!currentRuntime) return null;
   const workerId = stateRouting.assignments?.worker;
-  const workerVendor = workerId ? contract.runtimes[workerId]?.vendor : null;
+  const workerProvider = workerId && contract.runtimes[workerId] ? effectiveProvider(contract.runtimes[workerId]) : null;
   const used = new Set(attempted);
   return Object.entries(contract.runtimes)
     .filter(([id, runtime]) => id !== current && !used.has(id) && sameTier(runtime, currentRuntime))
     .filter(([id]) => isRuntimeAvailable(stateRouting.availability?.[id]))
-    .filter(([, runtime]) => role !== "judge" || runtime.vendor !== workerVendor)
+    .filter(([, runtime]) => role !== "judge" || effectiveProvider(runtime) !== workerProvider)
     .sort((left, right) => runtimeOrder(left[1]) - runtimeOrder(right[1]))
     .map(([id]) => id)
     .at(0) ?? null;
@@ -232,11 +293,11 @@ export function cheapest(candidates) {
  * `cheapest` for `setup`'s cross-vendor judge default.
  *
  * @param {RuntimeCandidate[]} candidates
- * @param {string} vendor
+ * @param {string|undefined} vendor
  * @returns {RuntimeCandidate|null}
  */
 export function strongest(candidates, vendor) {
-  return [...candidates].filter(({ runtime }) => runtime.vendor !== vendor)
+  return [...candidates].filter(({ runtime }) => effectiveProvider(runtime) !== vendor)
     .sort((left, right) => tierOrder(right.runtime) - tierOrder(left.runtime)
       || runtimeOrder(right.runtime) - runtimeOrder(left.runtime)
       || left.order - right.order).at(0) ?? null;

package/src/engine/scheduler.mjs

@@ -44,6 +44,8 @@ import { captureNodeScopeBoundaries, checkWorkerScope, emptyScope } from "./scop
 import { validateContractForLaunch } from "../campaign/chain.mjs";
 import { finalVerificationCommands, gateProofTimeoutMs, sharedVerificationCommands } from "../contract/final-verification.mjs";
 import { startJudge, startWorker } from "./dispatch.mjs";
+import { raiseNodeAttention } from "./settle.mjs";
+import { HUMAN_STEP_ERROR_CODE, humanStepAttentionMessage } from "../contract/human-step.mjs";
 import { assertEnvironmentReady, captureRunIdentity, createRunMetadata, serializableContract, statesFingerprint } from "./run-identity.mjs";
 import { blockDependents, runtimeAssignments } from "./assignment.mjs";
 import { createHeartbeat, HEARTBEAT_INTERVAL_MS } from "./supervise.mjs";
@@ -290,6 +292,11 @@ export async function runContract(contractPath, options = {}) {
           currentOverride: null,
           assignments: runtimePlan.assignments[node.id],
           availability: runtimePlan.availability,
+          // Only a genuinely list-driven pick (R18) carries this evidence. An
+          // exhausted list (`chosen` null) never reaches here: composeAssignments
+          // throws before a run is created rather than falling through to the
+          // discovery ranking (see `runtime-discovery.mjs`'s `listPick`).
+          ...(runtimePlan.judgeListStates[node.id] ? { judgeList: runtimePlan.judgeListStates[node.id] } : {}),
         },
         progress: null,
         invocations: [],
@@ -617,20 +624,34 @@ export async function driveRun(contract, runDir, states, campaign, lock, sourceI
       autoRetryParkedNodes(contract, runDir, states, lock, parkedBefore);
       blockDependents(contract, runDir, states, lock);
 
+      const ready = contract.nodes.filter((node) => {
+        const state = states.get(node.id);
+        return state?.status === "pending" && !pendingSettlements.has(node.id)
+          && node.dependsOn.every((id) => states.get(id)?.status === "done");
+      });
+      // A human-step node (R16) never reaches a provider: once its
+      // dependencies are done it stops right here, `state.error.message`
+      // naming the step and its command, instead of entering the slot-gated
+      // dispatch below. It costs no slot and is not bounded by `maxParallel`,
+      // so this runs whether or not one is free.
+      for (const node of ready) {
+        if (!node.humanStep) continue;
+        transition(runDir, /** @type {NodeSnapshot} */ (states.get(node.id)), "blocked", {
+          phase: "complete",
+          error: { code: HUMAN_STEP_ERROR_CODE, message: humanStepAttentionMessage(node.humanStep) },
+        }, lock);
+        await raiseNodeAttention(campaign.path, runDir, /** @type {NodeSnapshot} */ (states.get(node.id)), HUMAN_STEP_ERROR_CODE);
+      }
       const slots = contract.maxParallel - running.size;
       if (slots > 0) {
-        const ready = contract.nodes.filter((node) => {
-          const state = states.get(node.id);
-          return state?.status === "pending" && !pendingSettlements.has(node.id)
-            && node.dependsOn.every((id) => states.get(id)?.status === "done");
-        });
+        const dispatchable = ready.filter((node) => !node.humanStep);
         // Per-runtime capacity is judged per dispatch, not per tick: the
         // counts include what this tick has already started, and a runtime a
         // sibling is waiting out a quota reset on accepts nothing new.
         const counts = runningPerRuntime(running.values());
         const held = quotaHeldRuntimes(states.values(), Date.now());
         let dispatched = 0;
-        for (const node of ready) {
+        for (const node of dispatchable) {
           if (dispatched >= slots) break;
           const state = states.get(node.id);
           if (!state || routingBackoffActive(state, state.phase)) continue;

package/src/harnesses/catalogue.mjs

@@ -1,7 +1,9 @@
 import { spawnSync } from "node:child_process";
 import { getHarness, probeRuntime, registeredHarnesses, resolveVendor } from "./index.mjs";
 import { DISCOVERY_RUNTIME_DEFINITIONS, composeAssignments } from "../engine/runtime-discovery.mjs";
+import { canonicalProvider } from "../contract/provider.mjs";
 import { errorMessage } from "../util.mjs";
+import { ANTHROPIC_MODEL_TIERS } from "./model-tiers.mjs";
 import { spawnInvocation } from "../host/platform.mjs";
 
 /**
@@ -51,7 +53,7 @@ const GLM_CONTEXT_WINDOW_TOKENS = 200_000;
 const GLM_ONE_MILLION_CONTEXT_WINDOW_TOKENS = 1_048_576;
 
 /**
- * @typedef {{id: string, contextWindowTokens: number|null, efforts: readonly string[], defaultEffort: string|null, effortInModelId: string|null}} DeclaredModel
+ * @typedef {{id: string, contextWindowTokens: number|null, efforts: readonly string[], defaultEffort: string|null, effortInModelId: string|null, tier: number|null}} DeclaredModel
  * @typedef {{harness: string, vendor: string|null}} ModelPath
  * @typedef {{id: string, contextWindowTokens: number|null, efforts: string[], defaultEffort: string|null, effortInModelId: string|null, declaredBy: ModelPath[]}} ModelView
  * @typedef {{ok: boolean, available: boolean, reason: string, version: string|null}} ProbeView
@@ -72,6 +74,9 @@ export const DECLARED_MODEL_CATALOGUES = Object.freeze({
   claude: Object.freeze([
     declaredModel("claude-sonnet-5", { efforts: CLAUDE_EFFORTS }),
     declaredModel("claude-opus-5", { efforts: CLAUDE_EFFORTS }),
+    declaredModel("claude-opus-5-5", { efforts: CLAUDE_EFFORTS }),
+    declaredModel("claude-fable-5", { efforts: CLAUDE_EFFORTS }),
+    declaredModel("claude-fable-5-1", { efforts: CLAUDE_EFFORTS }),
     declaredModel("claude-sonnet-4-6", { efforts: CLAUDE_EFFORTS }),
   ]),
   codex: Object.freeze([
@@ -162,6 +167,7 @@ function declaredModel(id, options) {
     efforts: options.efforts,
     defaultEffort: options.defaultEffort ?? null,
     effortInModelId: options.effortInModelId ?? null,
+    tier: ANTHROPIC_MODEL_TIERS[id] ?? null,
   });
 }
 
@@ -182,6 +188,7 @@ function agyModel(id, contextWindowTokens = null) {
     efforts: AGY_EFFORTS,
     defaultEffort: encoded,
     effortInModelId: encoded,
+    tier: ANTHROPIC_MODEL_TIERS[id] ?? null,
   });
 }
 
@@ -358,7 +365,7 @@ function suggestedAllocation() {
   /** @type {Record<string, {available: boolean, exhaustedUntil: string|null, reason: string}>} */
   const availability = {};
   for (const [id, definition] of Object.entries(DISCOVERY_RUNTIME_DEFINITIONS)) {
-    const vendor = resolveVendor(definition);
+    const vendor = canonicalProvider(definition) ?? resolveVendor(definition);
     if (!vendor) throw new Error(`discovery runtime ${id} resolves no vendor`);
     runtimes[id] = { ...definition, vendor };
     availability[id] = { available: true, exhaustedUntil: null, reason: "declared" };

package/src/harnesses/index.mjs

@@ -177,7 +177,7 @@ export function writesWorkspace(runtime) {
  * the exec'd binary actually is, so neither gets a default here — a contract
  * using either must declare `vendor` outright.
  */
-const DEFAULT_HARNESS_VENDORS = Object.freeze({
+export const DEFAULT_HARNESS_VENDORS = Object.freeze({
   claude: "anthropic",
   codex: "openai",
   agy: "google",
@@ -322,7 +322,7 @@ export function exhaustedUntilOf(envelope, now = Date.now()) {
  * @returns {{available: false, exhaustedUntil: string|null, reason: string}|null} null when text names none of the known patterns
  */
 function classifyAvailabilityText(text) {
-  if (/insufficient balance/iu.test(text) || /\b402\b/u.test(text)) {
+  if (/insufficient balance|spend limit/iu.test(text) || /\b402\b/u.test(text)) {
     return { available: false, exhaustedUntil: null, reason: "insufficient_balance" };
   }
   if (/quota|rate.?limit|usage limit|session limit|limit exhausted|1310/iu.test(text)) {

package/src/harnesses/model-tiers.mjs

@@ -0,0 +1,39 @@
+/**
+ * The per-model tier table same-vendor review reads (R20). Separate from
+ * `catalogue.mjs` because that module imports the engine's runtime discovery,
+ * and the tier rule is read by both contract validation and runtime
+ * assignment; kept here it has no imports, so neither reader cycles back
+ * through the catalogue.
+ */
+
+/**
+ * Every Anthropic model's tier, in the order of the owner's price list (R20):
+ * Sonnet 2 (US$ 2 / 10 per MTok), Opus 3 (5 / 25 and 4 / 20), Fable 4 (10 /
+ * 50). Sonnet is cheap enough to work; Opus or Fable is what judges it. A
+ * model absent from this table declares no tier and cannot judge in
+ * same-vendor mode (`contract/judge-independence.mjs`).
+ *
+ * @type {Readonly<Record<string, number>>}
+ */
+export const ANTHROPIC_MODEL_TIERS = Object.freeze({
+  "claude-sonnet-5": 2,
+  "claude-opus-5": 3,
+  "claude-opus-5-5": 3,
+  "claude-fable-5": 4,
+  "claude-fable-5-1": 4,
+});
+
+/**
+ * The declared tier of a model reached through a given harness: only an
+ * Anthropic model run through the `claude` harness carries one today. `null`
+ * covers every other harness and every model this table does not list, which
+ * is exactly what `sameVendorTierRefusal` reads as "cannot judge in
+ * same-vendor mode".
+ *
+ * @param {string} harness
+ * @param {string} model
+ * @returns {number|null}
+ */
+export function declaredModelTier(harness, model) {
+  return harness === "claude" ? ANTHROPIC_MODEL_TIERS[model] ?? null : null;
+}

package/src/harnesses/protocol.mjs

@@ -307,8 +307,11 @@ export function eventItem(event) {
  * window: measured 2026-09-20, "You've hit your session limit · resets 6:40pm
  * (America/Sao_Paulo)" settled as provider_error and two faberun nodes burnt
  * both attempts inside a minute instead of holding until the reset.
+ * "spend limit" is the account's monthly credit ceiling: measured 2026-09-25,
+ * "You've hit your monthly spend limit" on claude-fable-5-1 settled as
+ * provider_error, so the planner's reviewer list never moved to its next entry.
  */
-const QUOTA_TEXT_PATTERN = /429|1310|rate.?limit|usage limit|session limit|limit exhausted|quota|too many requests/iu;
+const QUOTA_TEXT_PATTERN = /429|1310|rate.?limit|usage limit|session limit|spend limit|limit exhausted|quota|too many requests/iu;
 
 /**
  * @param {string|null|undefined} text

package/src/host/config.mjs

@@ -1,6 +1,9 @@
 /**
  * The user config at `$FABERUN_HOME/config.json`: which harnesses `setup`
- * enabled and which runtime is the default worker and judge.
+ * enabled, which runtime is the default worker and judge, the machine's own
+ * ordered `judges` list (R18) -- read only when a contract declares none --
+ * and its ordered `reviewers` list (R19), `faberun plan`'s own machine
+ * default, read only when `--reviewers` names none.
  *
  * It is separate from `host/home.mjs`, which owns the path, because reading a
  * config is a validation problem and writing it is an atomic-write problem;
@@ -11,7 +14,7 @@ import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { configPath, faberunHome } from "./home.mjs";
 
-/** @typedef {{schemaVersion: 1, harnesses: string[], worker?: string, judge?: string, updatedAt: string}} UserConfig */
+/** @typedef {{schemaVersion: 1, harnesses: string[], worker?: string, judge?: string, judges?: string[], reviewers?: string[], updatedAt: string}} UserConfig */
 
 /** Paths already reported malformed, so a process that reads twice warns once. */
 const warned = new Set();
@@ -83,5 +86,7 @@ function isUserConfig(value) {
   if (!Array.isArray(record.harnesses) || !record.harnesses.every((harness) => typeof harness === "string")) return false;
   if (record.worker !== undefined && typeof record.worker !== "string") return false;
   if (record.judge !== undefined && typeof record.judge !== "string") return false;
+  if (record.judges !== undefined && (!Array.isArray(record.judges) || !record.judges.every((id) => typeof id === "string"))) return false;
+  if (record.reviewers !== undefined && (!Array.isArray(record.reviewers) || !record.reviewers.every((id) => typeof id === "string"))) return false;
   return typeof record.updatedAt === "string";
 }

package/src/plan/contest.mjs

@@ -0,0 +1,78 @@
+/**
+ * The contested-plan writer: end a planning pipeline the way every
+ * no-valid-plan exit ends it — the contested `plan.json`, its stage line and
+ * an open question on the campaign journal. Separate from `pipeline.mjs` and
+ * `rounds.mjs` (measured 2026-09-24: pipeline.mjs was 742 of 800 lines)
+ * because both the round loop and the pipeline's own outer catches reach this
+ * same exit; a plain function they can each call, rather than a closure
+ * either would have to own, is what makes that sharing possible without
+ * `rounds.mjs` importing back from `pipeline.mjs`.
+ *
+ * `plan` and `resume` ride along on the written record so `faberun plan
+ * --resolve` (R9, `src/plan/resolve.mjs`) can continue from exactly this
+ * point without redrafting or re-collecting repo facts: `plan` is the last
+ * plan a draft or revise actually validated (null when none ever did), and
+ * `resume` is everything else `resolve.mjs` needs to reassemble and freeze
+ * it — the same inputs this run itself was given.
+ *
+ * The open-question note carries a count and the finding ids only, never
+ * their text (RM-105, measured 2026-09-24: two contests in the same campaign
+ * joined every critical finding's text into one note and blew the journal's
+ * per-entry cap, `entry.text is 4706 bytes, over the 2048-byte cap`). Every
+ * finding's full text already lives in `plan.json`, which the note points at.
+ */
+import { join } from "node:path";
+import { campaignCli } from "../cli/campaign.mjs";
+import { writeJsonAtomic } from "../run/store.mjs";
+
+/** @typedef {import("./template.mjs").PlanOutput} PlanOutput */
+/** @typedef {import("./template.mjs").PlanFindingOutput} PlanFindingOutput */
+/** @typedef {import("./pipeline.mjs").VerificationSuites} VerificationSuites */
+/** @typedef {{status: "contested", plansDir: string, planPath: string, findings: PlanFindingOutput[], round: number}} ContestedPipelineResult */
+/**
+ * @typedef {{
+ *   campaignId: string,
+ *   phase: string,
+ *   specPath: string,
+ *   specDigest: string,
+ *   reviewRounds: number,
+ *   runtimeDefaults: {worker?: string, judge?: string},
+ *   reviewers: string[],
+ *   runtimes: Record<string, Record<string, unknown>>,
+ *   verification: VerificationSuites,
+ *   packageMode: import("./sizing.mjs").PackageMode,
+ *   targetedFix: boolean,
+ *   approveBelow: "standard"|"high"|"none",
+ *   repoFacts: import("./repo-facts.mjs").RepoFacts,
+ * }} ContestResumeContext
+ */
+/** @typedef {{formatVersion: 1, status: "contested", rounds: number, findings: PlanFindingOutput[], plan: PlanOutput|null, resume: ContestResumeContext}} ContestedPlanRecord */
+
+/**
+ * @param {{
+ *   campaignId: string,
+ *   phase: string,
+ *   cwd: string,
+ *   plansDir: string,
+ *   sessionId: string,
+ *   findings: PlanFindingOutput[],
+ *   round: number,
+ *   plan: PlanOutput|null,
+ *   resume: ContestResumeContext,
+ *   logStage: (stage: string, extra?: Record<string, unknown>) => void,
+ * }} options
+ * @returns {Promise<ContestedPipelineResult>}
+ */
+export async function contestPlan({ campaignId, phase, cwd, plansDir, sessionId, findings, round, plan, resume, logStage }) {
+  const criticalFindings = findings.filter((finding) => finding.severity === "critical");
+  const planPath = join(plansDir, "plan.json");
+  writeJsonAtomic(planPath, /** @type {ContestedPlanRecord} */ ({ formatVersion: 1, status: "contested", rounds: round, findings, plan, resume }));
+  logStage("contested", { round, criticalCount: criticalFindings.length });
+  const criticalIds = criticalFindings.map((finding) => finding.id);
+  await campaignCli([
+    "note", campaignId, "--cwd", cwd, "--session-id", sessionId,
+    "--kind", "open-question", "--question-id", `plan-${phase}-contested`,
+    "--text", `Plan for phase ${phase} is contested after ${round} review round(s) with ${criticalFindings.length} critical finding(s): ${criticalIds.join(", ")}. Each finding's node/requirement and resolution is in ${planPath}. Resolve with: faberun plan --resolve ${plansDir} --answer <finding-id>=accept and/or --answer <finding-id>=reject:<reason>.`,
+  ]);
+  return { status: "contested", plansDir, planPath, findings, round };
+}

package/src/plan/freeze.mjs

@@ -21,8 +21,10 @@ import { assertObject, rejectUnknown, requirePacketHash, requireString } from ".
 import { writeJsonAtomic, writeTextAtomic } from "../run/store.mjs";
 import { VERIFICATION_LIMITS } from "../contract/verification.mjs";
 import { validatePlanPhases } from "./template.mjs";
+import { NODE_VALUE_OPTIONS, assertFilteredProofsNameTheirTest } from "./proof-scope.mjs";
 
 /** @typedef {import("../contract/index.mjs").JsonObject} JsonObject */
+/** @typedef {import("./human-step.mjs").HumanStep} PlanHumanStep */
 
 /** @typedef {{runtimeId: string, model: string}} PlanParticipant */
 /** @typedef {{id: string, severity: "minor"|"major"|"critical", nodeId?: string, text: string}} PlanFinding */
@@ -30,7 +32,7 @@ import { validatePlanPhases } from "./template.mjs";
 /** @typedef {PlanProvenanceInput & {packageVersion: string, schemaVersion: number, contractVersion: string}} PlanProvenance */
 /** @typedef {{id: string, requirementIds: string[], nodeIds?: string[], deliverable: string}} PlanPhase */
 /** @typedef {{path: string, digest: string}} PlanSpecIdentity */
-/** @typedef {{formatVersion: number, contractDigest: string, spec?: PlanSpecIdentity, phases?: PlanPhase[], provenance: PlanProvenance}} FrozenPlan */
+/** @typedef {{formatVersion: number, contractDigest: string, spec?: PlanSpecIdentity, phases?: PlanPhase[], humanSteps?: PlanHumanStep[], provenance: PlanProvenance}} FrozenPlan */
 /** @typedef {{ok: boolean, digest: string, expectedDigest: string}} FrozenPlanVerdict */
 /** @typedef {{scripts?: Record<string, string>, verificationCandidates: {argv: string[], measuredMs: number}[]}} MeasuredFacts */
 
@@ -46,8 +48,6 @@ const MEASURED_TIMEOUT_MARGIN = 1.5;
 /** `node --test` options that run a subset of the files they name. */
 const FILTER_OPTIONS = ["--test-name-pattern", "--test-skip-pattern", "--test-only", "--test-shard"];
 
-/** `node` options whose value is the next argument, so it is not a path. */
-const NODE_VALUE_OPTIONS = new Set(["--import", "--require", "-r", "--loader", "--experimental-loader", "--env-file", "--test-reporter", "--test-reporter-destination", "--test-name-pattern", "--test-skip-pattern", "--test-concurrency", "--test-timeout"]);
 
 /**
  * The `node --test <dir>` candidates one path argument includes: a directory
@@ -134,6 +134,38 @@ export function assertTimeoutsCoverMeasured(contract, facts) {
   if (problems.size) throw new TypeError(`verification timeouts do not cover their measured durations: ${[...problems].join("; ")}`);
 }
 
+/**
+ * Raise every plan node's verification timeout that sits under
+ * `MEASURED_TIMEOUT_MARGIN` times its measured duration to exactly that
+ * bound — the one repair `assertTimeoutsCoverMeasured` names, so it has a
+ * single answer and needs no worker. A command whose bound passes
+ * `maxTimeoutSec` is left alone: splitting it is a judgement, and the check
+ * still contests it. Measured 2026-09-26 on the 3a gate: four rounds left a
+ * plan with no critical from review, contested only because three nodes gave
+ * `node --test test/harnesses` 120s against a measured 84.4s (bound 127s).
+ *
+ * @param {import("./template.mjs").PlanOutput} plan
+ * @param {MeasuredFacts} facts
+ * @returns {{plan: import("./template.mjs").PlanOutput, raised: string[]}}
+ */
+export function raiseTimeoutsToMeasured(plan, facts) {
+  /** @type {string[]} */
+  const raised = [];
+  const nodes = plan.nodes.map((node) => ({
+    ...node,
+    verification: (node.verification ?? []).map((command) => {
+      const measuredMs = measuredMsFor(command.argv, facts);
+      if (measuredMs === null) return command;
+      const requiredSec = Math.ceil((measuredMs * MEASURED_TIMEOUT_MARGIN) / 1_000);
+      const timeoutSec = command.timeoutSec ?? 120;
+      if (timeoutSec >= requiredSec || requiredSec > VERIFICATION_LIMITS.maxTimeoutSec) return command;
+      raised.push(`${node.id}: ${command.argv.join(" ")} ${timeoutSec}s -> ${requiredSec}s`);
+      return { ...command, timeoutSec: requiredSec };
+    }),
+  }));
+  return { plan: raised.length ? { ...plan, nodes } : plan, raised };
+}
+
 /** @returns {string} the installed package's own version, read once per call so a freeze always names the toolchain that produced it */
 function packageVersion() {
   const packageJsonPath = fileURLToPath(new URL("../../package.json", import.meta.url));
@@ -215,6 +247,78 @@ function specIdentityOf(spec) {
   return { path: /** @type {string} */ (record.path), digest: /** @type {string} */ (record.digest) };
 }
 
+/** The fields a human step declaration carries: requirementId|step|command. */
+const HUMAN_STEP_FIELDS = new Set(["requirementId", "step", "command"]);
+
+/**
+ * The human steps a frozen plan records, shape-checked before anything is
+ * written. Absent or empty is legal: most plans declare none.
+ *
+ * @param {unknown} humanSteps
+ * @returns {PlanHumanStep[]|undefined}
+ */
+function humanStepsOf(humanSteps) {
+  if (humanSteps === undefined) return undefined;
+  if (!Array.isArray(humanSteps) || humanSteps.length === 0) return undefined;
+  return humanSteps.map((step, index) => {
+    const label = `humanSteps[${index}]`;
+    assertObject(step, label);
+    const record = /** @type {Record<string, unknown>} */ (step);
+    rejectUnknown(record, HUMAN_STEP_FIELDS, label);
+    requireString(record.requirementId, `${label}.requirementId`);
+    requireString(record.step, `${label}.step`);
+    requireString(record.command, `${label}.command`);
+    return /** @type {PlanHumanStep} */ ({
+      requirementId: /** @type {string} */ (record.requirementId),
+      step: /** @type {string} */ (record.step),
+      command: /** @type {string} */ (record.command),
+    });
+  });
+}
+
+/**
+ * Add one human node per declared step (R16): the frozen contract node the
+ * scheduler stops on instead of dispatching (`contract/human-step.mjs`
+ * validates the shape; the scheduler reads it at dispatch time). The node the
+ * planner drafted for the requirement keeps its own provider work: the human
+ * node depends on every node that carries the requirement (matched by the
+ * already-inherited `requirementIds`), and every node that depended on one of
+ * those carriers now waits for the human node too. A requirement no node
+ * carries still gets its stop, with no dependencies. The packet is a
+ * discovery packet with no files because it is never dispatched; only its
+ * `humanStep` is read.
+ *
+ * @param {unknown} nodes
+ * @param {PlanHumanStep[]} humanSteps
+ * @returns {unknown}
+ */
+function addHumanStepNodes(nodes, humanSteps) {
+  if (!Array.isArray(nodes)) return nodes;
+  let records = nodes.map((node) => /** @type {Record<string, unknown>} */ (node && typeof node === "object" ? node : {}));
+  for (const step of humanSteps) {
+    const id = `human-step-${step.requirementId.toLowerCase()}`;
+    if (records.some((record) => record.id === id)) throw new TypeError(`human step node id ${id} is already a planned node id`);
+    const carriers = records.filter((record) => Array.isArray(record.requirementIds) && record.requirementIds.includes(step.requirementId));
+    const carrierIds = new Set(carriers.map((record) => /** @type {string} */ (record.id)));
+    records = records.map((record) => {
+      const dependsOn = Array.isArray(record.dependsOn) ? /** @type {string[]} */ (record.dependsOn) : [];
+      if (carrierIds.has(/** @type {string} */ (record.id)) || !dependsOn.some((dependency) => carrierIds.has(dependency))) return record;
+      return { ...record, dependsOn: [...dependsOn, id] };
+    });
+    records.push({
+      id,
+      type: "human",
+      ...(carriers[0]?.phase === undefined ? {} : { phase: carriers[0].phase }),
+      requirementIds: [step.requirementId],
+      dependsOn: [...carrierIds],
+      gate: false,
+      humanStep: { step: step.step, command: step.command },
+      taskPacket: { mode: "discovery", objective: step.step, instructions: [`The operator runs \`${step.command}\` and records it done with faberun resume --answer.`], readFiles: [], writeFiles: [], symbols: [], decisions: [], nonGoals: [], verification: [] },
+    });
+  }
+  return records;
+}
+
 /**
  * The SHA-256 of a file's exact bytes: the independent digest a frozen plan's
  * `plan.json.sha256` sidecar carries, recomputable by a reader without parsing
@@ -272,16 +376,18 @@ export function writeFrozenPlanRecord(outDir, record) {
  * validatePlanOutput applies, and recorded on plan.json verbatim.
  * `options.spec` carries the structured spec's path and content digest; when
  * given, both are recorded so a reader can pin the plan to the exact spec it
- * was planned from.
+ * was planned from. `options.humanSteps` carries the operator steps R16
+ * detected in the spec's requirements (`human-step.mjs`); recorded verbatim
+ * as the explicit stop the frozen plan carries for each of them.
  *
  * @param {JsonObject} plan
  * `options.facts` carries repo facts' measured durations; given, a
  * verification timeout that does not cover one is refused.
  *
- * @param {{outDir: string, provenance: PlanProvenanceInput, phases?: import("./template.mjs").PlanPhase[], spec?: PlanSpecIdentity, facts?: MeasuredFacts}} options
+ * @param {{outDir: string, provenance: PlanProvenanceInput, phases?: import("./template.mjs").PlanPhase[], spec?: PlanSpecIdentity, humanSteps?: PlanHumanStep[], facts?: MeasuredFacts}} options
  * @returns {FrozenPlan}
  */
-export function freezePlan(plan, { outDir, provenance, phases, spec, facts }) {
+export function freezePlan(plan, { outDir, provenance, phases, spec, humanSteps, facts }) {
   // Shape-checked before anything is written, so a malformed declaration
   // leaves the outDir exactly as it was — the same failure discipline as the
   // validateContract rollback below. A declaration in the nodeIds shape must
@@ -290,19 +396,23 @@ export function freezePlan(plan, { outDir, provenance, phases, spec, facts }) {
   // report rather than a reason to refuse the freeze.
   const phaseDeclarations = validatePlanPhases(phases, plannedNodeIdsOf(plan.nodes));
   const specIdentity = specIdentityOf(spec);
+  const humanStepList = humanStepsOf(humanSteps);
   mkdirSync(outDir, { recursive: true });
   const contractPath = join(outDir, "contract.json");
+  const requirementStampedNodes = phaseDeclarations ? stampPhaseRequirementIds(plan.nodes, phaseDeclarations) : plan.nodes;
+  const stampedNodes = humanStepList ? addHumanStepNodes(requirementStampedNodes, humanStepList) : requirementStampedNodes;
   const raw = /** @type {JsonObject} */ ({
     schemaVersion: PROTOCOL_SCHEMA_VERSION,
     contractVersion: CONTRACT_VERSION,
     ...plan,
     // Listed again, not mutated in place, so the caller's plan object keeps
     // the shape it was reviewed with.
-    ...(phaseDeclarations ? { nodes: stampPhaseRequirementIds(plan.nodes, phaseDeclarations) } : {}),
+    ...(phaseDeclarations || humanStepList ? { nodes: stampedNodes } : {}),
   });
   writeJsonAtomic(contractPath, raw);
   try {
     const validated = validateContract(raw, contractPath);
+    assertFilteredProofsNameTheirTest(validated);
     if (facts) assertTimeoutsCoverMeasured(validated, facts);
   } catch (error) {
     rmSync(contractPath, { force: true });
@@ -318,6 +428,7 @@ export function freezePlan(plan, { outDir, provenance, phases, spec, facts }) {
     // contract schema takes no extra field), so the traceability a reviewer
     // saw is readable straight off plan.json, nodeIds included.
     ...(phaseDeclarations === undefined ? {} : { phases: phaseDeclarations }),
+    ...(humanStepList === undefined ? {} : { humanSteps: humanStepList }),
     provenance: {
       packageVersion: packageVersion(),
       schemaVersion: /** @type {number} */ (raw.schemaVersion),