@kylecheng3146/agent-ops 0.3.7 → 0.4.1

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

@@ -1,11 +1,16 @@
 import { runVerificationCommand } from "../verify/spawn.js";
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { extractFinalMessage } from "./extract.js";
-import { isolatedReviewEnvironment } from "./execute.js";
-import { isNetworkFailure, probeHostReachable, TARGET_API_HOST } from "./host-sandbox.js";
+import { firstComplaint, isolatedReviewEnvironment } from "./execute.js";
+import { isLoginFailure, isNetworkFailure, probeHostReachable, TARGET_API_HOST } from "./host-sandbox.js";
 import { buildProbeInvocation } from "./invocation.js";
+/** A log's last non-empty line: where a CLI that logs to a file puts its error. */
+async function lastLogLine(path) {
+    const text = await readFile(path, "utf8").catch(() => "");
+    return text.split(/\r?\n/u).filter((line) => line.trim().length > 0).at(-1) ?? "";
+}
 const PROBE_PROMPT = "Reply with the single word OK and nothing else.";
 /**
  * Matches the review timeout rather than being "quick": codex at high
@@ -30,6 +35,22 @@ export function probeTimeoutMs(requested) {
  * is not evidence at all.
  */
 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-"))
@@ -67,7 +88,7 @@ export async function probeReviewTarget(target, options) {
                 : {})
         });
         if (invocation === undefined) {
-            return "ineligible";
+            return { result: "ineligible" };
         }
         const spawned = await runVerificationCommand({
             id: `review-probe-${target}`,
@@ -89,29 +110,44 @@ export async function probeReviewTarget(target, options) {
                 : {})
         });
         if (spawned.failureClass === "missing-executable") {
-            return "missing-executable";
+            return { result: "missing-executable" };
         }
         if (spawned.timedOut) {
-            return "timeout";
+            return { result: "timeout" };
         }
-        if (/(?:operation not permitted|permission denied|bind(?:ing)?[^\n]*(?:failed|denied))/iu.test(`${spawned.stderr}\n${spawned.stdout}`)) {
-            return "capability-unavailable";
+        const output = `${spawned.stderr}\n${spawned.stdout}`;
+        // The target's own words, so a failure is never reduced to a guess. agy
+        // writes its errors to the log file the probe hands it, not to stderr.
+        const complaint = async () => firstComplaint(spawned.stderr, spawned.stdout) ??
+            (deep && target === "agy"
+                ? firstComplaint(await lastLogLine(join(directory, "agy.log")))
+                : undefined);
+        if (/(?:operation not permitted|permission denied|bind(?:ing)?[^\n]*(?:failed|denied))/iu.test(output)) {
+            return { result: "capability-unavailable", diagnostic: await complaint() };
         }
         if (!deep) {
-            return spawned.status === "PASS" ? "ok" : "unauthenticated";
+            return spawned.status === "PASS"
+                ? { result: "ok" }
+                : { result: "probe-failed", diagnostic: await complaint() };
         }
         if (spawned.status === "PASS" &&
             extractFinalMessage(target, spawned.stdout) !== undefined) {
-            return "ok";
+            return { result: "ok" };
         }
         // An unreachable API host outranks whatever the CLI printed: a sandbox that
         // withholds the network makes an authenticated CLI say "not logged in".
-        if (isNetworkFailure(`${spawned.stderr}\n${spawned.stdout}`)) {
-            return "network-unreachable";
+        if (isNetworkFailure(output)) {
+            return { result: "network-unreachable", diagnostic: await complaint() };
+        }
+        if (!await (options.reachable ?? probeHostReachable)(TARGET_API_HOST[target])) {
+            return { result: "network-unreachable", diagnostic: await complaint() };
         }
-        return (await (options.reachable ?? probeHostReachable)(TARGET_API_HOST[target]))
-            ? "unauthenticated"
-            : "network-unreachable";
+        const diagnostic = await complaint();
+        // Login is what the output says it is; anything else is a probe that could
+        // not run, and the diagnostic is all the evidence there is.
+        return isLoginFailure(`${output}\n${diagnostic ?? ""}`)
+            ? { result: "unauthenticated", diagnostic }
+            : { result: "probe-failed", diagnostic };
     }
     finally {
         if (deep) {

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

@@ -88,6 +88,10 @@ export function renderReviewResult(result) {
             lines.push("The reviewer could not reach the network. This is not a login " +
                 "problem: run agent-ops outside the sandbox, or grant it escalated execution.");
         }
+        if (result.reason === "probe-failed") {
+            lines.push("The reviewer CLI failed its probe for the reason quoted above. This " +
+                "is not a login problem: fix that cause instead of logging in again.");
+        }
         // Evidence is pinned to the source it was produced from, so any edit to a
         // changed file after the verifier ran — a doc rewritten by a later step
         // counts — voids it. Without the next command the caller reads

package/docs/en/guides/configuration.md

@@ -140,7 +140,11 @@ review preflight finds a target unauthenticated, a 2-second TCP connection to
 that target's API host on port 443 (`cloudcode-pa.googleapis.com` for agy,
 `api.openai.com` for codex, `api.anthropic.com` for claude) decides between the
 two; it only refines the reported reason and never blocks a review. The review suggests
-`doctor --check-auth` only when an authentication failure was detected. Confirm target authentication with:
+`doctor --check-auth` only when an authentication failure was detected. A probe
+that fails without network or login wording is `probe-failed`, never
+`login-required`: the preflight record and `doctor` quote the target's own first
+line (for agy, the last line of its log file when stderr is empty) so the real
+cause is visible instead of guessed. Confirm target authentication with:
 
 ```bash
 agent-ops doctor              # presence only: no tokens, no network
@@ -203,6 +207,52 @@ evidence. Give each editing conversation its own worktree instead:
 - The session's completion gate follows it: Claude Code enters the worktree
   with EnterWorktree, and a host that cannot move a session (agy) is judged by
   the worktree's gate through a redirect the main checkout records.
+- A command knows its session from `--session`, then `AGENT_OPS_SESSION_ID`,
+  then `CODEX_THREAD_ID`, then the id a SessionStart recorded for the
+  checkout. Claude Code's SessionStart appends `AGENT_OPS_SESSION_ID` to its
+  `CLAUDE_ENV_FILE`, so every later Bash command carries it. When a different
+  session started in the same checkout within fifteen minutes, the recorded id
+  is contested: `task create`, `attach` and `status` fail with
+  `SESSION_ID_AMBIGUOUS` instead of acting as the wrong session.
+- A worktree belongs to the session that created it: a file write into
+  another session's worktree is denied (`WORKTREE_OWNED_BY_OTHER_SESSION`),
+  naming the session's own worktree. A session with no baseline (its
+  SessionStart never arrived) gets one at its first tool call, never at Stop.
+- Inside a worktree the project config is the main checkout's, so a branch
+  cannot change the gate, verifiers or trust that judge it before merging; a
+  worktree of a repository whose main checkout has no config uses its own.
+- `agent-ops worktree commit --message <text>` stages and commits every change
+  in the current worktree. Git runs inside agent-ops, not the shell, so a host
+  that cannot prove a shell command stays inside the worktree still lets the
+  session commit; it refuses the main checkout, a worktree another session
+  owns, a caller it cannot identify and an empty change. It stages everything
+  Git does not ignore, so keep stray files out of the worktree.
+- In auto mode the Claude PreToolUse hook also handles `EnterWorktree`: a
+  switch into exactly a worktree recorded for the calling session is allowed
+  without Claude Code's own confirmation, and any other path is denied
+  (`WORKTREE_ENTER_DENIED`, naming the session's worktrees). Run `agent-ops
+  update` once so the hook's matcher includes `EnterWorktree`; `doctor`
+  reports an older matcher as registration drift.
+- 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
+  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`
+  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.
+- `review` and `doctor` take `--output <file>`: the JSON envelope is written
+  there (mode 0600) and one summary line is printed. Use it instead of a shell
+  redirect, which Codex wraps in `zsh -lc` and can only allow by matching the
+  whole command string.
+- Trust is bound to the config hash, so a hand edit of `.agent-ops/config.json`
+  (adding `worktree.setup`, say) leaves the repository untrusted and
+  `WORKTREE_SETUP_UNTRUSTED` stops the next worktree. The one grant is the
+  user's: `agent-ops update` lists the commands it will trust and asks once.
 - In a worktree, verify and review each task but do not run `task complete`
   (Claude Code refuses it inside an isolated worktree session). `agent-ops
   worktree finish <name>` completes every non-archived task in the worktree,

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

@@ -121,6 +121,9 @@ preflight 判定目標未認證時，會再對該目標的 API 主機（agy 為
 `api.anthropic.com`）的 443 埠做 2 秒 TCP 連線測試，據此在兩種原因間擇一；
 它只修正回報的原因，不會阻擋 review。
 只有偵測到認證失敗時，review 才會建議執行 `doctor --check-auth`。
+探測失敗但輸出沒有網路或登入字樣時為 `probe-failed`，不會被當成
+`login-required`：preflight 紀錄與 `doctor` 會引述目標自己的第一行輸出
+（agy 在 stderr 為空時取其 log 檔最後一行），讓真正原因可見而非猜測。
 可用以下指令確認目標的認證狀態：
 
 ```bash
@@ -177,6 +180,44 @@ fingerprint，因此兩個對話修改同一個 checkout 會互相作廢對方
 - Session 的 completion gate 會跟著它：Claude Code 以 EnterWorktree 進入
   worktree；無法移動 session 的 host（agy）則透過主 checkout 記錄的 redirect，
   由 worktree 的 gate 判定。
+- 指令依序以 `--session`、`AGENT_OPS_SESSION_ID`、`CODEX_THREAD_ID`、SessionStart
+  為該 checkout 記錄的 id 得知自己的 session。Claude Code 的 SessionStart 會把
+  `AGENT_OPS_SESSION_ID` 寫入 `CLAUDE_ENV_FILE`，之後每個 Bash 指令都帶有它。
+  十五分鐘內若有另一個 session 在同一 checkout 啟動，記錄的 id 視為有爭議：
+  `task create`、`attach`、`status` 會以 `SESSION_ID_AMBIGUOUS` 失敗，而不是以
+  錯誤的 session 行動。
+- Worktree 屬於建立它的 session：寫入別的 session 的 worktree 會被拒絕
+  （`WORKTREE_OWNED_BY_OTHER_SESSION`），並指出該 session 自己的 worktree。沒有
+  baseline 的 session（SessionStart 沒送達）會在第一次呼叫工具時補建，絕不會在
+  Stop 時補建。
+- 在 worktree 內，專案 config 一律取自主 checkout，因此分支無法在合併前改變判定
+  它自己的 gate、verifier 或 trust；主 checkout 沒有 config 時才使用 worktree 自己的。
+- `agent-ops worktree commit --message <text>` 會暫存並 commit 目前 worktree 的
+  所有變更。Git 由 agent-ops 自己執行而非經過 shell，因此即使 host 無法證明某條
+  shell 指令停留在 worktree 內，session 仍能 commit；它會拒絕主 checkout、別的
+  session 擁有的 worktree、無法辨識的呼叫者，以及沒有變更的情況。它會暫存所有
+  Git 未忽略的檔案，所以請不要把雜檔留在 worktree 裡。
+- 在 auto 模式下，Claude 的 PreToolUse hook 也處理 `EnterWorktree`：切入恰好是
+  為呼叫 session 記錄的 worktree 時，不必經過 Claude Code 自己的確認即放行；其他
+  任何路徑一律拒絕（`WORKTREE_ENTER_DENIED`，並列出該 session 的 worktree）。請
+  執行一次 `agent-ops update`，讓 hook 的 matcher 包含 `EnterWorktree`；`doctor`
+  會把較舊的 matcher 回報為註冊漂移。
+- 當 `worktree.mode` 為 auto，`init` 與 `update` 也會預先授權 session 自己會執行的
+  指令，並在你確認前先列在計畫裡：在 `.claude/settings.local.json` 寫入
+  `agent-ops task`、`verify`、`review`、`worktree`、`doctor` 的 `permissions.allow`，
+  以及 `agent-ops review` 的 `sandbox.excludedCommands`（你原有的項目會保留，計畫只
+  描述該檔案而不印出內容）；若 CLI 找得到 Codex 的 home（`CODEX_HOME`，否則
+  `~/.codex`），另寫入 `rules/agent-ops.rules`，內含 `agent-ops review` 與
+  `doctor --check-auth` 的 allow 規則（含與不含 `AGENT_OPS_HOST=`）。`trust`、
+  `allow-stop`、`init`、`update`、`uninstall` 永遠不會被預先授權。關閉 auto 模式或
+  `uninstall` 會精確移除這些項目；同名但不是 agent-ops 寫的規則檔不會被動到。
+- `review` 與 `doctor` 支援 `--output <file>`：JSON envelope 寫入該檔（權限 0600），
+  並只印出一行摘要。請用它取代 shell 重導向；Codex 會把重導向包成 `zsh -lc`，只能
+  以整串指令比對來放行。
+- Trust 綁定 config hash，因此手動編輯 `.agent-ops/config.json`（例如加入
+  `worktree.setup`）會讓 repository 變成未受信任，`WORKTREE_SETUP_UNTRUSTED` 會擋下
+  下一個 worktree。唯一的授權點屬於使用者：`agent-ops update` 會列出它將信任的指令並
+  詢問一次。
 - 在 worktree 裡對每個 task 執行 verify 與 review，但不要執行 `task complete`
   （Claude Code 在隔離的 worktree session 中會拒絕它）。`agent-ops worktree finish
   <name>` 會在任何 rebase 之前 complete worktree 內每個未封存的 task，先 subtask

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.3.7",
+  "version": "0.4.1",
   "description": "Evidence-driven development loops for agy, Codex, Claude Code, and opencode",
   "type": "module",
   "license": "MIT",