faberun 0.30.0 → 0.32.0

package/src/engine/phase-session.mjs

@@ -2,7 +2,8 @@
  * Which provider session a node's next invocation runs in: fresh, a
  * continuation of a compatible earlier session in the same plan phase, or a
  * rotation -- a fresh session that carries the prior nodes' structured
- * summaries. Separate from dispatch.mjs, which spawns whatever this decides,
+ * summaries for a worker, and the role's own prompt, whole, for a judge.
+ * Separate from dispatch.mjs, which spawns whatever this decides,
  * because the decision reads only persisted node snapshots and the routing
  * table, and because dispatch.mjs crossed the 800-line ceiling carrying it.
  */
@@ -12,6 +13,7 @@ import { boundedUtf8, stableJson } from "../util.mjs";
 import { providerCommand } from "../harnesses/index.mjs";
 import { readJson } from "../run/store.mjs";
 import { routeRuntimeForState } from "./failover.mjs";
+import { JUDGE_PROMPT_BYTES, JUDGE_PROMPT_REASON } from "../contract/judge-envelope.mjs";
 import { validateNodeSnapshot } from "../contract/snapshot.mjs";
 
 /** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
@@ -57,6 +59,13 @@ export function forceFreshSession(state, explicit = {}) {
  * the call site is not enough, because this function rediscovers the prior
  * continuation from the persisted ledger.
  *
+ * A rotation never substitutes a synthesized text for the prompt the role was
+ * dispatched with. A worker gets the phase's prior summaries in front of its
+ * own prompt; a judge gets its own prompt, whole, because the definition of
+ * done, the evidence and the re-ask instruction it carries are the review, and
+ * the author's packet and reasoning summary are what the review is independent
+ * of.
+ *
  * @param {ValidatedContract} contract
  * @param {ValidatedNode} node
  * @param {NodeSnapshot} state
@@ -99,13 +108,11 @@ export function phaseInvocationPlan(contract, node, state, runDir, role, prompt,
   // A harness that cannot continue at all, or a session picked up from a
   // different phase-sibling node whose identity does not match this one, has
   // no native continuity: the fresh attempt carries the prior nodes'
-  // structured summaries forward instead of starting blind.
+  // structured summaries forward instead of starting blind. The judge is the
+  // exception -- it rotates onto its own prompt, never the author's.
   if (session && (!canContinue || session.nodeId !== node.id)) {
-    return {
-      prompt: phaseHandoffPrompt(contract, node, state, runDir, role),
-      continuationId: null,
-      mode: "rotate",
-    };
+    const rotated = role === "judge" ? preservedJudgePrompt(prompt) : phaseHandoffPrompt(contract, node, state, runDir, role, prompt);
+    return { prompt: rotated, continuationId: null, mode: "rotate" };
   }
   // A capable harness continuing its own node whose identity merely drifted
   // (the run directory moved, or a runtime edge) still gets the caller's own
@@ -188,8 +195,22 @@ export function fingerprintRuntime(runtime) {
   return createHash("sha256").update(stableJson({ runtime, executable })).digest("hex");
 }
 
-/** @param {ValidatedContract} contract @param {ValidatedNode} node @param {NodeSnapshot} state @param {string} runDir @param {"worker"|"judge"} role @returns {string} */
-function phaseHandoffPrompt(contract, node, state, runDir, role) {
+/**
+ * The worker's rotation prompt: the phase's prior structured summaries in front
+ * of the prompt the caller built for this attempt — the node's own packet, or
+ * the retry prompt carrying the gate's findings. Reading `node.prompt` here
+ * instead discarded whatever the caller had added to the role's effective
+ * prompt, which is the defect this rotation exists to avoid.
+ *
+ * @param {ValidatedContract} contract
+ * @param {ValidatedNode} node
+ * @param {NodeSnapshot} state
+ * @param {string} runDir
+ * @param {"worker"|"judge"} role
+ * @param {string} prompt
+ * @returns {string}
+ */
+function phaseHandoffPrompt(contract, node, state, runDir, role, prompt) {
   const summaries = phaseSessionCandidates(contract, node, state, runDir, role)
     .map(({ nodeId }) => {
       const candidate = contract.nodes.find((item) => item.id === nodeId);
@@ -211,7 +232,32 @@ function phaseHandoffPrompt(contract, node, state, runDir, role) {
     "Prior structured node summaries:",
     summaries.length ? summaries.map((summary) => `- ${summary}`).join("\n") : "- (none)",
     "Current closed task packet:",
-    boundedUtf8(node.prompt, 48 * 1024),
+    boundedUtf8(prompt, 48 * 1024),
   ].join("\n\n");
   return boundedUtf8(handoff, 60 * 1024);
 }
+
+/**
+ * The judge's effective prompt, carried whole into a fresh session, or refused.
+ *
+ * measured 2026-09-29 (review R1): the rotation used to rebuild the text from
+ * `node.prompt`, so a judge picking up a phase sibling's session was handed the
+ * author's closed packet under a "continue as the judge agent" preamble and
+ * lost the criteria, the evidence and the re-ask instruction — a judge that
+ * never sees the checklist can only be discarded by it. The judge takes none of
+ * the author's context: it is not worker continuity, it is an independent
+ * review of work the prompt already describes.
+ *
+ * The prompt is returned unmodified or not at all. Bounding it to fit would cut
+ * exactly the mandatory content, so one over `JUDGE_PROMPT_BYTES` fails before
+ * any provider is spawned, with the code every oversized judge prompt carries.
+ *
+ * @param {string} prompt
+ * @returns {string}
+ */
+function preservedJudgePrompt(prompt) {
+  if (Buffer.byteLength(prompt, "utf8") <= JUDGE_PROMPT_BYTES) return prompt;
+  const error = /** @type {Error & {code: string}} */ (new Error(JUDGE_PROMPT_REASON));
+  error.code = "judge_prompt_too_large";
+  throw error;
+}

package/src/engine/prompts.mjs

@@ -202,6 +202,58 @@ export function previousAttemptOperatorAnswer(previousAttempt) {
   return answer || null;
 }
 
+/**
+ * The heading the variable previous-attempt state travels under, byte-equal
+ * to the line `renderPreviousAttemptSection` (engine/retry.mjs) writes: two
+ * hashes, one space, `Previous attempt`, end of line. Every tolerance this
+ * match ever carried cost a node: a tolerant suffix read the task's own
+ * `## Previous attempt notes:` heading as retry state (this node's attempt
+ * 2), and a tolerant `#{1,6}` hash run read a task instruction headed
+ * `# Previous attempt` the same way (attempt 3's revision_cap) — with a
+ * state section supplied, the lifted block was replaced and the stable
+ * instructions after that heading were dropped from the worker and judge
+ * prompts. Only the writer's exact spelling may open the variable block.
+ */
+const PREVIOUS_ATTEMPT_HEADING = /^## Previous attempt$/gm;
+
+/**
+ * The line every rendered record opens with — `Attempt N failed; this is
+ * attempt M.`, the `Attempt N failed` opening `previousAttemptOperatorAnswer`'s
+ * stop regex reads as a section start, and the first body line under the
+ * heading in every record the retry writer lays down (this node's own retry
+ * records included). Requiring it behind the heading keeps the split on real
+ * trailing record blocks: an instruction block that borrows even the exact
+ * heading opens its body with other words — measured on attempt 3's
+ * revision_cap, where `Attempt 2 failed in staging` under a borrowed heading
+ * was classified as a record and split out of the stable prefix.
+ */
+const PREVIOUS_ATTEMPT_RECORD_LINE = /^Attempt \d+ failed; this is attempt \d+\./u;
+
+/**
+ * Split a prompt that already carries the variable `Previous attempt` section
+ * into the stable instructions and that section, so assembly can re-append it
+ * after the stable sandbox notice and result-file protocol — cacheable prefix
+ * first, variable state last. The section is the block from its heading to
+ * the end of the prompt: every writer lays it down as the trailing block of
+ * whatever it was built on. `section` is null when the base carries none.
+ *
+ * @param {string} basePrompt
+ * @returns {{stable: string, section: string|null}}
+ */
+export function splitPreviousAttemptSection(basePrompt) {
+  for (const match of basePrompt.matchAll(PREVIOUS_ATTEMPT_HEADING)) {
+    const rest = basePrompt.slice(match.index + match[0].length);
+    const bodyStart = rest.split("\n").find((line) => line.trim() !== "");
+    if (bodyStart !== undefined && PREVIOUS_ATTEMPT_RECORD_LINE.test(bodyStart)) {
+      return {
+        stable: basePrompt.slice(0, match.index).replace(/\n+$/u, ""),
+        section: basePrompt.slice(match.index).replace(/\n+$/u, ""),
+      };
+    }
+  }
+  return { stable: basePrompt, section: null };
+}
+
 /**
  * @param {JudgeNode} node
  * @param {unknown} workerResult
@@ -256,7 +308,6 @@ export function judgePrompt(node, workerResult, context = {}) {
     `Controller diff paths:\n${diff.length ? diff.map((path) => `- ${path}`).join("\n") : "- (none)"}\n\n` +
     `Controller verification:\n${JSON.stringify(verificationResult)}\n\n` +
     (scopeSection ? `${scopeSection}\n\n` : "") +
-    (context.previousAttempt ? `${context.previousAttempt}\n\n` : "") +
     "Return only the JSON object required by the output schema, with every field present: a verdict with nothing to report still carries `findings: []`, never an omitted key. The verdict is a record, not a report: keep `summary` within " + JUDGE_LIMITS.summaryBytes + " bytes, use at most " + JUDGE_LIMITS.findings + " findings, and keep each finding's `description` within " + JUDGE_LIMITS.descriptionBytes + " bytes and its `evidence` within " + JUDGE_LIMITS.evidenceBytes + " bytes. A verdict that overshoots this envelope is rejected unread, however sound the arbitration. Evidence must be concrete. " +
     "Use verdict pass only when findings is empty and maxSeverity is none. " +
     "Use verdict fail whenever findings is non-empty, including advisory findings below failOn. " +
@@ -264,7 +315,11 @@ export function judgePrompt(node, workerResult, context = {}) {
       ? "Arbitrate only the judgment items; deterministic items are already proven by the controller and must not be re-arbitrated. " +
         "Use pass only when every judgment item is satisfied. Every finding must cite the id of the judgment item it addresses; a fail verdict whose findings cite no id is a protocol failure."
       : "Use pass only when every Definition of Done item is satisfied. " +
-        "Assess every Definition of Done item by its id and cite the id you are addressing in each finding.");
+        "Assess every Definition of Done item by its id and cite the id you are addressing in each finding.") +
+    // The variable state trails every stable instruction, including the
+    // output-schema rules, so the cacheable prefix ends at the section's
+    // heading and dispatch's assembly keeps it last when it re-appends.
+    (context.previousAttempt ? `\n\n${context.previousAttempt}` : "");
 }
 
 /**

package/src/engine/reserve-admission.mjs

@@ -0,0 +1,99 @@
+/**
+ * Admission of one new paid dispatch through the campaign's optional reserve
+ * (ADR 0011): read the campaign record, and either admit the dispatch with a
+ * hold, admit it as unconfigured, or refuse it before any provider starts.
+ * Split from `dispatch.mjs` because the decision is one gate the worker and
+ * the judge paths must apply identically, and because its fail-closed rule
+ * needs the record read in exactly one place: a record that is present but
+ * cannot be read or validated refuses the dispatch, it is not waved through
+ * on the validation the launch performed.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { errorMessage } from "../util.mjs";
+import { CAMPAIGN_FILE } from "../campaign/layout.mjs";
+import { readCampaign } from "../campaign/record.mjs";
+import { releaseCampaignReservation, reserveCampaignCost } from "../campaign/reserve.mjs";
+
+/**
+ * The error code a node is parked blocked with when the campaign's reserve
+ * refuses its new dispatch. Deliberately outside every auto-retry set: the
+ * balance does not recover by re-dispatching, only by an operator topping it
+ * up (or the in-flight holds settling) and resuming.
+ */
+const RESERVE_INSUFFICIENT_CODE = "reserve_insufficient";
+
+/**
+ * The error code a node is parked blocked with when the campaign record is
+ * present but cannot be read or validated. Distinct from
+ * `reserve_insufficient` because the operator responses differ -- a balance
+ * needs a top-up, a broken record needs a repair -- and like it, deliberately
+ * outside every auto-retry set: re-dispatching does not make a record
+ * readable.
+ */
+const CAMPAIGN_RECORD_UNREADABLE_CODE = "campaign_record_unreadable";
+
+/**
+ * Admit one new paid dispatch through the campaign's optional reserve
+ * (ADR 0011), before the provider starts. The only measured predictor of
+ * what the call will cost is what this node's most recent invocation actually
+ * charged; a first dispatch has no measurement, so it is reserved as unknown
+ * exposure and holds nothing -- the reserve never invents a number to gate
+ * with. A refusal takes no hold and carries the error the caller parks the
+ * node blocked with. Calls already running are never touched: the reserve
+ * gates only the admission of a new one.
+ *
+ * A missing campaign path or record file is the unconfigured path the reserve
+ * never touched, and a readable record without `reserveUsd` is the same. A
+ * record that is present but cannot be read or validated is the opposite of
+ * unconfigured: it may have changed since the launch validated it, so the
+ * dispatch is refused before the provider starts instead of being assumed
+ * safe.
+ *
+ * @param {string} campaignPath
+ * @param {import("../contract/index.mjs").NodeSnapshot} state
+ * @param {string} runId
+ * @param {string} nodeId
+ * @param {"worker"|"judge"} role
+ * @returns {{refused: false, reservation: import("../campaign/reserve.mjs").Reservation|null}|{refused: true, error: {code: string, message: string}}}
+ */
+export function reserveAdmission(campaignPath, state, runId, nodeId, role) {
+  if (!campaignPath || !existsSync(join(campaignPath, CAMPAIGN_FILE))) return { refused: false, reservation: null };
+  try {
+    const campaign = /** @type {{reserveUsd?: number}} */ (/** @type {unknown} */ (readCampaign(campaignPath)));
+    if (campaign.reserveUsd === undefined) return { refused: false, reservation: null };
+  } catch (error) {
+    return { refused: true, error: {
+      code: CAMPAIGN_RECORD_UNREADABLE_CODE,
+      message: `campaign record at ${campaignPath} cannot be read or validated, refusing the new ${role} dispatch: ${errorMessage(error)}`,
+    } };
+  }
+  const last = state.invocations?.at(-1);
+  const estimateUsd = typeof last?.costUsd === "number" && Number.isFinite(last.costUsd) ? last.costUsd : null;
+  const decision = reserveCampaignCost(campaignPath, { runId, node: nodeId, costUsd: estimateUsd });
+  if (!decision.admitted) return { refused: true, error: {
+    code: RESERVE_INSUFFICIENT_CODE,
+    message: `reserve refused the new ${role} dispatch: estimated ${estimateUsd} USD cannot be held against ${decision.availableUsd ?? 0} USD available`,
+  } };
+  return { refused: false, reservation: decision.reservation };
+}
+
+/**
+ * Give a reservation back when the gated call never started (the provider
+ * could not be spawned). Never throws: a hold that cannot be released stays
+ * visible as held in `readCampaignReserve`, and the dispatch failure it rode
+ * on still settles the node.
+ *
+ * @param {string} campaignPath
+ * @param {import("../campaign/reserve.mjs").Reservation|null} reservation
+ * @returns {void}
+ */
+export function releaseReservation(campaignPath, reservation) {
+  if (!campaignPath || !reservation) return;
+  try {
+    releaseCampaignReservation(campaignPath, reservation.id);
+  } catch {
+    // The hold remains recorded; it is visible in the reserve status and no
+    // other reservation can consume it.
+  }
+}

package/src/engine/resume.mjs

@@ -15,6 +15,7 @@
 import { JUDGE_SCHEMA, SETTLED, TERMINAL } from "./prompts.mjs";
 import { Buffer } from "node:buffer";
 import { acquire as acquireLock } from "../run/lock.mjs";
+import { classifyFailureCause } from "./failure-cause.mjs";
 import { applyInvalidWorkerResult, assertRunMutable, handleProviderExhaustion } from "./lifecycle.mjs";
 import { applyJudgeResult } from "./review.mjs";
 import { assertSourceUnchanged, captureRunIdentity, recordedBaseRef, statesFingerprint } from "./run-identity.mjs";
@@ -618,6 +619,7 @@ export async function reauthorRefusedNode(options) {
   const raw = JSON.parse(readFileSync(contractPath, "utf8"));
   const refused = /** @type {{missingContext?: string[]}|null|undefined} */ (state.result);
   const missingContext = Array.isArray(refused?.missingContext) ? refused.missingContext : [];
+  const failureCause = classifyFailureCause(node, state);
   const budget = await runBoundedRounds(rounds, async (round, history) => {
     const additions = (await discover({ round, node, state, missingContext, findings: history.flatMap((item) => item.findings) })) ?? {};
     const packet = widenTaskPacket(node.taskPacket, additions);
@@ -641,7 +643,7 @@ export async function reauthorRefusedNode(options) {
   const outcome = budget.accepted ? (reauthorApproved(node, { approve, approveBelow }) ? "applied" : "approval_required") : "rounds_exhausted";
   const record = reauthorProposalRecord({
     nodeId: node.id, outcome, riskTier: reauthorRiskTier(node), budget: rounds, roundsUsed: budget.roundsUsed,
-    additions: last?.additions, packet: last?.packet, findings: last?.findings, history: budget.history,
+    additions: last?.additions, packet: last?.packet, findings: last?.findings, history: budget.history, failureCause,
   });
   appendJsonl(join(runDir, "reauthor.jsonl"), record);
   return {

package/src/engine/review.mjs

@@ -23,6 +23,7 @@ import {
 import { errorMessage, excerpt } from "../util.mjs";
 import { appendTransitionEvent, transition, writeNode } from "./state.mjs";
 import { startJudge } from "./dispatch.mjs";
+import { auxSpawnAdmission, recordAuxRefusal } from "./aux-admission.mjs";
 import { applyRejection, raiseNodeAttention, settleDone } from "./settle.mjs";
 
 /** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
@@ -86,6 +87,16 @@ export async function applyJudgeProtocolFailure(contract, node, state, runDir, r
     transition(runDir, state, "pending", { phase: "judge", gate: null, result: state.result, error: null, blockedBy: [] }, lock);
     return;
   }
+  const admission = auxSpawnAdmission(contract, node, state, running, states, "judge");
+  if (!admission.admitted) {
+    // The runtime the re-ask would land on holds its ceiling: defer the
+    // bounded re-ask the same way a controller-loss recovery defers it, bound
+    // and result durable, until the scheduler can admit it.
+    const from = state.status;
+    transition(runDir, state, "pending", { phase: "judge", gate: null, result: state.result, error: null, blockedBy: [] }, lock);
+    recordAuxRefusal(runDir, state, from, lock, "judge", admission);
+    return;
+  }
   await applyJudgeRound(await startJudge(contract, node, state, runDir, running, state.result, lock, states, campaignPath),
     contract, node, state, runDir, running, lock, states, campaignPath, state.result);
 }
@@ -179,6 +190,16 @@ export async function applyJudgeResult(contract, node, state, result, runDir, lo
       transition(runDir, state, "pending", { phase: "judge", gate: null, result: state.result, error: null, blockedBy: [] }, lock);
       return;
     }
+    const admission = auxSpawnAdmission(contract, node, state, running, states, "judge");
+    if (!admission.admitted) {
+      // The runtime the re-ask would land on holds its ceiling: defer the
+      // bounded re-ask with its bound and result durable until the scheduler
+      // can admit it, exactly as a controller-loss recovery defers it.
+      const from = state.status;
+      transition(runDir, state, "pending", { phase: "judge", gate: null, result: state.result, error: null, blockedBy: [] }, lock);
+      recordAuxRefusal(runDir, state, from, lock, "judge", admission);
+      return;
+    }
     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;

package/src/engine/run-command.mjs

@@ -9,18 +9,38 @@
  *
  * The schema for what may be run lives in `contract/verification.mjs`; this is
  * only the doing.
+ *
+ * A pass interrupted mid-list restarts every command on resume (review
+ * 2026-09-29: an interrupted verification re-runs the whole list, and the
+ * engine's own suite costs 1035-1058s per full pass — `VERIFICATION_LIMITS.maxTimeoutSec`).
+ * Each completed command therefore also writes a checkpoint beside its log,
+ * `checkpoint-<ordinal>.json`: the identity hash of everything the proof
+ * depends on — the committed tree (the HEAD tree id) and the dirty tree
+ * fingerprint, the validated command, the exact child environment, the
+ * dependency-inputs hash — plus the bounded result. Both tree hashes are
+ * needed: the fingerprint hashes only the difference from HEAD, so clean
+ * trees at different commits share one, and a stale passing result survived a
+ * commit until the HEAD tree joined the identity (review 2026-10-02, d5.1). A
+ * resumed pass serves a checkpoint only when that identity is unchanged and
+ * the tree actually carried a fingerprint; any difference forces
+ * re-execution. A
+ * mutation entry is the explicit invalidation policy: it is never checkpointed
+ * and never served, because its proof is a function of the tree it breaks and
+ * restores, so a reused record could certify a tree that no longer exists.
  */
 import { Buffer } from "node:buffer";
-import { VERIFICATION_LIMITS, compactVerification, resolveVerificationCwd, validateVerificationCommands } from "../contract/verification.mjs";
-import { mkdirSync, writeFileSync } from "node:fs";
+import { VERIFICATION_LIMITS, commandCheckpointIdentity, compactVerification, parseCommandCheckpoint, resolveVerificationCwd, validateVerificationCommands } from "../contract/verification.mjs";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { processStartToken } from "../run/lock.mjs";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { runMutation } from "./mutation.mjs";
 import { SANDBOX_BLOCKED_WRITE } from "../contract/worker-result.mjs";
-import { isAbsolute, resolve } from "node:path";
+import { isAbsolute, join, resolve } from "node:path";
 import { isContained } from "../util.mjs";
 import { spawn } from "node:child_process";
 import { killTarget, spawnInvocation } from "../host/platform.mjs";
+import { gitIdentity } from "../repo/source-identity.mjs";
+import { boundedGitSync } from "../repo/worktree.mjs";
 /** @typedef {import("../contract/verification.mjs").VerificationOptions} VerificationOptions */
 
 /**
@@ -76,14 +96,15 @@ const VERIFICATION_ENV_BASE_NAMES = Object.freeze([
 
 /**
  * @param {VerificationCommand} command
- * @returns {Record<string, string|undefined>}
+ * @returns {Record<string, string>}
  */
 function verificationEnv(command) {
   const names = new Set([...(command.env ?? []), ...VERIFICATION_ENV_BASE_NAMES]);
-  /** @type {Record<string, string|undefined>} */
+  /** @type {Record<string, string>} */
   const env = {};
   for (const name of names) {
-    if (process.env[name] !== undefined) env[name] = process.env[name];
+    const value = process.env[name];
+    if (value !== undefined) env[name] = value;
   }
   return env;
 }
@@ -126,6 +147,123 @@ export function classifySandboxBlockedWrite({ text, workspace, mode }) {
   }
   return null;
 }
+/**
+ * Everything one pass needs to decide checkpoint reuse, cached per pass: the
+ * tree identity per command cwd (one `gitIdentity` and one `rev-parse` each,
+ * paid only when a checkpoint directory is in play) and the dependency-inputs
+ * hash (the packet's writeFiles do not change during a pass; a mutation entry
+ * restores them in `finally`).
+ *
+ * @typedef {{trees: Map<string, WorkspaceTreeIdentity>, dependencyHash: string|undefined}} CheckpointCaches
+ */
+
+/**
+ * The two tree hashes a checkpoint identity sits on: the dirty fingerprint
+ * (what the working tree adds to HEAD) and the HEAD tree id (what HEAD
+ * commits). Either changing forces re-execution.
+ *
+ * @typedef {{dirtyTreeFingerprint: string|null, headTree: string|null}} WorkspaceTreeIdentity
+ */
+
+/**
+ * The committed tree the workspace sits on: the HEAD tree id, which the dirty
+ * fingerprint cannot see — it hashes only the difference from HEAD, so two
+ * clean trees at different commits used to share one checkpoint identity and
+ * a stale pass survived a commit (review 2026-10-02, d5.1). Null when there
+ * is no commit to name (no repository, unborn HEAD): the identity still
+ * compares, and null to null is the same unborn state across passes.
+ *
+ * @param {string} workspace
+ * @returns {string|null}
+ */
+function headTreeId(workspace) {
+  try {
+    const result = boundedGitSync(["-C", workspace, "rev-parse", "HEAD^{tree}"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    if (result.error || result.status !== 0) return null;
+    return String(result.stdout).trim() || null;
+  } catch {
+    // Git absent or unreadable: no committed tree to name, matching the
+    // dirty fingerprint's own null for a workspace without a repository.
+    return null;
+  }
+}
+
+/**
+ * A hash over the dependency inputs a proof is about: the packet's writeFiles,
+ * the mutation sample's input. ReadFiles and every other tracked or untracked
+ * source ride inside the tree fingerprint instead; installed dependencies that
+ * git ignores (a mid-attempt `npm ci`) are covered only when the packet
+ * declares them here — a known bound, not a solved one.
+ *
+ * @param {string} baseCwd
+ * @param {string[]} writeFiles
+ * @returns {string}
+ */
+function dependencyInputsHash(baseCwd, writeFiles) {
+  const hash = createHash("sha256");
+  for (const path of [...new Set(writeFiles)].sort()) {
+    hash.update(`${path}\0`);
+    try {
+      hash.update(readFileSync(resolve(baseCwd, path)));
+    } catch {
+      // ENOENT or a non-file: the mutation sampler skips the same paths, so a
+      // missing dependency input hashes as missing rather than failing the pass.
+      hash.update("missing");
+    }
+    hash.update("\0");
+  }
+  return hash.digest("hex");
+}
+
+/**
+ * The pre-run identity of one command's proof, plus whether the tree gave a
+ * fingerprint to compare at all: a workspace that is not a git repository has
+ * no tree identity, so its checkpoints never serve.
+ *
+ * @param {VerificationCommand} command
+ * @param {string} baseCwd
+ * @param {RunVerificationOptions} options
+ * @param {CheckpointCaches} caches
+ * @returns {{identity: string, reusable: boolean}}
+ */
+function checkpointIdentity(command, baseCwd, options, caches) {
+  const workspace = resolveVerificationCwd(baseCwd, command.cwd ?? ".");
+  let tree = caches.trees.get(workspace);
+  if (tree === undefined) {
+    tree = { dirtyTreeFingerprint: gitIdentity(workspace).dirtyTreeFingerprint, headTree: headTreeId(workspace) };
+    caches.trees.set(workspace, tree);
+  }
+  if (caches.dependencyHash === undefined) {
+    caches.dependencyHash = dependencyInputsHash(baseCwd, options.writeFiles ?? []);
+  }
+  return {
+    identity: commandCheckpointIdentity({ treeFingerprint: tree.dirtyTreeFingerprint, headTree: tree.headTree, command, env: verificationEnv(command), dependencyHash: caches.dependencyHash }),
+    reusable: tree.dirtyTreeFingerprint !== null,
+  };
+}
+
+/**
+ * The recorded result for this ordinal, served only when the checkpoint
+ * validates, the tree carried a fingerprint, and the identity is unchanged.
+ * Every read or parse failure lands on re-execution: a corrupted checkpoint is
+ * never a verdict on the command and never fatal to the pass.
+ *
+ * @param {string} logDir
+ * @param {number} ordinal
+ * @param {{identity: string, reusable: boolean}} identity
+ * @returns {VerificationCommandResult|null}
+ */
+function servedCheckpoint(logDir, ordinal, identity) {
+  try {
+    const parsed = parseCommandCheckpoint(JSON.parse(readFileSync(join(logDir, `checkpoint-${ordinal}.json`), "utf8")));
+    if (!identity.reusable || parsed.identity !== identity.identity) return null;
+    return parsed.result;
+  } catch {
+    // ENOENT is the no-checkpoint case; every other failure (corrupt JSON, a
+    // record past its bounds) fails closed to a re-run for the same reason.
+    return null;
+  }
+}
 /**
  * Run every declared command `repeat` times inside the workspace.
  *
@@ -138,14 +276,31 @@ export async function runVerification(commands, baseCwd, options = {}) {
   const validated = validateVerificationCommands(commands);
   /** @type {VerificationCommandResult[]} */
   const results = [];
+  /** @type {CheckpointCaches|null} */
+  const checkpoints = options.logDir ? { trees: new Map(), dependencyHash: undefined } : null;
   for (const [commandIndex, command] of validated.entries()) {
-    const result = command.mutation
-      ? await runMutationCommand(command, baseCwd, commandIndex, options)
-      : await runRepeatedCommand(command, baseCwd, commandIndex, options);
+    // Identity before the run: a checkpoint records the tree, environment and
+    // dependency inputs the proof was made against, which are the pre-run ones.
+    const identity = checkpoints && !command.mutation
+      ? checkpointIdentity(command, baseCwd, options, checkpoints)
+      : null;
+    const reused = identity
+      ? servedCheckpoint(/** @type {string} */ (options.logDir), results.length + 1, identity)
+      : null;
+    const result = reused ?? await (command.mutation
+      ? runMutationCommand(command, baseCwd, commandIndex, options)
+      : runRepeatedCommand(command, baseCwd, commandIndex, options));
     results.push(result);
     if (options.logDir) {
       mkdirSync(options.logDir, { recursive: true });
-      writeFileSync(`${options.logDir}/verification-${results.length}.json`, `${JSON.stringify(compactVerification({ passed: result.passed, commands: [result] }))}\n`, { mode: 0o600 });
+      const compacted = compactVerification({ passed: result.passed, commands: [result] });
+      writeFileSync(`${options.logDir}/verification-${results.length}.json`, `${JSON.stringify(compacted)}\n`, { mode: 0o600 });
+      // A mutation entry records no checkpoint (the invalidation policy in the
+      // header); an argv past the persisted bounds compacts to no command, and
+      // its unreadable record simply fails closed to a re-run on resume.
+      if (identity) {
+        writeFileSync(`${options.logDir}/checkpoint-${results.length}.json`, `${JSON.stringify({ identity: identity.identity, result: compacted })}\n`, { mode: 0o600 });
+      }
     }
   }
   return { passed: results.every((result) => result.passed), commands: results };