faberun 0.25.1 → 0.26.0

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),

package/src/plan/human-step.mjs

@@ -0,0 +1,38 @@
+/**
+ * R16: a requirement's `constraints` bullet can declare a step only the
+ * operator can perform (the planner and every worker run inside a sandbox
+ * that is never the operator's real environment). Detected here so
+ * freeze.mjs can carry it on the frozen plan as an explicit stop, and the
+ * Campaign Brief can list it among the human decisions. Pure text matching:
+ * no file I/O, no git, no model.
+ */
+
+/** @typedef {{requirementId: string, step: string, command: string}} HumanStep */
+
+/** The word a requirement's constraints must use to name the actor a worker cannot be. */
+const OPERATOR_KEYWORD = /\boperator\b/iu;
+
+/** The one command the declared step names, quoted the way the spec format already writes one (spec-format.md). */
+const COMMAND_FENCE = /`([^`]+)`/u;
+
+/**
+ * @param {import("./spec.mjs").SpecRequirement} requirement
+ * @returns {HumanStep|null}
+ */
+export function detectHumanStep(requirement) {
+  const text = requirement.constraints;
+  if (!text || !OPERATOR_KEYWORD.test(text)) return null;
+  const command = COMMAND_FENCE.exec(text);
+  if (!command) return null;
+  return { requirementId: requirement.id ?? requirement.title, step: text, command: command[1] };
+}
+
+/**
+ * @param {import("./spec.mjs").SpecRequirement[]} requirements
+ * @returns {HumanStep[]}
+ */
+export function collectHumanSteps(requirements) {
+  return requirements
+    .map((requirement) => detectHumanStep(requirement))
+    .filter((step) => step !== null);
+}