@kylecheng3146/agent-ops 0.10.0 → 0.10.2

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/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

@@ -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,10 @@ 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;
 /**
  * A call the service dropped before answering. It produced no verdict, so
  * one fresh retry is not review shopping.
@@ -221,10 +222,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,7 +233,8 @@ function watchForStall(logFile, parent, idleMs) {
         stalled: () => stalled,
         beat,
         stop: () => {
-            clearInterval(timer);
+            if (timer !== undefined)
+                clearInterval(timer);
         }
     };
 }

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);
 }

package/dist/runtime/src/run/hosts/codex.js

@@ -41,6 +41,7 @@ export class CodexGoalHost {
     kind = "codex";
     sessions = new WeakMap();
     turns = new WeakMap();
+    activations = new WeakMap();
     now;
     constructor(options = {}) {
         this.options = options;
@@ -67,12 +68,14 @@ export class CodexGoalHost {
             throw new AgentOpsError("NATIVE_GOAL_INVALID", "Codex goal objective must be 1–4000 characters.");
         }
         const session = this.session(handle);
+        this.activations.get(handle).started = true;
         const goal = await session.request("thread/goal/set", {
             threadId: handle.threadId,
             objective,
             status: "active",
             tokenBudget
         });
+        this.assertActive(goal);
         const turn = await session.request("turn/start", {
             threadId: handle.threadId,
             input: [{ type: "text", text: objective }],
@@ -89,12 +92,14 @@ export class CodexGoalHost {
         assertContext(handle, update);
         assertProcessRunning(handle.process);
         const session = this.session(handle);
+        this.activations.get(handle).started = true;
         const goal = await session.request("thread/goal/set", {
             threadId: handle.threadId,
             objective: update.objective,
             status: "active",
             tokenBudget: update.tokenBudget ?? null
         });
+        this.assertActive(goal);
         const turnId = this.turns.get(handle);
         let turn;
         if (turnId === undefined) {
@@ -176,7 +181,23 @@ export class CodexGoalHost {
     async open(input, resume, threadId) {
         const parts = commandParts(this.options, "codex", ["app-server", "--listen", "stdio://"]);
         const process = spawnNative(parts.command, parts.args, input.cwd, input.env, this.options);
-        const channel = new JsonRpcSession(process, input.timeoutMs ?? this.options.requestTimeoutMs ?? 30_000);
+        const activation = { started: false };
+        let ownedThreadId = threadId;
+        const resumeTime = Date.parse(input.manualResumeAt ?? "");
+        const channel = new JsonRpcSession(process, input.timeoutMs ?? this.options.requestTimeoutMs ?? 30_000, message => {
+            if (message.method !== "thread/goal/updated" && message.method !== "thread/goal/cleared")
+                return true;
+            const payload = nestedRecord(message, "params");
+            const scopedThread = stringField(payload, "threadId");
+            if (ownedThreadId !== null && scopedThread !== null && scopedThread !== ownedThreadId)
+                return false;
+            const goal = nestedRecord(payload, "goal");
+            const updatedAt = goal?.updatedAt;
+            // Classify at receipt: queued snapshots may be observed after activation starts.
+            return !(resume && !activation.started && scopedThread === ownedThreadId && scopedThread !== null &&
+                ["budgetLimited", "usageLimited"].includes(statusField(goal)) && Number.isFinite(resumeTime) && this.now().getTime() >= resumeTime &&
+                typeof updatedAt === "number" && Number.isSafeInteger(updatedAt) && updatedAt >= 0 && updatedAt < Math.floor(resumeTime / 1000));
+        });
         try {
             if (process.pid !== undefined)
                 await input.registerProcess?.(process.pid);
@@ -203,6 +224,7 @@ export class CodexGoalHost {
                 });
                 nativeThreadId = resultThreadId(result);
             }
+            ownedThreadId = nativeThreadId;
             const handle = {
                 runId: input.runId,
                 workerId: input.workerId,
@@ -219,6 +241,7 @@ export class CodexGoalHost {
                 goalStatus: "unknown"
             };
             this.sessions.set(handle, channel);
+            this.activations.set(handle, activation);
             return handle;
         }
         catch (cause) {
@@ -248,6 +271,10 @@ export class CodexGoalHost {
         }
         return session;
     }
+    assertActive(result) {
+        if (statusField(nestedRecord(result, "goal") ?? result) !== "active")
+            throw new AgentOpsError("NATIVE_GOAL_NOT_ACTIVE", "Codex did not activate the goal; no turn was started or steered.");
+    }
     mapEvent(handle, message) {
         const method = typeof message.method === "string" ? message.method : "message";
         const payload = isRecord(message.params) ? message.params : message;

package/dist/runtime/src/run/hosts/protocol.js

@@ -20,15 +20,17 @@ function parseLine(line, source) {
 export class JsonRpcSession {
     child;
     requestTimeoutMs;
+    acceptNotification;
     lines;
     pending = new Map();
     events = [];
     waiters = [];
     nextId = 1;
     closed = null;
-    constructor(child, requestTimeoutMs = 30_000) {
+    constructor(child, requestTimeoutMs = 30_000, acceptNotification = () => true) {
         this.child = child;
         this.requestTimeoutMs = requestTimeoutMs;
+        this.acceptNotification = acceptNotification;
         this.lines = createInterface({ input: child.stdout });
         this.lines.on("line", (line) => this.receive(line, "stdout"));
         child.once("error", (error) => this.close(error));
@@ -135,7 +137,8 @@ export class JsonRpcSession {
             }
             return;
         }
-        this.enqueue(message);
+        if (id !== undefined || this.acceptNotification(message))
+            this.enqueue(message);
     }
     write(message) {
         this.child.stdin.write(`${JSON.stringify(message)}\n`);