agentflowctl 0.16.0 → 0.17.0

package/README.md

@@ -198,6 +198,7 @@ Codex 另有幾點差異：
 | `tddSplit` | `true` | 有多位 agent 時，`true` 會把同一任務的測試與實作分給不同 agent |
 | `reviewQuorum` | `1` | 任務與最終程式碼審查需要幾位不同審查者核准 |
 | `planReviewQuorum` | `1` | 計畫需要幾位不同審查者核准 |
+| `reviewConcurrency` | 不限 | 同一輪審查最多幾位審查者同時執行；`1` 為一次一位；說明見表格下方，`doctor` 會顯示目前的設定 |
 | `planArbiter` | `true` | 計畫審查僵持，或修訂一次後仍被要求修改時是否啟用仲裁 |
 | `planReviewLayers` | `{ "enabled": true, "minTasks": 7, "maxGroups": 5, "tasksPerGroup": 3 }` | 任務夠多時把計畫審查拆成索引與任務群；說明見表格下方 |
 | `tieBreak` | `"proceed"` | 兩位仲裁者意見分歧時，`"proceed"` 繼續、`"stop"` 停止 |
@@ -210,6 +211,34 @@ Codex 另有幾點差異：
 
 計畫審查會依任務規模選做法。同時符合下列條件時，每輪先做一次索引審查，再只審查有變動的任務群：任務達到 `planReviewLayers.minTasks` 個；依 description 寫的檔案路徑能分成至少兩群，而且最大一群不超過三分之二；`plan.md` 每個任務都有 `## T-<數字>` 標題。索引審查讀規格、全部任務描述、驗收條件與整體做法，人數是 `planReviewQuorum`。群數最多 `maxGroups`，也不超過任務數除以 `tasksPerGroup`；每群一位審查者，含 `high` 任務的群改由 `planReviewQuorum` 位審查。改了 `plan.md` 的整體做法時所有群都重審；某一次審查失敗時只重跑還沒完成的部分。已達門檻卻不符其他條件時，終端機會印出原因並改由審查者讀完整份規格與計畫。`"planReviewLayers": { "enabled": false }` 可以關閉，`doctor` 會顯示目前的設定。
 
+#### 平行審查
+
+同一輪的審查者（整份計畫審查、分層計畫審查的索引與各群、程式碼審查）預設同時執行，可用 `reviewConcurrency` 限制同時數量（`1` 為一次一位）。
+
+**審查者的環境**
+
+- 每位審查者在自己的臨時 git worktree 裡工作，固定放在 `.agentflowctl/runs/<id>/tmp-review/slot-<N>/`；只有該路徑被占用（例如上次中斷的殘骸）時才改用唯一的子目錄。
+- 看到的是 run 目前的 HEAD、`.flow/` 的複本，以及指向 run worktree 頂層 `node_modules` 的 symlink（有才建）；不含其他未 commit 或被 gitignore 的檔案（例如 `dist/`）。所以審查者改了什麼都不會影響 run 的 worktree 或其他審查者。
+- 唯一的例外是 `node_modules`：它是共用的 symlink，審查者若在臨時 worktree 裡跑安裝，會寫到 run 真正的 `node_modules`。
+- 程式碼審查開始前，會先把 run 的 worktree 還原成 HEAD（清掉驗證階段留下的未 commit 修改與未追蹤產物）。
+
+**結果如何套用**
+
+- 審查結果一完成就存進 `.agentflowctl/runs/<id>/parallel-review/`，全部審查者跑完後才依固定順序逐一套用結果與交接事項。
+- 因此即使 `reviewConcurrency` 為 `1`，同一輪的審查者也看不到彼此本輪新增或結掉的交接事項，核准與否也依它開始時看到的帳本判斷。例如一位審查者結掉了某個未結事項，另一位核准卻沒有結掉它，後者會被判交接不合格而多重跑一次（重跑時就看得到該事項已結）。
+- 同時執行時，引擎印出的訊息會加上 `[審查者]` 前綴；agent 自己的輸出（`-v` 時印出的內容、回報的疑慮）不加。
+
+**中斷與 resume**
+
+- 任何時候 Ctrl-C 或被中斷，之後 `resume` 只會補跑沒完成的審查者，已完成的不重跑。
+- 已存檔的審查只在同一輪、計畫或程式碼沒變，而且交接帳本沒有被這一輪以外的呼叫（例如修正者）動過時沿用，否則重審。
+- 中斷留下的臨時 worktree（`.agentflowctl/runs/<id>/tmp-review/`）在該 run 下次 `resume`（或 `clean`）時自動清掉。
+
+**額度與預算**
+
+- 若有審查者的額度用完，其他審查者仍會跑完並存檔，全部結束後才暫停；但同一家 agent 還沒啟動的審查者也會略過（這家在這次執行中已確認額度用完），`resume` 時再和額度用完的那位一起補跑。
+- 審查只在 `maxAgentRuns` 剩餘的次數內啟動：預算不夠整輪時只啟動預算內的審查者（結果照樣存檔），run 以 `agent_budget` 失敗，用 `resume <id> --max-agent-runs <次數>` 調高後只補跑沒跑的。
+
 審查意見的處理寫在 `.flow/plan-replies.md`，每輪覆寫，不寫進 `plan.md` 文末。下一輪索引會看到整份回應；任務群只看到自己的 `## T-<數字>` 節。
 
 `install`、`test`、`checks` 未設定時，會依 `packageManager`、lockfile 和 `package.json` scripts 偵測。完整範例見 [examples/flow.config.json](examples/flow.config.json)。專案設定每一步都會重新讀取，但已建立 run 的參與 agent 與執行次數上限會沿用建立時的值；要調高後者請用 `resume --max-agent-runs`。

package/dist/agents/claude.js

@@ -1,4 +1,4 @@
-import { mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { num, str, toolDetail, tryJson } from "./types.js";
 /**
@@ -19,7 +19,13 @@ function settingsFile(o) {
     };
     mkdirSync(o.runDir, { recursive: true });
     const path = join(o.runDir, "claude-settings.json");
-    writeFileSync(path, JSON.stringify(settings, null, 2));
+    const content = JSON.stringify(settings, null, 2);
+    // 平行審查時多個 claude 同時啟動：內容沒變就不寫；要寫時先寫暫存檔再 rename，別的行程不會讀到被截斷的檔案而在沒有 deny list 下執行
+    if (existsSync(path) && readFileSync(path, "utf8") === content)
+        return path;
+    const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, content);
+    renameSync(tmp, path);
     return path;
 }
 export const claude = {

package/dist/cleanup.js

@@ -2,6 +2,7 @@ import { existsSync, readdirSync, rmSync } from "node:fs";
 import { git, removeWorktree } from "./git.js";
 import { projectRoot, runDir, runsDir, worktreeDir, worktreesDir } from "./paths.js";
 import { getRun } from "./store.js";
+import { cleanupTempWorktrees } from "./tempWorktree.js";
 /**
  * 移除一個 run 的 worktree 與紀錄，分支保留。
  * 不需要 state.json：中斷在建立 worktree 之後、寫入紀錄之前留下的孤兒也能清。
@@ -14,6 +15,8 @@ export async function cleanRun(id) {
     const root = projectRoot();
     const wt = worktreeDir(id);
     const found = existsSync(wt) || existsSync(runDir(id));
+    // 平行審查中斷留下的臨時 worktree：locked 的登記 prune 不會清，要先處理；tmp-review/ 已不在時也要查
+    await cleanupTempWorktrees(id, { force: true });
     if (existsSync(wt)) {
         // git 不認得這個資料夾時（登記已被 prune、或 worktree add 做到一半）改成直接刪
         await removeWorktree(root, wt).catch(() => rmSync(wt, { recursive: true, force: true }));

package/dist/cli.js

@@ -544,6 +544,7 @@ async function doctor() {
     console.log(`\n單一 run 的 agent 執行上限：${cfg.maxAgentRuns} 次`);
     console.log(`修正策略：${cfg.fixStrategy}　測試與實作分開：${cfg.tddSplit ? "是" : "否"}`);
     console.log(`程式碼審查人數：${cfg.reviewQuorum}　計畫審查人數：${cfg.planReviewQuorum}　計畫仲裁：${cfg.planArbiter ? "開啟" : "關閉"}`);
+    console.log(`同一輪審查者同時執行上限：${cfg.reviewConcurrency ?? "不限"}`);
     const layers = cfg.planReviewLayers;
     console.log(`計畫分層審查：${layers.enabled ? `任務達 ${layers.minTasks} 個時開啟，最多 ${layers.maxGroups} 群，每群平均至少 ${layers.tasksPerGroup} 個任務` : "關閉"}`);
 }

package/dist/engine.js

@@ -5,11 +5,13 @@ import { arbitrationDecision } from "./arbitration.js";
 import { detectProjectDefaults, usesTestFramework, withProjectDefaults } from "./detect.js";
 import { escapeXml, opinion, reviewIssue } from "./feedback.js";
 import { changedFiles, commitAll, discardChanges, git, headCommit, resetTo } from "./git.js";
-import { acceptHandoff, openActions, prepareHandoff, previewHandoff, readHandoff, recoverHandoff, reviewHandoffGate, validateHandoffResponse } from "./handoff.js";
+import { acceptHandoff, openActions, prepareHandoff, previewHandoff, readHandoff, recoverHandoff, responsePath, reviewHandoffGate, validateHandoffResponse } from "./handoff.js";
 import { flowDir, logDir, planArbitrationPath, planReviewStatePath, projectRoot, runDir, worktreeDir } from "./paths.js";
 import { CMD_AGENT, nextLogFile } from "./logs.js";
 import { exec } from "./proc.js";
 import { arbiterPanel, availableAgent, fixAgent, planAgent, planFixAgent, reviewers, specAgent, taskAgents } from "./roles.js";
+import { dropCall, loadCalls, openRound, runPool, saveCall, storedCallValid } from "./parallelReview.js";
+import { cleanupTempWorktrees, withTempWorktree } from "./tempWorktree.js";
 import { resolveAgent, runAgent, runCommand } from "./runner.js";
 import { AcceptanceList, ArbiterResult, ConsistentReviewResult, RepoConfig, TaskList, } from "./schemas.js";
 import { addRetry, addSubstitution, addUsage, agentRuns, saveRun } from "./store.js";
@@ -22,8 +24,8 @@ const info = (run, msg) => console.log(`[${run.id}] ${msg}`);
 const logHint = (run, seq) => `（agentflowctl logs ${run.id} ${seq}）`;
 const flowFile = (run, name) => join(flowDir(run.id), name);
 const to = (run, stage) => ({ ...run, stage });
-function target(run, step, agent) {
-    return { runId: run.id, cwd: worktreeDir(run.id), logFile: nextLogFile(logDir(run.id), run.stage, step, agent), stage: run.stage, step };
+function target(run, step, agent, cwd = worktreeDir(run.id)) {
+    return { runId: run.id, cwd, logFile: nextLogFile(logDir(run.id), run.stage, step, agent), stage: run.stage, step };
 }
 /** 額度用完而必須停下：審查類步驟，或所有 agent 的額度都用完 */
 export class QuotaPause extends Error {
@@ -50,7 +52,8 @@ function handoffKey(run, step, slot, agent) {
 }
 async function agentStep(run, planned, step, prompt, mode) {
     const cfg = loadRepoConfig();
-    const reset = mode.reset ?? (() => discardChanges(worktreeDir(run.id)));
+    const say = (msg) => info(run, mode.tag ? `[${mode.tag}] ${msg}` : msg);
+    const reset = mode.reset ?? (mode.workspace ? () => { } : () => discardChanges(worktreeDir(run.id)));
     let agent = planned;
     for (;;) {
         if (exhausted.has(agent)) {
@@ -62,16 +65,16 @@ async function agentStep(run, planned, step, prompt, mode) {
                 throw new QuotaPause(`所有 agent 的額度都已用完（${[...exhausted].join("、")}）`);
             const note = step.endsWith("-code") && sub === run.lastTestsAuthor ? "測試與實作由同一家負責" : undefined;
             addSubstitution(run.id, { step, planned, actual: sub, note });
-            info(run, `🔁 ${agent} 額度已用完，${step} 由 ${sub} 代打${note ? `（注意：${note}）` : ""}`);
+            say(`🔁 ${agent} 額度已用完，${step} 由 ${sub} 代打${note ? `（注意：${note}）` : ""}`);
             agent = sub;
         }
         const selected = selectModel(run, cfg, agent, step, /^T-\d+-/.test(step) ? loadOrderedTasks(run)[run.taskIndex]?.complexity : undefined, mode.kind === "review" ? agent : undefined, mode.modelScope);
-        info(run, `🤖 ${step}：${agent} 使用 ${selected.name ?? "CLI 預設（名稱未知）"}${selected.insufficient ? `（低於目標 ${selected.targetStrength}）` : ""}`);
+        say(`🤖 ${step}：${agent} 使用 ${selected.name ?? "CLI 預設（名稱未知）"}${selected.insufficient ? `（低於目標 ${selected.targetStrength}）` : ""}`);
         const callKey = handoffKey(run, step, mode.slot ?? 0, agent);
-        prepareHandoff(run.id, callKey, handoffTarget(run), mode.blind ?? false);
-        const r = await runAgent(agent, { ...resolveAgent(cfg, agent), model: selected.name }, { ...target(run, step, agent), strength: selected.strength, targetStrength: selected.targetStrength }, prompt);
+        prepareHandoff(run.id, callKey, handoffTarget(run), mode.blind ?? false, mode.workspace?.flow);
+        const r = await runAgent(agent, { ...resolveAgent(cfg, agent), model: selected.name }, { ...target(run, step, agent, mode.workspace?.dir), strength: selected.strength, targetStrength: selected.targetStrength }, prompt);
         if (r.resolvedModel && r.resolvedModel !== selected.name)
-            info(run, `   ↳ CLI 回報實際模型：${r.resolvedModel}`);
+            say(`   ↳ CLI 回報實際模型：${r.resolvedModel}`);
         addUsage(run.id, { stage: step, agent, model: selected.name, resolvedModel: r.resolvedModel,
             strength: selected.strength, targetStrength: selected.targetStrength, usageReported: r.usageReported,
             inputTokens: r.inputTokens, outputTokens: r.outputTokens, cacheReadTokens: r.cacheReadTokens, cacheWriteTokens: r.cacheWriteTokens });
@@ -79,14 +82,16 @@ async function agentStep(run, planned, step, prompt, mode) {
             reportMeta(run, agent, r);
             return { r, agent, step, callKey };
         }
-        info(run, `⛽ ${agent} 的額度已用完`);
+        say(`⛽ ${agent} 的額度已用完`);
         exhausted.add(agent);
         await reset();
         // 迴圈回到開頭：review 會停下，write 會找代打
     }
 }
 /** 原有關卡已通過後才接受交接；失敗回覆不進入正式紀錄。 */
-function finishHandoff(run, outcome, role, gate) {
+function finishHandoff(run, outcome, role, gate, 
+/** 平行審查：關卡以這個呼叫啟動時看到的帳本判斷（存檔裡的 base），套用仍落在目前的帳本 */
+base) {
     const parsed = validateHandoffResponse(run.id);
     if (!parsed.ok)
         return parsed.error;
@@ -94,7 +99,7 @@ function finishHandoff(run, outcome, role, gate) {
         const source = {
             stage: run.stage, step: outcome.step, agent: outcome.agent, callKey: outcome.callKey,
         };
-        const preview = previewHandoff(readHandoff(run.id), outcome.callKey, source, parsed.data, role);
+        const preview = previewHandoff(base ?? readHandoff(run.id), outcome.callKey, source, parsed.data, role);
         if (gate) {
             const error = reviewHandoffGate(preview, gate.target, gate.verdict);
             if (error)
@@ -330,38 +335,115 @@ async function planReviewStage(run) {
     const layered = loadLayeredPlan(run, cfg);
     return layered ? planReviewLayered(run, layered, cfg) : planReviewFull(run, cfg);
 }
+const readIfExists = (path) => (existsSync(path) ? readFileSync(path, "utf8") : null);
 /**
- * 整份審查與分層審查共用的單次呼叫：還原審查者改過的計畫檔、驗證裁決與交接。
- * 失敗時回傳已呼叫 retry 的 run、沒有 collected，呼叫端應直接回傳這個 run。
+ * 平行階段：每位審查者在自己的臨時 worktree 執行，成功的結果立刻存檔。
+ * 這個階段不改 run、不寫交接帳本、不呼叫 retry。
+ * - 已有同一輪存檔、且仍有效的呼叫直接沿用（resume）；帳本在它啟動後被本輪以外的呼叫（例如修正者）動過就作廢重跑
+ * - 預算（maxAgentRuns）不夠時只啟動預算內的，回傳 undefined，呼叫端應原樣回傳 run，由 advance 判定 agent_budget
+ * - 有呼叫額度用完時，其他呼叫照常跑完並存檔，最後才丟 QuotaPause
  */
-async function collectPlanReview(run, spec) {
+async function executeReviewCalls(run, cfg, scope, fingerprint, calls) {
+    if (calls.length === 0)
+        return { dir: "", finished: [] };
+    // openRound、loadCalls 與有效性檢查都要在 runPool 啟動任何呼叫之前（loadCalls 會刪 .tmp）
+    const dir = openRound(run.id, scope, fingerprint);
+    const saved = loadCalls(dir);
+    const live = readHandoff(run.id);
+    const round = [...saved.values()];
+    for (const [key, stored] of [...saved]) {
+        if (storedCallValid(stored, live, round))
+            continue;
+        dropCall(dir, key);
+        saved.delete(key);
+    }
+    let budget = run.maxAgentRuns - agentRuns(run.id);
+    // 已有存檔的不花預算；其餘依序佔預算，超出的這次不啟動
+    const launch = calls.filter((call) => saved.has(call.key) || budget-- > 0);
+    const limit = cfg.reviewConcurrency ?? Infinity;
+    const tagged = limit > 1 && launch.filter((call) => !saved.has(call.key)).length > 1;
+    // 預算內能跑的照跑並存檔，之後 resume 加大預算就不必重付
+    const executed = await runPool(launch, limit, (call) => executeOne(run, dir, saved, call, tagged));
+    const quota = executed.find((item) => "quota" in item);
+    if (quota)
+        throw new QuotaPause(quota.quota);
+    if (launch.length < calls.length)
+        return undefined;
+    return { dir, finished: executed };
+}
+async function executeOne(run, dir, saved, call, tagged) {
+    const reused = saved.get(call.key);
+    if (reused) {
+        info(run, `   ↪ 沿用本輪已完成的審查（${call.reviewer}）`);
+        return { stored: reused, ok: true };
+    }
+    try {
+        return await withTempWorktree(run.id, `slot-${call.slot}`, async (ws) => {
+            rmSync(join(ws.flow, call.output), { force: true });
+            // 平行階段不動帳本，同一批呼叫看到的都是這一份；序列收尾以它評估這個呼叫的核准門檻
+            const base = readHandoff(run.id);
+            const outcome = await agentStep(run, call.reviewer, call.step, call.prompt, {
+                kind: "review", slot: call.slot, modelScope: call.scope, workspace: ws, tag: tagged ? call.reviewer : undefined,
+            });
+            const stored = {
+                key: call.key, reviewer: call.reviewer, agent: outcome.agent, step: outcome.step, callKey: outcome.callKey,
+                summary: outcome.r.summary,
+                output: readIfExists(join(ws.flow, call.output)),
+                handoffResponse: readIfExists(responsePath(run.id, ws.flow)),
+                base,
+            };
+            if (outcome.r.ok)
+                saveCall(dir, stored); // 先存檔，臨時 worktree 才會被移除
+            return { stored, ok: outcome.r.ok };
+        });
+    }
+    catch (err) {
+        if (err instanceof QuotaPause)
+            return { quota: err.message };
+        throw err;
+    }
+}
+/** 序列收尾第一步：把存檔的內容放回共用 .flow/，之後就能沿用原有的驗證與交接程式 */
+function replay(run, stored, output) {
+    mkdirSync(flowDir(run.id), { recursive: true });
+    const put = (path, text) => (text === null ? rmSync(path, { force: true }) : writeFileSync(path, text));
+    put(flowFile(run, output), stored.output);
+    put(responsePath(run.id), stored.handoffResponse);
+}
+/** 存檔內容還原成 finishHandoff 需要的 StepOutcome */
+function storedOutcome(stored, ok) {
+    return {
+        r: { ok, quotaExhausted: false, summary: stored.summary, usageReported: false },
+        agent: stored.agent, step: stored.step, callKey: stored.callKey,
+    };
+}
+/**
+ * 整份審查與分層審查共用的序列收尾：驗證裁決與交接。
+ * 失敗時回傳已呼叫 retry 的 run、沒有 collected，呼叫端應直接回傳這個 run；
+ * 不合格的存檔結果一併刪掉，否則同一輪重跑會反覆讀到同一份。
+ */
+function applyPlanReview(run, spec, done, dir) {
     const { reviewer, step } = spec;
-    const snap = snapshotPlan(run, PLAN_REPLY_FILES);
-    rmSync(flowFile(run, spec.output), { force: true });
-    const outcome = await agentStep(run, reviewer, step, spec.prompt, {
-        kind: "review", slot: spec.slot, modelScope: spec.scope,
-        reset: async () => { await discardChanges(worktreeDir(run.id)); restorePlan(run, snap); },
-    });
-    await discardChanges(worktreeDir(run.id));
-    const tampered = restorePlan(run, snap);
-    if (tampered.length)
-        info(run, `   ↩️  已還原審查者修改的檔案：${tampered.join(", ")}`);
-    const stop = (category, reason) => ({
-        run: retry(recordModelReviewFailure(run, step, reviewer, spec.scope), "plan-review-run", reason, "plan_review", category),
-    });
-    if (!outcome.r.ok)
-        return stop("agent_error", `Agent 執行失敗：${outcome.r.summary}`);
+    const stop = (category, reason) => {
+        dropCall(dir, spec.key);
+        return { run: retry(recordModelReviewFailure(run, step, reviewer, spec.scope), "plan-review-run", reason, "plan_review", category) };
+    };
+    if (!done.ok)
+        return stop("agent_error", `Agent 執行失敗：${done.stored.summary}`);
+    replay(run, done.stored, spec.output);
     const review = readJsonFile(flowFile(run, spec.output), ConsistentReviewResult);
     if (!review.ok)
         return stop("format_invalid", review.error);
-    // 群審查不帶關卡：索引要求修改並新增事項後，群的核准不算矛盾；最後由 planSettled 檢查未結事項
-    const handoffError = finishHandoff(run, outcome, "reviewer", spec.gated ? { target: "plan", verdict: review.data.verdict } : undefined);
+    // 群審查不帶關卡：索引要求修改並新增事項後，群的核准不算矛盾；最後由 planSettled 檢查未結事項。
+    // 門檻以這個呼叫自己看到的帳本評估：同輪其他審查者剛新增（或崩潰前已套用）的事項它沒看過，不能拿來判它矛盾
+    const handoffError = finishHandoff(run, storedOutcome(done.stored, true), "reviewer", spec.gated ? { target: "plan", verdict: review.data.verdict } : undefined, done.stored.base);
     if (handoffError)
         return stop("handoff_invalid", handoffError);
     run = clearModelReviewFailure(run, step, reviewer, spec.scope);
     // 審查紀錄移到 worktree 外面：之後的仲裁者看不到是哪一家提的意見
     mkdirSync(join(runDir(run.id), "reviews"), { recursive: true });
-    renameSync(flowFile(run, spec.output), join(runDir(run.id), "reviews", spec.archive));
+    writeFileSync(join(runDir(run.id), "reviews", spec.archive), readFileSync(flowFile(run, spec.output)));
+    rmSync(flowFile(run, spec.output), { force: true });
     if (review.data.verdict === "approve") {
         info(run, `   ✓ ${reviewer} 核准${spec.subject}`);
         return { run, collected: { reviewer, verdict: "approve", issueLines: [] } };
@@ -414,14 +496,19 @@ async function planReviewFull(run, cfg) {
     const author = run.planWriter ?? planAgent(run.cycle, run.id);
     const round = (run.attempts["plan-review"] ?? 0) + 1;
     const panel = reviewers(run.cycle, author, cfg.planReviewQuorum, `${run.id}:plan-review:${round}`);
+    const specs = panel.map((reviewer, slot) => ({
+        key: `full:${reviewer}`, reviewer, step: "plan-review", slot, gated: true, subject: "計畫",
+        prompt: renderPrompt("plan-review", { reviewer, author, requirement: run.requirement }),
+        output: "plan-review.json", archive: `plan-review-${round}-${reviewer}.json`,
+    }));
+    for (const spec of specs)
+        info(run, `🧐 計畫審查第 ${round} 輪（${spec.reviewer}，作者 ${author}）`);
+    const ran = await executeReviewCalls(run, cfg, "plan-review", `${round}:${currentPlanKey(run)}`, specs);
+    if (!ran)
+        return run;
     const calls = [];
-    for (const [slot, reviewer] of panel.entries()) {
-        info(run, `🧐 計畫審查第 ${round} 輪（${reviewer}，作者 ${author}）`);
-        const passed = await collectPlanReview(run, {
-            reviewer, step: "plan-review", slot, gated: true, subject: "計畫",
-            prompt: renderPrompt("plan-review", { reviewer, author, requirement: run.requirement }),
-            output: "plan-review.json", archive: `plan-review-${round}-${reviewer}.json`,
-        });
+    for (const [i, spec] of specs.entries()) {
+        const passed = applyPlanReview(run, spec, ran.finished[i], ran.dir);
         run = passed.run;
         if (!passed.collected)
             return run;
@@ -490,35 +577,17 @@ async function planReviewLayered(run, layered, cfg) {
     const calls = [];
     // 沿用的呼叫也佔一格，重跑時每個呼叫的 slot 才不會變
     let nextSlot = 0;
-    /** 執行或沿用一次呼叫；失敗時回傳 false，run 已是 retry 後的狀態 */
-    const runCall = async (key, taskIds, label, spec) => {
-        const slot = nextSlot++;
+    const items = [];
+    const add = (key, taskIds, label, spec) => {
         const reused = done.get(key);
-        if (reused) {
+        if (reused)
             info(run, `   ↪ 沿用本輪已完成的${label}（${reused.reviewer}）`);
-            calls.push(reused);
-            return true;
-        }
-        info(run, `🧐 ${label}第 ${round} 輪（${spec.reviewer}，作者 ${author}）`);
-        // run 是外層參數，刻意在閉包裡更新：後續呼叫與最後的彙總都要看到 retry、clearModelReviewFailure 之後的 run
-        const passed = await collectPlanReview(run, { ...spec, slot });
-        run = passed.run;
-        if (!passed.collected)
-            return false;
-        // 真的執行並成功就是有進展：同一輪不同呼叫輪流失敗時，不會累計到重試上限而讓 run 失敗。
-        // 進度寫在 round 裡、不會重跑，所以一輪最多失敗「呼叫數 × maxAttempts」次。
-        // 整份審查每次重跑整輪，不能這樣歸零，否則同一位審查者反覆失敗會無限重試。
-        const attempts = { ...run.attempts };
-        delete attempts["plan-review-run"];
-        run = { ...run, attempts };
-        const call = { key, ...passed.collected, ...(taskIds ? { taskIds } : {}) };
-        progress.calls.push(call);
-        calls.push(call);
-        saveState({ version: 1, ...(reviewed ? { reviewed } : {}), round: progress });
-        return true;
+        else
+            info(run, `🧐 ${label}第 ${round} 輪（${spec.reviewer}，作者 ${author}）`);
+        items.push({ key, taskIds, reused, spec: { ...spec, slot: nextSlot++, key } });
     };
     for (const reviewer of panel) {
-        const ok = await runCall(`index:${reviewer}`, undefined, "計畫索引審查", {
+        add(`index:${reviewer}`, undefined, "計畫索引審查", {
             reviewer, step: "plan-review", gated: true, subject: "計畫索引",
             prompt: renderPrompt("plan-review-index", {
                 reviewer, author, requirement: run.requirement,
@@ -529,8 +598,6 @@ async function planReviewLayered(run, layered, cfg) {
             }),
             output: "plan-review.json", archive: `plan-review-${round}-${reviewer}.json`,
         });
-        if (!ok)
-            return run;
     }
     for (const group of layered.dirty) {
         const groupTasks = layered.tasks.filter((task) => group.taskIds.includes(task.id));
@@ -538,7 +605,7 @@ async function planReviewLayered(run, layered, cfg) {
         const neighbors = neighborTasks(layered.tasks, group.taskIds).map(({ id, title, description, dependsOn }) => ({ id, title, description, dependsOn }));
         const groupPanel = reviewers(run.cycle, author, groupReviewerCount(groupTasks, cfg.planReviewQuorum), `${run.id}:plan-group:${group.id}:${round}`);
         for (const reviewer of groupPanel) {
-            const ok = await runCall(`group:${group.id}:${group.taskIds.join(",")}:${reviewer}`, group.taskIds, `計畫群 ${group.id} 審查`, {
+            add(`group:${group.id}:${group.taskIds.join(",")}:${reviewer}`, group.taskIds, `計畫群 ${group.id} 審查`, {
                 reviewer, step: "plan-review-group", gated: false, subject: `任務群 ${group.id}`, scope: group.id,
                 prompt: renderPrompt("plan-review-group", {
                     reviewer, author, groupId: group.id,
@@ -551,10 +618,32 @@ async function planReviewLayered(run, layered, cfg) {
                 }),
                 output: "plan-review-group.json", archive: `plan-review-${round}-${group.id}-${reviewer}.json`,
             });
-            if (!ok)
-                return run;
         }
     }
+    // 平行執行還沒套用的呼叫；沿用的（已套用、記在進度檔裡）不再跑
+    const pending = items.filter((item) => !item.reused);
+    const ran = await executeReviewCalls(run, cfg, "plan-review", `${round}:${planKey}`, pending.map((item) => item.spec));
+    if (!ran)
+        return run;
+    // 序列收尾，依原本的順序逐一套用；每套用一個就寫進度檔，中途被中斷也不會重複套用
+    const applied = new Map();
+    for (const [i, item] of pending.entries()) {
+        const passed = applyPlanReview(run, item.spec, ran.finished[i], ran.dir);
+        run = passed.run;
+        if (!passed.collected)
+            return run;
+        // 真的執行並成功就是有進展：同一輪不同呼叫輪流失敗時，不會累計到重試上限而讓 run 失敗。
+        // 進度寫在 round 裡、不會重跑，所以一輪最多失敗「呼叫數 × maxAttempts」次。
+        // 整份審查每次重跑整輪，不能這樣歸零，否則同一位審查者反覆失敗會無限重試。
+        const attempts = { ...run.attempts };
+        delete attempts["plan-review-run"];
+        run = { ...run, attempts };
+        const call = { key: item.key, ...passed.collected, ...(item.taskIds ? { taskIds: item.taskIds } : {}) };
+        progress.calls.push(call);
+        applied.set(item.key, call);
+        saveState({ version: 1, ...(reviewed ? { reviewed } : {}), round: progress });
+    }
+    calls.push(...items.map((item) => item.reused ?? applied.get(item.key)));
     // 只放這一輪真的審過的群（含沿用的），沒審到的任務才留得住前次 verdict
     const groupVerdicts = calls.flatMap((call) => call.taskIds ? [{ taskIds: call.taskIds, verdict: call.verdict }] : []);
     saveState({ version: 1, reviewed: applyReviewVerdicts(reviewed, layered.tasks, layered.acceptance, layered.planMd, groupVerdicts) });
@@ -956,32 +1045,42 @@ async function codeReview(run, opts) {
     const cfg = loadRepoConfig();
     const repo = worktreeDir(run.id);
     const panel = reviewers(run.cycle, run.lastWriter, cfg.reviewQuorum, opts.seed, opts.testAuthor, opts.prefer);
+    // 審查的是 HEAD：先清掉驗證階段留下的未 commit 修改與未追蹤產物，之後修正時的 commitAll 才不會把它們帶進去（.flow/ 在 exclude 內不受影響）
+    await discardChanges(repo);
     writeFileSync(flowFile(run, "diff.patch"), await git(repo, "diff", `${opts.base}...HEAD`));
     const authors = [...new Set((await git(repo, "log", "--format=%s", `${opts.base}..HEAD`)).match(/\[[^\]]+\]$/gm) ?? [])]
         .map((s) => s.slice(1, -1));
+    const specs = panel.map((reviewer, slot) => ({
+        key: `${slot}:${reviewer}`, slot, reviewer, step: opts.step,
+        prompt: opts.prompt(reviewer, authors.join("、") || "未知"),
+        output: "review.json",
+    }));
+    for (const spec of specs)
+        info(run, `👀 ${opts.label}（${spec.reviewer}）`);
+    // 指紋含 HEAD：程式碼被修過就不沿用舊的審查結果
+    const ran = await executeReviewCalls(run, cfg, opts.step, `${opts.seed}|${await headCommit(repo)}|${opts.base}`, specs);
+    if (!ran)
+        return { run };
     const issues = [];
     let objector;
-    for (const [slot, reviewer] of panel.entries()) {
-        info(run, `👀 ${opts.label}（${reviewer}）`);
-        rmSync(flowFile(run, "review.json"), { force: true });
-        const snap = snapshotPlan(run, LOCKED_FILES);
-        const outcome = await agentStep(run, reviewer, opts.step, opts.prompt(reviewer, authors.join("、") || "未知"), {
-            kind: "review", slot, reset: async () => { await discardChanges(repo); restorePlan(run, snap); },
-        });
-        const { r } = outcome;
-        await discardChanges(repo); // 審查者不可改程式碼
-        const tampered = restorePlan(run, snap); // .flow/ 不受 git 管理，要另外還原
-        if (tampered.length)
-            info(run, `   ↩️  已還原審查者修改的檔案：${tampered.join(", ")}`);
-        if (!r.ok)
-            return { run: retry(opts.step === "review" ? recordModelReviewFailure(run, "review", reviewer) : run, opts.runKey, `Agent 執行失敗：${r.summary}`, opts.backTo, "agent_error") };
+    for (const [i, spec] of specs.entries()) {
+        const reviewer = spec.reviewer;
+        const done = ran.finished[i];
+        const fail = (reason, category) => {
+            dropCall(ran.dir, spec.key); // 不合格的存檔不能留著，否則同一輪重跑會讀到同一份
+            return { run: retry(opts.step === "review" ? recordModelReviewFailure(run, "review", reviewer) : run, opts.runKey, reason, opts.backTo, category) };
+        };
+        if (!done.ok)
+            return fail(`Agent 執行失敗：${done.stored.summary}`, "agent_error");
+        replay(run, done.stored, "review.json");
         const review = readJsonFile(flowFile(run, "review.json"), ConsistentReviewResult);
         if (!review.ok)
-            return { run: retry(opts.step === "review" ? recordModelReviewFailure(run, "review", reviewer) : run, opts.runKey, review.error, opts.backTo, "format_invalid") };
+            return fail(review.error, "format_invalid");
         const gate = opts.gate ? { target: "code", verdict: review.data.verdict } : undefined;
-        const handoffError = finishHandoff(run, outcome, "reviewer", gate);
+        // 門檻以這個呼叫自己看到的帳本評估：同輪其他審查者剛新增（或崩潰前已套用）的事項它沒看過，不能拿來判它矛盾
+        const handoffError = finishHandoff(run, storedOutcome(done.stored, true), "reviewer", gate, done.stored.base);
         if (handoffError)
-            return { run: retry(opts.step === "review" ? recordModelReviewFailure(run, "review", reviewer) : run, opts.runKey, handoffError, opts.backTo, "handoff_invalid") };
+            return fail(handoffError, "handoff_invalid");
         if (opts.step === "review")
             run = clearModelReviewFailure(run, "review", reviewer);
         renameSync(flowFile(run, "review.json"), flowFile(run, opts.saveAs(reviewer)));
@@ -1061,6 +1160,7 @@ const STAGES = {
 export async function advance(initial) {
     let run = initial;
     recoverHandoff(run.id);
+    await cleanupTempWorktrees(run.id); // 上次被中斷（Ctrl-C、SIGTERM、當機）時留下的平行審查臨時 worktree
     for (;;) {
         if (["done", "failed", "awaiting_approval", "paused"].includes(run.stage))
             return run;

package/dist/handoff.js

@@ -5,7 +5,8 @@ import { z } from "zod";
 import { flowDir, handoffPath, runDir } from "./paths.js";
 import { HandoffLedger, HandoffResponse, HandoffSource } from "./schemas.js";
 import { readJsonFile } from "./util.js";
-const responsePath = (id) => join(flowDir(id), "handoff-response.json");
+/** agent 寫交接回覆的位置；平行審查者用自己臨時 worktree 的 .flow/ */
+export const responsePath = (id, flow = flowDir(id)) => join(flow, "handoff-response.json");
 const receiptsDir = (id) => join(runDir(id), "handoff-receipts");
 const keyHash = (key) => createHash("sha256").update(key).digest("hex").slice(0, 16);
 const receiptPath = (id, key) => join(receiptsDir(id), `${keyHash(key)}.json`);
@@ -71,7 +72,7 @@ export function mergeHandoff(id, callKey, source, response, role) {
     return next;
 }
 /** 只把目前步驟需要處理的事項投影給 agent。 */
-export function prepareHandoff(id, _callKey, target, blind) {
+export function prepareHandoff(id, _callKey, target, blind, flow = flowDir(id)) {
     const items = readHandoff(id).issues.filter((item) => item.targetStage === target && (item.kind === "info" || item.status === "open" || item.status === "proposed_resolved"));
     const render = (item) => {
         const source = blind ? "" : `\n來源：${item.source.stage}／${item.source.agent}`;
@@ -85,12 +86,12 @@ export function prepareHandoff(id, _callKey, target, blind) {
         actions.length ? `## 待處理事項（action，可在 dispositions 處置）\n\n${actions.join("\n\n")}` : "",
         infos.length ? `## 參考資訊（info，只供參考，不要放進 dispositions）\n\n${infos.join("\n\n")}` : "",
     ].filter(Boolean);
-    mkdirSync(flowDir(id), { recursive: true });
-    writeFileSync(join(flowDir(id), "handoff-context.md"), `# 待處理交接事項\n\n${sections.length ? sections.join("\n\n") : "目前沒有待處理事項。"}\n`);
-    rmSync(responsePath(id), { force: true });
+    mkdirSync(flow, { recursive: true });
+    writeFileSync(join(flow, "handoff-context.md"), `# 待處理交接事項\n\n${sections.length ? sections.join("\n\n") : "目前沒有待處理事項。"}\n`);
+    rmSync(responsePath(id, flow), { force: true });
 }
-export function validateHandoffResponse(id) {
-    return readJsonFile(responsePath(id), HandoffResponse);
+export function validateHandoffResponse(id, flow = flowDir(id)) {
+    return readJsonFile(responsePath(id, flow), HandoffResponse);
 }
 /** 已通過原有關卡的回覆先記收據，再合併；中斷後可重播。 */
 export function acceptHandoff(id, callKey, source, response, role) {

package/dist/parallelReview.js

@@ -0,0 +1,112 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { parallelReviewDir } from "./paths.js";
+import { HandoffLedger } from "./schemas.js";
+/**
+ * 依序啟動、同時最多 limit 個；結果依輸入順序回傳。
+ * fn 丟例外時，其餘已啟動與待啟動的項目仍會跑完（讓它們的收尾，例如移除臨時 worktree，都能完成），最後才把第一個例外丟出。
+ */
+export async function runPool(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    let failure;
+    const worker = async () => {
+        for (;;) {
+            const index = next++;
+            if (index >= items.length)
+                return;
+            try {
+                results[index] = await fn(items[index], index);
+            }
+            catch (error) {
+                failure ??= { error };
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, worker));
+    if (failure)
+        throw failure.error;
+    return results;
+}
+/**
+ * 一次已執行成功的審查呼叫。放在 run 目錄（worktree 外），以輪次＋輸入指紋為鍵記憶化：
+ * 中斷後 resume、或同一輪因別的呼叫失敗而重跑時直接沿用，不重複付費。
+ * 只存原始檔案內容：套用時再放回共用的 .flow/，走原有的驗證與交接程式。
+ */
+export const StoredCall = z.object({
+    /** 同一輪內唯一的呼叫識別 */
+    key: z.string(),
+    reviewer: z.string(),
+    agent: z.string(),
+    step: z.string(),
+    callKey: z.string(),
+    summary: z.string(),
+    /** 裁決檔原文；agent 沒寫時為 null */
+    output: z.string().nullable(),
+    /** handoff-response.json 原文；agent 沒寫時為 null */
+    handoffResponse: z.string().nullable(),
+    /** 這個呼叫啟動時看到的交接帳本：核准門檻以它評估，也用來判斷存檔是否仍可沿用 */
+    base: HandoffLedger,
+});
+const hash = (text) => createHash("sha256").update(text).digest("hex").slice(0, 16);
+const scopeDir = (runId, scope) => join(parallelReviewDir(runId), scope);
+/** 這一輪的存檔目錄；同 scope 下其他指紋（計畫或程式碼已變、輪次已換）的結果一律作廢 */
+export function openRound(runId, scope, fingerprint) {
+    const base = scopeDir(runId, scope);
+    const mine = hash(fingerprint);
+    if (existsSync(base)) {
+        for (const name of readdirSync(base)) {
+            if (name !== mine)
+                rmSync(join(base, name), { recursive: true, force: true });
+        }
+    }
+    const dir = join(base, mine);
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+const callFile = (dir, key) => join(dir, `${hash(key)}.json`);
+export function saveCall(dir, call) {
+    const path = callFile(dir, call.key);
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, JSON.stringify(call));
+    renameSync(tmp, path);
+}
+/**
+ * 讀出這一輪已存檔的結果，並刪掉寫到一半的 .tmp 與損毀的檔案。
+ * 呼叫順序：必須在 runPool 啟動任何呼叫之前；之後才呼叫會刪到別的呼叫正在寫的 .tmp。
+ */
+export function loadCalls(dir) {
+    const calls = new Map();
+    if (!existsSync(dir))
+        return calls;
+    for (const name of readdirSync(dir)) {
+        const path = join(dir, name);
+        if (!name.endsWith(".json")) {
+            rmSync(path, { force: true }); // 寫到一半留下的 .tmp
+            continue;
+        }
+        try {
+            const call = StoredCall.parse(JSON.parse(readFileSync(path, "utf8")));
+            calls.set(call.key, call);
+        }
+        catch {
+            rmSync(path, { force: true }); // 損毀或格式不符：當作沒有，重跑
+        }
+    }
+    return calls;
+}
+export function dropCall(dir, key) {
+    rmSync(callFile(dir, key), { force: true });
+}
+/**
+ * 存檔是否仍可沿用：帳本在這個呼叫啟動後多出的已套用呼叫，必須全是這一輪已存檔的審查者（崩潰或重跑時已套用的 slot）。
+ * 多出別的呼叫（例如修正者只回覆交接、沒改計畫或程式碼，輪次與指紋都沒變）代表審查者沒看過現在的帳本，要重跑。
+ */
+export function storedCallValid(call, live, round) {
+    const seen = new Set(call.base.appliedCalls ?? []);
+    const sameRound = new Set([...round].map((item) => item.callKey));
+    return (live.appliedCalls ?? []).every((key) => seen.has(key) || sameRound.has(key));
+}
+//# sourceMappingURL=parallelReview.js.map

package/dist/paths.js

@@ -22,6 +22,10 @@ export const handoffPath = (id) => join(runDir(id), "handoff.json");
 export const planReviewStatePath = (id) => join(runDir(id), "plan-review-state.json");
 /** 已交付仲裁、尚未得出裁決：暫停後 resume 直接回到仲裁。放在 worktree 外，agent 無法偽造 */
 export const planArbitrationPath = (id) => join(runDir(id), "plan-arbitration.json");
+/** 平行審查的臨時 worktree（每個呼叫一個）；孤兒在 advance() 開頭統一清掉 */
+export const tempWorktreesDir = (id) => join(runDir(id), "tmp-review");
+/** 平行審查已執行成功的呼叫存檔（依輪次與輸入指紋分目錄），resume 時沿用 */
+export const parallelReviewDir = (id) => join(runDir(id), "parallel-review");
 /** 每個 run 一個 git worktree，Agent 只在這裡工作，不碰你正在編輯的檔案 */
 export const worktreesDir = () => join(agentflowctlDir(), "worktrees");
 export const worktreeDir = (id) => join(worktreesDir(), id);

package/dist/schemas.js

@@ -143,6 +143,8 @@ export const RepoConfig = z.object({
     reviewQuorum: z.number().int().min(1).default(1),
     /** 計畫需要幾位不同的 reviewer 都核准 */
     planReviewQuorum: z.number().int().min(1).default(1),
+    /** 同一輪審查最多幾位審查者同時執行；沒寫＝不限，1＝一次一位 */
+    reviewConcurrency: z.number().int().min(1).optional(),
     /** 計畫審查僵持不下（達到重試上限或意見不再變化）時，交給第三方 agent 仲裁，而不是停下來等人 */
     planArbiter: z.boolean().default(true),
     /** 任務夠多、能依檔案分群時，計畫審查改成每輪一次索引加上只審有變動的任務群 */

package/dist/tempWorktree.js

@@ -0,0 +1,129 @@
+import { cpSync, existsSync, mkdirSync, realpathSync, rmSync, symlinkSync } from "node:fs";
+import { join, sep } from "node:path";
+import { git, removeWorktree } from "./git.js";
+import { flowDir, projectRoot, tempWorktreesDir, worktreeDir } from "./paths.js";
+export { tempWorktreesDir };
+let created = 0;
+const warn = (what, err) => console.warn(`⚠️  ${what}失敗（下次執行或 clean 會再清）：${err.message}`);
+/**
+ * 建立臨時 worktree：detached、內容是 run worktree 的 HEAD，並複製目前的 .flow/（.flow/ 不受 git 管理，要另外帶），
+ * run worktree 頂層有 node_modules 時再建一個指向它的 symlink，讓審查者讀得到依賴。
+ * 路徑固定為 tmp-review/<name>：agent CLI（Claude Code、Gemini CLI）會依工作目錄記錄專案，路徑每次不同會一直累積紀錄。
+ * 固定路徑被占用（目錄已存在，或殘留的 locked 登記讓 git worktree add 失敗）時才改用唯一的父目錄，basename 仍是 name。
+ */
+export async function createTempWorktree(runId, name) {
+    const stable = join(tempWorktreesDir(runId), name);
+    mkdirSync(tempWorktreesDir(runId), { recursive: true });
+    let ws;
+    if (!existsSync(stable)) {
+        try {
+            await git(worktreeDir(runId), "worktree", "add", "--detach", stable, "HEAD");
+            ws = { dir: stable, flow: join(stable, ".flow") };
+        }
+        catch {
+            // 固定路徑被占用：清掉這次可能留下的半成品目錄（原本不存在，是這次建的），改用唯一路徑
+            try {
+                rmSync(stable, { recursive: true, force: true });
+            }
+            catch (err) {
+                warn("清掉固定路徑的半成品 ", err);
+            }
+        }
+    }
+    if (!ws) {
+        const parent = join(tempWorktreesDir(runId), `${process.pid}-${Date.now()}-${created++}`);
+        const dir = join(parent, name);
+        mkdirSync(parent, { recursive: true });
+        await git(worktreeDir(runId), "worktree", "add", "--detach", dir, "HEAD");
+        ws = { dir, flow: join(dir, ".flow"), uniqueParent: parent };
+    }
+    try {
+        if (existsSync(flowDir(runId)))
+            cpSync(flowDir(runId), ws.flow, { recursive: true });
+        else
+            mkdirSync(ws.flow, { recursive: true });
+        const deps = join(worktreeDir(runId), "node_modules");
+        if (existsSync(deps))
+            symlinkSync(deps, join(ws.dir, "node_modules"), process.platform === "win32" ? "junction" : "dir");
+    }
+    catch (err) {
+        await removeTempWorktree(runId, ws); // 不會丟例外，不會蓋掉原本的錯誤
+        throw err;
+    }
+    return ws;
+}
+/**
+ * 移除這次建立的臨時 worktree：固定路徑只刪 dir（絕不刪 tmp-review/ 本身，裡面可能還有別的呼叫在用），唯一路徑連父目錄一起刪。
+ * git worktree remove 與 rmSync 都不會跟進 node_modules symlink 刪到原本的依賴。
+ * 永遠不丟例外：這在 withTempWorktree 的 finally 裡執行，丟出去會蓋掉審查本身的結果（已存檔，甚至可能是額度用完）；
+ * 清不掉的只印警告，交給下次 advance 或 clean 的清理。
+ */
+export async function removeTempWorktree(runId, ws) {
+    let removed = true;
+    try {
+        await removeWorktree(worktreeDir(runId), ws.dir);
+    }
+    catch {
+        removed = false; // 目錄可能已經不在：刪掉目錄後再讓 git 忘掉這一個登記
+    }
+    try {
+        rmSync(ws.uniqueParent ?? ws.dir, { recursive: true, force: true, maxRetries: 3 });
+    }
+    catch (err) {
+        warn("移除平行審查的臨時 worktree ", err);
+        return;
+    }
+    // 只處理自己這一個登記；repo 層級的 prune 可能清掉使用者其他資料夾暫時不在的 worktree
+    if (!removed)
+        await git(worktreeDir(runId), "worktree", "remove", "-f", "-f", ws.dir).catch(() => { });
+}
+export async function withTempWorktree(runId, name, fn) {
+    const ws = await createTempWorktree(runId, name);
+    try {
+        return await fn(ws);
+    }
+    finally {
+        await removeTempWorktree(runId, ws);
+    }
+}
+/** git worktree list 裡登記在這個 run 臨時目錄下的 worktree（含 locked 的） */
+async function registeredTempWorktrees(repo, runId) {
+    const base = tempWorktreesDir(runId);
+    const prefixes = [base + sep];
+    try {
+        prefixes.push(realpathSync(base) + sep);
+    }
+    catch {
+        // 目錄已不在：只比對原路徑
+    }
+    return (await git(repo, "worktree", "list", "--porcelain"))
+        .split("\n")
+        .filter((line) => line.startsWith("worktree "))
+        .map((line) => line.slice("worktree ".length))
+        .filter((path) => prefixes.some((prefix) => path.startsWith(prefix)));
+}
+/**
+ * 清掉上次中斷（Ctrl-C 的 process.exit 不跑 finally、SIGTERM、kill -9、當機）留下的臨時 worktree 與 git 登記。
+ * git 在 worktree add 途中被強制中止會留下 locked 登記，prune 會略過它，所以先逐個 remove -f -f。
+ * 這個 run 沒有 tmp-review/ 就什麼都不做（不呼叫 git）；prune 是 repo 層級的，只在確實找到這個 run 的登記時才執行。
+ * force（`clean` 用）：tmp-review/ 已不在也照樣列出登記並清掉，否則只剩 locked 登記時會永遠留在 .git/worktrees/。
+ * 不丟例外：清不乾淨只印警告，下一次 advance 會再試；固定路徑被殘骸占用時建立會改用唯一路徑，不會被擋住。
+ */
+export async function cleanupTempWorktrees(runId, opts = {}) {
+    if (!opts.force && !existsSync(tempWorktreesDir(runId)))
+        return;
+    try {
+        const repo = existsSync(worktreeDir(runId)) ? worktreeDir(runId) : projectRoot();
+        const registered = await registeredTempWorktrees(repo, runId);
+        for (const path of registered) {
+            await git(repo, "worktree", "remove", "-f", "-f", path).catch(() => { }); // 失敗交給下面的 rmSync 與 prune
+        }
+        rmSync(tempWorktreesDir(runId), { recursive: true, force: true, maxRetries: 3 });
+        if (registered.length)
+            await git(repo, "worktree", "prune");
+    }
+    catch (err) {
+        warn("清理平行審查的臨時 worktree ", err);
+    }
+}
+//# sourceMappingURL=tempWorktree.js.map

package/examples/flow.config.json

@@ -4,6 +4,7 @@
   "tddSplit": true,
   "reviewQuorum": 1,
   "planReviewQuorum": 1,
+  "reviewConcurrency": 2,
   "planArbiter": true,
   "planReviewLayers": { "enabled": true, "minTasks": 7, "maxGroups": 5, "tasksPerGroup": 3 },
   "tieBreak": "proceed",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentflowctl",
   "license": "MIT",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "跨廠商 AI 開發 harness：Claude Code、Codex、Gemini 輪流實作、審查、修正",
   "keywords": [
     "ai",