faberun 0.19.0 → 0.19.2

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;
+}

package/src/engine/cancel.mjs

@@ -16,7 +16,7 @@ import { invocationOwned } from "./process-identity.mjs";
 import { terminateInvocation } from "./process.mjs";
 import { join, resolve } from "node:path";
 import { readFileSync } from "node:fs";
-import { readRunNodes } from "./scheduler.mjs";
+import { readRunNodes } from "../run/node-store.mjs";
 import { createPreservedRef, deleteRef, releaseAttemptWorktree, runRefName } from "../repo/worktree.mjs";
 import { syncAgentSignal } from "../repo/signal.mjs";
 import { transition, writeNode } from "./state.mjs";
@@ -55,7 +55,7 @@ export async function cancelRun(runDirPath) {
   }
   const controllerLock = await acquireStaleLock(runDir);
   try {
-    const states = readRunNodes(runDir, contract);
+    const states = readRunNodes(runDir, contract, { tolerateMissing: true });
     /** @type {Error[]} */
     const failures = [];
     for (const state of states) {
@@ -196,7 +196,7 @@ async function waitForTerminal(runDir, timeoutMs) {
   while (Date.now() < deadline) {
     const contractPath = join(runDir, "contract.json");
     const contract = validateContract(JSON.parse(readFileSync(contractPath, "utf8")), contractPath, { persisted: true });
-    const states = readRunNodes(runDir, contract);
+    const states = readRunNodes(runDir, contract, { tolerateMissing: true });
     if (states.every((state) => SETTLED.has(state.status)) && states.every((state) => (state.invocations ?? []).every((invocation) => !invocationOwned(invocation)))) return true;
     await delay(100);
   }

package/src/engine/dispatch.mjs

@@ -25,6 +25,7 @@ import { attemptWorkspace, createAttemptWorktree, sealAttempt } from "../repo/wo
 import { attemptWorktreePath } from "../run/paths.mjs";
 import { basename, dirname, join } from "node:path";
 import { errorCode, errorMessage } from "../util.mjs";
+import { gateProofTimeoutMs } from "../contract/final-verification.mjs";
 import { captureWorkspaceScope, captureWorkspaceSnapshot } from "../repo/workspace.mjs";
 import { deterministicGate, judgeReaskReason, judgeRequired, judgeSkippedByScope } from "./judge-gate.mjs";
 import { emptyScope, persistedScopeBoundary, workerScope } from "./scope.mjs";
@@ -459,7 +460,7 @@ export async function startJudge(contract, node, state, runDir, running, workerR
     node,
     workspace,
     reask,
-    Math.max(1_000, Math.min((node.timeoutSec ?? contract.timeoutSec ?? 60) * 1000, 120_000)),
+    gateProofTimeoutMs(node, contract),
     /** @type {import("../contract/index.mjs").VerificationState|null} */ (state.verification),
   );
   state.review = reviewMode(node.gate);

package/src/engine/failover.mjs

@@ -136,15 +136,22 @@ export function failoverEdges(contract) {
  * The first snapshot wins; every later requirement set is accumulated, so a
  * runtime reached twice is still checked against both callers' demands.
  *
- * @param {Map<string, {runtime: RuntimeSnapshot, requiredCapabilitySets: import("../harnesses/index.mjs").CapabilityRequirements[]}>} runtimes
+ * `routed` says whether some node or default names this runtime, directly or
+ * as a declared failover target. A runtime reached only because a role named
+ * none -- every catalogue entry is then a candidate availability discovery may
+ * pick -- is added with `routed: false`, and one route that names it at all
+ * makes it routed for good.
+ *
+ * @param {Map<string, {runtime: RuntimeSnapshot, requiredCapabilitySets: import("../harnesses/index.mjs").CapabilityRequirements[], routed: boolean}>} runtimes
  * @param {RuntimeSnapshot} runtime
  * @param {import("../harnesses/index.mjs").CapabilityRequirements[]} requiredCapabilitySets
+ * @param {boolean} [routed]
  */
-export function addRuntimeRequirement(runtimes, runtime, requiredCapabilitySets) {
+export function addRuntimeRequirement(runtimes, runtime, requiredCapabilitySets, routed = true) {
   const incoming = requiredCapabilitySets.filter((requirements) => requirements && Object.keys(requirements).length);
   const current = runtimes.get(runtime.id);
-  if (!current) runtimes.set(runtime.id, { runtime, requiredCapabilitySets: incoming });
-  else runtimes.set(runtime.id, { runtime: current.runtime, requiredCapabilitySets: [...current.requiredCapabilitySets, ...incoming] });
+  if (!current) runtimes.set(runtime.id, { runtime, requiredCapabilitySets: incoming, routed });
+  else runtimes.set(runtime.id, { runtime: current.runtime, requiredCapabilitySets: [...current.requiredCapabilitySets, ...incoming], routed: current.routed || routed });
 }
 
 /**

package/src/engine/judge-gate.mjs

@@ -16,6 +16,7 @@ import { reviewMode, UNCITED_REJECTION_REASON } from "../contract/review-modes.m
 import { JUDGE_LIMITS } from "../contract/judge-envelope.mjs";
 import { sharedVerificationCommands } from "../contract/final-verification.mjs";
 import { killTarget } from "../host/platform.mjs";
+import { shellWords } from "../util.mjs";
 
 /** @typedef {import("../contract/definition-of-done.mjs").DefinitionOfDoneItem} DefinitionOfDoneItem */
 /** @typedef {import("../contract/verification.mjs").VerificationCommand} VerificationCommand */
@@ -174,31 +175,26 @@ function envForFilteredProof() {
 /**
  * The node:test filters a command string declares, in argv order, as flag and
  * value. Presence alone changes behaviour (the appended reporter and the
- * zero-plan look-up); the value is read for the refusal detail alone, which is
- * why a whitespace split is close enough even though the command runs through
- * a shell.
+ * zero-plan look-up); the value lands in the refusal detail, and it is read
+ * the way the shell this command runs under reads it -- `shellWords` groups a
+ * quoted pattern into one word instead of splitting the pattern itself.
  *
  * @param {string} ref
  * @returns {Array<{flag: string, value: string}>}
  */
 function declaredTestFilters(ref) {
-  const tokens = ref.split(/\s+/u).filter(Boolean);
+  const tokens = shellWords(ref);
   /** @type {Array<{flag: string, value: string}>} */
   const filters = [];
   for (const [index, token] of tokens.entries()) {
     for (const flag of TEST_FILTER_FLAGS) {
-      if (token.startsWith(`${flag}=`)) filters.push({ flag, value: unquote(token.slice(flag.length + 1)) });
-      else if (token === flag) filters.push({ flag, value: unquote(tokens[index + 1] ?? "") });
+      if (token.startsWith(`${flag}=`)) filters.push({ flag, value: token.slice(flag.length + 1) });
+      else if (token === flag) filters.push({ flag, value: tokens[index + 1] ?? "" });
     }
   }
   return filters;
 }
 
-/** @param {string} value @returns {string} */
-function unquote(value) {
-  return value.replace(/^['"]|['"]$/gu, "");
-}
-
 /** @param {Array<{flag: string, value: string}>} filters @returns {string} */
 function filterNames(filters) {
   return filters.map(({ flag, value }) => `${flag} "${value}"`).join(", ");

package/src/engine/process.mjs

@@ -36,7 +36,7 @@ import { killTarget } from "../host/platform.mjs";
 /** @typedef {{prompt: string|null, stdout: string, stderr: string}} PathSet */
 /** @typedef {{id: string, pid: number, processGroupId: number|null, processStartToken: string|null, harness: string, runtimeId: string|null, runtimeFingerprint?: string, revision?: number, phase: string, promptPath: string|null, stdoutPath: string, stderrPath: string, startedAt: string, deadlineAt: string|null, updatedAt: string, closedAt: string|null, exitCode: number|null, signal: string|null, status: "active"|"closed"|"terminated", executable: string, snapshotPath?: string, usage?: Usage, usageEstimated?: boolean, costUsd?: number|null, costProvenance?: "priced", runId?: string, campaignId?: string, nodeId?: string, attempt?: number, workspace?: string, worktreeBranch?: string|null, worktreeBaseSha?: string|null, planPhase?: string, role?: "worker"|"judge", model?: string, reasoning?: string|null, sandbox?: string|null, continuationId?: string|null, continuationMode?: "fresh"|"reuse"|"rotate", session?: import("../harnesses/session-metrics.mjs").SessionLedger|null}} Invocation */
 /** @typedef {{pid: number|null, processGroupId?: number|null, processStartToken?: string|null}} InvocationProbe */
-/** @typedef {{child: ChildProcess, contract: ValidatedContract, node: ValidatedNode, state: NodeSnapshot, runtime: HarnessRuntime & {id: string|null}, cwd: string, paths: PathSet, phase: string, invocation: Invocation, startedAt: string, startedTicks: bigint, progressTicks: bigint, lastOutputAt: number, closed: boolean, exitCode: number|null, signal: string|null, spawnError: Error|null, terminating: Promise<void>|null, gateConfigPath: string, gateReleasePath: string, scopeBaseline?: unknown, scopeChecked?: boolean, scopeViolation?: boolean, resultMaterialization?: boolean, recoveryBaseline?: unknown, observeTimer?: ReturnType<typeof setInterval>, monitorOffset?: number, monitorParser?: import("../harnesses/session-metrics.mjs").SessionMetricsParser, lastEventCount?: number, observedOnce?: boolean, onClose?: (invocation: Invocation) => void, onInvocationUpdate?: (invocation: Invocation) => void, onProgress?: (state: NodeSnapshot) => void}} Job */
+/** @typedef {{child: ChildProcess, contract: ValidatedContract, node: ValidatedNode, state: NodeSnapshot, runtime: HarnessRuntime & {id: string|null}, cwd: string, paths: PathSet, phase: string, invocation: Invocation, startedAt: string, startedTicks: bigint, progressTicks: bigint, lastOutputAt: number, closed: boolean, exitCode: number|null, signal: string|null, spawnError: Error|null, terminating: Promise<void>|null, gateConfigPath: string, gateReleasePath: string, scopeBaseline?: unknown, scopeChecked?: boolean, scopeViolation?: boolean, resultMaterialization?: boolean, recoveryBaseline?: unknown, observeTimer?: ReturnType<typeof setInterval>, monitorOffset?: number, monitorParser?: import("../harnesses/session-metrics.mjs").SessionMetricsParser, lastEventCount?: number, lastMonitorOffset?: number, observedOnce?: boolean, turnCapWarned?: boolean, onClose?: (invocation: Invocation) => void, onInvocationUpdate?: (invocation: Invocation) => void, onProgress?: (state: NodeSnapshot) => void}} Job */
 /** @typedef {{graceMs?: number, killGraceMs?: number, escalate?: boolean, runDir?: string, kill?: (pid: number, signal: string|number) => unknown, child?: ChildProcess|null}} TerminateOptions */
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -278,6 +278,14 @@ export async function terminateInvocation(invocation, options = {}) {
  */
 const SEAL_BEFORE_KILL_CODES = new Set(["wall_clock_timeout", "stall_timeout", "turn_limit"]);
 
+/**
+ * How far into its request ceiling an attempt gets before it says so. Four
+ * fifths: late enough that an ordinary attempt never mentions it (measured
+ * 2026-09-20 over 200 completed claude worker turns, p90 was 83 of a 150
+ * default), early enough that the remaining fifth is still room to act in.
+ */
+const TURN_CAP_WARN_FRACTION = 0.8;
+
 /**
  * How long a `SIGSTOP`ped process group is given to actually stop before the
  * seal begins. The stop is asynchronous; this bounded settle keeps the seal
@@ -434,8 +442,26 @@ export async function detectStalls(contract, running, onTimeout, onProgress, onB
     if (streaming) {
       const monitored = monitorInvocation(job);
       const events = monitored.turns + monitored.toolCalls;
-      if (events !== job.lastEventCount || job.observedOnce !== true) {
+      // Transcript bytes the monitor consumed count as liveness beside the
+      // events, because a turn can transmit for a long time without finishing
+      // one. Codex meters progress as `turn.completed` plus tool calls, so a
+      // single long reasoning stretch -- streaming `item.completed` records
+      // that are neither -- advanced no counter and was killed as a stall
+      // while it was actively transmitting. This is not the mtime the module
+      // header rejects: mtime moves for a buffered harness that has written
+      // nothing a provider produced, and this branch is the streaming
+      // harnesses only, where new bytes on the transcript are the provider's
+      // own output and the monitor's offset only ever advances. A process
+      // that transmits forever without ending is still held by the wall clock
+      // and the turn cap below.
+      // An offset this job has never recorded is not growth: `observedOnce`
+      // below is what covers the first pass, and reading `undefined` as a
+      // change would make every first observation look like progress.
+      const consumed = job.monitorOffset ?? 0;
+      const grew = consumed !== (job.lastMonitorOffset ?? consumed);
+      if (events !== job.lastEventCount || grew || job.observedOnce !== true) {
         job.lastEventCount = events;
+        job.lastMonitorOffset = consumed;
         job.progressTicks = now;
         // `lastOutputAt` is the supervised controller's provider-progress
         // signal (scheduler.mjs): keep it advancing for an event that counts
@@ -450,6 +476,18 @@ export async function detectStalls(contract, running, onTimeout, onProgress, onB
       // (`turns` counts provider requests for claude, dsh and agy; codex
       // reports whole turns, so its cap is in effect a turn count.)
       const turnCap = job.node?.maxTurns ?? contract.maxTurns;
+      // The ceiling used to arrive only as the kill. `maxTurns` appeared once
+      // in the whole documentation set and not at all in the contract
+      // reference, so the author of a long-running contract raised
+      // `timeoutSec` and `stallTimeoutSec` -- everything they knew existed --
+      // and left this at its default; two Opus attempts at maximum effort
+      // were then cut mid-turn with `turn_limit`, after the cost was already
+      // paid. Said once per attempt as the ceiling comes into view, it is a
+      // decision the operator can still make.
+      if (typeof turnCap === "number" && job.turnCapWarned !== true && monitored.turns >= Math.floor(turnCap * TURN_CAP_WARN_FRACTION)) {
+        job.turnCapWarned = true;
+        process.stdout.write(`[node] ${nodeId} ${job.phase} · ${monitored.turns} of the attempt's maxTurns of ${turnCap} provider requests · raise maxTurns to give it more\n`);
+      }
       if (typeof turnCap === "number" && monitored.turns >= turnCap) {
         const limit = {
           code: "turn_limit",

package/src/engine/resume.mjs

@@ -23,7 +23,8 @@ import { attemptWorktreePath } from "../run/paths.mjs";
 import { canonicalWorkerResultText, isResultMaterializationInvocation, materializeAttemptResult, recoverWorkerResult } from "./result-file.mjs";
 import { checkPersistedWorkerScope, persistedScopeBoundary, reconcileAmbiguousWorkerRestart, resolveUnknownEffect } from "./scope.mjs";
 import { closePersistedInvocation, recoverOrphan, recoveryFromOverride } from "./recover.mjs";
-import { driveRun, readRunNodes } from "./scheduler.mjs";
+import { driveRun } from "./scheduler.mjs";
+import { readRunNodes } from "../run/node-store.mjs";
 import { emptyUsage, invocationCost, invocationUsage, persistRecoveryUsage } from "../run/usage.mjs";
 import { ensureTerminalEvent, hasDoneEvent, recordExecutionOverride, transition, writeNode } from "./state.mjs";
 import { errorMessage, excerpt } from "../util.mjs";

package/src/engine/runtime-discovery.mjs

@@ -60,7 +60,18 @@ export const DISCOVERY_RUNTIME_DEFINITIONS = Object.freeze({
     costRank: 1,
   },
   "agy-gemini": { harness: "agy", model: "gemini-3.8-flash-low", vendor: "google", tier: 1, costRank: 1 },
+  // Three codex rows, because the harness declares three models and an
+  // account is entitled to only some of them: measured 2026-09-21 on the
+  // owner's ChatGPT account, plain `gpt-5.6` answers HTTP 400 while
+  // `gpt-5.6-sol` answers normally. One row meant `setup` could offer only the
+  // model that account cannot use, and the operator's only way out was to hand
+  // every contract its own catalogue through `--runtimes`. Declaration order is
+  // unchanged, so the composed default is still `codex-gpt`: which of the three
+  // an account can reach is not something this file can know, and the live
+  // preflight is what reports it per id.
   "codex-gpt": { harness: "codex", model: "gpt-5.6", vendor: "openai", tier: 2, costRank: 2 },
+  "codex-sol": { harness: "codex", model: "gpt-5.6-sol", vendor: "openai", tier: 2, costRank: 2 },
+  "codex-luna": { harness: "codex", model: "gpt-5.6-luna", vendor: "openai", tier: 2, costRank: 2 },
   "claude-sonnet": { harness: "claude", model: "claude-sonnet-5", vendor: "anthropic", tier: 2, costRank: 2 },
 });
 

package/src/engine/scheduler.mjs

@@ -37,14 +37,12 @@ import { delay, errorCode } from "../util.mjs";
 import { alreadyNotified, emitNodeAdvisories, notifyQueueFor, notifyQueuesByRun, renderCampaignHandoffSafely } from "./notify-queue.mjs";
 import { detectStalls, invocationAlive, terminateProcess } from "./process.mjs";
 import { transition, writeNode } from "./state.mjs";
-import { listNodeSnapshots, readNodeSnapshot } from "../run/node-store.mjs";
 import { render, renderFinalReport, writeFindingsArtifact } from "../report/final.mjs";
 import { operationNextState, providerReceipts, settleInvocation } from "../run/operations.mjs";
 import { appendUsageRecord, invocationCost, invocationUsage, recordInvocationUsage } from "../run/usage.mjs";
 import { captureNodeScopeBoundaries, checkWorkerScope, emptyScope } from "./scope.mjs";
 import { validateContractForLaunch } from "../campaign/chain.mjs";
-import { validateNodeSnapshot } from "../contract/snapshot.mjs";
-import { finalVerificationCommands, sharedVerificationCommands } from "../contract/final-verification.mjs";
+import { finalVerificationCommands, gateProofTimeoutMs, sharedVerificationCommands } from "../contract/final-verification.mjs";
 import { startJudge, startWorker } from "./dispatch.mjs";
 import { assertEnvironmentReady, captureRunIdentity, createRunMetadata, serializableContract, statesFingerprint } from "./run-identity.mjs";
 import { blockDependents, runtimeAssignments } from "./assignment.mjs";
@@ -120,7 +118,7 @@ export function nodeBudgetBasisMs(contract, node) {
   // finalVerification set with each.
   const attemptMs = packetMs + sharedMs;
   const candidateMs = attemptMs + finalMs;
-  const gateTimeoutMs = Math.max(1_000, Math.min(defaultTimeoutMs, 120_000));
+  const gateTimeoutMs = gateProofTimeoutMs(node, contract);
   const commandProofs = (node.definitionOfDone ?? []).filter((item) => item.proof?.kind === "command").length;
   return defaultTimeoutMs + attemptMs + candidateMs + commandProofs * gateTimeoutMs + finalMs;
 }
@@ -238,6 +236,19 @@ export async function runContract(contractPath, options = {}) {
   }
   const lock = acquireLock(runDir);
   try {
+    // `contract.json` is written before anything else claims a name outside
+    // this directory, because `cancel` is the only verb that releases those
+    // names and it reads the contract from here. Everything below can fail or
+    // be killed -- `runtimeAssignments` probes providers, `captureRunIdentity`
+    // shells out to git, `createRunRef` claims `refs/faberun/<id>/run` -- and a
+    // launch that died between the ref and this write used to leave an
+    // occupied ref plus a run directory `cancel` could not parse: the operator
+    // was refused the directory, deleted it, was then refused the ref, and had
+    // no single verb for either. Written first, the directory is always
+    // cancellable from the instant it exists.
+    mkdirSync(join(runDir, "nodes"), { recursive: true });
+    mkdirSync(join(runDir, "logs"), { recursive: true });
+    writeJsonAtomic(join(runDir, "contract.json"), serializableContract(contract));
     const runtimePlan = await runtimeAssignments(contract);
     const scopeBoundaries = captureNodeScopeBoundaries(contract);
     const sourceIdentity = await captureRunIdentity(contract, scopeBoundaries);
@@ -245,9 +256,6 @@ export async function runContract(contractPath, options = {}) {
     lock.assert();
     const runsDir = runsRoot(contract.cwd);
     const campaign = resolveCampaign(runsDir, contract.campaignId);
-    mkdirSync(join(runDir, "nodes"), { recursive: true });
-    mkdirSync(join(runDir, "logs"), { recursive: true });
-    writeJsonAtomic(join(runDir, "contract.json"), serializableContract(contract));
     writeJsonAtomic(join(runDir, "judge.schema.json"), JUDGE_SCHEMA);
     writeJsonAtomic(join(runDir, "run.json"), createRunMetadata(lock, sourceIdentity, {}, integrationRef));
     registerRun(campaign.path, contract.id);
@@ -755,20 +763,3 @@ export async function driveRun(contract, runDir, states, campaign, lock, sourceI
   }
   return { runDir, states, ok: failed.length === 0 };
 }
-
-/**
- * @param {string} runDir
- * @param {ValidatedContract} contract
- * @returns {NodeSnapshot[]}
- */
-export function readRunNodes(runDir, contract) {
-  const names = listNodeSnapshots(runDir);
-  const expected = new Map(contract.nodes.map((node) => [`${node.id}.json`, node]));
-  for (const name of names) if (!expected.has(name)) throw new TypeError(`unexpected persisted node snapshot ${name}`);
-  return contract.nodes.map((node) => {
-    const name = `${node.id}.json`;
-    if (!names.includes(name)) throw new TypeError(`missing persisted node snapshot ${name}`);
-    return validateNodeSnapshot(readNodeSnapshot(runDir, node.id), node);
-  });
-}
-

package/src/engine/scope.mjs

@@ -15,7 +15,7 @@ import { SETTLED } from "./prompts.mjs";
 import { appendTransitionEvent, recordExecutionOverride, transition, writeNode } from "./state.mjs";
 import { attemptWorkspace } from "../repo/worktree.mjs";
 
-import { errorCode, errorMessage, excerpt, isContained } from "../util.mjs";
+import { errorCode, errorMessage, excerpt, isContained, shellWords } from "../util.mjs";
 import { executeControllerVerification } from "./verify.mjs";
 import { providerReceiptsFromInvocationTail, settleInvocation } from "../run/operations.mjs";
 import { readJson } from "../run/store.mjs";
@@ -108,10 +108,17 @@ export function workerScope(taskPacket) {
 
 /**
  * Everything a node's own proofs name: a Definition of Done `path` proof's
- * path, the words of a `command` proof (a command proof carries a display
- * string, not an argv, so a quoted path holding a space is not recovered), the
- * argv of the verification entry a `verification` proof references, and the
- * argv of every verification command the packet declares.
+ * path, the words of a `command` proof, the argv of the verification entry a
+ * `verification` proof references, and the argv of every verification command
+ * the packet declares.
+ *
+ * A command proof carries a display string, not an argv, so its words are
+ * recovered with `shellWords` rather than a whitespace split -- the split lost
+ * exactly what the shell it runs under preserves. Measured 2026-09-22:
+ * `spawn(ref, {shell: true})` hands the whole string to `sh -c`, which groups
+ * `"b c"` into one argument, while the split here cut it into `"b` and `c"`,
+ * so a proof naming a real path with a space cited two fragments that matched
+ * no file and the write it excused read as unexpected.
  *
  * @param {ValidatedNode} node
  * @returns {ProofCitation[]}
@@ -129,7 +136,7 @@ function proofCitations(node) {
     if (proof.kind === "path") {
       citations.push({ tokens: [proof.ref], cwd: ".", literal: true, citation: `${item.id} path proof` });
     } else if (proof.kind === "command") {
-      citations.push({ tokens: proof.ref.split(/\s+/u), cwd: ".", literal: false, citation: `${item.id} command proof` });
+      citations.push({ tokens: shellWords(proof.ref), cwd: ".", literal: false, citation: `${item.id} command proof` });
     } else {
       const command = commands[Number.parseInt(proof.ref, 10)];
       if (command) citations.push({ tokens: command.argv, cwd: command.cwd ?? ".", literal: false, citation: `${item.id} verification[${proof.ref}] proof` });

package/src/host/home.mjs

@@ -154,3 +154,41 @@ function parseVersion(text) {
   if (!match) return null;
   return [Number(match[1]), Number(match[2]), Number(match[3])];
 }
+
+/**
+ * How old a cached update check may be and still be repeated as a fact about
+ * the world. The banner and the notification message read the cache and never
+ * the network -- a version hint must not put a request in front of every
+ * command -- so the cache is only ever as fresh as the last
+ * `faberun update --check` somebody remembered to run. Measured 2026-09-22 on
+ * the owner's machine: `update-check.json` was five days old and still named
+ * 0.10.0 as the latest release while 0.19.0 was being cut.
+ *
+ * A week is the bound, not a refresh: past it the hint stops being shown
+ * rather than being re-fetched, because a stale claim asserted with authority
+ * is worse than no claim. The command that does reach the network is
+ * unaffected, and the file keeps its `checkedAt` either way.
+ */
+export const UPDATE_CHECK_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+/**
+ * The newer release a still-fresh cached check names, or null: no cache, a
+ * cache older than the window, a cache timestamped in the future (a record
+ * that would otherwise never expire), or a `latest` that is not newer than
+ * what is running. The one home of the "is there an update to mention" rule,
+ * so the banner and the notification message cannot come to disagree.
+ *
+ * @param {string} home
+ * @param {string} version the version actually running
+ * @param {number} [now] epoch milliseconds, injected by tests
+ * @returns {string|null}
+ */
+export function availableUpdate(home, version, now = Date.now()) {
+  const check = readUpdateCheck(home);
+  if (!check) return null;
+  const checkedAt = Date.parse(check.checkedAt);
+  if (!Number.isFinite(checkedAt)) return null;
+  const age = now - checkedAt;
+  if (age < 0 || age > UPDATE_CHECK_MAX_AGE_MS) return null;
+  return compareVersions(check.latest, version) > 0 ? check.latest : null;
+}

package/src/host/preflight.mjs

@@ -50,7 +50,7 @@ import { availabilityKey, readAvailability, recordAvailability } from "../run/av
 /** @typedef {import("../harnesses/index.mjs").CapabilityRequirements} CapabilityRequirements */
 /** @typedef {import("../harnesses/index.mjs").ProbeResult} ProbeResult */
 /** @typedef {import("../engine/runtime-discovery.mjs").RuntimeAvailability} RuntimeAvailability */
-/** @typedef {Map<string, {runtime: RuntimeSnapshot, requiredCapabilitySets: CapabilityRequirements[]}>} ReachableRuntimes */
+/** @typedef {Map<string, {runtime: RuntimeSnapshot, requiredCapabilitySets: CapabilityRequirements[], routed: boolean}>} ReachableRuntimes */
 /** @typedef {{name: string, ok: boolean, advisory: boolean, detail: string}} EnvCheck */
 /** @typedef {{schemaVersion: number, ok: boolean, checks: EnvCheck[]}} EnvReport */
 
@@ -169,9 +169,19 @@ export function checkWorktree(cwd, requireClean) {
 }
 
 /**
- * Every runtime the run can route to — initial and failover — must resolve to
- * a binary that exists and reports a version. A version-less runtime is fatal
- * up front because a resume refuses a runtime whose probe came back null.
+ * Every runtime the run committed to — a node's or a default's named runtime,
+ * and the failover target it declares — must resolve to a binary that exists
+ * and reports a version. A version-less runtime is fatal up front because a
+ * resume refuses a runtime whose probe came back null.
+ *
+ * A runtime that is merely a candidate is held to a weaker rule: at least one
+ * of them has to resolve. A role that names no runtime lets availability
+ * discovery choose at dispatch, so every catalogue entry is reachable without
+ * any of them being chosen, and demanding a binary for each of them refused a
+ * run over a harness it would never have started. Measured 2026-09-21 on the
+ * owner's machine: `codex reported no version` blocked a launch whose work was
+ * routed to `zcode`. What is still fatal is a catalogue where nothing resolves
+ * — then there is no route at all, and discovery has nothing to choose.
  *
  * @param {ReachableRuntimes} runtimes
  * @param {Record<string, string|null>} harnessVersions
@@ -182,20 +192,34 @@ export function checkRuntimeBinaries(runtimes, harnessVersions, cwd = ".") {
   /** @type {string[]} */
   const problems = [];
   /** @type {string[]} */
+  const unavailableCandidates = [];
+  /** @type {string[]} */
   const resolved = [];
-  for (const [id, { runtime }] of runtimes) {
+  let candidates = 0;
+  let candidatesResolved = 0;
+  for (const [id, { runtime, routed }] of runtimes) {
     // The harness owns the resolution: a per-runtime executable, an
     // FABERUN_*_BIN override, and each harness's default binary all
     // land here, and a relative path belongs to the run cwd, not to ours.
     const executable = getHarness(runtime.harness).executable(runtime);
     const found = findExecutable(executable.includes("/") || executable.includes("\\") ? resolve(cwd, executable) : executable);
     const version = harnessVersions[id] ?? null;
-    if (found === null) problems.push(`${id}: ${executable} not found on PATH`);
-    else if (version === null) problems.push(`${id}: ${executable} reported no version`);
-    else resolved.push(`${id} ${version}`);
+    if (!routed) candidates += 1;
+    const problem = found === null
+      ? `${id}: ${executable} not found on PATH`
+      : version === null ? `${id}: ${executable} reported no version` : null;
+    if (problem === null) {
+      resolved.push(`${id} ${version}`);
+      if (!routed) candidatesResolved += 1;
+    } else if (routed) problems.push(problem);
+    else unavailableCandidates.push(problem);
   }
   if (problems.length) return fail("runtime binaries", problems.join(" · "));
-  return pass("runtime binaries", resolved.length ? resolved.join(" · ") : "no routed runtime");
+  if (candidates > 0 && candidatesResolved === 0) {
+    return fail("runtime binaries", `no catalogue runtime resolves, so availability discovery has nothing to choose: ${unavailableCandidates.join(" · ")}`);
+  }
+  const aside = unavailableCandidates.length ? ` · not candidates: ${unavailableCandidates.join(" · ")}` : "";
+  return pass("runtime binaries", resolved.length ? `${resolved.join(" · ")}${aside}` : "no routed runtime");
 }
 
 /**
@@ -360,10 +384,10 @@ export function timeVerificationCommands(contract, probes = {}) {
  * can take only one hop, and its reachable set stops at B.
  *
  * @param {ValidatedContract} contract
- * @returns {Map<string, {runtime: RuntimeSnapshot, requiredCapabilitySets: import("../harnesses/index.mjs").CapabilityRequirements[]}>}
+ * @returns {ReachableRuntimes}
  */
 export function reachableRuntimes(contract) {
-  /** @type {Map<string, {runtime: RuntimeSnapshot, requiredCapabilitySets: import("../harnesses/index.mjs").CapabilityRequirements[]}>} */
+  /** @type {ReachableRuntimes} */
   const runtimes = new Map();
   for (const node of contract.nodes) {
     for (const role of /** @type {("worker"|"judge")[]} */ (["worker", ...(node.gate.enabled ? ["judge"] : [])])) {
@@ -384,14 +408,22 @@ export function reachableRuntimes(contract) {
         ? [runtime.requiredCapabilities, node.gate.requiredCapabilities]
         : [runtime.requiredCapabilities, node.requiredCapabilities];
       const requiredCapabilitySets = required.filter((item) => item !== undefined);
-      addRuntimeRequirement(runtimes, runtime, requiredCapabilitySets);
+      if (explicit) addRuntimeRequirement(runtimes, runtime, requiredCapabilitySets);
       const current = { node, role, runtimeId: /** @type {string} */ (runtime.id) };
       for (const fallbackRuntime of failoverTargets(contract, current)) {
-        addRuntimeRequirement(runtimes, fallbackRuntime, requiredCapabilitySets);
+        addRuntimeRequirement(runtimes, fallbackRuntime, requiredCapabilitySets, Boolean(explicit));
       }
       if (!explicit) {
+        // Nothing names a runtime for this role, so availability discovery
+        // picks one at dispatch and every catalogue entry is a candidate --
+        // including the stand-in above, which was chosen as "the first entry"
+        // and is no more routed than the rest. They are reachable, so their
+        // capabilities still have to hold, but none of them is a runtime this
+        // run committed to: requiring a binary for each turned one absent
+        // harness into a refusal of a run that would never have used it. The
+        // loop covers the stand-in as well -- it is one of the keys.
         for (const candidate of Object.keys(contract.runtimes)) {
-          addRuntimeRequirement(runtimes, runtimeSnapshot(contract, candidate), requiredCapabilitySets);
+          addRuntimeRequirement(runtimes, runtimeSnapshot(contract, candidate), requiredCapabilitySets, false);
         }
       }
     }