faberun 0.9.0 → 0.11.0

package/README.md

@@ -2,7 +2,9 @@
 
 <h1 align="center">faberun</h1>
 
-<p align="center">From intent to running software.</p>
+<p align="center"><strong>From intent to running software.</strong></p>
+
+<p align="center">Graph engineering for coding agents.</p>
 
 <p align="center">
   <a href="https://github.com/feliperun/faberun/actions/workflows/ci.yml"><img src="https://github.com/feliperun/faberun/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
@@ -10,21 +12,162 @@
   <a href="https://www.npmjs.com/package/faberun"><img src="https://img.shields.io/npm/v/faberun" alt="npm version"></a>
 </p>
 
-Faberun is a development orchestration system that turns intent into verified
-software. It manages the process around software creation: plans, tasks,
-dependencies, execution, validation, evidence, retries and progress toward a
-defined outcome. It is not another coding agent, and it does not generate code
-without a definition of done.
+Faberun is a graph-engineering runtime for building software with coding agents.
+It sits above the models and the harnesses and turns an implementation plan into
+a durable graph of tasks, dependencies, workers, proofs, reviews, retries and
+integration gates.
+
+Harnesses are execution environments: Claude Code, Codex, the Gemini, DeepSeek
+and GLM shells, and a generic `exec-jsonl` door for whatever comes next. Models
+are the engines inside them. Faberun owns the graph, the state and the
+definition of done around both.
+
+The goal is not to make a group of agents talk to each other. It is to use the
+right model for each kind of work, keep the process independent of any single
+model or harness, and require evidence before software counts as done.
+
+## Why Faberun
+
+Coding agents are already very good at changing repositories. The remaining
+problem is everything around that execution.
+
+A frontier model earns its cost when it reasons about architecture, challenges a
+design, writes a specification or reviews a difficult decision. The same model
+is usually unnecessary for a small, well-defined implementation task a much
+cheaper one performs well. Without an orchestration layer, though, the model
+driving the current session becomes the model doing everything.
+
+Faberun separates those concerns. One campaign can use a frontier model to
+reason about the problem and author a plan, a second strong model to attack that
+plan, lower-cost models to execute well-defined implementation nodes, a model
+from another vendor to judge the work that genuinely needs judgment, and plain
+deterministic commands wherever no model is needed at all. The expensive
+intelligence goes where it matters, and the rest becomes an execution problem.
+
+It also takes the campaign out of the lifetime of one chat. The work has durable
+state on disk, so Claude Code can start a campaign and Codex, DeepSeek, GLM or
+any other adapted harness can continue it later without reconstructing the
+process from a conversation history.
+
+## Graph engineering
 
-Faberun is model- and harness-agnostic. Claude Code, Codex, OpenCode and
-whatever comes next are workers; Claude, GPT, Gemini, DeepSeek, GLM and other
-models are engines; Faberun sits above them. It keeps the intent, coordinates
-the work, tracks what was actually completed, validates the result and decides
-what should happen next.
+Faberun treats development as an executable graph rather than a long
+conversation.
 
-Software should be built, not merely generated. A craftsman does not depend on
-one hammer, so Faberun does not depend on one model or one agent: tools,
-models and harnesses can change, and the work remains.
+```text
+intent
+  └─ campaign
+       └─ contract
+            ├─ node A ── proof ── review ──┐
+            ├─ node B ── proof ── review ──┼── integration ── promotion
+            └─ node C ── proof ── review ──┘
+```
+
+A campaign carries the durable intent. A contract turns part of that intent into
+a schema-versioned DAG. Each node carries a closed packet: what the worker may
+read, what it may change, what done means, and how that claim has to be proven.
+The graph decides what can run, what must wait, what may retry, what needs a
+human and what is allowed to advance. The models are replaceable participants
+inside it. The graph remains.
+
+## What is different
+
+### Use the right model for the job
+
+A runtime is one harness running one model. Workers, judges and planning
+sessions need not share a provider or a capability tier, so high-cost reasoning
+and low-cost execution live in the same campaign instead of one model owning the
+whole process. Changing providers is a routing decision, not a rewrite of the
+workflow.
+
+### Proof before opinion
+
+A worker saying "done" is not evidence that it is. Every definition-of-done item
+declares how it can be proven: a command that must succeed, a path that must
+exist, or — only when the criterion cannot be mechanised — the judgment of a
+judge. Mechanical verification always runs first, and a node whose proofs are
+all mechanical settles without spending a token on review. A gate may also
+declare `skipWhen`, so a change that is green and small enough skips the judge
+by policy rather than by accident.
+
+### Independent review
+
+When judgment is required, the worker does not grade itself. Validation refuses
+a gated node whose worker and judge resolve to the same vendor. The judge reads
+the recorded result and its evidence, never the reasoning that produced it, and
+never re-runs the work. The point is not to make two agents agree; it is to keep
+implementation and acceptance as separate responsibilities.
+
+### Isolated execution
+
+Each attempt runs in its own git worktree, so independent nodes run at the same
+time without sharing a mutable working tree, and accepted work reaches the
+repository through controlled refs instead of being copied into the operator's
+checkout. The operator keeps working while the campaign runs.
+
+### Durable campaigns
+
+A run is not tied to the terminal that launched it. The controller runs
+detached, state is persisted under `.runs/`, `supervise` resumes a controller
+that died, and a campaign carries its intent across many runs and sessions. If a
+provider goes down or a harness session ends, the work does not have to be
+re-authored.
+
+### Safe integration
+
+Passing a worker's own checks is not the end of the process. An accepted attempt
+is sealed, integrated onto the run ref and verified again in the candidate
+state, and the phase-terminal node runs the contract's final verification. If
+combining individually valid changes breaks the system, the campaign does not
+promote them.
+
+### Measurable model economics
+
+Every invocation records its usage, routing and outcome, and a closed campaign
+keeps that ledger in its own record under `docs/campaigns/<id>/ledger/`. It makes
+questions like these measurable instead of anecdotal: which model handles this
+class of task reliably, where a frontier model is actually worth its price,
+which nodes close mechanically with no judge at all, how many revisions a worker
+needs before acceptance, what one closed checkpoint costs, and how often a
+fallback saves a campaign. The objective is not to spend less. It is to know
+where expensive intelligence creates value.
+
+## Campaigns, not synthetic teams
+
+Faberun does not model an agent process as a human organisation. It needs no "AI
+architect", "AI developer", "AI QA engineer" and "AI product manager" merely
+because human teams carry those titles: models are general enough that those
+boundaries are mostly artificial. The roles it does define are the ones that
+stay useful for agents.
+
+| role | responsibility |
+| --- | --- |
+| worker | produces a result inside its packet. |
+| judge | decides independently whether a result that needs judgment satisfies its contract. |
+| controller | advances the graph deterministically. |
+| operator | supplies the intent and intervenes when a decision genuinely needs a human. |
+
+Everything else belongs in the contract.
+
+## From spec to contract
+
+Planning is part of the product, and it is adversarial on purpose. `faberun spec
+validate` checks a specification's front matter, its `R<n>` requirements and the
+proof each one declares, and invokes no model to do it. `faberun plan` then runs
+the debate in budgeted, isolated runs: an author drafts, a reviewer from another
+vendor attacks the draft holding only the spec, the repository facts and the
+plan under review, and a revision round follows while a critical finding
+remains. A converged draft is sized, routed and frozen into a contract. Freezing
+never launches, and a plan that never converges ends `contested`, with its open
+findings recorded as a campaign question instead of a contract.
+
+None of it is mandatory. The traceability rules are advisory unless you ask for
+`--strict-traceability`, a document with no front matter validates as `legacy`
+rather than being rejected, and you can skip planning altogether and author the
+contract by hand. What Faberun needs is the executable part of the plan:
+objective, nodes, dependencies, read and write scope, definitions of done,
+verification, runtime policy and integration behaviour. Your specification
+process stays yours.
 
 ## Install
 
@@ -92,29 +235,35 @@ The operator writes the intent into a campaign and an authored contract, a
 schema-versioned DAG whose nodes each carry a closed task packet. The controller
 schedules every dependency-ready node and dispatches its packet to a worker
 inside an attempt worktree, where the worker sees only the files the packet
-names. The controller then runs the deterministic verification once, and a
-judge from a different vendor reviews the recorded result without re-running it.
-A passing attempt is sealed and integrated onto the run ref, a campaign promotes
-each run onto its landing branch, and the orchestrator lands that branch.
-Campaigns, handoffs and the `supervise` watchdog carry the work across sessions,
-so an interrupted run is continued in place instead of being re-authored.
+names. Faberun then judges the result in stages, and a free slot dispatches the
+next node while another one is still being verified.
 
 ```text
-intent
-  └─ contract: validate · preflight
-       └─ controller
-            ├─ worker attempt in an attempt worktree
-            │     └─ deterministic verification · cross-vendor judge
-            └─ integration ref · promotion · landing branch
+packet
+  └─ worker attempt in its own worktree
+       └─ mechanical proof ── failure ─→ retry · route · attention
+            └─ judge, when required ── rejection ─→ revision
+                 └─ seal ─→ integration ref ─→ candidate verification
+                      └─ promotion onto the campaign's landing branch
 ```
 
-The vocabulary is in [Concepts](docs/CONCEPTS.md), and the layers, process
-model and gates are in [Architecture](docs/ARCHITECTURE.md).
+A judge reviews recorded evidence rather than re-running arbitrary work. A
+passing attempt is sealed and integrated onto the run ref, a campaign promotes
+each finished run onto its landing branch, and the orchestrator lands that
+branch. Campaigns, handoffs and the `supervise` watchdog carry the work across
+sessions, so an interrupted run is continued in place instead of being
+re-authored.
 
-## Harnesses
+The vocabulary is in [Concepts](docs/CONCEPTS.md), and the layers, process model
+and gates are in [Architecture](docs/ARCHITECTURE.md).
 
-A runtime is one harness running one model. Any runtime can be a worker, and a
-judge of another vendor reviews what it produced.
+## Harnesses and models
+
+Faberun keeps three things apart. A **model** is the reasoning engine, a
+**harness** is the environment that gives a model access to code and tools, and
+a **runtime** is one configured harness-and-model pair Faberun can dispatch. Any
+runtime can act as a worker or as a judge, according to the contract and the
+routing policy.
 
 | Harness | Default vendor | Example model |
 | --- | --- | --- |
@@ -126,6 +275,19 @@ judge of another vendor reviews what it produced.
 | `exec-jsonl` | declared per runtime | the model its command names |
 | `replay` | declared per runtime | the recorded model |
 
+Harness and model support are adapter concerns. The orchestration above them
+depends on no single vendor.
+
+## Philosophy
+
+Software should be built, not merely generated. Generating plausible code is
+becoming cheap; the valuable part is the system around the generation —
+preserving intent, decomposing work, choosing the appropriate intelligence,
+isolating effects, proving outcomes, recovering from failure, and recording why a
+change was accepted. A craftsman does not depend on one hammer, and Faberun does
+not depend on one model. Models change, harnesses change, providers change. The
+intent, the graph, the evidence and the finished work remain.
+
 ## Documentation
 
 - [Documentation map](docs/README.md): every document and the question it answers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faberun",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Faberun is a development orchestration system that turns intent into verified software: harness- and model-agnostic, it keeps the intent, coordinates the work, verifies the result and decides what happens next.",
   "type": "module",
   "bin": {

package/src/campaign/chain.mjs

@@ -290,6 +290,25 @@ export function validateContractAgainstRef(raw, contractPath, context = {}) {
   }
 }
 
+/**
+ * Validate a contract for a launch, the one path the CLI's `run` command and
+ * the scheduler's own re-validation both go through: against `baseRef` when
+ * one is given, the checkout otherwise. `repo` defaults to the contract's own
+ * `cwd` when the caller does not know a better one (the campaign chain always
+ * passes its own), since a contract's `cwd` is always inside the repo it
+ * names.
+ *
+ * @param {Record<string, unknown>} raw
+ * @param {string} contractPath
+ * @param {{repo?: string, baseRef?: string}} [context]
+ * @returns {ValidatedContract}
+ */
+export function validateContractForLaunch(raw, contractPath, context = {}) {
+  if (!context.baseRef) return validateContract(raw, contractPath);
+  const repo = context.repo ?? resolve(dirname(contractPath), typeof raw.cwd === "string" ? raw.cwd : ".");
+  return validateContractAgainstRef(raw, contractPath, { repo, baseRef: context.baseRef });
+}
+
 /**
  * Reduce a run's progress to the one decision the chain makes. An in-flight run
  * is `unfinished` even though `reduceRunOutcome` already names its running nodes

package/src/cli.mjs

@@ -24,6 +24,7 @@ import {
   validBootstrapNonce,
 } from "./run/lock.mjs";
 import { renderRunHandoff } from "./campaign/index.mjs";
+import { validateContractForLaunch } from "./campaign/chain.mjs";
 import { campaignCli } from "./cli/campaign.mjs";
 import { seatCli } from "./cli/seat.mjs";
 import { initCommand } from "./cli/init.mjs";
@@ -291,9 +292,9 @@ async function main(argv) {
   if (command === "run") {
     warnIfNoTransport();
     const absolute = resolve(target);
-    const contract = validateContract(JSON.parse(readFileSync(absolute, "utf8")), absolute);
-    const runDir = join(contract.cwd, ".runs", contract.id);
     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);
     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
@@ -314,7 +315,7 @@ async function main(argv) {
       return;
     }
     for (const warning of [...contract.warnings, ...reusedDoneWarnings(contract)]) process.stdout.write(`${advisoryToken()} ${warning}\n`);
-    const result = await runContract(target, { detachedBootstrap: hasDetachedBootstrapNonce() });
+    const result = await runContract(target, { detachedBootstrap: hasDetachedBootstrapNonce(), baseRef });
     if (!result.ok) process.exitCode = 1;
     return;
   }

package/src/contract/final-verification.mjs

@@ -3,11 +3,13 @@
  * rule 12).
  *
  * `contract.finalVerification` is the contract-wide proof that the phase as a
- * whole closes: the controller runs it before the judge on the phase-terminal
- * node (the node no other node depends on), so no final checkpoint is ever
- * approved on partial verification. `contract.sharedVerification` carries the
- * same command schema but is appended to every node's attempt and integration
- * candidate, for the fast repository ratchets a node's write set can break.
+ * whole closes: the controller runs it before the judge, once, on whichever
+ * phase-terminal node (a node no other node depends on) is the last of them
+ * to settle, so no final checkpoint is ever approved on partial verification
+ * and a flake on one phase-terminal node cannot also cost its siblings a
+ * revision. `contract.sharedVerification` carries the same command schema but
+ * is appended to every node's attempt and integration candidate, for the fast
+ * repository ratchets a node's write set can break.
  * The persisted node-snapshot shape for verification evidence lives here too,
  * next to the schema it records.
  */
@@ -58,20 +60,49 @@ export function sharedVerificationCommands(contract) {
   return contract.sharedVerification ?? [];
 }
 
+/**
+ * Whether no other node in the contract depends on this one. `finalVerification`
+ * is a candidate to run on a phase-terminal node only; a node with a dependant
+ * never carries it, no matter which of its siblings settles last.
+ *
+ * @param {{nodes: {id: string, dependsOn: string[]}[]}} contract
+ * @param {{id: string}} node
+ * @returns {boolean}
+ */
+export function phaseTerminalNode(contract, node) {
+  return !contract.nodes.some((candidate) => candidate.dependsOn.includes(node.id));
+}
+
 /**
  * The contract's `finalVerification` commands when this node is the one that
- * closes the phase, otherwise none. A node is phase-terminal when no other
- * node in the contract depends on it.
+ * closes the phase, otherwise none. A phase can have several phase-terminal
+ * nodes (several nodes no other node depends on); the suite runs once for the
+ * phase, on whichever of them is the last to settle, not on every one of them.
+ *
+ * `settledIds` is the set of sibling node ids (any status a node does not
+ * leave on its own -- see `SETTLED` in `engine/prompts.mjs`) already reached
+ * at the moment this call is made. A phase-terminal node carries the suite
+ * exactly when every *other* phase-terminal node is already in that set --
+ * whichever node that is true for, in whatever order nodes actually settle,
+ * including a node retried after every sibling has already closed. Omitting
+ * `settledIds` (the scheduler's budget estimate, which has no run to inspect)
+ * falls back to the old per-node-shape answer: any phase-terminal node may
+ * still turn out to be the one that carries it, so the estimate stays an
+ * upper bound.
  *
  * @param {{finalVerification?: VerificationCommand[], nodes: {id: string, dependsOn: string[]}[]}} contract
  * @param {{id: string}} node
+ * @param {Set<string>} [settledIds]
  * @returns {VerificationCommand[]}
  */
-export function finalVerificationCommands(contract, node) {
+export function finalVerificationCommands(contract, node, settledIds) {
   const commands = contract.finalVerification ?? [];
   if (commands.length === 0) return [];
-  const hasDependant = contract.nodes.some((candidate) => candidate.dependsOn.includes(node.id));
-  return hasDependant ? [] : commands;
+  if (!phaseTerminalNode(contract, node)) return [];
+  if (!settledIds) return commands;
+  const siblings = contract.nodes.filter((candidate) => candidate.id !== node.id && phaseTerminalNode(contract, candidate));
+  const isLastToClose = siblings.every((sibling) => settledIds.has(sibling.id));
+  return isLastToClose ? commands : [];
 }
 
 /**

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

@@ -668,6 +668,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 +691,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: