faberun 0.10.0 → 0.12.0

package/src/engine/resume.mjs

@@ -18,7 +18,8 @@ import { acquire as acquireLock } from "../run/lock.mjs";
 import { applyInvalidWorkerResult, assertRunMutable, handleProviderExhaustion } from "./lifecycle.mjs";
 import { applyJudgeResult } from "./review.mjs";
 import { assertSourceUnchanged, captureRunIdentity, recordedBaseRef, statesFingerprint } from "./run-identity.mjs";
-import { attemptWorkspace, attemptWorktreePath, gitHead, removeWorktree, runRefName } from "../repo/worktree.mjs";
+import { attemptWorkspace, gitHead, removeWorktree, runRefName } from "../repo/worktree.mjs";
+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";
@@ -302,7 +303,10 @@ export async function resumeRun(runDirPath, options = {}) {
             await applyInvalidWorkerResult(contract, node, state, runDir, null, lock, errorMessage(error), states, campaign.path);
             continue;
           }
-          if (node.taskPacket.mode === "discovery" && parsedWorkerResult.status === "done") {
+          // Same discriminator as lifecycle.mjs: the artifact is owed only by
+          // the repo-reading discovery packet (empty readFiles), never by one
+          // closed to its listed read files, which delivers through `output`.
+          if (node.taskPacket.mode === "discovery" && node.taskPacket.readFiles.length === 0 && parsedWorkerResult.status === "done") {
             try {
               parseDiscoveryResult(parsedWorkerResult, attemptWorkspace(state) ?? contract.cwd);
             } catch (error) {

package/src/engine/run-identity.mjs

@@ -23,6 +23,7 @@ import { fileURLToPath } from "node:url";
 import { stableJson } from "../util.mjs";
 import { validateRunMetadata } from "../contract/snapshot.mjs";
 import { contractDigest } from "../contract/index.mjs";
+import { RUNS_DIR_NAME, runDirectory } from "../run/paths.mjs";
 
 /** @typedef {import("../harnesses/index.mjs").HarnessRuntime} HarnessRuntime */
 /** @typedef {import("../cli.mjs").LockHandle} LockHandle */
@@ -88,7 +89,7 @@ export function createRunMetadata(lock, sourceIdentity, resume = {}, integration
  */
 function runDirFor(sourceIdentity) {
   if (!sourceIdentity.cwd || !sourceIdentity.contractId) return null;
-  return join(sourceIdentity.cwd, ".runs", sourceIdentity.contractId);
+  return runDirectory(sourceIdentity.cwd, sourceIdentity.contractId);
 }
 
 /**
@@ -319,7 +320,13 @@ function walkControllerFiles(root) {
   /** @type {string[]} */
   const found = [];
   for (const entry of readdirSync(root, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
-    if (entry.name === "node_modules" || entry.name === ".git" || entry.name === ".runs") continue;
+    // The controller identity hashes the executable snapshot, not the tree it
+    // is running in: `node_modules` is a dependency install, `.git` is
+    // repository metadata, and `RUNS_DIR_NAME` is the runner's own scratch
+    // state written while a run is in flight. None of the three is a change
+    // to the controller's source, so the sha must never move because the
+    // runner wrote to its own state -- only because tracked source did.
+    if (entry.name === "node_modules" || entry.name === ".git" || entry.name === RUNS_DIR_NAME) continue;
     const path = join(root, entry.name);
     if (entry.isDirectory()) found.push(...walkControllerFiles(path));
     else if (entry.isFile()) found.push(path);

package/src/engine/scheduler.mjs

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import { syncAgentSignal } from "../repo/signal.mjs";
 import { JUDGE_SCHEMA, PARKED, SETTLED, retryPrompt } from "./prompts.mjs";
@@ -18,8 +18,10 @@ import {
 } from "../run/store.mjs";
 import {
   acquire as acquireLock,
+  lockStale,
   LockLostError,
   processStartToken,
+  readLock,
 } from "../run/lock.mjs";
 import { registerRun, resolveCampaign } from "../campaign/index.mjs";
 import { createRunRef, runRefName } from "../repo/worktree.mjs";
@@ -46,6 +48,7 @@ import { startJudge, startWorker } from "./dispatch.mjs";
 import { assertEnvironmentReady, captureRunIdentity, createRunMetadata, serializableContract, statesFingerprint } from "./run-identity.mjs";
 import { blockDependents, runtimeAssignments } from "./assignment.mjs";
 import { createHeartbeat, HEARTBEAT_INTERVAL_MS } from "./supervise.mjs";
+import { runDirectory, runsRoot } from "../run/paths.mjs";
 
 /** @typedef {import("../contract/index.mjs").WorkspaceScopeBoundary} WorkspaceScopeBoundary */
 
@@ -179,6 +182,25 @@ function renderFingerprint(states) {
   return `${statesFingerprint(states)}#${progress}`;
 }
 
+/**
+ * Move a cancelled run's directory out of the way of its own id, once, so
+ * the launch that needs the id back can create it fresh. Never called for
+ * any other reason a run directory might already exist -- this is the one
+ * occupant a launch is allowed to displace on its own.
+ *
+ * @param {string} runDir
+ * @returns {void}
+ */
+function archiveCanceledRunDir(runDir) {
+  let archivedPath = `${runDir}.canceled-${Date.now()}`;
+  let suffix = 0;
+  while (existsSync(archivedPath)) {
+    suffix += 1;
+    archivedPath = `${runDir}.canceled-${Date.now()}-${suffix}`;
+  }
+  renameSync(runDir, archivedPath);
+}
+
 /**
  * @param {string} contractPath
  * @param {{detachedBootstrap?: boolean, baseRef?: string}} [options]
@@ -192,9 +214,21 @@ function renderFingerprint(states) {
 export async function runContract(contractPath, options = {}) {
   const absoluteContractPath = resolve(contractPath);
   const contract = validateContractForLaunch(JSON.parse(readFileSync(absoluteContractPath, "utf8")), absoluteContractPath, { baseRef: options.baseRef });
-  const runDir = join(contract.cwd, ".runs", contract.id);
-  if (existsSync(runDir)) throw new Error(`run already exists: ${runDir}`);
-  mkdirSync(join(contract.cwd, ".runs"), { recursive: true });
+  const runDir = runDirectory(contract.cwd, contract.id);
+  if (existsSync(runDir)) {
+    // A cancelled run is the one prior occupant of this id a fresh launch may
+    // move aside on its own: `cancel` already released the git names (the run
+    // ref, every node's attempt branch) this launch needs back, and the
+    // cancel-request marker plus a stale controller lock is what proves no
+    // process can still be writing into it. Anything else at this path --
+    // still running, or settled without ever being cancelled -- keeps
+    // refusing exactly as before; the operator's evidence is never silently
+    // claimed.
+    const wasCanceled = existsSync(join(runDir, "cancel.request.json")) && lockStale(readLock(runDir));
+    if (!wasCanceled) throw new Error(`run already exists: ${runDir}`);
+    archiveCanceledRunDir(runDir);
+  }
+  mkdirSync(runsRoot(contract.cwd), { recursive: true });
   try {
     mkdirSync(runDir);
   } catch (error) {
@@ -208,7 +242,7 @@ export async function runContract(contractPath, options = {}) {
     const sourceIdentity = await captureRunIdentity(contract, scopeBoundaries);
     const integrationRef = createRunRef(contract.cwd, contract.id, sourceIdentity.gitHead);
     lock.assert();
-    const runsDir = join(contract.cwd, ".runs");
+    const runsDir = runsRoot(contract.cwd);
     const campaign = resolveCampaign(runsDir, contract.campaignId);
     mkdirSync(join(runDir, "nodes"), { recursive: true });
     mkdirSync(join(runDir, "logs"), { recursive: true });
@@ -281,7 +315,7 @@ export async function runContract(contractPath, options = {}) {
 export async function driveRun(contract, runDir, states, campaign, lock, sourceIdentity, resume = {}, options = {}) {
   lock.assert();
   assertEnvironmentReady(contract, runDir, sourceIdentity);
-  const runsDir = join(contract.cwd, ".runs");
+  const runsDir = runsRoot(contract.cwd);
   const bootstrapNonce = bootstrapNonceForProcess();
   // Only the CLI entry can answer this: a nonce inherited by evals/run.mjs or
   // by a test must not make the controller wait for an acknowledgement nobody

package/src/engine/settle-judge.mjs

@@ -0,0 +1,141 @@
+/**
+ * The judge branch of `finalizeClosedJobs`, and the workspace comparison its
+ * fail-closed write check depends on. Split out of `lifecycle.mjs` for the
+ * same reason `engine/settle.mjs` was: `lifecycle.mjs` and
+ * `test/engine/judge.test.mjs` both sit on the 800-line ceiling
+ * `test/repo/source-shape.test.mjs` enforces.
+ *
+ * `settleJudgeRound` runs only after `lifecycle.mjs` has already called
+ * `judgeWorkspaceWriteViolation` and found nothing: the check has to run
+ * before any branch here (a failed provider, a bounded re-dispatch, or a
+ * verdict) can adopt or launder a judge's own write, so it cannot live inside
+ * this function without reintroducing the escape it closes.
+ *
+ * `clearTierExhaustion` and `handleProviderExhaustion` are `lifecycle.mjs`'s
+ * own -- importing them back from there would recreate the exact
+ * `lifecycle.mjs` <-> `review.mjs` cycle `test/repo/source-shape.test.mjs`
+ * once caught and `AGENTS.md` records as fixed, so the caller passes them in
+ * instead.
+ */
+import { judgeReaskOutstanding } from "./judge-gate.mjs";
+import { judgeVerdictEvidence } from "../contract/review-modes.mjs";
+import {
+  JUDGE_MAX_FAILURES,
+  applyJudgeProtocolFailure,
+  applyJudgeResult,
+  applyJudgeRound,
+  settleUnavailableJudge,
+} from "./review.mjs";
+import { networkTransition } from "./backoff.mjs";
+import { startJudge } from "./dispatch.mjs";
+import { writeNode } from "./state.mjs";
+import { compareWorkspaceSnapshot } from "../repo/workspace.mjs";
+import { errorCode, errorMessage, excerpt } from "../util.mjs";
+
+/** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
+/** @typedef {import("../contract/index.mjs").NodeSnapshot} NodeSnapshot */
+/** @typedef {import("./process.mjs").Job} Job */
+/** @typedef {import("../run/lock.mjs").LockRecord} LockRecord */
+/** @typedef {ReturnType<typeof import("../run/lock.mjs").acquire>} LockHandle */
+/** @typedef {import("../harnesses/index.mjs").ProviderEnvelope} ProviderEnvelope */
+/** @typedef {ProviderEnvelope & {costProvenance?: "priced"}} PricedEnvelope */
+
+/**
+ * Whether a closed judge job wrote into its own workspace, or a workspace
+ * comparison error that means the same thing: either is a violation, never
+ * silence. `compareWorkspaceSnapshot` throws `snapshot_ignore_changed` when
+ * the judge edits an ignore source, `snapshot_symlink_escape` when it creates
+ * a symlink out of the tree, and `snapshot_too_large` when it adds enough
+ * entries -- all ordinary judge writes that must fail closed exactly like the
+ * worker path (`engine/scope.mjs`'s `checkWorkerScope`), never vanish into a
+ * "no writes" result. `job.scopeBaseline` is null only when the capture at
+ * dispatch time itself failed -- `startJudge` degrades to unchecked rather
+ * than refuse to run the judge at all -- and that is the one case with
+ * nothing to compare, not a violation.
+ *
+ * @param {Job} job
+ * @returns {{message: string}|null}
+ */
+export function judgeWorkspaceWriteViolation(job) {
+  const baseline = job.scopeBaseline;
+  if (!baseline) return null;
+  try {
+    const { unexpectedPaths } = compareWorkspaceSnapshot(/** @type {import("../repo/workspace.mjs").WorkspaceSnapshot} */ (baseline), job.cwd);
+    if (!unexpectedPaths.length) return null;
+    return { message: excerpt(`judge wrote into its own workspace (${unexpectedPaths.length}): ${unexpectedPaths.slice(0, 8).join(", ")}`) ?? "judge wrote into its own workspace" };
+  } catch (error) {
+    return { message: excerpt(`judge workspace comparison failed (${errorCode(error) ?? "scope_snapshot_invalid"}): ${errorMessage(error)}`) ?? "judge workspace comparison failed" };
+  }
+}
+
+/**
+ * Settle a closed judge invocation whose write check already passed: a
+ * provider that failed outright gets one bounded re-dispatch, then review-mode
+ * settlement; anything else that is not exactly one usable verdict (none at
+ * all, several of them, an unparseable one, a stream cut off before its
+ * terminal envelope, or a phase killed on its wall clock) takes the same
+ * bounded re-ask; a clean verdict is applied.
+ *
+ * @param {ValidatedContract} contract
+ * @param {Job} job
+ * @param {NodeSnapshot} state
+ * @param {string} runDir
+ * @param {Map<string, Job>} running
+ * @param {LockHandle} lock
+ * @param {Map<string, NodeSnapshot>} states
+ * @param {string} campaignPath
+ * @param {PricedEnvelope} envelope
+ * @param {{clearTierExhaustion: (state: NodeSnapshot) => void, handleProviderExhaustion: typeof import("./lifecycle.mjs").handleProviderExhaustion}} hooks
+ *   `lifecycle.mjs`'s own tier-exhaustion clear and provider-exhaustion router, passed in rather than imported back.
+ * @returns {Promise<void>}
+ */
+export async function settleJudgeRound(contract, job, state, runDir, running, lock, states, campaignPath, envelope, { clearTierExhaustion, handleProviderExhaustion }) {
+  const node = job.node;
+  // A judge provider that failed outright (its turn died, its tool host was
+  // gone) is a provider failure, never a verdict: the gate cannot adopt a
+  // result the judge could not ground in inspection. Re-dispatch the judge
+  // once on the same routing, then settle by review mode so a judge failure
+  // is surfaced, never silently settled. A stream that never reached its
+  // terminal envelope is a protocol defect instead and takes the bounded
+  // re-ask below.
+  if (envelope.status === "failed" && envelope.error?.code !== "incomplete_stream") {
+    // A judge that lost its socket is not an unavailable judge. It buys the
+    // same bounded network waits a worker does, on the runtime it already
+    // warmed, and spends none of the one re-dispatch counted below.
+    const network = networkTransition(contract, node, state, "judge", envelope, job.exitCode);
+    if (network && handleProviderExhaustion(contract, runDir, node, state, "judge", envelope, job.runtime.id, lock, states, campaignPath, network)) return;
+    clearTierExhaustion(state);
+    // The provider died on the bounded re-ask itself, so the one permitted
+    // re-ask is spent: settle by review mode here rather than dispatch a
+    // third judge invocation behind a fresh failure count.
+    if (judgeReaskOutstanding(state)) {
+      await applyJudgeProtocolFailure(contract, node, state, runDir, running, lock, states, campaignPath, envelope.error?.message ?? "judge provider failed");
+      return;
+    }
+    state.judgeFailures = (state.judgeFailures ?? 0) + 1;
+    if (state.judgeFailures < JUDGE_MAX_FAILURES) {
+      writeNode(runDir, state, lock);
+      await applyJudgeRound(await startJudge(contract, node, state, runDir, running, state.result, lock, states, campaignPath),
+        contract, node, state, runDir, running, lock, states, campaignPath, state.result);
+      return;
+    }
+    await settleUnavailableJudge(contract, node, state, runDir, lock, states, campaignPath, envelope.error?.message ?? "judge provider failed");
+    return;
+  }
+  // Whatever else this invocation produced, it is not exactly one usable
+  // verdict: no verdict at all, several of them in separate agent messages,
+  // an unparseable one, a stream cut off before its terminal envelope, or a
+  // phase killed on its wall clock. One bounded re-ask, then the review mode
+  // decides — advisory completes, blocking enters attention with the work
+  // preserved so a retry in place can re-judge it.
+  const evidence = judgeVerdictEvidence(envelope);
+  if (!evidence.ok) {
+    const network = networkTransition(contract, node, state, "judge", envelope, job.exitCode);
+    if (network && handleProviderExhaustion(contract, runDir, node, state, "judge", envelope, job.runtime.id, lock, states, campaignPath, network)) return;
+    clearTierExhaustion(state);
+    await applyJudgeProtocolFailure(contract, node, state, runDir, running, lock, states, campaignPath, evidence.reason);
+    return;
+  }
+  clearTierExhaustion(state);
+  await applyJudgeResult(contract, node, state, evidence.result, runDir, lock, running, states, campaignPath);
+}

package/src/engine/settle.mjs

@@ -22,10 +22,10 @@ import { alreadyNotified, notifyQueueFor } from "./notify-queue.mjs";
 
 import {
   attemptWorkspace,
-  attemptWorktreePath,
   removeWorktree,
   sealAttempt,
 } from "../repo/worktree.mjs";
+import { attemptWorktreePath } from "../run/paths.mjs";
 import { basename } from "node:path";
 import { boundedUtf8, errorCode, errorMessage } from "../util.mjs";
 import { campaignIdOf } from "../campaign/record.mjs";

package/src/harnesses/protocol.mjs

@@ -498,6 +498,50 @@ export function isVerdictCandidate(text) {
   }
 }
 
+/**
+ * A judge's final message can carry its whole verdict on one line with no
+ * newline before the JSON: `Confirmed. Now write the verdict JSON.{"verdict":
+ * "fail", ...}`, measured 2026-09-17 at 5662 characters. A line-boundary-only
+ * suffix scan never finds it, extractJson returns null, isVerdictCandidate
+ * returns false, and a correct, evidenced verdict is discarded as
+ * `judge_unavailable`. The candidate starts tried here are every `{` and `[`
+ * offset, not just line starts, so a JSON object glued directly to prose is
+ * still reachable.
+ */
+const SUFFIX_CANDIDATE_LIMIT = 200;
+
+/**
+ * The last parseable suffix of `trimmed`, trying every `{`/`[` offset from the
+ * end backwards. Bounded to the last `SUFFIX_CANDIDATE_LIMIT` offsets: without
+ * a cap this is one `JSON.parse` per bracket character, quadratic on a
+ * pathological message built mostly of brackets. 200 is comfortably above the
+ * bracket count of any real verdict object (the measured 5662-character
+ * message resolves on one of its first few tries, since its outermost `{` is
+ * also its first) and keeps every call to at most 200 parses regardless of
+ * message length.
+ *
+ * @param {string} trimmed
+ * @returns {string|null}
+ */
+function suffixJsonCandidate(trimmed) {
+  const offsets = [];
+  for (let index = 0; index < trimmed.length; index += 1) {
+    const char = trimmed[index];
+    if (char === "{" || char === "[") offsets.push(index);
+  }
+  const floor = Math.max(0, offsets.length - SUFFIX_CANDIDATE_LIMIT);
+  for (let index = offsets.length - 1; index >= floor; index -= 1) {
+    const candidate = trimmed.slice(offsets[index]);
+    try {
+      JSON.parse(candidate);
+      return candidate;
+    } catch {
+      // This suffix is not JSON; keep trying earlier bracket offsets.
+    }
+  }
+  return null;
+}
+
 /**
  * Extract a JSON value from a provider response that may carry prose, taking
  * the last parseable suffix or fenced JSON block.
@@ -514,16 +558,8 @@ export function extractJson(value) {
   } catch {
     // Not JSON as a whole: fall through to the suffix and fenced-block scans below.
   }
-  const lines = trimmed.split(/\r?\n/u);
-  for (let index = lines.length - 1; index > 0; index -= 1) {
-    const candidate = lines.slice(index).join("\n").trim();
-    try {
-      JSON.parse(candidate);
-      return candidate;
-    } catch {
-      // This suffix is not JSON; keep trying earlier line boundaries.
-    }
-  }
+  const suffix = suffixJsonCandidate(trimmed);
+  if (suffix !== null) return suffix;
   const blocks = [...value.matchAll(/```json\s*([\s\S]*?)```/giu)];
   for (const block of blocks.reverse()) {
     const candidate = block[1].trim();

package/src/harnesses/replay/bin.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { RUNS_DIR_NAME } from "../../run/paths.mjs";
 
 const ENVELOPE_STATUSES = new Set(["done", "no-op", "blocked", "failed", "exhausted", "stalled", "canceled"]);
 const LINE_KEYS = new Set(["envelope", "files", "delayMs", "exitCode", "stdoutRaw"]);
@@ -13,7 +14,15 @@ const ENVELOPE_KEYS = new Set([...ENVELOPE_REQUIRED_KEYS, ...ENVELOPE_OPTIONAL_K
 const USAGE_KEYS = new Set(["inputTokens", "outputTokens", "cacheReadInputTokens"]);
 const FILE_KEYS = new Set(["path", "content"]);
 const ERROR_KEYS = new Set(["code", "message", "resetAt"]);
-const METADATA_ROOTS = new Set([".git", ".runs", "node_modules", ".claude", ".codex"]);
+// A recorded file write is refused, not merely ignored, if it targets any of
+// these roots: `.git` is repository metadata, `RUNS_DIR_NAME` is the runner's
+// own scratch tree, `node_modules` is a dependency install, and `.claude` and
+// `.codex` are agent runtimes' own scratch state. A replayed recording that
+// named one of these would be indistinguishable from a live worker escaping
+// its workspace into the runner's own bookkeeping, so replay comparison
+// treats all five the same way live execution does: never a legitimate
+// worker write.
+const METADATA_ROOTS = new Set([".git", RUNS_DIR_NAME, "node_modules", ".claude", ".codex"]);
 const PREFLIGHT_TOKEN = "FABERUN_PREFLIGHT_OK";
 
 const PREFLIGHT_ENVELOPE = Object.freeze({

package/src/host/home.mjs

@@ -3,9 +3,11 @@
  *
  * One module owns every path the installer, the self-updater and the banner
  * must agree on: `versions/<v>/`, the `current` symlink, `config.json`,
- * `update-check.json` and `tmp/`. install.sh is owned by another node; if it
- * and the updater each spelled the layout out, they would drift until
- * `current` pointed at a directory one of them did not mean.
+ * `update-check.json`, `tmp/` and `projects/`. install.sh is owned by another
+ * node; if it and the updater each spelled the layout out, they would drift
+ * until `current` pointed at a directory one of them did not mean.
+ * `projects/` holds the project registry; `host/projects.mjs` owns what goes
+ * inside it, since this module owns where things sit, not what they mean.
  */
 import { mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -50,6 +52,11 @@ export function tmpDir(home) {
   return join(home, "tmp");
 }
 
+/** @param {string} home @returns {string} */
+export function projectsDir(home) {
+  return join(home, "projects");
+}
+
 /**
  * The version directory an entry path was launched from, or null when the path
  * does not name a location inside `versions/`.

package/src/host/platform.mjs

@@ -0,0 +1,111 @@
+/**
+ * The three primitives whose implementation differs on Windows, in one module
+ * because the callers that need them — the updater repointing `current`, the
+ * skill registration linking a directory, the doctor and the banner asking
+ * whether a binary is there — must all get the same answer.
+ *
+ * A directory link is a junction on Windows. A directory *symlink* there needs
+ * Developer Mode or an elevated shell, so `symlinkSync` on a stock machine
+ * fails with EPERM; a junction needs no privilege, resolves through
+ * `realpathSync` — which is how `installedVersionDir` identifies the running
+ * version — and reports `isSymbolicLink()` true, so every reader already
+ * written against the POSIX layout keeps working.
+ *
+ * `tar` is the one in System32 when it is there (bsdtar, shipped with Windows
+ * since 10 1803). Git for Windows puts a GNU tar on PATH that reads the `C:` in
+ * an absolute path as a remote host and fails with `Cannot connect to C:`, and
+ * whichever of the two comes first on PATH is not something this tool gets to
+ * choose. install.ps1 resolves it the same way for the same reason.
+ *
+ * A command name is a name plus `PATHEXT` on Windows. `node` on PATH is
+ * `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 { delimiter, dirname, isAbsolute, join, resolve } from "node:path";
+
+/**
+ * Point `linkPath` at `target`, replacing whatever link is already there. A
+ * relative `target` is relative to the link's own directory, which is the form
+ * the install layout is written in (`current -> versions/<v>`).
+ *
+ * On POSIX the swap is atomic: a sibling temporary link then a rename, so a
+ * concurrent reader sees either the old target or the new one, never a missing
+ * link. On Windows it cannot be — renaming a directory over an existing
+ * junction fails with EPERM — so the link is removed and remade, and a reader
+ * in the moment between the two finds nothing there.
+ *
+ * @param {string} linkPath
+ * @param {string} target
+ * @returns {void}
+ */
+export function linkDirectory(linkPath, target) {
+  if (process.platform === "win32") {
+    // A junction stores an absolute target; a relative one would be recorded
+    // against the process cwd rather than the link's directory.
+    const absolute = isAbsolute(target) ? target : resolve(dirname(linkPath), target);
+    rmSync(linkPath, { recursive: true, force: true });
+    symlinkSync(absolute, linkPath, "junction");
+    return;
+  }
+  const temporary = `${linkPath}.tmp`;
+  rmSync(temporary, { force: true });
+  symlinkSync(target, temporary);
+  renameSync(temporary, linkPath);
+}
+
+/**
+ * The `tar` to spawn on this machine.
+ *
+ * @returns {string}
+ */
+export function tarExecutable() {
+  if (process.platform !== "win32") return "tar";
+  const system = join(process.env.SystemRoot ?? "C:\\Windows", "System32", "tar.exe");
+  return existsSync(system) ? system : "tar";
+}
+
+/**
+ * The first directory on PATH that holds `name`, or null. Exported because the
+ * doctor, the banner and the skill registration all count the same binaries,
+ * rather than each keeping a copy of the lookup that can disagree.
+ *
+ * @param {string} name
+ * @returns {string|null}
+ */
+export function findExecutable(name) {
+  const candidates = executableCandidates(name);
+  if (name.includes("/") || name.includes("\\")) {
+    return candidates.find((candidate) => existsSync(candidate)) ?? null;
+  }
+  for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+    if (!dir) continue;
+    for (const candidate of candidates) {
+      const path = join(dir, candidate);
+      if (existsSync(path)) return path;
+    }
+  }
+  return null;
+}
+
+/**
+ * The file names a command name can have on this platform: itself on POSIX,
+ * itself plus every `PATHEXT` spelling on Windows.
+ *
+ * PATHEXT comes first and the bare name last, because that is the order
+ * Windows itself runs them in: `node` on PATH is `node.exe`, a CLI npm
+ * installed is `<name>.cmd`, and the extensionless file npm leaves beside it is
+ * a shell script no Windows process can execute. Measured 2026-09-18 on Windows
+ * 11: without the extensions `doctor` reported `binary node · not found on
+ * PATH` from a process that node itself was running.
+ *
+ * @param {string} name
+ * @returns {string[]}
+ */
+function executableCandidates(name) {
+  if (process.platform !== "win32") return [name];
+  // Lowercased so the reported path reads like the file on disk: PATHEXT is
+  // upper case by convention, the file system is not case sensitive.
+  const extensions = (process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").map((extension) => extension.trim().toLowerCase()).filter(Boolean);
+  return [...extensions.map((extension) => `${name}${extension}`), name];
+}

package/src/host/preflight.mjs

@@ -16,9 +16,10 @@
  */
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, statfsSync } from "node:fs";
-import { delimiter, join, resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { CONTRACT_VERSION, PROTOCOL_SCHEMA_VERSION, getHarness, probeRuntime } from "../harnesses/index.mjs";
 import { addRuntimeRequirement, failoverTargets, runtimeSnapshot } from "../engine/failover.mjs";
+import { pricingSeedAge } from "../engine/pricing-seed.mjs";
 import { validateContract } from "../contract/index.mjs";
 import { sharedVerificationCommands } from "../contract/final-verification.mjs";
 import { DISCOVERY_RUNTIME_DEFINITIONS, discoverRuntimes } from "../engine/runtime-discovery.mjs";
@@ -26,7 +27,9 @@ import { errorMessage } from "../util.mjs";
 import { boundedGitSync } from "../repo/worktree.mjs";
 import { routeRuntime } from "../contract/runtime.mjs";
 import { NOTIFY_BIN_ENV, noTransportWarning } from "../notify/index.mjs";
+import { findExecutable } from "./platform.mjs";
 import { colorLevel, statusToken } from "../cli/brand.mjs";
+import { RUNS_DIR_NAME } from "../run/paths.mjs";
 
 /** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
 /** @typedef {import("../contract/index.mjs").RuntimeSnapshot} RuntimeSnapshot */
@@ -254,6 +257,22 @@ export function declaredVerificationCommands(contract) {
   return [...commands.values()];
 }
 
+/**
+ * Environment names removed before spawning a timing candidate. The probe
+ * only measures how long a command takes; a subtraction of a named few, not
+ * an allowlist, so PATH, HOME and every ordinary variable the command needs
+ * to run at all still pass through unchanged.
+ */
+const SIDE_EFFECT_ENV_KEYS = [
+  NOTIFY_BIN_ENV, // a measurement must not notify a human
+  "FABERUN_CODEX_BIN", // could redirect the timed command at a live, paid codex binary instead of this repository's own fixtures
+  "FABERUN_CLAUDE_BIN", // same, for the claude harness
+  "FABERUN_AGY_BIN", // same, for the agy harness
+  "FABERUN_DSH_BIN", // same, for the dsh harness
+  "FABERUN_ZCODE_BIN", // same, for the zcode harness
+  "FABERUN_EXEC_JSONL_BIN", // same, for the exec-jsonl harness
+];
+
 /**
  * Run every declared verification command once and report what it actually
  * costs against the timeout the contract gives it.
@@ -275,6 +294,8 @@ export function declaredVerificationCommands(contract) {
 export function timeVerificationCommands(contract, probes = {}) {
   const now = probes.now ?? (() => Date.now());
   const run = probes.run ?? spawnSync;
+  const env = { ...process.env };
+  for (const key of SIDE_EFFECT_ENV_KEYS) delete env[key];
   return declaredVerificationCommands(contract).map((command) => {
     const label = command.argv.join(" ");
     const name = `verification timing · ${label}`;
@@ -288,6 +309,7 @@ export function timeVerificationCommands(contract, probes = {}) {
       timeout: ceilingSec * 1_000,
       stdio: "ignore",
       encoding: "utf8",
+      env,
     });
     const seconds = (now() - startedAt) / 1_000;
     const measured = `${seconds.toFixed(1)}s measured against ${command.timeoutSec}s declared`;
@@ -391,6 +413,17 @@ export async function doctorCommand(contractPath, values) {
     checks.push({ name: `binary ${binary}`, ok: found !== null, detail: found ?? "not found on PATH" });
   }
   checks.push({ name: "runner schema", ok: true, detail: `protocol ${PROTOCOL_SCHEMA_VERSION} · runner ${CONTRACT_VERSION}` });
+  // A stale seed still prices better than no seed, so this check informs and
+  // never fails: a fact beside the runner-schema line, not a gate like the
+  // advisory checks below it, which exist because they can genuinely fail.
+  const seedAge = pricingSeedAge();
+  checks.push({
+    name: "pricing seed",
+    ok: true,
+    detail: seedAge.stale
+      ? `models.dev rates vendored ${seedAge.fetchedAt} · ${seedAge.ageDays} days old; re-vendor src/engine/pricing-seed.json`
+      : `models.dev rates vendored ${seedAge.fetchedAt}`,
+  });
   /** @type {Set<string>} */
   let usedHarnesses = new Set();
   /** @type {Set<string>} */
@@ -486,12 +519,20 @@ function isGitWorkTree(repoDir) {
 }
 
 /**
+ * Whether the runs directory name is ignored in `repoDir`.
+ *
+ * Not dead cleanup after run state moved under the faberun home: an attempt
+ * worktree is still a git working tree, and R3 keeps the worker's result
+ * sidecar inside it, under `.runs/`. The ignore line is what keeps that
+ * sidecar out of the worktree's scope diff, so this check -- and the
+ * `.gitignore` line `cli/init.mjs` writes -- survive the move.
+ *
  * @param {string} repoDir
  * @returns {boolean}
  */
 function isRunsIgnored(repoDir) {
   try {
-    const result = boundedGitSync(["-C", repoDir, "check-ignore", "-q", ".runs"], { stdio: ["ignore", "ignore", "ignore"] });
+    const result = boundedGitSync(["-C", repoDir, "check-ignore", "-q", RUNS_DIR_NAME], { stdio: ["ignore", "ignore", "ignore"] });
     if (result.status === 0) return true;
   } catch {
     // A git that cannot run leaves the check-ignore answer unknown; fall through to reading .gitignore directly.
@@ -503,22 +544,3 @@ function isRunsIgnored(repoDir) {
     return false;
   }
 }
-
-/**
- * The first directory on PATH that holds `name`, or null. Exported because the
- * banner counts the harness binaries with the same lookup the doctor uses,
- * rather than a second copy that can disagree.
- *
- * @param {string} name
- * @returns {string|null}
- */
-export function findExecutable(name) {
-  if (name.includes("/") || name.includes("\\")) return existsSync(name) ? name : null;
-  for (const dir of (process.env.PATH ?? "").split(delimiter)) {
-    if (!dir) continue;
-    const candidate = join(dir, name);
-    if (existsSync(candidate)) return candidate;
-  }
-  return null;
-}
-