@kylecheng3146/agent-ops 0.4.0 → 0.5.0

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,28 @@ 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 *)"
+    "Bash(agent-ops doctor *)",
+    // The PreToolUse hook still blocks a path this session does not own.
+    "EnterWorktree",
+    // A worktree commit runs the project's pre-commit hook, usually this.
+    "Bash(npx lint-staged *)"
 ];
-/** review talks to the reviewer's API, which the sandbox withholds. */
+/**
+ * review and batch talk to the reviewer's API, which the sandbox withholds;
+ * worktree commit and lint-staged write the main .git, which a worktree's
+ * sandbox cannot.
+ */
 export const CLAUDE_PREAUTH_UNSANDBOXED = [
     "agent-ops review",
-    "agent-ops review *"
+    "agent-ops review *",
+    "agent-ops batch",
+    "agent-ops batch *",
+    "agent-ops worktree commit",
+    "agent-ops worktree commit *",
+    "npx lint-staged",
+    "npx lint-staged *"
 ];
 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,11 +66,32 @@ 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,
+    ...[
+        {
+            pattern: ["agent-ops", "worktree", "commit"],
+            justification: "agent-ops worktree commit runs git hooks, which write the main .git outside the sandbox.",
+            match: "agent-ops worktree commit -m message"
+        },
+        {
+            pattern: ["npx", "lint-staged"],
+            justification: "lint-staged backs up through the main .git, which the sandbox cannot write from a worktree.",
+            match: "npx lint-staged --debug"
+        }
+    ].map((entry) => [
+        "prefix_rule(",
+        `    pattern = ${starlarkList(entry.pattern)},`,
+        '    decision = "allow",',
+        `    justification = ${JSON.stringify(entry.justification)},`,
+        `    match = [${JSON.stringify(entry.match)}],`,
+        '    not_match = ["agent-ops trust grant --scope project --yes"]',
+        ")"
+    ].join("\n")),
     ...[true, false].flatMap((withHost) => {
         const host = withHost ? "AGENT_OPS_HOST=codex " : "";
         const env = `env -u CODEX_SANDBOX_NETWORK_DISABLED ${host}agent-ops`;
@@ -67,6 +103,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"],
@@ -229,7 +272,7 @@ async function codexChange(codexHome, desired) {
                 content: CODEX_RULES_CONTENT,
                 expectedHash: current?.hash ?? null
             },
-            summary: `Writes ${join(codexHome, CODEX_RULES_PATH)}: allow rules for agent-ops review and doctor --check-auth.`,
+            summary: `Writes ${join(codexHome, CODEX_RULES_PATH)}: allow rules for agent-ops review, batch, doctor --check-auth, worktree commit and lint-staged.`,
             ownedContent: true
         };
 }

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/guides/configuration.md

@@ -236,12 +236,15 @@ evidence. Give each editing conversation its own worktree instead:
 - With `worktree.mode` auto, `init` and `update` also pre-authorize what a
   session runs itself, and the plan lists it before you confirm: in
   `.claude/settings.local.json`, `permissions.allow` for `agent-ops task`,
-  `verify`, `review`, `worktree` and `doctor` and `sandbox.excludedCommands`
-  for `agent-ops review` (your other entries are kept, and the plan describes
+  `verify`, `review`, `worktree` and `doctor`, plus `EnterWorktree` (the hook
+  still blocks a path the session does not own) and `npx lint-staged`, and
+  `sandbox.excludedCommands` for `agent-ops review`, `batch`, `worktree commit`
+  and `npx lint-staged` (your other entries are kept, and the plan describes
   the file instead of printing it); and, when the CLI can see Codex's home
   (`CODEX_HOME`, else `~/.codex`), `rules/agent-ops.rules` with allow rules
   for `agent-ops review` and `doctor --check-auth`, with and without
-  `AGENT_OPS_HOST=`. `trust`, `allow-stop`, `init`, `update` and `uninstall`
+  `AGENT_OPS_HOST=`, and for `agent-ops worktree commit` and `npx lint-staged`,
+  so a pre-commit hook can write the main `.git`. `trust`, `allow-stop`, `init`, `update` and `uninstall`
   are never pre-authorized. Turning auto mode off, or `uninstall`, takes
   exactly those entries back out; a rules file of that name agent-ops did not
   write is left alone.

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.`