@kylecheng3146/agent-ops 0.11.5 → 0.11.6

package/dist/packages/cli/src/bin.js

@@ -4,6 +4,7 @@ import { renderCriteriaReview } from "../../../runtime/src/review/criteria.js";
 import { advancePhaseObserver, productionRunContext } from "./run-deps.js";
 import { AgentOpsError } from "../../../runtime/src/fs/paths.js";
 import { recordRunVerification } from "../../../runtime/src/run/verification.js";
+import { runReviewCheckpoints } from "../../../runtime/src/run/proof-recovery.js";
 import { runOwnedLocalProof } from "./owned-run-step.js";
 import { runRunCommand } from "./commands/run.js";
 import { runFollowupCommand } from "./commands/followup.js";
@@ -557,6 +558,10 @@ else {
                 // a `batch` are reviewed identically.
                 const buildReviewOptions = async (reviewArgs, signal, preflightTarget = probeTarget, progressPrefix = "") => {
                     const reviewSessionId = process.env.AGENT_OPS_SESSION_ID;
+                    // Only the coordinator's registered run proof group, during a final proof, resumes saved rounds.
+                    const run = await runPolicyContext(root).catch(() => null);
+                    const checkpoints = run?.proof === true && run.worker?.workerId === run.state.coordinatorId &&
+                        run.state.finalProof?.pending === true ? runReviewCheckpoints(run.repository, run.state) : undefined;
                     const reviewGit = gitRunner(root);
                     const reviewConfig = (await loadEffectiveConfig(root, reviewArgs.scope === "user" ? "user" : "project")).config;
                     const reviewRole = resolveReviewRole("independent-review", reviewConfig.reviewRoles ?? []);
@@ -625,6 +630,7 @@ else {
                                 ? {}
                                 : { timeoutMs: reviewRole.timeoutMs }),
                             preflightTarget,
+                            ...(checkpoints === undefined ? {} : { checkpoints }),
                             verifySourceFingerprint: async (expected, scope) => {
                                 const currentScope = await resolveReviewScope({
                                     root,

package/dist/packages/cli/src/commands/advance.js

@@ -8,6 +8,9 @@ import { readWorktreeRecord, resolveCheckouts, sessionWorktreeName, worktreePath
 import { resolveReviewScope } from "../../../../runtime/src/review/scope.js";
 import { renderReviewDetails, renderReviewHighlights } from "../../../../runtime/src/review/render.js";
 import { calculateSourceFingerprint } from "../../../../runtime/src/verify/source-fingerprint.js";
+import { FileEvidenceStore } from "../../../../runtime/src/verify/evidence.js";
+import { parseArgs } from "../args.js";
+import { hasFreshVerification } from "./review.js";
 import { okEnvelope } from "../output.js";
 import { readFinishedReview } from "./review-show.js";
 import { criteriaProgress } from "../../../../runtime/src/run/phase.js";
@@ -50,6 +53,17 @@ function runner(deps, cwd) {
             return { exitCode: result.exitCode, stdout: Buffer.from(result.stdout, "utf8") };
         } };
 }
+/** Current passing evidence for this candidate, by the rule review's own preflight applies; anything unreadable re-verifies. */
+async function freshlyVerified(deps, cwd, taskId, base) {
+    try {
+        return await hasFreshVerification({ args: parseArgs(["review", "--task", taskId, "--base", base, "--yes"]), authorized: true,
+            tasks: deps.tasks(cwd), root: cwd, gitRunner: runner(deps, cwd), config: await deps.loadConfig(cwd),
+            evidenceStore: new FileEvidenceStore(cwd, cwd) }, taskId, base);
+    }
+    catch {
+        return false;
+    }
+}
 async function git(deps, cwd, args) {
     const result = await deps.git(cwd, args);
     if (result.exitCode !== 0)
@@ -138,6 +152,10 @@ export async function runAdvanceCommand(options) {
         const onPhase = options.onPhase ?? (async () => { });
         await onPhase("verifying");
         for (const task of ordered) {
+            if (await freshlyVerified(deps, record.path, task.task.id, target)) {
+                await onPhase("verifying", { taskId: task.task.id, update: { verify: "PASS" } });
+                continue;
+            }
             const verified = await step(record.path, ["verify", "--task", task.task.id, "--base", target]);
             await onPhase("verifying", { taskId: task.task.id, update: { verify: verified.status === "ok" ? "PASS" : "FAIL",
                     ...criteriaProgress(task.task.criteria, verified.data?.report ?? {}) } });

package/dist/packages/cli/src/commands/run.js

@@ -29,6 +29,8 @@ function textFor(action, state, message) {
         `Cause: ${recovery.cause === null ? "none recorded" : recovery.cause.code + ": " + recovery.cause.detail}`,
         `Sealed proof: ${recovery.sealedProof}; cleanup: ${recovery.cleanup}; resumable: ${recovery.resumable ? "yes, after reconciliation" : "no"}`,
         `Remediation: ${recovery.remediation}`,
+        state.finalProof == null ? "" : `Final proof recovery: ${state.finalProof.recoveries}/1 used; first failure ${state.finalProof.failures[0]?.code ?? "none"}; ` +
+            `last failure ${state.finalProof.failures.at(-1)?.code ?? "none"}; automatic recovery ${state.finalProof.stopped ? "stopped" : state.finalProof.pending ? "in progress" : "available"}`,
         `Host: ${state.host}`,
         `Workers: ${active}/${state.jobs}`,
         state.budget.limitMs === null ? `Budget: unlimited; ${state.budget.accumulatedMs}ms active time recorded` : `Budget: ${Math.max(0, state.budget.limitMs - state.budget.accumulatedMs)}ms remaining (legacy; manual resume upgrades)`,

package/dist/packages/cli/src/context.js

@@ -263,7 +263,8 @@ export async function runPolicyContext(root, renew = false) {
     const policy = await readRunPolicy(state, await runRuntimeHash());
     if (policy === null)
         return null;
-    return { repository, state, policy, worker };
+    // `proof`: this process runs inside the supervisor's registered run-level proof group.
+    return { repository, state, policy, worker, proof: globalProof };
 }
 /** Only active execution paths call this; status, installation and recovery reads never renew. */
 export async function ensureRunPolicy(repository, state) {

package/dist/packages/cli/src/run-entry.js

@@ -8,6 +8,7 @@ import { resolveReviewScope } from "../../../runtime/src/review/scope.js";
 import { writeNoChangeDelivery, integrateSessionChildren } from "../../../runtime/src/parallel/integrate.js";
 import { recordNativeRunUsage, recordReviewRunUsage, recordSavedReviewRunUsage } from "../../../runtime/src/run/usage.js";
 import { recordNativeRunAuthorization } from "../../../runtime/src/run/authorization.js";
+import { discardReviewCheckpoints, finalProofAttemptKey, InterruptedStepError, processGroupAlive, runFinalProof } from "../../../runtime/src/run/proof-recovery.js";
 import { observeRunFailure } from "../../../runtime/src/run/verification.js";
 import { criteriaProgress, recordRunPhase } from "../../../runtime/src/run/phase.js";
 import { compareFailureObservations } from "../../../runtime/src/run/convergence.js";
@@ -435,6 +436,27 @@ export async function superviseNativeRun(root, runId) {
         async function advance(saved) {
             return await step(root, ["task", "advance", "--task", saved.rootTaskId, "--session", saved.ownerSessionId, "--yes"], saved);
         }
+        async function attemptKey(saved) {
+            const coordinator = saved.workers.find(w => w.workerId === saved.coordinatorId);
+            if (coordinator?.worktree == null)
+                throw new AgentOpsError("RUN_WORKTREE_MISSING", "Final proof requires the coordinator checkout.");
+            return finalProofAttemptKey({ candidate: (await deps.git(coordinator.worktree, ["rev-parse", "HEAD"])).stdout.trim(),
+                target: (await deps.git(root, ["rev-parse", saved.targetBranch + "^{commit}"])).stdout.trim(),
+                contractHash: saved.currentContractHash, configHash: saved.policyBinding?.configHash ?? null,
+                runtimeHash: saved.policyBinding?.runtimeHash ?? null });
+        }
+        async function finalProof(restartedKey) {
+            return await runFinalProof(repository, runId, {
+                advance: async () => await advance((await repository.read(runId))),
+                attemptKey: async () => await attemptKey((await repository.read(runId))),
+                untouched: async () => {
+                    const latest = (await repository.read(runId));
+                    const coordinator = latest.workers.find(w => w.workerId === latest.coordinatorId);
+                    return coordinator?.worktree != null && latest.integration === null &&
+                        (await collectChangeSurface(gitRunner(coordinator.worktree))).paths.length === 0;
+                }
+            }, restartedKey);
+        }
         async function recoverIntegration(saved) {
             const coordinator = saved.workers.find(worker => worker.workerId === saved.coordinatorId);
             if (coordinator?.worktree == null)
@@ -662,7 +684,9 @@ export async function superviseNativeRun(root, runId) {
                 await recordReviewRunUsage(repository, runId, review.report.value);
             const finalContract = treeContractHash(receipt.tasks.map(record => record.task));
             await repository.mutate(runId, current => ({ ...current, currentContractHash: finalContract,
-                contractRevision: current.contractRevision + (current.currentContractHash === finalContract ? 0 : 1) }));
+                contractRevision: current.contractRevision + (current.currentContractHash === finalContract ? 0 : 1),
+                ...(current.finalProof == null ? {} : { finalProof: { ...current.finalProof, pending: false, checkpoints: undefined } }) }));
+            await discardReviewCheckpoints(current).catch(() => { });
             await supervisor.finalize(runId, { targetCommit: receipt.candidateHead, candidateCommit: receipt.candidateHead,
                 verificationPass: true, reviewPass: true, taskStateComplete: true, receiptWritten: true, receiptDigest: sha256(source) });
             try {
@@ -726,6 +750,32 @@ export async function superviseNativeRun(root, runId) {
             else if (state.policyBinding !== undefined)
                 await synchronizePolicy();
             state = (await repository.read(runId));
+            // A final proof the previous supervisor left pending resumes before any writer starts.
+            let proofNote;
+            if (state.finalProof?.pending === true && state.rootTaskId !== null) {
+                try {
+                    const result = await finalProof(state.finalProof.attemptKey);
+                    if (result.status !== "ok")
+                        throw runStepError(result, "Final proof failed after a supervisor restart");
+                    if (!plain(result.data) || typeof result.data.receipt !== "string")
+                        throw new AgentOpsError("RUN_RECEIPT_REQUIRED", "Finalization requires the receipt returned by the existing finish gate.");
+                    await acceptReceipt(state, result.data.receipt);
+                    await writePrivateFile(join(directory, runId, "final-response.json"), JSON.stringify({ code: "RUN_COMPLETE", receipt: result.data.receipt }), commonDir);
+                    return;
+                }
+                catch (cause) {
+                    // A sealed transaction keeps its manual reconciliation path.
+                    if ((await repository.read(runId)).integration !== null)
+                        throw cause;
+                    const coordinator = state.workers.find(w => w.workerId === state.coordinatorId);
+                    await writePrivateFile(join(coordinator.worktree, ".agent-ops", "tasks", "run-last-failure.json"), JSON.stringify({
+                        code: cause instanceof AgentOpsError ? cause.code : "RUN_PROOF_FAILED",
+                        error: cause instanceof AgentOpsError ? cause.message : "Final proof failed; inspect local diagnostics."
+                    }), coordinator.worktree);
+                    proofNote = "Final proof did not complete after a supervisor restart. Read run-last-failure.json and saved review/verification reports, fix substantive findings, then request a new evidence gate.";
+                }
+                state = (await repository.read(runId));
+            }
             for (const worker of state.workers.filter(w => active(w) || w.status === "stopped")) {
                 if (recoverySkips(state, worker))
                     continue;
@@ -733,7 +783,8 @@ export async function superviseNativeRun(root, runId) {
                     !(await deps.tasks(worker.worktree).list()).some(r => r.task.id === worker.taskId)))
                     continue;
                 try {
-                    await start(worker, worker.workerId === state.coordinatorId && yielded(worker) ? coordinatorWakeNote(state, worker) : undefined, manualResumeAt);
+                    await start(worker, worker.workerId === state.coordinatorId
+                        ? proofNote ?? (yielded(worker) ? coordinatorWakeNote(state, worker) : undefined) : undefined, manualResumeAt);
                     if (state.jobs === 1)
                         break;
                 }
@@ -964,7 +1015,7 @@ export async function superviseNativeRun(root, runId) {
                             }
                             await stopAll("stop", false);
                             await recordRunPhase(repository, runId, worker.workerId, "verifying");
-                            const result = await advance(current);
+                            const result = await finalProof();
                             if (result.status !== "ok")
                                 throw runStepError(result, "Final proof failed; inspect saved verifier and fresh review reports before repair");
                             const data = result.data;
@@ -1066,7 +1117,10 @@ export async function runControlledStep(repository, cli, cwd, args, saved) {
                     catch { }
             }, 3000);
         };
-        const timeout = Number.isFinite(remaining) ? setTimeout(terminate, remaining) : undefined;
+        // Why the supervisor itself ended the step; any such end is never replayed automatically.
+        let ended;
+        const end = (why) => { ended ??= why; terminate(); };
+        const timeout = Number.isFinite(remaining) ? setTimeout(() => end("deadline"), remaining) : undefined;
         const registration = (async () => {
             const identity = child.pid === undefined ? null : await nativeProcessIdentity(child.pid);
             if (identity === null || closed) {
@@ -1095,8 +1149,8 @@ export async function runControlledStep(repository, cli, cwd, args, saved) {
             checking = true;
             void repository.read(runId).then(current => {
                 if (current === null || current.disableRestart || current.status !== "active")
-                    terminate();
-            }).catch(terminate).finally(() => { checking = false; });
+                    end("stop");
+            }).catch(() => end("state")).finally(() => { checking = false; });
         }, 250);
         child.stdout.on("data", (chunk) => {
             const room = 4 * 1024 * 1024 - output.length;
@@ -1104,7 +1158,7 @@ export async function runControlledStep(repository, cli, cwd, args, saved) {
                 output = Buffer.concat([output, chunk.subarray(0, room)]);
             if (chunk.length > room) {
                 outputOverflow = true;
-                terminate();
+                end("overflow");
             }
         });
         child.stderr.on("data", (chunk) => {
@@ -1112,7 +1166,7 @@ export async function runControlledStep(repository, cli, cwd, args, saved) {
             if (room > 0)
                 diagnostic = Buffer.concat([diagnostic, chunk.subarray(0, room)]);
         });
-        child.once("error", cause => { spawnError = cause; terminate(); });
+        child.once("error", cause => { spawnError = cause; end("spawn"); });
         child.once("close", async (exitCode, signal) => {
             closed = true;
             clearTimeout(timeout);
@@ -1160,12 +1214,14 @@ export async function runControlledStep(repository, cli, cwd, args, saved) {
             catch (cause) {
                 const excerpt = (value) => redactSecrets(value)
                     .replace(/-----BEGIN (?:[A-Z0-9]+ )?PRIVATE KEY-----[\s\S]*$/u, "[REDACTED_PRIVATE_KEY]").slice(0, 3500);
-                const detail = JSON.stringify({ exitCode, signal, stage, outputOverflow,
+                const replayable = ["process", "result"].includes(stage) && ended === undefined && spawnError === undefined &&
+                    child.pid !== undefined && !processGroupAlive(child.pid);
+                const detail = JSON.stringify({ exitCode, signal, stage, outputOverflow, ended: ended ?? null, replayable,
                     cause: excerpt(cause instanceof Error ? cause.message : String(cause)),
                     stderr: excerpt(diagnostic.toString("utf8")), stdout: excerpt(output.toString("utf8").slice(0, 4096)) }).slice(0, 9500);
                 await repository.appendEvent(runId, { type: "diagnostic", code: "RUN_CONTROLLED_STEP_FAILED",
                     workerId: env.AGENT_OPS_WORKER_ID ?? null, taskId: saved.workers.find(w => w.worktree === cwd)?.taskId ?? null, detail }).catch(() => undefined);
-                reject(new AgentOpsError("RUN_FINAL_PROOF_INTERRUPTED", "Final gate did not return a complete result; inspect target and receipt before retrying. " + detail));
+                reject(new InterruptedStepError("Final gate did not return a complete result; inspect target and receipt before retrying. " + detail, replayable));
             }
         });
     });

package/dist/runtime/src/review/execute.js

@@ -10,7 +10,7 @@ import { reviewReportResults, reviewReportStatus, validateReviewReport } from ".
 import { detectHostTarget, planReviewTargets } from "./roles.js";
 import { detectHostRestriction, isLoginFailure, isNetworkFailure } from "./host-sandbox.js";
 import { buildAdversarialPrompt, buildReviewPrompt } from "./runner.js";
-import { MAX_ADVERSARIAL_PROMPT_BYTES } from "./runner.js";
+import { MAX_ADVERSARIAL_PROMPT_BYTES, redactReviewReport } from "./runner.js";
 import { extractUsage, sumUsage } from "./usage.js";
 /**
  * Full repository reviews need far more headroom than the lightweight auth
@@ -754,7 +754,7 @@ async function attemptTarget(request, options) {
  */
 async function attemptTargetWithRetry(request, options) {
     const first = await attemptTarget(request, options);
-    if (first.kind !== "skip" || first.transient !== true || budgetSpent(options)) {
+    if (first.kind !== "skip" || first.transient !== true || budgetSpent(options) || options.checkpoints !== undefined) {
         return first;
     }
     options.onProgress?.(`${request.target}: ${first.diagnostic} → retrying once`);
@@ -817,9 +817,59 @@ export function createReviewExecutor(options) {
                 attempts: []
             };
         }
+        const expectedCriterionIds = request.invocation.packet.criteria.map((criterion) => criterion.id);
+        const primaryTarget = plannedTargets[0];
+        const adversarialTarget = plannedTargets[1];
+        const primaryPrompt = buildReviewPrompt({ ...request.invocation, harness: primaryTarget });
+        const binding = sha256(JSON.stringify({ primaryPrompt, targets: [primaryTarget, adversarialTarget],
+            model: options.model ?? null, effort: options.effort ?? null }));
+        const journal = options.checkpoints;
+        let saved = null;
+        if (journal !== undefined) {
+            const valid = (round, target) => round !== undefined && round.target === target && typeof round.sessionId === "string" && round.sessionId.length > 0 &&
+                validateReviewReport(round.report, expectedCriterionIds, request.invocation.scope?.changedFiles).ok;
+            try {
+                saved = await journal.load(binding);
+            }
+            catch {
+                report("checkpoint: the saved review checkpoint is unreadable or altered; stopping review");
+                return { status: "NOT_RUN", reason: "checkpoint-invalid", attempts: [] };
+            }
+            if (saved !== null && (saved.binding !== binding || !valid(saved.primary, primaryTarget) ||
+                reviewReportStatus(saved.primary.report) !== "PASS" ||
+                (saved.adversarial !== undefined && !valid(saved.adversarial, adversarialTarget)))) {
+                report("checkpoint: the saved review checkpoint does not match this review; stopping review");
+                return { status: "NOT_RUN", reason: "checkpoint-invalid", attempts: [] };
+            }
+            if (saved?.adversarial !== undefined && reviewReportStatus(saved.adversarial.report) === "FAIL")
+                saved = null;
+            if (saved?.adversarial !== undefined) {
+                report("checkpoint: both rounds already answered for this exact review; no reviewer is called");
+                const { primary, adversarial } = saved;
+                return {
+                    status: "PASS",
+                    results: reviewReportResults(primary.report),
+                    report: primary.report,
+                    harness: primaryTarget,
+                    attempts: [
+                        { target: primaryTarget, status: "PASS", sessionId: primary.sessionId, metrics: primary.metrics },
+                        { target: adversarialTarget, status: "PASS", sessionId: adversarial.sessionId, metrics: adversarial.metrics }
+                    ],
+                    preflight: [],
+                    independence: primaryTarget === adversarialTarget ? "same-target" : "different-target",
+                    sessionIsolation: "fresh",
+                    adversarial: { target: adversarialTarget, refuted: false, report: adversarial.report }
+                };
+            }
+        }
+        const signalTransient = async (outcome) => {
+            if (outcome.kind === "skip" && outcome.transient === true)
+                await journal?.transient().catch(() => { });
+        };
         const preflight = [];
         if (options.preflightTarget !== undefined) {
-            for (const target of new Set(plannedTargets)) {
+            // A resumed primary needs no probe: its round is not run again.
+            for (const target of new Set(saved === null ? plannedTargets : [adversarialTarget])) {
                 if (outOfTime()) {
                     const diagnostic = "the review deadline was reached during target " +
                         "preflight";
@@ -859,7 +909,6 @@ export function createReviewExecutor(options) {
                 };
             }
         }
-        const expectedCriterionIds = request.invocation.packet.criteria.map((criterion) => criterion.id);
         const repositoryRoot = await realpath(options.cwd);
         const shared = {
             repositoryRoot,
@@ -874,20 +923,26 @@ export function createReviewExecutor(options) {
                 : {})
         };
         const attempts = [];
-        const primaryTarget = plannedTargets[0];
-        const adversarialTarget = plannedTargets[1];
         if (outOfTime()) {
             report("chain: review deadline reached before the first round");
             return { status: "NOT_RUN", reason: "timeout", attempts: [] };
         }
-        announceRound(options, 1, primaryTarget, plannedTargets);
-        const primaryOutcome = await attemptTargetWithRetry({
-            ...shared,
-            target: primaryTarget,
-            label: `${primaryTarget}-primary`,
-            prompt: buildReviewPrompt({ ...request.invocation, harness: primaryTarget })
-        }, staged());
+        let primaryOutcome;
+        if (saved !== null) {
+            report(`${primaryTarget}: necessary review already passed for this exact review; resuming at the adversarial round`);
+            primaryOutcome = { kind: "verdict", report: saved.primary.report, sessionId: saved.primary.sessionId, metrics: saved.primary.metrics };
+        }
+        else {
+            announceRound(options, 1, primaryTarget, plannedTargets);
+            primaryOutcome = await attemptTargetWithRetry({
+                ...shared,
+                target: primaryTarget,
+                label: `${primaryTarget}-primary`,
+                prompt: primaryPrompt
+            }, staged());
+        }
         if (primaryOutcome.kind === "skip") {
+            await signalTransient(primaryOutcome);
             attempts.push({
                 target: primaryTarget,
                 status: "NOT_RUN",
@@ -949,6 +1004,17 @@ export function createReviewExecutor(options) {
                 };
             }
         }
+        if (journal !== undefined && saved === null) {
+            try {
+                await journal.save({ binding, primary: { target: primaryTarget, sessionId: primaryOutcome.sessionId,
+                        report: redactReviewReport(primaryReport), metrics: primaryOutcome.metrics } });
+            }
+            catch {
+                report("checkpoint: the necessary review PASS could not be saved; stopping before the adversarial round");
+                return { status: "NOT_RUN", reason: "evidence-write-failed", report: primaryReport, preflight,
+                    independence, sessionIsolation: "fresh", attempts };
+            }
+        }
         const adversarialPrompt = buildAdversarialPrompt({ ...request.invocation, harness: adversarialTarget }, primaryReport);
         if (Buffer.byteLength(adversarialPrompt, "utf8") > MAX_ADVERSARIAL_PROMPT_BYTES) {
             const diagnostic = `the redacted primary report exceeds ${MAX_ADVERSARIAL_PROMPT_BYTES} bytes`;
@@ -998,6 +1064,7 @@ export function createReviewExecutor(options) {
             prompt: adversarialPrompt
         }, staged());
         if (adversarialOutcome.kind === "skip") {
+            await signalTransient(adversarialOutcome);
             attempts.push({
                 target: adversarialTarget,
                 status: "NOT_RUN",
@@ -1039,6 +1106,18 @@ export function createReviewExecutor(options) {
                 attempts
             };
         }
+        if (journal !== undefined) {
+            try {
+                await journal.save({ binding, primary: { target: primaryTarget, sessionId: primaryOutcome.sessionId,
+                        report: redactReviewReport(primaryReport), metrics: primaryOutcome.metrics }, adversarial: { target: adversarialTarget,
+                        sessionId: adversarialOutcome.sessionId, report: redactReviewReport(adversarialReport), metrics: adversarialOutcome.metrics } });
+            }
+            catch {
+                report("checkpoint: the answered pair could not be saved; its verdict is not accepted");
+                return { status: "NOT_RUN", reason: "evidence-write-failed", report: primaryReport, preflight,
+                    independence, sessionIsolation: "fresh", attempts };
+            }
+        }
         report(`${adversarialTarget}: adversarial re-check ${refuted ? "refuted the PASS" : "upheld the PASS"}`);
         return {
             status: refuted ? "FAIL" : "PASS",

package/dist/runtime/src/review/render.js

@@ -121,6 +121,10 @@ export function renderReviewResult(result) {
             lines.push("Three configured targets require AGENT_OPS_HOST=agy|claude|codex; " +
                 "the host identity was not guessed.");
         }
+        if (result.reason === "checkpoint-invalid") {
+            lines.push("The saved final-proof review checkpoint is unreadable or does not match " +
+                "this review, so no round was resumed or repeated automatically.");
+        }
         if (result.reason === "evidence-write-failed") {
             lines.push("Reviewers may have completed, but the required evidence could not be " +
                 "written; the completion gate remains blocked.");

package/dist/runtime/src/run/proof-recovery.js

@@ -0,0 +1,167 @@
+import { execFileSync } from "node:child_process";
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import { sha256 } from "../fs/hash.js";
+import { AgentOpsError } from "../fs/paths.js";
+import { readPrivateFile, writePrivateFile } from "../security/permissions.js";
+const MAX_CHECKPOINT_BYTES = 4 * 1024 * 1024;
+const BINDING = /^[a-f0-9]{64}$/u;
+/** Matches the run state validator; the oldest record is dropped first. */
+const MAX_CHECKPOINTS = 64;
+/** One immutable final attempt: a new candidate, target, contract or policy starts a new allowance. */
+export function finalProofAttemptKey(parts) {
+    return sha256(JSON.stringify([parts.candidate, parts.target, parts.contractHash, parts.configHash, parts.runtimeHash]));
+}
+function checkpointDirectory(state) {
+    return join(state.commonDir, "agent-ops", "runs", state.runId, "final-review");
+}
+/**
+ * Saved rounds live beside the run state, and each file is trusted only
+ * through the digest the proof recorded in the locked run state, like run
+ * answers and plans: a file nobody recorded is ignored, so a writer that can
+ * reach the directory cannot plant a PASS. `transient` marks the same record.
+ */
+export function runReviewCheckpoints(repository, state) {
+    const path = (binding) => {
+        if (!BINDING.test(binding))
+            throw new AgentOpsError("RUN_REVIEW_CHECKPOINT_INVALID", "Checkpoint binding must be a sha256 digest.");
+        return join(checkpointDirectory(state), binding + ".json");
+    };
+    return {
+        async load(binding) {
+            const file = path(binding);
+            const recorded = (await repository.read(state.runId))?.finalProof?.checkpoints?.[binding];
+            if (recorded === undefined)
+                return null;
+            const source = await readPrivateFile(file, state.commonDir);
+            const saved = source === null || Buffer.byteLength(source) > MAX_CHECKPOINT_BYTES || sha256(source) !== recorded ? null
+                : JSON.parse(source);
+            if (saved === null || typeof saved !== "object" || saved.schemaVersion !== 1 ||
+                typeof saved.checkpoint !== "object" || saved.checkpoint === null)
+                throw new AgentOpsError("RUN_REVIEW_CHECKPOINT_INVALID", "Saved review checkpoint is missing, altered or does not match its run state record.");
+            return saved.checkpoint;
+        },
+        async save(checkpoint) {
+            const file = path(checkpoint.binding);
+            const content = JSON.stringify({ schemaVersion: 1, checkpoint });
+            if (Buffer.byteLength(content) > MAX_CHECKPOINT_BYTES)
+                throw new AgentOpsError("RUN_REVIEW_CHECKPOINT_TOO_LARGE", "Review checkpoint exceeds 4 MiB.");
+            await writePrivateFile(file, content, state.commonDir);
+            await repository.mutate(state.runId, current => {
+                if (current.finalProof == null)
+                    throw new AgentOpsError("RUN_REVIEW_CHECKPOINT_UNBOUND", "A review checkpoint needs the run's final-proof record.");
+                const kept = Object.entries(current.finalProof.checkpoints ?? {}).filter(([binding]) => binding !== checkpoint.binding)
+                    .slice(-(MAX_CHECKPOINTS - 1));
+                return { ...current, finalProof: { ...current.finalProof,
+                        checkpoints: Object.fromEntries([...kept, [checkpoint.binding, sha256(content)]]) } };
+            });
+        },
+        async transient() {
+            await repository.mutate(state.runId, current => current.finalProof == null ? current
+                : { ...current, finalProof: { ...current.finalProof, reviewTransient: true } });
+        }
+    };
+}
+/** A delivered run keeps no resumable review rounds. */
+export async function discardReviewCheckpoints(state) {
+    await rm(checkpointDirectory(state), { recursive: true, force: true });
+}
+/** Starts a proof step for `attemptKey`. The same key keeps its spent allowance; restarts never refund it. */
+export async function beginFinalProof(repository, runId, attemptKey) {
+    const state = await repository.mutate(runId, current => ({ ...current, finalProof: current.finalProof?.attemptKey === attemptKey
+            ? { ...current.finalProof, pending: true, reviewTransient: false }
+            : { attemptKey, recoveries: 0, pending: true, reviewTransient: false, failures: [], stopped: false } }));
+    return state.finalProof;
+}
+/**
+ * Records a failed or interrupted proof step and decides under the run lock
+ * whether the one automatic recovery is spent on it. Only an eligible failure
+ * of the same attempt in an active run consumes it; anything else stops
+ * automatic recovery for this attempt. The first failure is never overwritten.
+ */
+export async function settleFinalProofFailure(repository, runId, attemptKey, code, eligible) {
+    let decision = "stop";
+    await repository.mutate(runId, current => {
+        const record = current.finalProof;
+        if (record == null || record.attemptKey !== attemptKey)
+            return current;
+        const replay = eligible && record.recoveries === 0 && !record.stopped && current.status === "active" && !current.disableRestart;
+        decision = replay ? "replay" : "stop";
+        return { ...current, finalProof: { ...record, recoveries: replay ? 1 : record.recoveries, pending: replay, reviewTransient: false,
+                stopped: !replay, failures: [...record.failures.slice(0, 1), { code: code.slice(0, 128), at: new Date().toISOString() }] } };
+    });
+    return decision;
+}
+/**
+ * A controlled step that ended without a complete result. Replayable only when
+ * no stop, deadline, limit or spawn failure ended it and nothing of its
+ * process group is still running.
+ */
+export class InterruptedStepError extends AgentOpsError {
+    replayable;
+    constructor(message, replayable) {
+        super("RUN_FINAL_PROOF_INTERRUPTED", message);
+        this.replayable = replayable;
+    }
+}
+/**
+ * Coordinator final proof with at most one automatic recovery per immutable
+ * attempt. `restartedKey` resumes a proof a previous supervisor left pending;
+ * the crash itself is the failure that may spend the allowance.
+ */
+export async function runFinalProof(repository, runId, steps, restartedKey) {
+    const key = restartedKey ?? await steps.attemptKey();
+    const replay = async (code, replayable) => {
+        let eligible = false;
+        try {
+            eligible = replayable && await steps.attemptKey() === key && await steps.untouched();
+        }
+        catch {
+            eligible = false;
+        }
+        const replaying = await settleFinalProofFailure(repository, runId, key, code, eligible) === "replay";
+        const latest = (await repository.read(runId));
+        await repository.appendEvent(runId, { type: "diagnostic", code: replaying ? "RUN_FINAL_PROOF_RECOVERING" : "RUN_FINAL_PROOF_RECOVERY_STOPPED",
+            workerId: latest.coordinatorId, taskId: latest.rootTaskId, detail: replaying
+                ? `${code}: replaying final proof once with no writer started; a valid saved primary review and current verification are reused.`
+                : `${code}: automatic recovery ${replayable ? "is spent or no longer applies to this candidate" : "does not apply to this failure"}; the checkout is preserved.` });
+        return replaying;
+    };
+    if (restartedKey === undefined)
+        await beginFinalProof(repository, runId, key);
+    else if (!await replay("RUN_SUPERVISOR_RESTARTED", true))
+        throw new AgentOpsError("RUN_FINAL_PROOF_INTERRUPTED", "Final proof was interrupted by a supervisor restart and cannot be replayed automatically.");
+    for (;;) {
+        let result;
+        let failure;
+        try {
+            result = await steps.advance();
+            if (result.status === "ok")
+                return result;
+        }
+        catch (cause) {
+            failure = cause;
+        }
+        const replayable = failure === undefined ? (await repository.read(runId)).finalProof?.reviewTransient === true
+            : failure instanceof InterruptedStepError && failure.replayable;
+        const code = failure instanceof AgentOpsError ? failure.code : result?.code ?? "RUN_FINAL_PROOF_FAILED";
+        if (await replay(code, replayable))
+            continue;
+        if (failure !== undefined)
+            throw failure;
+        return result;
+    }
+}
+/**
+ * Whether any process still belongs to the group: a proof group can outlive
+ * its leader. An unreadable process table counts as alive.
+ */
+export function processGroupAlive(group) {
+    try {
+        return execFileSync("ps", ["-axo", "pgid="], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] })
+            .split("\n").some(line => Number(line.trim()) === group);
+    }
+    catch {
+        return true;
+    }
+}

package/dist/runtime/src/run/service.js

@@ -159,6 +159,15 @@ export function assertRunState(value) {
         state.landing.processId < 1 || typeof state.landing.hostname !== "string" || state.landing.hostname.length > 256 ||
         !Number.isFinite(Date.parse(String(state.landing.startedAt)))))
         return invalid("Invalid run landing marker.");
+    if (state.finalProof != null && (!plain(state.finalProof) || !SHA256.test(String(state.finalProof.attemptKey)) ||
+        ![0, 1].includes(state.finalProof.recoveries) || typeof state.finalProof.pending !== "boolean" ||
+        typeof state.finalProof.reviewTransient !== "boolean" || typeof state.finalProof.stopped !== "boolean" ||
+        !boundedArray(state.finalProof.failures, 2) || state.finalProof.failures.some(f => !plain(f) ||
+        typeof f.code !== "string" || f.code.length === 0 || f.code.length > 128 || !Number.isFinite(Date.parse(String(f.at)))) ||
+        (state.finalProof.checkpoints !== undefined && (!plain(state.finalProof.checkpoints) ||
+            Object.keys(state.finalProof.checkpoints).length > 64 ||
+            Object.entries(state.finalProof.checkpoints).some(([binding, digest]) => !SHA256.test(binding) || !SHA256.test(String(digest)))))))
+        return invalid("Invalid final proof recovery record.");
     if (state.proofProcess != null && (!plain(state.proofProcess) || !Number.isSafeInteger(state.proofProcess.processId) ||
         state.proofProcess.processId < 1 || typeof state.proofProcess.processIdentity !== "string" ||
         state.proofProcess.processIdentity.length === 0 || state.proofProcess.processIdentity.length > 256))

package/docs/en/spec/review.md

@@ -280,3 +280,16 @@ A batch result MUST report every task's outcome and MUST exit 0 only when every
 - Evidence: The envelope code and the exit code agree with the per-task outcomes.
 - Positive: `One FAIL and one NOT_RUN exit 1, so the defect is handled first.`
 - Negative: `Exit 0 while a task is still NOT_RUN.`
+
+## REVIEW-RESUME-001
+
+A native run's coordinator final proof MUST NOT pay again for a review round
+that already answered the exact same review, and MUST retry automatically at
+most once per immutable final attempt.
+
+- Trigger: A run's final proof is interrupted: its proof process group was killed or returned a broken result (not by a stop, the run deadline, the output limit or a spawn failure, and with no process of the group left), its review chain ended on a transient attempt (a dropped call or a lost agy turn), or the supervisor restarted with the proof pending.
+- Action: Inside the supervisor's registered proof group, review saves the necessary PASS after the source recheck and before the adversarial round, then the answered pair, under the run's private directory, bound to the primary prompt, the planned pair, model and effort, with each file's digest recorded in the locked run state like run answers and plans: a file without that record is ignored, so a planted PASS pair cannot skip review; the reviewer's in-process retry is off there. The supervisor keys each attempt by candidate, target, tree contract and policy config and runtime, and spends its one recovery only while the coordinator checkout is clean, no integration transaction exists and the run is active. The replay starts no writer, resumes a saved PASS with a fresh adversarial session, rebuilds a saved PASS pair without any model call, and still needs the standard attestation, finish and receipt. `task advance`, for every caller, skips `verify` for a task whose passing evidence still holds for the candidate by the rule review's preflight applies.
+- Evidence: `run status` prints `Final proof recovery: <n>/1 used; first failure …; last failure …; automatic recovery stopped|in progress|available`, and the run events carry `RUN_FINAL_PROOF_RECOVERING` or `RUN_FINAL_PROOF_RECOVERY_STOPPED`. A recorded checkpoint that is corrupt, missing or mismatched ends the review NOT_RUN `checkpoint-invalid` without calling any reviewer. A refuted pair is never resumed. Checkpoints are deleted once the run's receipt is accepted.
+- Positive: `The second round lost its connection; the supervisor replayed once, the necessary reviewer was not called again, and the run finished with a receipt.`
+- Negative: `Retry until the adversarial reviewer passes, or replay after a stop, a timeout or a substantive FAIL.`
+- Note: Standalone `review`, `batch` and child handoff keep their in-process retry and never read or write checkpoints. An uncommitted coordinator checkout is never replayed; it is left untouched for the existing repair.

package/docs/zh-TW/spec/review.md

@@ -250,3 +250,14 @@ permission bypass。外部 host runner 不可用時，結果 MUST 保持 NOT_RUN
 - Evidence: envelope code 與 exit code 與各 task 的結果一致。
 - Positive: `一個 FAIL 與一個 NOT_RUN 以 1 結束，先處理缺陷。`
 - Negative: `仍有 task 是 NOT_RUN 卻以 0 結束。`
+
+## REVIEW-RESUME-001
+
+native run 的 coordinator 最終驗收 MUST NOT 為同一份審查中已經回答過的輪次再付一次費用，且每個不可變的最終驗收 attempt MUST 至多自動重試一次。
+
+- Trigger: run 的最終驗收中斷：proof process group 被終止或回傳損壞的結果（不是 stop、run 期限、輸出上限或啟動失敗造成，且該 group 已沒有任何程序），審查鏈以 transient attempt（連線中斷或 agy 遺失回合）結束，或 supervisor 在驗收 pending 時重啟。
+- Action: 在 supervisor 已註冊的 proof group 內，審查於來源再檢查之後、adversarial 輪之前保存必要 PASS，之後保存已回答的雙輪，存於 run 的私有目錄，綁定 primary prompt、規劃的雙 target、model 與 effort，並像 run 的 answers 與 plans 一樣把每個檔案的 digest 記在加鎖的 run state：沒有紀錄的檔案一律忽略，植入的 PASS 雙輪無法略過審查；此情境關閉 reviewer 的程序內 retry。supervisor 以 candidate、target、tree contract、policy config 與 runtime 作為 attempt key，只在 coordinator checkout 乾淨、沒有 integration transaction 且 run 仍 active 時花掉那一次恢復。重放不啟動任何 writer，以全新 adversarial session 接續已保存的 PASS，已保存的 PASS 雙輪不呼叫任何模型直接重建，且仍須標準 attestation、finish 與 receipt。`task advance` 對所有呼叫者，若某 task 的 PASS 證據依審查 preflight 的同一規則對 candidate 仍有效，就略過 `verify`。
+- Evidence: `run status` 顯示 `Final proof recovery: <n>/1 used; first failure …; last failure …; automatic recovery stopped|in progress|available`，run 事件記錄 `RUN_FINAL_PROOF_RECOVERING` 或 `RUN_FINAL_PROOF_RECOVERY_STOPPED`。已記錄但損壞、遺失或不相符的 checkpoint 使審查以 NOT_RUN `checkpoint-invalid` 結束，且不呼叫任何 reviewer。被反駁的雙輪永不續用。run 的 receipt 被接受後即刪除 checkpoint。
+- Positive: `第二輪連線中斷；supervisor 重放一次，必要 reviewer 沒有再被呼叫，run 以 receipt 完成。`
+- Negative: `一直重試直到 adversarial reviewer 通過，或在 stop、timeout、實質 FAIL 之後重放。`
+- Note: standalone `review`、`batch` 與 child handoff 保留程序內 retry，永不讀寫 checkpoint。有未提交修改的 coordinator checkout 永不重放，原樣保留給既有 repair 處理。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kylecheng3146/agent-ops",
-  "version": "0.11.5",
+  "version": "0.11.6",
   "description": "Evidence-driven development loops for agy, Codex, Claude Code, and opencode",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",