faberun 0.19.1 → 0.19.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faberun",
-  "version": "0.19.1",
+  "version": "0.19.2",
   "description": "Faberun is a development orchestration system that turns intent into verified software: harness- and model-agnostic, it keeps the intent, coordinates the work, verifies the result and decides what happens next.",
   "type": "module",
   "bin": {

package/skills/faberun/references/contract.md

@@ -46,8 +46,10 @@ typecheck`). Schema version is `3`.
 ```
 
 Every `definitionOfDone` item declares `id`, `text`, and how it is proven:
-`proof.kind` `command` (re-runs the command, capped at `min(timeoutSec, 120s)`)
-or `path` (a file must exist), or `judgment: true` for the judge. `proof: {
+`proof.kind` `command` (re-runs the command through a shell, bounded by the
+node's own `timeoutSec`; quote a flag value containing spaces, which
+`verification`'s argv does not need and a shell splits) or `path` (a file must
+exist), or `judgment: true` for the judge. `proof: {
 kind: "verification", ref: <index> }` reuses a `verification` entry's already
 recorded result by position instead of re-running it — never by comparing argv
 strings, since a joined argv loses shell semantics. A schema-1 string item is
@@ -95,8 +97,11 @@ discovery packet has empty `writeFiles`; with an empty `readFiles` it may
 read the repository read-only to produce an execution packet — the one
 exception to closed scope — otherwise it is closed to the listed files. Each
 `verification` entry is `{argv, cwd?, timeoutSec? (default 120, max 600),
-repeat? (default 1, max 8), env?}` — at most 32 commands, 64 argv items, 32
-KiB argv bytes per command. `env` declares variable *names* only; values
+repeat? (default 1, max 8), env?, requirementId?}` — at most 32 commands, 64
+argv items, 32 KiB argv bytes per command. `requirementId` names the spec
+requirement this command proves, changing nothing about how it runs: it is
+what lets `contract validate` report two copies of one proof that have stopped
+agreeing. `env` declares variable *names* only; values
 never travel in the packet. `prompt`/`promptFile` are
 rejected; a node has `taskPacket` or `taskPacketFile`, never both. Measure a
 candidate command's real duration before naming it in `verification` or a
@@ -289,7 +294,14 @@ only for a harness declaring `streamsOutput` (true for `codex`, `claude`,
 others fall back to `timeoutSec` alone.
 `timeoutSec` (default 2400s) caps one invocation and may be overridden per
 node; a node is bounded by `(1 + maxRevisions) × 2 × timeoutSec`. Both clocks
-are monotonic and pause with host suspend. `maxParallel` above 1 dispatches
+are monotonic and pause with host suspend.
+`maxTurns` (default 150) bounds something else: the *provider requests* one
+attempt may make, overridable per node. Reaching it ends the attempt with
+`errorCode: turn_limit`, sealed then retried once, the spend already spent. It
+bites the nodes that read much and write little — review, synthesis — so raise
+it there; raising `timeoutSec` does not help. The controller says so once at
+80%, and `usage.jsonl` records each invocation's `session.requests`.
+`maxParallel` above 1 dispatches
 every dependency-ready node concurrently, each into its own attempt
 worktree; integration stays serialized. Nodes of one phase need no edge
 between them: a continuation a live invocation already claims is never

package/src/campaign/index.mjs

@@ -132,9 +132,14 @@ export function closeCampaign(campaignPath, { at = new Date().toISOString(), eve
   requireTimestamp(at, "at");
   const campaign = readCampaign(campaignPath);
   if (campaign.status === "closed") throw new Error(`campaign already closed: ${campaign.id}`);
-  if (!readJournalForDedupe(campaignPath).some((entry) => entry.type === "retrospective")) {
+  const journal = readJournalForDedupe(campaignPath);
+  if (!journal.some((entry) => entry.type === "retrospective")) {
     throw new Error(`campaign ${campaign.id} has no recorded retrospective; record one with note --kind retrospective before close`);
   }
+  const unacknowledged = unacknowledgedAdvisories(campaignPath, campaign, journal);
+  if (unacknowledged.length) {
+    throw new Error(`campaign ${campaign.id} has judge findings no note has answered: ${unacknowledged.join("; ")}. Read them with \`faberun findings <run-dir>\`, then name the node in a note (\`campaign note ${campaign.id} --kind outcome --run-id <run-id> --text "...<node>..."\`) before close`);
+  }
   const repoRoot = campaignRepoRoot(campaignPath);
   const ledgerFiles = preserveCampaignLedger(campaignPath, repoRoot);
   // The closure travels on the record itself, computed in one deterministic
@@ -147,6 +152,56 @@ export function closeCampaign(campaignPath, { at = new Date().toISOString(), eve
   return { path: campaignPath, campaign: closed, ledgerFiles };
 }
 
+/**
+ * Judge findings on nodes the gate accepted, which no journal note names.
+ *
+ * A gate that accepts a node whose findings sit below `failOn` is correct and
+ * documented. What was wrong is that the campaign could then be closed with
+ * the finding never read by anyone: measured 2026-09-21, a synthesis node's
+ * `gate.verdict` was `fail` with a real finding, `STATUS` said `passed`, and
+ * the campaign's own retrospective recorded that every gate passed first
+ * time. A close is the last moment the claim can still be corrected.
+ *
+ * Acknowledgement is a note that names the node id. The node id is the
+ * identifier the run, the contract and the findings output all already use,
+ * so matching on it asks the operator for nothing new; matching on a
+ * finding's prose would be matching on text the judge wrote, which is not a
+ * stable name.
+ *
+ * @param {string} campaignPath
+ * @param {Campaign} campaign
+ * @param {{type: string, text?: unknown}[]} journal
+ * @returns {string[]} one `runId/nodeId (N findings, maxSeverity)` per unanswered node, sorted
+ */
+function unacknowledgedAdvisories(campaignPath, campaign, journal) {
+  const runsDir = resolve(campaignPath, "..", "..");
+  const noteText = journal
+    .filter((entry) => typeof entry.text === "string")
+    .map((entry) => /** @type {string} */ (entry.text))
+    .join("\n");
+  /** @type {string[]} */
+  const pending = [];
+  for (const runId of [...campaign.linkedRunIds].sort()) {
+    const contract = readRunJson(join(runsDir, runId, "contract.json"));
+    const nodes = contract !== null && Array.isArray(contract.nodes) ? /** @type {JsonObject[]} */ (contract.nodes) : [];
+    for (const node of nodes) {
+      const nodeId = typeof node.id === "string" ? node.id : "";
+      if (!nodeId) continue;
+      const snapshot = readRunJson(join(runsDir, runId, "nodes", `${nodeId}.json`));
+      if (snapshot === null) continue;
+      // Only an accepted node: on a rejected one the findings are the
+      // rejection itself, and the run already refuses to read as finished.
+      if (snapshot.status !== "done" && snapshot.status !== "no-op") continue;
+      const gate = /** @type {JsonObject|null|undefined} */ (snapshot.gate);
+      const findings = gate && Array.isArray(gate.findings) ? gate.findings : [];
+      if (findings.length === 0) continue;
+      if (noteText.includes(nodeId)) continue;
+      pending.push(`${runId}/${nodeId} (${findings.length} ${findings.length === 1 ? "finding" : "findings"}, ${typeof gate?.maxSeverity === "string" ? gate.maxSeverity : "unknown"})`);
+    }
+  }
+  return pending.sort();
+}
+
 /**
  * The requirement closure a close records: one entry per requirement id the
  * linked runs' contracts declared, correlated only by the identifiers the runs

package/src/cli/plan.mjs

@@ -4,8 +4,8 @@
  * contested. This file only owns the wire — `src/plan/pipeline.mjs` owns the
  * sequencing and every decision the pipeline makes.
  */
-import { readFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
 import { detachArgv, detachSelf, waitForBootstrap } from "./launch.mjs";
 import { classifyRunProgress } from "../campaign/chain.mjs";
 import { runProgress } from "../engine/supervise.mjs";
@@ -15,11 +15,22 @@ import { validateFinalVerification, validateSharedVerification } from "../contra
 import { colorLevel, statusToken } from "./brand.mjs";
 import { delay } from "../util.mjs";
 import { runPlanningPipeline } from "../plan/pipeline.mjs";
-import { runDirectory } from "../run/paths.mjs";
+import { campaignTree, runDirectory } from "../run/paths.mjs";
 
 /** How often a foreground `plan` polls a launched stage's run directory. */
 const DEFAULT_POLL_MS = 1_000;
 
+/**
+ * How long a `--detach` launcher stays to see whether the planning process it
+ * started is actually up. Long enough to cover the bootstrap work that fails
+ * synchronously -- spec read, strict validation, catalogue load, the runtime
+ * ask -- and short enough that a launcher is not a supervisor: past this
+ * window, a planning run that dies is a running campaign's problem and leaves
+ * its evidence in the run directory, not here.
+ */
+const PLAN_BOOTSTRAP_WINDOW_MS = 5_000;
+const PLAN_BOOTSTRAP_POLL_MS = 100;
+
 /**
  * `--runtime-defaults worker=<id>,judge=<id>`, either key optional, comma
  * separated. Absent entirely, the pipeline falls through to plain
@@ -114,7 +125,7 @@ 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, detach?: boolean, json?: boolean}} values
+ * @param {{campaign?: string, phase?: string, "review-rounds"?: string, "approve-below"?: string, "runtime-defaults"?: string, runtimes?: string, verification?: string, package?: string, detach?: boolean, json?: boolean}} values
  * @returns {Promise<void>}
  */
 export async function planCli(target, values) {
@@ -131,6 +142,7 @@ export async function planCli(target, values) {
   const verification = typeof values.verification === "string" && values.verification
     ? loadVerificationSuites(values.verification)
     : {};
+  const packageMode = packageModeOf(values.package);
 
   if (values.detach === true) {
     const argv = ["plan", specPath, "--campaign", campaignId, "--phase", phase, "--review-rounds", String(reviewRounds)];
@@ -138,35 +150,63 @@ export async function planCli(target, values) {
     if (values["runtime-defaults"] !== undefined) argv.push("--runtime-defaults", values["runtime-defaults"]);
     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);
+    const failurePath = planBootstrapFailurePath(process.cwd(), campaignId, phase);
+    mkdirSync(dirname(failurePath), { recursive: true });
+    rmSync(failurePath, { force: true });
     const child = detachArgv(argv);
     if (child.pid === undefined) throw new Error("detached plan has no pid");
+    // The child's stdio is discarded (detachArgv), so a planning run that dies
+    // during bootstrap used to take its own reason with it while the launcher
+    // had already printed a pid and exited 0. Measured 2026-09-21 on macOS and
+    // Linux the same day: a run died after collecting repo facts and the stderr
+    // went with the closed connection. Waiting out a bounded window is the
+    // whole check -- a controller still alive past it is up, and one that is
+    // not has written why.
+    const failure = await watchPlanBootstrap(child, failurePath);
+    if (failure) {
+      process.stderr.write(`[plan] bootstrap failed · ${failure.error}\n[plan] recorded at ${failurePath}\n`);
+      process.exitCode = 1;
+      return;
+    }
     process.stdout.write(`[plan] detached · pid ${child.pid} · ${specPath}\n`);
     return;
   }
 
-  const result = await runPlanningPipeline({
-    specPath,
-    campaignId,
-    phase,
-    reviewRounds,
-    approveBelow,
-    runtimeDefaults,
-    runtimes,
-    verification,
-    launch: async (contractPath, contract) => {
-      const child = detachSelf("run", contractPath);
-      if (child.pid === undefined) throw new Error("detached planning run has no pid");
-      await waitForBootstrap(runDirectory(contract.cwd, contract.id), child.pid, child);
-    },
-    wait: async (runDir) => {
-      for (;;) {
-        const progress = runProgress(runDir);
-        const classification = classifyRunProgress(progress);
-        if (classification !== "unfinished" && classification !== "waiting") return progress;
-        await delay(DEFAULT_POLL_MS);
-      }
-    },
-  });
+  // A detached child arrives here with its stdio already discarded, so what
+  // it throws reaches nobody unless it is written down first. The record is
+  // written on every path, detached or not: a foreground failure that also
+  // leaves the file costs nothing and reads the same.
+  let result;
+  try {
+    result = await runPlanningPipeline({
+      specPath,
+      campaignId,
+      phase,
+      reviewRounds,
+      approveBelow,
+      runtimeDefaults,
+      runtimes,
+      verification,
+      packageMode,
+      launch: async (contractPath, contract) => {
+        const child = detachSelf("run", contractPath);
+        if (child.pid === undefined) throw new Error("detached planning run has no pid");
+        await waitForBootstrap(runDirectory(contract.cwd, contract.id), child.pid, child);
+      },
+      wait: async (runDir) => {
+        for (;;) {
+          const progress = runProgress(runDir);
+          const classification = classifyRunProgress(progress);
+          if (classification !== "unfinished" && classification !== "waiting") return progress;
+          await delay(DEFAULT_POLL_MS);
+        }
+      },
+    });
+  } catch (error) {
+    writePlanBootstrapFailure(process.cwd(), campaignId, phase, error instanceof Error ? error : new Error(String(error)));
+    throw error;
+  }
 
   if (values.json === true) {
     process.stdout.write(`${JSON.stringify(result)}\n`);
@@ -180,3 +220,100 @@ export async function planCli(target, values) {
   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`);
 }
+
+/**
+ * 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
+ * tree, and it is derived from campaign and phase alone -- the launcher and
+ * the child compute the same path without either having to parse the spec.
+ *
+ * @param {string} cwd
+ * @param {string} campaignId
+ * @param {string} phase
+ * @returns {string}
+ */
+export function planBootstrapFailurePath(cwd, campaignId, phase) {
+  return join(campaignTree(cwd, campaignId), "plans", phase, "bootstrap-failure.json");
+}
+
+/**
+ * Record a detached planning run's bootstrap failure where its launcher can
+ * read it. Best effort: a failure to write this must never replace the
+ * failure it was describing.
+ *
+ * @param {string} cwd
+ * @param {string} campaignId
+ * @param {string} phase
+ * @param {Error} error
+ * @returns {void}
+ */
+export function writePlanBootstrapFailure(cwd, campaignId, phase, error) {
+  try {
+    const path = planBootstrapFailurePath(cwd, campaignId, phase);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify({ at: new Date().toISOString(), pid: process.pid, campaignId, phase, error: error.message }, null, 2)}\n`);
+  } catch {
+    // Nothing left to do: the caller is already reporting the real failure.
+  }
+}
+
+/**
+ * Watch a freshly detached planning child through its bootstrap window.
+ *
+ * Returns the recorded failure when the child died inside the window, and
+ * null when it is still running at the end of it. A child that exits zero
+ * inside the window also reads as no failure: a planning run can legitimately
+ * be that fast only by refusing early, and it will have written its own
+ * record if it refused.
+ *
+ * @param {import("node:child_process").ChildProcess} child
+ * @param {string} failurePath
+ * @param {{windowMs?: number, pollMs?: number}} [options]
+ * @returns {Promise<{error: string}|null>}
+ */
+export async function watchPlanBootstrap(child, failurePath, { windowMs = PLAN_BOOTSTRAP_WINDOW_MS, pollMs = PLAN_BOOTSTRAP_POLL_MS } = {}) {
+  let exitCode = /** @type {number|null|undefined} */ (undefined);
+  let exited = false;
+  child.once("exit", (code) => { exited = true; exitCode = code; });
+  const deadline = Date.now() + windowMs;
+  while (Date.now() < deadline) {
+    // Typed checks, not `!== null`: a child object that never carried the
+    // property at all would otherwise read as one that has already exited.
+    if (exited || typeof child.exitCode === "number" || typeof child.signalCode === "string") {
+      const recorded = readPlanBootstrapFailure(failurePath);
+      if (recorded) return recorded;
+      const code = typeof exitCode === "number" ? exitCode : child.exitCode;
+      if (typeof code === "number" && code !== 0) return { error: `the detached planning process exited ${code} without recording a reason` };
+      const signal = child.signalCode;
+      if (typeof signal === "string") return { error: `the detached planning process was killed by ${signal} without recording a reason` };
+      return null;
+    }
+    await delay(pollMs);
+  }
+  return null;
+}
+
+/** @param {string} failurePath @returns {{error: string}|null} */
+function readPlanBootstrapFailure(failurePath) {
+  try {
+    const record = JSON.parse(readFileSync(failurePath, "utf8"));
+    return typeof record?.error === "string" ? { error: record.error } : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * `--package implementation|exploratory`. Implementation is the default and
+ * the only mode there was: nodes sized by their write set. Exploratory sizes
+ * by what a node reads, accepts a one-file write set as the normal shape of a
+ * finding, and reports a node whose read surface dwarfs its siblings'.
+ *
+ * @param {unknown} value
+ * @returns {import("../plan/sizing.mjs").PackageMode}
+ */
+export function packageModeOf(value) {
+  if (value === undefined) return "implementation";
+  if (value === "implementation" || value === "exploratory") return value;
+  throw new Error(`--package must be implementation or exploratory: ${String(value)}`);
+}

package/src/cli/spec.mjs

@@ -14,7 +14,7 @@ import { validateSpec } from "../plan/spec.mjs";
 /** Flags are scoped to the operation that declares them; all others are rejected. */
 /** @type {Record<string, import("node:util").ParseArgsOptionsConfig>} */
 const OPERATION_OPTIONS = {
-  validate: { "strict-traceability": { type: "boolean" }, json: { type: "boolean" } },
+  validate: { "strict-traceability": { type: "boolean" }, "run-proofs": { type: "boolean" }, json: { type: "boolean" } },
   scaffold: { id: { type: "string" } },
 };
 
@@ -63,9 +63,13 @@ export function specCli(args) {
   }
   const target = parsed.positionals[0];
   if (!target || parsed.positionals.length > 1) return usage();
-  const values = /** @type {{"strict-traceability"?: boolean, json?: boolean, id?: string}} */ (parsed.values);
+  const values = /** @type {{"strict-traceability"?: boolean, "run-proofs"?: boolean, json?: boolean, id?: string}} */ (parsed.values);
   if (operation === "validate") {
-    validateSpecFile(resolve(target), { strict: values["strict-traceability"] === true, json: values.json === true });
+    validateSpecFile(resolve(target), {
+      strict: values["strict-traceability"] === true,
+      runProofs: values["run-proofs"] === true,
+      json: values.json === true,
+    });
     return;
   }
   try {
@@ -80,12 +84,18 @@ export function specCli(args) {
  * Validate a spec file and print its class, its overall verdict, and one
  * line per finding. Exits `1` when the verdict is not `ok`.
  *
+ * `runProofs` is the only operation here that spawns anything: it runs each
+ * requirement's declared proof instead of only checking that one is written
+ * down. It is opt-in because running a repository's proofs costs real time,
+ * and default-off keeps `spec validate` the deterministic, side-effect-free
+ * read it has always been.
+ *
  * @param {string} path
- * @param {{strict: boolean, json: boolean}} options
+ * @param {{strict: boolean, json: boolean, runProofs?: boolean}} options
  * @returns {SpecValidation}
  */
-export function validateSpecFile(path, { strict, json }) {
-  const result = validateSpec(readFileSync(path, "utf8"), { cwd: process.cwd(), strict });
+export function validateSpecFile(path, { strict, json, runProofs = false }) {
+  const result = validateSpec(readFileSync(path, "utf8"), { cwd: process.cwd(), strict, runProofs });
   if (json) {
     process.stdout.write(`${JSON.stringify(result)}\n`);
   } else {
@@ -112,7 +122,7 @@ export function scaffoldSpec(path, id) {
 
 /** @returns {void} */
 function usage() {
-  process.stderr.write("usage: faberun spec <validate|scaffold> <path> [--strict-traceability] [--json] [--id <value>]\n");
+  process.stderr.write("usage: faberun spec <validate|scaffold> <path> [--strict-traceability] [--run-proofs] [--json] [--id <value>]\n");
   process.exitCode = 2;
 }
 

package/src/cli.mjs

@@ -123,6 +123,7 @@ export const COMMAND_OPTIONS = {
     "runtime-defaults": { type: "string" },
     runtimes: { type: "string" },
     verification: { type: "string" },
+    package: { type: "string" },
     detach: { type: "boolean" },
     json: { type: "boolean" },
   },

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

@@ -95,3 +95,53 @@ function validateVerificationRef(value, label, options) {
   return String(index);
 }
 
+/**
+ * A `kind: "command"` proof's `ref` runs through a shell (`judge-gate.mjs`'s
+ * `proveCommand`), while a task packet's `verification` entries run as argv
+ * arrays -- the opposite quoting convention for the same author intent.
+ * Measured 2026-09-22: six DoD refs on one campaign wrote
+ * `--test-name-pattern=a b c` the way an argv array would take it, the shell
+ * split it into three words, and the gate rejected work whose identical
+ * command had just passed as verification. Nothing warned the author, because
+ * a shell that receives extra bare words after an unquoted flag value does not
+ * itself know they were meant to be one argument.
+ *
+ * This flags the same shape rather than every proof: a node:test filter flag
+ * (the flags `declaredTestFilters` in judge-gate.mjs recognizes) whose
+ * unquoted value is immediately followed by bare words is the pattern the
+ * incident measured, and it is precise enough that a legitimate `ref` rarely
+ * has trailing bare words right after such a flag by accident.
+ *
+ * @param {DefinitionOfDoneItem[]} items
+ * @param {number} index
+ * @returns {string[]}
+ */
+export function unquotedFilterValueWarnings(items, index) {
+  /** @type {string[]} */
+  const warnings = [];
+  items.forEach((item, itemIndex) => {
+    if (item.proof?.kind !== "command") return;
+    const tokens = item.proof.ref.split(/\s+/u).filter(Boolean);
+    for (const flag of TEST_FILTER_FLAGS) {
+      for (let position = 0; position < tokens.length; position++) {
+        const prefix = `${flag}=`;
+        if (!tokens[position].startsWith(prefix)) continue;
+        const value = tokens[position].slice(prefix.length);
+        if (/^['"]/u.test(value)) continue;
+        let end = position + 1;
+        while (end < tokens.length && !tokens[end].startsWith("-")) end++;
+        if (end === position + 1) continue;
+        const spilled = [value, ...tokens.slice(position + 1, end)].join(" ");
+        warnings.push(
+          `nodes[${index}] (definitionOfDone[${itemIndex}]): proof.ref's ${flag} value "${spilled}" is unquoted; ` +
+          `kind: "command" runs through a shell, unlike taskPacket.verification's argv, so the space splits it into extra words -- quote it as ${flag}="${spilled}"`,
+        );
+      }
+    }
+  });
+  return warnings;
+}
+
+/** The node:test filter flags a `kind: "command"` proof's shell can split on an unquoted value. */
+const TEST_FILTER_FLAGS = ["--test-name-pattern", "--test-skip-pattern"];
+

package/src/contract/final-verification.mjs

@@ -60,6 +60,27 @@ export function sharedVerificationCommands(contract) {
   return contract.sharedVerification ?? [];
 }
 
+/**
+ * The timeout a Definition of Done `command` proof is spawned with. It used
+ * to be capped at a hardcoded 120s regardless of what the node's own attempt
+ * was given, so a contract that raised `timeoutSec` to run a slow command as
+ * `taskPacket.verification` still had the identical command fail its DoD
+ * proof on the same run: measured 2026-09-22, six proofs rejected work whose
+ * argv had just passed with a `timeoutSec` well past 120s. A command proof
+ * gets the same budget the node's own attempt has, because that is the
+ * budget the author already reasoned about; nothing here invents a second
+ * number for the gate to disagree with. Shared by `dispatch.mjs` (the actual
+ * spawn) and `scheduler.mjs` (the freeze-detection budget that must not judge
+ * a node frozen before its own gate's timeout has had a chance to fire).
+ *
+ * @param {{timeoutSec?: number}} node
+ * @param {{timeoutSec?: number}} contract
+ * @returns {number}
+ */
+export function gateProofTimeoutMs(node, contract) {
+  return Math.max(1_000, (node.timeoutSec ?? contract.timeoutSec ?? 60) * 1_000);
+}
+
 /**
  * Whether no other node in the contract depends on this one. `finalVerification`
  * is a candidate to run on a phase-terminal node only; a node with a dependant

package/src/contract/index.mjs

@@ -3,9 +3,9 @@ import { readFileSync, statSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { loadTaskPacket, renderWorkerPrompt } from "./task-packet.mjs";
 import { RESERVED_ARTICLES } from "./articles.mjs";
-import { validateDefinitionOfDone } from "./definition-of-done.mjs";
+import { unquotedFilterValueWarnings, validateDefinitionOfDone } from "./definition-of-done.mjs";
 import { validateFinalVerification, validateSharedVerification } from "./final-verification.mjs";
-import { VERIFICATION_LIMITS } from "./verification.mjs";
+import { VERIFICATION_LIMITS, requirementProofWarnings } from "./verification.mjs";
 import {
   validateCapabilityRequirements,
 } from "../harnesses/index.mjs";
@@ -374,12 +374,24 @@ export function validateContract(raw, contractPath, options = {}) {
   const sharedVerification = validateSharedVerification(raw.sharedVerification, "contract.sharedVerification");
   const contractCommands = [...finalVerification ?? [], ...sharedVerification ?? []].map((command) => command.argv.join(" "));
   const contractWrites = new Set(nodes.flatMap((node) => node.taskPacket.writeFiles ?? []));
-  const warnings = nodes.flatMap((node, index) => [
-    ...commandCoverageWarnings(node, index),
-    ...(persisted ? [] : mirrorCoverageWarnings(node, index, cwd, contractCommands, contractWrites)),
-    ...(persisted ? [] : unsnapshottedWriteWarnings(node, index, cwd)),
-    ...(persisted ? [] : writeFileLineBudgetWarnings(node, index, cwd)),
-  ]);
+  const warnings = [
+    ...nodes.flatMap((node, index) => [
+      ...commandCoverageWarnings(node, index),
+      ...unquotedFilterValueWarnings(node.definitionOfDone ?? [], index),
+      ...(persisted ? [] : mirrorCoverageWarnings(node, index, cwd, contractCommands, contractWrites)),
+      ...(persisted ? [] : unsnapshottedWriteWarnings(node, index, cwd)),
+      ...(persisted ? [] : writeFileLineBudgetWarnings(node, index, cwd)),
+    ]),
+    // Cross-node by construction: a requirement proven in two nodes is only
+    // visible when every node's commands are read together, which is the
+    // whole point -- one copy repaired and six left behind is what a per-node
+    // read cannot see.
+    ...requirementProofWarnings([
+      ...nodes.map((node, index) => ({ id: `nodes[${index}] (${node.id})`, requirementIds: node.requirementIds, commands: node.taskPacket.verification ?? [] })),
+      { id: "contract.sharedVerification", commands: sharedVerification ?? [] },
+      { id: "contract.finalVerification", commands: finalVerification ?? [] },
+    ]),
+  ];
   const contract = /** @type {ValidatedContract} */ ({
     ...raw,
     schemaVersion: /** @type {number} */ (raw.schemaVersion),

package/src/contract/verification.mjs

@@ -42,7 +42,14 @@ export const MUTATION_TIERS = Object.freeze({
 /**
  * One declared deterministic check: an argv command run by the controller.
  *
- * @typedef {{argv: string[], cwd?: string, timeoutSec?: number, repeat?: number, env?: string[], mutation?: {tier: MutationTier}}} VerificationCommand
+ * `requirementId` names the spec requirement this command is the proof of. It
+ * changes nothing about how the command runs; it is what makes a duplicated
+ * proof visible. Measured 2026-09-22: one broken command lived in a spec's R3,
+ * in its R4 and in seven nodes' verification, and the repair reached one of
+ * them — nothing could tell that the other copies had stopped agreeing,
+ * because nothing recorded that they were copies of one claim.
+ *
+ * @typedef {{argv: string[], cwd?: string, timeoutSec?: number, repeat?: number, env?: string[], mutation?: {tier: MutationTier}, requirementId?: string}} VerificationCommand
  */
 
 /**
@@ -122,7 +129,7 @@ export function validateVerificationCommands(commands, label = "verification") {
 function validateVerificationCommand(command, label = "verification command") {
   if (!command || typeof command !== "object" || Array.isArray(command)) throw new TypeError(`${label} must be an argv command object`);
   const record = /** @type {Record<string, unknown>} */ (command);
-  const allowed = new Set(["argv", "cwd", "timeoutSec", "repeat", "env", "mutation"]);
+  const allowed = new Set(["argv", "cwd", "timeoutSec", "repeat", "env", "mutation", "requirementId"]);
   for (const key of Object.keys(record)) if (!allowed.has(key)) throw new TypeError(`${label} has unexpected field ${key}`);
   if (!Array.isArray(record.argv) || record.argv.length === 0 || record.argv.length > 64 || record.argv.some((item) => typeof item !== "string" || !item.trim() || Buffer.byteLength(item, "utf8") > 8 * 1024)) {
     throw new TypeError(`${label}.argv must be a non-empty array of strings`);
@@ -157,10 +164,18 @@ function validateVerificationCommand(command, label = "verification command") {
     }
     mutation = { tier: /** @type {MutationTier} */ (mutationRecord.tier) };
   }
+  // Bounded exactly like the node-level `requirementIds` it must match against
+  // (at most 128 bytes), so the two sides of the claim cannot accept different
+  // ids.
+  if (record.requirementId !== undefined
+    && (typeof record.requirementId !== "string" || !record.requirementId.trim() || Buffer.byteLength(record.requirementId, "utf8") > 128)) {
+    throw new TypeError(`${label}.requirementId must be a requirement id of at most 128 bytes`);
+  }
   /** @type {VerificationCommand} */
   const normalized = { argv: [.../** @type {string[]} */ (record.argv)], timeoutSec, repeat, env: [.../** @type {string[]} */ (env)] };
   if (record.cwd !== undefined) normalized.cwd = /** @type {string} */ (record.cwd);
   if (mutation !== undefined) normalized.mutation = mutation;
+  if (record.requirementId !== undefined) normalized.requirementId = /** @type {string} */ (record.requirementId);
   return normalized;
 }
 
@@ -199,3 +214,49 @@ export function compactVerification(result) {
   return { passed: Boolean(result?.passed), commands };
 }
 
+
+/**
+ * One proof, one source. A command that declares `requirementId` says it is
+ * the proof of that requirement; this reports the two ways such a claim can
+ * be false.
+ *
+ * A claim the node does not carry is a mislabel: the node's own
+ * `requirementIds` are what the phase assigned it, and a command proving
+ * something outside them is either the wrong id or the wrong node.
+ *
+ * Copies that stopped agreeing are the measured one. 2026-09-22: a broken
+ * command lived in a spec's R3, its R4, and seven nodes' verification, and
+ * the repair reached one copy. Nothing could see that the others had drifted,
+ * because nothing recorded that they were copies of a single claim. Argv is
+ * compared against argv, never a joined string against a shell command: a
+ * joined argv loses argument boundaries, which is the same reason a
+ * `verification` proof references an index instead of comparing text.
+ *
+ * @param {Array<{id: string, requirementIds?: string[], commands: VerificationCommand[]}>} owners
+ * @returns {string[]}
+ */
+export function requirementProofWarnings(owners) {
+  /** @type {string[]} */
+  const warnings = [];
+  /** @type {Map<string, Array<{owner: string, position: number, argv: string[]}>>} */
+  const claims = new Map();
+  for (const owner of owners) {
+    owner.commands.forEach((command, position) => {
+      const requirementId = command.requirementId;
+      if (requirementId === undefined) return;
+      if (owner.requirementIds !== undefined && !owner.requirementIds.includes(requirementId)) {
+        warnings.push(`${owner.id}: verification[${position}] declares requirementId "${requirementId}", which this node does not carry in requirementIds`);
+      }
+      const claimed = claims.get(requirementId) ?? [];
+      claimed.push({ owner: owner.id, position, argv: command.argv });
+      claims.set(requirementId, claimed);
+    });
+  }
+  for (const [requirementId, claimed] of claims) {
+    const distinct = new Map(claimed.map((claim) => [JSON.stringify(claim.argv), claim]));
+    if (distinct.size < 2) continue;
+    const listed = [...distinct.values()].map((claim) => `${claim.owner}: verification[${claim.position}] runs ${JSON.stringify(claim.argv)}`).join("; ");
+    warnings.push(`requirementId "${requirementId}" is proven by commands that no longer agree: ${listed}`);
+  }
+  return warnings;
+}