@kylecheng3146/agent-ops 0.11.4 → 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/review.js

@@ -317,6 +317,7 @@ const SURFACE_REASONS = {
     SURFACE_UNCLASSIFIED: "surface-unclassified",
     SURFACE_QUERY_TOO_BROAD: "surface-query-too-broad",
     SURFACE_EXCLUSION_TOO_BROAD: "surface-exclusion-too-broad",
+    SURFACE_INCLUSION_TOO_BROAD: "surface-inclusion-too-broad",
     SCENARIO_MISSING: "scenario-missing",
     SURFACE_BUDGET_EXCEEDED: "surface-budget-exceeded",
     SURFACE_UNASSIGNED: "surface-unassigned",

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/review/runner.js

@@ -108,6 +108,8 @@ function taskDataBlock(invocation) {
 function surfaceBlock(invocation, round) {
     if (invocation.packet.surface === undefined)
         return [];
+    const discovery = invocation.packet.surface.discovery;
+    const skipped = round === "adversarial" ? discovery?.skipped ?? [] : [];
     return [
         "",
         "Surface coverage (narrow exception to \"Do not survey\"): task data carries the surface audit, its revision " +
@@ -121,7 +123,10 @@ function surfaceBlock(invocation, round) {
                 "and indirect consumer. Do not run other searches beyond callers a specific question needs."
             : "Round 2: check the five fixed scenarios (initialState, redo, timeBoundary, identitySwitch, concurrency) against " +
                 "the code, and hunt unlisted surfaces with at most 3 new `git grep -F` queries per axis (dependents, duplicates, " +
-                "otherPaths, sharedState); cite each query you ran in evidence."
+                "otherPaths, sharedState); cite each query you ran in evidence.",
+        ...(skipped.length === 0 ? [] : ["Skipped derived queries (over 10 files outside the diff, so discovery never gated them; " +
+                `fewest first): ${skipped.map(row => `\`${row.query}\` (${row.files})`).join(", ")}. Beyond the per-axis budget, run at most 3 ` +
+                "extra `git grep -F` queries in total over these to find copied siblings the change missed; cite each in evidence."])
     ];
 }
 /** Escape Loop: both rounds adjudicate the earliest-gate label of each declared escape. */

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/dist/runtime/src/surface/discovery.js

@@ -11,8 +11,8 @@ import { globMatcher, isCovers, missingScenarios, parseSurface, SURFACE_AXES } f
 /** Cheapest first: a budget overrun stops before the long tail of diff tokens. */
 export const DISCOVERY_SOURCES = ["agent", "hunk-header", "template-fragment", "diff-token"];
 export const SURFACE_LIMITS = {
-    // ponytail: derived queries over 10 files are skipped as generic; incidental ones under that are dismissed by query.
-    agentQueryFiles: 200, derivedQueryFiles: 10, exclusionFiles: 10, dismissals: 128, dismissMinFiles: 4, budgetMs: 120_000, queryTimeoutMs: 30_000,
+    // ponytail: derived queries over 10 files outside the diff are skipped as generic; incidental ones under that are dismissed by query.
+    agentQueryFiles: 200, derivedQueryFiles: 10, exclusionFiles: 10, inclusionFiles: 10, dismissals: 128, dismissMinFiles: 4, budgetMs: 120_000, queryTimeoutMs: 30_000,
     tokenLength: 6, fragmentLength: 4, derivedQueries: 400
 };
 /** argv only: queries are task text and must never meet a shell or a regex engine. */
@@ -142,14 +142,23 @@ export async function runSurfaceGate(input) {
     const tracked = await git(input.root, ["ls-files", "-z"], Math.min(SURFACE_LIMITS.queryTimeoutMs, Math.max(1, remaining())));
     if (tracked.timedOut || remaining() <= 0)
         return notRun("SURFACE_BUDGET_EXCEEDED", "Discovery budget exhausted listing files.", []);
+    const trackedFiles = zList(tracked.stdout);
     const exclusions = surface.excluded.map(row => ({ ...row, match: globMatcher(row.glob) }));
     for (const row of exclusions) {
-        const files = zList(tracked.stdout).filter(row.match);
+        const files = trackedFiles.filter(row.match);
         const diffFiles = [...changed].filter(row.match);
         if (files.length > SURFACE_LIMITS.exclusionFiles || diffFiles.length > 0)
             return notRun("SURFACE_EXCLUSION_TOO_BROAD", diffFiles.length > 0 ? "Files in the diff cannot be excluded."
                 : `One exclusion may hide at most ${SURFACE_LIMITS.exclusionFiles} files.`, [{ glob: row.glob, files: files.length, diffFiles }]);
     }
+    // An included or UNKNOWN glob classifies every hit it matches, so it is capped like an exclusion.
+    for (const glob of [...surface.included.map(row => row.path), ...surface.unknown.flatMap(row => row.path === undefined ? [] : [row.path])]) {
+        const match = globMatcher(glob);
+        const files = trackedFiles.filter(path => match(path) && !changed.has(path)).length;
+        if (files > SURFACE_LIMITS.inclusionFiles)
+            return notRun("SURFACE_INCLUSION_TOO_BROAD", `One included or UNKNOWN glob may cover at most ${SURFACE_LIMITS.inclusionFiles} ` +
+                "files outside the diff; list narrower paths, each with its own behavior.", [{ glob, files }]);
+    }
     const head = (await git(input.root, ["rev-parse", "HEAD"], SURFACE_LIMITS.queryTimeoutMs)).stdout.toString("utf8").trim();
     const diff = (await git(input.root, ["diff", "-U0", "--no-color", "--no-ext-diff", input.base ?? "HEAD", "--"], SURFACE_LIMITS.queryTimeoutMs)).stdout.toString("utf8");
     const derived = extractDiffQueries(diff);
@@ -217,7 +226,7 @@ export async function runSurfaceGate(input) {
             return notRun("SURFACE_DISMISSAL_INVALID", "A recorded axis query cannot be dismissed; classify its hits.", [{ query }]);
         const hit = hits.find(row => row.query === query && row.source !== "agent");
         const outside = hit === undefined ? [] : hit.files.filter(path => !changed.has(path));
-        if (hit !== undefined && outside.length < SURFACE_LIMITS.dismissMinFiles && hit.files.length <= SURFACE_LIMITS.derivedQueryFiles)
+        if (hit !== undefined && outside.length < SURFACE_LIMITS.dismissMinFiles)
             return notRun("SURFACE_DISMISSAL_INVALID", `A query reaching fewer than ${SURFACE_LIMITS.dismissMinFiles} files outside the diff ` +
                 "is the likeliest sibling signal and cannot be dismissed; classify its files.", [{ query, files: outside }]);
         if (hit !== undefined)
@@ -227,8 +236,9 @@ export async function runSurfaceGate(input) {
         sources[hit.source].queries += 1;
         if (hit.source === "agent" && hit.files.length > SURFACE_LIMITS.agentQueryFiles)
             return notRun("SURFACE_QUERY_TOO_BROAD", `Query hits more than ${SURFACE_LIMITS.agentQueryFiles} files; record a more specific fixed string.`, [{ query: hit.query, files: hit.files.length }]);
-        if (hit.source !== "agent" && hit.files.length > SURFACE_LIMITS.derivedQueryFiles) {
-            skipped.push({ source: hit.source, query: hit.query, files: hit.files.length });
+        const outside = hit.files.filter(path => !changed.has(path)).length;
+        if (hit.source !== "agent" && outside > SURFACE_LIMITS.derivedQueryFiles) {
+            skipped.push({ source: hit.source, query: hit.query, files: outside });
             continue;
         }
         if (hit.source !== "agent" && dismissals.has(hit.query))
@@ -284,7 +294,8 @@ export async function runSurfaceGate(input) {
         return notRun("ESCAPE_RULE_NO_EXCLUDE", "A learned escape rule marks these places noExclude: include them or mark them UNKNOWN.", noExclude);
     for (const source of DISCOVERY_SOURCES)
         sources[source].files = metrics.get(source).hits.size;
-    const discovery = { cached, sources, skipped: skipped.slice(0, 50), postBlockExclusions, dismissed };
+    const discovery = { cached, sources, skipped: skipped
+            .sort((a, b) => a.files - b.files || (a.query < b.query ? -1 : a.query > b.query ? 1 : 0)).slice(0, 50), postBlockExclusions, dismissed };
     if (input.metrics === true)
         await logMetrics(input.logHome ?? process.env.AGENT_OPS_HOME ?? homedir(), DISCOVERY_SOURCES.map(source => ({ source,
             hits: metrics.get(source).hits.size, included: metrics.get(source).included.size, excluded: metrics.get(source).excluded.size,

package/docs/en/spec/acceptance-and-evidence.md

@@ -99,6 +99,9 @@ Every new task MUST record a surface audit of where else its change lands before
   `glob` and a reason saying why the surface is unaffected ("out of scope" is
   not a reason); `unknown` rows name a reader the repository cannot see.
   `contracts` declare `compatible` or `breaking`. A single surface is allowed.
+  An `included` or `unknown` path glob may cover at most 10 tracked files
+  outside the diff, like an exclusion; list narrower paths, each with its own
+  behavior.
 - `valueChanges` `[{producer, kind, change, consumers, indirectConsumers}]`
   list two hops whenever a value's semantics change (clear, redact, default,
   normalize, unit/format).
@@ -114,8 +117,9 @@ Every new task MUST record a surface audit of where else its change lands before
   template-literal fixed fragments (at least 4 characters, separator-bounded,
   such as `order:`, `user_`, `menu.`); compound identifiers (snake_case,
   camelCase or containing digits, so prose words are not queries) and string
-  literals from added and removed lines (at least 6 characters; skipped as too
-  generic above 10 file hits, changed files included). Every hit outside the diff and the surface lists stops review.
+  literals from added and removed lines (at least 6 characters). A derived
+  query is skipped as too generic above 10 hit files outside the diff; skipped
+  queries, fewest hits first, go to the second reviewer. Every hit outside the diff and the surface lists stops review.
 - A derived query (diff token, template fragment or hunk-header name) whose hits
   are incidental may be dismissed once in the surface's optional `dismissed`
   list (`{query, reason}`, reason at most 256 characters, "out of scope" is
@@ -132,7 +136,8 @@ Every new task MUST record a surface audit of where else its change lands before
   also refused at create), `SURFACE_UNCLASSIFIED`,
   `SURFACE_QUERY_TOO_BROAD` (one recorded query over 200 files),
   `SURFACE_EXCLUSION_TOO_BROAD` (one glob over 10 files, or any file in the
-  diff), `SURFACE_DISMISSAL_TOO_BROAD` (over 128 dismissals),
+  diff), `SURFACE_INCLUSION_TOO_BROAD` (one included or UNKNOWN glob over 10
+  files outside the diff), `SURFACE_DISMISSAL_TOO_BROAD` (over 128 dismissals),
   `SURFACE_DISMISSAL_INVALID` (a recorded or rare query), `SCENARIO_MISSING`, `SURFACE_BUDGET_EXCEEDED` (120 s total, never
   silently skipped) or `SURFACE_UNASSIGNED` (children's covers differ from the
   parent's included list; checked by every review, including advance and batch).

package/docs/en/spec/review.md

@@ -108,7 +108,9 @@ successful refutation MUST make the run FAIL.
   session. A FAIL is already terminal and is never re-checked.
 - Note: For a surfaced task the second round also hunts unlisted surfaces and
   scenarios under `surface-coverage`: it checks the five fixed scenario
-  dimensions and may run at most 3 new `git grep -F` queries per axis. Round 1
+  dimensions and may run at most 3 new `git grep -F` queries per axis, plus at
+  most 3 in total over the derived queries discovery skipped as too generic,
+  which the prompt names with their hit counts. Round 1
   replays the recorded queries and reads every listed `valueChanges` consumer;
   this is the only exception to "do not survey the repository".
 
@@ -278,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/acceptance-and-evidence.md

@@ -62,7 +62,8 @@ English source version: 2026-10-20. Revalidate: when the English specification c
 - `included` 列含 `id`、`path` glob 與 `behavior`；`excluded` 列含 `glob` 與說明
   該 surface 為何不受影響的理由（「out of scope」不是理由）；`unknown` 列記錄
   repository 看不到的讀取者。`contracts` 宣告 `compatible` 或 `breaking`。只有單一
-  surface 也可以。
+  surface 也可以。`included` 或 `unknown` 的 path glob 與排除一樣，至多涵蓋 diff
+  以外 10 個 tracked 檔案；請改列更窄的路徑，各自寫出 behavior。
 - 值的語意改變（clear、redact、default、normalize、unit/format）時，
   `valueChanges` `[{producer, kind, change, consumers, indirectConsumers}]` 列出兩層
   consumer。
@@ -75,8 +76,8 @@ English source version: 2026-10-20. Revalidate: when the English specification c
   不以 task 文字組 regex），由便宜的來源先跑：記錄的查詢；diff hunk header 的外層
   函式名；template literal 固定片段（至少 4 字元且以分隔符界定，例如 `order:`、
   `user_`、`menu.`）；新增與刪除行的複合識別字（snake_case、camelCase 或含數字，
-  因此一般文字單字不會成為查詢）與字串常值（至少 6 字元；命中超過 10 個檔案〈含
-  變更檔案〉視為太通用而略過）。diff 與 surface 清單之外的任何命中都會擋下 review。
+  因此一般文字單字不會成為查詢）與字串常值（至少 6 字元）。衍生查詢在 diff 以外命中
+  超過 10 個檔案時視為太通用而略過；略過的查詢依命中數由少到多交給第二輪 reviewer。diff 與 surface 清單之外的任何命中都會擋下 review。
 - 衍生查詢（diff 字詞、template 片段或 hunk header 函式名）的命中若只是巧合，可在
   surface 選用的 `dismissed` 清單中以一筆 `{query, reason}` 排除（理由至多 256
   字元，「out of scope」不是理由），不必逐檔排除。記錄的軸查詢與 escape rule 命中
@@ -88,7 +89,8 @@ English source version: 2026-10-20. Revalidate: when the English specification c
 - Review 以 NOT_RUN 回報：`SURFACE_MISSING`（沒有或無法解析的 surface；
   task 建立時也會拒絕）、`SURFACE_UNCLASSIFIED`、`SURFACE_QUERY_TOO_BROAD`（單一
   記錄查詢超過 200 個檔案）、`SURFACE_EXCLUSION_TOO_BROAD`（單一 glob 超過 10 個
-  檔案，或包含 diff 內的檔案）、`SURFACE_DISMISSAL_TOO_BROAD`（超過 128 筆排除）、
+  檔案，或包含 diff 內的檔案）、`SURFACE_INCLUSION_TOO_BROAD`（單一 included 或
+  UNKNOWN glob 涵蓋 diff 以外超過 10 個檔案）、`SURFACE_DISMISSAL_TOO_BROAD`（超過 128 筆排除）、
   `SURFACE_DISMISSAL_INVALID`（記錄的查詢或稀有查詢）、`SCENARIO_MISSING`、`SURFACE_BUDGET_EXCEEDED`
   （總計 120 秒，絕不默默略過）或 `SURFACE_UNASSIGNED`（子 task covers 與父 task
   included 不一致；每次 review 都檢查，包含 advance 與 batch）。

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

@@ -98,7 +98,7 @@ PASS MUST 交給第二個規劃的 target 嘗試反駁，且反駁成立時 MUST
 - Positive: `codex 判 PASS，claude 找到 blocking 缺陷，整體判定 FAIL。`
 - Negative: `為了讓複查看起來有效而編造反駁。`
 - Note: 只有一個設定 target 時，會在全新 session 再呼叫同一 target。FAIL 已是終局，不再複查。
-- Note: 有 surface 的 task，第二輪也會在 `surface-coverage` 下搜尋未列出的 surface 與情境：檢查五個固定情境維度，每個軸向最多可新增 3 個 `git grep -F` 查詢。第一輪重放記錄的查詢並閱讀每個列出的 `valueChanges` consumer；這是「不要普查 repository」唯一的例外。
+- Note: 有 surface 的 task，第二輪也會在 `surface-coverage` 下搜尋未列出的 surface 與情境：檢查五個固定情境維度，每個軸向最多可新增 3 個 `git grep -F` 查詢，另外可針對 discovery 因太通用而略過的衍生查詢（prompt 會列出它們與命中數）總計最多再跑 3 個。第一輪重放記錄的查詢並閱讀每個列出的 `valueChanges` consumer；這是「不要普查 repository」唯一的例外。
 
 ## REVIEW-ORIGIN-001
 
@@ -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.4",
+  "version": "0.11.6",
   "description": "Evidence-driven development loops for agy, Codex, Claude Code, and opencode",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",