faberun 0.18.0 → 0.19.1

package/integrations/claude-code/statusline.sh

@@ -31,6 +31,15 @@ ALLOWANCE_WARN_PCT=85
 
 session=$(cat)
 repo=$(printf '%s' "$session" | sed -n 's/.*"cwd":"\([^"]*\)".*/\1/p;s/.*"current_dir":"\([^"]*\)".*/\1/p' | head -n 1)
+# A Windows session names its cwd with backslashes, and JSON doubles them.
+# Three forms of one path, because three readers want different ones:
+#   repo_json  as it appears in the file -- what a fixed-string grep matches
+#   repo       the path itself           -- what jq compares a parsed key to
+#   repo_path  with forward slashes      -- what a POSIX shell can stat
+# On a host with no backslashes in its paths all three are the same string.
+repo_json=$repo
+repo=$(printf '%s' "$repo_json" | sed 's|\\\\|\\|g')
+repo_path=$(printf '%s' "$repo" | tr '\\' '/')
 # The pointer follows the state (R2): the project registry under the faberun
 # home maps the repository's resolved path to an opaque id, and the pointer
 # sits in that project's runs directory. A repository whose runs never moved
@@ -40,6 +49,7 @@ repo=$(printf '%s' "$session" | sed -n 's/.*"cwd":"\([^"]*\)".*/\1/p;s/.*"curren
 # no glob, no newest-by-mtime. That is the half of R6 already true and to
 # keep; the one machine-wide pointer is a later phase, not this lookup.
 home=${FABERUN_HOME:-$HOME/.faberun}
+home=$(printf '%s' "$home" | tr '\\' '/')
 index="$home/projects/index.json"
 id=
 if [ -n "$repo" ] && [ -f "$index" ]; then
@@ -50,10 +60,10 @@ if [ -n "$repo" ] && [ -f "$index" ]; then
     # fixed-string grep for the quoted key picks exactly that one line and
     # the id follows its colon. Fixed-string on purpose: a repo path is
     # data, not a regex.
-    id=$(grep -F "\"$repo\"" "$index" 2>/dev/null | sed -n 's/^.*:[[:space:]]*"\([^"]*\)".*/\1/p')
+    id=$(grep -F "\"$repo_json\"" "$index" 2>/dev/null | sed -n 's/^.*:[[:space:]]*"\([^"]*\)".*/\1/p')
   fi
 fi
-pointer="$repo/.runs/status.json"
+pointer="$repo_path/.runs/status.json"
 if [ -n "$id" ] && [ -d "$home/projects/$id/runs" ]; then
   pointer="$home/projects/$id/runs/status.json"
 fi

package/package.json

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

package/skills/init-agentkit/scripts/install-agentkit.sh

@@ -95,9 +95,17 @@ for f in CLAUDE.md GEMINI.md CURSOR.md AGENT.md; do
   fi
   if [ "$DRY_RUN" = 0 ]; then
     mkdir -p "$(dirname "$link")"
-    ( cd "$(dirname "$link")" && rm -f "$(basename "$f")" && ln -s "$dest" "$(basename "$f")" )
+    # MSYS's `ln -s` copies the file instead of linking it unless told
+    # otherwise, which is exactly how a pointer becomes the real file this
+    # script exists to prevent. `winsymlinks:nativestrict` asks for a real
+    # symlink and fails rather than copying when the host cannot make one
+    # (no Developer Mode, no privilege); the plain `ln -s` after it is that
+    # host's honest fallback, and a no-op variable everywhere else.
+    ( cd "$(dirname "$link")" && rm -f "$(basename "$f")" \
+      && { MSYS=winsymlinks:nativestrict ln -s "$dest" "$(basename "$f")" 2>/dev/null \
+           || ln -s "$dest" "$(basename "$f")"; } )
   fi
-  say "  + $f → $dest" "$G"
+  if [ -L "$link" ]; then say "  + $f → $dest" "$G"; else say "  + $f (copy of $dest; this host makes no symlink)" "$Y"; fi
 done
 
 # --- git hook via core.hooksPath --------------------------------------------

package/src/campaign/chain.mjs

@@ -42,6 +42,7 @@ import { pidAlive, processStartToken } from "../run/lock.mjs";
 import { delay, errorCode, errorMessage } from "../util.mjs";
 import { writeJsonAtomic } from "../run/store.mjs";
 import { runDirectory } from "../run/paths.mjs";
+import { gitArguments, killTarget } from "../host/platform.mjs";
 
 /** @typedef {import("../contract/index.mjs").ControllerIdentity} ControllerIdentity */
 /** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
@@ -140,7 +141,7 @@ function groupKill(pid, signal) {
         if (errorCode(error) !== "ESRCH") throw error;
       }
     }
-    process.kill(pid, signal);
+    killTarget(pid, signal);
   } catch (error) {
     if (errorCode(error) !== "ESRCH") throw error;
   }
@@ -235,7 +236,7 @@ function landBranchRef(repo, landBranch) {
  */
 function gitHead(repo, ref) {
   try {
-    return execFileSync("git", ["-C", repo, "rev-parse", ref], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || null;
+    return execFileSync("git", gitArguments(["-C", repo, "rev-parse", ref]), { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || null;
   } catch {
     return null;
   }
@@ -269,7 +270,7 @@ export function validateContractAgainstRef(raw, contractPath, context = {}) {
   const originalCwd = resolve(dirname(contractPath), typeof raw.cwd === "string" ? raw.cwd : ".");
   const worktree = mkdtempSync(join(tmpdir(), "runner-chain-ref-"));
   try {
-    execFileSync("git", ["-C", repo, "worktree", "add", "--detach", worktree, baseRef], { stdio: ["ignore", "pipe", "pipe"] });
+    execFileSync("git", gitArguments(["-C", repo, "worktree", "add", "--detach", worktree, baseRef]), { stdio: ["ignore", "pipe", "pipe"] });
     const relativedCwd = relative(repo, originalCwd);
     const mappedCwd = relativedCwd && !relativedCwd.startsWith("..") ? join(worktree, relativedCwd) : worktree;
     const relativeContract = relative(repo, contractPath);
@@ -283,7 +284,7 @@ export function validateContractAgainstRef(raw, contractPath, context = {}) {
     return contract;
   } finally {
     try {
-      execFileSync("git", ["-C", repo, "worktree", "remove", "--force", worktree], { stdio: ["ignore", "pipe", "ignore"] });
+      execFileSync("git", gitArguments(["-C", repo, "worktree", "remove", "--force", worktree]), { stdio: ["ignore", "pipe", "ignore"] });
     } catch {
       // The ref-based validation is done; a cleanup failure must not mask it.
     }

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";
@@ -64,7 +64,16 @@ export function detachArgv(argv, options = {}) {
   const child = /** @type {DetachedChild} */ (spawn(process.execPath, [CLI_ENTRY, ...argv], {
     cwd: process.cwd(),
     env: { ...process.env, ...options.env, FABERUN_BOOTSTRAP_NONCE: nonce },
-    detached: process.platform !== "win32",
+    // Detached on every platform, for a different reason on each. POSIX: a
+    // new session, so the controller survives the launcher's terminal and
+    // owns a process group its own children can be killed by. Windows: libuv
+    // puts every non-detached child in a job object that is killed when the
+    // parent exits, so without this the controller dies the instant the
+    // launcher returns -- measured 2026-09-21: `run --detach` bootstrapped to
+    // `ready` and then died with its launcher, every time, leaving the node
+    // pending forever. There it also means DETACHED_PROCESS: no console
+    // window, which is what "ignore" stdio already implies.
+    detached: true,
     stdio: "ignore",
   }));
   child.unref();

package/src/cli.mjs

@@ -46,7 +46,7 @@ import { cancelRun } from "./engine/cancel.mjs";
 
 import { errorMessage } from "./util.mjs";
 import { validateContract } from "./contract/index.mjs";
-import { setLaunchBaseRef } from "./engine/run-identity.mjs";
+import { setLaunchBaseRef, setFreshPreflight } from "./engine/run-identity.mjs";
 import { assertLaunchBaseClean } from "./repo/source-identity.mjs";
 import { detachSelf, waitForBootstrap, writeBootstrapFailure } from "./cli/launch.mjs";
 import { DEFAULT_SUPERVISE_INTERVAL_SEC, superviseRun } from "./engine/supervise.mjs";
@@ -96,8 +96,8 @@ export function hasDetachedBootstrapNonce() {
 
 /** @type {Record<string, import("node:util").ParseArgsOptionsConfig>} */
 export const COMMAND_OPTIONS = {
-  run: { detach: { type: "boolean" }, "base-ref": { type: "string" } },
-  resume: { detach: { type: "boolean" }, node: { type: "string" }, reconcile: { type: "string" }, answer: { type: "string" } },
+  run: { detach: { type: "boolean" }, "base-ref": { type: "string" }, "fresh-preflight": { type: "boolean" } },
+  resume: { detach: { type: "boolean" }, node: { type: "string" }, reconcile: { type: "string" }, answer: { type: "string" }, "fresh-preflight": { type: "boolean" } },
   supervise: { detach: { type: "boolean" }, interval: { type: "string" } },
   cancel: {},
   preflight: { static: { type: "boolean" }, json: { type: "boolean" }, "time-verification": { type: "boolean" } },
@@ -323,6 +323,7 @@ async function main(argv) {
     const contract = validateContractForLaunch(JSON.parse(readFileSync(absolute, "utf8")), absolute, { baseRef });
     const runDir = runDirectory(contract.cwd, contract.id);
     setLaunchBaseRef(baseRef);
+    setFreshPreflight(values["fresh-preflight"] === true);
     // The base is what every worktree is cut from; a dirty tree only blocks
     // when the cwd HEAD *is* that base. A `--base-ref` elsewhere leaves the
     // operator's checkout out of the run entirely. The contract file being
@@ -334,7 +335,10 @@ async function main(argv) {
     if (values.detach === true) {
       if (existsSync(runDir)) throw new Error(`run already exists: ${runDir}`);
       for (const warning of [...contract.warnings, ...reusedDoneWarnings(contract)]) process.stdout.write(`${advisoryToken()} ${warning}\n`);
-      const child = detachSelf("run", target, baseRef ? ["--base-ref", baseRef] : []);
+      const child = detachSelf("run", target, [
+        ...(baseRef ? ["--base-ref", baseRef] : []),
+        ...(values["fresh-preflight"] === true ? ["--fresh-preflight"] : []),
+      ]);
       const pid = child.pid;
       if (pid === undefined) throw new Error("detached child has no pid");
       await waitForBootstrap(runDir, pid, child);
@@ -348,6 +352,7 @@ async function main(argv) {
   }
   if (command === "resume") {
     const resumeOptions = resumeOptionsOf(values);
+    setFreshPreflight(values["fresh-preflight"] === true);
     if (values.detach === true) {
       const runDir = resolve(target);
       if (!existsSync(join(runDir, "contract.json"))) throw new Error(`not a run directory: ${runDir}`);
@@ -355,6 +360,7 @@ async function main(argv) {
         ...(resumeOptions.node ? ["--node", resumeOptions.node] : []),
         ...(resumeOptions.reconcile ? ["--reconcile", resumeOptions.reconcile] : []),
         ...(resumeOptions.answer ? ["--answer", `${resumeOptions.answer.node}=${resumeOptions.answer.path}`] : []),
+        ...(values["fresh-preflight"] === true ? ["--fresh-preflight"] : []),
       ];
       const child = detachSelf("resume", target, extraArgs);
       const pid = child.pid;

package/src/contract/index.mjs

@@ -15,7 +15,7 @@ import { assertObject, boundedString, nonNegativeInteger, nonNegativeNumber, pos
 import { validateMetadata } from "./schema-version.mjs";
 import { assertRuntimeExecutesCommands, requireRuntime, validateRuntime } from "./runtime.mjs";
 import { validateSourceIdentity } from "../repo/source-identity.mjs";
-import { commandCoverageWarnings, unsnapshottedWriteWarnings } from "../repo/declared-paths.mjs";
+import { commandCoverageWarnings, mirrorCoverageWarnings, unsnapshottedWriteWarnings } from "../repo/declared-paths.mjs";
 import { crossNodeScopeFindings, scopeClosureFindings } from "../repo/scope-closure.mjs";
 
 export { CONTRACT_VERSION, PROTOCOL_SCHEMA_VERSION } from "../harnesses/index.mjs";
@@ -368,8 +368,15 @@ export function validateContract(raw, contractPath, options = {}) {
     throw new TypeError(`task packet scope does not close; declare in readFiles or writeFiles, or acknowledge in scopeAcknowledged: ${scopeErrors.join("; ")}`);
   }
 
+  // Validated here rather than inline below, because the mirror warning reads
+  // them: a layer covered by a shared or final command is covered.
+  const finalVerification = validateFinalVerification(raw.finalVerification, "contract.finalVerification");
+  const sharedVerification = validateSharedVerification(raw.sharedVerification, "contract.sharedVerification");
+  const contractCommands = [...finalVerification ?? [], ...sharedVerification ?? []].map((command) => command.argv.join(" "));
+  const contractWrites = new Set(nodes.flatMap((node) => node.taskPacket.writeFiles ?? []));
   const warnings = nodes.flatMap((node, index) => [
     ...commandCoverageWarnings(node, index),
+    ...(persisted ? [] : mirrorCoverageWarnings(node, index, cwd, contractCommands, contractWrites)),
     ...(persisted ? [] : unsnapshottedWriteWarnings(node, index, cwd)),
     ...(persisted ? [] : writeFileLineBudgetWarnings(node, index, cwd)),
   ]);
@@ -394,8 +401,8 @@ export function validateContract(raw, contractPath, options = {}) {
     // count, because it began with 200k tokens of context instead of 45k and
     // re-read them on every request.
     phaseSessionReuse: booleanField(raw.phaseSessionReuse, false, "contract.phaseSessionReuse"),
-    finalVerification: validateFinalVerification(raw.finalVerification, "contract.finalVerification"),
-    sharedVerification: validateSharedVerification(raw.sharedVerification, "contract.sharedVerification"),
+    finalVerification,
+    sharedVerification,
     nodeAdvisory: validateNodeAdvisory(raw.nodeAdvisory),
     warnings,
   });
@@ -688,6 +695,12 @@ function dependencyCoversPath(closure, path, cwd) {
 function writeFileLineBudgetWarnings(node, index, cwd) {
   const warnings = [];
   for (const path of node.taskPacket.writeFiles ?? []) {
+    // The ceiling is a rule about source modules, and `source-shape` enforces
+    // it over `.mjs` alone. Measured 2026-09-22: a packet declaring the
+    // generated `docs/COMMANDS.md` was warned that 1141 lines left "-341 from
+    // the 800-line ceiling", which is not a budget, not true of that file, and
+    // trains the reader to skim past the warnings that are.
+    if (!path.endsWith(".mjs")) continue;
     let text;
     try {
       text = readFileSync(resolve(cwd, path), "utf8");

package/src/contract/task-packet.mjs

@@ -325,6 +325,14 @@ function validateRelativePath(path, label, cwd, mustExist, options = {}) {
   }
   if (!pathInside(realAnchor, realCwd)) throw new TypeError(`${label} escapes cwd`);
 
+  if (!existsSync(absolute) && anchor !== absolute && statSync(anchor).isFile()) {
+    // Nothing can ever appear beneath a regular file, so this path is refused
+    // outright rather than deferred to a dependency that might produce it.
+    // Only POSIX states that through an errno (ENOTDIR, from the walk above);
+    // Windows reports the same layout as a plain absence, so the shape is
+    // asked here rather than read off a platform error code.
+    throw new TypeError(`${label} is under a file, not a directory: ${path}`);
+  }
   if (!mustExist && !existsSync(absolute)) return;
   if (!existsSync(absolute)) {
     if (options.deferMissing) return DEFERRED_MISSING;
@@ -390,7 +398,11 @@ function findExistingPath(path) {
       lstatSync(current);
       return current;
     } catch (error) {
-      if (errorCode(error) !== "ENOENT") throw error;
+      // A path whose parent is a regular file is absent, not unreadable:
+      // POSIX says ENOTDIR where Windows says ENOENT, and both mean the same
+      // thing -- keep walking up to the ancestor that does exist.
+      const code = errorCode(error);
+      if (code !== "ENOENT" && code !== "ENOTDIR") throw error;
     }
     const parent = dirname(current);
     if (parent === current) return null;

package/src/engine/bulk-read.mjs

@@ -16,6 +16,7 @@ import { DECLARED_MODEL_CATALOGUES, stableJsonDocument } from "../harnesses/cata
 import { READ_LINE_LIMIT, normalizeProviderResult, providerCommand } from "../harnesses/index.mjs";
 import { appendUsageRecord, emptyUsage, priceUsage } from "../run/usage.mjs";
 import { errorMessage, fail } from "../util.mjs";
+import { spawnInvocation } from "../host/platform.mjs";
 import { DISCOVERY_RUNTIME_DEFINITIONS } from "./runtime-discovery.mjs";
 
 /** Fixed-size copy buffer: the pack is built through this, never through a corpus-sized string. */
@@ -178,10 +179,15 @@ function invokeDelegation(runtime, prompt, cwd) {
     /** @type {import("node:child_process").ChildProcess} */
     let child;
     try {
-      child = spawn(command.executable, command.args, {
+      // The provider binary, reached the way this platform reaches one: a
+      // delegation that spawns it raw is ENOENT on Windows against the very
+      // CLI the run is configured to use.
+      const invocation = spawnInvocation(command.executable, command.args, { cwd });
+      child = spawn(invocation.command, invocation.args, {
         cwd,
         env: environmentWith(command.env),
         stdio: ["pipe", "pipe", "pipe"],
+        ...invocation.options,
       });
     } catch (error) {
       observation.spawnError = errorMessage(error);

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/gate.mjs

@@ -31,6 +31,7 @@ import { existsSync, readFileSync, statSync, openSync, closeSync, readSync, writ
 import { dirname } from "node:path";
 import { spawn } from "node:child_process";
 import { NOTIFY_ENV_NAMES } from "../notify/index.mjs";
+import { killTarget, spawnInvocation } from "../host/platform.mjs";
 
 /** @typedef {{executable: string, args: string[], cwd: string, promptTransport: "stdin"|"argv", harness: string, env: Record<string, string|null>|null, stdoutPath: string, stderrPath: string}} GateConfig */
 
@@ -92,13 +93,24 @@ if (config.promptTransport === "stdin") {
 
 /** @param {NodeJS.Signals} signal */
 function killGroup(signal) {
-  try { process.kill(-process.pid, signal); } catch {
+  try {
+    // `killTarget` reads the negative pid as the group on POSIX and as the tree
+    // to walk on Windows, which has no group to signal.
+    killTarget(-process.pid, signal);
+  } catch {
     // ESRCH: the process group is already gone, so there is nothing to signal.
   }
 }
 
 function stopProvider() {
-  try { provider?.kill("SIGTERM"); } catch {
+  try {
+    // The tree, not the process: on Windows a harness installed as a `.cmd` is
+    // reached through the command interpreter, so the provider this gate holds
+    // is `cmd.exe` and the harness is its child. Killing the one it spawned
+    // leaves the other running — measured 2026-09-20, as stranded `node`
+    // processes outliving a suite that had already stopped waiting for them.
+    if (provider?.pid) killTarget(provider.pid, "SIGTERM");
+  } catch {
     // No provider yet, or it already exited: a failed SIGTERM needs no action.
   }
   setTimeout(() => killGroup("SIGKILL"), 100).unref();
@@ -181,10 +193,12 @@ const timer = setInterval(() => {
   clearInterval(timer);
   const stdoutFd = openSync(config.stdoutPath, "wx", 0o600);
   const stderrFd = openSync(config.stderrPath, "wx", 0o600);
-  provider = spawn(config.executable, config.args, {
+  const invocation = spawnInvocation(config.executable, config.args, { cwd: config.cwd });
+  provider = spawn(invocation.command, invocation.args, {
     cwd: config.cwd,
     env: childEnv(),
     stdio: [config.promptTransport === "stdin" ? "pipe" : "ignore", stdoutFd, stderrFd],
+    ...invocation.options,
   });
   if (config.promptTransport === "stdin") {
     for (const chunk of pendingInput) provider.stdin?.write(chunk);

package/src/engine/judge-gate.mjs

@@ -15,6 +15,8 @@ import { isAbsolute, resolve } from "node:path";
 import { reviewMode, UNCITED_REJECTION_REASON } from "../contract/review-modes.mjs";
 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 */
@@ -173,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(", ");
@@ -284,8 +281,7 @@ function terminateProofGroup(child) {
   if (!pid) return;
   const signal = (/** @type {NodeJS.Signals} */ name) => {
     try {
-      if (process.platform !== "win32") process.kill(-pid, name);
-      else child.kill(name);
+      killTarget(process.platform === "win32" ? pid : -pid, name);
     } catch {
       try { child.kill(name); } catch {
         // ESRCH: the group and the leader are already gone.

package/src/engine/live-preflight.mjs

@@ -17,6 +17,7 @@ import { errorMessage } from "../util.mjs";
 import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { normalizeProviderResult, probeRuntime, providerCommand } from "../harnesses/index.mjs";
+import { killTarget, spawnInvocation } from "../host/platform.mjs";
 import { reachableRuntimes } from "../host/preflight.mjs";
 import { spawn } from "node:child_process";
 import { boundedGitSync } from "../repo/worktree.mjs";
@@ -34,16 +35,48 @@ import { runsRoot } from "../run/paths.mjs";
 const LIVE_PREFLIGHT_PROMPT = "Respond with exactly FABERUN_PREFLIGHT_OK and do not use tools.";
 const LIVE_PREFLIGHT_OUTPUT_LIMIT_BYTES = 512 * 1024;
 /**
+ * `persisted` is for the dispatch gate, which hands over the run's own
+ * serialized contract: that one was validated when it was authored, and
+ * re-running the filesystem-dependent checks against the checkout reaches a
+ * different answer for a run launched with `--base-ref`, whose declared paths
+ * live in the ref and not in the working tree. Measured 2026-09-22: without
+ * it the gate refused a `--base-ref` run with "readFiles[0] does not exist".
+ * The CLI's own `preflight <contract>` leaves it off on purpose -- there the
+ * contract is an authored file the operator is asking about, so validating it
+ * whole is part of the answer.
+ *
  * @param {string} contractPath
- * @param {{static?: boolean, liveTimeoutSec?: number}} [options]
+ * @param {{static?: boolean, liveTimeoutSec?: number, persisted?: boolean}} [options]
  * @returns {Promise<ProbeResult[]>}
  */
 export async function preflightContract(contractPath, options = {}) {
   const absoluteContractPath = resolve(contractPath);
-  const contract = validateContract(JSON.parse(readFileSync(absoluteContractPath, "utf8")), absoluteContractPath);
-  const runtimes = reachableRuntimes(contract);
-  const staticChecks = await Promise.all([...runtimes.values()].map(({ runtime, requiredCapabilitySets }) =>
-    probeRuntime(runtime, { cwd: contract.cwd, requiredCapabilitySets }),
+  const contract = validateContract(JSON.parse(readFileSync(absoluteContractPath, "utf8")), absoluteContractPath, options.persisted === true ? { persisted: true } : {});
+  return preflightRuntimes([...reachableRuntimes(contract).values()], { ...options, cwd: contract.cwd });
+}
+
+/**
+ * The same ask, entered from a set of runtimes rather than a contract.
+ *
+ * `faberun plan` needs this and a contract cannot give it. Planning contracts
+ * carry no gate (`plan/template.mjs`), and `reachableRuntimes` only counts the
+ * judge role when a node's gate is enabled -- so preflighting the draft
+ * stage's contract asks the planner and never the reviewer, which is reached
+ * only as the *worker* of a later stage's own contract. Asking both before the
+ * first stage therefore has to name the runtimes directly.
+ *
+ * One asking function with two entry points, never two: the live probe, the
+ * throwaway repository, the budget and the detail wording are decided here
+ * once, so a caller cannot accidentally ask a different question.
+ *
+ * @param {{runtime: RuntimeSnapshot, requiredCapabilitySets?: import("../harnesses/index.mjs").CapabilityRequirements[]}[]} entries
+ * @param {{static?: boolean, liveTimeoutSec?: number, cwd?: string}} [options]
+ * @returns {Promise<ProbeResult[]>}
+ */
+export async function preflightRuntimes(entries, options = {}) {
+  const runtimes = entries.map((entry) => entry.runtime);
+  const staticChecks = await Promise.all(entries.map(({ runtime, requiredCapabilitySets }) =>
+    probeRuntime(runtime, { cwd: options.cwd, requiredCapabilitySets }),
   ));
   if (options.static === true) return staticChecks;
 
@@ -62,8 +95,7 @@ export async function preflightContract(contractPath, options = {}) {
   }
   try {
     return await Promise.all(staticChecks.map(async (check, index) => {
-      const runtime = [...runtimes.values()][index].runtime;
-      const live = await livePreflight(runtime, liveRepo, timeoutSec);
+      const live = await livePreflight(runtimes[index], liveRepo, timeoutSec);
       const liveDetail = live.status === "done"
         ? `live done · usage ${formatUsage(live.usage)} · cost ${formatCost(live.costUsd)}`
         : `live ${live.status} · ${live.error?.code ?? "provider_error"}: ${redactProviderText(live.error?.message ?? "generation failed")} · usage ${formatUsage(live.usage)} · cost ${formatCost(live.costUsd)}`;
@@ -146,11 +178,13 @@ function livePreflight(runtime, cwd, timeoutSec) {
         else env[key] = value;
       }
       delete env.FABERUN_NOTIFY_BIN;
-      child = /** @type {import("node:child_process").ChildProcessWithoutNullStreams} */ (spawn(command.executable, command.args, {
+      const invocation = spawnInvocation(command.executable, command.args, { cwd });
+      child = /** @type {import("node:child_process").ChildProcessWithoutNullStreams} */ (spawn(invocation.command, invocation.args, {
         cwd,
         env,
         detached: process.platform !== "win32",
         stdio: [command.promptTransport === "stdin" ? "pipe" : "ignore", "pipe", "pipe"],
+        ...invocation.options,
       }));
     } catch (error) {
       settle({
@@ -182,8 +216,7 @@ function livePreflight(runtime, cwd, timeoutSec) {
     /** @param {NodeJS.Signals} name */
     const signal = (name) => {
       try {
-        if (process.platform === "win32") child.kill(name);
-        else process.kill(-/** @type {number} */ (child.pid), name);
+        killTarget(process.platform === "win32" ? /** @type {number} */ (child.pid) : -/** @type {number} */ (child.pid), name);
       } catch {
         // ESRCH: the child is already gone, so there is no process to signal.
       }