@kylecheng3146/agent-ops 0.10.2 → 0.11.1

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

@@ -1,3 +1,5 @@
+import { criteriaReviewStatus } from "./criteria-review.js";
+import { renderCriteriaReview } from "../../../runtime/src/review/criteria.js";
 import { stat } from "node:fs/promises";
 import { recoverRunIntegrationAfterCleanup, validateRunIntegrationReceipt } from "../../../runtime/src/run/integration.js";
 import { pendingFindingPins } from "../../../runtime/src/run/ratchet.js";
@@ -43,25 +45,69 @@ const exec = promisify(execFile);
 const plain = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const active = (worker) => ["assigned", "starting", "running", "idle", "handing-off"].includes(worker.status);
 const cli = fileURLToPath(new URL("./bin.js", import.meta.url));
-/** Release the sole native slot only after confirmed coordinator death. */
+const pendingChildren = (state) => state.tasks.filter(task => task.taskId !== state.rootTaskId && !["delivered", "complete", "blocked"].includes(task.status));
+// Only a coordinator wait stops the coordinator with a handoff reason; it never delivers itself.
+const yielded = (worker) => worker.status === "stopped" && worker.stopIntent?.reason === "handoff";
+/**
+ * Stop a coordinator that asked to wait for its children, instead of letting it
+ * poll run status. Its native thread is dropped so the wake starts fresh.
+ */
+export async function waitForChildren(repository, supervisor, runId, workerId, generation) {
+    const current = await repository.read(runId);
+    if (current === null || workerId !== current.coordinatorId)
+        throw new AgentOpsError("RUN_COORDINATOR_REQUIRED", "Only the coordinator can wait for child deliveries.");
+    if (current.rootTaskId === null || pendingChildren(current).length === 0)
+        throw new AgentOpsError("RUN_WAIT_NOTHING_PENDING", "Wait requires at least one planned child that has not finished.");
+    await yieldCoordinator(repository, supervisor, runId, workerId, generation, current.rootTaskId);
+}
+async function yieldCoordinator(repository, supervisor, runId, workerId, generation, taskId) {
+    await supervisor.stopWorker(runId, workerId, generation, "handoff");
+    await repository.mutate(runId, saved => ({ ...saved, workers: saved.workers.map(w => w.workerId === workerId && w.generation === generation && w.status === "stopped" ? { ...w, nativeSessionId: null, nativeJobId: null } : w) }));
+    await repository.appendEvent(runId, { type: "diagnostic", code: "RUN_COORDINATOR_YIELDED", workerId, taskId,
+        detail: "Coordinator waited; process death confirmed and its slot released until every child finishes." });
+}
+/** Finish an unconfirmed wait, then return the stopped coordinator once every child has finished. */
 export async function prepareSerialSchedule(repository, supervisor, runId) {
     const current = await repository.read(runId);
-    if (current === null || current.jobs !== 1 || current.rootTaskId === null || current.status !== "active" || current.disableRestart || current.awaitingResume)
+    if (current === null || current.rootTaskId === null || current.status !== "active" || current.disableRestart || current.awaitingResume)
         return null;
-    const children = current.tasks.filter(task => task.taskId !== current.rootTaskId);
     const coordinator = current.workers.find(worker => worker.workerId === current.coordinatorId);
-    if (children.length === 0 || coordinator === undefined)
-        return null;
-    if (children.some(task => !["delivered", "complete", "blocked"].includes(task.status))) {
-        if (active(coordinator)) {
-            await supervisor.stopWorker(runId, coordinator.workerId, coordinator.generation, "handoff");
-            await repository.appendEvent(runId, { type: "diagnostic", code: "RUN_COORDINATOR_YIELDED", workerId: coordinator.workerId,
-                taskId: coordinator.taskId, detail: "Coordinator process death confirmed before assigning the sole slot to children." });
+    if (coordinator?.status === "handing-off" && coordinator.stopIntent?.reason === "handoff") {
+        try {
+            await yieldCoordinator(repository, supervisor, runId, coordinator.workerId, coordinator.generation, current.rootTaskId);
+        }
+        catch (cause) {
+            // The slot stays held until death is confirmed; retry on the next supervisor pass.
+            if (cause instanceof AgentOpsError && ["RUN_HANDOFF_PROCESS_ALIVE", "RUN_WRITER_STILL_ALIVE"].includes(cause.code))
+                return null;
+            throw cause;
         }
         return null;
     }
+    if (coordinator === undefined || current.tasks.every(task => task.taskId === current.rootTaskId) || pendingChildren(current).length > 0)
+        return null;
     return coordinator.status === "stopped" && !current.workers.some(worker => worker.workerId !== coordinator.workerId && active(worker)) ? coordinator : null;
 }
+/** Recovery leaves a waiting coordinator stopped, and with jobs=1 starts only a child whose dependencies are delivered. */
+export function recoverySkips(state, worker) {
+    if (state.rootTaskId === null)
+        return false;
+    const pending = pendingChildren(state);
+    if (pending.length === 0)
+        return false;
+    if (worker.workerId === state.coordinatorId)
+        return yielded(worker);
+    const node = pending.find(task => task.taskId === worker.taskId);
+    return state.jobs === 1 && (node === undefined ||
+        node.dependencies.some(id => !state.tasks.some(task => task.taskId === id && ["delivered", "complete"].includes(task.status))));
+}
+/** Child status handed to a woken coordinator, which may have lost its conversation. */
+export function coordinatorWakeNote(state, coordinator) {
+    const children = state.tasks.filter(task => task.taskId !== state.rootTaskId)
+        .map(task => `${task.taskId} ${task.status}${task.sourceCommit === null ? "" : " " + task.sourceCommit}`);
+    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.`;
+}
 /** 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)
@@ -187,11 +233,14 @@ 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.",
+                    "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, 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.",
@@ -200,11 +249,11 @@ export async function superviseNativeRun(root, runId) {
                     "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 finalize fields: action=finalize.",
+                    "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 };
             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 waits for all child deliveries, then requests finalization. Never substitute native goal completion for agent-ops evidence.";
+            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.";
         }
         async function start(worker, diagnostic, resumeAt) {
             if (await discoverPendingPolicyTransition(repository, runId) !== null)
@@ -243,7 +292,7 @@ export async function superviseNativeRun(root, runId) {
         async function schedule() {
             const coordinator = await prepareSerialSchedule(repository, supervisor, runId);
             if (coordinator !== null) {
-                await start(coordinator);
+                await start(coordinator, coordinatorWakeNote((await repository.read(runId)), coordinator));
                 return;
             }
             const current = (await repository.read(runId));
@@ -297,7 +346,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));
@@ -341,97 +391,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));
@@ -682,18 +645,13 @@ export async function superviseNativeRun(root, runId) {
                 await synchronizePolicy();
             state = (await repository.read(runId));
             for (const worker of state.workers.filter(w => active(w) || w.status === "stopped")) {
-                if (state.jobs === 1 && state.rootTaskId !== null) {
-                    const pending = state.tasks.filter(task => task.taskId !== state.rootTaskId && !["delivered", "complete", "blocked"].includes(task.status));
-                    const node = pending.find(task => task.taskId === worker.taskId);
-                    if (pending.length > 0 && (worker.workerId === state.coordinatorId || node === undefined ||
-                        node.dependencies.some(id => !state.tasks.some(task => task.taskId === id && ["delivered", "complete"].includes(task.status)))))
-                        continue;
-                }
+                if (recoverySkips(state, worker))
+                    continue;
                 if (worker.workerId !== state.coordinatorId && (worker.worktree === null ||
                     !(await deps.tasks(worker.worktree).list()).some(r => r.task.id === worker.taskId)))
                     continue;
                 try {
-                    await start(worker, undefined, manualResumeAt);
+                    await start(worker, worker.workerId === state.coordinatorId && yielded(worker) ? coordinatorWakeNote(state, worker) : undefined, manualResumeAt);
                     if (state.jobs === 1)
                         break;
                 }
@@ -855,7 +813,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));
                         }
@@ -927,6 +886,12 @@ export async function superviseNativeRun(root, runId) {
                                     { questionId: request.requestId, prompt: request.prompt, askedAt: new Date().toISOString(), answeredAt: null, answerDigest: null }] }));
                             response = { requestId: request.requestId, code: "RUN_AWAITING_INPUT" };
                         }
+                        else if (request.action === "wait") {
+                            if ((await collectChangeSurface(gitRunner(worker.worktree))).paths.length > 0)
+                                throw new AgentOpsError("RUN_WAIT_DIRTY", "Commit coordinator changes before waiting; a stopped checkout must be clean to restart.");
+                            await waitForChildren(repository, supervisor, runId, worker.workerId, worker.generation);
+                            response = { requestId: request.requestId, code: "RUN_COORDINATOR_WAITING" };
+                        }
                         else if (request.action === "finalize") {
                             if (worker.workerId !== current.coordinatorId || current.tasks.some(task => task.taskId !== current.rootTaskId && task.status !== "delivered"))
                                 throw new AgentOpsError("RUN_DELIVERIES_PENDING", "The coordinator must wait for every planned child delivery before final integration.");
@@ -1011,3 +976,126 @@ 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 = "";
+        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.");
+                }
+                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 => { 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 (!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 {
+                reject(new AgentOpsError("RUN_FINAL_PROOF_INTERRUPTED", "Final gate did not return a complete result; inspect target and receipt before retrying."));
+            }
+        });
+    });
+}
+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/adapters/agy/config.js

@@ -54,7 +54,7 @@ export function buildAgyHookSettings(capabilities, runtimePath, platform = proce
         throw new AgentOpsError("AGY_HOOK_PATH_INVALID", "agy hook runtime path is invalid.");
     }
     const hooks = {};
-    if ((capabilities.includes("lifecycle-summary") || capabilities.includes("office-presence") || capabilities.includes("task-debug")) || capabilities.includes("project-loop")) {
+    if ((capabilities.includes("lifecycle-summary") || capabilities.includes("office-presence")) || capabilities.includes("project-loop")) {
         hooks.PreInvocation = [handler(runtimePath, "SessionStart", platform)];
     }
     if ((capabilities.includes("command-policy") || capabilities.includes("office-presence")) || capabilities.includes("project-loop")) {
@@ -62,8 +62,7 @@ export function buildAgyHookSettings(capabilities, runtimePath, platform = proce
     }
     if (capabilities.includes("office-presence") ||
         capabilities.includes("optional-stop-verify") ||
-        capabilities.includes("completion-gate") ||
-        capabilities.includes("task-debug")) {
+        capabilities.includes("completion-gate")) {
         hooks.Stop = [handler(runtimePath, "Stop", platform, capabilities.includes("completion-gate"))];
     }
     return { hooks };

package/dist/runtime/src/adapters/claude/config.js

@@ -115,7 +115,7 @@ export function buildClaudeHookSettings(capabilities, runtimePath, platform = pr
         }
         // The loop has its own prompt hook. Outside it, a prompt is both the
         // turn's start for Office and content for command policy.
-        if (capabilities.includes("command-policy") || capabilities.includes("office-presence") || capabilities.includes("task-debug")) {
+        if (capabilities.includes("command-policy") || capabilities.includes("office-presence")) {
             hooks.UserPromptSubmit = [matcherGroup("UserPromptSubmit", runtimePath)];
             if (capabilities.includes("command-policy") || capabilities.includes("office-presence"))
                 hooks.PreToolUse = [matcherGroup("PreToolUse", runtimePath)];
@@ -126,7 +126,7 @@ export function buildClaudeHookSettings(capabilities, runtimePath, platform = pr
     if (capabilities.includes("completion-gate")) {
         hooks.Stop = [matcherGroup("Stop", runtimePath, true)];
     }
-    else if (capabilities.includes("task-debug") || capabilities.includes("optional-stop-verify") || capabilities.includes("office-presence")) {
+    else if (capabilities.includes("optional-stop-verify") || capabilities.includes("office-presence")) {
         hooks.Stop = [matcherGroup("Stop", runtimePath)];
     }
     // Stop only ends a turn. SessionEnd is the one signal that the conversation

package/dist/runtime/src/adapters/codex/config.js

@@ -84,18 +84,15 @@ export function buildCodexHookConfig(capabilities, runtimePath) {
         }
         // The loop has its own prompt hook. Outside it, a prompt is both the
         // turn's start for Office and content for command policy.
-        if (capabilities.includes("command-policy") || capabilities.includes("office-presence") || capabilities.includes("task-debug")) {
+        if (capabilities.includes("command-policy") || capabilities.includes("office-presence")) {
             hooks.UserPromptSubmit = [matcherGroup("UserPromptSubmit", runtimePath)];
             if (capabilities.includes("command-policy") || capabilities.includes("office-presence"))
                 hooks.PreToolUse = [matcherGroup("PreToolUse", runtimePath)];
         }
     }
-    if (capabilities.includes("task-debug") || capabilities.includes("optional-stop-verify") || capabilities.includes("office-presence")) {
+    if (capabilities.includes("optional-stop-verify") || capabilities.includes("office-presence")) {
         hooks.Stop = [matcherGroup("Stop", runtimePath)];
     }
-    if (capabilities.includes("task-debug")) {
-        hooks.Interrupt = [{ hooks: [{ ...commandHook("Interrupt", runtimePath), timeout: 3 }] }];
-    }
     if (capabilities.includes("office-presence") && hooks.PreToolUse !== undefined) {
         hooks.PreToolUse = hooks.PreToolUse.map(group => ({ ...group, matcher: "^(Bash|apply_patch)$" }));
     }

package/dist/runtime/src/hooks/completion-gate.js

@@ -260,9 +260,6 @@ export class CompletionGateService {
         }
     }
     async grantPermit(sessionId) {
-        const attached = await this.#options.taskService.status({ sessionId }).catch(() => null);
-        if (attached?.task.debug !== undefined && attached.status === "active")
-            throw new AgentOpsError("TASK_DEBUG_CHECKPOINT_REQUIRED", "Active debug issues require a runtime stop checkpoint; allow-stop does not grant budget or success.");
         const fingerprint = await this.#fingerprint();
         const granted = await this.#store.mutate(sessionId, (state) => {
             if (state === null) {
@@ -488,18 +485,6 @@ export class CompletionGateService {
             }
             return last;
         }
-        const debugTask = await this.#options.taskService.status({ sessionId }).catch(() => null);
-        if (debugTask?.task.debug !== undefined) {
-            if (debugTask.status === "active") {
-                await this.#options.taskService.debugService().prepareStop(debugTask.task.id, sessionId);
-                const valid = await this.#options.taskService.debugService().validCheckpoint(debugTask.task.id, sessionId, fingerprint);
-                return valid ? gateResult("continue", "UNKNOWN", "COMPLETION_GATE_TASK_DEBUG_STOPPED", "Original issue remains active with a runtime-bound non-success checkpoint.") :
-                    gateResult("block", "FAIL", "COMPLETION_GATE_TASK_DEBUG_ACTIVE", "Continue the investigation/evidence loop or record a current runtime stop checkpoint, even when Git has no net diff.");
-            }
-            const failure = await this.#validateTask(sessionId);
-            if (failure !== null)
-                return failure;
-        }
         if (changed) {
             const failure = await this.#validateTask(sessionId);
             if (failure !== null)

package/dist/runtime/src/install/harness.js

@@ -342,7 +342,7 @@ function autoRunInstruction(descriptor, context) {
         "`RUN_REPO_UNTRUSTED` means stop and ask the user; never work",
         "around trust. New runs have no total time cap; legacy finite runs upgrade",
         "only on manual resume, preserving accounting and independent blockers.",
-        "Command/review timeouts, provider limits and DEBUG budgets remain effective.",
+        "Command/review timeouts and provider limits remain effective.",
         "If the run ends without completing (blocked, stopped, failing review),",
         "report the `agent-ops run status",
         "<id>` state and code, the last `agent-ops run logs <id>` events, and the",
@@ -364,10 +364,10 @@ export function managedRules(descriptor, context) {
             : [`Toolkit version: ${context.toolkitVersion}`]),
         ""
     ];
-    if (context.capabilities.includes("task-debug"))
-        lines.push("Task DEBUG routing is enabled for investigation/bugfix issues. Native prompt hooks create the issue task when a session identity is available; otherwise use agent-ops task create --debug --goal <verbatim issue> with two to five issue-specific criteria. Explain/read-only, feature and refactor requests use the existing normal task flow.", "For DEBUG: understand the issue, investigate with task debug --debug-action investigate --command-id <trusted verifier>, record falsifiable hypotheses with --debug-action hypothesis --payload-file <json>, reproduce, fix, then once a hypothesis is confirmed declare the origin with --debug-action origin --payload-file <json> (escape-of <commit> with the earliest-gate label, or pre-existing/external with a reason; finish refuses ESCAPE_ORIGIN_MISSING without it; a surface label also needs a tracked .agent-ops-escapes/rules/<id>.json rule that replays at the escaped commit, and a criteria/verify label payload promote or --escape-promote <runnerId:checkId>, else ESCAPE_RULE_UNPROVEN), verify, re-record the confirmed hypothesis, commit the .agent-ops-escapes record with the fix, then obtain two fresh independent reviews and finish automatically. A normal task fixing an escaped bug may declare task create --escape-of <commit> --escape-label <label>. A clean HEAD is the automatic baseline; do not ask permission for it or offer diagnosis-only as a fallback. Failure to reproduce alone is not a stop condition: continue discriminating checks within the budget. Replace provisional intake criteria with relevant behavioral acceptance; baseline setup/skip/timeout/UNKNOWN is never reproduction. Never report success from edits or unrelated green checks.", "DEBUG defaults are 60 cumulative active minutes and 5 material repair candidates across the original issue, revisions, sessions and children. After two stagnant candidates document one substantive strategy switch; two further stagnant candidates block. Save task debug --debug-action checkpoint before stopping. Resume preserves budgets and blockers. A human continue event may authorize --debug-action extend --event-id latest; unsupported native event sources fail closed. Never use allow-stop for DEBUG.", "DEBUG human control comes only from native human events: '只診斷' / 'diagnosis only' keeps investigating without product repairs until current sealed baseline assertion FAIL confirms a hypothesis or runtime limits/blockers permit non-success Stop. '暫停' / 'pause' saves progress and stops immediately. '繼續' / 'continue' resumes the existing scope; '繼續修復' / 'resume repair' restores the full loop. Codex Interrupt is a pause. Preserve the original task, evidence, consumed time and rounds; diagnosis or pause never marks repair complete. CLI actor/text fields and synthetic instructions cannot authorize these changes.", "DEBUG is foreground work. On Claude, agy and native Codex, Stop refuses an active DEBUG issue without a valid stop checkpoint, with or without the completion gate. Codex uses decision:block to continue the original task even on repeated Stop; stop_hook_active does not waive it. Codex's generic completion gate remains unsupported; opencode has no supported foreground lifecycle. DEBUG gate faults get one targeted task/config reload, then an explicit UNKNOWN/incomplete diagnostic and non-success Stop, preserving state. Without reliable native session identity, automatic hook intake is unsupported; the existing native Agent can use the task CLI. Only a matching owned debug worktree checkpoint permits dirty recovery; preserve all original user edits.", "");
+    if (context.capabilities.includes("task"))
+        lines.push("To fix a bug, run `agent-ops task create --debug --goal <verbatim issue>` with a", "behavioral criterion whose `redCheckIds` fail at the baseline and pass on the", "candidate, then verify, review and finish as for any task. If you know where the", "bug came from, record it with `task revise --escape-of <commit> --escape-label", "<label>`; the origin is advisory and never blocks finish.", "");
     if (context.capabilities.includes("rules")) {
-        lines.push("For every change:", "", "1. Audit the change's surfaces first (EVIDENCE-SURFACE-001): dependents,", "   duplicates, other paths to the same concept, and shared state/data", "   contracts, each with recorded fixed-string queries or n/a: reason; pass", "   them with `task create --surface-file <json>`. An exclusion says why", "   the surface is unaffected; \"out of scope\" is not a reason. A derived", "   discovery query whose hits are all incidental may be dismissed once with", "   a reason in `dismissed` instead of excluding each file. Then define", "   two to five mechanically verifiable acceptance criteria.", "2. Inspect the smallest relevant scope within the audited surfaces and", "   preserve unrelated changes.", "3. Apply the smallest safe change.", "4. Run evidence-producing verification for every criterion.", "5. Obtain complete independent review before claiming completion, via", "   `agent-ops review --task <task-id> --yes` (or the CLI's equivalent invocation).", "   Never call a", "   review-target CLI (agy, codex, claude) directly — direct calls skip", "   the enforced read-only sandbox flags and can hang or fail on command", "   permission prompts.", "   Start this command through the trusted outer host runner as its first", "   and only invocation. On Codex, the outer tool request must use", "   `sandbox_permissions: \"require_escalated\"` so network and loopback", "   are available; in that same request, unset", "   `CODEX_SANDBOX_NETWORK_DISABLED` and set `AGENT_OPS_HOST` when three", "   targets are configured. The Codex shell form is", "   `env -u CODEX_SANDBOX_NETWORK_DISABLED AGENT_OPS_HOST=<current-host> agent-ops review --task <task-id> --yes`.", "   Keep it a plain command line: to keep the output add `--output <file>`", "   (the JSON envelope is written there and one line is printed) instead of", "   a shell redirect, which the host can only allow by matching the whole", "   command string, task id included.", "   Do not run it once in the restricted sandbox and retry; changing the", "   variable inside that sandbox is not elevation.", "   Review runs exactly two fresh sessions: with three configured targets,", "   set `AGENT_OPS_HOST` to the current CLI id so it is excluded; with two", "   targets both run in configured order; with one target it runs twice.", "   The first session is necessary; a PASS then requires an adversarial", "   re-check carrying the first report. A first FAIL or NOT_RUN stops.", "", "Treat `.agent-ops/config.json` as verifier authority. Discovery output is", "only a proposal until a user confirms it. Repository commands require an", "exact matching trust record. Confirmed project init/update grants it", "automatically when verification commands are configured.", "");
+        lines.push("   Every production task creation waits for one independent criteria advisory", "   before implementation (also DEBUG and native run parents/children). It has", "   no time/token budget; real launch/auth/output errors report NOT_RUN and", "   allow work, while explicit cancellation means stop. Read the private report,", "   decide which advice to adopt, and use task revise with reasons (including", "   rejections). Revise does not rerun it. Explicit rerun only:", "   `agent-ops review --criteria --task <id> --rerun --yes`.", "   Start task creation/criteria review through the trusted outer host when", "   the host sandbox blocks reviewer auth/network, using the same outer-host", "   invocation described below for review. Never bypass a native denial.", "   This advisory never replaces verify, final two-round review or finish.", "", "For every change:", "", "1. Audit the change's surfaces first (EVIDENCE-SURFACE-001): dependents,", "   duplicates, other paths to the same concept, and shared state/data", "   contracts, each with recorded fixed-string queries or n/a: reason; pass", "   them with `task create --surface-file <json>`. An exclusion says why", "   the surface is unaffected; \"out of scope\" is not a reason. A derived", "   discovery query whose hits are all incidental may be dismissed once with", "   a reason in `dismissed` instead of excluding each file. Then define", "   two to five mechanically verifiable acceptance criteria.", "2. Inspect the smallest relevant scope within the audited surfaces and", "   preserve unrelated changes.", "3. Apply the smallest safe change.", "4. Run evidence-producing verification for every criterion.", "5. Obtain complete independent review before claiming completion, via", "   `agent-ops review --task <task-id> --yes` (or the CLI's equivalent invocation).", "   Never call a", "   review-target CLI (agy, codex, claude) directly — direct calls skip", "   the enforced read-only sandbox flags and can hang or fail on command", "   permission prompts.", "   Start this command through the trusted outer host runner as its first", "   and only invocation. On Codex, the outer tool request must use", "   `sandbox_permissions: \"require_escalated\"` so network and loopback", "   are available; in that same request, unset", "   `CODEX_SANDBOX_NETWORK_DISABLED` and set `AGENT_OPS_HOST` when three", "   targets are configured. The Codex shell form is", "   `env -u CODEX_SANDBOX_NETWORK_DISABLED AGENT_OPS_HOST=<current-host> agent-ops review --task <task-id> --yes`.", "   Keep it a plain command line: to keep the output add `--output <file>`", "   (the JSON envelope is written there and one line is printed) instead of", "   a shell redirect, which the host can only allow by matching the whole", "   command string, task id included.", "   Do not run it once in the restricted sandbox and retry; changing the", "   variable inside that sandbox is not elevation.", "   Review runs exactly two fresh sessions: with three configured targets,", "   set `AGENT_OPS_HOST` to the current CLI id so it is excluded; with two", "   targets both run in configured order; with one target it runs twice.", "   The first session is necessary; a PASS then requires an adversarial", "   re-check carrying the first report. A first FAIL or NOT_RUN stops.", "", "Treat `.agent-ops/config.json` as verifier authority. Discovery output is", "only a proposal until a user confirms it. Repository commands require an", "exact matching trust record. Confirmed project init/update grants it", "automatically when verification commands are configured.", "");
     }
     if (context.capabilities.includes("task")) {
         lines.push("Split a change that exceeds five acceptance criteria into subtasks:", "`agent-ops task create --parent <task-id>` records one, and", "`agent-ops task status --parent <task-id>` lists them. Each subtask", "carries its own criteria and verification; final review covers all", "tasks together when their worktrees are integrated;", "completing one never completes its parent.", "", ...autoRunInstruction(descriptor, context), "To review every active subtask of a parent together, run", "`agent-ops batch --parent <task-id> --yes` instead of one review per", "subtask. It needs what review needs: start it through the trusted outer", "host runner as its first and only invocation, with the same Codex", "elevation, and keep `--output <file>` instead of a shell redirect. It", "verifies, one task at a time, each task that lacks fresh evidence, and", "reviews a few tasks at once. Do not commit or edit the worktree while it", "runs: a moved HEAD voids every verify and review in the batch.", "For subagents in separate worktrees, use `task advance` instead.", "", "Delegate a subtask whose scope spans unknown files, broad scans, or an", "independent workstream instead of doing it inline. Name the bounded", "scope, the artifact to return, and the acceptance criteria it serves.", subagentInstruction(descriptor), "Read every returned artifact back yourself: integration, verification,", "and review stay with the coordinator.", "", "One writer at a time. `agent-ops verify` and `agent-ops review`", "fingerprint the working tree and report UNKNOWN when anything else", "writes it during the run, so delegate edits to one subagent at a time,", "or give each writer its own Git worktree and merge before verifying.", "Read-only delegation has no such limit and may run in parallel.", "", "Parallel conversations in one repository each need their own worktree.", "When `.agent-ops/config.json` sets `worktree.mode` to `auto`, run", "`agent-ops task create` from the main checkout before your first edit:", "it creates this session's worktree and puts the task there (`agent-ops", "worktree add <name> --session <session-id>` does the same without a", "task). Work only inside the printed path", "(Claude Code: EnterWorktree with that path; otherwise use it as every", "command's working directory). Commit, then run verify and review for", "each task with the printed `--base`; do not run `task complete` in the", "worktree. Leave it (Claude Code: ExitWorktree with action keep) and run", "`agent-ops worktree finish <name>` from the main checkout: it completes", "every task in the worktree, subtasks first, then merges. A finish that", "reports an incomplete task names it; verify or review that task again", "in the worktree and finish again. A finish that reports a conflict is", "resolved once, as a new task whose criteria cover both intents; if its", "verification or review fails, reset as instructed and report.", "", "For a session with writing subagents, record each child task's complete", "modification intent with `task create --intent <text>` before editing.", "Each child commits and runs local `verify --task` in its own worktree.", "From the main checkout run `agent-ops task advance --task <parent-id>", "--session <session-id> --yes` through the trusted outer host runner,", "unsetting `CODEX_SANDBOX_NETWORK_DISABLED` on Codex. Advance integrates", "child commits and intent into the coordinator worktree, verifies every", "task on the final candidate, then runs one two-round tree review.", "Only `NOT_RUN / scope-too-large` falls back to per-task two-round review;", "a substantive FAIL must be fixed. After PASS, advance writes a local", "receipt under the main checkout's Git common directory and calls finish.", "If the target moves, it retries the final gate once. An unresolved", "failure preserves worktrees and cannot be reported as finished.", "");

package/dist/runtime/src/install/plan.js

@@ -1,5 +1,4 @@
 import { lstat, readFile } from "node:fs/promises";
-import { DEBUG_DEFAULTS } from "../task/debug-state.js";
 import { CONFIG_SCHEMA_VERSION, MANIFEST_SCHEMA_VERSION } from "../contracts.js";
 import { discoverProject } from "../discovery/index.js";
 import { sha256 } from "../fs/hash.js";
@@ -90,6 +89,8 @@ function buildConfig(profiles, existing, reviewTargets = [], detectedCommands =
         existing.verification.commands.length > 0
         ? existing.verification
         : { commands: [...detectedCommands] };
+    // Pre-0.11 DEBUG budget settings are dropped on rewrite.
+    const existingFeatures = existing === undefined ? undefined : (({ debug: _legacyDebug, ...rest }) => rest)(existing.features);
     const effectiveWorktree = worktree !== undefined
         ? (worktree === null ? undefined : structuredClone(worktree))
         : (existing?.worktree === undefined ? undefined : structuredClone(existing.worktree));
@@ -98,8 +99,7 @@ function buildConfig(profiles, existing, reviewTargets = [], detectedCommands =
         profiles: [...profiles],
         verification,
         features: {
-            debug: existing?.features.debug ?? { ...DEBUG_DEFAULTS },
-            ...(existing?.features ?? {
+            ...(existingFeatures ?? {
                 stopVerification: { enabled: false },
                 completionGate: { enabled: completionGateEnabled }
             }),

package/dist/runtime/src/install/profiles.js

@@ -34,8 +34,6 @@ export function resolveProfiles(inputProfiles) {
 }
 export function resolveCapabilities(config) {
     const resolved = resolveProfiles(config.profiles);
-    if (config.features.debug?.enabled === true)
-        resolved.capabilities.push("task-debug");
     if (config.features.office?.enabled === true)
         resolved.capabilities.push("office-presence");
     if (config.features.stopVerification.enabled) {

package/dist/runtime/src/logging/local-log.js

@@ -29,6 +29,18 @@ function sanitizeEvent(value) {
     if (!isRecord(value) || typeof value.type !== "string") {
         return invalidEvent();
     }
+    if (value.type === "criteria-review") {
+        if (!hasExactKeys(value, ["type", "taskId", "attemptId", "status", "code", "durationMs", "invocations", "recommendations", "report", "usage"]) ||
+            typeof value.taskId !== "string" || !ID_PATTERN.test(value.taskId) ||
+            typeof value.attemptId !== "string" || !/^[a-f0-9-]{36}$/u.test(value.attemptId) ||
+            !["RUNNING", "COMPLETED", "NOT_RUN", "CANCELLED"].includes(String(value.status)) ||
+            typeof value.code !== "string" || !ID_PATTERN.test(value.code) || !isBoundedString(value.report) ||
+            ![value.durationMs, value.invocations, value.recommendations].every(n => Number.isSafeInteger(n) && n >= 0) ||
+            !isRecord(value.usage) || Object.entries(value.usage).some(([key, n]) => !["inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens", "costUsd"].includes(key) ||
+            typeof n !== "number" || !Number.isFinite(n) || n < 0))
+            return invalidEvent();
+        return { ...value, report: redactSecrets(value.report) };
+    }
     if (value.type === "diagnostic") {
         if (!hasExactKeys(value, ["code", "type"]) ||
             typeof value.code !== "string" ||