@kylecheng3146/agent-ops 0.4.0 → 0.4.1

package/README.md

@@ -345,6 +345,41 @@ agent-ops doctor              # presence only: no tokens, no network
 agent-ops doctor --check-auth # one real print call per configured target
 ```
 
+### Batch review
+
+A change split into subtasks needs one verify and one review per subtask.
+`agent-ops batch --parent <task-id> --yes` runs them together for the parent's
+active subtasks and the parent itself, instead of one `review` at a time:
+
+```bash
+agent-ops batch --parent <task-id> --yes --output batch.json
+agent-ops batch --parent <task-id> --yes --base <ref> --parent-base <ref> --width 3
+```
+
+- Each task is verified and reviewed against its own base: `--base` for the
+  subtasks and `--parent-base` for the parent, otherwise the base recorded by
+  its last PASS review, otherwise the worktree base.
+- A task that already has fresh PASS verification evidence skips verify. The
+  rest are verified one at a time, and each task's review starts as soon as its
+  own verify passes, so the next verify overlaps it. A task whose verify fails
+  gets no review; the others continue.
+- At most `--width` reviews run at once (default 2). A transient `NOT_RUN`
+  (`probe-failed`, `stalled`, `timeout`, `quota-exhausted`,
+  `network-unreachable`) lowers the width to 1 for the rest and earns that task
+  one retry, alone, after the others finish. Other results are final.
+- Each review target is probed once per batch while the probe succeeds; a
+  failed probe is forgotten so the retry probes again.
+- Nothing may commit or edit the worktree while it runs. HEAD is part of every
+  fingerprint, so a change aborts the batch and reports the unfinished tasks
+  as `aborted`.
+- Exit code 0 means every task passed, 1 means a review or verify failed, and 2
+  means the rest could not run and may be retried. The JSON envelope lists each
+  task; the full reports stay under `.agent-ops/reviews/`.
+
+`batch` is started exactly like `review`: through the trusted outer host runner
+as its first and only invocation, with `--output` instead of a shell redirect.
+`agent-ops init` and `update` pre-authorize it beside `review`.
+
 See [Configuration](docs/en/guides/configuration.md) for the full contract.
 
 ## Project principles

package/dist/packages/cli/src/args.js

@@ -9,6 +9,7 @@ export const COMMAND_NAMES = [
     "task",
     "verify",
     "review",
+    "batch",
     "allow-stop",
     "worktree"
 ];
@@ -71,6 +72,8 @@ export function parseArgs(argv) {
     let title;
     let sessionId;
     let base;
+    let parentBase;
+    let width;
     const profiles = [];
     const reviewTargets = [];
     const criteria = [];
@@ -210,6 +213,26 @@ export function parseArgs(argv) {
                 index += 1;
                 break;
             }
+            case "--parent-base": {
+                if (parentBase !== undefined) {
+                    duplicate(token);
+                }
+                parentBase = readOptionValue(argv, index, token);
+                index += 1;
+                break;
+            }
+            case "--width": {
+                if (width !== undefined) {
+                    duplicate(token);
+                }
+                const value = readOptionValue(argv, index, token);
+                if (!/^[1-9][0-9]{0,2}$/u.test(value)) {
+                    invalidValue(token, value);
+                }
+                width = Number(value);
+                index += 1;
+                break;
+            }
             case "--check-auth":
                 if (checkAuth) {
                     duplicate(token);
@@ -416,6 +439,8 @@ export function parseArgs(argv) {
             completionGate !== undefined ||
             sessionId !== undefined ||
             base !== undefined ||
+            parentBase !== undefined ||
+            width !== undefined ||
             checkAuth ||
             checkAuthTargets.length > 0 ||
             dryRun ||
@@ -465,15 +490,18 @@ export function parseArgs(argv) {
         (hasTaskTargetOptions || hasTaskMutationOptions)) {
         throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "Task target options may be used only with task or verify.");
     }
-    if (command !== "task" && parentTaskId !== undefined) {
-        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "--parent may be used only with task create or task status.");
+    if (command !== "task" && command !== "batch" && parentTaskId !== undefined) {
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "--parent may be used only with task create, task status or batch.");
     }
     if (command !== "update" && targetVersion !== undefined) {
         throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "--target-version may be used only with update.");
     }
     if (base !== undefined && command !== "verify" && command !== "review" &&
-        !(command === "task" && action === "complete")) {
-        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "--base may be used only with verify, review or task complete.");
+        command !== "batch" && !(command === "task" && action === "complete")) {
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "--base may be used only with verify, review, batch or task complete.");
+    }
+    if ((parentBase !== undefined || width !== undefined) && command !== "batch") {
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", `${parentBase !== undefined ? "--parent-base" : "--width"} may be used only with batch.`);
     }
     if (hookTargets.length > 0 &&
         command !== "init" &&
@@ -566,6 +594,16 @@ export function parseArgs(argv) {
     if (command === "review" && (criteria.length > 0 || evidence.length > 0)) {
         throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "Complete review covers every task criterion; omit --criterion and --evidence.");
     }
+    if (command === "batch" && parentTaskId === undefined) {
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "Batch requires --parent to name the task whose subtasks it covers.");
+    }
+    if (command === "batch" && !yes) {
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "Batch requires --yes to authorize the reviewer sessions.");
+    }
+    if (command === "batch" &&
+        (harness !== undefined || profiles.length > 0 || dryRun || rerun)) {
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "Batch accepts parent, base, parent-base, width, json, output and yes options.");
+    }
     if (command === "allow-stop" &&
         (sessionId === undefined ||
             scope !== undefined ||
@@ -589,8 +627,8 @@ export function parseArgs(argv) {
             rerun)) {
         throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "worktree accepts only a name, --session, --from, --target-branch, --message and --json.");
     }
-    if (output !== undefined && command !== "review" && command !== "doctor") {
-        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "--output may be used only with review or doctor.", "--output");
+    if (output !== undefined && command !== "review" && command !== "batch" && command !== "doctor") {
+        throw new CliArgumentError("CLI_OPTION_NOT_ALLOWED", "--output may be used only with review, batch or doctor.", "--output");
     }
     if (output !== undefined && (output.trim() === "" || output.includes("\0"))) {
         throw new CliArgumentError("CLI_INVALID_VALUE", "Invalid value for --output.", "--output");
@@ -636,6 +674,8 @@ export function parseArgs(argv) {
         ...(evidence.length === 0 ? {} : { evidence }),
         ...(sessionId === undefined ? {} : { sessionId }),
         ...(base === undefined ? {} : { base }),
+        ...(parentBase === undefined ? {} : { parentBase }),
+        ...(width === undefined ? {} : { width }),
         ...(worktreeFrom === undefined ? {} : { worktreeFrom }),
         ...(worktreeMessage === undefined ? {} : { worktreeMessage }),
         ...(output === undefined ? {} : { output }),

package/dist/packages/cli/src/bin.js

@@ -18,6 +18,7 @@ import { FileEvidenceStore } from "../../../runtime/src/verify/evidence.js";
 import { calculateSourceFingerprint } from "../../../runtime/src/verify/source-fingerprint.js";
 import { VerificationService } from "../../../runtime/src/verify/service.js";
 import { NodeVerificationProcessRunner } from "../../../runtime/src/verify/spawn.js";
+import { COMMAND_NAMES, parseArgs } from "./args.js";
 import { runCli } from "./cli.js";
 import { loadEffectiveConfig, repositoryTrust, repositoryTrustBinding } from "./context.js";
 import { runHookProcess } from "./hook-process.js";
@@ -30,7 +31,10 @@ import { runDoctorCommand } from "./commands/doctor.js";
 import { formatInstallPlan, runInitCommand } from "./commands/init.js";
 import { formatUninstallPlan, runUninstallCommand } from "./commands/uninstall.js";
 import { runTaskCommand } from "./commands/task.js";
-import { runReviewCommand } from "./commands/review.js";
+import { hasFreshVerification, runReviewCommand } from "./commands/review.js";
+import { runBatchCommand } from "./commands/batch.js";
+import { createSourceGuard } from "../../../runtime/src/review/batch-guard.js";
+import { memoizePreflight } from "../../../runtime/src/review/batch.js";
 import { createReviewExecutor, ReviewInterruptedError } from "../../../runtime/src/review/execute.js";
 import { probeReviewTargetDetailed } from "../../../runtime/src/review/probe.js";
 import { resolveReviewScope } from "../../../runtime/src/review/scope.js";
@@ -43,7 +47,7 @@ import { formatUpdatePlan, runUpdateCommand } from "./commands/update.js";
 import { errorEnvelope } from "./output.js";
 import { runAgyHeadless } from "./agy-headless.js";
 import { runWorktreeCommand } from "./commands/parallel.js";
-import { ensureSessionWorktree, resolveCheckouts } from "../../../runtime/src/parallel/service.js";
+import { ensureSessionWorktree, readWorktreeRecord, resolveCheckouts } from "../../../runtime/src/parallel/service.js";
 import { listWorktrees, branchLockDoctorResult, worktreeDoctorResult } from "../../../runtime/src/parallel/manage.js";
 import { detectGhostFiles, ghostFilesDoctorResult } from "../../../runtime/src/install/doctor.js";
 const HOOK_RUNTIME_PATH = fileURLToPath(new URL("./hook-entry.js", import.meta.url));
@@ -207,19 +211,10 @@ else {
         writeStderr: (value) => process.stderr.write(value)
     }, {
         version: CLI_VERSION,
-        registry: createCommandRegistry(Object.fromEntries([
-            "init",
-            "config",
-            "trust",
-            "doctor",
-            "update",
-            "uninstall",
-            "task",
-            "verify",
-            "review",
-            "allow-stop",
-            "worktree"
-        ].map((command) => [command, async (args) => {
+        registry: createCommandRegistry(Object.fromEntries(
+        // Every command the parser knows is registered: a hand-kept list here
+        // once left a parsed command answering CLI_COMMAND_UNAVAILABLE.
+        COMMAND_NAMES.map((command) => [command, async (args) => {
                 const root = args.scope === "user"
                     ? process.env.AGENT_OPS_HOME ?? homedir()
                     : process.cwd();
@@ -442,12 +437,68 @@ else {
                             : {})
                     });
                 }
-                if (args.command === "review") {
+                const probeTarget = async (target, budget) => await probeReviewTargetDetailed(target, {
+                    cwd: root,
+                    deep: true,
+                    // The probe answers within the chain's remaining budget
+                    // or not at all; its own default would outlast it.
+                    ...(budget === undefined ? {} : { timeoutMs: budget.timeoutMs })
+                });
+                // One place builds a review's options, so `review` and each task of
+                // a `batch` are reviewed identically.
+                const buildReviewOptions = async (reviewArgs, signal, preflightTarget = probeTarget, progressPrefix = "") => {
                     const reviewSessionId = process.env.AGENT_OPS_SESSION_ID;
                     const reviewGit = gitRunner(root);
-                    const reviewConfig = (await loadEffectiveConfig(root, args.scope === "user" ? "user" : "project")).config;
+                    const reviewConfig = (await loadEffectiveConfig(root, reviewArgs.scope === "user" ? "user" : "project")).config;
                     const reviewRole = resolveReviewRole("independent-review", reviewConfig.reviewRoles ?? []);
                     const configuredReviewTargets = reviewRole?.targets ?? [];
+                    return {
+                        args: reviewArgs,
+                        authorized: reviewArgs.yes,
+                        tasks: taskService,
+                        ...(reviewArgs.taskId === undefined ? {} : { taskId: reviewArgs.taskId }),
+                        ...(reviewSessionId === undefined
+                            ? {}
+                            : { sessionId: reviewSessionId }),
+                        ...(reviewConfig.reviewRoles === undefined
+                            ? {}
+                            : { roles: reviewConfig.reviewRoles }),
+                        targets: configuredReviewTargets,
+                        root,
+                        gitRunner: reviewGit,
+                        policyConfigHash: calculateConfigHash(reviewConfig),
+                        currentPolicyConfigHash: async () => calculateConfigHash((await loadEffectiveConfig(root, reviewArgs.scope === "user" ? "user" : "project")).config),
+                        config: reviewConfig,
+                        evidenceStore: new FileEvidenceStore(root, root),
+                        execute: createReviewExecutor({
+                            targets: configuredReviewTargets,
+                            cwd: root,
+                            ...(reviewRole?.model === undefined
+                                ? {}
+                                : { model: reviewRole.model }),
+                            ...(reviewRole?.effort === undefined
+                                ? {}
+                                : { effort: reviewRole.effort }),
+                            ...(reviewRole?.timeoutMs === undefined
+                                ? {}
+                                : { timeoutMs: reviewRole.timeoutMs }),
+                            preflightTarget,
+                            verifySourceFingerprint: async (expected) => {
+                                const currentScope = await resolveReviewScope({
+                                    root,
+                                    runner: reviewGit,
+                                    ...(reviewArgs.base === undefined ? {} : { base: reviewArgs.base })
+                                });
+                                return await calculateSourceFingerprint(root, currentScope, reviewGit) === expected;
+                            },
+                            signal,
+                            onProgress: (line) => {
+                                process.stderr.write(`${progressPrefix}${line}\n`);
+                            }
+                        })
+                    };
+                };
+                if (args.command === "review") {
                     const controller = new AbortController();
                     let interruptedBy;
                     const interrupt = (signal) => {
@@ -459,59 +510,7 @@ else {
                     process.once("SIGINT", onSigint);
                     process.once("SIGTERM", onSigterm);
                     try {
-                        return await runReviewCommand({
-                            args,
-                            authorized: args.yes,
-                            tasks: taskService,
-                            ...(args.taskId === undefined ? {} : { taskId: args.taskId }),
-                            ...(reviewSessionId === undefined
-                                ? {}
-                                : { sessionId: reviewSessionId }),
-                            ...(reviewConfig.reviewRoles === undefined
-                                ? {}
-                                : { roles: reviewConfig.reviewRoles }),
-                            targets: configuredReviewTargets,
-                            root,
-                            gitRunner: reviewGit,
-                            policyConfigHash: calculateConfigHash(reviewConfig),
-                            currentPolicyConfigHash: async () => calculateConfigHash((await loadEffectiveConfig(root, args.scope === "user" ? "user" : "project")).config),
-                            config: reviewConfig,
-                            evidenceStore: new FileEvidenceStore(root, root),
-                            execute: createReviewExecutor({
-                                targets: configuredReviewTargets,
-                                cwd: root,
-                                ...(reviewRole?.model === undefined
-                                    ? {}
-                                    : { model: reviewRole.model }),
-                                ...(reviewRole?.effort === undefined
-                                    ? {}
-                                    : { effort: reviewRole.effort }),
-                                ...(reviewRole?.timeoutMs === undefined
-                                    ? {}
-                                    : { timeoutMs: reviewRole.timeoutMs }),
-                                preflightTarget: async (target, budget) => await probeReviewTargetDetailed(target, {
-                                    cwd: root,
-                                    deep: true,
-                                    // The probe answers within the chain's remaining budget
-                                    // or not at all; its own default would outlast it.
-                                    ...(budget === undefined
-                                        ? {}
-                                        : { timeoutMs: budget.timeoutMs })
-                                }),
-                                verifySourceFingerprint: async (expected) => {
-                                    const currentScope = await resolveReviewScope({
-                                        root,
-                                        runner: reviewGit,
-                                        ...(args.base === undefined ? {} : { base: args.base })
-                                    });
-                                    return await calculateSourceFingerprint(root, currentScope, reviewGit) === expected;
-                                },
-                                signal: controller.signal,
-                                onProgress: (line) => {
-                                    process.stderr.write(`${line}\n`);
-                                }
-                            })
-                        });
+                        return await runReviewCommand(await buildReviewOptions(args, controller.signal));
                     }
                     catch (error) {
                         if (error instanceof ReviewInterruptedError &&
@@ -525,6 +524,72 @@ else {
                         process.removeListener("SIGTERM", onSigterm);
                     }
                 }
+                if (args.command === "batch") {
+                    const controller = new AbortController();
+                    let interruptedBy;
+                    const interrupt = (signal) => {
+                        interruptedBy ??= signal;
+                        controller.abort(signal);
+                    };
+                    const onSigint = () => interrupt("SIGINT");
+                    const onSigterm = () => interrupt("SIGTERM");
+                    process.once("SIGINT", onSigint);
+                    process.once("SIGTERM", onSigterm);
+                    try {
+                        const batchScope = args.scope === "user" ? "user" : "project";
+                        const batchConfig = (await loadEffectiveConfig(root, batchScope)).config;
+                        const batchGit = gitRunner(root);
+                        const trusted = await repositoryTrust(root, batchConfig, CLI_VERSION) === "TRUSTED";
+                        const guard = await createSourceGuard(batchGit);
+                        const preflight = memoizePreflight(probeTarget);
+                        const taskArgs = (taskId, base) => parseArgs(["review", "--task", taskId, "--base", base, "--yes"]);
+                        const worktreeRecord = await readWorktreeRecord(root);
+                        const envelope = await runBatchCommand({
+                            args,
+                            tasks: taskService,
+                            ...(worktreeRecord === null ? {} : { worktreeBase: worktreeRecord.base }),
+                            guard,
+                            isVerified: async (taskId, base) => await hasFreshVerification(await buildReviewOptions(taskArgs(taskId, base), controller.signal, preflight), taskId, base),
+                            verify: async (taskId, base) => {
+                                const report = await new VerificationService({
+                                    root,
+                                    scope: batchScope,
+                                    config: batchConfig,
+                                    gitRunner: batchGit,
+                                    processRunner: new NodeVerificationProcessRunner(),
+                                    taskService,
+                                    evidenceStore: new FileEvidenceStore(root, root),
+                                    trusted,
+                                    base
+                                }).verify(taskId);
+                                return report.status === "PASS" ? "PASS" : "FAIL";
+                            },
+                            review: async (taskId, base, signal) => {
+                                const reviewed = await runReviewCommand(await buildReviewOptions(taskArgs(taskId, base), signal, preflight, `${taskId.slice(5, 13)}: `));
+                                const result = reviewed.data?.result;
+                                return result === undefined
+                                    ? { status: "NOT_RUN", reason: reviewed.errors[0]?.code ?? "review-error" }
+                                    : {
+                                        status: result.status,
+                                        ...(result.reason === undefined ? {} : { reason: result.reason }),
+                                        ...(result.reused === true ? { reused: true } : {})
+                                    };
+                            },
+                            signal: controller.signal,
+                            onProgress: (line) => {
+                                process.stderr.write(`batch: ${line}\n`);
+                            }
+                        });
+                        if (interruptedBy !== undefined) {
+                            process.exit(interruptedBy === "SIGINT" ? 130 : 143);
+                        }
+                        return envelope;
+                    }
+                    finally {
+                        process.removeListener("SIGINT", onSigint);
+                        process.removeListener("SIGTERM", onSigterm);
+                    }
+                }
                 if (args.command === "config") {
                     return explainConfigCommand(await loadEffectiveConfig(root, args.scope === "user" ? "user" : "project"));
                 }

package/dist/packages/cli/src/cli.js

@@ -29,6 +29,7 @@ Commands:
              Manage independent task acceptance state
   verify     Run configured verification
   review     Run an independent review
+  batch      Verify and review a parent task's subtasks together
   allow-stop Grant one fingerprint-bound completion-gate Stop permit (requires --session)
   agy-run    Run headless agy with a process-exit completion recheck
   worktree <add|finish|list|resume|remove>
@@ -47,13 +48,16 @@ Options:
   --check-auth-target <target>        Repeatable doctor filter with --check-auth
   --task <id>
   --parent <task-id>                  Task create: record a subtask of this
-                                      task; task status: list its subtasks
+                                      task; task status: list its subtasks;
+                                      batch: the task whose subtasks it covers
+  --parent-base <git-ref>             Batch only: base for the parent task
+  --width <n>                         Batch only: reviews allowed at once (default 2)
   --target-version <version>          Update target version (offline-capable)
   --title <text>
   --criterion <json>                    Repeatable
   --evidence <criterion-id=reference>   Repeatable
   --session <id>
-  --base <git-ref>                    Verify/review/complete a clean committed range
+  --base <git-ref>                    Verify/review/batch/complete a clean committed range
   --dry-run
   --json
   --yes
@@ -181,6 +185,26 @@ Options:
                        one summary line, so no shell redirect is needed
   --json
   --yes                Required authorization for both reviewer sessions
+`,
+    batch: `Usage: agent-ops batch --parent <task-id> --yes [options]
+
+Verify and review the active subtasks of a parent task, and the parent itself,
+together. Verify runs one task at a time and skips a task that already has
+fresh PASS evidence; each review starts as soon as its own verify passes.
+Nothing may commit or edit the worktree while it runs.
+
+Options:
+  --parent <task-id>   Required task whose active subtasks and itself are covered
+  --base <git-ref>     Base for the subtasks (default: each task's recorded
+                       review base, then the worktree base)
+  --parent-base <git-ref>
+                       Base for the parent task (same default)
+  --width <n>          Reviews allowed at once (default 2); a transient
+                       NOT_RUN lowers it to 1 and earns one retry
+  --output <file>      Write the JSON envelope to <file> (mode 0600) and print
+                       one summary line, so no shell redirect is needed
+  --json
+  --yes                Required authorization for the reviewer sessions
 `,
     "allow-stop": `Usage: agent-ops allow-stop --session <id> [options]
 
@@ -289,7 +313,7 @@ export async function runCli(argv, io, services) {
         const result = await execute(args);
         const exitCode = result.status === "ok"
             ? 0
-            : result.code === "REVIEW_NOT_RUN"
+            : result.code === "REVIEW_NOT_RUN" || result.code === "BATCH_NOT_RUN"
                 ? 2
                 : 1;
         if (args.output !== undefined) {

package/dist/packages/cli/src/commands/batch.js

@@ -0,0 +1,106 @@
+import { AgentOpsError } from "../../../../runtime/src/fs/paths.js";
+import { DEFAULT_BATCH_WIDTH, runBatch } from "../../../../runtime/src/review/batch.js";
+import { resolveBatchBase, selectBatchTasks } from "../../../../runtime/src/review/batch-select.js";
+import { redactSecrets } from "../../../../runtime/src/security/redact.js";
+import { safeTaskText } from "../../../../runtime/src/task/render.js";
+import { errorEnvelope } from "../output.js";
+function outcomeLabel(task) {
+    if (task.aborted) {
+        return "aborted";
+    }
+    if (task.review === null) {
+        return task.verify === "FAIL" ? "no review (verify failed)" : "not reviewed";
+    }
+    const reason = task.review.reason === undefined ? "" : ` ${task.review.reason}`;
+    return `${task.review.status}${reason}${task.review.reused === true ? " (reused)" : ""}${task.retried ? " (retried)" : ""}`;
+}
+function renderBatch(data) {
+    const lines = [
+        `Batch of ${data.tasks.length} task(s) under ${data.parentTaskId}, width ${data.width}.`,
+        "",
+        ...data.tasks.map((task) => `- ${task.taskId}  verify ${task.verify}  review ${outcomeLabel(task)}  base ${task.base.slice(0, 12)} (${task.baseSource})  ${safeTaskText(redactSecrets(task.title))}`)
+    ];
+    if (data.tasks.some((task) => task.aborted)) {
+        lines.push("", "The source changed or the run was interrupted; unfinished tasks were aborted. Run the batch again.");
+    }
+    return lines.join("\n");
+}
+function isPass(task) {
+    return !task.aborted && task.review?.status === "PASS";
+}
+/**
+ * The envelope's code follows the worst outcome that needs a human: a failed
+ * verify or review (fix the code) before a run that could not finish (run it
+ * again), so one defect is never hidden behind an unrelated NOT_RUN.
+ */
+function classify(tasks) {
+    if (tasks.every(isPass)) {
+        return "BATCH_RESULT";
+    }
+    return tasks.some((task) => task.verify === "FAIL" || task.review?.status === "FAIL")
+        ? "BATCH_FAILED"
+        : "BATCH_NOT_RUN";
+}
+export async function runBatchCommand(options) {
+    const { args } = options;
+    const parentTaskId = args.parentTaskId;
+    if (parentTaskId === undefined) {
+        throw new AgentOpsError("BATCH_PARENT_REQUIRED", "Batch requires --parent.");
+    }
+    const selected = selectBatchTasks(await options.tasks.list(), parentTaskId);
+    const plan = selected.map((record) => ({
+        record,
+        ...resolveBatchBase(record, record.task.id === parentTaskId, {
+            ...(args.base === undefined ? {} : { base: args.base }),
+            ...(args.parentBase === undefined ? {} : { parentBase: args.parentBase }),
+            ...(options.worktreeBase === undefined ? {} : { worktreeBase: options.worktreeBase })
+        })
+    }));
+    const baseOf = new Map(plan.map((item) => [item.record.task.id, item.base]));
+    const base = (id) => baseOf.get(id);
+    // The first answer is the clean-tree check: a batch reviews committed ranges.
+    if (!await options.guard()) {
+        return {
+            ...errorEnvelope("BATCH_DIRTY_WORKTREE", "Batch needs a clean working tree. Commit or discard your changes first."),
+            data: null
+        };
+    }
+    const width = args.width ?? DEFAULT_BATCH_WIDTH;
+    const outcomes = await runBatch(plan.map((item) => item.record.task.id), {
+        isVerified: (id) => options.isVerified(id, base(id)),
+        verify: (id, signal) => options.verify(id, base(id), signal),
+        review: (id, signal) => options.review(id, base(id), signal),
+        guard: options.guard
+    }, {
+        width,
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+        ...(options.onProgress === undefined ? {} : { onProgress: options.onProgress })
+    });
+    const byId = new Map(outcomes.map((outcome) => [outcome.id, outcome]));
+    const tasks = plan.map((item) => {
+        const outcome = byId.get(item.record.task.id);
+        return {
+            taskId: item.record.task.id,
+            title: item.record.task.title,
+            base: item.base,
+            baseSource: item.source,
+            verify: outcome.verify,
+            review: outcome.review,
+            retried: outcome.retried,
+            aborted: outcome.aborted
+        };
+    });
+    const code = classify(tasks);
+    const passed = tasks.filter(isPass).length;
+    const message = code === "BATCH_RESULT"
+        ? `Batch passed: ${passed} of ${tasks.length} task(s).`
+        : code === "BATCH_FAILED"
+            ? `Batch failed: ${passed} of ${tasks.length} task(s) passed.`
+            : `Batch was not completed: ${passed} of ${tasks.length} task(s) passed.`;
+    const summary = { message, parentTaskId, width, tasks };
+    const data = { ...summary, text: `${message}\n\n${renderBatch(summary)}` };
+    if (code === "BATCH_RESULT") {
+        return { code, status: "ok", data, errors: [] };
+    }
+    return { code, status: "error", data, errors: [{ code, message }] };
+}

package/dist/packages/cli/src/commands/review.js

@@ -196,6 +196,28 @@ async function preflightReview(options, context, sourceFingerprint) {
         summary: { status: "PASS", sourceFingerprint, commands }
     };
 }
+/**
+ * Whether the task already holds current PASS verification evidence for the
+ * source a review of `base` (or the working tree) would measure. This is the
+ * same preflight `review` runs before it spawns, so a batch that skips verify
+ * on a true answer never reaches a review that then reports stale evidence.
+ */
+export async function hasFreshVerification(options, taskId, base) {
+    if (options.root === undefined || options.gitRunner === undefined) {
+        return false;
+    }
+    const context = await taskContext({ ...options, taskId });
+    if (context === undefined) {
+        return false;
+    }
+    const scope = await resolveReviewScope({
+        root: options.root,
+        runner: options.gitRunner,
+        ...(base === undefined ? {} : { base })
+    });
+    const fingerprint = await calculateSourceFingerprint(options.root, scope, options.gitRunner);
+    return (await preflightReview(options, context, fingerprint)).ok;
+}
 function scopeReason(error) {
     if (!(error instanceof AgentOpsError)) {
         return undefined;

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

@@ -322,7 +322,7 @@ export function managedRules(descriptor, context) {
         lines.push("For every change:", "", "1. Define two to five mechanically verifiable acceptance criteria.", "2. Inspect the smallest relevant scope 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, verification, and independent review;", "completing one never completes its parent.", "", "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.", "");
+        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, verification, and independent review;", "completing one never completes its parent.", "", "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.", "", "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.", "");
     }
     if (context.capabilities.includes("lifecycle-summary")) {
         lines.push("Advisory lifecycle summaries and local logs are informational. Advisory", "failures must remain fail-open and cannot become verification evidence.", "");

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

@@ -15,13 +15,16 @@ export const CLAUDE_PREAUTH_ALLOW = [
     "Bash(agent-ops task *)",
     "Bash(agent-ops verify *)",
     "Bash(agent-ops review *)",
+    "Bash(agent-ops batch *)",
     "Bash(agent-ops worktree *)",
     "Bash(agent-ops doctor *)"
 ];
-/** review talks to the reviewer's API, which the sandbox withholds. */
+/** review and batch talk to the reviewer's API, which the sandbox withholds. */
 export const CLAUDE_PREAUTH_UNSANDBOXED = [
     "agent-ops review",
-    "agent-ops review *"
+    "agent-ops review *",
+    "agent-ops batch",
+    "agent-ops batch *"
 ];
 export const CODEX_RULES_PATH = "rules/agent-ops.rules";
 export const CODEX_RULES_MARKER = "# agent-ops managed: regenerated by agent-ops init and update; do not edit.";
@@ -51,8 +54,9 @@ function rule(options) {
 }
 /**
  * Prefix rules for the exact shapes `.agent-ops/AGENTS.md` tells Codex to run,
- * with and without AGENT_OPS_HOST, for review and the auth probe. Matching is
- * by argv prefix, so a shell redirect would defeat it: use `--output`.
+ * with and without AGENT_OPS_HOST, for review, batch and the auth probe.
+ * Matching is by argv prefix, so a shell redirect would defeat it: use
+ * `--output`.
  */
 export const CODEX_RULES_CONTENT = `${[
     CODEX_RULES_MARKER,
@@ -67,6 +71,13 @@ export const CODEX_RULES_CONTENT = `${[
                 match: `${env} review --task task-x --yes --output review.json`,
                 notMatch: `${env} trust grant --scope project --yes`
             }),
+            rule({
+                withHost,
+                command: ["batch"],
+                justification: "agent-ops batch runs reviews, which need network and loopback outside the sandbox.",
+                match: `${env} batch --parent task-x --yes --output batch.json`,
+                notMatch: `${env} trust grant --scope project --yes`
+            }),
             rule({
                 withHost,
                 command: ["doctor", "--check-auth"],

package/dist/runtime/src/review/batch-guard.js

@@ -0,0 +1,11 @@
+import { collectChangeSurface, resolveGitCommit } from "../verify/change-surface.js";
+/**
+ * Remembers HEAD now and answers whether the batch may go on: HEAD is still
+ * that commit and the working tree has no change. The first answer doubles as
+ * the clean-tree check, since a batch reviews committed ranges only.
+ */
+export async function createSourceGuard(runner) {
+    const head = await resolveGitCommit(runner, "HEAD");
+    return async () => await resolveGitCommit(runner, "HEAD") === head &&
+        (await collectChangeSurface(runner)).paths.length === 0;
+}

package/dist/runtime/src/review/batch-select.js

@@ -0,0 +1,37 @@
+import { AgentOpsError } from "../fs/paths.js";
+/**
+ * The tasks one `batch --parent` covers: the parent's active subtasks in
+ * creation order, then the parent itself. Archived and completed tasks, and
+ * tasks under another parent, are left out.
+ */
+export function selectBatchTasks(records, parentId) {
+    const parent = records.find((record) => record.task.id === parentId);
+    if (parent === undefined) {
+        throw new AgentOpsError("BATCH_PARENT_NOT_FOUND", `Parent task not found: ${parentId}`);
+    }
+    if (parent.status !== "active") {
+        throw new AgentOpsError("BATCH_PARENT_NOT_ACTIVE", `Parent task is not active: ${parentId}`);
+    }
+    const subtasks = records
+        .filter((record) => record.task.parentTaskId === parentId && record.status === "active")
+        .sort((left, right) => left.createdAt.localeCompare(right.createdAt) || left.task.id.localeCompare(right.task.id));
+    return [...subtasks, parent];
+}
+/**
+ * An explicit flag wins, then the commit the task's last PASS review measured
+ * against (so a rerun reproduces the same fingerprint), then the worktree base.
+ * A parent's base is a human choice that cannot be derived from the repository.
+ */
+export function resolveBatchBase(record, isParent, input) {
+    const flag = isParent ? input.parentBase : input.base;
+    if (flag !== undefined) {
+        return { base: flag, source: "flag" };
+    }
+    if (record.reviewBase !== undefined) {
+        return { base: record.reviewBase, source: "recorded" };
+    }
+    if (input.worktreeBase !== undefined) {
+        return { base: input.worktreeBase, source: "worktree" };
+    }
+    throw new AgentOpsError("BATCH_BASE_UNKNOWN", `No base for task ${record.task.id}: pass ${isParent ? "--parent-base" : "--base"} or run from an agent-ops worktree.`);
+}

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

@@ -0,0 +1,202 @@
+import { AgentOpsError } from "../fs/paths.js";
+/**
+ * NOT_RUN reasons that mean the reviewer was briefly unavailable. Anything
+ * else (a sandboxed host, stale verification, a changed policy) fails the same
+ * way on a second attempt, so it is reported instead of retried.
+ */
+export const TRANSIENT_REVIEW_REASONS = new Set([
+    "probe-failed",
+    "stalled",
+    "timeout",
+    "quota-exhausted",
+    "network-unreachable"
+]);
+/** Reviews allowed at once when the caller names no width. */
+export const DEFAULT_BATCH_WIDTH = 2;
+/**
+ * Verify runs one task at a time (a full test run per task; several at once
+ * starve each other of CPU and fake a failure). Each task's review starts as
+ * soon as its own verify has passed, so the next verify overlaps it. Reviews
+ * run up to `width` at a time; a transient NOT_RUN drops the width to 1 for
+ * good and that task gets one more try alone after everything else finished.
+ */
+export async function runBatch(ids, deps, options) {
+    if (!Number.isInteger(options.width) || options.width < 1) {
+        throw new AgentOpsError("BATCH_INVALID_WIDTH", "Batch width must be a positive integer.");
+    }
+    const progress = options.onProgress ?? (() => { });
+    const controller = new AbortController();
+    const outer = options.signal;
+    if (outer?.aborted === true) {
+        controller.abort();
+    }
+    else {
+        outer?.addEventListener("abort", () => controller.abort(), { once: true });
+    }
+    const slots = new Map(ids.map((id) => [
+        id,
+        { id, verify: "not-run", review: null, retried: false }
+    ]));
+    const slot = (id) => slots.get(id);
+    const stop = (why) => {
+        if (!controller.signal.aborted) {
+            progress(why);
+            controller.abort();
+        }
+    };
+    const guard = async () => {
+        try {
+            return await deps.guard();
+        }
+        catch {
+            return false;
+        }
+    };
+    let width = options.width;
+    let running = 0;
+    let verifying = true;
+    const ready = [];
+    const retry = [];
+    let finish;
+    const done = new Promise((resolve) => {
+        finish = resolve;
+    });
+    const review = async (id, final) => {
+        if (!await guard()) {
+            stop("source changed; aborting the batch");
+            return;
+        }
+        const entry = slot(id);
+        if (final) {
+            entry.retried = true;
+        }
+        let result;
+        try {
+            result = await deps.review(id, controller.signal);
+        }
+        catch (error) {
+            progress(`review ${id} failed to run: ${error instanceof Error ? error.message : String(error)}`);
+            result = { status: "NOT_RUN", reason: "review-error" };
+        }
+        if (controller.signal.aborted) {
+            return;
+        }
+        entry.review = result;
+        if (!final &&
+            result.status === "NOT_RUN" &&
+            result.reason !== undefined &&
+            TRANSIENT_REVIEW_REASONS.has(result.reason)) {
+            if (width > 1) {
+                width = 1;
+                progress(`degrade: review width -> 1 (${id}: ${result.reason})`);
+            }
+            retry.push(id);
+        }
+    };
+    const pump = () => {
+        while (!controller.signal.aborted && running < width && ready.length > 0) {
+            const id = ready.shift();
+            running += 1;
+            void review(id, false).finally(() => {
+                running -= 1;
+                pump();
+            });
+        }
+        if (!verifying && running === 0 && (ready.length === 0 || controller.signal.aborted)) {
+            finish();
+        }
+    };
+    const fresh = await Promise.all(ids.map((id) => deps.isVerified(id).catch(() => false)));
+    const stale = [];
+    ids.forEach((id, index) => {
+        if (fresh[index] === true) {
+            slot(id).verify = "skipped";
+            ready.push(id);
+        }
+        else {
+            stale.push(id);
+        }
+    });
+    const verifyAll = async () => {
+        for (const id of stale) {
+            if (controller.signal.aborted) {
+                break;
+            }
+            if (!await guard()) {
+                stop("source changed; aborting the batch");
+                break;
+            }
+            let status;
+            try {
+                status = await deps.verify(id, controller.signal);
+            }
+            catch (error) {
+                progress(`verify ${id} failed to run: ${error instanceof Error ? error.message : String(error)}`);
+                status = "FAIL";
+            }
+            if (controller.signal.aborted) {
+                break;
+            }
+            slot(id).verify = status;
+            if (status === "PASS") {
+                ready.push(id);
+                pump();
+            }
+        }
+        verifying = false;
+        pump();
+    };
+    void verifyAll();
+    pump();
+    await done;
+    if (!controller.signal.aborted) {
+        for (const id of retry) {
+            if (controller.signal.aborted) {
+                break;
+            }
+            await review(id, true);
+        }
+    }
+    const interrupted = controller.signal.aborted;
+    return ids.map((id) => {
+        const entry = slot(id);
+        const pendingRetry = retry.includes(id) && !entry.retried;
+        const unfinished = entry.review === null
+            ? entry.verify !== "FAIL"
+            : pendingRetry;
+        return {
+            id,
+            verify: entry.verify,
+            review: entry.review,
+            retried: entry.retried,
+            aborted: interrupted && unfinished
+        };
+    });
+}
+/**
+ * One probe per target for a whole batch. Concurrent callers share the probe
+ * in flight and a success is kept, but a failure is forgotten so the retry of
+ * a task re-probes instead of inheriting the failure.
+ */
+export function memoizePreflight(probe) {
+    const cache = new Map();
+    return (target, budget) => {
+        const cached = cache.get(target);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const pending = probe(target, budget);
+        cache.set(target, pending);
+        const forget = () => {
+            if (cache.get(target) === pending) {
+                cache.delete(target);
+            }
+        };
+        pending.then((answer) => {
+            if ((typeof answer === "string" ? answer : answer.result) !== "ok") {
+                forget();
+            }
+        }, forget);
+        return pending;
+    };
+}

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

@@ -161,11 +161,24 @@ export function buildTargetInvocation(request) {
     };
 }
 /** A deep doctor probe uses stdin but keeps its simple text response contract. */
+/**
+ * What the probe runs with where it differs from a review. The probe asks for
+ * one word, not a review, and agy's plan mode tells the model to research the
+ * task first: on a real project it explores, runs a command the headless user
+ * never allowed, is soft-denied, and prints nothing, which reads as
+ * `probe-failed`. In 40 replays, plan mode failed 4 of 20 and without it all 20
+ * answered in exactly two model calls. Only the probe drops it; a review keeps
+ * `READ_ONLY_ARGS`, and the sandbox stays on for both.
+ */
+const PROBE_ARGS = {
+    agy: ["--sandbox"]
+};
 export function buildProbeInvocation(request) {
-    const readOnly = READ_ONLY_ARGS[request.target];
-    if (readOnly === undefined || readOnly.length === 0) {
+    const eligible = READ_ONLY_ARGS[request.target];
+    if (eligible === undefined || eligible.length === 0) {
         return undefined;
     }
+    const readOnly = PROBE_ARGS[request.target] ?? eligible;
     if (request.target === "codex") {
         return {
             command: "codex",

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

@@ -37,7 +37,20 @@ export function probeTimeoutMs(requested) {
 export async function probeReviewTarget(target, options) {
     return (await probeReviewTargetDetailed(target, options)).result;
 }
+/**
+ * A deep probe is one model call, and a model call can fail for reasons that
+ * say nothing about the install. `probe-failed` is the answer for "it did not
+ * work and did not say why", so it gets one more try; every other answer is
+ * specific (not logged in, no network, timed out, not installed) and repeating
+ * it would only spend more of the budget on the same result.
+ */
 export async function probeReviewTargetDetailed(target, options) {
+    const first = await probeOnce(target, options);
+    return options.deep === true && first.result === "probe-failed"
+        ? await probeOnce(target, options)
+        : first;
+}
+async function probeOnce(target, options) {
     const deep = options.deep === true;
     const directory = deep
         ? await mkdtemp(join(tmpdir(), "agent-ops-review-probe-"))

package/docs/en/spec/review.md

@@ -125,3 +125,73 @@ FAIL.
 - Evidence: The result reason distinguishes a protocol violation from a verdict.
 - Positive: `NOT_RUN: unparseable-output; one criterion was missing.`
 - Negative: `Record a failed review because the model's JSON was malformed.`
+
+## REVIEW-BATCH-001
+
+A batch review MUST cover exactly the active subtasks of the named parent and the parent itself.
+
+- Trigger: Running `batch --parent <task-id>`.
+- Action: Select the parent's active subtasks in creation order, then the parent. Leave out archived and completed tasks and tasks under another parent. Reject an unknown parent with `BATCH_PARENT_NOT_FOUND` and an inactive one with `BATCH_PARENT_NOT_ACTIVE`.
+- Evidence: `data.tasks` lists exactly those task ids, in that order.
+- Positive: `Two active subtasks and the parent are covered; the archived subtask is not.`
+- Negative: `Cover every task in the worktree whatever its parent.`
+
+## REVIEW-BATCH-002
+
+Each task's base MUST come from an explicit flag, then its recorded review base, then the worktree base.
+
+- Trigger: Resolving the range a batch task is verified and reviewed against.
+- Action: Use `--base` for subtasks and `--parent-base` for the parent; otherwise the task's recorded `reviewBase`; otherwise the worktree base. Report `BATCH_BASE_UNKNOWN` when none exists.
+- Evidence: `data.tasks[].base` names the base each task used.
+- Positive: `A rerun reuses each PASSed task's recorded base, so its fingerprint and attestation still match.`
+- Negative: `Apply --base to the parent, or fall back to HEAD when no base is known.`
+
+## REVIEW-BATCH-003
+
+Verification MUST run one task at a time, each task's review MUST start as soon as its own verification passes, and no more than `--width` reviews (default 2) MUST run at once.
+
+- Trigger: Tasks in a batch need verification and review.
+- Action: Skip verification for a task that already holds fresh PASS evidence, using the same check review preflight makes. Verify the rest serially. Start a task's review right after its verification passes. Give a task whose verification fails no review, and continue with the others.
+- Evidence: `data.tasks[].verify` is `skipped`, `PASS` or `FAIL`, and a task that failed verification has no review.
+- Positive: `Task B is verified while task A is being reviewed.`
+- Negative: `Run every task's test suite at once.`
+
+## REVIEW-BATCH-004
+
+A transient NOT_RUN MUST lower the review width to 1 for the rest of the batch and earn exactly one retry, and every other result MUST be final.
+
+- Trigger: A review in a batch returns NOT_RUN.
+- Action: When the reason is `probe-failed`, `stalled`, `timeout`, `quota-exhausted` or `network-unreachable`, set the width to 1 for every review not yet started and retry that task once, alone, after the rest have finished. Never retry another reason, never retry twice, and never raise the width again.
+- Evidence: `review.retried` is true for a retried task, and a second transient NOT_RUN stays NOT_RUN.
+- Positive: `probe-failed on task A drops the width to 1, and A runs once more after the others.`
+- Negative: `Retry host-sandboxed until it passes.`
+
+## REVIEW-BATCH-005
+
+A batch MUST stop when the source it started on changes or the process is interrupted.
+
+- Trigger: HEAD or the working tree differs from the start of the batch, or the process receives SIGINT or SIGTERM.
+- Action: Require a clean working tree before starting and check HEAD and the tree before every step. On a change, abort the reviews in flight, start nothing new, and report each unfinished task as `aborted`. A signal exits 130 or 143.
+- Evidence: `data.tasks[].aborted` is true for every task that did not finish.
+- Positive: `A commit during the batch aborts it and the unfinished tasks say aborted.`
+- Negative: `Let in-flight reviews finish against a HEAD that no longer matches.`
+
+## REVIEW-BATCH-006
+
+A batch MUST probe each review target at most once while the probe succeeds and MUST NOT cache a failed probe.
+
+- Trigger: Reviews in a batch need target preflight.
+- Action: Share the probe in flight between concurrent reviews and keep a successful answer for the rest of the batch. Forget a failed answer, so the retry of a task probes again.
+- Evidence: A batch of several reviews makes one probe per target, and a retry after a failure makes a new one.
+- Positive: `Five reviews share one successful agy probe.`
+- Negative: `Cache probe-failed and refuse every remaining task.`
+
+## REVIEW-BATCH-007
+
+A batch result MUST report every task's outcome and MUST exit 0 only when every task passed.
+
+- Trigger: A batch ends.
+- Action: Return `BATCH_RESULT`, `BATCH_FAILED` or `BATCH_NOT_RUN` with `data.tasks[]` holding each task's id, base, verify status, review status and reason, `reused`, `retried` and `aborted`, without the full reports, which stay under `.agent-ops/reviews/`. Exit 0 when every task passed, 1 when any review or verification failed, and 2 otherwise. `batch` is started like `review`: it needs `--yes` and trust, and REVIEW-HOST-001 applies to it.
+- Evidence: The envelope code and the exit code agree with the per-task outcomes.
+- Positive: `One FAIL and one NOT_RUN exit 1, so the defect is handled first.`
+- Negative: `Exit 0 while a task is still NOT_RUN.`

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

@@ -1,6 +1,6 @@
 # 審查
 
-English source version: 2026-07-23. Revalidate: when the English specification changes.
+English source version: 2026-09-30. Revalidate: when the English specification changes.
 
 ## REVIEW-INDEPENDENT-001
 
@@ -116,3 +116,73 @@ permission bypass。外部 host runner 不可用時，結果 MUST 保持 NOT_RUN
 - Evidence: 結果的 reason 能區分協議違規與判定結果。
 - Positive: `NOT_RUN：unparseable-output；缺少一條 criterion。`
 - Negative: `因為模型的 JSON 格式錯誤就記錄一次失敗的審查。`
+
+## REVIEW-BATCH-001
+
+批次審查 MUST 只涵蓋指定 parent 的 active 子 task 以及 parent 本身。
+
+- Trigger: 執行 `batch --parent <task-id>`。
+- Action: 依建立順序選出 parent 的 active 子 task，再加上 parent。排除 archived、已完成的 task 與屬於其他 parent 的 task。未知 parent 以 `BATCH_PARENT_NOT_FOUND` 拒絕，非 active 的以 `BATCH_PARENT_NOT_ACTIVE` 拒絕。
+- Evidence: `data.tasks` 依序列出的正是這些 task id。
+- Positive: `兩個 active 子 task 與 parent 被涵蓋；archived 的子 task 不在內。`
+- Negative: `不論 parent 為何，涵蓋 worktree 內所有 task。`
+
+## REVIEW-BATCH-002
+
+每個 task 的 base MUST 依序取自明確旗標、該 task 已記錄的 review base、worktree base。
+
+- Trigger: 決定批次中某個 task 驗證與審查所用的範圍。
+- Action: 子 task 用 `--base`，parent 用 `--parent-base`；否則用該 task 已記錄的 `reviewBase`；再否則用 worktree base。都沒有時回報 `BATCH_BASE_UNKNOWN`。
+- Evidence: `data.tasks[].base` 指出每個 task 使用的 base。
+- Positive: `重跑時沿用每個已 PASS task 記錄的 base，fingerprint 與 attestation 仍然吻合。`
+- Negative: `把 --base 套到 parent，或在不知道 base 時退回 HEAD。`
+
+## REVIEW-BATCH-003
+
+驗證 MUST 一次只跑一個 task，每個 task 的審查 MUST 在它自己的驗證通過後立刻開始，同時進行的審查 MUST NOT 超過 `--width`（預設 2）。
+
+- Trigger: 批次中的 task 需要驗證與審查。
+- Action: 已有 fresh PASS evidence 的 task 略過驗證，判斷方式與 review 預檢相同。其餘串行驗證。task 驗證通過後立刻開始它的審查。驗證失敗的 task 不開審查，其他 task 繼續。
+- Evidence: `data.tasks[].verify` 為 `skipped`、`PASS` 或 `FAIL`，驗證失敗的 task 沒有 review。
+- Positive: `task A 審查的同時驗證 task B。`
+- Negative: `同時跑每個 task 的完整測試。`
+
+## REVIEW-BATCH-004
+
+暫時性的 NOT_RUN MUST 讓其餘審查的 width 降為 1 並只重試一次，其他結果 MUST 為最終結果。
+
+- Trigger: 批次中的某個審查回傳 NOT_RUN。
+- Action: 原因為 `probe-failed`、`stalled`、`timeout`、`quota-exhausted` 或 `network-unreachable` 時，讓所有尚未開始的審查 width 降為 1，並在其餘審查結束後，單獨重試該 task 一次。其他原因不重試，不重試第二次，width 也不再升回。
+- Evidence: 被重試的 task `review.retried` 為 true，第二次暫時性 NOT_RUN 仍是 NOT_RUN。
+- Positive: `task A 的 probe-failed 使 width 降為 1，A 在其他 task 之後再跑一次。`
+- Negative: `對 host-sandboxed 不斷重試直到通過。`
+
+## REVIEW-BATCH-005
+
+來源變動或程序被中斷時，批次 MUST 停止。
+
+- Trigger: HEAD 或工作樹與批次開始時不同，或程序收到 SIGINT 或 SIGTERM。
+- Action: 開始前要求工作樹乾淨，每個步驟前檢查 HEAD 與工作樹。發現變動時，中止進行中的審查，不再開始新步驟，並把每個未完成的 task 回報為 `aborted`。訊號以 130 或 143 結束。
+- Evidence: 每個未完成的 task 其 `data.tasks[].aborted` 為 true。
+- Positive: `批次進行中發生 commit 就中止，未完成的 task 標示 aborted。`
+- Negative: `讓進行中的審查對已不吻合的 HEAD 跑完。`
+
+## REVIEW-BATCH-006
+
+批次 MUST 在探測成功時對每個審查 target 最多探測一次，且 MUST NOT 快取失敗的探測。
+
+- Trigger: 批次中的審查需要 target 預檢。
+- Action: 同時進行的審查共用進行中的探測，成功的答案在批次剩餘期間保留。失敗的答案丟棄，讓 task 的重試再探測一次。
+- Evidence: 多個審查的批次每個 target 只探測一次，失敗後的重試會產生新的探測。
+- Positive: `五個審查共用一次成功的 agy 探測。`
+- Negative: `快取 probe-failed 並拒絕其餘所有 task。`
+
+## REVIEW-BATCH-007
+
+批次結果 MUST 回報每個 task 的結果，且 MUST 僅在每個 task 都通過時以 0 結束。
+
+- Trigger: 批次結束。
+- Action: 回傳 `BATCH_RESULT`、`BATCH_FAILED` 或 `BATCH_NOT_RUN`，`data.tasks[]` 含每個 task 的 id、base、驗證狀態、審查狀態與原因、`reused`、`retried` 與 `aborted`，不含完整報告（報告留在 `.agent-ops/reviews/`）。全數通過以 0 結束，任一審查或驗證失敗以 1 結束，其餘以 2 結束。`batch` 的啟動方式與 `review` 相同：需要 `--yes` 與 trust，且適用 REVIEW-HOST-001。
+- Evidence: envelope code 與 exit code 與各 task 的結果一致。
+- Positive: `一個 FAIL 與一個 NOT_RUN 以 1 結束，先處理缺陷。`
+- Negative: `仍有 task 是 NOT_RUN 卻以 0 結束。`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kylecheng3146/agent-ops",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Evidence-driven development loops for agy, Codex, Claude Code, and opencode",
   "type": "module",
   "license": "MIT",