faberun 0.18.0 → 0.19.0

package/src/host/platform.mjs

@@ -21,7 +21,9 @@
  * `node.exe` and there is no extensionless file beside it, so a lookup that
  * only joins the bare name reports the running interpreter as missing.
  */
-import { existsSync, renameSync, rmSync, symlinkSync } from "node:fs";
+import { Buffer } from "node:buffer";
+import { spawnSync } from "node:child_process";
+import { closeSync, existsSync, openSync, readSync, renameSync, rmSync, symlinkSync } from "node:fs";
 import { delimiter, dirname, isAbsolute, join, resolve } from "node:path";
 
 /**
@@ -109,3 +111,204 @@ function executableCandidates(name) {
   const extensions = (process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").map((extension) => extension.trim().toLowerCase()).filter(Boolean);
   return [...extensions.map((extension) => `${name}${extension}`), name];
 }
+
+/** A command script Windows runs through the command interpreter, not directly. */
+const COMMAND_SCRIPT = /\.(?:cmd|bat)$/iu;
+
+/**
+ * How this platform has to be asked to run `executable` with `args`.
+ *
+ * POSIX hands both back untouched. Windows has two problems with the binaries
+ * a harness actually installs as, and both are this function's business so no
+ * caller has to know about either.
+ *
+ * A command name resolves through `PATHEXT`, and `spawn` does not do it: with
+ * only `claude.cmd` on PATH, `spawn("claude")` is ENOENT. So a bare name is
+ * resolved here first.
+ *
+ * And a `.cmd` or `.bat` cannot be spawned directly at all — node refuses it
+ * with EINVAL since the argument-injection fix — so it runs through
+ * `%ComSpec% /d /s /c`. Every argument is quoted for `CommandLineToArgvW` and
+ * then caret-escaped *twice*: the interpreter consumes one layer parsing the
+ * command line, and the `%*` that every npm-written shim forwards its
+ * arguments with consumes the second. Measured 2026-09-20 on Windows 11 —
+ * with one layer, an argument containing `&` is truncated at it; with two,
+ * spaces, quotes, `&`, `|`, `%`, `^`, `()` and `!` all arrive intact.
+ *
+ * A relative executable — `./my-worker.mjs`, the shape a contract names a
+ * wrapped harness by — is relative to the directory the child will run in, and
+ * the caller is the only one who knows it. Without `cwd` the shebang is looked
+ * for beside *this* process instead, found nowhere, and the spawn fails as
+ * EFTYPE with nothing said about why.
+ *
+ * @param {string} executable
+ * @param {string[]} args
+ * @param {{cwd?: string}} [options] the directory the child will run in
+ * @returns {{command: string, args: string[], options: {windowsVerbatimArguments?: boolean}}}
+ */
+export function spawnInvocation(executable, args, options = {}) {
+  if (process.platform !== "win32") return { command: executable, args, options: {} };
+  const named = executable.includes("/") || executable.includes("\\");
+  const resolved = named
+    ? (options.cwd === undefined ? executable : resolve(options.cwd, executable))
+    : (findExecutable(executable) ?? executable);
+  if (COMMAND_SCRIPT.test(resolved)) {
+    const line = [quoteArgument(resolved), ...args.map((argument) => escapeThroughShim(quoteArgument(argument)))].join(" ");
+    return {
+      command: process.env.ComSpec ?? "cmd.exe",
+      args: ["/d", "/s", "/c", `"${line}"`],
+      options: { windowsVerbatimArguments: true },
+    };
+  }
+  const shebang = interpreterOf(resolved);
+  if (shebang) return { command: shebang[0], args: [...shebang.slice(1), resolved, ...args], options: {} };
+  return { command: resolved, args, options: {} };
+}
+
+/**
+ * The interpreter a `#!` line names, or null when the file has none.
+ *
+ * A shebang is a POSIX kernel feature, so Windows hands the same file back as
+ * EFTYPE. Reading the line and running the interpreter is what cross-spawn —
+ * and therefore npm — does on Windows, and it is the only way an executable
+ * handed over as a POSIX script (`FABERUN_CODEX_BIN` pointed at the
+ * extensionless file npm installs beside its `.cmd`, a harness wrapper written
+ * by hand) runs there at all.
+ *
+ * @param {string} path
+ * @returns {string[]|null} the interpreter and its own arguments
+ */
+function interpreterOf(path) {
+  /** @type {number|undefined} */
+  let handle;
+  try {
+    handle = openSync(path, "r");
+    const head = Buffer.alloc(256);
+    const read = readSync(handle, head, 0, 256, 0);
+    const first = head.subarray(0, read).toString("utf8").split(/\r?\n/u, 1)[0];
+    if (!first.startsWith("#!")) return null;
+    const line = first.slice(2).trim();
+    if (!line) return null;
+    // A whole line that names a real file is the interpreter, spaces and all:
+    // every fixture here is written with `#!${process.execPath}`, and on
+    // Windows that is `C:\Program Files\nodejs\node.exe`. Splitting it on
+    // whitespace the POSIX way would ask for `C:\Program`.
+    if (existsSync(line)) return [line];
+    // An interpreter named by a POSIX path that this host does not have:
+    // `#!/bin/sh` is not a file on Windows, but `sh` is a command there
+    // wherever Git for Windows is installed, which is wherever this tool runs.
+    const named = line.includes(" ") ? null : findExecutable(line.slice(line.lastIndexOf("/") + 1));
+    if (named) return [named];
+    // `#!/usr/bin/env node` names the interpreter in its own argument.
+    const parts = line.split(/\s+/u).filter(Boolean);
+    if (!parts.length) return null;
+    if (/(?:^|[\\/])env(?:\.exe)?$/iu.test(parts[0])) return parts.slice(1).length ? parts.slice(1) : null;
+    return parts;
+  } catch {
+    // Unreadable, a directory, or gone: there is no shebang to honour, and the
+    // spawn below reports the real reason.
+    return null;
+  } finally {
+    if (handle !== undefined) closeSync(handle);
+  }
+}
+
+/**
+ * One argument, quoted the way `CommandLineToArgvW` reads it back: a backslash
+ * run before a quote doubles, and a trailing run doubles so the closing quote
+ * survives.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+function quoteArgument(value) {
+  return `"${String(value).replace(/(\*)"/gu, '$1$1\\"').replace(/(\+)$/u, "$1$1")}"`;
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function escapeThroughShim(value) {
+  return value.replace(/[()%!^"<>&|]/gu, "^$&").replace(/[()%!^"<>&|]/gu, "^$&");
+}
+
+/**
+ * End a process and everything it started, the way this platform can.
+ *
+ * On POSIX the caller passes a negative pid and the kernel signals the whole
+ * process group, which is what every signalling path here already does.
+ * Windows has no process group to signal: `process.kill(pid)` ends that one
+ * process, and the provider a gate spawned — or the `node` a `.cmd` shim
+ * started — keeps running. Measured 2026-09-20: a full suite run on Windows 11
+ * stranded 105 `node -e "setInterval(…)"` fixtures this way, and then hung
+ * waiting for one of them to die.
+ *
+ * `taskkill /T` walks the tree from the pid. `/F` is the only ending Windows
+ * offers a console process, so there is no graceful step to escalate from —
+ * which is why every caller already skips its `SIGKILL` escalation there.
+ * A non-zero exit means no such process, read the way a POSIX `ESRCH` is: the
+ * target is gone, which is not a failure to report.
+ *
+ * @param {number} target a pid, or on POSIX a negative process-group id
+ * @param {string|number} signal
+ * @returns {unknown}
+ */
+export function killTarget(target, signal) {
+  if (process.platform !== "win32") return process.kill(target, signal);
+  const result = spawnSync(join(process.env.SystemRoot ?? "C:\Windows", "System32", "taskkill.exe"), ["/PID", String(Math.abs(target)), "/T", "/F"], { stdio: "ignore" });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw Object.assign(new Error(`taskkill found no process ${Math.abs(target)}`), { code: "ESRCH" });
+  return true;
+}
+
+/**
+ * The `git` argument list every invocation here carries.
+ *
+ * **`core.fsmonitor=false`, on every platform.** A repository with the file
+ * system monitor enabled starts `git fsmonitor--daemon --detach` on first use,
+ * and the daemon outlives the directory it watched. This tool creates a
+ * worktree per attempt and its suite creates a throwaway repository per
+ * fixture, so the daemons accumulate: measured 2026-09-20 on Windows 11, one
+ * afternoon of suite runs left **4810** of them holding 39 GB, until the
+ * machine could not start another test process. Nothing here benefits from a
+ * daemon watching a tree that is about to be deleted.
+ *
+ * **`core.longpaths=true`, on Windows.** It caps a path at 260 characters
+ * unless the program opts out, and git's
+ * own `core.longpaths` is off by default even where the OS itself allows long
+ * paths. The run layout is deep on purpose — `projects/<id>/runs/worktrees/
+ * <run>/<node>.<attempt>` before the repository's own tree begins — so a file
+ * a worker writes a few directories down reaches the cap easily.
+ *
+ * What makes this worth a flag on every call is *how* git fails there.
+ * Measured 2026-09-20 on Windows 11, a repository holding one file at a
+ * 268-character path: `git add --all` exits 0 and tracks nothing. With
+ * `core.longpaths=true` it exits 0 and tracks the file. A tool whose gate is
+ * the diff of what a worker changed cannot afford a git that silently cannot
+ * see part of the tree.
+ *
+ * It does not lift every limit: `git worktree add` dies with `'$GIT_DIR' too
+ * big` once the repository's own `.git/worktrees/<name>` path passes about 160
+ * characters, and that guard is a fixed buffer no configuration reaches.
+ *
+ * **`core.autocrlf=false`, on Windows.** The default there is `true`, and it
+ * rewrites line endings on the way into the index and out of a checkout. This
+ * tool's gate is a byte comparison of what a worker changed, and a rewrite it
+ * did not make is indistinguishable from one it did: measured 2026-09-22 on a
+ * GitHub windows-latest runner, a declared read carried into an attempt
+ * worktree came back changed after passing through git, the scope gate called
+ * it an `unexpected_write`, and the adopted node failed for a file nobody had
+ * touched. The attempt worktree is this tool's own directory and its content
+ * is what the run commits; the operator's checkout keeps whatever they
+ * configured.
+ *
+ * @param {string[]} args
+ * @returns {string[]}
+ */
+export function gitArguments(args) {
+  const platformArgs = process.platform === "win32"
+    ? ["-c", "core.longpaths=true", "-c", "core.autocrlf=false"]
+    : [];
+  return ["-c", "core.fsmonitor=false", ...platformArgs, ...args];
+}

package/src/host/preflight.mjs

@@ -8,6 +8,17 @@
  * report as run evidence and stops, so the operator fixes the host and
  * resumes instead of starting over and paying for the finished nodes twice.
  *
+ * A version is not a verdict: a binary that answered `--version` can still
+ * hold a dead credential or a spent quota. With a contract, `doctor` asks
+ * each routed runtime the same live question the dispatch gate asks and
+ * reports that verdict beside the version checks — the `models` surfaces
+ * name this report the authoritative word on availability — and without a
+ * contract it says plainly that it asked nothing. The verdict is the
+ * report, not the gate: a runtime with no answer is a finding on its own
+ * line, while the exit code keeps answering the host-fact question it
+ * always answered, because blocking on silence is the dispatch gate's job
+ * and it blocks on exactly those causes.
+ *
  * A check may be advisory, meaning it reports a fact without blocking: a
  * merely dirty worktree is normal in this repository (the run captures a
  * dirtyTreeFingerprint for it), while unmerged paths or an interrupted git
@@ -18,6 +29,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, statfsSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { CONTRACT_VERSION, PROTOCOL_SCHEMA_VERSION, getHarness, probeRuntime } from "../harnesses/index.mjs";
+import { liveSilenceCause } from "../engine/live-silence.mjs";
 import { addRuntimeRequirement, failoverTargets, runtimeSnapshot } from "../engine/failover.mjs";
 import { pricingSeedAge } from "../engine/pricing-seed.mjs";
 import { validateContract } from "../contract/index.mjs";
@@ -31,10 +43,13 @@ import { NOTIFY_SESSION_ENV, sessionWakeNotice } from "../notify/session.mjs";
 import { findExecutable } from "./platform.mjs";
 import { colorLevel, statusToken } from "../cli/brand.mjs";
 import { RUNS_DIR_NAME } from "../run/paths.mjs";
+import { availabilityKey, readAvailability, recordAvailability } from "../run/availability.mjs";
 
 /** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
 /** @typedef {import("../contract/index.mjs").RuntimeSnapshot} RuntimeSnapshot */
 /** @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 {{name: string, ok: boolean, advisory: boolean, detail: string}} EnvCheck */
 /** @typedef {{schemaVersion: number, ok: boolean, checks: EnvCheck[]}} EnvReport */
@@ -384,6 +399,106 @@ export function reachableRuntimes(contract) {
   return runtimes;
 }
 
+
+/**
+ * Read the live verdict off one `preflightContract` probe, in the detail it
+ * embeds: `… · live <status> · <code>: …` for an ask that failed, and the
+ * repository wording when no runtime could be asked at all. Any verdict a
+ * provider produced — a quota refusal, an auth failure, unparsable output —
+ * is an answer; a silence is a verdict of nothing and is never recorded, so
+ * the operator who fixes the host is never told the fix "already answered".
+ *
+ * @param {ProbeResult} probe
+ * @returns {{answered: boolean, cause: string|null, recorded: boolean}}
+ */
+function liveVerdict(probe) {
+  if (probe.liveStatus === "done") return { answered: true, cause: null, recorded: true };
+  // `liveSilenceCause` is the dispatch gate's own classification, imported
+  // rather than restated. A second copy here had `command_invalid` in it,
+  // which the gate deliberately does not: a command that could not be
+  // constructed never reached a provider, so there is no availability verdict
+  // to report either way. Two copies of this rule is how doctor and the gate
+  // would come to disagree about whether an answer was an answer.
+  const silence = liveSilenceCause(probe);
+  if (silence !== null) return { answered: false, cause: silence, recorded: false };
+  const match = / · live \S+ · ([a-z_]+):/u.exec(probe.detail ?? "");
+  const cause = match?.[1] ?? null;
+  if (cause === null) return { answered: false, cause, recorded: false };
+  return { answered: true, cause, recorded: true };
+}
+
+/**
+ * The live half of `doctor`: the verdict, not the version. The two catalogue
+ * surfaces (`models`, `models --probe`) name this report the authoritative
+ * word on availability, so with a contract doctor asks what the dispatch
+ * gate asks — one trivial prompt per routed runtime through
+ * `preflightContract` — and reports beside the version checks what
+ * answered, naming the cause when nothing did.
+ *
+ * A verdict this machine recorded inside the preflight window is reused
+ * rather than re-bought, and every ask that reached a provider is recorded
+ * in turn: the store (`run/availability.mjs`) is the only cache; none is
+ * built here.
+ *
+ * Every check returned here is advisory. `ok` carries the honest verdict —
+ * false when nothing answered — but the lines never gate `doctor`'s exit
+ * code: the report is where the operator reads what answered, and blocking
+ * on silence is the dispatch gate's decision, made on the same causes. A
+ * doctor that failed on a runtime it could not ask inside its own sandbox
+ * (a relative-executable wrapper) would report the runtime broken when the
+ * actual launch may resolve it fine.
+ *
+ * @param {string} contractPath the authored contract, re-read and re-validated by the ask
+ * @param {ReachableRuntimes} runtimes
+ * @returns {Promise<EnvCheck[]>}
+ */
+async function liveAvailabilityChecks(contractPath, runtimes) {
+  /** @type {Map<string, RuntimeAvailability>} */
+  const fresh = new Map();
+  for (const [id, { runtime }] of runtimes) {
+    const verdict = readAvailability(availabilityKey({
+      harness: runtime.harness,
+      model: runtime.model,
+      executable: getHarness(runtime.harness).executable(runtime),
+    }));
+    if (verdict) fresh.set(id, verdict);
+  }
+  if (runtimes.size > 0 && fresh.size === runtimes.size) {
+    return [...runtimes.keys()].map((id) => {
+      const verdict = /** @type {RuntimeAvailability} */ (fresh.get(id));
+      return {
+        name: `availability ${id}`,
+        ok: true,
+        advisory: true,
+        detail: `answered · verdict reused · observed ${verdict.observedAt ?? "unknown instant"}`,
+      };
+    });
+  }
+  // The ask is imported where it runs: live-preflight imports this module's
+  // reachableRuntimes, so a static edge here would be the runtime import
+  // cycle the source gate bans. At call time both modules are fully
+  // evaluated; this is a plain cache hit, not a cycle.
+  const { preflightContract } = await import("../engine/live-preflight.mjs");
+  // measured 2026-09-22 (dispatch gate): four routed runtimes asked in
+  // parallel took about 18s, so 60s is the budget; FABERUN_PREFLIGHT_TIMEOUT_SEC
+  // is the same operator override the gate honours.
+  const override = Number(process.env.FABERUN_PREFLIGHT_TIMEOUT_SEC);
+  const timeoutSec = process.env.FABERUN_PREFLIGHT_TIMEOUT_SEC !== undefined && Number.isFinite(override) && override > 0 ? override : 60;
+  const probes = await preflightContract(contractPath, { liveTimeoutSec: timeoutSec });
+  recordAvailability(probes.filter((probe) => liveVerdict(probe).recorded).map((probe) => availabilityKey(probe)));
+  return probes.map((probe) => {
+    const verdict = liveVerdict(probe);
+    return {
+      name: `availability ${probe.id ?? probe.harness}`,
+      ok: verdict.answered,
+      advisory: true,
+      detail: verdict.answered
+        ? `answered · ${probe.detail ?? `the provider answered (${verdict.cause})`}`
+        : `no answer · ${probe.detail ?? `cause ${verdict.cause ?? "unknown"}`}`,
+    };
+  });
+}
+
 const HARNESS_BIN_OVERRIDES = Object.freeze({
   codex: "FABERUN_CODEX_BIN",
   claude: "FABERUN_CLAUDE_BIN",
@@ -393,9 +508,17 @@ const HARNESS_BIN_OVERRIDES = Object.freeze({
 });
 
 /**
- * Mutation-free environment doctor: repository prerequisites, ignored .runs,
- * required binaries, the dispatch environment gate, and (when a contract is
- * given) schema and harness versions.
+ * Environment doctor: repository prerequisites, ignored .runs, required
+ * binaries, the dispatch environment gate, and (when a contract is given)
+ * the harness versions beside the live availability verdict per routed
+ * runtime — the report `models` defers to. Without a contract it says
+ * plainly that it asked nothing.
+ *
+ * The exit code answers the host-fact question it always answered: the
+ * live availability lines carry their verdict (false when nothing
+ * answered) but are advisory, because blocking on silence is the dispatch
+ * gate's job and a runtime doctor could not ask inside its own sandbox is
+ * not thereby a runtime the launch cannot run.
  *
  * @param {string|undefined} contractPath
  * @param {{cwd?: string, json?: boolean, discover?: boolean}} values
@@ -403,7 +526,7 @@ const HARNESS_BIN_OVERRIDES = Object.freeze({
  */
 export async function doctorCommand(contractPath, values) {
   const repoDir = resolve(values.cwd ?? ".");
-  /** @type {{name: string, ok: boolean, detail: string}[]} */
+  /** @type {{name: string, ok: boolean, advisory?: boolean, detail: string}[]} */
   const checks = [];
   const gitRepo = isGitWorkTree(repoDir);
   checks.push({ name: "git repository", ok: gitRepo, detail: gitRepo ? repoDir : "not inside a git work tree" });
@@ -457,6 +580,10 @@ export async function doctorCommand(contractPath, values) {
         harnessVersions[id] = probe.version;
         checks.push({ name: `harness ${probe.id ?? runtime.harness}`, ok: probe.ok, detail: probe.detail ?? (probe.ok ? "ok" : "probe failed") });
       }
+      // The verdict beside the version: a binary that answered --version is
+      // not thereby a provider that answered, and the report names which of
+      // the two failed because the remedies differ.
+      checks.push(...await liveAvailabilityChecks(absolute, runtimes));
     } catch (error) {
       checks.push({ name: "contract", ok: false, detail: errorMessage(error) });
     }
@@ -497,7 +624,12 @@ export async function doctorCommand(contractPath, values) {
   for (const check of environmentPreflight({ cwd: dispatchCwd, runtimes: routedRuntimes, harnessVersions }).checks) {
     checks.push({ name: check.name, ok: check.ok || check.advisory, detail: check.ok ? check.detail : `${check.detail} (advisory)` });
   }
-  const ok = checks.every((check) => check.ok);
+  // The live availability lines never gate the verdict: a no-answer is the
+  // finding it is on its own line (ok false, cause named), and what still
+  // fails doctor is every host fact and static probe — which is why the
+  // nonexistent-binary case below exits non-zero while a merely silent
+  // provider does not.
+  const ok = checks.every((check) => check.ok || check.advisory === true);
   const transportWarning = noTransportWarning(process.env);
   if (transportWarning) process.stderr.write(`${statusToken("warn", colorLevel(process.env, process.stderr.isTTY))} ${transportWarning}\n`);
   if (values.json === true) {

package/src/notify/index.mjs

@@ -51,6 +51,7 @@ import { appendFileSync, closeSync, mkdirSync, openSync, readFileSync, writeSync
 import { join } from "node:path";
 import { createMacosNotifier } from "./os-macos.mjs";
 import { NOTIFY_SESSION_ENV, deliverToSessions, resolveSessionTargets, sessionWakeNotice } from "./session.mjs";
+import { spawnInvocation } from "../host/platform.mjs";
 import { errorMessage } from "../util.mjs";
 
 /**
@@ -484,7 +485,12 @@ function spawnDeliver(bin, event, { spawn = defaultSpawn, timeoutMs = notificati
   return new Promise((resolveDelivery) => {
     let child;
     try {
-      child = spawn(bin, [], { stdio: ["pipe", "ignore", "pipe"], env: process.env });
+      // The transport is whatever the operator bound, and on Windows that is
+      // rarely an .exe: a `.cmd` shim npm wrote, or a script whose shebang
+      // names its interpreter. Either spawns as EFTYPE unhandled, which is a
+      // notification that silently never arrives.
+      const invocation = spawnInvocation(bin, []);
+      child = spawn(invocation.command, invocation.args, { stdio: ["pipe", "ignore", "pipe"], env: process.env, ...invocation.options });
     } catch (error) {
       resolveDelivery({ ok: false, error: errorMessage(error) });
       return;

package/src/notify/session.mjs

@@ -31,6 +31,7 @@
 import { spawn as defaultSpawn } from "node:child_process";
 import { createConnection as defaultConnect } from "node:net";
 import { errorMessage } from "../util.mjs";
+import { spawnInvocation } from "../host/platform.mjs";
 
 export const NOTIFY_SESSION_ENV = "FABERUN_NOTIFY_SESSION";
 export const CLAUDE_SOCKET_ENV = "CLAUDE_CODE_MESSAGING_SOCKET";
@@ -224,7 +225,11 @@ export function createCodexSessionNotifier({ spawn = /** @type {SpawnFunction} *
         const executable = env.FABERUN_CODEX_BIN ?? "codex";
         let child;
         try {
-          child = spawn(executable, ["queue", "--thread", target.thread, "--message", messageText(event)], { stdio: ["ignore", "ignore", "pipe"], env });
+          // The harness CLI, reached the way this platform reaches one: the
+          // `codex` a Windows machine has is `codex.cmd`, and a raw spawn of
+          // the bare name is ENOENT — a wake that silently never arrives.
+          const invocation = spawnInvocation(executable, ["queue", "--thread", target.thread, "--message", messageText(event)]);
+          child = spawn(invocation.command, invocation.args, { stdio: ["ignore", "ignore", "pipe"], env, ...invocation.options });
         } catch (error) {
           resolve({ ok: false, error: errorMessage(error) });
           return;

package/src/plan/pipeline.mjs

@@ -24,6 +24,7 @@ import { campaignCli } from "../cli/campaign.mjs";
 import { appendJsonl, writeJsonAtomic } from "../run/store.mjs";
 import { stableJson } from "../util.mjs";
 import { allowanceDelta, allowanceEventFields, sampleAllowance } from "../seat/allowance.mjs";
+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";
@@ -42,6 +43,7 @@ import { campaignTree, runDirectory } from "../run/paths.mjs";
 /** @typedef {{sizing: import("./sizing.mjs").SizingResult, routing: import("./routing.mjs").RoutingResult, nodes: JsonObject[]}} AssembledPlan */
 /** @typedef {"standard"|"high"|"none"} ApproveBelow */
 /** @typedef {(contractPath: string, contract: ValidatedContract) => Promise<void>|void} LaunchFn */
+/** @typedef {(runtimes: Record<string, JsonObject>, runtimeDefaults: {worker?: string, judge?: string}, cwd: string) => Promise<import("../harnesses/index.mjs").ProbeResult[]>} AskFn */
 /** @typedef {(runDir: string) => Promise<import("../engine/supervise.mjs").RunProgress>|import("../engine/supervise.mjs").RunProgress} WaitFn */
 /** @typedef {{status: "frozen", plansDir: string, planPath: string, contractPath: string, approved: boolean, findings: PlanFindingOutput[], warnings: string[]}} FrozenPipelineResult */
 /** @typedef {{status: "contested", plansDir: string, planPath: string, findings: PlanFindingOutput[], round: number}} ContestedPipelineResult */
@@ -80,7 +82,7 @@ export const DEFAULT_NODE_BUDGET_MS = 600_000;
 const APPROVE_BELOW_VALUES = new Set(["standard", "high", "none"]);
 
 /**
- * @param {{specPath: string, campaignId: string, phase: string, cwd?: string, reviewRounds?: number, approveBelow?: ApproveBelow, runtimeDefaults?: {worker?: string, judge?: string}, runtimes: Record<string, JsonObject>, verification?: VerificationSuites, launch: LaunchFn, wait: WaitFn}} options
+ * @param {{specPath: string, campaignId: string, phase: string, cwd?: string, reviewRounds?: number, approveBelow?: ApproveBelow, runtimeDefaults?: {worker?: string, judge?: string}, runtimes: Record<string, JsonObject>, verification?: VerificationSuites, launch: LaunchFn, wait: WaitFn, ask?: AskFn}} options
  * @returns {Promise<FrozenPipelineResult|ContestedPipelineResult>}
  */
 export async function runPlanningPipeline(options) {
@@ -88,6 +90,7 @@ export async function runPlanningPipeline(options) {
     specPath, campaignId, phase, runtimes, launch, wait,
     reviewRounds = 2, runtimeDefaults = {}, verification = {},
   } = options;
+  const ask = options.ask ?? askPlanningRuntimes;
   const approveBelow = /** @type {ApproveBelow} */ (options.approveBelow ?? "standard");
   if (!APPROVE_BELOW_VALUES.has(approveBelow)) throw new TypeError(`approveBelow must be one of ${[...APPROVE_BELOW_VALUES].join(", ")}`);
   if (typeof launch !== "function") throw new TypeError("runPlanningPipeline requires a launch seam");
@@ -97,6 +100,7 @@ export async function runPlanningPipeline(options) {
   const campaignPath = campaignTree(cwd, campaignId);
   const campaign = readCampaign(campaignPath);
   if (campaign.status !== "active") throw new Error(`campaign is closed: ${campaignId}`);
+  refusePlanningSilence(await ask(runtimes, runtimeDefaults, cwd), cwd);
 
   const relativeSpecPath = repoRelativePath(cwd, specPath, "specPath");
   const specText = readFileSync(resolve(cwd, relativeSpecPath), "utf8");

package/src/plan/preflight.mjs

@@ -0,0 +1,77 @@
+/**
+ * The ask `faberun plan` makes before its first stage.
+ *
+ * It lives beside the pipeline rather than inside it because asking is its own
+ * concern -- which runtimes a planning run will spend, and what counts as one
+ * of them not answering -- and because `pipeline.mjs` sits 45 lines from this
+ * tree's 800-line ceiling.
+ */
+import { preflightRuntimes } from "../engine/live-preflight.mjs";
+import { liveSilenceCause } from "../engine/live-silence.mjs";
+import { harnessCapabilities } from "../harnesses/index.mjs";
+import { validateRuntime } from "../contract/runtime.mjs";
+
+/**
+ * The runtimes a planning run will spend, asked once before its first stage.
+ *
+ * Planning routes two roles across nine stages and does not reach them at the
+ * same time: the planner is spent at `draft`, the reviewer not until `review`.
+ * Every stage does launch through `runContract`, so the dispatch gate asks --
+ * but it asks that stage's own contract, and a planning contract carries no
+ * gate (`plan/template.mjs` builds them with `gate: false`), so
+ * `reachableRuntimes` never counts the judge role: it only adds one when a
+ * node's gate is enabled. The reviewer is therefore reached only as the
+ * *worker* of a later stage's contract, which is why a reviewer that never
+ * answers used to surface after the draft had already been bought. Naming both
+ * runtimes directly is the only ask that reaches them before anything is
+ * spent.
+ *
+ * Phase 2's verdict store makes this free at the stage boundary: what is
+ * recorded here is what each stage's own gate reuses instead of asking again.
+ *
+ * @param {Record<string, Record<string, unknown>>} runtimes the catalogue as the pipeline carries it, validated here per entry
+ * @param {{worker?: string, judge?: string}} runtimeDefaults
+ * @param {string} cwd
+ * @returns {Promise<import("../harnesses/index.mjs").ProbeResult[]>}
+ */
+export async function askPlanningRuntimes(runtimes, runtimeDefaults, cwd) {
+  /** @type {string[]} */
+  const ids = [];
+  for (const id of [runtimeDefaults.worker, runtimeDefaults.judge]) {
+    if (typeof id === "string" && id.length > 0 && !ids.includes(id)) ids.push(id);
+  }
+  const entries = ids.flatMap((id) => {
+    const raw = runtimes[id];
+    // A default naming a runtime the catalogue does not carry is the
+    // catalogue loader's refusal to make, not this one's.
+    if (raw === undefined) return [];
+    const runtime = validateRuntime(id, raw);
+    return [{ runtime: { ...runtime, id, capabilities: harnessCapabilities(runtime) } }];
+  });
+  return entries.length === 0 ? [] : preflightRuntimes(entries, { cwd });
+}
+
+/**
+ * Refuse before the first stage when a runtime said nothing at all.
+ *
+ * The rule is the dispatch gate's own, imported rather than restated:
+ * `liveSilenceCause` decides what silence is, so planning and dispatch cannot
+ * drift into disagreeing about whether an answer was an answer. Silence
+ * blocks; any verdict a provider returned -- a quota refusal included -- is an
+ * answer, and the run proceeds onto whatever the contract declares.
+ *
+ * @param {import("../harnesses/index.mjs").ProbeResult[]} checks
+ * @param {string} cwd
+ * @returns {void}
+ */
+export function refusePlanningSilence(checks, cwd) {
+  const silent = checks.flatMap((check) => {
+    const cause = liveSilenceCause(check);
+    return cause === null ? [] : [`runtime ${check.id ?? check.harness} did not answer: ${cause}`];
+  });
+  if (silent.length === 0) return;
+  throw Object.assign(
+    new Error(`env_preflight_failed: ${silent.join(" · ")} · planning stays resumable: fix the environment and plan again in ${cwd}`),
+    { code: "env_preflight_failed" },
+  );
+}