agentflowctl 0.15.1 → 0.17.0

package/README.md

@@ -1,7 +1,6 @@
 # agentflowctl
 
 [![npm version](https://img.shields.io/npm/v/agentflowctl.svg)](https://www.npmjs.com/package/agentflowctl)
-[![GitHub release](https://img.shields.io/github/v/release/gogogohuang/agentflowctl)](https://github.com/gogogohuang/agentflowctl/releases)
 
 讓 Claude Code、Codex、Gemini CLI 等 agent 在同一個專案裡分工：整理需求、規劃、寫測試與程式、交叉審查，最後建立 PR。agentflowctl 負責推進流程，並用檔案、測試和檢查結果決定能否進到下一步。
 
@@ -40,11 +39,13 @@ npx agentflowctl run --req-file ./requirement.md
 
 流程預設會自動往下走。想在計畫通過審查後親自確認，可加 `--manual-plan`；確認後執行 `agentflowctl approve <id>`。
 
+需要先取用某個階段的產出時，可用 `--stop-after <階段>`。可選停點是 `spec`（規格）、`plan`（計畫審查完成）、`implement`（所有任務完成）、`verify`（測試與 checks 通過）、`review`（程式碼審查完成）或 `pr`（PR 流程完成）。除了 `pr` 會照常結束外，其他停點完成後會進入 `paused`，可檢視 worktree 與 `.flow/` 檔案，再執行 `agentflowctl resume <id>` 從下一階段接續；`--manual-plan` 與 `--stop-after` 不能同時使用。
+
 agentflowctl 會依專案的 `packageManager`、lockfile 與 `package.json` scripts 選擇安裝、測試及檢查指令。第一次執行時，請留意終端機印出的偵測結果；需要調整可在 `flow.config.json` 指定 `install`、`test` 或 `checks`。`package.json` 的依賴或 `test` script 看不出測試框架（且沒有手動設定 `test`）時，終端機會提示「未偵測到測試框架」，並略過紅綠燈；要改回來，在 `flow.config.json` 設定 `test`。
 
 ## 查看進度
 
-`run` 開始時會印出 run id，例如 `f-xxxx`。執行中預設只顯示階段進度；加 `-v` 可看到 agent 文字、工具呼叫與專案指令。
+`run` 開始時會印出 run id，例如 `f-xxxx`。執行中預設只顯示階段進度；加 `-v`（或在 `flow.config.json` 設 `"verbose": true`）可看到 agent 文字、工具呼叫與專案指令。
 
 ```bash
 agentflowctl list                  # 列出 run
@@ -73,6 +74,7 @@ agentflowctl resume f-xxxx         # 從暫停、中斷或失敗處接續
 | 按 Ctrl-C，或終端機意外關閉 | 執行 `agentflowctl resume <id>`；沒有結束紀錄的步驟會重跑 |
 | `awaiting_approval`：計畫等你確認 | 閱讀 `.agentflowctl/worktrees/<id>/.flow/plan.md`，確認後執行 `agentflowctl approve <id>` |
 | `paused`：agent 額度用完 | 等額度恢復後執行 `agentflowctl resume <id>`；審查步驟不會換 agent 代審。在仲裁途中暫停時，resume 直接回到仲裁，不重跑計畫審查；暫停期間若改了計畫檔，或在 `flow.config.json` 把 `planArbiter` 關掉，就改成重新審查 |
+| `paused`：已完成指定停點 | 依 `status` 顯示的下一階段檢視產出，再執行 `agentflowctl resume <id>` 接續；run 會保留原本的停點設定 |
 | `failed`：仲裁連續沒有產生有效裁決 | 仲裁者沒寫出 `.flow/plan-arbiter.json`、格式錯誤或交接無效時不會暫停，會把原因寫進 `.flow/feedback.md` 並自動重跑仲裁（不重跑計畫審查）；無效的檔案移到 `.agentflowctl/runs/<id>/reviews/plan-arbiter-<輪>-<agent>-invalid.json`。連續達重試上限才失敗，查看 log 後執行 `agentflowctl resume <id>` 會再回到仲裁 |
 | `failed`：測試、檢查、審查或 agent 執行失敗 | 依 `status` 提示查看失敗的 log，處理原因後執行 `agentflowctl resume <id>`；失敗階段會重試 |
 | `failed`：已達 agent 執行次數上限 | 用 `agentflowctl resume <id> --max-agent-runs 100` 調高上限後接續，數字須大於已執行次數 |
@@ -97,10 +99,11 @@ agentflowctl resume f-xxxx
 | --- | --- |
 | `run --req "..."` / `--req-file <檔案>` | 二選一，直接輸入需求或讀取檔案 |
 | `run --manual-plan` | 計畫通過審查後等待你確認，再用 `approve <id>` 繼續 |
+| `run --stop-after <階段>` | 在 `spec`、`plan`、`implement`、`verify` 或 `review` 完成後暫停；`pr` 會完成 PR 流程並結束。與 `--manual-plan` 互斥 |
 | `run --cycle <名單>` | 指定這次參與的 agent，例如 `--cycle claude,codex`；優先於設定檔的 `cycle` |
 | `run --model-mode balanced\|adaptive` | 只覆蓋這次 run 的模型模式；`resume` 沿用建立時的模式 |
 | `run --base <分支>` | 指定起始分支；未設定時使用目前分支 |
-| `run --max-attempts <次數>` | 覆蓋這次的重試上限（至少 3；預設取 `AGENTFLOWCTL_MAX_ATTEMPTS`，未設定為 5）；失敗後可用 `resume <id> --max-attempts <次數>` 調高 |
+| `run --max-attempts <次數>` | 覆蓋這次的重試上限（至少 3；預設取 `flow.config.json` 的 `maxAttempts`，未設定為 5）；失敗後可用 `resume <id> --max-attempts <次數>` 調高 |
 | `run --max-agent-runs <次數>` | 覆蓋這次的 `maxAgentRuns`；上限不夠時可用 `resume <id> --max-agent-runs <次數>` 調高 |
 | `-v` / `--verbose` | 執行時顯示 agent 文字、工具呼叫與專案指令，適用於 `run`、`resume`、`approve` |
 
@@ -108,6 +111,7 @@ agentflowctl resume f-xxxx
 
 ```bash
 agentflowctl run --req-file ./requirement.md --cycle claude,codex --max-agent-runs 80 --manual-plan
+agentflowctl run --req-file ./requirement.md --stop-after plan
 agentflowctl resume f-xxxx --max-agent-runs 100
 agentflowctl resume f-xxxx --max-attempts 8
 ```
@@ -126,7 +130,7 @@ agentflowctl agent cycle claude,codex
 
 `agent add` 的 `--adapter` 可填 `claude`、`codex`、`gemini` 或 `command`。`--model` 指定個別 agent 的模型；`--extra-arg=--參數` 可重複使用，傳給該 CLI。使用 `command` adapter 時，把指令寫在 `--` 後，例如 `agentflowctl agent add aider --adapter command -- aider --message {prompt}`。`agent remove <名稱>` 會移除設定與參與名單；`agent cycle` 不帶名單則顯示目前參與者。
 
-`model add/set/remove` 只修改指定 agent 的模型清單；`model remove` 移除最後一個模型時，會檢查參與的 agent 是否仍有模型，不論目前使用哪種模型模式。同一 adapter 的 `agent set` 會保留清單；換 adapter 時會清掉舊 adapter 的模型設定。`agent setup` 遇到同名 agent 會先詢問是否覆寫。
+`model add/set/remove` 只修改指定 agent 的模型清單；`model remove` 移除最後一個模型時，會檢查參與的 agent 是否仍有模型，不論目前使用哪種模型模式。同一 adapter 的 `agent set` 會保留清單；換 adapter 時會清掉舊 adapter 的模型設定。`agent setup` 遇到同名 agent 會先詢問是否覆寫。目前是 adaptive 模式、但參與的 agent 沒有 `models` 時，`agent setup` 會提醒並詢問是否改回 balanced；`run` 遇到同樣情況會列出所有缺 `models` 的 agent，並附上 `model add` 與 `model mode balanced` 兩種修法。
 
 ### 依階段與任務難度選模型
 
@@ -194,29 +198,52 @@ 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"` 停止 |
 | `maxAgentRuns` | `60` | 一次 run 最多執行幾次 agent；可用指令選項覆蓋 |
+| `maxAttempts` | `5` | 同一關連續失敗幾次後停止，至少 3；可用 `run`／`resume` 的 `--max-attempts` 覆蓋 |
+| `verbose` | `false` | 顯示 agent 文字、工具呼叫與專案指令，效果同 `-v` |
 | `install`、`test` | 依專案偵測 | 寫成指令字串，例如 `"install": "pnpm install"` |
 | `checks` | 依專案偵測 | 檢查清單，例如 `[{ "name": "test", "cmd": "pnpm test" }]`；提供時會取代整份預設清單 |
 | `testPattern` | 常見的 `.test.`、`.spec.` 檔名 | 辨識測試檔的正規表示式字串；非標準檔名時調整 |
 
 計畫審查會依任務規模選做法。同時符合下列條件時，每輪先做一次索引審查，再只審查有變動的任務群：任務達到 `planReviewLayers.minTasks` 個；依 description 寫的檔案路徑能分成至少兩群，而且最大一群不超過三分之二；`plan.md` 每個任務都有 `## T-<數字>` 標題。索引審查讀規格、全部任務描述、驗收條件與整體做法，人數是 `planReviewQuorum`。群數最多 `maxGroups`，也不超過任務數除以 `tasksPerGroup`；每群一位審查者，含 `high` 任務的群改由 `planReviewQuorum` 位審查。改了 `plan.md` 的整體做法時所有群都重審；某一次審查失敗時只重跑還沒完成的部分。已達門檻卻不符其他條件時，終端機會印出原因並改由審查者讀完整份規格與計畫。`"planReviewLayers": { "enabled": false }` 可以關閉，`doctor` 會顯示目前的設定。
 
-審查意見的處理寫在 `.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`。
+同一輪的審查者（整份計畫審查、分層計畫審查的索引與各群、程式碼審查）預設同時執行，可用 `reviewConcurrency` 限制同時數量（`1` 為一次一位）。
 
-### 環境變數
+**審查者的環境**
 
-| 變數 | 預設 | 設定方式與用途 |
-| --- | --- | --- |
-| `AGENTFLOWCTL_MAX_ATTEMPTS` | `5` | 同一關連續失敗幾次後停止，至少 3（設得更小以 3 計）；例如 `AGENTFLOWCTL_MAX_ATTEMPTS=10 agentflowctl run --req "..."` |
-| `AGENTFLOWCTL_VERBOSE` | 未開啟 | 設為 `1` 顯示詳細輸出，效果同 `-v` |
-| `AGENTFLOWCTL_MAX_TURNS` | `200` | 目前程式會讀取此值，但尚未用它限制 agent 執行 |
+- 每位審查者在自己的臨時 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`。
 
-環境變數對新啟動的 agentflowctl 程序生效。`AGENTFLOWCTL_MAX_ATTEMPTS` 是單一關卡的重試上限（至少 3），單一 run 可用 `run`／`resume` 的 `--max-attempts` 覆蓋；計畫審查何時交付仲裁與它無關：意見沒有變化，或第 2 輪（修訂過一次）仍被要求修改時就交付，兩家 agent 時自動進入雙盲交叉仲裁，有第三方時由第三方單獨仲裁；`maxAgentRuns` 則是整次 run 的 agent 執行次數上限。修正成功、或計畫審查與程式碼審查整組完成一輪有效審查後，該關的失敗次數會歸零，所以上限只計算連續失敗。分層計畫審查時，同一輪裡只要有一次審查呼叫真的執行成功，計畫審查的失敗次數也會歸零；所以索引與各群輪流各失敗一次、每次重跑都有進展時，不會因累計達上限而失敗。
+agentflowctl 不讀取任何 `AGENTFLOWCTL_*` 環境變數，設定都寫在 `flow.config.json`。`maxAttempts`（預設 5、至少 3；設得更小會直接報設定錯誤）是單一關卡的重試上限（至少 3），單一 run 可用 `run`／`resume` 的 `--max-attempts` 覆蓋；計畫審查何時交付仲裁與它無關：意見沒有變化，或第 2 輪（修訂過一次）仍被要求修改時就交付，兩家 agent 時自動進入雙盲交叉仲裁，有第三方時由第三方單獨仲裁；`maxAgentRuns` 則是整次 run 的 agent 執行次數上限。修正成功、或計畫審查與程式碼審查整組完成一輪有效審查後，該關的失敗次數會歸零，所以上限只計算連續失敗。分層計畫審查時，同一輪裡只要有一次審查呼叫真的執行成功，計畫審查的失敗次數也會歸零；所以索引與各群輪流各失敗一次、每次重跑都有進展時，不會因累計達上限而失敗。
 
 ## 發版（維護者）
 
@@ -228,7 +255,7 @@ pnpm release minor             # 確認後建立 v0.x+1.0 的 GitHub Release
 pnpm release 1.0.0             # 指定版本，必須大於目前最新的 tag
 ```
 
-腳本會先檢查目前在 `main`、工作區乾淨、與 `origin/main` 同步、`gh` 已登入、新 tag 不存在，再跑 typecheck、test、build，列出自上個 tag 以來的 commit 並等你輸入 `y` 確認，然後用 `gh release create --generate-notes` 建立 Release。npm 由 Release 觸發的 `npm-publish.yml` 發布；版本號取自 tag，腳本不會改 `package.json`。
+腳本會先檢查目前在 `main`、工作區乾淨、與 `origin/main` 同步、`gh` 已登入、新 tag 不存在，再跑 typecheck、test、build（通過只顯示 ✓，失敗才印出完整輸出），列出自上個 tag 以來的 commit 並等你輸入 `y` 確認，然後用 `gh release create --generate-notes` 建立 Release。npm 由 Release 觸發的 `npm-publish.yml` 發布；版本號取自 tag，腳本不會改 `package.json`。
 
 ## 更多文件
 

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

@@ -12,7 +12,7 @@ import { cleanableRuns, cleanRun } from "./cleanup.js";
 import { describeDetected, detectProjectDefaults } from "./detect.js";
 import { CMD_AGENT, listLogs, localTime, logMark, nextLogFile, renderLog } from "./logs.js";
 import { flowDir, logDir, projectRoot, worktreeDir } from "./paths.js";
-import { ModelStage, ModelStrength, TaskList } from "./schemas.js";
+import { ModelStage, ModelStrength, StopAfterStage, TaskList } from "./schemas.js";
 import { computeInsights, failureLabel, retryLabel } from "./insights.js";
 import { computeUsageInsights } from "./usageInsights.js";
 import { computeStats, formatDuration } from "./stats.js";
@@ -41,6 +41,14 @@ function positiveInt(text, flag, min = 1) {
         throw new Error(`${flag} 必須是不小於 ${min} 的整數：${text}`);
     return n;
 }
+function parseStopAfter(value) {
+    if (value === undefined)
+        return undefined;
+    const result = StopAfterStage.safeParse(value);
+    if (!result.success)
+        throw new Error(`未知的流程停點：${value}（可用：spec、plan、implement、verify、review、pr）`);
+    return result.data;
+}
 function mustGetRun(id) {
     const run = getRun(id);
     if (!run)
@@ -60,6 +68,8 @@ function printSummary(run, interrupted = false) {
     console.log("");
     console.log(`run      ${run.id}`);
     console.log(`階段     ${run.stage}`);
+    if (run.stopAfter)
+        console.log(`停點     ${run.stopAfter}`);
     console.log(`用量     agent 執行 ${agentRuns(run.id)} / ${run.maxAgentRuns} 次`);
     console.log(`agent    ${run.cycle.join("、")}${run.lastWriter ? `（最後作者：${run.lastWriter}）` : ""}`);
     console.log(`分支     ${run.branch}`);
@@ -115,10 +125,17 @@ const TASK_PHASE_MARK = { tests: "🧪", code: "🛠️ ", review: "👀", verif
 const program = new Command()
     .name("agentflowctl")
     .description("在專案資料夾內執行的 Agent 開發流程：規格 → 計畫 → TDD 實作 → 驗證 → 審查 → PR")
-    .option("-v, --verbose", "執行時印出 agent 的文字、工具呼叫與專案指令（預設只印階段進度）")
+    .option("-v, --verbose", "執行時印出 agent 的文字、工具呼叫與專案指令（預設只印階段進度；也可在 flow.config.json 設 verbose）")
     .hook("preAction", (cmd) => {
     if (cmd.opts().verbose)
         config.verbose = true;
+    else {
+        // doctor、agent setup 等可能在沒有專案或設定壞掉時執行；這裡讀不到就維持安靜，指令本身會回報設定錯誤
+        try {
+            config.verbose = loadRepoConfig().verbose;
+        }
+        catch { /* 維持預設 */ }
+    }
 });
 program
     .command("run")
@@ -127,14 +144,18 @@ program
     .option("--req-file <file>", "從檔案讀取需求")
     .option("--base <branch>", "基底分支（預設為目前的分支）")
     .option("--max-agent-runs <n>", "單一 run 最多執行幾次 agent（預設取 flow.config.json 的 maxAgentRuns）")
-    .option("--max-attempts <n>", "同一關連續失敗幾次後停止（預設取 AGENTFLOWCTL_MAX_ATTEMPTS，未設定為 5）")
+    .option("--max-attempts <n>", "同一關連續失敗幾次後停止（預設取 flow.config.json 的 maxAttempts，未設定為 5）")
     .option("--manual-plan", "計畫通過 AI 審查後，仍停下來等你確認", false)
+    .option("--stop-after <stage>", "完成公開階段後暫停：spec、plan、implement、verify、review 或 pr")
     .option("--cycle <agents>", "參與的 agent，例如 claude,codex,gemini（順序不影響分工）")
     .option("--model-mode <mode>", "這次 run 的模型模式：balanced 或 adaptive")
     .action(async (opts) => {
     const requirement = opts.reqFile ? readFileSync(opts.reqFile, "utf8") : opts.req;
     if (!requirement?.trim())
         throw new Error("請用 --req 或 --req-file 提供需求");
+    const stopAfter = parseStopAfter(opts.stopAfter);
+    if (opts.manualPlan && stopAfter)
+        throw new Error("--manual-plan 與 --stop-after 不能同時使用");
     const root = projectRoot();
     const base = opts.base ?? (await git(root, "branch", "--show-current"));
     if (!base)
@@ -159,6 +180,7 @@ program
         branch,
         requirement: requirement.trim(),
         stage: "spec",
+        stopAfter,
         autopilot: !opts.manualPlan,
         maxAgentRuns: opts.maxAgentRuns ? Number(opts.maxAgentRuns) : cfg.maxAgentRuns,
         maxAttempts: opts.maxAttempts ? positiveInt(opts.maxAttempts, "--max-attempts", MIN_ATTEMPTS) : undefined,
@@ -522,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/config.js

@@ -1,11 +1,8 @@
 /** 重試上限的下限：低於這個值時，修正與審查來不及往返一輪 */
 export const MIN_ATTEMPTS = 3;
+/** 執行期旗標；沒有環境變數，設定一律來自 flow.config.json 與命令列選項 */
 export const config = {
-    /** 單一 Agent 執行最多幾輪工具迴圈，避免卡在迴圈裡 */
-    maxTurns: Number(process.env.AGENTFLOWCTL_MAX_TURNS ?? 200),
-    /** 同一個關卡連續失敗幾次後停止；環境變數低於 3 時以 3 計 */
-    maxAttempts: Math.max(MIN_ATTEMPTS, Number(process.env.AGENTFLOWCTL_MAX_ATTEMPTS ?? 5) || 5),
-    /** 終端機是否印出 agent 的文字、工具呼叫與專案指令；預設安靜，-v 或 AGENTFLOWCTL_VERBOSE=1 開啟 */
-    verbose: process.env.AGENTFLOWCTL_VERBOSE === "1",
+    /** 終端機是否印出 agent 的文字、工具呼叫與專案指令；預設安靜，flow.config.json 的 verbose 或 -v 開啟 */
+    verbose: false,
 };
 //# sourceMappingURL=config.js.map

package/dist/engine.js

@@ -1,16 +1,17 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
-import { config } from "./config.js";
 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";
@@ -23,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 {
@@ -51,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)) {
@@ -63,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 });
@@ -80,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;
@@ -95,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)
@@ -127,9 +131,9 @@ function readFeedback(run) {
 }
 /** 計畫審查第幾輪仍有人要求修改時交付仲裁；固定值，不受重試上限影響 */
 const PLAN_ARBITRATION_ROUND = 2;
-/** 這個 run 的重試上限：`--max-attempts` 存在 run 裡，沒設定才用環境變數 */
+/** 這個 run 的重試上限：`--max-attempts` 存在 run 裡，沒設定才用 flow.config.json 的 maxAttempts */
 function attemptLimit(run) {
-    return run.maxAttempts ?? config.maxAttempts;
+    return run.maxAttempts ?? loadRepoConfig().maxAttempts;
 }
 /** 關卡未通過：寫入 feedback.md 給下一次嘗試參考，並把原因分類記進 retries.jsonl；超過上限就讓整個 run 失敗 */
 function retry(run, key, reason, backTo, category) {
@@ -151,6 +155,31 @@ function succeed(run, key, next) {
     delete attempts[key];
     return { ...run, attempts, stage: next };
 }
+/** 回傳這次 transition 完成的公開階段；內部審查／修正 transition 不算交付邊界。 */
+function completedStopStage(current, next) {
+    if (current === "spec" && next === "plan")
+        return "spec";
+    if (current === "plan_review" && next === "implement")
+        return "plan";
+    if (current === "implement" && next === "verify")
+        return "implement";
+    if (current === "verify" && next === "review")
+        return "verify";
+    if (current === "review" && next === "pr")
+        return "review";
+    return undefined;
+}
+function pauseAtStopAfter(run, next) {
+    const completed = completedStopStage(run.stage, next.stage);
+    if (!completed || run.stopAfter !== completed)
+        return next;
+    return {
+        ...next,
+        stage: "paused",
+        pausedStage: next.stage,
+        pauseReason: `已完成指定階段 ${completed}，等待使用者執行 resume 接續`,
+    };
+}
 /** 設定檔放在主專案根目錄，未 commit 的修改也會生效 */
 /** 讀取 flow.config.json；沒寫的 install、test、checks 依專案現況偵測 */
 export function loadRepoConfig() {
@@ -306,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);
+/**
+ * 平行階段：每位審查者在自己的臨時 worktree 執行，成功的結果立刻存檔。
+ * 這個階段不改 run、不寫交接帳本、不呼叫 retry。
+ * - 已有同一輪存檔、且仍有效的呼叫直接沿用（resume）；帳本在它啟動後被本輪以外的呼叫（例如修正者）動過就作廢重跑
+ * - 預算（maxAgentRuns）不夠時只啟動預算內的，回傳 undefined，呼叫端應原樣回傳 run，由 advance 判定 agent_budget
+ * - 有呼叫額度用完時，其他呼叫照常跑完並存檔，最後才丟 QuotaPause
+ */
+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。
+ * 整份審查與分層審查共用的序列收尾：驗證裁決與交接。
+ * 失敗時回傳已呼叫 retry 的 run、沒有 collected，呼叫端應直接回傳這個 run；
+ * 不合格的存檔結果一併刪掉，否則同一輪重跑會反覆讀到同一份。
  */
-async function collectPlanReview(run, spec) {
+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: [] } };
@@ -390,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;
@@ -466,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,
@@ -505,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));
@@ -514,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,
@@ -527,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) });
@@ -932,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)));
@@ -1037,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;
@@ -1052,7 +1176,7 @@ export async function advance(initial) {
             });
         }
         try {
-            run = saveRun(await STAGES[stage](run));
+            run = saveRun(pauseAtStopAfter(run, await STAGES[stage](run)));
         }
         catch (err) {
             if (err instanceof QuotaPause) {

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/modelSelection.js

@@ -90,15 +90,26 @@ export function selectModel(run, cfg, agent, step, complexity, reviewer, scope)
         ?? def.models.reduce((best, current) => LEVEL[current.strength] > LEVEL[best.strength] ? current : best);
     return { mode, name: chosen.name, strength: chosen.strength, targetStrength, insufficient: LEVEL[chosen.strength] < LEVEL[targetStrength] };
 }
+/** adaptive 模式下缺少 models 的錯誤說明：列出全部 agent，並給兩種修法 */
+export function missingModelsMessage(names) {
+    return [
+        `目前是 adaptive 模式，但以下 agent 沒有登記 models（adaptive 只看 models，不看 model）：${names.join("、")}`,
+        "  修法一：登記模型與強度（會用目前帳號送一個短請求驗證）",
+        ...names.map((n) => `    agentflowctl model add ${n} <模型名稱> --strength low|medium|high`),
+        "  修法二：改用 balanced，沿用各 agent 的 model",
+        "    agentflowctl model mode balanced（只改這次 run：run --model-mode balanced）",
+    ].join("\n");
+}
 /** 啟用 adaptive 前檢查本次實際參與的 agent。 */
 export function validateAdaptiveConfig(cfg, cycle) {
+    const lacking = cycle.filter((name) => cfg.agents[name] && !cfg.agents[name].models?.length);
+    if (lacking.length)
+        throw new Error(missingModelsMessage(lacking));
     for (const name of cycle) {
         const def = cfg.agents[name];
         if (!def)
             throw new Error(`未定義的 agent：${name}`);
-        if (!def.models?.length)
-            throw new Error(`agent ${name} 的 models 至少要有一個模型`);
-        const names = def.models.map((m) => m.name);
+        const names = (def.models ?? []).map((m) => m.name);
         if (new Set(names).size !== names.length)
             throw new Error(`agent ${name} 的 models 有重複名稱`);
         if (def.adapter === "command") {

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

@@ -14,6 +14,8 @@ export const Stage = z.enum([
     "done",
     "failed",
 ]);
+/** 使用者可指定的公開流程停點；內部修正階段不列入。 */
+export const StopAfterStage = z.enum(["spec", "plan", "implement", "verify", "review", "pr"]);
 export const HandoffSource = z.object({
     stage: Stage,
     step: z.string().min(1),
@@ -141,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),
     /** 任務夠多、能依檔案分群時，計畫審查改成每輪一次索引加上只審有變動的任務群 */
@@ -160,6 +164,10 @@ export const RepoConfig = z.object({
     tieBreak: z.enum(["proceed", "stop"]).default("proceed"),
     /** 單一 run 最多執行幾次 agent */
     maxAgentRuns: z.number().int().positive().default(60),
+    /** 同一關連續失敗幾次後停止；至少 3，修正與審查才來得及往返一輪 */
+    maxAttempts: z.number().int().min(3).default(5),
+    /** 終端機是否印出 agent 的文字、工具呼叫與專案指令；命令列 -v 也能開啟 */
+    verbose: z.boolean().default(false),
     install: z.string().default("npm install --no-audit --no-fund"),
     test: z.string().default("npx vitest run"),
     testPattern: z.string().default("\\.(test|spec)\\.[cm]?[jt]sx?$"),
@@ -180,10 +188,12 @@ export const FlowRun = z.object({
     branch: z.string(),
     requirement: z.string(),
     stage: Stage,
+    /** 完成這個公開階段後暫停；舊 run 沒有此欄位時一路跑完。 */
+    stopAfter: StopAfterStage.optional(),
     autopilot: z.boolean(),
     /** 單一 run 最多執行幾次 agent */
     maxAgentRuns: z.number().int().positive(),
-    /** 這個 run 同一關連續失敗的上限；沒寫就用 AGENTFLOWCTL_MAX_ATTEMPTS（舊 state.json 沒有此欄位） */
+    /** 這個 run 同一關連續失敗的上限；沒寫就用 flow.config.json 的 maxAttempts（舊 state.json 沒有此欄位） */
     maxAttempts: z.number().int().min(3).optional(),
     /** 暫停前所在的階段與原因（額度用完時） */
     pausedStage: Stage.optional(),

package/dist/setup.js

@@ -1,4 +1,6 @@
 import { addAgent, setAgent, setCycle } from "./agentConfig.js";
+import { missingModelsMessage } from "./modelSelection.js";
+import { setModelMode } from "./modelConfig.js";
 import { ADAPTERS } from "./agents/index.js";
 /**
  * `agentflowctl agent setup` 的互動精靈。
@@ -74,6 +76,16 @@ export async function runSetup(initial, deps) {
             log(`  ${e.message}`);
         }
     }
+    // adaptive 只看 models；精靈只會寫 model，參與的 agent 缺 models 時 run 會直接失敗
+    const defs = (cfg.agents ?? {});
+    const lacking = cfg.cycle.filter((n) => !defs[n]?.models?.length);
+    if (lacking.length && (cfg.modelSelection ?? {}).mode === "adaptive") {
+        log(`\n⚠️  ${missingModelsMessage(lacking)}`);
+        if (await confirm("改回 balanced 模式？（選 n 則維持 adaptive，請之後自行登記 models）", true)) {
+            cfg = setModelMode(cfg, "balanced");
+            changes.push("modelSelection.mode → balanced");
+        }
+    }
     const agents = cfg.agents;
     log("\n即將寫入：");
     for (const name of chosen)

package/dist/stopReport.js

@@ -51,6 +51,10 @@ export function stopReport(i) {
         for (const item of i.open)
             out.push(`  [${item.targetStage}] ${item.id} ${item.summary}（${item.status}）`);
     }
+    const stoppedAfterStage = run.stage === "paused" && run.stopAfter && run.pauseReason?.startsWith("已完成指定階段");
+    if (stoppedAfterStage) {
+        out.push("", "── 指定停點 ──", `  ${run.pauseReason}`, `  指定停點：${run.stopAfter}`, `  下一階段：${run.pausedStage ?? "?"}`);
+    }
     const cmd = (c, why) => `  ${c.padEnd(40)} ${why}`;
     const actions = [];
     if (run.stage === "failed") {
@@ -61,7 +65,7 @@ export function stopReport(i) {
         actions.push(cmd(`agentflowctl cancel ${run.id}`, "放棄這個 run"));
     }
     else if (run.stage === "paused") {
-        actions.push(cmd(`agentflowctl resume ${run.id}`, "額度恢復後接續"));
+        actions.push(cmd(`agentflowctl resume ${run.id}`, stoppedAfterStage ? `從 ${run.pausedStage ?? "下一階段"} 接續` : "額度恢復後接續"));
     }
     else if (run.stage === "awaiting_approval") {
         actions.push(cmd(`less ${join(i.worktree, ".flow", "plan.md")}`, "檢視計畫"));

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.15.1",
+  "version": "0.17.0",
   "description": "跨廠商 AI 開發 harness：Claude Code、Codex、Gemini 輪流實作、審查、修正",
   "keywords": [
     "ai",