faberun 0.23.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faberun",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "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": {
@@ -24,7 +24,7 @@
     "node": ">=22"
   },
   "scripts": {
-    "check": "node -e \"const{readdirSync}=require('node:fs');const{spawnSync}=require('node:child_process');const roots=['bin','.claude/hooks','src','evals','test'];const files=roots.flatMap(r=>readdirSync(r,{recursive:true}).map(String).filter(p=>p.endsWith('.mjs')).map(p=>r+'/'+p));for(const f of files)if(spawnSync(process.execPath,['--check',f],{stdio:'inherit'}).status!==0)process.exit(1);console.log(files.length+' files checked')\"",
+    "check": "node -e \"const{readdirSync}=require('node:fs');const{spawnSync}=require('node:child_process');const roots=['bin','.claude/hooks','src','evals','test'];const files=roots.flatMap(r=>readdirSync(r,{recursive:true}).map(String).filter(p=>p.endsWith('.mjs')&&!p.includes('.runs')).map(p=>r+'/'+p));for(const f of files)if(spawnSync(process.execPath,['--check',f],{stdio:'inherit'}).status!==0)process.exit(1);console.log(files.length+' files checked')\"",
     "typecheck": "tsc",
     "check:campaign-brief-render": "node src/report/campaign-brief-html.mjs",
     "test": "node --test --import ./test/scoped-home.mjs --import ./test/git-env.mjs --import ./test/setup.mjs test/*.test.mjs test/*/*.test.mjs",

package/src/campaign/chain.mjs

@@ -32,7 +32,7 @@ import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { hostname, tmpdir } from "node:os";
 import { dirname, join, relative, resolve } from "node:path";
-import { assertContractManifestIntact, parkCampaign, promoteRunInCampaign } from "./index.mjs";
+import { assertContractManifestIntact, parkCampaign, promoteRunInCampaign, recordOperatorCommand } from "./index.mjs";
 import { readCampaign } from "./record.mjs";
 import { validateContract } from "../contract/index.mjs";
 import { defaultControllerIdentity, storedContractDigest, verifyControllerIdentity } from "../engine/run-identity.mjs";
@@ -386,6 +386,7 @@ function storedContractId(stored) {
  *   maxTicks?: number,
  *   coordination?: boolean,
  *   controllerIdentity?: ControllerIdentity,
+ *   refreshController?: boolean,
  *   launch?: (contractPath: string, context: {baseRef: string|undefined, controllerIdentity: ControllerIdentity, runDir: string, contract: ValidatedContract}) => Promise<void>|void,
  *   validate?: (entry: CampaignContract, context: {repo: string|undefined, baseRef: string|undefined, contractPath: string}) => ValidatedContract,
  *   progress?: (runDir: string) => RunProgress,
@@ -551,13 +552,25 @@ export async function driveCampaignChain(campaignPath, options = {}) {
       try {
         verifyControllerIdentity(controllerIdentity);
       } catch (error) {
-        return park({
-          code: errorCode(error) ?? "controller_snapshot_changed",
-          message: errorMessage(error),
-          contractPath: entry.path,
-          contractId: id,
-          runId: id,
-        });
+        // A campaign whose contracts change faberun's own src/ changes the
+        // controller between launches (measured on evidence-you-can-recompute).
+        // Adopting the new snapshot is the operator's call, so it happens only
+        // under --refresh-controller and is recorded as an operator command.
+        if (options.refreshController === true && errorCode(error) === "controller_snapshot_changed") {
+          controllerIdentity = defaultControllerIdentity();
+          recordOperatorCommand(campaignPath, "campaign supervise --refresh-controller");
+          emit(`[campaign] controller snapshot refreshed · ${controllerIdentity.sha.slice(0, 12)}`);
+        } else {
+          return park({
+            code: errorCode(error) ?? "controller_snapshot_changed",
+            message: errorCode(error) === "controller_snapshot_changed"
+              ? `${errorMessage(error)}: \`faberun campaign supervise ${readCampaign(campaignPath).id} --refresh-controller\``
+              : errorMessage(error),
+            contractPath: entry.path,
+            contractId: id,
+            runId: id,
+          });
+        }
       }
       try {
         await launch(entry.path, { baseRef, controllerIdentity, runDir, contract });

package/src/campaign/index.mjs

@@ -401,10 +401,22 @@ export function addContractToCampaign(campaignPath, contractPath, { at = new Dat
     : campaign.contracts.map((existing, index) => (index === existingIndex ? entry : existing));
   const updated = /** @type {Campaign} */ ({ ...campaign, contracts, updatedAt: at });
   writeJsonAtomic(join(campaignPath, CAMPAIGN_FILE), updated);
-  appendJournal(campaignPath, { type: "operator.command", eventId: randomUUID(), at, command: "campaign add-contract" });
+  recordOperatorCommand(campaignPath, "campaign add-contract", at);
   return { campaign: updated, added: true };
 }
 
+/**
+ * The one writer of `operator.command` (docs/FIELD-OWNERSHIP.md): an operator
+ * command that changed campaign state, which `humanTouches` counts.
+ *
+ * @param {string} campaignPath
+ * @param {string} command
+ * @param {string} [at]
+ */
+export function recordOperatorCommand(campaignPath, command, at = new Date().toISOString()) {
+  appendJournal(campaignPath, { type: "operator.command", eventId: randomUUID(), at, command });
+}
+
 /**
  * Replace a manifest entry -- matched by its current, recorded path -- with a
  * freshly authored contract. Re-authoring a phase after a blocked or failed

package/src/campaign/metrics.mjs

@@ -51,6 +51,7 @@ const UNKNOWN_COST_PROVENANCE = "unknown";
 /** @typedef {"down"|"up"|"informative"} Direction */
 /** @typedef {{value: number|null, direction: Direction, count: number, numerator?: number, denominator?: number, excludedRunIds?: string[], missingSources?: string[]}} Indicator */
 /** @typedef {Indicator & {unknownCount: number, unknownCountByReason: Record<string, number>, unknownFractionByReason: Record<string, number>}} CostIndicator */
+/** @typedef {Indicator & {unknownCount: number}} JudgeCostShareIndicator */
 /** @typedef {{value: Record<string, number>|null, direction: Direction, count: number, numerator?: Record<string, number>, denominator?: Record<string, number>, excludedRunIds?: string[], missingSources?: string[]}} GroupedIndicator */
 /** @typedef {{atMs: number, index: number, event: JsonObject}} RunEvent */
 /** @typedef {{runId: string, id: string, status: string, attempt?: number|null, revisions?: number|null, review?: string|null}} RunNode */
@@ -79,6 +80,8 @@ const UNKNOWN_COST_PROVENANCE = "unknown";
  *   usageTokensByKind: GroupedIndicator,
  *   usageTokensByKindByRuntime: GroupedIndicator,
  *   usageCostUsd: CostIndicator,
+ *   judgeFindingRate: Indicator,
+ *   judgeCostShare: JudgeCostShareIndicator,
  *   blockingJudgeFirstPassRate: GroupedIndicator,
  *   notifyReceiptRate: Indicator,
  *   silentStallRate: Indicator,
@@ -101,6 +104,10 @@ export function projectMetrics({ events = [], usageRecords = [], notifications =
   const excluded = excludedRunIdsFor(campaign, excludedRunIds);
   const eligibleNodes = nodes.filter((node) => !excluded.includes(node.runId));
   const eligibleEvents = eventList.filter((event) => typeof event.runId !== "string" || !excluded.includes(event.runId));
+  const eligibleUsageRecords = usageRecords.filter((record) => {
+    const object = jsonObjectOf(record);
+    return object === null || typeof object.runId !== "string" || !excluded.includes(object.runId);
+  });
   const eligibleNotifications = notifications.filter((record) => {
     const object = jsonObjectOf(record);
     return object === null || typeof object.runId !== "string" || !excluded.includes(object.runId);
@@ -110,6 +117,7 @@ export function projectMetrics({ events = [], usageRecords = [], notifications =
   const closedCheckpoints = closedCheckpointsOf(nodes);
   const span = eventSpanOf(eventList);
   const usage = usageTotalsOf(usageRecords);
+  const judgeYield = judgeYieldOf(eligibleEvents, eligibleUsageRecords);
   const gates = blockingJudgeFirstPassRateOf(eligibleNodes, eligibleEvents);
   const notify = notifyReceiptRateOf(eligibleNotifications);
   const stalls = silentStallRateOf(eligibleNodes, eligibleEvents);
@@ -129,6 +137,11 @@ export function projectMetrics({ events = [], usageRecords = [], notifications =
       unknownCountByReason: usage.unknownCountByReason,
       unknownFractionByReason: usage.unknownFractionByReason,
     },
+    judgeFindingRate: rate("up", judgeYield.findings, judgeYield.judged, excluded),
+    judgeCostShare: {
+      ...measured("down", usage.costCount, usage.costUsd === null ? null : usage.judgeCostUsd / usage.costUsd),
+      unknownCount: usage.unknownJudgeCount,
+    },
     blockingJudgeFirstPassRate: groupedRate("up", gates, excluded),
     notifyReceiptRate: rate("up", notify.satisfied, notify.count, excluded),
     silentStallRate: rate("down", stalls.stalled, stalls.activeHours, excluded, stalls.activeIntervals),
@@ -162,6 +175,8 @@ function applyMissingSources(metrics, missingSources) {
     usageTokensByKind: withMissing(metrics.usageTokensByKind, ["usage.jsonl"]),
     usageTokensByKindByRuntime: withMissing(metrics.usageTokensByKindByRuntime, ["usage.jsonl"]),
     usageCostUsd: withMissing(metrics.usageCostUsd, ["usage.jsonl"]),
+    judgeFindingRate: withMissing(metrics.judgeFindingRate, ["events.jsonl", "usage.jsonl"]),
+    judgeCostShare: withMissing(metrics.judgeCostShare, ["usage.jsonl"]),
     blockingJudgeFirstPassRate: withMissing(metrics.blockingJudgeFirstPassRate, ["nodes.json", "events.jsonl"]),
     notifyReceiptRate: withMissing(metrics.notifyReceiptRate, ["notify.jsonl"]),
     silentStallRate: withMissing(metrics.silentStallRate, ["nodes.json", "events.jsonl"]),
@@ -311,7 +326,7 @@ function humanTouchesOf(journal, events) {
 /** @param {JsonObject} entry @returns {boolean} */
 function isRecordedJournalTouch(entry) {
   return entry.type === "question.resolved"
-    || (entry.type === "operator.command" && entry.command === "campaign add-contract");
+    || (entry.type === "operator.command" && ["campaign add-contract", "campaign supervise --refresh-controller"].includes(String(entry.command)));
 }
 
 /** @param {JsonObject} entry @returns {boolean} */
@@ -397,7 +412,7 @@ function eventSpanOf(events) {
  * invocation is counted separately rather than folded into a measured zero.
  *
  * @param {unknown[]} usageRecords
- * @returns {{tokensByKind: Record<string, number>, tokensByKindByRuntime: Record<string, number>, tokenCount: number, costUsd: number|null, costCount: number, unknownCount: number, unknownCountByReason: Record<string, number>, unknownFractionByReason: Record<string, number>}}
+ * @returns {{tokensByKind: Record<string, number>, tokensByKindByRuntime: Record<string, number>, tokenCount: number, costUsd: number|null, judgeCostUsd: number, costCount: number, unknownCount: number, unknownJudgeCount: number, unknownCountByReason: Record<string, number>, unknownFractionByReason: Record<string, number>}}
  */
 function usageTotalsOf(usageRecords) {
   const tokensByKind = { inputTokens: 0, cacheReadInputTokens: 0, outputTokens: 0 };
@@ -405,8 +420,10 @@ function usageTotalsOf(usageRecords) {
   const tokensByKindByRuntime = {};
   let tokenCount = 0;
   let costUsd = 0;
+  let judgeCostUsd = 0;
   let costCount = 0;
   let unknownCount = 0;
+  let unknownJudgeCount = 0;
   /** @type {Record<string, number>} */
   const unknownCountByReason = {};
   const kinds = /** @type {("inputTokens"|"cacheReadInputTokens"|"outputTokens")[]} */ (["inputTokens", "cacheReadInputTokens", "outputTokens"]);
@@ -425,9 +442,11 @@ function usageTotalsOf(usageRecords) {
     if (measuredAny) tokenCount += 1;
     if (typeof record.costUsd === "number" && Number.isFinite(record.costUsd) && record.costProvenance !== UNKNOWN_COST_PROVENANCE) {
       costUsd += record.costUsd;
+      if (record.role === "judge") judgeCostUsd += record.costUsd;
       costCount += 1;
     } else {
       unknownCount += 1;
+      if (record.role === "judge") unknownJudgeCount += 1;
       const reason = typeof record.unknownReason === "string" && UNKNOWN_COST_REASONS.includes(record.unknownReason)
         ? record.unknownReason
         : "legacy";
@@ -443,13 +462,51 @@ function usageTotalsOf(usageRecords) {
     tokensByKindByRuntime,
     tokenCount,
     costUsd: costCount === 0 ? null : costUsd,
+    judgeCostUsd,
     costCount,
     unknownCount,
+    unknownJudgeCount,
     unknownCountByReason,
     unknownFractionByReason,
   };
 }
 
+/**
+ * Count logical nodes that reached a judge and those whose judge recorded at
+ * least one finding. A failed judge verdict is the durable ledger projection
+ * of a non-empty findings array; a complete-phase fail is included for
+ * advisory reviews that settle the node after reporting their finding.
+ *
+ * @param {JsonObject[]} events
+ * @param {unknown[]} usageRecords
+ * @returns {{judged: number, findings: number}}
+ */
+function judgeYieldOf(events, usageRecords) {
+  const judged = new Set();
+  const findings = new Set();
+  for (const raw of usageRecords) {
+    const record = jsonObjectOf(raw);
+    if (record === null || record.role !== "judge" || typeof record.nodeId !== "string") continue;
+    judged.add(logicalNodeKey(record.runId, record.nodeId));
+  }
+  for (const event of events) {
+    if (typeof event.node !== "string") continue;
+    const key = logicalNodeKey(event.runId, event.node);
+    if (event.phase === "judge") judged.add(key);
+    const hasFindingArray = Array.isArray(event.findings) && event.findings.length > 0;
+    if ((event.phase === "judge" || event.phase === "complete") && (event.verdict === "fail" || hasFindingArray)) {
+      judged.add(key);
+      findings.add(key);
+    }
+  }
+  return { judged: judged.size, findings: findings.size };
+}
+
+/** @param {unknown} runId @param {string} nodeId @returns {string} */
+function logicalNodeKey(runId, nodeId) {
+  return `${typeof runId === "string" ? runId : ""}:${nodeId}`;
+}
+
 /**
  * Fraction of blocking-gated checkpoints whose first recorded verdict passed,
  * per lane (the judge runtime that produced it). A node under `advisory` or

package/src/cli/campaign.mjs

@@ -84,7 +84,7 @@ const OPERATION_OPTIONS = {
   },
   close: { cwd: { type: "string" }, "event-id": { type: "string" } },
   reledger: { cwd: { type: "string" } },
-  supervise: { cwd: { type: "string" }, "allow-main": { type: "boolean" } },
+  supervise: { cwd: { type: "string" }, "allow-main": { type: "boolean" }, "refresh-controller": { type: "boolean" } },
   unpark: { cwd: { type: "string" }, force: { type: "boolean" }, "event-id": { type: "string" } },
   "add-contract": { cwd: { type: "string" }, path: { type: "string" } },
   "replace-contract": { cwd: { type: "string" }, path: { type: "string" }, replace: { type: "string" } },
@@ -94,7 +94,7 @@ const OPERATION_OPTIONS = {
   ack: { cwd: { type: "string" }, "session-id": { type: "string" }, "event-id": { type: "string" } },
 };
 
-/** @typedef {{cwd?: string, goal?: string, contract?: string[], landBranch?: string, tool?: string, sessionId?: string, transcript?: string, format?: string, cursor?: string, since?: string, kind?: string, text?: string, runId?: string, supersedes?: string, decisionId?: string, questionId?: string, eventId?: string, noTranscript?: boolean, wake?: boolean, detach?: boolean, interval?: string, once?: boolean, allowMain?: boolean, force?: boolean, path?: string, replace?: string, phase?: string}} CliValues */
+/** @typedef {{cwd?: string, goal?: string, contract?: string[], landBranch?: string, tool?: string, sessionId?: string, transcript?: string, format?: string, cursor?: string, since?: string, kind?: string, text?: string, runId?: string, supersedes?: string, decisionId?: string, questionId?: string, eventId?: string, noTranscript?: boolean, wake?: boolean, detach?: boolean, interval?: string, once?: boolean, allowMain?: boolean, refreshController?: boolean, force?: boolean, path?: string, replace?: string, phase?: string}} CliValues */
 /** @typedef {import("../campaign/index.mjs").Campaign} Campaign */
 
 /**
@@ -398,6 +398,7 @@ async function supervise(campaignId, values) {
   const outcome = await driveCampaignChain(path, {
     repo: cwd,
     allowMain: values.allowMain === true,
+    refreshController: values.refreshController === true,
     emit: (line) => process.stdout.write(`${line}\n`),
     launch: async (contractPath, { baseRef, runDir }) => {
       const child = detachSelf("run", contractPath, baseRef ? ["--base-ref", baseRef] : []);

package/src/cli/contract.mjs

@@ -6,6 +6,7 @@
  */
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { parseArgs as parseFlags } from "node:util";
 import { loadPersistedContract, validateContract } from "../contract/index.mjs";
 
 /** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
@@ -13,7 +14,7 @@ import { loadPersistedContract, validateContract } from "../contract/index.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: {},
+  validate: { "strict-traceability": { type: "boolean" } },
 };
 
 /**
@@ -23,9 +24,17 @@ const OPERATION_OPTIONS = {
 export function contractCli(args) {
   const operation = args[0];
   if (!operation || !Object.hasOwn(OPERATION_OPTIONS, operation)) return usage();
-  const target = args[1];
-  if (!target || args.length > 2) return usage();
-  if (operation === "validate") validateContractFile(resolve(target));
+  let parsed;
+  try {
+    parsed = parseFlags({ args: args.slice(1), options: OPERATION_OPTIONS[operation], allowPositionals: true, strict: true });
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    return usage();
+  }
+  const target = parsed.positionals[0];
+  if (!target || parsed.positionals.length > 1) return usage();
+  const values = /** @type {{"strict-traceability"?: boolean}} */ (parsed.values);
+  if (operation === "validate") validateContractFile(resolve(target), { strictTraceability: values["strict-traceability"] === true });
 }
 
 /**
@@ -38,19 +47,29 @@ export function contractCli(args) {
  * authoring validation, tree reads included.
  *
  * @param {string} path
+ * @param {{strictTraceability?: boolean}} [options]
  * @returns {ValidatedContract}
  */
-export function validateContractFile(path) {
+export function validateContractFile(path, { strictTraceability = false } = {}) {
   const runJsonPath = join(dirname(path), "run.json");
   const contract = existsSync(runJsonPath)
     ? loadPersistedContract(path, readRunDigest(runJsonPath))
     : validateContract(JSON.parse(readFileSync(path, "utf8")), path);
   const count = contract.warnings.length;
-  process.stdout.write(`valid${count ? ` (${count} warning${count === 1 ? "" : "s"})` : ""}\n`);
+  const blockingTraceability = strictTraceability
+    ? contract.warnings.filter((warning) => isTraceabilityFinding(warning))
+    : [];
+  process.stdout.write(`${blockingTraceability.length > 0 ? "invalid" : "valid"}${count ? ` (${count} warning${count === 1 ? "" : "s"})` : ""}\n`);
   for (const warning of contract.warnings) process.stdout.write(`[warn] ${warning}\n`);
+  if (blockingTraceability.length > 0) process.exitCode = 1;
   return contract;
 }
 
+/** @param {string} warning @returns {boolean} */
+function isTraceabilityFinding(warning) {
+  return warning.includes("judgment_without_reason") || warning.includes("judgment_beside_mechanical_proof");
+}
+
 /**
  * @param {string} runJsonPath
  * @returns {string|undefined}
@@ -62,7 +81,7 @@ function readRunDigest(runJsonPath) {
 
 /** @returns {void} */
 function usage() {
-  process.stderr.write("usage: faberun contract validate <contract.json>\n");
+  process.stderr.write("usage: faberun contract validate <contract.json> [--strict-traceability]\n");
   process.exitCode = 2;
 }
 

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

@@ -9,7 +9,7 @@ import { rejectUnknown, requireId, requireString } from "./assert.mjs";
 
 /** @typedef {{kind: "command"|"path"|"verification", ref: string}} DefinitionOfDoneProof */
 
-/** @typedef {{id: string, text: string, proof?: DefinitionOfDoneProof, judgment?: true}} DefinitionOfDoneItem */
+/** @typedef {{id: string, text: string, proof?: DefinitionOfDoneProof, judgment?: true, reason?: string}} DefinitionOfDoneItem */
 
 /**
  * @param {unknown} value
@@ -28,12 +28,16 @@ export function validateDefinitionOfDone(value, label, options = {}) {
       throw new TypeError(`${itemLabel} must be an object with id, text, and proof or judgment: true`);
     }
     const record = /** @type {Record<string, unknown>} */ (item);
-    rejectUnknown(record, new Set(["id", "text", "proof", "judgment"]), itemLabel);
+    rejectUnknown(record, new Set(["id", "text", "proof", "judgment", "reason"]), itemLabel);
     requireId(record.id, `${itemLabel}.id`);
     requireString(record.text, `${itemLabel}.text`);
     if (record.judgment !== undefined && record.judgment !== true) {
       throw new TypeError(`${itemLabel}.judgment must be true when present`);
     }
+    if (record.reason !== undefined) {
+      if (record.judgment !== true) throw new TypeError(`${itemLabel}.reason requires judgment: true`);
+      requireString(record.reason, `${itemLabel}.reason`);
+    }
     const proof = record.proof === undefined
       ? undefined
       : validateProof(record.proof, `${itemLabel}.proof`, options);
@@ -45,10 +49,34 @@ export function validateDefinitionOfDone(value, label, options = {}) {
       text: /** @type {string} */ (record.text),
       ...(proof === undefined ? {} : { proof }),
       ...(record.judgment === true ? { judgment: true } : {}),
+      ...(record.reason === undefined ? {} : { reason: /** @type {string} */ (record.reason) }),
     };
   });
 }
 
+/**
+ * Report judgment items that do not explain what mechanical verification cannot
+ * observe. These remain advisory because `contract validate` has no strict
+ * traceability flag; a later strict contract command can promote these codes.
+ *
+ * @param {DefinitionOfDoneItem[]} items
+ * @param {number} index
+ * @returns {string[]}
+ */
+export function judgmentReasonWarnings(items, index) {
+  const judgmentItems = items.filter((item) => item.judgment === true);
+  const warnings = items.flatMap((item, itemIndex) => item.judgment === true && item.reason === undefined
+    ? [`nodes[${index}] (definitionOfDone[${itemIndex}]): judgment_without_reason: judgment item must say what no command verifies`]
+    : []);
+  const hasMechanicalProof = items.some((item) => item.proof !== undefined);
+  if (judgmentItems.length > 0 && hasMechanicalProof && judgmentItems.every((item) => item.reason === undefined)) {
+    warnings.push(
+      `nodes[${index}]: judgment_beside_mechanical_proof: every judgment item shares this node with mechanical-proof items but declares no reason`,
+    );
+  }
+  return warnings;
+}
+
 /**
  * @param {unknown} value
  * @param {string} label
@@ -144,4 +172,3 @@ export function unquotedFilterValueWarnings(items, index) {
 
 /** 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/index.mjs

@@ -3,7 +3,7 @@ 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 { unquotedFilterValueWarnings, validateDefinitionOfDone } from "./definition-of-done.mjs";
+import { judgmentReasonWarnings, unquotedFilterValueWarnings, validateDefinitionOfDone } from "./definition-of-done.mjs";
 import { validateFinalVerification, validateSharedVerification } from "./final-verification.mjs";
 import { VERIFICATION_LIMITS, requirementProofWarnings } from "./verification.mjs";
 import {
@@ -378,6 +378,7 @@ export function validateContract(raw, contractPath, options = {}) {
     ...nodes.flatMap((node, index) => [
       ...commandCoverageWarnings(node, index),
       ...unquotedFilterValueWarnings(node.definitionOfDone ?? [], index),
+      ...judgmentReasonWarnings(node.definitionOfDone ?? [], index),
       ...(persisted ? [] : mirrorCoverageWarnings(node, index, cwd, contractCommands, contractWrites)),
       ...(persisted ? [] : unsnapshottedWriteWarnings(node, index, cwd)),
       ...(persisted ? [] : ignoreSourceWriteWarnings(node, index)),

package/src/engine/dispatch.mjs

@@ -50,7 +50,7 @@ import { transition, writeNode } from "./state.mjs";
  * `dispatched`: a judge is running (or failed to start and the node is already
  * marked failed).
  *
- * @typedef {{kind: "rejected", verdict: JudgeVerdict}|{kind: "settle", gate: JudgeVerdict}|{kind: "dispatched"}} JudgeRound
+ * @typedef {{kind: "rejected", verdict: JudgeVerdict}|{kind: "settle", gate: JudgeVerdict|null}|{kind: "dispatched"}} JudgeRound
  */
 /** @typedef {import("./prompts.mjs").JudgeVerdict} JudgeVerdict */
 
@@ -439,6 +439,28 @@ export function startResultMaterialization(contract, node, state, runDir, runnin
     transition(runDir, state, "failed", { phase: "worker", error: { code: "result_materialization_failed", message: errorMessage(error) } }, lock);
   }
 }
+/**
+ * The mechanical half of the gate, for a node whose gate is disabled: its
+ * Definition of Done command and path proofs still run, and no judge is
+ * asked. Measured 2026-09-23 on evidence-you-can-recompute: every node carried
+ * `gate: false`, and not one of its declared proofs ran.
+ *
+ * @param {ValidatedContract} contract
+ * @param {ValidatedNode} node
+ * @param {NodeSnapshot} state
+ * @returns {Promise<JudgeRound>}
+ */
+export async function startMechanicalGate(contract, node, state) {
+  const { verdict, results } = await deterministicGate(
+    node,
+    attemptWorkspace(state) ?? contract.cwd,
+    false,
+    gateProofTimeoutMs(node, contract),
+    /** @type {import("../contract/index.mjs").VerificationState|null} */ (state.verification),
+  );
+  if (verdict.verdict === "fail") return { kind: "rejected", verdict };
+  return { kind: "settle", gate: results.length ? verdict : null };
+}
 /**
  * Gate a completed worker: mechanical proofs gate first, the judge arbitrates
  * only judgment items and is skipped when the review mode is `none` or no

package/src/engine/lifecycle.mjs

@@ -52,7 +52,7 @@ import {
   workerResultPath,
 } from "./result-file.mjs";
 import { canReuseResultEvidence, checkResultMaterializationScope, checkWorkerScope, recordScopeFinding, sourceWorkerRuntime } from "./scope.mjs";
-import { startJudge, startResultMaterialization } from "./dispatch.mjs";
+import { startJudge, startMechanicalGate, startResultMaterialization } from "./dispatch.mjs";
 import { raiseNodeAttention, settleDone } from "./settle.mjs";
 import { applyRejection, applyVerificationFailure } from "./settle.mjs";
 import { emitNodeAdvisories } from "./notify-queue.mjs";
@@ -587,11 +587,10 @@ export async function finalizeClosedJobs(contract, runDir, states, closed, lock,
         continue;
       }
       if (job.scopeViolation) recordScopeFinding(runDir, state, lock);
-      if (job.node.gate.enabled) {
-        await applyJudgeRound(await startJudge(contract, job.node, state, runDir, running, workerResult, lock, states, campaignPath),
-          contract, job.node, state, runDir, running, lock, states, campaignPath, workerResult);
-      }
-      else await settleDone(contract, job.node, state, runDir, lock, states, campaignPath, { phase: "complete", result: workerResult });
+      const round = job.node.gate.enabled
+        ? await startJudge(contract, job.node, state, runDir, running, workerResult, lock, states, campaignPath)
+        : await startMechanicalGate(contract, job.node, state);
+      await applyJudgeRound(round, contract, job.node, state, runDir, running, lock, states, campaignPath, workerResult);
       continue;
     }
   }

package/src/plan/proof-run.mjs

@@ -25,6 +25,13 @@ import { NOTIFY_SESSION_ENV } from "../notify/session.mjs";
 /** @typedef {{requirementId: string|null, kind: "command"|"path", ref: string, pass: boolean, detail: string}} RequirementProofResult */
 
 export const MEASURE_TIMEOUT_MS = 30_000;
+/**
+ * A proof is a test run, not a fact probe. Measured 2026-09-24: R6 of
+ * `evals-with-a-budget` takes 98 s pinned to its file, and under the 30 s fact
+ * bound the runner died on SIGTERM with exit 1, read as a failing proof. Ten
+ * minutes has no measurement behind it beyond covering the slowest proof seen.
+ */
+const PROOF_TIMEOUT_MS = 600_000;
 export const MEASURE_OUTPUT_CAP_BYTES = 4096;
 
 /** How much of a failing proof's own output a finding carries: enough to name the failure, never the whole log. */
@@ -65,18 +72,62 @@ export const MEASURE_SIDE_EFFECT_ENV_KEYS = [
  * @returns {{output: string, exitCode: number|null, truncated: boolean}}
  */
 export function runShellCapture(cwd, command, probes = {}) {
+  const { output, exitCode, truncated } = runShellFull(cwd, command, probes);
+  const bytes = Buffer.from(output, "utf8");
+  return {
+    output: truncated ? bytes.subarray(0, MEASURE_OUTPUT_CAP_BYTES).toString("utf8") : output,
+    exitCode,
+    truncated,
+  };
+}
+
+/**
+ * The shell run behind `runShellCapture`, returning the whole output: a
+ * pinned-test check has to see every test the runner reported, and the
+ * matching line can sit far past the 4 KiB a measurement keeps.
+ *
+ * @param {string} cwd
+ * @param {string} command
+ * @param {MeasureProbes} [probes]
+ * @param {number} [timeoutMs]
+ * @returns {{output: string, exitCode: number|null, truncated: boolean, timedOut: boolean}}
+ */
+function runShellFull(cwd, command, probes = {}, timeoutMs = MEASURE_TIMEOUT_MS) {
   const run = probes.run ?? spawnSync;
   const env = { ...process.env };
   for (const key of MEASURE_SIDE_EFFECT_ENV_KEYS) delete env[key];
-  const result = run(command, { shell: true, cwd, timeout: MEASURE_TIMEOUT_MS, encoding: "utf8", env });
+  // A nested `node --test` that inherits NODE_TEST_CONTEXT stays a runner
+  // child and prints no result at all (measured 2026-09-21, AGENTS.md), so a
+  // proof run from inside a test runner would have nothing to show.
+  delete env.NODE_TEST_CONTEXT;
+  const result = run(command, { shell: true, cwd, timeout: timeoutMs, encoding: "utf8", env });
   const combined = `${result.stdout ?? ""}${result.stderr ?? ""}`;
-  const bytes = Buffer.from(combined, "utf8");
-  const truncated = bytes.length > MEASURE_OUTPUT_CAP_BYTES;
-  return {
-    output: truncated ? bytes.subarray(0, MEASURE_OUTPUT_CAP_BYTES).toString("utf8") : combined,
-    exitCode: result.status,
-    truncated,
-  };
+  const timedOut = /** @type {NodeJS.ErrnoException|undefined} */ (result.error)?.code === "ETIMEDOUT";
+  return { output: combined, exitCode: result.status, truncated: Buffer.byteLength(combined, "utf8") > MEASURE_OUTPUT_CAP_BYTES, timedOut };
+}
+
+/** `--test-name-pattern` in a shell command, quoted or bare, `=` or space. */
+const NAME_PATTERN_FLAG = /--test-name-pattern(?:=|\s+)(?:"([^"]*)"|'([^']*)'|(\S+))/u;
+/** A passing test as the spec reporter (`✔ name (1ms)`) or TAP (`ok 1 - name`) prints it. */
+const PASSING_TEST_LINE = /^\s*(?:\u2714\s+|ok \d+ - )(.+?)(?:\s+\(\d[\d.]*m?s\))?\s*$/gmu;
+
+/**
+ * Whether a `node --test --test-name-pattern=<p>` proof ran a test named by
+ * its pattern. Node exits 0 when the pattern matches nothing, printing only
+ * the file, so the exit code alone cannot tell a proof from its absence.
+ * Returns null when the command carries no pattern.
+ *
+ * @param {string} command
+ * @param {string} output
+ * @returns {boolean|null}
+ */
+function patternMatchedATest(command, output) {
+  if (!/\bnode\b[^|;&]*--test\b/u.test(command)) return null;
+  const flag = NAME_PATTERN_FLAG.exec(command);
+  if (!flag) return null;
+  const pattern = new RegExp(flag[1] ?? flag[2] ?? flag[3], "u");
+  const plain = output.replace(/\u001b\[[0-9;]*m/gu, "");
+  return [...plain.matchAll(PASSING_TEST_LINE)].some((line) => pattern.test(line[1]) && !/\.m?[jt]s$/u.test(line[1].trim()));
 }
 
 /**
@@ -104,11 +155,14 @@ export function proveRequirements(cwd, requirements, probes = {}) {
     const proof = requirement.proof;
     if (!proof?.ref) continue;
     if (proof.kind === "command") {
-      const { output, exitCode } = runShellCapture(cwd, proof.ref, probes);
-      const detail = exitCode === 0
-        ? "exit 0"
-        : `exit ${exitCode ?? "no exit code (killed or never started)"}${output.trim() ? `: ${output.trim().slice(0, PROOF_DETAIL_CAP)}` : ""}`;
-      results.push({ requirementId: requirement.id, kind: "command", ref: proof.ref, pass: exitCode === 0, detail });
+      const { output, exitCode, timedOut } = runShellFull(cwd, proof.ref, probes, PROOF_TIMEOUT_MS);
+      const matched = exitCode === 0 ? patternMatchedATest(proof.ref, output) : null;
+      const detail = timedOut
+        ? `timed out after ${PROOF_TIMEOUT_MS / 1000} s`
+        : exitCode !== 0
+        ? `exit ${exitCode ?? "no exit code (killed or never started)"}${output.trim() ? `: ${output.trim().slice(0, PROOF_DETAIL_CAP)}` : ""}`
+        : matched === false ? "exit 0, but its --test-name-pattern matched no test: the proof ran nothing" : "exit 0";
+      results.push({ requirementId: requirement.id, kind: "command", ref: proof.ref, pass: exitCode === 0 && matched !== false, detail });
       continue;
     }
     if (proof.kind === "path") {

package/src/plan/template.mjs

@@ -111,7 +111,7 @@ const REQUIRED_INPUTS = Object.freeze({
 // run had already succeeded. The id charset is requireId's
 // (contract/assert.mjs) verbatim, because an id that is present but invalid
 // fails that same validator just as late.
-const PLAN_OUTPUT_SHAPE = '{nodes: [{id, objective, taskKind, riskTier, dependsOn, readFiles, writeFiles, scopeAcknowledged, definitionOfDone: [{id, text, proof?: {kind: "command"|"path"|"verification", ref}, judgment?: true}], verification: [{argv: [string], cwd?, timeoutSec?, repeat?, env?, mutation?: {threshold}}], expectedTurns?}], phases?: [{id, requirementIds: [string], nodeIds: [string], deliverable}], justification?}; every id in it (node, phase, node assignment, and definitionOfDone item) must match [A-Za-z0-9._-]+ and never be exactly "." or ".."';
+const PLAN_OUTPUT_SHAPE = '{nodes: [{id, objective, taskKind, riskTier, dependsOn, readFiles, writeFiles, scopeAcknowledged, definitionOfDone: [{id, text, proof?: {kind: "command"|"path"|"verification", ref}, judgment?: true, reason?: string}], verification: [{argv: [string], cwd?, timeoutSec?, repeat?, env?, mutation?: {threshold}}], expectedTurns?}], phases?: [{id, requirementIds: [string], nodeIds: [string], deliverable}], justification?}; every id in it (node, phase, node assignment, and definitionOfDone item) must match [A-Za-z0-9._-]+ and never be exactly "." or ".."';
 /**
  * The size guidance every draft and revise carries. measured 2026-09-20 over
  * stored runs: median 49 provider requests per worker turn; cost per turn

package/src/repo/worktree.mjs

@@ -384,7 +384,10 @@ export function sealAttempt({ repo, path, baseSha, runId, nodeId, attempt, exclu
       // schedule it chose. The identity and signing overrides above are the
       // same argument: this commit answers to the factory, not to the repo's
       // conventions for human commits.
-      "commit", "--no-verify", "-qm", `faberun ${runId} ${nodeId} attempt ${attempt}`,
+      // Conventional, so a campaign branch passes a PR's commitlint check
+      // (measured 2026-09-23: every `faberun <run> <node> attempt N` seal was
+      // refused); the run id moves to the body to keep the header short.
+      "commit", "--no-verify", "-q", "-m", `chore(faberun): seal ${nodeId} attempt ${attempt}`, "-m", `run ${runId}`,
     ]);
   }
   const sha = gitHead(path);

package/src/run/lock.mjs

@@ -17,7 +17,7 @@ import { closeSync, fsyncSync, linkSync, mkdirSync, openSync, readFileSync, rena
 import { hostname } from "node:os";
 import { join } from "node:path";
 import { fsyncDirectory } from "./store.mjs";
-import { errorCode } from "../util.mjs";
+import { errorCode, sleepSync } from "../util.mjs";
 
 const LOCK_FILE = "controller.lock";
 const TAKEOVER_ATTEMPTS = 20;
@@ -84,7 +84,7 @@ export function processStartToken(pid) {
     // and report nothing for a pid that is already alive. One short retry
     // closes that window; a still-empty answer stays null.
     if (!pidAlive(pid)) return null;
-    sleepMs(20);
+    sleepSync(20);
     const retried = psStartTime(pid);
     return retried.length > 0 ? retried : null;
   }
@@ -106,16 +106,6 @@ function psStartTime(pid) {
   }
 }
 
-/**
- * Block without a timer so the synchronous darwin retry above can wait out the
- * spawn race. The duration is tiny and bounded, so blocking the loop is safe.
- *
- * @param {number} milliseconds
- */
-function sleepMs(milliseconds) {
-  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
-}
-
 /** @param {number|null|undefined} pid @returns {boolean} */
 export function pidAlive(pid) {
   if (!Number.isInteger(pid) || /** @type {number} */ (pid) <= 0) return false;

package/src/run/store.mjs

@@ -14,9 +14,19 @@ import {
 } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { dirname, join } from "node:path";
-import { errorCode } from "../util.mjs";
+import { errorCode, sleepSync } from "../util.mjs";
 
 const BOOTSTRAP_FILE = "bootstrap.json";
+// Windows refuses to replace a file another process holds open: MoveFileEx
+// answers EPERM (or EACCES, EBUSY) while a reader, an indexer or a virus
+// scanner has the destination, where a POSIX rename replaces it regardless.
+// Measured 2026-09-23 on Windows 11 with node 24: one process polling a file
+// with readFileSync failed 882 of 2190 atomic writes onto it, and on CI that
+// killed controllers mid-run (a heartbeat write threw out of driveRun). The
+// retry and its bounds are graceful-fs's: back off 10 ms more per attempt up to
+// 100 ms, and give up after 60 s.
+const WINDOWS_RENAME_BUSY = new Set(["EPERM", "EACCES", "EBUSY"]);
+const RENAME_RETRY_BUDGET_MS = 60_000;
 const JSONL_RECOVERY_TAIL_BYTES = 64 * 1024;
 
 /**
@@ -51,7 +61,7 @@ export function writeTextAtomic(path, text) {
     } finally {
       closeSync(fd);
     }
-    renameSync(temporary, path);
+    renameReplacing(temporary, path);
     fsyncDirectory(dirname(path));
     committed = true;
   } catch (error) {
@@ -68,6 +78,24 @@ export function writeTextAtomic(path, text) {
   }
 }
 
+/**
+ * @param {string} from
+ * @param {string} to
+ */
+function renameReplacing(from, to) {
+  const deadline = Date.now() + RENAME_RETRY_BUDGET_MS;
+  for (let backoff = 0; ; backoff = Math.min(backoff + 10, 100)) {
+    try {
+      renameSync(from, to);
+      return;
+    } catch (error) {
+      const busy = process.platform === "win32" && WINDOWS_RENAME_BUSY.has(errorCode(error) ?? "");
+      if (!busy || Date.now() >= deadline) throw error;
+      sleepSync(backoff);
+    }
+  }
+}
+
 /**
  * @param {string} path
  * @param {unknown} value

package/src/util.mjs

@@ -275,3 +275,13 @@ export function shellWords(text) {
   if (current !== null) words.push(current);
   return words;
 }
+
+/**
+ * Block the thread without a timer, for a synchronous path that has to wait
+ * out a short race. Callers keep the duration tiny and bounded.
+ *
+ * @param {number} milliseconds
+ */
+export function sleepSync(milliseconds) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}