faberun 0.10.0 → 0.12.0

package/src/cli/project.mjs

@@ -0,0 +1,150 @@
+/**
+ * `faberun project`: re-associate a project whose repository moved, keeping
+ * its id -- and everything that will hang off that id -- untouched.
+ *
+ * `src/host/projects.mjs` is out of this node's write scope, and its public
+ * surface (`registerProject`, `findProjectByPath`, `readProject`) has no
+ * operation that keeps an existing id while giving it a new path:
+ * `registerProject` either finds the id already at a path or mints a fresh
+ * one, and a fresh id is exactly what a move must not produce. This module
+ * therefore reads and rewrites `projects/index.json` and
+ * `projects/<id>/project.json` directly, with the same temp-then-rename
+ * discipline the registry itself uses, rather than inventing a second
+ * on-disk format for the same directory.
+ */
+import { join } from "node:path";
+import { readJson, writeJsonAtomic } from "../run/store.mjs";
+import { errorCode } from "../util.mjs";
+import { findProjectByPath, projectsDir, readProject, resolveIdentity } from "../host/projects.mjs";
+import { boundedGitSync } from "../repo/worktree.mjs";
+
+/** @typedef {import("../host/projects.mjs").ProjectRecord} ProjectRecord */
+
+/**
+ * The path-to-id index, read straight off `index.json`. Inlined at each of
+ * its two call sites rather than pulled out as a shared top-level helper: the
+ * identical helper already lives, unexported, in `host/projects.mjs`, which
+ * this module cannot import from without that file entering its write scope.
+ *
+ * @param {string} indexPath
+ * @returns {Record<string, string>}
+ */
+function readIndexAt(indexPath) {
+  try {
+    return /** @type {Record<string, string>} */ (readJson(indexPath));
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return {};
+    throw error;
+  }
+}
+
+/**
+ * Every registered project, read straight off disk. Used only to search by
+ * remote when the operator names no `--from`.
+ *
+ * @param {string} home
+ * @returns {ProjectRecord[]}
+ */
+function listProjects(home) {
+  const index = readIndexAt(join(projectsDir(home), "index.json"));
+  const ids = new Set(Object.values(index));
+  /** @type {ProjectRecord[]} */
+  const projects = [];
+  for (const id of ids) {
+    const project = readProject(home, id);
+    if (project) projects.push(project);
+  }
+  return projects;
+}
+
+/**
+ * The remote URLs a git repository at `path` currently reports, or `[]` when
+ * `path` is not a git repository, has no remote, or git is unavailable. An
+ * operator who names `--from` never needs this at all.
+ *
+ * @param {string} path
+ * @returns {string[]}
+ */
+export function readRemotes(path) {
+  const result = boundedGitSync(["-C", path, "remote", "-v"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+  if (result.error || result.status !== 0) return [];
+  /** @type {Set<string>} */
+  const urls = new Set();
+  for (const line of /** @type {string} */ (result.stdout).split("\n")) {
+    const match = /^\S+\s+(\S+)\s+\(/u.exec(line);
+    if (match) urls.add(match[1]);
+  }
+  return [...urls];
+}
+
+/**
+ * The registered project whose remotes overlap what `remotesOf(path)` reports
+ * right now, or null when none does, or when `path` reports no remote at all.
+ * More than one match is refused by the caller, not decided here.
+ *
+ * @param {string} home
+ * @param {string} path
+ * @param {(path: string) => string[]} remotesOf
+ * @returns {ProjectRecord[]}
+ */
+function projectsMatchingRemotes(home, path, remotesOf) {
+  const remotes = new Set(remotesOf(path));
+  if (remotes.size === 0) return [];
+  return listProjects(home).filter((project) => project.remotes.some((remote) => remotes.has(remote)));
+}
+
+/**
+ * @param {string} home
+ * @param {ProjectRecord} project
+ * @param {string} newPath
+ * @returns {ProjectRecord}
+ */
+function moveProject(home, project, newPath) {
+  const indexPath = join(projectsDir(home), "index.json");
+  const index = readIndexAt(indexPath);
+  delete index[project.path];
+  index[newPath] = project.id;
+  writeJsonAtomic(indexPath, index);
+  /** @type {ProjectRecord} */
+  const record = { ...project, path: newPath, updatedAt: new Date().toISOString() };
+  writeJsonAtomic(join(projectsDir(home), project.id, "project.json"), record);
+  return record;
+}
+
+/**
+ * Re-associate a project with the path its repository moved to.
+ *
+ * Idempotent by construction: when `newPath` is already the project's
+ * registered path -- whether this is the first call or a repeat of one that
+ * already landed -- the current record comes back untouched and nothing is
+ * written. That is deliberate: an operator unsure whether a previous attempt
+ * succeeded runs the same command again rather than inspecting the registry
+ * first.
+ *
+ * With `options.from`, the project once registered at that path is moved.
+ * Without it, the project is found by matching the git remotes `newPath`
+ * reports now against the remotes every registered project last recorded;
+ * no match, or more than one, is refused with a message naming what was
+ * looked for, rather than guessed.
+ *
+ * @param {string} home
+ * @param {string} newPath
+ * @param {{from?: string, remotesOf?: (path: string) => string[]}} [options]
+ * @returns {ProjectRecord}
+ */
+export function reassociateProject(home, newPath, options = {}) {
+  const resolvedNew = resolveIdentity(newPath);
+  const already = findProjectByPath(home, resolvedNew);
+  if (already) return already;
+  if (options.from) {
+    const resolvedFrom = resolveIdentity(options.from);
+    const found = findProjectByPath(home, resolvedFrom);
+    if (!found) throw new Error(`no project is registered at ${resolvedFrom}`);
+    return moveProject(home, found, resolvedNew);
+  }
+  const remotesOf = options.remotesOf ?? readRemotes;
+  const matches = projectsMatchingRemotes(home, resolvedNew, remotesOf);
+  if (matches.length === 0) throw new Error(`no registered project has the remotes reported at ${resolvedNew}`);
+  if (matches.length > 1) throw new Error(`${matches.length} registered projects share a remote reported at ${resolvedNew}; pass --from to disambiguate`);
+  return moveProject(home, matches[0], resolvedNew);
+}

package/src/cli/skills.mjs

@@ -20,7 +20,6 @@ import {
   readdirSync,
   realpathSync,
   rmSync,
-  symlinkSync,
 } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve, sep } from "node:path";
@@ -28,7 +27,7 @@ import { fileURLToPath } from "node:url";
 import { parseArgs as parseFlags } from "node:util";
 
 import { faberunHome, installedVersionDir } from "../host/home.mjs";
-import { findExecutable } from "../host/preflight.mjs";
+import { findExecutable, linkDirectory } from "../host/platform.mjs";
 import { colorLevel, statusToken } from "./brand.mjs";
 
 const SKILLS_DIR = fileURLToPath(new URL("../../skills", import.meta.url));
@@ -304,7 +303,7 @@ function linkSkill(source, destination, force) {
     if (!existing.isSymbolicLink() && !force) return "skipped";
     rmSync(destination, { recursive: true, force: true });
   }
-  symlinkSync(source, destination);
+  linkDirectory(destination, source);
   return "linked";
 }
 

package/src/cli/update.mjs

@@ -13,9 +13,10 @@
  * rather than something to compare as if it were a release.
  */
 import { spawnSync } from "node:child_process";
-import { mkdirSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { compareVersions, currentLink, faberunHome, installedVersionDir, tmpDir, versionsDir, writeUpdateCheck } from "../host/home.mjs";
+import { linkDirectory, tarExecutable } from "../host/platform.mjs";
 import { packageVersion } from "../host/package.mjs";
 import { errorMessage } from "../util.mjs";
 
@@ -170,7 +171,7 @@ async function downloadTarball(fetchImpl, url, destination) {
  * @returns {void}
  */
 function extractTarball(tarball, destination) {
-  const result = spawnSync("tar", ["-xzf", tarball, "--strip-components=1", "-C", destination], { encoding: "utf8" });
+  const result = spawnSync(tarExecutable(), ["-xzf", tarball, "--strip-components=1", "-C", destination], { encoding: "utf8" });
   if (result.error) throw result.error;
   if (result.status !== 0) throw new Error(`tar failed: ${String(result.stderr ?? "").trim() || `exit ${result.status}`}`);
 }
@@ -193,21 +194,17 @@ function verifyVersion(partial, version) {
 }
 
 /**
- * Point `current` at the new version atomically: a `current.tmp` symlink then a
- * rename over `current`, so a concurrent reader sees either the old target or
- * the new one, never a missing link.
+ * Point `current` at the new version. `linkDirectory` owns how: a rename over
+ * a sibling temporary link where the platform makes that atomic, a remove and
+ * remake on Windows where it does not.
  *
  * @param {string} home
  * @param {string} version
  * @returns {void}
  */
 function repointCurrent(home, version) {
-  const link = currentLink(home);
-  const temporary = `${link}.tmp`;
-  rmSync(temporary, { force: true });
   // SPEC.md's layout: `current -> versions/<v>`, relative to the home.
-  symlinkSync(join("versions", version), temporary);
-  renameSync(temporary, link);
+  linkDirectory(currentLink(home), join("versions", version));
 }
 
 /** @returns {Record<string, string>} */

package/src/cli.mjs

@@ -9,8 +9,11 @@ import { parseArgs } from "node:util";
 import { fileURLToPath } from "node:url";
 import { modelsCommand } from "./harnesses/catalogue.mjs";
 import { bulkReadCommand } from "./engine/bulk-read.mjs";
-import { doctorCommand, environmentPreflight, findExecutable, notifyTransportCheck, reachableRuntimes, timeVerificationCommands } from "./host/preflight.mjs";
+import { doctorCommand, environmentPreflight, notifyTransportCheck, reachableRuntimes, timeVerificationCommands } from "./host/preflight.mjs";
+import { findExecutable } from "./host/platform.mjs";
 import { packageName, packageVersion } from "./host/package.mjs";
+import { faberunHome } from "./host/home.mjs";
+import { reassociateProject } from "./cli/project.mjs";
 import { colorLevel, renderBanner, renderUsage, statusToken } from "./cli/brand.mjs";
 import { noTransportWarning } from "./notify/index.mjs";
 import { renderFindings, renderReport, renderReportJson, renderStatus, renderStatusJson } from "./report/render.mjs";
@@ -19,6 +22,8 @@ import { renderNext, renderNextJson } from "./report/next.mjs";
 import {
   writeTextAtomic,
 } from "./run/store.mjs";
+import { runDirectory, runsRoot } from "./run/paths.mjs";
+import { migrateRunState } from "./run/migrate.mjs";
 import {
   acquire as acquireLock,
   validBootstrapNonce,
@@ -105,6 +110,8 @@ export const COMMAND_OPTIONS = {
   "bulk-read": { question: { type: "string" }, paths: { type: "string", multiple: true }, json: { type: "boolean" } },
   next: { cwd: { type: "string" }, json: { type: "boolean" } },
   update: { check: { type: "boolean" }, json: { type: "boolean" } },
+  project: { from: { type: "string" } },
+  migrate: { cwd: { type: "string" } },
   setup: { yes: { type: "boolean" }, harnesses: { type: "string" }, worker: { type: "string" }, judge: { type: "string" }, "no-skill": { type: "boolean" }, json: { type: "boolean" } },
   init: { cwd: { type: "string" }, yes: { type: "boolean" }, "no-skill": { type: "boolean" }, agentkit: { type: "boolean" }, greenfield: { type: "boolean" }, stable: { type: "boolean" }, json: { type: "boolean" } },
   metrics: METRICS_OPTIONS,
@@ -145,7 +152,8 @@ function parseCli(argv, quiet = false) {
   if (command === "update" && parsed.positionals.length !== 0) return null;
   if (command === "setup" && parsed.positionals.length !== 0) return null;
   if (command === "init" && parsed.positionals.length !== 0) return null;
-  if (command !== "doctor" && command !== "models" && command !== "bulk-read" && command !== "next" && command !== "update" && command !== "setup" && command !== "init" && parsed.positionals.length !== 1) return null;
+  if (command === "migrate" && parsed.positionals.length !== 0) return null;
+  if (command !== "doctor" && command !== "models" && command !== "bulk-read" && command !== "next" && command !== "update" && command !== "setup" && command !== "init" && command !== "migrate" && parsed.positionals.length !== 1) return null;
   return {
     command,
     target: parsed.positionals[0],
@@ -246,7 +254,7 @@ async function main(argv) {
   }
   if (command === "next") {
     const cwd = resolve(typeof values.cwd === "string" ? values.cwd : ".");
-    const runsDir = join(cwd, ".runs");
+    const runsDir = runsRoot(cwd);
     process.stdout.write(values.json === true ? renderNextJson(runsDir, cwd) : renderNext(runsDir, cwd));
     return;
   }
@@ -288,13 +296,31 @@ async function main(argv) {
     });
     return;
   }
+  if (command === "migrate") {
+    const result = migrateRunState(resolve(typeof values.cwd === "string" ? values.cwd : "."), { home: faberunHome(process.env) });
+    if (!result.moved) {
+      process.stdout.write(`[migrate] nothing to move · ${result.legacy} does not exist\n`);
+      return;
+    }
+    const runs = `${result.runs} run${result.runs === 1 ? "" : "s"}`;
+    const campaigns = `${result.campaigns} campaign${result.campaigns === 1 ? "" : "s"}`;
+    process.stdout.write(`[migrate] ${result.legacy} -> ${result.target} · ${runs}, ${campaigns}\n`);
+    return;
+  }
   if (!target) { usage(); return; }
+  if (command === "project") {
+    const record = reassociateProject(faberunHome(process.env), target, {
+      from: typeof values.from === "string" && values.from ? values.from : undefined,
+    });
+    process.stdout.write(`[project] ${record.id} · ${record.path}\n`);
+    return;
+  }
   if (command === "run") {
     warnIfNoTransport();
     const absolute = resolve(target);
     const baseRef = typeof values["base-ref"] === "string" && values["base-ref"] ? values["base-ref"] : undefined;
     const contract = validateContractForLaunch(JSON.parse(readFileSync(absolute, "utf8")), absolute, { baseRef });
-    const runDir = join(contract.cwd, ".runs", contract.id);
+    const runDir = runDirectory(contract.cwd, contract.id);
     setLaunchBaseRef(baseRef);
     // 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

package/src/contract/index.mjs

@@ -20,6 +20,16 @@ import { crossNodeScopeFindings, scopeClosureFindings } from "../repo/scope-clos
 
 export { CONTRACT_VERSION, PROTOCOL_SCHEMA_VERSION } from "../harnesses/index.mjs";
 
+// Mirrors test/repo/source-shape.test.mjs's LINE_CEILING; that test refuses a
+// file over it, at commit time. The margin is 100 lines: measured against
+// this tree (`find src -name '*.mjs' | xargs wc -l`, 2026-09-18), it is the
+// smallest round number that would have flagged both write targets a real
+// node overran -- 783 and 749 lines, both later landing at 801 -- while
+// catching only about 8 of this tree's ~230 modules today, so the warning
+// stays rare enough to read instead of becoming routine noise.
+const WRITE_FILE_LINE_CEILING = 800;
+const WRITE_FILE_LINE_WARN_MARGIN = 100;
+
 const CONTRACT_FIELDS = new Set([
   "schemaVersion", "contractVersion", "id", "campaignId", "goal", "cwd", "sourceIdentity",
   "maxParallel", "pollIntervalMs", "stallTimeoutSec", "timeoutSec",
@@ -337,6 +347,7 @@ export function validateContract(raw, contractPath, options = {}) {
   const warnings = nodes.flatMap((node, index) => [
     ...commandCoverageWarnings(node, index),
     ...(persisted ? [] : unsnapshottedWriteWarnings(node, index, cwd)),
+    ...(persisted ? [] : writeFileLineBudgetWarnings(node, index, cwd)),
   ]);
   const contract = /** @type {ValidatedContract} */ ({
     ...raw,
@@ -620,6 +631,39 @@ function dependencyCoversPath(closure, path, cwd) {
   return false;
 }
 
+/**
+ * A `writeFiles` entry naming a file already close to the line ceiling is
+ * legal -- the ceiling refuses the file itself, at commit time, not the
+ * contract that names it -- but a worker cannot discover the file has no
+ * room for its diff until an attempt has already spent an invocation
+ * finding out. This warns, never refuses, so the author decides whether the
+ * write set needs a split before dispatch. A missing file has no current
+ * count to warn about, so it is skipped, not treated as zero.
+ *
+ * @param {ValidatedNode} node
+ * @param {number} index
+ * @param {string} cwd
+ * @returns {string[]}
+ */
+function writeFileLineBudgetWarnings(node, index, cwd) {
+  const warnings = [];
+  for (const path of node.taskPacket.writeFiles ?? []) {
+    let text;
+    try {
+      text = readFileSync(resolve(cwd, path), "utf8");
+    } catch {
+      continue;
+    }
+    const lines = text.split("\n").length;
+    const remaining = WRITE_FILE_LINE_CEILING - lines;
+    if (remaining > WRITE_FILE_LINE_WARN_MARGIN) continue;
+    warnings.push(
+      `nodes[${index}] (${node.id}): writeFiles ${path} is already ${lines} lines, ${remaining} from the ${WRITE_FILE_LINE_CEILING}-line ceiling; confirm this node's write has room before it starts`,
+    );
+  }
+  return warnings;
+}
+
 /**
  * @param {string} root
  * @param {string} cwd

package/src/contract/task-packet.mjs

@@ -27,6 +27,15 @@ const PROMPT_MAX_BYTES = 64 * 1024;
  */
 const VERIFICATION_PARAGRAPH = "The controller runs every command below after you report; its recorded results are the proof of this node. Running a command yourself is optional and only for one that finishes in seconds and spawns no long-lived process. Keep output bounded (pipe through `| tail -n 200`). Never wait on a background job, never run the whole test suite, and never run tests that start and terminate other processes.";
 
+/**
+ * The `## Required output` schema every mode states: literally every key
+ * `validateWorkerResult` requires, so a worker never loses a valid result to
+ * a field this paragraph failed to name. What belongs in `artifacts` (if
+ * anything) is this packet's own content contract, stated in its own
+ * `instructions`, not repeated or guessed here.
+ */
+const REQUIRED_OUTPUT_SCHEMA = 'Return exactly one JSON object, with no markdown or prose, matching this shape: {"status":"done"|"blocked_context","summary":"string","verification":["string"],"artifacts":["string"],"missingContext":["string"]}. status is "done" when the node is complete or "blocked_context" when required context is missing; summary is prose for a human reader; verification and artifacts are string arrays, sent as [] when this node ran no command or has nothing to put there; missingContext lists exactly what is absent, non-empty only for blocked_context. Use blocked_context only when missingContext is non-empty; use done only when missingContext is empty.';
+
 /**
  * `validateRelativePath`'s answer when a path is absent and the caller asked to
  * defer the missing-path verdict rather than throw it. Only contract loading
@@ -128,7 +137,7 @@ export function renderWorkerPrompt(packet, nodeId) {
     ...packet.verification.map((command) => `- ${command.argv.join(" ")}`),
     "",
     "## Required output",
-    'Return exactly one JSON object, with no markdown or prose: {"status":"done"|"blocked_context","summary":"string","verification":["string"],"artifacts":["string"],"missingContext":["string"]}. Use blocked_context only when missingContext is non-empty; use done only when missingContext is empty.',
+    REQUIRED_OUTPUT_SCHEMA,
   ];
   const prompt = `${lines.join("\n")}\n`;
   if (Buffer.byteLength(prompt, "utf8") > PROMPT_MAX_BYTES) {
@@ -432,7 +441,7 @@ function renderDiscoveryPrompt(packet, nodeId) {
     ...bulletOrNone(packet.nonGoals),
     "",
     "## Required output",
-    'Return exactly one worker-result JSON object, with no markdown or prose. Set status to "done", missingContext to [], and artifacts to an array containing exactly one JSON-stringified execution task packet with every required taskPacket field. The packet readFiles and writeFiles must be non-empty and scoped to this repository. Put structured findings meant to inform that packet in `output` (a JSON object, at most 65536 bytes); prose belongs in `summary`.',
+    `${REQUIRED_OUTPUT_SCHEMA} Put structured findings meant to inform this packet's own instructions in \`output\` instead (a JSON object, at most 65536 bytes).`,
     "",
     "## Verification",
     VERIFICATION_PARAGRAPH,
@@ -481,7 +490,7 @@ function renderAutonomousPrompt(packet, nodeId) {
     ...packet.verification.map((command) => `- ${command.argv.join(" ")}`),
     "",
     "## Required output",
-    'Return exactly one JSON object, with no markdown or prose: {"status":"done"|"blocked_context","summary":"string","verification":["string"],"artifacts":["string"],"missingContext":["string"]}. Use blocked_context only when missingContext is non-empty; use done only when missingContext is empty.',
+    REQUIRED_OUTPUT_SCHEMA,
   ];
   const prompt = `${lines.join("\n")}\n`;
   if (Buffer.byteLength(prompt, "utf8") > PROMPT_MAX_BYTES) throw new TypeError(`worker prompt exceeds ${PROMPT_MAX_BYTES} bytes`);

package/src/engine/cancel.mjs

@@ -17,6 +17,7 @@ import { terminateInvocation } from "./process.mjs";
 import { join, resolve } from "node:path";
 import { readFileSync } from "node:fs";
 import { readRunNodes } from "./scheduler.mjs";
+import { deleteRef, releaseAttemptWorktree, runRefName } from "../repo/worktree.mjs";
 import { syncAgentSignal } from "../repo/signal.mjs";
 import { transition, writeNode } from "./state.mjs";
 import { validateContract } from "../contract/index.mjs";
@@ -107,6 +108,18 @@ export async function cancelRun(runDirPath) {
       throw error;
     }
     if (!await waitForTerminal(runDir, 1_000)) throw new Error("cancel could not confirm a terminal run state");
+    // The run directory is evidence a campaign ledger may still want, so it
+    // stays; the run ref and every node's attempt branch are just git names
+    // the next launch of this same contract id needs back, and cancel is the
+    // operator saying this run is over. Releasing a name is not destroying a
+    // record -- each state's `worktree.branch`/`commit` fields, and the sha
+    // this ref pointed at, remain in the persisted snapshot regardless.
+    // Idempotent both ways: `removeWorktree` and `deleteRef` already tolerate
+    // an artefact a previous cancel (or the run itself) already released.
+    for (const state of states) {
+      if (state.worktree?.branch) releaseAttemptWorktree(contract.cwd, state.worktree.path, state.worktree.branch);
+    }
+    deleteRef(contract.cwd, runRefName(contract.id));
     syncAgentSignal(join(runDir, ".."));
     return true;
   } finally {

package/src/engine/dispatch.mjs

@@ -21,8 +21,8 @@ import {
   readWorkerResultFile,
   workerProtocolPrompt,
 } from "./result-file.mjs";
-import { attemptWorkspace } from "../repo/worktree.mjs";
-import { attemptWorktreePath, createAttemptWorktree, sealAttempt } from "../repo/worktree.mjs";
+import { attemptWorkspace, createAttemptWorktree, sealAttempt } from "../repo/worktree.mjs";
+import { attemptWorktreePath } from "../run/paths.mjs";
 import { basename, dirname, join } from "node:path";
 import { boundedUtf8, errorCode, errorMessage, stableJson } from "../util.mjs";
 import { captureWorkspaceScope, captureWorkspaceSnapshot } from "../repo/workspace.mjs";
@@ -387,6 +387,7 @@ function ensureAttemptWorkspace(contract, node, state, runDir, lock) {
     runId: contract.id,
     nodeId: node.id,
     attempt: state.attempt,
+    declaredReads: node.taskPacket.readFiles,
     base: previous?.sha,
   });
   const boundary = captureWorkspaceScope(worktree.path, workerScope(node.taskPacket));
@@ -668,6 +669,19 @@ export async function startJudge(contract, node, state, runDir, running, workerR
       error.code = "judge_prompt_too_large";
       throw error;
     }
+    // Captured at the last possible instant before the judge can touch
+    // anything, so the settlement pass's comparison proves what the judge
+    // itself wrote rather than racing whatever ran just before dispatch. A
+    // capture failure must not block dispatch -- the write check is a
+    // controller invariant on top of whatever the judge does, not a
+    // precondition for running it -- so it degrades to unchecked instead of
+    // to a refusal.
+    let judgeBaseline;
+    try {
+      judgeBaseline = captureWorkspaceSnapshot(workspace);
+    } catch {
+      judgeBaseline = null;
+    }
     const job = startProcess({
       contract, node, state, runtime, workspace,
       prompt: phasePlan.prompt,
@@ -678,6 +692,10 @@ export async function startJudge(contract, node, state, runDir, running, workerR
       }),
       onInvocation: (invocation, currentJob) => {
         stampInvocation(invocation, contract, node, runtime, state, runDir, "judge", phasePlan.mode, phasePlan.continuationId);
+        // Reusing the worker phase's own scratch field: a job is never both a
+        // worker and a judge, and this field carries no persisted shape of
+        // its own that a judge borrowing it would have to match.
+        currentJob.scopeBaseline = judgeBaseline;
         persistInvocation(runDir, state, invocation, currentJob, lock);
         persistInvocationIntent(runDir, invocation, {
           nodeId: node.id,

package/src/engine/lifecycle.mjs

@@ -17,17 +17,8 @@ import {
   SETTLED,
 } from "./prompts.mjs";
 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 { routeRuntimeForState, routingBackoffActive, runtimeSnapshot } from "./failover.mjs";
 import {
@@ -65,6 +56,7 @@ import { startJudge, startResultMaterialization } from "./dispatch.mjs";
 import { raiseNodeAttention, settleDone } from "./settle.mjs";
 import { applyRejection, applyVerificationFailure } from "./settle.mjs";
 import { emitNodeAdvisories } from "./notify-queue.mjs";
+import { judgeWorkspaceWriteViolation, settleJudgeRound } from "./settle-judge.mjs";
 
 /** @typedef {import("../repo/integrate.mjs").IntegrationResult} IntegrationResult */
 /** @typedef {import("./backoff.mjs").Transition} Transition */
@@ -80,7 +72,6 @@ import { emitNodeAdvisories } from "./notify-queue.mjs";
 /** @typedef {import("../contract/index.mjs").GateResult} GateResult */
 /** @typedef {import("../contract/index.mjs").SnapshotError} SnapshotError */
 /** @typedef {import("../contract/index.mjs").BoundedScope} BoundedScope */
-/** @typedef {import("../repo/workspace.mjs").WorkspaceSnapshot} WorkspaceSnapshot */
 /** @typedef {import("../run/lock.mjs").LockRecord} LockRecord */
 /** @typedef {ReturnType<typeof acquireLock>} LockHandle */
 /** @typedef {import("../harnesses/index.mjs").HarnessRuntime} HarnessRuntime */
@@ -90,7 +81,6 @@ import { emitNodeAdvisories } from "./notify-queue.mjs";
 /** @typedef {import("../contract/verification.mjs").VerificationAttempt} VerificationAttempt */
 /** @typedef {import("../contract/verification.mjs").VerificationAttemptResult} VerificationAttemptResult */
 /** @typedef {import("../contract/verification.mjs").VerificationResult} VerificationResult */
-/** @typedef {import("../repo/workspace.mjs").ScopeComparison} ScopeComparison */
 /** @typedef {import("../contract/worker-result.mjs").WorkerResult} WorkerResult */
 /** @typedef {import("../campaign/index.mjs").Campaign} Campaign */
 /** @typedef {{path: string, campaign: Campaign}} CampaignRef */
@@ -277,7 +267,7 @@ export function autoRetryParkedNodes(contract, runDir, states, lock, previouslyP
  *
  * @param {NodeSnapshot} state
  */
-function clearTierExhaustion(state) {
+export function clearTierExhaustion(state) {
   if (!state.routing || state.routing.tierExhaustion === undefined) return;
   const routing = { ...state.routing };
   delete routing.tierExhaustion;
@@ -393,6 +383,25 @@ export async function finalizeClosedJobs(contract, runDir, states, running, lock
     appendUsageRecord(runDir, state.invocations.find((invocation) => invocation.id === job.invocation.id));
     state.usage = invocationUsage(state);
     state.costUsd = invocationCost(state);
+    // Checked before any other branch can act on how this invocation closed --
+    // a done verdict, a provider failure, a bounded re-dispatch, or exhaustion
+    // -- so a judge that wrote into its own workspace is caught here rather
+    // than laundered through a re-dispatch whose fresh baseline would already
+    // contain the write (the whole point of TECH-SPEC's write check: blocked
+    // outright, never re-asked). A comparison that cannot even be completed --
+    // an edited ignore source, a symlink escaping the tree, too many entries --
+    // is the same violation as an ordinary write, never silence: the worker
+    // path (`engine/scope.mjs`'s `checkWorkerScope`) already fails closed on
+    // exactly the same throw.
+    if (job.phase === "judge") {
+      const violation = judgeWorkspaceWriteViolation(job);
+      if (violation) {
+        clearTierExhaustion(state);
+        transition(runDir, state, "blocked", { phase: "judge", result: state.result, usage: state.usage, error: { code: "judge_protocol", message: violation.message } }, lock);
+        await raiseNodeAttention(campaignPath, runDir, state, "judge_protocol");
+        continue;
+      }
+    }
     // A closed worker whose canonical result file is valid and whose scope
     // passed is completed work, no matter what the provider envelope or the
     // exit code said. The durable file was read above, before the scope gate,
@@ -425,55 +434,17 @@ export async function finalizeClosedJobs(contract, runDir, states, running, lock
       continue;
     }
     // 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 (job.phase === "judge" && 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, job.node, state, "judge", envelope, job.exitCode);
-      if (network && handleProviderExhaustion(contract, runDir, job.node, state, "judge", envelope, job.runtime.id, lock, states, campaignPath, network)) continue;
-      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.
-      // 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, job.node, state, runDir, running, lock, states, campaignPath, envelope.error?.message ?? "judge provider failed");
-        continue;
-      }
-      state.judgeFailures = (state.judgeFailures ?? 0) + 1;
-      if (state.judgeFailures < JUDGE_MAX_FAILURES) {
-        writeNode(runDir, state, lock);
-        await applyJudgeRound(await startJudge(contract, job.node, state, runDir, running, state.result, lock, states, campaignPath),
-          contract, job.node, state, runDir, running, lock, states, campaignPath, state.result);
-        continue;
-      }
-      await settleUnavailableJudge(contract, job.node, state, runDir, lock, states, campaignPath, envelope.error?.message ?? "judge provider failed");
-      continue;
-    }    // 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.
+    // gone) is a provider failure, never a verdict, and a verdict that arrived
+    // but is not exactly one usable one (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) is a protocol defect rather than a
+    // pass. Both are settled by `settleJudgeRound`, moved out of this file
+    // for the same reason `engine/settle.mjs` was: this file and
+    // `test/engine/judge.test.mjs` both sit on the 800-line ceiling
+    // `test/repo/source-shape.test.mjs` enforces. The write check above has
+    // already run, so nothing here can adopt or launder a judge's own write.
     if (job.phase === "judge") {
-      const evidence = judgeVerdictEvidence(envelope);
-      if (!evidence.ok) {
-        const network = networkTransition(contract, job.node, state, "judge", envelope, job.exitCode);
-        if (network && handleProviderExhaustion(contract, runDir, job.node, state, "judge", envelope, job.runtime.id, lock, states, campaignPath, network)) continue;
-        clearTierExhaustion(state);
-        await applyJudgeProtocolFailure(contract, job.node, state, runDir, running, lock, states, campaignPath, evidence.reason);
-        continue;
-      }
-      clearTierExhaustion(state);
-      await applyJudgeResult(contract, job.node, state, evidence.result, runDir, lock, running, states, campaignPath);
+      await settleJudgeRound(contract, job, state, runDir, running, lock, states, campaignPath, envelope, { clearTierExhaustion, handleProviderExhaustion });
       continue;
     }
     // An empty final message is a missing worker result, not a no-op worker:
@@ -550,7 +521,13 @@ export async function finalizeClosedJobs(contract, runDir, states, running, lock
         await applyInvalidWorkerResult(contract, job.node, state, runDir, running, lock, errorMessage(error), states, campaignPath);
         continue;
       }
-      if (job.node.taskPacket.mode === "discovery" && workerResult.status === "done") {
+      // The artifact demand follows the documented discovery contract, not the
+      // mode alone: only a packet with no read files -- the one exception to
+      // closed scope, allowed to read the repository to produce an execution
+      // packet -- owes that artifact. A discovery packet closed to its listed
+      // read files delivers through `output` (a planning node's plan or
+      // findings) and carries none.
+      if (job.node.taskPacket.mode === "discovery" && job.node.taskPacket.readFiles.length === 0 && workerResult.status === "done") {
         try {
           parseDiscoveryResult(workerResult, attemptWorkspace(state) ?? contract.cwd);
         } catch (error) {