@kylecheng3146/agent-ops 0.10.0 → 0.11.0

package/dist/runtime/src/parallel/finish.js

@@ -1,18 +1,18 @@
 import { withActivity } from "../office/activity.js";
-import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { lstat, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { join } from "node:path";
-import { sha256 } from "../fs/hash.js";
-import { AgentOpsError, resolveContainedPath } from "../fs/paths.js";
+import { AgentOpsError } from "../fs/paths.js";
 import { currentGateFingerprint } from "../hooks/completion-gate.js";
 import { collectChangeSurface } from "../verify/change-surface.js";
-import { aggregateVerificationStatus, executeConfiguredCommand } from "../verify/command-executor.js";
 import { prepareFinishReceipt } from "./receipt.js";
 import { resolveReviewScope } from "../review/scope.js";
 import { calculateSourceFingerprint } from "../verify/source-fingerprint.js";
-import { readRunIntegrationProof, readRunIntegrationReceiptBinding, markRunIntegration } from "../run/integration.js";
+import { readRunIntegrationProof, readRunIntegrationReceiptBinding, markRunIntegration, validateRunIntegrationCleanup, recoverRunIntegrationAfterCleanup } from "../run/integration.js";
+import { FileRunRepository } from "../run/service.js";
+import { sha256 } from "../fs/hash.js";
+import { redactSecrets } from "../security/redact.js";
 import { canonicalJson } from "../config/hash.js";
-import { listWorktrees } from "./manage.js";
 import { withPrivateFileLock } from "../security/permissions.js";
 import { markOfficeSessionCompleted } from "../office/sessions.js";
 import { assertWorktreeName, NOTES_REF, noteSessionLine, parseWorktreeListPorcelain, readWorktreeRecord, removeCheckout, resolveCheckouts, worktreePath } from "./service.js";
@@ -23,6 +23,104 @@ const LOCK_WAIT_MS = 30 * 60 * 1000;
 // reused by something we can see; the lock is reclaimed.
 const LOCK_STALE_MS = 2 * 60 * 60 * 1000;
 const MAX_INTENTS = 20;
+/** Resume only the uncompleted cleanup steps of an already receipt-bound transaction. */
+async function finishRunCleanup(deps, commonDir, record, proof, children) {
+    const sealed = await readRunIntegrationProof(commonDir, record);
+    const { recovery: _recovery, ...requested } = proof;
+    if (sealed === null || canonicalJson(sealed) !== canonicalJson(requested))
+        throw finishError("RUN_INTEGRATION_PROOF_CHANGED", "Cleanup requires the exact sealed final candidate.");
+    const { state, integration, receipt, noteBound } = await validateRunIntegrationCleanup(commonDir, record.runId, deps.git, true);
+    if (state.status !== "active" || state.disableRestart || state.awaitingResume)
+        throw finishError("RUN_RESUME_DISABLED", "Manual resume is required before executing pending cleanup steps.");
+    if (state.events.some(event => event.code === "RUN_COMMAND_DENIED"))
+        throw finishError("RUN_COMMAND_DENIED", "Cleanup cannot erase an explicit native or organization denial.");
+    const expectedChildren = new Map(proof.children.map(child => [child.name, child]));
+    if (children.some(child => !expectedChildren.has(child.name)) || proof.children.some(child => !children.some(actual => actual.name === child.name) && !integration.completedSteps.includes("child:" + child.name)))
+        throw finishError("WORKTREE_CHILDREN_CHANGED", "Cleanup requires the sealed child set or recorded completed child cleanup.");
+    for (const child of [record, ...children]) {
+        const expected = child === record ? proof.head : expectedChildren.get(child.name).commit;
+        if (await git(deps, child.path, ["rev-parse", "HEAD"], "WORKTREE_SOURCE_MOVED", "Cannot read cleanup checkout.") !== expected ||
+            (child !== record && (child.runId !== record.runId || child.ownerSessionId !== record.ownerSessionId ||
+                child.workerId !== expectedChildren.get(child.name).workerId ||
+                child.workerGeneration !== expectedChildren.get(child.name).workerGeneration)))
+            throw finishError("WORKTREE_CHILDREN_CHANGED", "The cleanup checkout owner or candidate changed; preserve it.");
+    }
+    // This key suppresses identical removal retries, never authorizes cleanup or reuses proof.
+    const inputs = [];
+    for (const child of [record, ...children]) {
+        const status = await git(deps, child.path, ["status", "--porcelain=v1", "-z", "--untracked-files=all"], "WORKTREE_LOG_FAILED", "Cannot inspect cleanup inputs.");
+        const untracked = await deps.git(child.path, ["ls-files", "--others", "--exclude-standard", "-z"]);
+        if (untracked.exitCode !== 0)
+            throw finishError("WORKTREE_LOG_FAILED", "Cannot inspect cleanup files.");
+        const files = [];
+        for (const path of untracked.stdout.split("\0").filter(Boolean)) {
+            const info = await lstat(join(child.path, path));
+            const pid = /(?:^|\/)\.agent-ops-process-(\d+)-/u.exec(path)?.[1];
+            files.push([path, info.size, info.mtimeMs, info.ctimeMs, info.mode, pid === undefined ? null : alive(Number(pid))]);
+        }
+        inputs.push({ path: child.path, status, files });
+    }
+    const inputDigest = sha256(canonicalJson({ transaction: integration, inputs }));
+    const previous = [...state.events].reverse().find(event => event.code === "RUN_CLEANUP_BLOCKED");
+    if (previous?.detail !== null && previous?.detail !== undefined) {
+        let saved = {};
+        try {
+            saved = JSON.parse(previous.detail);
+        }
+        catch { /* Old diagnostics cannot suppress a new attempt. */ }
+        if (saved.inputDigest === inputDigest)
+            throw finishError("RUN_CLEANUP_UNCHANGED", "Cleanup inputs match the saved failure; resolve its original blocker before retrying. See run status/logs.");
+    }
+    const repository = new FileRunRepository(join(commonDir, "agent-ops/runs"), commonDir);
+    const step = async (name, action) => {
+        if (integration.completedSteps.includes(name))
+            return;
+        await readRunIntegrationProof(commonDir, record);
+        const { state: current } = await validateRunIntegrationCleanup(commonDir, record.runId, deps.git, name === "note");
+        if (current.status !== "active" || current.disableRestart || current.awaitingResume)
+            throw finishError("RUN_RESUME_DISABLED", "The run was paused or stopped before the pending cleanup step.");
+        await action();
+        await markRunIntegration(commonDir, record, "receipt-written", name);
+    };
+    try {
+        await step("note", async () => {
+            if (!noteBound)
+                await git(deps, record.mainRoot, ["notes", `--ref=${NOTES_REF}`, "add", "-m",
+                    `${noteText(record, taskTree(receipt.tasks ?? []))}\nreceipt: ${integration.receiptPath}\nreceipt-sha256: ${integration.receiptDigest}`,
+                    proof.head], "WORKTREE_NOTE_FAILED", "Cannot bind the sealed receipt to its candidate.");
+        });
+        const config = await deps.loadConfig(record.mainRoot);
+        await step("gate", async () => {
+            if (!config.features.completionGate.enabled)
+                return;
+            const gate = await deps.gate(record.mainRoot, config);
+            const fingerprint = await currentGateFingerprint(record.mainRoot, runner(deps, record.mainRoot));
+            for (const child of [record, ...children])
+                await gate.afterFinish(record.sessionId, child.path, fingerprint);
+        });
+        await step("trust", async () => await deps.trust.revoke(record.path, await deps.loadConfig(record.path)));
+        for (const child of children)
+            await step("child:" + child.name, async () => {
+                if ((await collectChangeSurface(runner(deps, child.path))).paths.length > 0)
+                    throw finishError("WORKTREE_CHILDREN_CHANGED", "The child changed after integration; preserve it.");
+                await deps.trust.revoke(child.path, await deps.loadConfig(child.path));
+                await removeCheckout(deps, child, false, expectedChildren.get(child.name).commit);
+            });
+        await step("coordinator", async () => await removeCheckout(deps, record, false, proof.head));
+    }
+    catch (cause) {
+        // Completed steps change the retry key; preserve the latest boundary with the original cause.
+        const latest = (await repository.read(record.runId));
+        const digest = sha256(canonicalJson({ transaction: latest.integration, inputs }));
+        await repository.appendEvent(record.runId, { type: "diagnostic", code: "RUN_CLEANUP_BLOCKED", workerId: record.workerId, taskId: state.rootTaskId,
+            detail: JSON.stringify({ inputDigest: digest, code: cause instanceof AgentOpsError ? cause.code : "RUN_CLEANUP_FAILED",
+                message: redactSecrets(cause instanceof Error ? cause.message : "Cleanup failed; preserve the owned checkout.").slice(0, 4096) }) });
+        throw cause;
+    }
+    await recoverRunIntegrationAfterCleanup(commonDir, record.runId, deps.git);
+    return { record, mergedHead: proof.head, taskIds: (receipt.tasks ?? []).map(item => item.task.id), warnings: [],
+        receipt: integration.receiptPath, residualRisks: receipt.residualRisks ?? [] };
+}
 /**
  * The work and the moved target touch the same lines. The rebase was undone;
  * this carries what the agent needs to redo it deliberately: the files, and
@@ -151,30 +249,6 @@ export async function withFinishLock(deps, commonDir, action) {
         });
     }
 }
-/**
- * The branch's own change, independent of where it is based: hunk positions
- * and blob ids move with a rebase, the change itself does not.
- */
-async function patchHash(deps, cwd, target) {
-    const diff = await git(deps, cwd, ["diff", "--no-color", "--no-ext-diff", "--no-textconv", `${target}...HEAD`], "WORKTREE_DIFF_FAILED", "Git could not diff the branch.");
-    return sha256(diff.split("\n")
-        .filter((line) => !line.startsWith("index "))
-        .map((line) => line.startsWith("@@") ? "@@" : line)
-        .join("\n"));
-}
-async function reverify(deps, root, config) {
-    const results = [];
-    for (const command of config.verification.commands) {
-        results.push(await executeConfiguredCommand(command, {
-            cwd: command.cwd === "." ? root : await resolveContainedPath(root, command.cwd),
-            trusted: true,
-            ...(deps.processRunner === undefined ? {} : { runner: deps.processRunner })
-        }));
-    }
-    return aggregateVerificationStatus(results) === "PASS"
-        ? []
-        : results.filter((result) => result.required && result.status !== "PASS").map(({ commandId }) => commandId);
-}
 async function targetIntents(deps, cwd, target) {
     const commits = (await git(deps, cwd, ["log", "--format=%H", `HEAD..${target}`], "WORKTREE_LOG_FAILED", "Git could not list the target-side commits.")).split("\n").filter(Boolean);
     const intents = [];
@@ -238,10 +312,16 @@ export async function finishWorktree(deps, options) {
     }
     // Display only: the integrator is at work while the finish runs.
     return await withActivity(commonDir, { kind: "finish", root: record.path, sessionId: record.sessionId, worktree: name }, async () => await withFinishLock(deps, commonDir, async () => {
-        const sessionChildren = (await listWorktrees(deps, mainRoot))
-            .map(({ record: child }) => child)
-            .filter((child) => child.path !== record.path && child.sessionId === record.sessionId &&
+        const listing = await git(deps, mainRoot, ["worktree", "list", "--porcelain"], "WORKTREE_LIST_FAILED", "Cannot list cleanup worktrees.");
+        const records = await Promise.all(parseWorktreeListPorcelain(listing).map(child => readWorktreeRecord(child.path)));
+        const sessionChildren = records
+            .filter((child) => child !== null && child.path !== record.path && child.sessionId === record.sessionId &&
             (child.agentId !== undefined || (record.runId !== undefined && child.runId === record.runId)));
+        if (options.finalProof?.recovery === true && record.runId !== undefined) {
+            const saved = await new FileRunRepository(join(commonDir, "agent-ops/runs"), commonDir).read(record.runId);
+            if (["receipt-written", "cleaned"].includes(saved?.integration?.status ?? ""))
+                return await finishRunCleanup(deps, commonDir, record, options.finalProof, sessionChildren);
+        }
         if (options.finalProof === undefined && sessionChildren.length > 0) {
             throw finishError("WORKTREE_CHILDREN_REQUIRE_ADVANCE", "This session has child worktrees; run task advance for integrated final evidence before finish.");
         }
@@ -346,6 +426,25 @@ export async function finishWorktree(deps, options) {
                 throw finishError("WORKTREE_TASK_INCOMPLETE", `The worktree's task is not ready to merge (${problem.code}). ${problem.remedy ?? ""}`.trim());
             }
         };
+        // A final proof already refused a moved target above. A plain finish
+        // rebases for the caller but never delivers the rebased combination: its
+        // evidence and review covered the old base, not what would merge.
+        if (options.finalProof === undefined &&
+            (await deps.git(record.path, ["merge-base", "--is-ancestor", target, "HEAD"])).exitCode !== 0) {
+            const rebase = await deps.git(record.path, ["rebase", "--no-autostash", target]);
+            if (rebase.exitCode !== 0) {
+                const files = (await deps.git(record.path, ["diff", "--name-only", "--diff-filter=U"])).stdout
+                    .split("\n").map((line) => line.trim()).filter(Boolean);
+                await deps.git(record.path, ["rebase", "--abort"]);
+                await deps.git(record.path, ["reset", "--hard", headBeforeCompletion]);
+                throw new WorktreeConflictError(record, target, headBeforeCompletion, files, await targetIntents(deps, record.path, target));
+            }
+            const completed = tree.filter(({ task }) => task.status === "complete").map(({ task }) => task.task.id);
+            throw finishError("WORKTREE_REBASED", `${record.targetBranch} moved, so ${record.branch} was rebased onto ${target}; its earlier verification and review do not cover the result. ` +
+                (completed.length === 0
+                    ? `Verify and review again with --base ${target}, then finish again.`
+                    : `Completed task(s) ${completed.join(", ")} cannot take new evidence: create a follow-up task in this worktree covering the rebased change, verify and review it with --base ${target}, then finish again.`));
+        }
         let plainReceipt;
         let plainReceiptWarning;
         if (options.finalProof === undefined) {
@@ -365,36 +464,7 @@ export async function finishWorktree(deps, options) {
                 plainReceiptWarning = `receipt: ${error instanceof Error ? error.message : String(error)}`;
             }
         }
-        const head = await git(deps, record.path, ["rev-parse", "HEAD"], "WORKTREE_LOG_FAILED", "Git could not read HEAD.");
-        const fastForward = (await deps.git(record.path, ["merge-base", "--is-ancestor", target, "HEAD"])).exitCode === 0;
-        if (options.finalProof !== undefined && !fastForward) {
-            throw finishError("WORKTREE_TARGET_MOVED", "The target branch moved after final review.");
-        }
-        if (!fastForward) {
-            const before = await patchHash(deps, record.path, target);
-            const rebase = await deps.git(record.path, ["rebase", "--no-autostash", target]);
-            if (rebase.exitCode !== 0) {
-                const files = (await deps.git(record.path, ["diff", "--name-only", "--diff-filter=U"])).stdout
-                    .split("\n").map((line) => line.trim()).filter(Boolean);
-                await deps.git(record.path, ["rebase", "--abort"]);
-                await deps.git(record.path, ["reset", "--hard", head]);
-                throw new WorktreeConflictError(record, target, head, files, await targetIntents(deps, record.path, target));
-            }
-            const reset = async () => { await deps.git(record.path, ["reset", "--hard", head]); };
-            if (await patchHash(deps, record.path, target) !== before) {
-                await reset();
-                throw finishError("WORKTREE_REBASE_CHANGED", `Rebasing onto ${target} changed the branch's own diff, so the review no longer covers it. The branch was reset; rebase it yourself and review the result as a new task.`);
-            }
-            if (await deps.trust.status(record.path, worktreeConfig) !== "TRUSTED") {
-                await reset();
-                throw finishError("WORKTREE_UNTRUSTED", "Re-verifying the rebased branch runs repository commands; run agent-ops trust grant in the worktree.");
-            }
-            const failed = await reverify(deps, record.path, worktreeConfig);
-            if (failed.length > 0) {
-                await reset();
-                throw finishError("WORKTREE_REVERIFY_FAILED", `After rebasing onto ${target}, verification failed: ${failed.join(", ")}. The branch was reset; fix it as a new task and finish again.`);
-            }
-        }
+        const head = headBeforeCompletion;
         const sealedIntegration = options.finalProof === undefined || record.runId === undefined
             ? null
             : await readRunIntegrationReceiptBinding(commonDir, record, { target, candidate: head });
@@ -481,7 +551,7 @@ export async function finishWorktree(deps, options) {
                 await step();
             }
             catch (error) {
-                const message = `${label}: ${error instanceof Error ? error.message : String(error)}`;
+                const message = `${label}: ${error instanceof AgentOpsError ? error.code + ": " : ""}${error instanceof Error ? error.message : String(error)}`;
                 if (options.finalProof !== undefined) {
                     throw finishError("WORKTREE_FINISH_PARTIAL", `Code merged at ${mergedHead} with receipt ${receipt?.path}; ${message}`);
                 }
@@ -508,9 +578,13 @@ export async function finishWorktree(deps, options) {
                 }
             });
         }
+        if (receiptOptions !== undefined)
+            await markRunIntegration(commonDir, record, "receipt-written", "gate");
         // Office is display-only: its room closing never fails or partially fails a finish.
         await markOfficeSessionCompleted(commonDir, record.sessionId).catch(() => undefined);
         await attempt("trust", async () => await deps.trust.revoke(record.path, worktreeConfig));
+        if (receiptOptions !== undefined)
+            await markRunIntegration(commonDir, record, "receipt-written", "trust");
         if (options.finalProof !== undefined) {
             for (const child of sessionChildren) {
                 await attempt(`child ${child.name}`, async () => {
@@ -524,7 +598,7 @@ export async function finishWorktree(deps, options) {
         await attempt("remove", async () => await removeCheckout(deps, record, options.finalProof === undefined, options.finalProof?.head));
         if (receiptOptions !== undefined)
             await markRunIntegration(commonDir, record, "cleaned", "coordinator");
-        return { record, mergedHead, rebased: !fastForward, taskIds: tree.map(({ task }) => task.task.id), warnings,
+        return { record, mergedHead, taskIds: tree.map(({ task }) => task.task.id), warnings,
             ...(receipt === undefined ? {} : { receipt: receipt.path, residualRisks: receipt.receipt.residualRisks }) };
     }));
 }

package/dist/runtime/src/parallel/manage.js

@@ -192,11 +192,8 @@ export async function resumeWorktree(deps, options) {
     const sessionId = assertSessionId(options.sessionId);
     const mainRoot = await mainCheckout(deps, options.cwd);
     const previous = await requireRecord(mainRoot, name);
-    // A base gives the service repository context, which debug resume needs.
     const tasks = deps.tasks(previous.path, previous.base);
     const attached = await tasks.status({ sessionId: previous.sessionId }).catch(() => null);
-    if (attached?.task.debug !== undefined)
-        await tasks.debugService().resume(attached.task.id, sessionId);
     if (attached !== null)
         await tasks.attach(sessionId, attached.task.id);
     const record = { ...previous, sessionId };

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

@@ -5,7 +5,7 @@ import { sha256 } from "../fs/hash.js";
 import { parseInstallManifest } from "../fs/manifest.js";
 import { AgentOpsError } from "../fs/paths.js";
 import { writeSessionMarker } from "../hooks/codex-loop.js";
-import { readPrivateFile, withPrivateFileLock, writePrivateFile } from "../security/permissions.js";
+import { cleanupWorktreeHeartbeats, readPrivateFile, withPrivateFileLock, writePrivateFile } from "../security/permissions.js";
 /**
  * One Git worktree per writing session, so parallel sessions stop sharing the
  * change surface every fingerprint is taken over. Worktrees live inside the
@@ -256,6 +256,10 @@ export async function bindSession(deps, record, mainConfig, baselineFingerprint)
         await mainGate.addRoot(record.sessionId, record.path);
 }
 export async function removeCheckout(deps, record, force, expectedHead) {
+    if (!force) {
+        const untracked = await git(deps, record.path, ["ls-files", "--others", "--exclude-standard", "-z", "--", ".claude/", ".codex/"], "WORKTREE_REMOVE_FAILED", "Git could not inspect runtime heartbeat paths.");
+        await cleanupWorktreeHeartbeats(record.path, untracked.split("\0").filter(Boolean));
+    }
     await git(deps, record.mainRoot, ["worktree", "remove", ...(force ? ["--force"] : []), record.path], "WORKTREE_REMOVE_FAILED", `Git could not remove ${record.path}.`);
     await git(deps, record.mainRoot, expectedHead === undefined
         ? ["branch", force ? "-D" : "-d", record.branch]

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

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { chmod, copyFile, lstat, mkdir, mkdtemp, realpath, rm, stat, writeFile } from "node:fs/promises";
+import { chmod, copyFile, lstat, mkdir, mkdtemp, readFile, realpath, rm, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { runVerificationCommand } from "../verify/spawn.js";
@@ -18,7 +18,7 @@ import { extractUsage, sumUsage } from "./usage.js";
  * claude both exceeded it on this repository, and a timeout costs the whole
  * review while looking like an unavailable target. Fifteen minutes was not
  * enough either: agy rounds took 450-900 s and timed out at 900 s; the stall
- * guards still stop a reviewer that goes quiet.
+ * guards still stop reviewers whose transports expose progress.
  */
 export const DEFAULT_REVIEW_TIMEOUT_MS = 1_800_000;
 /**
@@ -33,9 +33,18 @@ export const DEFAULT_STALL_IDLE_MS = 90_000;
 /**
  * agy writes nothing to stdout, stderr or its log while one generation
  * streams, so a long think is indistinguishable from a wedge. Its own logs
- * show normal generations silent for up to ~177s; 90s cut real reviews off.
+ * cannot distinguish a long generation from a wedge. Only the configured
+ * round timeout or caller cancellation may stop a silent agy review.
  */
-export const AGY_STALL_IDLE_MS = 240_000;
+export const AGY_STALL_IDLE_MS = Number.POSITIVE_INFINITY;
+/**
+ * agy logs this once its turn is over and the answer is on stdout. Some runs
+ * then never exit (the language server shutdown hangs), which would hold a
+ * finished round until the full round timeout and report it as NOT_RUN.
+ */
+const AGY_TURN_FINISHED = /Stream goroutine exited for \S+, sending completion signal/u;
+/** How long a finished agy turn may take to exit before it is stopped. */
+export const AGY_EXIT_GRACE_MS = 30_000;
 /**
  * A call the service dropped before answering. It produced no verdict, so
  * one fresh retry is not review shopping.
@@ -221,10 +230,10 @@ function watchForStall(logFile, parent, idleMs) {
             controller.abort("stalled");
         }
     };
-    const timer = setInterval(() => {
+    const timer = Number.isFinite(idleMs) ? setInterval(() => {
         void check();
-    }, pollMs);
-    timer.unref();
+    }, pollMs) : undefined;
+    timer?.unref();
     return {
         signal: parent === undefined
             ? controller.signal
@@ -232,10 +241,60 @@ function watchForStall(logFile, parent, idleMs) {
         stalled: () => stalled,
         beat,
         stop: () => {
-            clearInterval(timer);
+            if (timer !== undefined)
+                clearInterval(timer);
         }
     };
 }
+/**
+ * Stops an agy round that finished its turn but did not exit. Only the log's
+ * completion line starts the grace window, so a long silent generation is
+ * never cut off; the round timeout still caps a reviewer that never finishes.
+ */
+function watchForFinishedTurn(logFile, graceMs) {
+    const controller = new AbortController();
+    let fired = false;
+    let grace;
+    const check = async () => {
+        if (logFile === undefined || grace !== undefined)
+            return;
+        try {
+            if (!AGY_TURN_FINISHED.test(await readFile(logFile, "utf8")))
+                return;
+        }
+        catch {
+            return;
+        }
+        if (grace !== undefined)
+            return;
+        clearInterval(poll);
+        grace = setTimeout(() => {
+            fired = true;
+            controller.abort("finished-without-exit");
+        }, graceMs);
+        grace.unref();
+    };
+    const poll = setInterval(() => {
+        void check();
+    }, Math.max(20, Math.min(5_000, Math.floor(graceMs / 3))));
+    poll.unref();
+    return {
+        signal: controller.signal,
+        fired: () => fired,
+        stop: () => {
+            clearInterval(poll);
+            if (grace !== undefined)
+                clearTimeout(grace);
+        }
+    };
+}
+/** A finished agy turn that was stopped for not exiting counts as completed. */
+function finishedTurnCompletion(target, spawned, watch, graceMs, options) {
+    if (!watch.fired() || spawned.failureClass !== "aborted" || options.signal?.aborted === true)
+        return spawned;
+    options.onProgress?.(`${target}: finished its turn but did not exit within ${Math.max(1, Math.round(graceMs / 1_000))}s → stopped it and read its answer`);
+    return { ...spawned, failureClass: "none" };
+}
 function throwIfInterrupted(target, options, failureClass) {
     if (failureClass !== "aborted" && options.signal?.aborted !== true) {
         return;
@@ -505,6 +564,8 @@ async function attemptTarget(request, options) {
         const stallIdleMs = options.stallIdleMs ??
             (target === "agy" ? AGY_STALL_IDLE_MS : DEFAULT_STALL_IDLE_MS);
         const stallWatch = watchForStall(heartbeatLog, options.signal, stallIdleMs);
+        const exitGraceMs = options.agyExitGraceMs ?? AGY_EXIT_GRACE_MS;
+        const finishedWatch = watchForFinishedTurn(agyLog, exitGraceMs);
         let spawned;
         try {
             spawned = await runVerificationCommand({
@@ -524,13 +585,15 @@ async function attemptTarget(request, options) {
                 stdin: invocation.stdin,
                 env: environment,
                 replaceEnv: true,
-                signal: stallWatch.signal,
+                signal: AbortSignal.any([stallWatch.signal, finishedWatch.signal]),
                 onActivity: stallWatch.beat
             });
         }
         finally {
             stallWatch.stop();
+            finishedWatch.stop();
         }
+        spawned = finishedTurnCompletion(target, spawned, finishedWatch, exitGraceMs, options);
         // Ahead of `throwIfInterrupted`, which reads the same `aborted` failure
         // class as a user interrupt. A stall is this executor's own abort, and
         // ends one target rather than the whole review.
@@ -605,6 +668,7 @@ async function attemptTarget(request, options) {
                 if (nudge !== undefined) {
                     options.onProgress?.(`${target}: turn ended without answering${denied.length > 0 ? ` (denied ${denied.join(", ")})` : ""} → resuming the conversation once`);
                     const nudgeWatch = watchForStall(nudgeLog, options.signal, stallIdleMs);
+                    const nudgeFinished = watchForFinishedTurn(nudgeLog, exitGraceMs);
                     let second;
                     try {
                         second = await runVerificationCommand({
@@ -624,13 +688,15 @@ async function attemptTarget(request, options) {
                             stdin: nudge.stdin,
                             env: environment,
                             replaceEnv: true,
-                            signal: nudgeWatch.signal,
+                            signal: AbortSignal.any([nudgeWatch.signal, nudgeFinished.signal]),
                             onActivity: nudgeWatch.beat
                         });
                     }
                     finally {
                         nudgeWatch.stop();
+                        nudgeFinished.stop();
                     }
+                    second = finishedTurnCompletion(target, second, nudgeFinished, exitGraceMs, options);
                     usage = sumUsage(usage, extractUsage(target, second.stdout, second.stderr));
                     throwIfInterrupted(target, options, second.failureClass);
                     nudged = { log: nudgeLog, stdout: second.stdout };
@@ -710,7 +776,7 @@ export function createReviewExecutor(options) {
     const clock = options.now ?? (() => Date.now());
     return async (request) => {
         const deadlineAt = clock() +
-            Math.min(options.chainTimeoutMs ?? DEFAULT_REVIEW_CHAIN_TIMEOUT_MS, await options.remainingBudgetMs?.() ?? Infinity);
+            (options.chainTimeoutMs ?? DEFAULT_REVIEW_CHAIN_TIMEOUT_MS);
         const remainingMs = () => deadlineAt - clock();
         /**
          * The options one stage runs under: its own timeout, or what is left of

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

@@ -3,15 +3,26 @@ const MAX_PACKET_BYTES = 64 * 1024;
 export function reviewPacketData(packet) {
     const artifacts = packet.contractArtifacts?.map(({ path, digest }) => ({ path, digest }));
     let indexed = false;
-    if (packet.contractManifest !== undefined && artifacts !== undefined) {
+    let sealedSurface = false;
+    const manifest = packet.contractManifest;
+    const reference = manifest === undefined ? undefined : { path: manifest.path, digest: manifest.digest };
+    if (manifest !== undefined && Buffer.byteLength(manifest.content, "utf8") <= 512 * 1024 &&
+        sha256(manifest.content) === manifest.digest &&
+        manifest.path === ".agent-ops/tasks/review-contracts/" + manifest.digest + ".json") {
         try {
-            const manifest = JSON.parse(packet.contractManifest.content);
-            indexed = JSON.stringify(manifest?.artifacts) === JSON.stringify(artifacts);
+            const content = JSON.parse(manifest.content);
+            indexed = artifacts !== undefined && JSON.stringify(content?.artifacts) === JSON.stringify(artifacts);
+            sealedSurface = packet.surface !== undefined &&
+                JSON.stringify(safeDeep(content?.surface)) === JSON.stringify(packet.surface);
         }
-        catch { /* Legacy manifests keep inline artifact metadata. */ }
+        catch { /* Legacy manifests keep inline metadata. */ }
     }
-    return { ...packet, contractArtifacts: indexed ? undefined : artifacts,
-        contractManifest: packet.contractManifest === undefined ? undefined : { path: packet.contractManifest.path, digest: packet.contractManifest.digest } };
+    const data = { ...packet, contractArtifacts: indexed ? undefined : artifacts, contractManifest: reference };
+    // Preserve small packets; large audits remain complete in the validated snapshot manifest.
+    if (sealedSurface && reference !== undefined && Buffer.byteLength(JSON.stringify(data), "utf8") > MAX_PACKET_BYTES) {
+        return { ...data, surface: { manifest: reference, field: "surface", digest: sha256(JSON.stringify(packet.surface)) } };
+    }
+    return data;
 }
 function safe(value) {
     return safeTaskText(redactSecrets(value));

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

@@ -87,6 +87,8 @@ function taskDataBlock(invocation) {
         "BEGIN_TASK_DATA",
         JSON.stringify(data),
         ...(invocation.packet.contractManifest === undefined ? [] : ["Read the complete contract manifest at " + invocation.packet.contractManifest.path + ". Assess coverage and every revision against its immutable original goal. Review whether verifier materials actually test the requirement and load product implementation rather than replacement helpers. Review-only and UNKNOWN are not mechanical proof."]),
+        ...(invocation.packet.surface !== undefined && invocation.packet.contractManifest !== undefined ?
+            ["Read the complete surface audit and revision history, including discovery and post-block exclusions, from the manifest surface field when task data references it."] : []),
         ...(data.contractArtifacts === undefined && invocation.packet.contractArtifacts !== undefined ?
             ["The complete evidence artifact path/digest index is in that manifest; inspect supporting evidence via those paths."] : []),
         "END_TASK_DATA"

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

@@ -1,10 +1,108 @@
 import { sha256 } from "../fs/hash.js";
 import { AgentOpsError } from "../fs/paths.js";
-import { canonicalJson } from "../config/hash.js";
+import { canonicalJson, calculateConfigHash } from "../config/hash.js";
+import { readRunPolicy } from "./policy.js";
 import { join } from "node:path";
 import { readPrivateFile, writePrivateFile } from "../security/permissions.js";
 import { redactSecrets } from "../security/redact.js";
 const MAX_REASON_LENGTH = 4_096;
+const RETRY_APPROVAL = "retry-approval:";
+const AUTH_ID = /^auth-[a-f0-9]{64}$/u;
+const DENIAL_DIAGNOSTIC = "Native authorization could not be accepted; no alternate permission path is allowed.";
+/** A manual resume covers initial recovery once, never a subsequent supervisor restart. */
+export function nativeResumeTime(state, now = Date.now()) {
+    const control = state.controls.at(-1);
+    if (control?.action !== "resume" || control.actor !== "user" || control.appliedAt !== null)
+        return undefined;
+    const time = Date.parse(control.requestedAt);
+    if (!Number.isFinite(time) || !Number.isFinite(now) || time > now ||
+        state.events.some(e => e.code === "RUN_SUPERVISOR_START" && (!Number.isFinite(Date.parse(e.at)) || Date.parse(e.at) >= time)))
+        return undefined;
+    return control.requestedAt;
+}
+/** An explicit retry acknowledges a failed reviewer, never a command permission. */
+export async function approvalRetryEvents(state, requested) {
+    const fail = () => { throw error("RUN_NOT_RESUMABLE", "Approval retry requires the original, intact Codex usage-limit review failure."); };
+    if (!Array.isArray(requested) || requested.some(id => typeof id !== "string" || !AUTH_ID.test(id)) || new Set(requested).size !== requested.length)
+        fail();
+    const prior = new Set();
+    for (const control of state.controls) {
+        if (control.action !== "resume" || control.actor !== "user" || !control.reason?.startsWith(RETRY_APPROVAL))
+            continue;
+        let ids;
+        try {
+            ids = JSON.parse(control.reason.slice(RETRY_APPROVAL.length));
+        }
+        catch {
+            return fail();
+        }
+        if (!Array.isArray(ids) || ids.some(id => typeof id !== "string" || !AUTH_ID.test(id)))
+            fail();
+        for (const id of ids)
+            prior.add(id);
+    }
+    const ignored = new Set();
+    for (const id of new Set([...prior, ...requested])) {
+        const index = state.events.findIndex(e => e.id === id);
+        const event = state.events[index];
+        if (event?.type !== "control" || event.code !== "RUN_COMMAND_DENIED")
+            fail();
+        const path = join(state.commonDir, "agent-ops/runs", state.runId, "authorizations", id + ".json");
+        let ref;
+        let authorization;
+        try {
+            ref = JSON.parse(event.detail);
+            const source = await readPrivateFile(path, state.commonDir);
+            if (ref.artifact !== path || ref.result !== "denied" || ref.source !== "codex-auto-review" || source === null ||
+                Buffer.byteLength(source) > 128 * 1024 || sha256(source) !== ref.digest)
+                fail();
+            authorization = JSON.parse(source);
+        }
+        catch {
+            return fail();
+        }
+        const a = authorization;
+        if (a === null || typeof a !== "object")
+            fail();
+        const worker = state.workers.find(w => w.workerId === event.workerId);
+        if (a.runId !== state.runId || a.workerId !== event.workerId || worker === undefined || event.taskId !== worker.taskId ||
+            !Number.isSafeInteger(a.generation) || a.generation < 1 || a.generation > worker.generation ||
+            (!prior.has(id) && (a.generation !== worker.generation || a.nativeSessionId !== worker.nativeSessionId)) ||
+            a.source !== "codex-auto-review" || a.result !== "denied" || a.operation !== "command" ||
+            typeof a.reason !== "string" || !/^Automatic approval review failed: You[’']ve hit your usage limit(?:[.!]|$)/u.test(a.reason) ||
+            typeof a.command !== "string" || typeof a.resource !== "string" ||
+            !/^[a-f0-9]{64}$/u.test(a.commandDigest) || !/^[a-f0-9]{64}$/u.test(a.resourceDigest) ||
+            typeof a.authorizationId !== "string" || a.authorizationId.length === 0 || a.authorizationId.length > 256 ||
+            !(a.nativeSessionId === null || typeof a.nativeSessionId === "string") ||
+            id !== "auth-" + sha256(canonicalJson({ runId: state.runId, workerId: a.workerId, generation: a.generation,
+                nativeSessionId: a.nativeSessionId, source: a.source, id: a.authorizationId })))
+            fail();
+        // Command/resource strings were redacted when saved; their original digests cannot be recomputed.
+        let binding = state.policyBinding;
+        let matched = false;
+        for (let depth = 0; binding !== undefined && depth < 128; depth++) {
+            const policy = await readRunPolicy({ ...state, policyBinding: binding }, binding.runtimeHash, Date.now(), true);
+            if (binding.artifactDigest === a.policyArtifactDigest) {
+                matched = binding.configHash === a.policyConfigHash && binding.runtimeHash === a.runtimeHash && binding.expiresAt === a.expiresAt;
+                break;
+            }
+            if (policy?.previousDigest == null)
+                break;
+            const source = await readPrivateFile(join(state.commonDir, "agent-ops/runs", state.runId, "policies", policy.previousDigest + ".json"), state.commonDir);
+            if (source === null || sha256(source) !== policy.previousDigest)
+                fail();
+            const previous = JSON.parse(source);
+            binding = { artifactDigest: policy.previousDigest, configHash: calculateConfigHash(previous.config), runtimeHash: previous.runtimeHash, expiresAt: previous.expiresAt };
+        }
+        if (!matched)
+            fail();
+        ignored.add(id);
+        const next = state.events.slice(index + 1).find(e => e.workerId === event.workerId && e.code === "RUN_COMMAND_DENIED");
+        if (next?.type === "diagnostic" && next.taskId === null && next.detail === DENIAL_DIAGNOSTIC)
+            ignored.add(next.id);
+    }
+    return ignored;
+}
 function error(code, message) {
     return new AgentOpsError(code, message);
 }