faberun 0.19.0 → 0.19.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faberun",
-  "version": "0.19.0",
+  "version": "0.19.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/cli/brand.mjs

@@ -9,7 +9,7 @@
  * untouched.
  */
 
-import { compareVersions, faberunHome, readUpdateCheck } from "../host/home.mjs";
+import { availableUpdate, faberunHome } from "../host/home.mjs";
 
 /** @typedef {"brand"|"ok"|"progress"|"warn"|"fail"|"muted"|"text"} Role */
 /** @typedef {"terra"|"argila"|"folha"} ColorName */
@@ -150,16 +150,15 @@ export function statusToken(kind, level) {
  * opening is muted, the wordmark is the brand role, the tagline is plain text
  * and the last line is muted and filled from the running process. The last line
  * gains ` · update available: <latest>` when the cached check names a newer
- * release; the banner reads only the cache (`update-check.json`) and never
- * fetches. ASCII apart from the middle-dot separator, so it survives every
+ * release and is still inside `UPDATE_CHECK_MAX_AGE_MS`; the banner reads only
+ * the cache (`update-check.json`) and never fetches. ASCII apart from the middle-dot separator, so it survives every
  * monospace font.
  *
  * @param {BannerOptions} options
  * @returns {string}
  */
 export function renderBanner({ version, nodeVersion, harnessCount, level, env = process.env }) {
-  const cached = readUpdateCheck(faberunHome(env));
-  const latest = cached && compareVersions(cached.latest, version) > 0 ? cached.latest : null;
+  const latest = availableUpdate(faberunHome(env), version);
   const terra = /** @param {string} text @returns {string} */ (text) => colorize(text, { color: "terra" }, level);
   const lines = [
     terra("       .-~~~-."),

package/src/cli/launch.mjs

@@ -20,7 +20,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { join, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
-import { readRunNodes } from "../engine/scheduler.mjs";
+import { readRunNodes } from "../run/node-store.mjs";
 import { spawn } from "node:child_process";
 import { validateContract } from "../contract/index.mjs";
 import { runDirectory } from "../run/paths.mjs";

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/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, 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));
@@ -434,8 +434,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

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,13 +37,11 @@ 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 { startJudge, startWorker } from "./dispatch.mjs";
 import { assertEnvironmentReady, captureRunIdentity, createRunMetadata, serializableContract, statesFingerprint } from "./run-identity.mjs";
@@ -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);
         }
       }
     }

package/src/plan/pipeline.mjs

@@ -27,7 +27,7 @@ import { allowanceDelta, allowanceEventFields, sampleAllowance } from "../seat/a
 import { askPlanningRuntimes, refusePlanningSilence } from "./preflight.mjs";
 import { parseSpec, validateSpec } from "./spec.mjs";
 import { collectRepoFacts } from "./repo-facts.mjs";
-import { RISK_TIERS, buildPlanningContract, validateFindings, validatePlanOutput } from "./template.mjs";
+import { RISK_TIERS, TASK_KIND_CATALOGUE_FILE, buildPlanningContract, renderTaskKindCatalogue, validateFindings, validatePlanOutput } from "./template.mjs";
 import { MIN_WRITE_FILES, applySizingRules, provenParallelism } from "./sizing.mjs";
 import { resolveRuntimes } from "./routing.mjs";
 import { freezePlan } from "./freeze.mjs";
@@ -135,6 +135,12 @@ export async function runPlanningPipeline(options) {
   const repoFactsPath = join(scratchDir, "repo-facts.json");
   writeFileSync(repoFactsPath, `${JSON.stringify(repoFacts, null, 2)}\n`);
   const relativeRepoFactsPath = relative(cwd, repoFactsPath);
+  // The taskKind catalogue is staged like every other planning input. It used
+  // to be handed over as faberun's own `src/plan/template.mjs`, which resolves
+  // against the target repository and therefore exists in exactly one of them.
+  const cataloguePath = join(scratchDir, TASK_KIND_CATALOGUE_FILE);
+  writeFileSync(cataloguePath, renderTaskKindCatalogue());
+  const relativeCataloguePath = relative(cwd, cataloguePath);
   logStage("repo-facts", { gitHead: repoFacts.gitHead });
 
   let n = 0;
@@ -177,7 +183,7 @@ export async function runPlanningPipeline(options) {
     return { contract: validated, output };
   };
 
-  const draft = await runStage("draft", { specPath: relativeSpecPath, repoFactsPath: relativeRepoFactsPath });
+  const draft = await runStage("draft", { specPath: relativeSpecPath, repoFactsPath: relativeRepoFactsPath, cataloguePath: relativeCataloguePath });
   /** @type {PlanOutput|null} */
   let plan = null;
   // Everything still open against the plan in hand, accumulated across rounds
@@ -365,7 +371,7 @@ export async function runPlanningPipeline(options) {
     const findingsPath = join(scratchDir, `findings-round-${round}.json`);
     writeJsonAtomic(findingsPath, findings);
     const revise = await runStage("revise", {
-      specPath: relativeSpecPath, repoFactsPath: relativeRepoFactsPath, findingsPath: relative(cwd, findingsPath),
+      specPath: relativeSpecPath, repoFactsPath: relativeRepoFactsPath, cataloguePath: relativeCataloguePath, findingsPath: relative(cwd, findingsPath),
     });
     // Kept for the write-drop comparison: the plan the revise revised, against
     // the plan it produced.

package/src/plan/template.mjs

@@ -23,25 +23,57 @@ import { validateVerificationCommands } from "../contract/verification.mjs";
 /** @typedef {import("../contract/index.mjs").JsonObject} JsonObject */
 /** @typedef {"draft"|"review"|"revise"|"spec-author"|"spec-review"} PlanningKind */
 /** @typedef {"low"|"standard"|"high"} RiskTier */
-/** @typedef {{campaignId: string, phase: string, n: number, goal?: string, cwd?: string, runtimes: Record<string, JsonObject>, runtimeDefaults: {worker?: string, judge?: string}, specPath?: string, repoFactsPath?: string, planPath?: string, findingsPath?: string, notesPath?: string}} PlanningContractInputs */
+/** @typedef {{campaignId: string, phase: string, n: number, goal?: string, cwd?: string, runtimes: Record<string, JsonObject>, runtimeDefaults: {worker?: string, judge?: string}, specPath?: string, repoFactsPath?: string, cataloguePath?: string, planPath?: string, findingsPath?: string, notesPath?: string}} PlanningContractInputs */
 /** @typedef {{id: string, objective: string, taskKind: string, riskTier: RiskTier, dependsOn: string[], readFiles: string[], writeFiles: string[], scopeAcknowledged: string[], definitionOfDone: import("../contract/definition-of-done.mjs").DefinitionOfDoneItem[], verification: import("../contract/verification.mjs").VerificationCommand[], expectedTurns?: number}} PlanOutputNode */
 /** @typedef {{nodes: PlanOutputNode[], phases?: PlanPhase[], findings?: PlanFindingOutput[], justification?: string}} PlanOutput */
 /** @typedef {{id: string, requirementIds: string[], deliverable: string}} PlanPhase */
 /** @typedef {{id: string, severity: "critical"|"major"|"minor", nodeId: string, text: string}} PlanFindingOutput */
 
-/**
- * The taskKind catalogue a draft or revise classifies against. Exported here,
- * not read from a separate document, so `TASK_KIND_CATALOGUE_PATH` (this
- * module's own repo-relative path) is a real, always-present file a
- * closed-context worker can be told to read for the authoritative list.
- */
+/** The taskKind catalogue a draft or revise classifies against. */
 export const TASK_KINDS = Object.freeze(["docs", "implement", "test", "refactor", "infra", "judge"]);
 
 /** The risk tiers a draft or revise classifies against. */
 export const RISK_TIERS = Object.freeze(["low", "standard", "high"]);
 
-/** This module's own repo-relative path: the taskKind catalogue's home. */
-export const TASK_KIND_CATALOGUE_PATH = "src/plan/template.mjs";
+/**
+ * The file name the planner stages the catalogue under, beside the spec and
+ * the repository facts it already stages.
+ *
+ * This used to be `src/plan/template.mjs` -- this module's own repo-relative
+ * path -- so that a closed-context worker had a real, always-present file to
+ * read for the authoritative list. It is always present in *this* repository.
+ * A planning contract's `readFiles` resolve against the target repository, and
+ * every other repository refuses the contract with `readFiles[2] does not
+ * exist: src/plan/template.mjs`, which made `faberun plan` able to plan only
+ * faberun. The catalogue is data, so it is written out like the other inputs
+ * instead of being pointed at across repository boundaries.
+ */
+export const TASK_KIND_CATALOGUE_FILE = "task-kinds.md";
+
+/**
+ * The catalogue document itself, rendered from the two exported lists so the
+ * file a worker reads and the values `validatePlanOutput` accepts cannot
+ * drift apart.
+ *
+ * @returns {string}
+ */
+export function renderTaskKindCatalogue() {
+  return [
+    "# taskKind and riskTier catalogue",
+    "",
+    "Written by `faberun plan` for this stage. These are the only values a plan may use;",
+    "any other value is rejected when the plan is validated.",
+    "",
+    "## taskKind",
+    "",
+    ...TASK_KINDS.map((kind) => `- ${kind}`),
+    "",
+    "## riskTier",
+    "",
+    ...RISK_TIERS.map((tier) => `- ${tier}`),
+    "",
+  ].join("\n");
+}
 
 /**
  * Which of the caller's `runtimeDefaults` roles resolves this contract's
@@ -62,8 +94,8 @@ const KIND_ROLE = Object.freeze({
 
 /** @type {Record<PlanningKind, string[]>} */
 const REQUIRED_INPUTS = Object.freeze({
-  draft: ["specPath", "repoFactsPath"],
-  revise: ["specPath", "repoFactsPath", "findingsPath"],
+  draft: ["specPath", "repoFactsPath", "cataloguePath"],
+  revise: ["specPath", "repoFactsPath", "cataloguePath", "findingsPath"],
   review: ["specPath", "repoFactsPath", "planPath"],
   "spec-author": ["notesPath"],
   "spec-review": ["specPath"],
@@ -110,7 +142,7 @@ const OBJECTIVES = Object.freeze({
 /** @type {Record<PlanningKind, string[]>} */
 const INSTRUCTIONS = Object.freeze({
   draft: [
-    `Consult ${TASK_KIND_CATALOGUE_PATH}'s exported TASK_KINDS before classifying any node; taskKind must be one of that catalogue and riskTier must be one of ${RISK_TIERS.join(", ")}.`,
+    `Consult the ${TASK_KIND_CATALOGUE_FILE} in readFiles before classifying any node; taskKind must be one of that catalogue and riskTier must be one of ${RISK_TIERS.join(", ")}.`,
     "Declare every phase the plan serves in output.plan.phases: the requirement ids (R<n> from the spec) the phase satisfies and the deliverable it produces in one sentence. A phase associated with no requirement is reported as a finding, not refused.",
     ...SCOPE_CLOSURE_RULE,
     `Return exactly one worker-result JSON object. Put the plan in output.plan as ${PLAN_OUTPUT_SHAPE} and nothing else in output.`,
@@ -156,9 +188,9 @@ const NON_GOALS = Object.freeze({
  * @returns {string[]}
  */
 function readFilesForKind(kind, inputs) {
-  if (kind === "draft") return [/** @type {string} */ (inputs.specPath), /** @type {string} */ (inputs.repoFactsPath), TASK_KIND_CATALOGUE_PATH];
+  if (kind === "draft") return [/** @type {string} */ (inputs.specPath), /** @type {string} */ (inputs.repoFactsPath), /** @type {string} */ (inputs.cataloguePath)];
   if (kind === "revise") {
-    return [/** @type {string} */ (inputs.specPath), /** @type {string} */ (inputs.repoFactsPath), TASK_KIND_CATALOGUE_PATH, /** @type {string} */ (inputs.findingsPath)];
+    return [/** @type {string} */ (inputs.specPath), /** @type {string} */ (inputs.repoFactsPath), /** @type {string} */ (inputs.cataloguePath), /** @type {string} */ (inputs.findingsPath)];
   }
   if (kind === "review") return [/** @type {string} */ (inputs.specPath), /** @type {string} */ (inputs.repoFactsPath), /** @type {string} */ (inputs.planPath)];
   if (kind === "spec-author") return [/** @type {string} */ (inputs.notesPath)];

package/src/report/message.mjs

@@ -28,7 +28,7 @@ import { chooseLanguage, labelsFor } from "./locale.mjs";
 import { readNodeSnapshot } from "../run/node-store.mjs";
 import { campaignDir } from "../campaign/layout.mjs";
 import { readJournal } from "../campaign/journal.mjs";
-import { compareVersions, faberunHome, readUpdateCheck } from "../host/home.mjs";
+import { availableUpdate, faberunHome } from "../host/home.mjs";
 import { packageVersion } from "../host/package.mjs";
 import { boundedUtf8, compactTokens } from "../util.mjs";
 import { SETTLED, SUCCESS } from "../engine/prompts.mjs";
@@ -277,23 +277,23 @@ function footer(view, eventType) {
 }
 
 /**
- * One line when the cached update check names a release newer than the one
- * running. The cache only, never the network: `faberun update --check`
+ * One line when a still-fresh cached update check names a release newer than
+ * the one running. The cache only, never the network: `faberun update --check`
  * refreshes it, and a notification must never wait on a request.
  *
  * @param {(key: string) => string} label
  * @returns {string[]}
  */
 function updateLine(label) {
-  let check;
+  let latest;
   try {
-    check = readUpdateCheck(faberunHome());
+    latest = availableUpdate(faberunHome(), packageVersion());
   } catch {
     // An unreadable install root is the banner's problem to report, not the message's.
     return [];
   }
-  if (!check || compareVersions(check.latest, packageVersion()) <= 0) return [];
-  return [`⬆️ faberun ${check.latest} ${label("available")} · ${label("runUpdate")} faberun update`];
+  if (!latest) return [];
+  return [`⬆️ faberun ${latest} ${label("available")} · ${label("runUpdate")} faberun update`];
 }
 
 /**

package/src/run/node-store.mjs

@@ -11,6 +11,7 @@ import { validateNodeSnapshot } from "../contract/snapshot.mjs";
 
 /** @typedef {ReturnType<typeof import("./lock.mjs").acquire>} LockHandle */
 /** @typedef {import("../contract/index.mjs").NodeSnapshot} NodeSnapshot */
+/** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
 
 const NODES_DIR_NAME = "nodes";
 
@@ -60,3 +61,35 @@ export function listNodeSnapshots(runDir) {
     throw error;
   }
 }
+
+/**
+ * The persisted node snapshots of one run.
+ *
+ * `tolerateMissing` returns only the snapshots that exist instead of refusing
+ * the run. For resume and supervise a node the contract declares and the run
+ * never persisted is corruption and stays fatal; for `cancel` it is the
+ * ordinary shape of what is being cancelled. A launch writes `contract.json`
+ * first and can die before it writes any node -- probing providers, shelling
+ * out to git, claiming the run ref -- and the directory then holds a
+ * contract, an occupied ref and no node state at all. Such a node started
+ * nothing, holds no invocation and no worktree, so there is nothing to
+ * terminate and only the git names to release, which is what cancel is for.
+ *
+ * @param {string} runDir
+ * @param {ValidatedContract} contract
+ * @param {{tolerateMissing?: boolean}} [options]
+ * @returns {NodeSnapshot[]}
+ */
+export function readRunNodes(runDir, contract, options = {}) {
+  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.flatMap((node) => {
+    const name = `${node.id}.json`;
+    if (!names.includes(name)) {
+      if (options.tolerateMissing === true) return [];
+      throw new TypeError(`missing persisted node snapshot ${name}`);
+    }
+    return [validateNodeSnapshot(readNodeSnapshot(runDir, node.id), node)];
+  });
+}

package/src/util.mjs

@@ -229,3 +229,49 @@ export function readJsonTolerant(path) {
 export function finite(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
+
+/**
+ * Split a command string into the words a POSIX shell would pass as argv, for
+ * the two readers handed a command as a display string rather than an argv: a
+ * Definition of Done `command` proof, whose words `engine/scope.mjs` matches
+ * against the files the node wrote, and the node:test filters one declares
+ * (`engine/judge-gate.mjs`). Quotes group and are stripped; whitespace
+ * outside them separates.
+ *
+ * Deliberately not a shell: no expansion, no substitution, no operators, and
+ * no backslash escape -- on Windows a backslash is a path separator and
+ * `C:\Users\x` must survive this intact. The question both callers ask is
+ * "which words does this command name", and a quoted path holding a space is
+ * one word: splitting it on whitespace produced two fragments that matched no
+ * file, so a proof naming a real path read as naming none.
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function shellWords(text) {
+  /** @type {string[]} */
+  const words = [];
+  /** @type {string|null} */
+  let current = null;
+  /** @type {string|null} */
+  let quote = null;
+  for (const character of text) {
+    if (quote === null && /\s/u.test(character)) {
+      if (current !== null) words.push(current);
+      current = null;
+      continue;
+    }
+    if (quote === null && (character === '"' || character === "'")) {
+      quote = character;
+      current ??= "";
+      continue;
+    }
+    if (quote === character) {
+      quote = null;
+      continue;
+    }
+    current = (current ?? "") + character;
+  }
+  if (current !== null) words.push(current);
+  return words;
+}