@kylecheng3146/agent-ops 0.11.0 → 0.11.2

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

@@ -1,4 +1,7 @@
-import { stat } from "node:fs/promises";
+import { criteriaReviewStatus } from "./criteria-review.js";
+import { collectFollowupReceipt } from "../../../runtime/src/followup/intake.js";
+import { renderCriteriaReview } from "../../../runtime/src/review/criteria.js";
+import { rm, stat } from "node:fs/promises";
 import { recoverRunIntegrationAfterCleanup, validateRunIntegrationReceipt } from "../../../runtime/src/run/integration.js";
 import { pendingFindingPins } from "../../../runtime/src/run/ratchet.js";
 import { resolveReviewScope } from "../../../runtime/src/review/scope.js";
@@ -12,6 +15,7 @@ import { RunControlService, nativeResumeTime } from "../../../runtime/src/run/co
 import { beginPolicyTransition, markPolicyTransitionStage, completePolicyTransition, discoverPendingPolicyTransition } from "../../../runtime/src/run/policy-transition.js";
 import { readReviewReportArtifact } from "../../../runtime/src/review/attestation.js";
 import { execFile, spawn } from "node:child_process";
+import { redactSecrets } from "../../../runtime/src/security/redact.js";
 import { promisify } from "node:util";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -106,6 +110,84 @@ export function coordinatorWakeNote(state, coordinator) {
     return (coordinator.nativeSessionId === null ? "Fresh native session after wait; the earlier conversation is unavailable. " : "") +
         `Children: ${children.join("; ")}. Review deliveries, then plan follow-up workers and wait again, or request finalization.`;
 }
+export function workerInstructionLines() {
+    return ["Keep the original goal fixed. Read this repository's AGENTS.md and use its existing verifier authority.",
+        "Plan 2–5 substantive acceptance criteria. Submit a plan request before changing product files; the supervisor creates the task with the fixed goal.",
+        "Read the criteria advisory before implementation. Decide which suggestions to adopt and use task revise with reasons (including rejected advice). A revision does not automatically rerun criteria review; formal final proof remains required.",
+        "For every mechanically testable requirement use a configured acceptance runner; explicit review-only fallback requires a recorded reason and fresh goal review.",
+        "Implement, run targeted fast checks on changed code, commit and submit action=handoff so the supervisor runs full verification outside your context window. Do not poll full-suite verification in a loop. Repair failed checks and pin mechanically testable review findings into regression criteria. Never disable a mandatory policy verifier.",
+        "Only registered run workers may write. Use isolated worktrees and supervisor-issued leases; do not launch an unregistered writing subagent.",
+        "Commit product changes before revising the contract. A contract revision stops existing generations; dirty recovery preserves the checkout and blocks takeover.",
+        "Write one request atomically to .agent-ops/tasks/run-request.json; wait for matching run-response.json before another request.",
+        "Requests require requestId (unique alphanumeric or hyphen, max 64), workerId, generation and current contractHash.",
+        "Plan fields: action=plan,title,intent,criteria,surface (the EVIDENCE-SURFACE-001 audit object, same shape as task create --surface-file). Worker fields: action=worker,title,intent,criteria,dependencies (known worker task IDs; omit all acceptance baselines until dependencies are delivered),covers (parent included surface IDs this worker delivers; every included surface needs one worker).",
+        "Only the coordinator may change execution policy: submit action=policy, configFile (relative proposed JSON), expectedPolicyHash, approvals (each changed capabilityId command:<id>/runner:<id>/setup:<index>, classification=non-dangerous, reason assessing the entire fixed definition including setup/build). Commit source changes and wait until every writer is clean before requesting policy synchronization. Never use init/update/trust grant to create permanent execution authorization. Explicit native or organization denial must not be bypassed.",
+        "Worker task baselines are frozen after dependency commits enter its checkout. Handoff fields: action=handoff,sourceFiles (explicit existing source paths when unchanged). Question fields: action=question,prompt. Coordinator wait fields: action=wait, sent once every worker is planned instead of polling run status; the supervisor stops the coordinator and starts it again, in a fresh session with a child-status diagnostic, after every child is delivered, complete or blocked. Coordinator finalize fields: action=finalize.",
+        "The supervisor, after stopping writers, runs final verification, two fresh reviews and finish. A native completed goal is never final proof."];
+}
+export function workerGoalPrompt() {
+    return "Read .agent-ops/tasks/run-instructions.json and carry its immutable original goal through the evidence loop. Submit a plan if rootTaskId is null; otherwise implement and repair the assigned task. A child runs targeted fast checks, commits, and requests handoff so the supervisor executes full verification; the coordinator submits action=wait after planning its children, then requests finalization once all have delivered. Never substitute native goal completion for agent-ops evidence.";
+}
+/** Drop the old native thread for a stopped or fenced writer on a clean checkout so repair starts without context bloat. */
+export async function resetStoppedRepairThread(repository, runId, workerId, generation, cleanCheckout = true) {
+    const state = await repository.mutate(runId, current => ({
+        ...current,
+        workers: current.workers.map(w => w.workerId === workerId && w.generation === generation && ["stopped", "fenced"].includes(w.status) && cleanCheckout
+            ? { ...w, nativeSessionId: null, nativeJobId: null }
+            : w)
+    }));
+    const worker = state.workers.find(w => w.workerId === workerId);
+    if (worker === undefined)
+        throw new AgentOpsError("RUN_WORKER_NOT_FOUND", `Unknown worker ${workerId}.`);
+    return worker;
+}
+/** Check persisted requests/<sha256(requestId)>.json completion artifacts before rejecting across generations. */
+export async function reconcileWorkerRequest(options) {
+    const { repository, directory, commonDir, runId, worker, source, requestPath } = options;
+    async function rejectRequest(code) {
+        const digest = sha256(source);
+        const diagnostic = join(directory, runId, "invalid-requests", worker.workerId + "-" + worker.generation + "-" + digest + ".json");
+        if (await readPrivateFile(diagnostic, commonDir) === null) {
+            await writePrivateFile(diagnostic, canonicalJson({ code, workerId: worker.workerId, generation: worker.generation, requestDigest: digest }), commonDir);
+            await repository.appendEvent(runId, { type: "diagnostic", code, workerId: worker.workerId, taskId: worker.taskId,
+                detail: "Supervisor request is malformed or stale; a diagnostic response is available in the current checkout." });
+        }
+        await writePrivateFile(join(worker.worktree, ".agent-ops/tasks/run-response.json"), JSON.stringify({ code,
+            workerId: worker.workerId, generation: worker.generation, error: "Read current run-instructions.json and replace the malformed or stale request atomically." }), worker.worktree);
+        return { kind: "rejected", code };
+    }
+    let request;
+    try {
+        request = JSON.parse(source);
+    }
+    catch {
+        return await rejectRequest("RUN_REQUEST_INVALID");
+    }
+    if (!plain(request) || typeof request.requestId !== "string" || !/^[A-Za-z0-9-]{1,64}$/u.test(request.requestId))
+        return await rejectRequest("RUN_REQUEST_INVALID");
+    const donePath = join(directory, runId, "requests", sha256(request.requestId) + ".json");
+    const requestDigest = sha256(canonicalJson(request));
+    const completed = await readPrivateFile(donePath, commonDir);
+    if (completed !== null && request.workerId === worker.workerId) {
+        const cached = JSON.parse(completed);
+        const sameGeneration = request.generation === worker.generation;
+        if (plain(cached) && cached.requestDigest === requestDigest) {
+            if (sameGeneration)
+                await writePrivateFile(join(worker.worktree, ".agent-ops", "tasks", "run-response.json"), JSON.stringify(cached.response), worker.worktree);
+            await rm(requestPath, { force: true }).catch(() => { });
+            return { kind: "completed", sameGeneration };
+        }
+        if (sameGeneration) {
+            const conflict = { requestId: request.requestId, code: "RUN_REQUEST_ID_CONFLICT", error: "A request ID cannot be reused for different content." };
+            await writePrivateFile(join(worker.worktree, ".agent-ops", "tasks", "run-response.json"), JSON.stringify(conflict), worker.worktree);
+            await rm(requestPath, { force: true }).catch(() => { });
+            return { kind: "completed", sameGeneration: true };
+        }
+    }
+    if (request.workerId !== worker.workerId || request.generation !== worker.generation)
+        return await rejectRequest("RUN_REQUEST_STALE");
+    return { kind: "active", request, donePath, requestDigest };
+}
 /** Retain the structured child failure instead of hiding it behind recovery text. */
 export function runStepError(result, fallback) {
     const details = Array.isArray(result.errors) ? result.errors.filter(plain)
@@ -231,24 +313,15 @@ export async function superviseNativeRun(root, runId) {
                     throw new AgentOpsError("RUN_ANSWER_CHANGED", "The saved answer no longer matches its recorded digest.");
                 answers.push({ questionId: question.questionId, prompt: question.prompt, answer: answer.answer });
             }
-            const content = { runId, workerId: worker.workerId, generation: worker.generation, contractHash: current.currentContractHash,
+            const localTask = worker.taskId === null ? undefined : await new TaskService(new FileTaskStore(join(worker.worktree, ".agent-ops/tasks/state.json"), worker.worktree)).status({ taskId: worker.taskId }).catch(() => undefined);
+            const criteriaAdvice = localTask === undefined ? null : await criteriaReviewStatus(worker.worktree, localTask.task);
+            const content = { criteriaAdvisory: criteriaAdvice === null ? null : renderCriteriaReview(criteriaAdvice), runId, workerId: worker.workerId, generation: worker.generation, contractHash: current.currentContractHash,
                 originalGoal: current.goal, answers, rootTaskId: current.rootTaskId, taskId: worker.taskId, cli, ownerSessionId: worker.ownerSessionId,
                 policyConfigHash: current.policyBinding?.configHash,
-                instructions: ["Keep the original goal fixed. Read this repository's AGENTS.md and use its existing verifier authority.",
-                    "Plan 2–5 substantive acceptance criteria. Submit a plan request before changing product files; the supervisor creates the task with the fixed goal.",
-                    "For every mechanically testable requirement use a configured acceptance runner; explicit review-only fallback requires a recorded reason and fresh goal review.",
-                    "Implement, commit and verify. Repair failed checks and pin mechanically testable review findings into regression criteria. Never disable a mandatory policy verifier.",
-                    "Only registered run workers may write. Use isolated worktrees and supervisor-issued leases; do not launch an unregistered writing subagent.",
-                    "Commit product changes before revising the contract. A contract revision stops existing generations; dirty recovery preserves the checkout and blocks takeover.",
-                    "Write one request atomically to .agent-ops/tasks/run-request.json; wait for matching run-response.json before another request.",
-                    "Requests require requestId (unique alphanumeric or hyphen, max 64), workerId, generation and current contractHash.",
-                    "Plan fields: action=plan,title,intent,criteria,surface (the EVIDENCE-SURFACE-001 audit object, same shape as task create --surface-file). Worker fields: action=worker,title,intent,criteria,dependencies (known worker task IDs; omit all acceptance baselines until dependencies are delivered),covers (parent included surface IDs this worker delivers; every included surface needs one worker).",
-                    "Only the coordinator may change execution policy: submit action=policy, configFile (relative proposed JSON), expectedPolicyHash, approvals (each changed capabilityId command:<id>/runner:<id>/setup:<index>, classification=non-dangerous, reason assessing the entire fixed definition including setup/build). Commit source changes and wait until every writer is clean before requesting policy synchronization. Never use init/update/trust grant to create permanent execution authorization. Explicit native or organization denial must not be bypassed.",
-                    "Worker task baselines are frozen after dependency commits enter its checkout. Handoff fields: action=handoff,sourceFiles (explicit existing source paths when unchanged). Question fields: action=question,prompt. Coordinator wait fields: action=wait, sent once every worker is planned instead of polling run status; the supervisor stops the coordinator and starts it again, in a fresh session with a child-status diagnostic, after every child is delivered, complete or blocked. Coordinator finalize fields: action=finalize.",
-                    "The supervisor, after stopping writers, runs final verification, two fresh reviews and finish. A native completed goal is never final proof."], diagnostic };
+                instructions: workerInstructionLines(), diagnostic };
             const path = join(worker.worktree, ".agent-ops", "tasks", "run-instructions.json");
             await writePrivateFile(path, JSON.stringify(content, null, 2), worker.worktree);
-            return "Read .agent-ops/tasks/run-instructions.json and carry its immutable original goal through the evidence loop. Submit a plan if rootTaskId is null; otherwise implement and repair the assigned task. A child requests handoff after local green; the coordinator submits action=wait after planning its children, then requests finalization once all have delivered. Never substitute native goal completion for agent-ops evidence.";
+            return workerGoalPrompt();
         }
         async function start(worker, diagnostic, resumeAt) {
             if (await discoverPendingPolicyTransition(repository, runId) !== null)
@@ -341,7 +414,8 @@ export async function superviseNativeRun(root, runId) {
                     });
                     await service.create({ title: plan.title, intent: plan.intent, criteria: plan.criteria, goal: current.goal,
                         sessionId: ownerSessionId, policyConfigHash: calculateConfigHash(config), ...(plan.covers === undefined ? {} : { surface: { covers: plan.covers } }) });
-                    await start((await repository.read(runId)).workers.find(w => w.workerId === registration.workerId));
+                    const advisory = await criteriaStep(workerRoot, node.taskId);
+                    await start((await repository.read(runId)).workers.find(w => w.workerId === registration.workerId), JSON.stringify(advisory));
                 }
                 catch (cause) {
                     const latest = (await repository.read(runId));
@@ -385,97 +459,10 @@ export async function superviseNativeRun(root, runId) {
             return result.data.receipt;
         }
         async function step(cwd, args, saved) {
-            const remaining = remainingRunTimeMs(saved);
-            if (remaining <= 0)
-                throw new AgentOpsError("RUN_BUDGET_EXHAUSTED", "No active time remains for final proof.");
-            return await new Promise((resolve, reject) => {
-                const env = { ...process.env, AGENT_OPS_HOST: saved.host,
-                    AGENT_OPS_SESSION_ID: saved.workers.find(worker => worker.worktree === cwd)?.ownerSessionId ?? saved.ownerSessionId,
-                    AGENT_OPS_RUN_ID: saved.runId,
-                    AGENT_OPS_WORKER_ID: saved.workers.find(worker => worker.worktree === cwd)?.workerId ?? saved.coordinatorId,
-                    AGENT_OPS_WORKER_GENERATION: String(saved.workers.find(worker => worker.worktree === cwd)?.generation ?? saved.workers.find(worker => worker.workerId === saved.coordinatorId)?.generation) };
-                delete env.CODEX_THREAD_ID;
-                delete env.AGENT_OPS_AGENT_ID;
-                delete env.CODEX_SANDBOX_NETWORK_DISABLED;
-                const child = spawn(process.execPath, [fileURLToPath(new URL("./run-step-entry.js", import.meta.url)), cli, ...args, "--json"], { cwd, env, detached: process.platform !== "win32", stdio: ["pipe", "pipe", "pipe"] });
-                let output = "";
-                let closed = false;
-                let escalation;
-                const terminate = () => {
-                    if (child.pid === undefined || escalation !== undefined)
-                        return;
-                    try {
-                        process.kill(process.platform === "win32" ? child.pid : -child.pid, "SIGTERM");
-                    }
-                    catch { }
-                    escalation = setTimeout(() => {
-                        if (!closed)
-                            try {
-                                process.kill(process.platform === "win32" ? child.pid : -child.pid, "SIGKILL");
-                            }
-                            catch { }
-                    }, 3000);
-                };
-                const timeout = Number.isFinite(remaining) ? setTimeout(terminate, remaining) : undefined;
-                const registration = (async () => {
-                    const identity = child.pid === undefined ? null : await nativeProcessIdentity(child.pid);
-                    if (identity === null || closed) {
-                        terminate();
-                        return;
-                    }
-                    await repository.mutate(runId, current => {
-                        if (current.status !== "active" || current.disableRestart) {
-                            terminate();
-                            throw new AgentOpsError("RUN_PROOF_STOPPED", "Stop raced final proof registration.");
-                        }
-                        return { ...current, proofProcess: { processId: child.pid, processIdentity: identity } };
-                    });
-                    child.stdin.end("start\n");
-                })();
-                child.stdin.on("error", terminate);
-                void registration.catch(() => terminate());
-                let checking = false;
-                const control = setInterval(() => {
-                    if (checking)
-                        return;
-                    checking = true;
-                    void repository.read(runId).then(current => {
-                        if (current === null || current.disableRestart || current.status !== "active")
-                            terminate();
-                    }).catch(terminate).finally(() => { checking = false; });
-                }, 250);
-                child.stdout.on("data", chunk => { output += chunk.toString(); if (Buffer.byteLength(output) > 4 * 1024 * 1024)
-                    terminate(); });
-                child.stderr.resume();
-                child.once("error", cause => { closed = true; clearTimeout(timeout); clearInterval(control); reject(cause); });
-                child.once("close", async () => {
-                    closed = true;
-                    clearTimeout(timeout);
-                    clearTimeout(escalation);
-                    clearInterval(control);
-                    try {
-                        await registration;
-                        await repository.mutate(runId, current => ({ ...current,
-                            ...(current.proofProcess?.processId === child.pid ? { proofProcess: null } : {}) }));
-                        const result = JSON.parse(output);
-                        if (!plain(result) || !["ok", "error"].includes(String(result.status)) || typeof result.code !== "string")
-                            throw new Error();
-                        const coordinatorRoot = saved.workers[0]?.worktree;
-                        if (result.status === "error" && coordinatorRoot != null)
-                            await recordSavedReviewRunUsage(repository, runId, coordinatorRoot);
-                        if (plain(result.data) && plain(result.data.result) && typeof result.data.result.sourceFingerprint === "string" &&
-                            typeof result.data.result.taskId === "string") {
-                            const artifact = await readReviewReportArtifact(cwd, result.data.result.sourceFingerprint, result.data.result.taskId);
-                            if (artifact !== null)
-                                await recordReviewRunUsage(repository, runId, artifact);
-                        }
-                        resolve(result);
-                    }
-                    catch {
-                        reject(new AgentOpsError("RUN_FINAL_PROOF_INTERRUPTED", "Final gate did not return a complete result; inspect target and receipt before retrying."));
-                    }
-                });
-            });
+            return await runControlledStep(repository, cli, cwd, args, saved);
+        }
+        async function criteriaStep(cwd, taskId) {
+            return await runCriteriaStep(repository, runId, cwd, taskId, step);
         }
         async function stopAll(reason, closeBudget = true) {
             const current = (await repository.read(runId));
@@ -640,8 +627,11 @@ export async function superviseNativeRun(root, runId) {
                 return;
             }
             const latest = result.state.workers.find(w => w.workerId === worker.workerId);
-            if (["fenced", "stopped"].includes(latest.status))
-                await start(latest, message);
+            if (["fenced", "stopped"].includes(latest.status)) {
+                const clean = latest.worktree !== null && (await collectChangeSurface(gitRunner(latest.worktree))).paths.length === 0;
+                const reset = await resetStoppedRepairThread(repository, runId, latest.workerId, latest.generation, clean);
+                await start(reset, message);
+            }
             else
                 await supervisor.sendRepair(runId, worker.workerId, worker.generation, message);
         }
@@ -675,6 +665,17 @@ export async function superviseNativeRun(root, runId) {
                 contractRevision: current.contractRevision + (current.currentContractHash === finalContract ? 0 : 1) }));
             await supervisor.finalize(runId, { targetCommit: receipt.candidateHead, candidateCommit: receipt.candidateHead,
                 verificationPass: true, reviewPass: true, taskStateComplete: true, receiptWritten: true, receiptDigest: sha256(source) });
+            try {
+                const followup = await collectFollowupReceipt({ git: deps.git, mainRoot: root, commonDir,
+                    path, config: await deps.loadConfig(root), loadConfig: async () => await deps.loadConfig(root) });
+                for (const warning of followup.warnings)
+                    await repository.appendEvent(runId, { type: "diagnostic",
+                        code: "FOLLOWUP_RECONCILIATION_PENDING", workerId: null, taskId: null, detail: warning });
+            }
+            catch {
+                await repository.appendEvent(runId, { type: "diagnostic", code: "FOLLOWUP_RECONCILIATION_PENDING",
+                    workerId: null, taskId: null, detail: "Completion remains valid; followup reconciliation needs retry." }).catch(() => { });
+            }
             try {
                 await stopAll("stop");
                 await launchd.disableRestart(runDescriptor(current), "verified final integration completed");
@@ -809,47 +810,18 @@ export async function superviseNativeRun(root, runId) {
                             await repair(worker, "RUN_NATIVE_COMPLETION_UNPROVEN", "Native completion has no agent-ops delivery or final receipt. Read run-instructions.json, complete the evidence loop and submit handoff or finalize.");
                         continue;
                     }
-                    async function rejectRequest(code) {
-                        const digest = sha256(source);
-                        const diagnostic = join(directory, runId, "invalid-requests", worker.workerId + "-" + worker.generation + "-" + digest + ".json");
-                        if (await readPrivateFile(diagnostic, commonDir) === null) {
-                            await writePrivateFile(diagnostic, canonicalJson({ code, workerId: worker.workerId, generation: worker.generation, requestDigest: digest }), commonDir);
-                            await repository.appendEvent(runId, { type: "diagnostic", code, workerId: worker.workerId, taskId: worker.taskId,
-                                detail: "Supervisor request is malformed or stale; a diagnostic response is available in the current checkout." });
-                        }
-                        await writePrivateFile(join(worker.worktree, ".agent-ops/tasks/run-response.json"), JSON.stringify({ code,
-                            workerId: worker.workerId, generation: worker.generation, error: "Read current run-instructions.json and replace the malformed or stale request atomically." }), worker.worktree);
+                    const reconciled = await reconcileWorkerRequest({ repository, directory, commonDir, runId, worker, source, requestPath });
+                    if (reconciled.kind === "rejected") {
                         if (observation.nativeGoalState === "complete")
-                            await repair(worker, code, "A malformed or stale request cannot establish completion. Read current run-instructions.json and replace run-request.json atomically.");
-                    }
-                    let request;
-                    try {
-                        request = JSON.parse(source);
-                    }
-                    catch {
-                        await rejectRequest("RUN_REQUEST_INVALID");
+                            await repair(worker, reconciled.code, "A malformed or stale request cannot establish completion. Read current run-instructions.json and replace run-request.json atomically.");
                         continue;
                     }
-                    if (!plain(request) || typeof request.requestId !== "string" || !/^[A-Za-z0-9-]{1,64}$/u.test(request.requestId)) {
-                        await rejectRequest("RUN_REQUEST_INVALID");
-                        continue;
-                    }
-                    if (request.workerId !== worker.workerId || request.generation !== worker.generation) {
-                        await rejectRequest("RUN_REQUEST_STALE");
-                        continue;
-                    }
-                    const donePath = join(directory, runId, "requests", sha256(request.requestId) + ".json");
-                    const requestDigest = sha256(canonicalJson(request));
-                    const completed = await readPrivateFile(donePath, commonDir);
-                    if (completed !== null) {
-                        const cached = JSON.parse(completed);
-                        const response = plain(cached) && cached.requestDigest === requestDigest ? cached.response :
-                            { requestId: request.requestId, code: "RUN_REQUEST_ID_CONFLICT", error: "A request ID cannot be reused for different content." };
-                        await writePrivateFile(join(worker.worktree, ".agent-ops", "tasks", "run-response.json"), JSON.stringify(response), worker.worktree);
-                        if (observation.nativeGoalState === "complete")
+                    if (reconciled.kind === "completed") {
+                        if (reconciled.sameGeneration && observation.nativeGoalState === "complete")
                             await repair(worker, "RUN_NATIVE_COMPLETION_UNPROVEN", "The previous request response is available, but current delivery or final proof is still missing. Continue the assigned goal and submit a new request.");
                         continue;
                     }
+                    const { request, donePath, requestDigest } = reconciled;
                     const current = (await repository.read(runId));
                     let response;
                     try {
@@ -894,7 +866,8 @@ export async function superviseNativeRun(root, runId) {
                             await repository.mutate(runId, saved => ({ ...saved, rootTaskId: task.task.id, currentContractHash: treeContractHash([task.task]),
                                 tasks: saved.tasks.map(node => node.taskId === worker.taskId ? { ...node, taskId: task.task.id } : node),
                                 workers: saved.workers.map(w => w.workerId === worker.workerId ? { ...w, taskId: task.task.id } : w) }));
-                            response = { requestId: request.requestId, code: "RUN_PLAN_CREATED", task: task.task, contractHash: treeContractHash([task.task]) };
+                            const advisory = await criteriaStep(worker.worktree, task.task.id);
+                            response = { advisory, requestId: request.requestId, code: "RUN_PLAN_CREATED", task: task.task, contractHash: treeContractHash([task.task]) };
                             await recordRunPhase(repository, runId, worker.workerId, "implementing", { taskId: task.task.id, update: { passed: 0, total: task.task.criteria.length } });
                             await instructions((await repository.read(runId)).workers.find(w => w.workerId === worker.workerId));
                         }
@@ -1026,6 +999,7 @@ export async function superviseNativeRun(root, runId) {
                         }
                     }
                     await writePrivateFile(donePath, JSON.stringify({ requestDigest, response }), commonDir);
+                    await rm(requestPath, { force: true }).catch(() => { });
                     const after = (await repository.read(runId));
                     if (after.status === "complete") {
                         await writePrivateFile(join(directory, runId, "final-response.json"), JSON.stringify(response), commonDir);
@@ -1056,3 +1030,167 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
         throw new AgentOpsError("RUN_SUPERVISOR_ARGUMENTS", "Supervisor requires canonical repository root and run ID.");
     await superviseNativeRun(process.argv[2], process.argv[3]);
 }
+export async function runControlledStep(repository, cli, cwd, args, saved) {
+    const runId = saved.runId;
+    const criteria = args[0] === "review" && args.includes("--criteria");
+    const remaining = criteria ? Infinity : remainingRunTimeMs(saved);
+    if (remaining <= 0)
+        throw new AgentOpsError("RUN_BUDGET_EXHAUSTED", "No active time remains for final proof.");
+    return await new Promise((resolve, reject) => {
+        const env = { ...process.env, AGENT_OPS_HOST: saved.host,
+            AGENT_OPS_SESSION_ID: saved.workers.find(worker => worker.worktree === cwd)?.ownerSessionId ?? saved.ownerSessionId,
+            AGENT_OPS_RUN_ID: saved.runId,
+            AGENT_OPS_WORKER_ID: saved.workers.find(worker => worker.worktree === cwd)?.workerId ?? saved.coordinatorId,
+            AGENT_OPS_WORKER_GENERATION: String(saved.workers.find(worker => worker.worktree === cwd)?.generation ?? saved.workers.find(worker => worker.workerId === saved.coordinatorId)?.generation) };
+        delete env.CODEX_THREAD_ID;
+        delete env.AGENT_OPS_AGENT_ID;
+        delete env.CODEX_SANDBOX_NETWORK_DISABLED;
+        const child = spawn(process.execPath, [fileURLToPath(new URL("./run-step-entry.js", import.meta.url)), cli, ...args, "--json"], { cwd, env, detached: process.platform !== "win32", stdio: ["pipe", "pipe", "pipe"] });
+        let output = Buffer.alloc(0), diagnostic = Buffer.alloc(0);
+        let outputOverflow = false;
+        let spawnError;
+        let closed = false;
+        let escalation;
+        const terminate = () => {
+            if (child.pid === undefined || escalation !== undefined)
+                return;
+            try {
+                process.kill(process.platform === "win32" ? child.pid : -child.pid, "SIGTERM");
+            }
+            catch { }
+            escalation = setTimeout(() => {
+                if (!closed)
+                    try {
+                        process.kill(process.platform === "win32" ? child.pid : -child.pid, "SIGKILL");
+                    }
+                    catch { }
+            }, 3000);
+        };
+        const timeout = Number.isFinite(remaining) ? setTimeout(terminate, remaining) : undefined;
+        const registration = (async () => {
+            const identity = child.pid === undefined ? null : await nativeProcessIdentity(child.pid);
+            if (identity === null || closed) {
+                terminate();
+                throw new Error("Controlled process identity unavailable.");
+            }
+            await repository.mutate(runId, current => {
+                if (current.status !== "active" || current.disableRestart) {
+                    terminate();
+                    throw new AgentOpsError("RUN_PROOF_STOPPED", "Stop raced final proof registration.");
+                }
+                if (criteria && current.proofProcess != null) {
+                    terminate();
+                    throw new AgentOpsError("CRITERIA_REVIEW_PROCESS_BUSY", "Another controlled process is already registered.");
+                }
+                return { ...current, proofProcess: { processId: child.pid, processIdentity: identity } };
+            });
+            child.stdin.end("start\n");
+        })();
+        child.stdin.on("error", terminate);
+        void registration.catch(() => terminate());
+        let checking = false;
+        const control = setInterval(() => {
+            if (checking)
+                return;
+            checking = true;
+            void repository.read(runId).then(current => {
+                if (current === null || current.disableRestart || current.status !== "active")
+                    terminate();
+            }).catch(terminate).finally(() => { checking = false; });
+        }, 250);
+        child.stdout.on("data", (chunk) => {
+            const room = 4 * 1024 * 1024 - output.length;
+            if (room > 0)
+                output = Buffer.concat([output, chunk.subarray(0, room)]);
+            if (chunk.length > room) {
+                outputOverflow = true;
+                terminate();
+            }
+        });
+        child.stderr.on("data", (chunk) => {
+            const room = 64 * 1024 - diagnostic.length;
+            if (room > 0)
+                diagnostic = Buffer.concat([diagnostic, chunk.subarray(0, room)]);
+        });
+        child.once("error", cause => { spawnError = cause; terminate(); });
+        child.once("close", async (exitCode, signal) => {
+            closed = true;
+            clearTimeout(timeout);
+            clearTimeout(escalation);
+            clearInterval(control);
+            let stage = "registration";
+            try {
+                // Cleanup ownership even when registration or the subprocess failed.
+                let registrationError;
+                try {
+                    await registration;
+                }
+                catch (cause) {
+                    registrationError = cause;
+                }
+                stage = "cleanup";
+                await repository.mutate(runId, current => ({ ...current,
+                    ...(current.proofProcess?.processId === child.pid ? { proofProcess: null } : {}) }));
+                stage = "registration";
+                if (registrationError !== undefined)
+                    throw registrationError;
+                stage = "process";
+                if (spawnError !== undefined)
+                    throw spawnError;
+                if (signal !== null || outputOverflow)
+                    throw new Error(outputOverflow ? "Result exceeded 4 MiB." : "Controlled process was signaled.");
+                stage = "result";
+                const result = JSON.parse(output.toString("utf8"));
+                if (!plain(result) || !["ok", "error"].includes(String(result.status)) || typeof result.code !== "string")
+                    throw new Error("Invalid result envelope.");
+                if (result.status === "ok" && exitCode !== 0)
+                    throw new Error("Successful envelope with unsuccessful process exit.");
+                stage = "usage";
+                const coordinatorRoot = saved.workers[0]?.worktree;
+                if (!criteria && result.status === "error" && coordinatorRoot != null)
+                    await recordSavedReviewRunUsage(repository, runId, coordinatorRoot);
+                if (plain(result.data) && plain(result.data.result) && typeof result.data.result.sourceFingerprint === "string" &&
+                    typeof result.data.result.taskId === "string") {
+                    const artifact = await readReviewReportArtifact(cwd, result.data.result.sourceFingerprint, result.data.result.taskId);
+                    if (artifact !== null)
+                        await recordReviewRunUsage(repository, runId, artifact);
+                }
+                resolve(result);
+            }
+            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,
+                    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));
+            }
+        });
+    });
+}
+export async function runCriteriaStep(repository, runId, cwd, taskId, step) {
+    const current = (await repository.read(runId));
+    if (current.status !== "active" || current.disableRestart)
+        throw new AgentOpsError("RUN_CRITERIA_STOPPED", "Run stopped before criteria review.");
+    try {
+        if (current.proofProcess != null)
+            throw new Error("Controlled process busy");
+        const result = await step(cwd, ["review", "--criteria", "--task", taskId, "--yes"], current);
+        const latest = (await repository.read(runId));
+        if (latest.status !== "active" || latest.disableRestart || result.code === "CRITERIA_REVIEW_CANCELLED")
+            throw new AgentOpsError("RUN_CRITERIA_STOPPED", "Criteria review cancelled; do not start implementation.");
+        if (result.status === "ok")
+            return result.data;
+    }
+    catch (cause) {
+        const latest = await repository.read(runId);
+        if (latest === null || latest.status !== "active" || latest.disableRestart ||
+            cause instanceof AgentOpsError && cause.code === "RUN_CRITERIA_STOPPED")
+            throw cause;
+    }
+    await repository.appendEvent(runId, { type: "diagnostic", code: "CRITERIA_REVIEW_NOT_RUN", workerId: null, taskId,
+        detail: "Pre-edit advisory unavailable; final evidence gates still apply." }).catch(() => undefined);
+    return { code: "CRITERIA_REVIEW_NOT_RUN", text: "Criteria advisory NOT_RUN (process unavailable); final evidence gates still apply." };
+}

package/dist/runtime/src/followup/intake.js

@@ -0,0 +1,75 @@
+import { lstat, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { AgentOpsError } from "../fs/paths.js";
+import { readDeliveredReceipt } from "./receipt.js";
+import { FileFollowupStore, followupIdentity } from "./store.js";
+import { reconcileFollowupRepairs } from "./process.js";
+function warning(error) {
+    const code = error instanceof AgentOpsError && /^[A-Z0-9_]{1,80}$/u.test(error.code) ? error.code : "FOLLOWUP_COLLECTION_FAILED";
+    return `followup: ${code}; original completion is unchanged. Retry with followup import.`;
+}
+/** Metadata-only and fail-open: collection cannot invalidate a successful finish. */
+export async function collectFollowupReceipt(options) {
+    try {
+        const { receipt, digest, reviews } = await readDeliveredReceipt(options);
+        const pending = [];
+        for (const review of reviews)
+            for (const round of ["primary", "adversarial"]) {
+                const report = round === "primary" ? review.artifact.report : review.artifact.adversarial.report;
+                const provenance = { receiptPath: options.path, receiptDigest: digest, receiptSchemaVersion: receipt.schemaVersion,
+                    candidateHead: receipt.candidateHead, targetCommit: receipt.targetCommit, sourceFingerprint: receipt.sourceFingerprint,
+                    taskId: review.taskId, reportDigest: review.reportDigest, round, provenanceLimit: review.provenanceLimit };
+                const add = (sourceKind, original, index) => {
+                    const source = { ...provenance, sourceKind, index };
+                    pending.push({ id: followupIdentity(source), kind: sourceKind === "finding" ? "candidate" : "observation",
+                        original, provenance: source, disposition: "pending", history: [{ at: new Date().toISOString(), action: "collected" }] });
+                };
+                report.findings.forEach((finding, index) => { if (!finding.blocking)
+                    add("finding", finding, index); });
+                report.residualRisks.forEach((risk, index) => add("residual-risk", risk, index));
+            }
+        const collected = await new FileFollowupStore(options.commonDir).mutate(items => {
+            const known = new Set(items.map(item => item.id));
+            const added = pending.filter(item => !known.has(item.id));
+            items.push(...added);
+            return { added: added.length, candidates: added.filter(item => item.kind === "candidate").length,
+                observations: added.filter(item => item.kind === "observation").length, warnings: [] };
+        });
+        const warnings = options.config === undefined ? [] : await reconcileFollowupRepairs({ ...options, config: options.config });
+        return { ...collected, warnings };
+    }
+    catch (error) {
+        return { added: 0, candidates: 0, observations: 0, warnings: [warning(error)] };
+    }
+}
+/** Historical import never launches assessment, repair, models or provider calls. */
+export async function reconcileFollowups(options) {
+    const result = { added: 0, candidates: 0, observations: 0, warnings: [] };
+    try {
+        const directory = join(options.commonDir, "agent-ops", "receipts");
+        // Checking through the private reader rejects symlinked ancestors before enumeration.
+        await new FileFollowupStore(options.commonDir).read();
+        const status = await lstat(directory);
+        if (!status.isDirectory() || status.isSymbolicLink())
+            throw new AgentOpsError("PRIVATE_STATE_PATH_INVALID", "Receipt directory is unsafe.");
+        const names = (await readdir(directory)).filter(name => /^[a-f0-9]{64}-[a-f0-9]{40,64}\.json$/u.test(name)).sort();
+        const { config: _config, loadConfig: _loadConfig, ...source } = options;
+        for (const name of names) {
+            const collected = await collectFollowupReceipt({ ...source, path: join(directory, name) });
+            result.added += collected.added;
+            result.candidates += collected.candidates;
+            result.observations += collected.observations;
+            // Repeated malformed sources cannot flood normal CLI diagnostics.
+            for (const item of collected.warnings)
+                if (!result.warnings.includes(item) && result.warnings.length < 8)
+                    result.warnings.push(item);
+        }
+        if (options.config !== undefined)
+            result.warnings.push(...await reconcileFollowupRepairs({ ...options, config: options.config }));
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            result.warnings.push(warning(error));
+    }
+    return result;
+}