faberun 0.23.0 → 0.23.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faberun",
-  "version": "0.23.0",
+  "version": "0.23.1",
   "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/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

@@ -311,7 +311,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} */

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/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

@@ -65,18 +65,60 @@ 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]
+ * @returns {{output: string, exitCode: number|null, truncated: boolean}}
+ */
+function runShellFull(cwd, command, probes = {}) {
   const run = probes.run ?? spawnSync;
   const env = { ...process.env };
   for (const key of MEASURE_SIDE_EFFECT_ENV_KEYS) delete env[key];
+  // 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: MEASURE_TIMEOUT_MS, 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,
-  };
+  return { output: combined, exitCode: result.status, truncated: Buffer.byteLength(combined, "utf8") > MEASURE_OUTPUT_CAP_BYTES };
+}
+
+/** `--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 +146,12 @@ 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 } = runShellFull(cwd, proof.ref, probes);
+      const matched = exitCode === 0 ? patternMatchedATest(proof.ref, output) : null;
+      const detail = 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/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);
+}