agentflowctl 0.13.0 → 0.14.0

package/dist/engine.js

@@ -7,14 +7,15 @@ import { detectProjectDefaults, 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 { flowDir, logDir, projectRoot, runDir, worktreeDir } from "./paths.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 { resolveAgent, runAgent, runCommand } from "./runner.js";
 import { AcceptanceList, ArbiterResult, ConsistentReviewResult, RepoConfig, TaskList, } from "./schemas.js";
-import { addSubstitution, addUsage, agentRuns, saveRun } from "./store.js";
+import { addRetry, addSubstitution, addUsage, agentRuns, saveRun } from "./store.js";
 import { clearModelReviewFailure, clearModelReviewStage, recordModelReviewFailure, selectModel } from "./modelSelection.js";
+import { applyReviewVerdicts, dirtyGroups, dirtyTaskIds, extractPlanEvidence, groupReviewerCount, layeredReview, neighborTasks, planContentKey, planOverview, planReviewIndex, readPendingArbitration, readPlanReviewState, repliesForTasks, reviewFingerprint, roundProgress, } from "./planReview.js";
 import { orderTasks, taskAcceptance, validateTaskComplexity } from "./tasks.js";
 import { readJsonFile, renderPrompt, tail } from "./util.js";
 // ───────────────────────── 共用工具 ─────────────────────────
@@ -33,6 +34,10 @@ export class QuotaPause extends Error {
 }
 /** 這次執行中已確認額度用完的 agent；程序結束即清空，resume 時會重新嘗試 */
 const exhausted = new Set();
+/** 只供測試使用：清掉這個程序內記下的額度用完 agent，模擬新啟動的程序 */
+export function resetQuotaState() {
+    exhausted.clear();
+}
 function handoffTarget(run) {
     return ["spec", "plan", "plan_review", "plan_fix"].includes(run.stage) ? "plan" : "code";
 }
@@ -61,7 +66,7 @@ async function agentStep(run, planned, step, prompt, mode) {
             info(run, `🔁 ${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);
+        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}）` : ""}`);
         const callKey = handoffKey(run, step, mode.slot ?? 0, agent);
         prepareHandoff(run.id, callKey, handoffTarget(run), mode.blind ?? false);
@@ -112,18 +117,24 @@ function reportMeta(run, agent, r) {
     if (r.meta.concerns)
         info(run, `   💭 ${agent} 的疑慮：${r.meta.concerns}`);
 }
-function readFeedback(run) {
-    const p = flowFile(run, "feedback.md");
+/** 讀 .flow/ 下的文字檔，沒有檔就當空字串 */
+function flowText(run, name) {
+    const p = flowFile(run, name);
     return existsSync(p) ? readFileSync(p, "utf8") : "";
 }
-/** 關卡未通過：寫入 feedback.md 給下一次嘗試參考，超過上限就讓整個 run 失敗 */
-function retry(run, key, reason, backTo) {
+function readFeedback(run) {
+    return flowText(run, "feedback.md");
+}
+/** 關卡未通過：寫入 feedback.md 給下一次嘗試參考，並把原因分類記進 retries.jsonl；超過上限就讓整個 run 失敗 */
+function retry(run, key, reason, backTo, category) {
     const n = (run.attempts[key] ?? 0) + 1;
     const attempts = { ...run.attempts, [key]: n };
+    const final = n >= config.maxAttempts;
     mkdirSync(flowDir(run.id), { recursive: true });
     writeFileSync(flowFile(run, "feedback.md"), `# 前次嘗試未通過（第 ${n} 次）\n\n${reason}\n`);
-    if (n >= config.maxAttempts) {
-        return { ...run, attempts, stage: "failed", failedStage: backTo, failureReason: `${key} 連續失敗 ${n} 次：${tail(reason, 500)}` };
+    addRetry(run.id, { key, backTo, category, attempt: n, final }, run.updatedAt);
+    if (final) {
+        return { ...run, attempts, stage: "failed", failedStage: backTo, failureCategory: "retry_limit", failureReason: `${key} 連續失敗 ${n} 次：${tail(reason, 500)}` };
     }
     info(run, `⚠️  ${key} 未通過，重試（${n}/${config.maxAttempts}）`);
     return { ...run, attempts, stage: backTo };
@@ -161,24 +172,26 @@ async function specStage(run) {
     const { r } = outcome;
     await discardChanges(worktreeDir(run.id)); // 這個階段只允許寫 .flow/
     if (!r.ok)
-        return retry(run, "spec", `Agent 執行失敗：${r.summary}`, "spec");
+        return retry(run, "spec", `Agent 執行失敗：${r.summary}`, "spec", "agent_error");
     if (!existsSync(flowFile(run, "spec.md")))
-        return retry(run, "spec", "缺少 .flow/spec.md", "spec");
+        return retry(run, "spec", "缺少 .flow/spec.md", "spec", "missing_artifact");
     const ac = readJsonFile(flowFile(run, "acceptance.json"), AcceptanceList);
     if (!ac.ok)
-        return retry(run, "spec", ac.error, "spec");
+        return retry(run, "spec", ac.error, "spec", "format_invalid");
     const ids = ac.data.map((a) => a.id);
     if (new Set(ids).size !== ids.length)
-        return retry(run, "spec", "驗收條件 id 有重複", "spec");
+        return retry(run, "spec", "驗收條件 id 有重複", "spec", "format_invalid");
     const handoffError = finishHandoff(run, outcome, "writer");
     if (handoffError)
-        return retry(run, "spec", handoffError, "spec");
+        return retry(run, "spec", handoffError, "spec", "handoff_invalid");
     return succeed(run, "spec", "plan");
 }
 // ── 規格與計畫檔案：計畫審查、仲裁與計畫定案後的所有階段只能讀，不能改 ──
 const PLAN_FILES = ["spec.md", "acceptance.json", "plan.md", "tasks.json"];
 /** 計畫定案後（實作、修正、程式碼審查）另外依賴排好的任務順序，同樣不能被改 */
 const LOCKED_FILES = [...PLAN_FILES, "tasks.ordered.json"];
+/** 審查、修訂與仲裁的快照另外包含審查回應；不要併進 PLAN_FILES，定案後的階段不依賴它 */
+const PLAN_REPLY_FILES = [...PLAN_FILES, "plan-replies.md"];
 function snapshotPlan(run, files = PLAN_FILES) {
     return Object.fromEntries(files.map((f) => [f, existsSync(flowFile(run, f)) ? readFileSync(flowFile(run, f), "utf8") : undefined]));
 }
@@ -232,7 +245,7 @@ function announceTasks(run, ordered) {
 function planSettled(run, key) {
     const pending = openActions(readHandoff(run.id), "plan");
     if (pending.length)
-        return retry(run, "plan-handoff", `計畫仍有未結交接事項：${pending.map((item) => item.id).join("、")}`, "plan_fix");
+        return retry(run, "plan-handoff", `計畫仍有未結交接事項：${pending.map((item) => item.id).join("、")}`, "plan_fix", "open_handoff");
     const next = run.autopilot ? "implement" : "awaiting_approval";
     const ordered = loadOrderedTasks(run);
     announceTasks(run, ordered);
@@ -252,59 +265,75 @@ async function planStage(run) {
     const { r, agent: actual } = outcome;
     await discardChanges(worktreeDir(run.id));
     if (!r.ok)
-        return retry(run, "plan", `Agent 執行失敗：${r.summary}`, "plan");
+        return retry(run, "plan", `Agent 執行失敗：${r.summary}`, "plan", "agent_error");
     const ordered = validatePlan(run);
     if (typeof ordered === "string")
-        return retry(run, "plan", ordered, "plan");
+        return retry(run, "plan", ordered, "plan", "format_invalid");
     const handoffError = finishHandoff(run, outcome, "writer");
     if (handoffError)
-        return retry(run, "plan", handoffError, "plan");
+        return retry(run, "plan", handoffError, "plan", "handoff_invalid");
     acceptPlan(run, ordered);
     rmSync(flowFile(run, "plan-review-last.txt"), { force: true });
     return { ...succeed(run, "plan", "plan_review"), planWriter: actual };
 }
 async function planReviewStage(run) {
     const cfg = loadRepoConfig();
-    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 issues = [];
-    const issueLines = []; // 只含意見內容、不含審查者名稱，用來偵測僵持
-    let firstObjector;
-    for (const reviewer of panel) {
-        info(run, `🧐 計畫審查第 ${round} 輪（${reviewer}，作者 ${author}）`);
-        const snap = snapshotPlan(run);
-        rmSync(flowFile(run, "plan-review.json"), { force: true });
-        const outcome = await agentStep(run, reviewer, "plan-review", renderPrompt("plan-review", { reviewer, author, requirement: run.requirement }), { kind: "review", slot: panel.indexOf(reviewer), reset: async () => { await discardChanges(worktreeDir(run.id)); restorePlan(run, snap); } });
-        const { r } = outcome;
-        await discardChanges(worktreeDir(run.id));
-        const tampered = restorePlan(run, snap);
-        if (tampered.length)
-            info(run, `   ↩️  已還原審查者修改的檔案：${tampered.join(", ")}`);
-        if (!r.ok)
-            return retry(recordModelReviewFailure(run, "plan-review", reviewer), "plan-review-run", `Agent 執行失敗：${r.summary}`, "plan_review");
-        const review = readJsonFile(flowFile(run, "plan-review.json"), ConsistentReviewResult);
-        if (!review.ok)
-            return retry(recordModelReviewFailure(run, "plan-review", reviewer), "plan-review-run", review.error, "plan_review");
-        const handoffError = finishHandoff(run, outcome, "reviewer", { target: "plan", verdict: review.data.verdict });
-        if (handoffError)
-            return retry(recordModelReviewFailure(run, "plan-review", reviewer), "plan-review-run", handoffError, "plan_review");
-        run = clearModelReviewFailure(run, "plan-review", reviewer);
-        // 審查紀錄移到 worktree 外面：之後的仲裁者看不到是哪一家提的意見
-        mkdirSync(join(runDir(run.id), "reviews"), { recursive: true });
-        renameSync(flowFile(run, "plan-review.json"), join(runDir(run.id), "reviews", `plan-review-${round}-${reviewer}.json`));
-        if (review.data.verdict === "approve") {
-            info(run, `   ✓ ${reviewer} 核准計畫`);
-            continue;
-        }
-        info(run, `   ✗ ${reviewer} 要求修改計畫`);
-        firstObjector ??= reviewer;
-        const lines = review.data.items
-            .filter((i) => i.status !== "met")
-            .map((i) => reviewIssue(i.criterion, i.status, i.note));
-        issueLines.push(...lines);
-        issues.push(opinion(reviewer, lines));
+    const pending = pendingArbitration(run, cfg);
+    if (pending) {
+        info(run, "⚖️  上次仲裁沒有完成，直接回到仲裁（不重跑計畫審查）");
+        return arbitratePlan({ ...run, planReviewer: pending.planReviewer });
+    }
+    const layered = loadLayeredPlan(run, cfg);
+    return layered ? planReviewLayered(run, layered, cfg) : planReviewFull(run, cfg);
+}
+/**
+ * 整份審查與分層審查共用的單次呼叫：還原審查者改過的計畫檔、驗證裁決與交接。
+ * 失敗時回傳已呼叫 retry 的 run、沒有 collected，呼叫端應直接回傳這個 run。
+ */
+async function collectPlanReview(run, spec) {
+    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 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);
+    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));
+    if (review.data.verdict === "approve") {
+        info(run, `   ✓ ${reviewer} 核准${spec.subject}`);
+        return { run, collected: { reviewer, verdict: "approve", issueLines: [] } };
     }
+    info(run, `   ✗ ${reviewer} 要求修改${spec.subject}`);
+    const issueLines = review.data.items
+        .filter((i) => i.status !== "met")
+        .map((i) => reviewIssue(i.criterion, i.status, i.note));
+    return { run, collected: { reviewer, verdict: "changes_requested", issueLines } };
+}
+/** 一輪審查都產出合法裁決後：全部核准就定案，否則退回修訂，僵持或達輪數上限時交付仲裁 */
+async function concludePlanReview(run, cfg, round, calls) {
+    const objections = calls.filter((call) => call.verdict !== "approve");
+    const issueLines = objections.flatMap((call) => call.issueLines);
+    const issues = objections.map((call) => opinion(call.reviewer, call.issueLines));
+    const firstObjector = objections[0]?.reviewer;
     run = clearModelReviewStage(run, "plan-review");
     const attempts = { ...run.attempts };
     delete attempts["plan-review-run"];
@@ -314,7 +343,7 @@ async function planReviewStage(run) {
     const report = `計畫審查要求修改：\n\n${issues.join("\n\n")}`;
     // 僵持偵測：意見和上一輪完全相同，代表修改沒有進展
     const lastPath = flowFile(run, "plan-review-last.txt");
-    const fingerprint = [...issueLines].sort().join("\n");
+    const fingerprint = reviewFingerprint(issueLines);
     const stalled = existsSync(lastPath) && readFileSync(lastPath, "utf8") === fingerprint;
     writeFileSync(lastPath, fingerprint);
     const exhausted = round >= config.maxAttempts;
@@ -326,9 +355,165 @@ async function planReviewStage(run) {
         // 給仲裁者的爭議清單不含任何模型名稱
         writeFileSync(flowFile(run, "dispute.md"), `# 尚未解決的審查意見\n\n${[...new Set(issueLines)].join("\n")}\n`);
         info(run, `⚖️  計畫審查${stalled ? "意見沒有變化" : `已達 ${round} 輪`}，交付仲裁`);
+        // 仲裁暫停（裁決無效或額度用完）後 resume 仍停在 plan_review，靠這份紀錄直接回到仲裁
+        mkdirSync(runDir(run.id), { recursive: true });
+        writeFileSync(planArbitrationPath(run.id), JSON.stringify({ planReviewer: firstObjector, planKey: currentPlanKey(run) }, null, 2));
         return arbitratePlan({ ...run, planReviewer: firstObjector });
     }
-    return { ...retry(run, "plan-review", report, "plan_fix"), planReviewer: firstObjector };
+    return { ...retry(run, "plan-review", report, "plan_fix", "review_changes"), planReviewer: firstObjector };
+}
+/** 整份審查：每位審查者讀完整份規格與計畫 */
+async function planReviewFull(run, cfg) {
+    // 整份審查不維護分層狀態；之後若又切回分層，不能沿用這之前的 approve
+    rmSync(planReviewStatePath(run.id), { force: true });
+    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 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`,
+        });
+        run = passed.run;
+        if (!passed.collected)
+            return run;
+        calls.push(passed.collected);
+    }
+    return concludePlanReview(run, cfg, round, calls);
+}
+/** 本輪進度的雜湊涵蓋的檔案：任一份變了，就不能沿用先前的審查結果 */
+const PLAN_KEY_FILES = ["tasks.json", "acceptance.json", "plan.md", "plan-replies.md"];
+function currentPlanKey(run) {
+    return planContentKey(PLAN_KEY_FILES.map((name) => flowText(run, name)));
+}
+/**
+ * 上次交付仲裁卻沒有得出裁決（暫停）時的紀錄。計畫在這之間被改過、或爭議清單不見了，
+ * 就當成沒有待完成的仲裁並刪掉紀錄，重新審查。暫停期間關掉了 planArbiter 也一樣，
+ * 連同爭議清單一起刪掉。
+ */
+function pendingArbitration(run, cfg) {
+    const path = planArbitrationPath(run.id);
+    if (!existsSync(path))
+        return undefined;
+    const pending = readPendingArbitration(readFileSync(path, "utf8"));
+    if (cfg.planArbiter && pending && pending.planKey === currentPlanKey(run) && existsSync(flowFile(run, "dispute.md")))
+        return pending;
+    rmSync(path, { force: true });
+    if (!cfg.planArbiter)
+        rmSync(flowFile(run, "dispute.md"), { force: true });
+    return undefined;
+}
+/** 符合分層條件時讀出分層審查需要的資料；不符合時回傳 undefined，已達門檻的會印出原因 */
+function loadLayeredPlan(run, cfg) {
+    const tasks = readJsonFile(flowFile(run, "tasks.json"), TaskList);
+    const acceptance = readJsonFile(flowFile(run, "acceptance.json"), AcceptanceList);
+    if (!tasks.ok || !acceptance.ok)
+        return undefined;
+    const planMd = flowText(run, "plan.md");
+    const decision = layeredReview(tasks.data, planMd, cfg.planReviewLayers);
+    if (!decision.layered) {
+        if (decision.reason)
+            info(run, `📋 這次計畫審查讀整份計畫：${decision.reason}`);
+        return undefined;
+    }
+    const statePath = planReviewStatePath(run.id);
+    const state = existsSync(statePath) ? readPlanReviewState(readFileSync(statePath, "utf8")) : undefined;
+    return {
+        tasks: tasks.data, acceptance: acceptance.data, planMd, state,
+        dirty: dirtyGroups(decision.groups, dirtyTaskIds(state?.reviewed, tasks.data, acceptance.data, planMd)),
+    };
+}
+/** 分層審查：每輪一次索引審查，再只審有變動的任務群 */
+async function planReviewLayered(run, layered, 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 replies = flowText(run, "plan-replies.md");
+    const statePath = planReviewStatePath(run.id);
+    const reviewed = layered.state?.reviewed;
+    const planKey = currentPlanKey(run);
+    // 同一輪因某一呼叫失敗而重跑時，沿用已成功的呼叫：不重複付費，已套用的交接也不會被重新提出
+    const progress = roundProgress(layered.state, round, planKey) ?? { round, planKey, calls: [] };
+    const saveState = (state) => {
+        mkdirSync(runDir(run.id), { recursive: true });
+        writeFileSync(statePath, JSON.stringify(state, null, 2));
+    };
+    const done = new Map(progress.calls.map((call) => [call.key, call]));
+    const calls = [];
+    // 沿用的呼叫也佔一格，重跑時每個呼叫的 slot 才不會變
+    let nextSlot = 0;
+    /** 執行或沿用一次呼叫；失敗時回傳 false，run 已是 retry 後的狀態 */
+    const runCall = async (key, taskIds, label, spec) => {
+        const slot = nextSlot++;
+        const reused = done.get(key);
+        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;
+    };
+    for (const reviewer of panel) {
+        const ok = await runCall(`index:${reviewer}`, undefined, "計畫索引審查", {
+            reviewer, step: "plan-review", gated: true, subject: "計畫索引",
+            prompt: renderPrompt("plan-review-index", {
+                reviewer, author, requirement: run.requirement,
+                index: planReviewIndex(layered.tasks),
+                acceptance: JSON.stringify(layered.acceptance, null, 2),
+                overview: planOverview(layered.planMd),
+                replies,
+            }),
+            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));
+        const acceptanceIds = new Set(groupTasks.flatMap((task) => task.acceptance));
+        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} 審查`, {
+                reviewer, step: "plan-review-group", gated: false, subject: `任務群 ${group.id}`, scope: group.id,
+                prompt: renderPrompt("plan-review-group", {
+                    reviewer, author, groupId: group.id,
+                    files: group.files.join("、") || "（這群的描述沒有點名檔案）",
+                    tasks: JSON.stringify(groupTasks, null, 2),
+                    neighbors: neighbors.length ? JSON.stringify(neighbors, null, 2) : "（沒有跨群的直接相依）",
+                    acceptance: JSON.stringify(layered.acceptance.filter((item) => acceptanceIds.has(item.id)), null, 2),
+                    evidence: extractPlanEvidence(layered.planMd, group.taskIds),
+                    replies: repliesForTasks(replies, group.taskIds),
+                }),
+                output: "plan-review-group.json", archive: `plan-review-${round}-${group.id}-${reviewer}.json`,
+            });
+            if (!ok)
+                return run;
+        }
+    }
+    // 只放這一輪真的審過的群（含沿用的），沒審到的任務才留得住前次 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) });
+    return concludePlanReview(run, cfg, round, calls);
 }
 async function planFixStage(run) {
     const cfg = loadRepoConfig();
@@ -340,24 +525,35 @@ async function planFixStage(run) {
     });
     info(run, `✏️  依 ${run.planReviewer ?? "審查者"} 的意見修改計畫（${agent}）`);
     const feedback = readFeedback(run);
-    const snap = snapshotPlan(run);
-    const outcome = await agentStep(run, agent, "plan-fix", renderPrompt("plan-fix", { requirement: run.requirement, testPattern: cfg.testPattern }), { kind: "write", reset: async () => { await discardChanges(worktreeDir(run.id)); restorePlan(run, snap); } });
+    const snap = snapshotPlan(run, PLAN_REPLY_FILES);
+    // 回應每輪整份覆寫：先刪掉上一輪的，agent 沒寫時下一輪才不會讀到舊回應；失敗時快照會還原
+    const clearReplies = () => rmSync(flowFile(run, "plan-replies.md"), { force: true });
+    clearReplies();
+    let outcome;
+    try {
+        outcome = await agentStep(run, agent, "plan-fix", renderPrompt("plan-fix", { requirement: run.requirement, testPattern: cfg.testPattern }), { kind: "write", reset: async () => { await discardChanges(worktreeDir(run.id)); restorePlan(run, snap); clearReplies(); } });
+    }
+    catch (err) {
+        // 所有 agent 額度都用完而暫停：還原成進入時的內容，resume 前的計畫審查回應仍在
+        restorePlan(run, snap);
+        throw err;
+    }
     const { r, agent: actual } = outcome;
     await discardChanges(worktreeDir(run.id)); // 只允許改 .flow/
     if (!r.ok) {
         restorePlan(run, snap);
-        return retry(run, "plan-fix", `${feedback}\n\n（上次修改時 Agent 執行失敗：${r.summary}）`, "plan_fix");
+        return retry(run, "plan-fix", `${feedback}\n\n（上次修改時 Agent 執行失敗：${r.summary}）`, "plan_fix", "agent_error");
     }
     const ordered = validatePlan(run);
     if (typeof ordered === "string") {
         restorePlan(run, snap);
-        return retry(run, "plan-fix", `${feedback}\n\n另外，修改後的計畫沒有通過格式檢查，已還原：\n${ordered}`, "plan_fix");
+        return retry(run, "plan-fix", `${feedback}\n\n另外，修改後的計畫沒有通過格式檢查，已還原：\n${ordered}`, "plan_fix", "format_invalid");
     }
     const handoffError = finishHandoff(run, outcome, "writer");
     if (handoffError) {
         restorePlan(run, snap);
         // 計畫已還原，要保留原本的審查意見，否則下一次修正不知道要改什麼
-        return retry(run, "plan-fix", `${feedback}\n\n另外，交接回覆不合格，本次修改已還原：${handoffError}`, "plan_fix");
+        return retry(run, "plan-fix", `${feedback}\n\n另外，交接回覆不合格，本次修改已還原：${handoffError}`, "plan_fix", "handoff_invalid");
     }
     acceptPlan(run, ordered);
     writeFileSync(flowFile(run, "feedback.md"), feedback); // 保留審查意見，讓下一輪審查者知道上次提了什麼
@@ -377,7 +573,7 @@ async function arbitratePlan(run) {
     const verdicts = [];
     for (const [slot, arbiter] of panel.entries()) {
         info(run, `⚖️  ${mode}（${arbiter}）`);
-        const snap = snapshotPlan(run);
+        const snap = snapshotPlan(run, PLAN_REPLY_FILES);
         rmSync(flowFile(run, "plan-arbiter.json"), { force: true });
         const outcome = await agentStep(run, arbiter, "plan-arbiter", renderPrompt("plan-arbiter", { requirement: run.requirement }), {
             kind: "review", slot, blind: true,
@@ -403,6 +599,7 @@ async function arbitratePlan(run) {
         verdicts.push({ arbiter, verdict, notes, markdownNotes });
     }
     rmSync(flowFile(run, "dispute.md"), { force: true });
+    rmSync(planArbitrationPath(run.id), { force: true });
     const approvals = verdicts.filter((v) => v.verdict === "approve").length;
     const unanimous = approvals === verdicts.length;
     const decision = arbitrationDecision(verdicts.map((v) => v.verdict), cfg.tieBreak);
@@ -418,6 +615,8 @@ async function arbitratePlan(run) {
         const attempts = { ...run.attempts, "plan-arbitration": arbitrationRound };
         delete attempts["plan-review"];
         rmSync(flowFile(run, "plan-review-last.txt"), { force: true });
+        rmSync(planReviewStatePath(run.id), { force: true });
+        addRetry(run.id, { key: "plan-arbitration", backTo: "plan_fix", category: "arbitration_revise", attempt: arbitrationRound, final: false }, run.updatedAt);
         writeFileSync(flowFile(run, "feedback.md"), `# 仲裁要求修訂（第 ${arbitrationRound} 次）\n\n${summary}\n\n${feedbackRecord}\n`);
         info(run, `   → ${summary}`);
         return { ...run, attempts, stage: "plan_fix" };
@@ -427,7 +626,7 @@ async function arbitratePlan(run) {
         info(run, `   → ${summary}`);
         return planSettled(run, "plan-review");
     }
-    return { ...run, stage: "failed", failedStage: "plan_review", failureReason: `${summary}，需要人工決定（見 plan.md 的仲裁紀錄）` };
+    return { ...run, stage: "failed", failedStage: "plan_review", failureCategory: "arbitration_stop", failureReason: `${summary}，需要人工決定（見 plan.md 的仲裁紀錄）` };
 }
 function planTamperedMessage(files) {
     return `計畫定案後不可修改規格與計畫檔，已還原你的變更：${files.map((f) => `.flow/${f}`).join(", ")}。若認為規格或驗收條件有誤，請寫進 .flow/handoff-response.json 的 newIssues。`;
@@ -467,29 +666,29 @@ async function implementStage(run) {
         const tampered = restorePlan(run, snap);
         if (!r.ok) {
             await resetTo(repo, before);
-            return retry(run, key, `Agent 執行失敗：${r.summary}`, "implement");
+            return retry(run, key, `Agent 執行失敗：${r.summary}`, "implement", "agent_error");
         }
         if (tampered.length) {
             await resetTo(repo, before);
-            return retry(run, key, planTamperedMessage(tampered), "implement");
+            return retry(run, key, planTamperedMessage(tampered), "implement", "plan_tampered");
         }
         const commit = await commitAll(repo, `test(${task.id}): ${task.title} [${testsAuthor}]`);
         if (!commit)
-            return retry(run, key, "沒有任何檔案變更，這個階段必須撰寫測試。", "implement");
+            return retry(run, key, "沒有任何檔案變更，這個階段必須撰寫測試。", "implement", "tests_not_written");
         const changed = await changedFiles(repo, before, commit);
         if (!changed.some((f) => testRe.test(f))) {
             await resetTo(repo, before);
-            return retry(run, key, `沒有新增或修改任何符合 /${cfg.testPattern}/ 的測試檔。`, "implement");
+            return retry(run, key, `沒有新增或修改任何符合 /${cfg.testPattern}/ 的測試檔。`, "implement", "tests_not_written");
         }
         const red = await runCommand(target(run, `${task.id}-red`, CMD_AGENT), testCmd);
         if (red.ok) {
             await resetTo(repo, before);
-            return retry(run, key, "測試在功能尚未實作前就全部通過，代表測試沒有驗證到新行為。請撰寫會因功能尚未實作而失敗的測試。", "implement");
+            return retry(run, key, "測試在功能尚未實作前就全部通過，代表測試沒有驗證到新行為。請撰寫會因功能尚未實作而失敗的測試。", "implement", "tests_not_red");
         }
         const handoffError = finishHandoff(run, outcome, "writer");
         if (handoffError) {
             await resetTo(repo, before);
-            return retry(run, key, handoffError, "implement");
+            return retry(run, key, handoffError, "implement", "handoff_invalid");
         }
         writeFileSync(flowFile(run, "red-output.txt"), red.output);
         info(run, `🔴 [${progress}] 測試如預期失敗`);
@@ -507,26 +706,26 @@ async function implementStage(run) {
     const { r, agent: codeAuthor } = outcome;
     const tampered = restorePlan(run, snap);
     if (!r.ok)
-        return retry(run, key, `Agent 執行失敗：${r.summary}`, "implement");
+        return retry(run, key, `Agent 執行失敗：${r.summary}`, "implement", "agent_error");
     if (tampered.length) {
         await resetTo(repo, testsCommit);
-        return retry(run, key, planTamperedMessage(tampered), "implement");
+        return retry(run, key, planTamperedMessage(tampered), "implement", "plan_tampered");
     }
     await commitAll(repo, `feat(${task.id}): ${task.title} [${codeAuthor}]`);
     const touched = (await changedFiles(repo, testsCommit, await headCommit(repo))).filter((f) => testRe.test(f));
     if (touched.length) {
         await resetTo(repo, testsCommit);
-        return retry(run, key, `實作階段不可修改測試檔，已還原你的變更：${touched.join(", ")}`, "implement");
+        return retry(run, key, `實作階段不可修改測試檔，已還原你的變更：${touched.join(", ")}`, "implement", "tests_modified");
     }
     const green = await runCommand(target(run, `${task.id}-green`, CMD_AGENT), testCmd);
     if (!green.ok) {
         info(run, `   ✗ 測試仍未通過${logHint(run, green.seq)}`);
-        return retry(run, key, `測試仍未通過：\n\n\`\`\`\n${tail(green.output)}\n\`\`\``, "implement");
+        return retry(run, key, `測試仍未通過：\n\n\`\`\`\n${tail(green.output)}\n\`\`\``, "implement", "tests_not_green");
     }
     const handoffError = finishHandoff(run, outcome, "writer");
     if (handoffError) {
         await resetTo(repo, testsCommit);
-        return retry(run, key, handoffError, "implement");
+        return retry(run, key, handoffError, "implement", "handoff_invalid");
     }
     info(run, `🟢 [${progress}] 測試通過`);
     return { ...succeed(run, key, "implement"), taskPhase: "review", lastWriter: codeAuthor };
@@ -558,7 +757,7 @@ async function taskReviewStep(run, task, progress, taskJson, acceptanceJson) {
     if (!result.objector)
         return { ...succeed(reviewed, key, "implement"), taskPhase: "verify" };
     return {
-        ...retry(reviewed, key, `任務審查要求修改：\n\n${result.issues.join("\n\n")}`, "implement"),
+        ...retry(reviewed, key, `任務審查要求修改：\n\n${result.issues.join("\n\n")}`, "implement", "review_changes"),
         taskPhase: "fix",
         fixSource: "review",
         lastReviewer: result.objector,
@@ -570,7 +769,7 @@ async function taskVerifyStep(run, task, progress) {
     info(run, `🔍 [${progress}] 執行驗證`);
     const report = await runChecks(run, `${task.id}-`);
     if (report)
-        return { ...retry(run, key, report, "implement"), taskPhase: "fix", fixSource: "verify" };
+        return { ...retry(run, key, report, "implement", "checks_failed"), taskPhase: "fix", fixSource: "verify" };
     info(run, `✅ [${progress}] 完成`);
     return {
         ...succeed(run, key, "implement"),
@@ -622,7 +821,7 @@ async function verifyStage(run) {
     const report = await runChecks(run);
     if (!report)
         return succeed(run, "verify", "review");
-    return { ...retry(run, "verify", report, "fix"), fixSource: "verify" };
+    return { ...retry(run, "verify", report, "fix", "checks_failed"), fixSource: "verify" };
 }
 /** 修正驗證錯誤或審查意見；成功時回傳實際修正者，未通過時回傳重試後的 run */
 async function applyFix(run, opts) {
@@ -647,24 +846,24 @@ async function applyFix(run, opts) {
     });
     const { r, agent: actual } = outcome;
     const tampered = restorePlan(run, snap);
-    const again = (reason) => ({ run: retry(run, opts.key, reason, opts.backTo) });
+    const again = (reason, category) => ({ run: retry(run, opts.key, reason, opts.backTo, category) });
     if (!r.ok)
-        return again(`${feedback}\n\n（上次修正時 Agent 執行失敗：${r.summary}）`);
+        return again(`${feedback}\n\n（上次修正時 Agent 執行失敗：${r.summary}）`, "agent_error");
     if (tampered.length) {
         await resetTo(repo, before);
-        return again(`${feedback}\n\n另外：${planTamperedMessage(tampered)}`);
+        return again(`${feedback}\n\n另外：${planTamperedMessage(tampered)}`, "plan_tampered");
     }
     await commitAll(repo, `${opts.commitScope}: ${why} [${actual}]`);
     const testRe = new RegExp(cfg.testPattern);
     const deleted = (await changedFiles(repo, before, await headCommit(repo), "D")).filter((f) => testRe.test(f));
     if (deleted.length) {
         await resetTo(repo, before);
-        return again(`${feedback}\n\n另外：不可刪除測試檔來讓檢查通過，已還原：${deleted.join(", ")}`);
+        return again(`${feedback}\n\n另外：不可刪除測試檔來讓檢查通過，已還原：${deleted.join(", ")}`, "tests_deleted");
     }
     const handoffError = finishHandoff(run, outcome, "writer");
     if (handoffError) {
         await resetTo(repo, before);
-        return again(`${feedback}\n\n另外，交接回覆不合格，本次修正已還原：${handoffError}`);
+        return again(`${feedback}\n\n另外，交接回覆不合格，本次修正已還原：${handoffError}`, "handoff_invalid");
     }
     return { agent: actual };
 }
@@ -709,14 +908,14 @@ async function codeReview(run, opts) {
         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) };
+            return { run: retry(opts.step === "review" ? recordModelReviewFailure(run, "review", reviewer) : run, opts.runKey, `Agent 執行失敗：${r.summary}`, opts.backTo, "agent_error") };
         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) };
+            return { run: retry(opts.step === "review" ? recordModelReviewFailure(run, "review", reviewer) : run, opts.runKey, review.error, opts.backTo, "format_invalid") };
         const gate = opts.gate ? { target: "code", verdict: review.data.verdict } : undefined;
         const handoffError = finishHandoff(run, outcome, "reviewer", gate);
         if (handoffError)
-            return { run: retry(opts.step === "review" ? recordModelReviewFailure(run, "review", reviewer) : run, opts.runKey, handoffError, opts.backTo) };
+            return { run: retry(opts.step === "review" ? recordModelReviewFailure(run, "review", reviewer) : run, opts.runKey, handoffError, opts.backTo, "handoff_invalid") };
         if (opts.step === "review")
             run = clearModelReviewFailure(run, "review", reviewer);
         renameSync(flowFile(run, "review.json"), flowFile(run, opts.saveAs(reviewer)));
@@ -753,7 +952,7 @@ async function reviewStage(run) {
     if (!result.objector)
         return succeed(result.state, "review", "pr");
     return {
-        ...retry(result.state, "review", `程式碼審查要求修改：\n\n${result.issues.join("\n\n")}`, "fix"),
+        ...retry(result.state, "review", `程式碼審查要求修改：\n\n${result.issues.join("\n\n")}`, "fix", "review_changes"),
         fixSource: "review",
         lastReviewer: result.objector,
     };
@@ -761,7 +960,7 @@ async function reviewStage(run) {
 async function prStage(run) {
     const pending = openActions(readHandoff(run.id));
     if (pending.length)
-        return { ...run, stage: "failed", failedStage: "pr", failureReason: `仍有未結交接事項：${pending.map((item) => item.id).join("、")}` };
+        return { ...run, stage: "failed", failedStage: "pr", failureCategory: "open_handoff", failureReason: `仍有未結交接事項：${pending.map((item) => item.id).join("、")}` };
     const repo = worktreeDir(run.id);
     const remotes = (await git(repo, "remote")).split("\n").filter(Boolean);
     if (!remotes.includes("origin")) {
@@ -806,6 +1005,7 @@ export async function advance(initial) {
                 ...run,
                 stage: "failed",
                 failedStage: stage,
+                failureCategory: "agent_budget",
                 failureReason: `已執行 agent ${runs} 次，達到上限 ${run.maxAgentRuns}（可用 resume --max-agent-runs 調高）`,
             });
         }
@@ -817,7 +1017,7 @@ export async function advance(initial) {
                 info(run, `⏸️  暫停：${err.message}`);
                 return saveRun({ ...run, stage: "paused", pausedStage: stage, pauseReason: err.message });
             }
-            return saveRun({ ...run, stage: "failed", failedStage: stage, failureReason: err.message });
+            return saveRun({ ...run, stage: "failed", failedStage: stage, failureCategory: "error", failureReason: err.message });
         }
     }
 }