agentflowctl 0.5.0 → 0.7.0

package/README.md

@@ -99,10 +99,11 @@ agentflowctl run --req-file ./req.md --cycle codex,claude --max-agent-runs 40
 agentflowctl run --req "..." --manual-plan   # 計畫通過 AI 審查後，仍停下來等你確認
 
 agentflowctl approve f-xxxx        # 搭配 --manual-plan
-agentflowctl status f-xxxx         # 階段、任務進度、各 agent 用量、代打紀錄
+agentflowctl status f-xxxx         # 階段、上一步結果、未結交接事項、下一步指令、任務進度、各 agent 用量、代打紀錄
 agentflowctl list
 agentflowctl logs f-xxxx           # 列出每一份 log 的編號、結果、階段、步驟、agent
 agentflowctl logs f-xxxx 7         # 解析第 7 份 log，最後附上錯誤整理（--latest 看最新一份）
+agentflowctl logs f-xxxx 7 --full  # 完整顯示多行指令與絕對路徑
 agentflowctl logs f-xxxx 7 --raw   # 原始內容（agent 的 JSON 行）
 agentflowctl resume f-xxxx         # 從暫停、Ctrl-C 或失敗處接續
 agentflowctl cancel f-xxxx
@@ -182,14 +183,14 @@ agentflowctl clean --all           # 清掉所有已結束的 run 與中斷留
 | 標記 | 內容 |
 |---|---|
 | 💬 | agent 的完整文字，不截斷 |
-| 🔧 | 工具呼叫與完整參數 |
+| 🔧 | 工具呼叫。只顯示第一行，多行時註明共幾行；去掉 `/bin/zsh -lc '…'` 這類 shell 包裝，worktree 內的絕對路徑改成相對路徑 |
 | 📊 | token 用量 |
-| 🏁 | 最後結果 |
+| 🏁 | 最後結果。與最後一則 💬 相同時不再重印 |
 | ⚠️ | 工具回報的錯誤。agent 通常會自己換方法繼續，所以不列進錯誤整理 |
 | ❌ | adapter 不認得的錯誤事件 |
 | 📄 | 不是 JSON 的輸出行 |
 
-adapter 不認得、也看不出錯誤跡象的 JSON 行不會顯示，只列出行數，要看全部請加 `--raw`。專案指令的 log 本來就是純文字，會原樣顯示。
+要看完整的工具內容與重複的最後結果，加 `--full`。adapter 不認得、也看不出錯誤跡象的 JSON 行不會顯示，只列出行數，要看全部請加 `--raw`。專案指令的 log 本來就是純文字，會原樣顯示。
 
 最後一段「錯誤」整理出結束碼、agent 回報的失敗、錯誤事件與 stderr：
 
@@ -199,7 +200,7 @@ adapter 不認得、也看不出錯誤跡象的 JSON 行不會顯示，只列出
 檔案 /repo/.agentflowctl/runs/f-xxxx/logs/003-plan-plan-codex.log
 
 💬 先讀 spec.md 與 acceptance.json
-🔧 shell: bash -lc 'cat .flow/spec.md'
+🔧 shell: cat .flow/spec.md
 🏁 失敗：stream disconnected before completion
 
 ── 錯誤 ──
@@ -211,9 +212,33 @@ stderr：
 
 執行成功時，stderr 會放在「其他輸出」段落，不算錯誤。
 
+### 停下來時的結果與下一步
+
+run 因 Ctrl-C、失敗、額度暫停或等待核准而停下時，終端機會直接印出三段；`agentflowctl status <id>` 也會印同樣的內容：
+
+- **結果**：被中斷、還沒有結束紀錄的步驟，以及上一步的結果。agent 的步驟取回覆 `<result>` 的摘要與疑慮；失敗時優先顯示失敗的那一步，並附上結束碼、錯誤事件、stderr 或指令輸出的最後幾行。
+- **未結交接事項**：交接紀錄裡還沒結案的 action 事項（open 或 proposed_resolved）。
+- **下一步**：依狀態列出可以執行的指令，例如 `logs`、`cd` 到 worktree、`resume`、`cancel`、`approve`。
+
+```
+── 結果 ──
+  中斷於 #20 plan_review / plan-review / codex（沒有結束紀錄，resume 時會重跑這一步）
+  #19 plan_fix / plan-fix / claude ✓
+     摘要：接受三條審查意見，拆分 T-3、T-5
+     疑慮：T-15 可能仍太大
+
+── 未結交接事項 ──
+  [plan] c9c730b280e87178 T-3、T-5 各混合多個獨立行為（proposed_resolved）
+
+── 下一步 ──
+  agentflowctl logs f-xxxx 19              看上一步的完整 log
+  agentflowctl resume f-xxxx               從 plan_review 接續
+  agentflowctl cancel f-xxxx               放棄這個 run
+```
+
 ### 出錯時怎麼查
 
-1. run 停下時印出的摘要，或 `agentflowctl status <id>`，會列出失敗的階段、原因、最後一份 log，以及最近失敗的那一份。
+1. 先看 run 停下時印出的「結果」與「下一步」，或執行 `agentflowctl status <id>`。
 2. `agentflowctl logs <id> <編號>` 看那份 log 的錯誤段落。
 3. 解析結果看不出原因時，加 `--raw` 看原始輸出。
 4. 必要時直接在 worktree（`.agentflowctl/worktrees/<id>`）裡修正，再執行 `agentflowctl resume <id>`。
@@ -307,12 +332,14 @@ agentflowctl agent cycle claude-strong,codex,gemini       # 不帶參數時顯
 | 有幾家 | 誰來仲裁 | 結果 |
 | --- | --- | --- |
 | 三家以上 | 沒參與這次討論的那一家 | 核准就繼續，否則 run 失敗 |
-| 兩家 | 兩家各自在全新 context 裡判斷 | 都核准就繼續；都不核准就依裁決意見修訂並重新審查，仲裁達重試上限才停下；分歧依 `tieBreak` |
+| 兩家 | 兩家各自在全新 context 裡判斷 | 都核准就繼續；都不核准就依裁決意見修訂並重新審查；分歧依 `tieBreak` |
 | 一家 | 同一家 | 由它自己仲裁 |
 
-兩家時的仲裁是雙盲的。仲裁者只看計畫，以及一份不含模型名稱的爭議清單（`.flow/dispute.md`）。帶有名稱的審查紀錄移到 worktree 以外。`tieBreak` 預設 `proceed`，因為後面還有測試紅燈、綠燈、verify 與程式碼審查。
+兩家時的仲裁是雙盲的。仲裁者只看計畫，以及一份不含審查者名稱的爭議清單（`.flow/dispute.md`）。爭議清單用 `<issue>` 包住每則意見；給修訂者的 `.flow/feedback.md` 則用 `<opinion author="…">` 包住每位審查者的意見，避免意見內文與外層結構混淆。帶有名稱的審查紀錄移到 worktree 以外。`tieBreak` 預設 `proceed`，因為後面還有測試紅燈、綠燈、verify 與程式碼審查。
 
-計畫定案或仲裁最終停止時，裁決與每位仲裁者的理由附在 `plan.md` 最後的「仲裁紀錄」。需再修訂時，裁決理由寫進 `.flow/feedback.md`，供修訂者處理；重新審查會從第一輪計數。原始審查與每輪仲裁紀錄在 `.agentflowctl/runs/<id>/reviews/`。仲裁最多進行 `AGENTFLOWCTL_MAX_ATTEMPTS` 次，預設三次。
+計畫定案或仲裁最終停止時，裁決與每位仲裁者的理由附在 `plan.md` 最後的「仲裁紀錄」。需再修訂時，裁決理由寫進 `.flow/feedback.md`，供修訂者處理；重新審查會從第一輪計數。原始審查與每輪仲裁紀錄在 `.agentflowctl/runs/<id>/reviews/`。兩家都要求修改時不因仲裁輪數而直接失敗；整個 run 仍受 `maxAgentRuns` 限制。
+
+仲裁 JSON 的 `verdict` 應為 `approve` 或 `changes_requested`；若模型寫成 `reject`，程式會當成 `changes_requested` 並保留理由。缺少檔案、JSON 格式錯誤或其他不合法輸出不算反對票，run 會暫停並顯示驗證錯誤；檢查 `agentflowctl logs <id>` 與 `.flow/plan-arbiter.json` 後可用 `resume` 重新執行。
 
 ## 階段與通過條件
 
@@ -322,7 +349,7 @@ agentflowctl agent cycle claude-strong,codex,gemini       # 不帶參數時顯
 | plan | 與 spec 同一位 | zod、相依存在、無循環、每條驗收條件都有任務 | 重試 |
 | plan_review | 計畫作者以外隨機挑（可多位，不重複） | 所有審查者都 `approve` | 進入 plan_fix |
 | plan_fix | 依 `fixStrategy` | 修改後仍通過 plan 的格式與 DAG 檢查 | 還原並重試 |
-| 仲裁 | 見上一節 | 一致核准；分歧依 `tieBreak` | 兩家都不核准時先進入 plan_fix，達仲裁上限才失敗；第三方不核准或 `tieBreak: stop` 時失敗 |
+| 仲裁 | 見上一節 | 一致核准；分歧依 `tieBreak` | 兩家都不核准時進入 plan_fix 再審查；第三方不核准或 `tieBreak: stop` 時失敗 |
 | 人工確認 | 你（只有 `--manual-plan`） | `agentflowctl approve` | — |
 | implement 紅燈 | 洗牌輪流，每家各一次 | 有測試變更，而且測試執行後失敗 | 還原並重試 |
 | implement 綠燈 | 測試作者以外隨機一位 | 測試檔沒有任何修改，而且測試通過 | 還原，或帶著輸出重試 |
@@ -349,6 +376,14 @@ Agent 的最後回覆要附上 XML 中繼資料：
 
 `blocked` 與 `concerns` 會印在終端機上，完整回覆留在 log，可用 `agentflowctl logs` 查看。這份中繼資料只給人看；缺少或格式錯誤都不影響流程，是否通過仍由上表的程式檢查決定。
 
+### Agent 交接紀錄
+
+每次 agent 執行前，程式會把與當前階段有關的未結事項寫入 `.flow/handoff-context.md`。agent 完成時必須寫 `.flow/handoff-response.json`，包含 `newIssues` 和 `dispositions` 兩個陣列；沒有事項也要明確寫成 `{ "newIssues": [], "dispositions": [] }`。缺少檔案或 JSON 格式不合法，會依該步驟的重試規則處理。
+
+程式只在原有關卡通過後接收交接回覆，並將正式紀錄原子儲存於 `.agentflowctl/runs/<id>/handoff.json`。`action` 是需要後續處理的事項；`info` 只供參考。作者只能提出已修正並附證據，審查者才能確認結案或附理由接受。XML `<concerns>` 可以供人閱讀，但重要疑慮必須寫進交接 JSON，才能交給下一位 agent。額度代打與重試不會接收失敗呼叫的交接內容；中斷後可用 `resume` 接續。
+
+計畫審查或程式碼審查若核准，但該階段仍有未結的 `action`，程式會視為互相矛盾的審查結果並重試。計畫定案和開 PR 前也會再檢查一次；`info` 會提供給目標階段閱讀，但不阻擋通關。
+
 ## Adapter
 
 | adapter | 執行方式 | 權限 |
@@ -401,6 +436,7 @@ src/
   roles.ts          角色分配規則（含計畫修正者與仲裁者）
   runner.ts         執行 agent、正規化結果、執行專案指令
   logs.ts           log 檔名、檔頭檔尾、列表與解析
+  stopReport.ts     run 停下時的結果、未結交接事項與下一步指令
   agents/           claude、codex、gemini、command
   setup.ts          agent setup 互動精靈
   git.ts            worktree 與 git 操作

package/dist/arbitration.js

@@ -1,10 +1,12 @@
-/** 仲裁沒有共識時，兩家先依裁決意見修訂計畫；重複仲裁仍受次數上限約束。 */
-export function arbitrationDecision(verdicts, tieBreak, round, maxAttempts) {
+/** 兩家仲裁都要求修改時交回計畫修訂；整體執行次數由 maxAgentRuns 限制。 */
+export function arbitrationDecision(verdicts, tieBreak) {
+    if (verdicts.includes("abstain"))
+        return "invalid";
     const approvals = verdicts.filter((v) => v === "approve").length;
     if (approvals === verdicts.length)
         return "proceed";
     if (approvals > 0)
         return tieBreak;
-    return verdicts.length === 2 && round < maxAttempts ? "revise" : "stop";
+    return verdicts.length === 2 ? "revise" : "stop";
 }
 //# sourceMappingURL=arbitration.js.map

package/dist/cli.js

@@ -15,6 +15,8 @@ import { flowDir, logDir, projectRoot, worktreeDir } from "./paths.js";
 import { TaskList } from "./schemas.js";
 import { agentRuns, getRun, listRuns, listSubstitutions, saveRun, usageByAgent } from "./store.js";
 import { readJsonFile } from "./util.js";
+import { openActions, readHandoff } from "./handoff.js";
+import { stopReport } from "./stopReport.js";
 import { runSetup, SETUP_ADAPTERS } from "./setup.js";
 import { addAgent, readRawConfig, removeAgent, setAgent, setCycle, writeRawConfig } from "./agentConfig.js";
 function mustGetRun(id) {
@@ -26,12 +28,13 @@ function mustGetRun(id) {
 async function drive(run) {
     // Ctrl-C 會同時送給子程序（claude、測試指令），狀態已經寫在 state.json，之後可用 resume 接續
     process.once("SIGINT", () => {
-        console.log(`\n已中斷，之後可用 agentflowctl resume ${run.id} 接續`);
+        console.log("\n已中斷");
+        printSummary(getRun(run.id) ?? run, true);
         process.exit(130);
     });
     printSummary(await advance(run));
 }
-function printSummary(run) {
+function printSummary(run, interrupted = false) {
     console.log("");
     console.log(`run      ${run.id}`);
     console.log(`階段     ${run.stage}`);
@@ -46,22 +49,21 @@ function printSummary(run) {
     if (run.stage === "failed") {
         console.log(`失敗於   ${run.failedStage ?? "?"}`);
         console.log(`原因     ${run.failureReason ?? "?"}`);
-        const logs = listLogs(logDir(run.id));
-        const last = logs.at(-1);
-        const lastFailed = logs.filter((e) => e.footer && !e.footer.ok).at(-1);
-        if (last)
-            console.log(`最後的 log #${last.seq} ${logMark(last)}（agentflowctl logs ${run.id} ${last.seq}）`);
-        if (lastFailed && lastFailed !== last)
-            console.log(`最近失敗的 log #${lastFailed.seq}（agentflowctl logs ${run.id} ${lastFailed.seq}）`);
-        console.log(`\n必要時直接在 worktree 裡修正，再執行 agentflowctl resume ${run.id}`);
     }
     if (run.stage === "paused") {
         console.log(`暫停於   ${run.pausedStage ?? "?"}`);
         console.log(`原因     ${run.pauseReason ?? "?"}`);
-        console.log(`\n額度恢復後執行 agentflowctl resume ${run.id}`);
     }
-    if (run.stage === "awaiting_approval")
-        console.log(`\n確認計畫後執行 agentflowctl approve ${run.id}`);
+    const report = stopReport({
+        run,
+        interrupted,
+        logs: listLogs(logDir(run.id)),
+        read: (file) => readFileSync(file, "utf8"),
+        open: openActions(readHandoff(run.id)),
+        worktree: worktreeDir(run.id),
+    });
+    for (const line of report)
+        console.log(line);
 }
 /** 決定參與的 agent：指令參數 > flow.config.json > 自動偵測已安裝的 CLI */
 async function resolveCycle(flag) {
@@ -367,6 +369,7 @@ program
     .command("logs <id> [seq]")
     .description("列出 log；指定編號（或 --latest）時顯示解析後的內容，最後附上錯誤整理")
     .option("--latest", "顯示最新一份 log", false)
+    .option("--full", "完整顯示工具內容（多行指令、絕對路徑）與重複的最後回覆", false)
     .option("--raw", "顯示原始內容（agent 的 JSON 行）", false)
     .action((id, seq, opts) => {
     mustGetRun(id);
@@ -379,14 +382,14 @@ program
             const h = e.header;
             console.log(`${String(e.seq).padStart(3)}  ${logMark(e).padEnd(4)}  ${(h?.stage ?? "?").padEnd(12)}  ${(h?.step ?? "?").padEnd(19)}  ${(h?.agent ?? "?").padEnd(10)}  ${localTime(h?.startedAt)}`);
         }
-        console.log(`\n查看內容：agentflowctl logs ${id} <編號>（加 --raw 看原始 JSON）`);
+        console.log(`\n查看內容：agentflowctl logs ${id} <編號>（加 --full 看完整工具內容、--raw 看原始 JSON）`);
         return;
     }
     const entry = seq ? logs.find((e) => e.seq === Number(seq)) : logs.at(-1);
     if (!entry)
         throw new Error(`找不到 log #${seq}（共 ${logs.length} 份，可用 agentflowctl logs ${id} 列出）`);
     const text = readFileSync(entry.file, "utf8");
-    console.log(opts.raw ? text : renderLog(text, entry.file));
+    console.log(opts.raw ? text : renderLog(text, entry.file, { full: opts.full }));
 });
 program.parseAsync().catch((err) => {
     console.error(`錯誤：${err.message}`);

package/dist/engine.js

@@ -4,13 +4,15 @@ import { z } from "zod";
 import { config } from "./config.js";
 import { arbitrationDecision } from "./arbitration.js";
 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 { 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, RepoConfig, ReviewResult, TaskList, } from "./schemas.js";
+import { AcceptanceList, ArbiterResult, RepoConfig, ReviewResult, TaskList, } from "./schemas.js";
 import { addSubstitution, addUsage, agentRuns, saveRun } from "./store.js";
 import { orderTasks } from "./tasks.js";
 import { readJsonFile, renderPrompt, tail } from "./util.js";
@@ -30,6 +32,14 @@ export class QuotaPause extends Error {
 }
 /** 這次執行中已確認額度用完的 agent；程序結束即清空，resume 時會重新嘗試 */
 const exhausted = new Set();
+function handoffTarget(run) {
+    return ["spec", "plan", "plan_review", "plan_fix"].includes(run.stage) ? "plan" : "code";
+}
+/** 同一輪重跑使用相同 key；重試次數或 panel 位置改變時使用新 key。 */
+function handoffKey(run, step, slot, agent) {
+    const attempts = Object.entries(run.attempts).sort(([a], [b]) => a.localeCompare(b));
+    return JSON.stringify([run.id, run.stage, step, run.taskIndex, run.taskPhase, attempts, slot, agent]);
+}
 async function agentStep(run, planned, step, prompt, mode) {
     const cfg = loadRepoConfig();
     const reset = mode.reset ?? (() => discardChanges(worktreeDir(run.id)));
@@ -47,11 +57,13 @@ async function agentStep(run, planned, step, prompt, mode) {
             info(run, `🔁 ${agent} 額度已用完，${step} 由 ${sub} 代打${note ? `（注意：${note}）` : ""}`);
             agent = sub;
         }
+        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), target(run, step, agent), prompt);
         addUsage(run.id, { stage: step, agent, inputTokens: r.inputTokens, outputTokens: r.outputTokens });
         if (!r.quotaExhausted) {
             reportMeta(run, agent, r);
-            return { r, agent };
+            return { r, agent, step, callKey };
         }
         info(run, `⛽ ${agent} 的額度已用完`);
         exhausted.add(agent);
@@ -59,6 +71,28 @@ async function agentStep(run, planned, step, prompt, mode) {
         // 迴圈回到開頭：review 會停下，write 會找代打
     }
 }
+/** 原有關卡已通過後才接受交接；失敗回覆不進入正式紀錄。 */
+function finishHandoff(run, outcome, role, gate) {
+    const parsed = validateHandoffResponse(run.id);
+    if (!parsed.ok)
+        return parsed.error;
+    try {
+        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);
+        if (gate) {
+            const error = reviewHandoffGate(preview, gate.target, gate.verdict);
+            if (error)
+                return error;
+        }
+        acceptHandoff(run.id, outcome.callKey, source, parsed.data, role);
+        return undefined;
+    }
+    catch (error) {
+        return error.message;
+    }
+}
 /** 印出回覆裡的 XML 中繼資料；只供人檢視，關卡仍由程式檢查決定 */
 function reportMeta(run, agent, r) {
     if (!r.meta)
@@ -113,7 +147,8 @@ function loadOrderedTasks(run) {
 async function specStage(run) {
     const agent = specAgent(run.cycle, run.id);
     info(run, `📝 產生規格（${agent}）`);
-    const { r } = await agentStep(run, agent, "spec", renderPrompt("spec", { requirement: run.requirement }), { kind: "write" });
+    const outcome = await agentStep(run, agent, "spec", renderPrompt("spec", { requirement: run.requirement }), { kind: "write" });
+    const { r } = outcome;
     await discardChanges(worktreeDir(run.id)); // 這個階段只允許寫 .flow/
     if (!r.ok)
         return retry(run, "spec", `Agent 執行失敗：${r.summary}`, "spec");
@@ -125,6 +160,9 @@ async function specStage(run) {
     const ids = ac.data.map((a) => a.id);
     if (new Set(ids).size !== ids.length)
         return retry(run, "spec", "驗收條件 id 有重複", "spec");
+    const handoffError = finishHandoff(run, outcome, "writer");
+    if (handoffError)
+        return retry(run, "spec", handoffError, "spec");
     return succeed(run, "spec", "plan");
 }
 // ── 規格與計畫檔案：審查者與仲裁者只能讀，不能改 ──
@@ -177,6 +215,9 @@ function announceTasks(run, ordered) {
 }
 /** 計畫定案後：預設直接開始實作；--manual-plan 時才停下來等人 */
 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");
     const next = run.autopilot ? "implement" : "awaiting_approval";
     const ordered = loadOrderedTasks(run);
     announceTasks(run, ordered);
@@ -192,13 +233,17 @@ async function planStage(run) {
     const agent = planAgent(run.cycle, run.id);
     info(run, `🗺️  拆解任務（${agent}）`);
     const cfg = loadRepoConfig();
-    const { r, agent: actual } = await agentStep(run, agent, "plan", renderPrompt("plan", { testPattern: cfg.testPattern }), { kind: "write" });
+    const outcome = await agentStep(run, agent, "plan", renderPrompt("plan", { testPattern: cfg.testPattern }), { kind: "write" });
+    const { r, agent: actual } = outcome;
     await discardChanges(worktreeDir(run.id));
     if (!r.ok)
         return retry(run, "plan", `Agent 執行失敗：${r.summary}`, "plan");
     const ordered = validatePlan(run);
     if (typeof ordered === "string")
         return retry(run, "plan", ordered, "plan");
+    const handoffError = finishHandoff(run, outcome, "writer");
+    if (handoffError)
+        return retry(run, "plan", handoffError, "plan");
     acceptPlan(run, ordered);
     rmSync(flowFile(run, "plan-review-last.txt"), { force: true });
     return { ...succeed(run, "plan", "plan_review"), planWriter: actual };
@@ -215,7 +260,8 @@ async function planReviewStage(run) {
         info(run, `🧐 計畫審查第 ${round} 輪（${reviewer}，作者 ${author}）`);
         const snap = snapshotPlan(run);
         rmSync(flowFile(run, "plan-review.json"), { force: true });
-        const { r } = await agentStep(run, reviewer, "plan-review", renderPrompt("plan-review", { reviewer, author, requirement: run.requirement }), { kind: "review", reset: async () => { await discardChanges(worktreeDir(run.id)); restorePlan(run, snap); } });
+        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)
@@ -225,6 +271,9 @@ async function planReviewStage(run) {
         const review = readJsonFile(flowFile(run, "plan-review.json"), ReviewResult);
         if (!review.ok)
             return retry(run, "plan-review-run", review.error, "plan_review");
+        const handoffError = finishHandoff(run, outcome, "reviewer", { target: "plan", verdict: review.data.verdict });
+        if (handoffError)
+            return retry(run, "plan-review-run", handoffError, "plan_review");
         // 審查紀錄移到 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`));
@@ -236,9 +285,9 @@ async function planReviewStage(run) {
         firstObjector ??= reviewer;
         const lines = review.data.items
             .filter((i) => i.status !== "met")
-            .map((i) => `- **${i.criterion}**（${i.status}）：${i.note}`);
+            .map((i) => reviewIssue(i.criterion, i.status, i.note));
         issueLines.push(...lines);
-        issues.push(`### ${reviewer} 的意見\n\n${lines.join("\n")}`);
+        issues.push(opinion(reviewer, lines));
     }
     if (!firstObjector)
         return planSettled(run, "plan-review");
@@ -272,7 +321,8 @@ async function planFixStage(run) {
     info(run, `✏️  依 ${run.planReviewer ?? "審查者"} 的意見修改計畫（${agent}）`);
     const feedback = readFeedback(run);
     const snap = snapshotPlan(run);
-    const { r, agent: actual } = 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 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 { r, agent: actual } = outcome;
     await discardChanges(worktreeDir(run.id)); // 只允許改 .flow/
     if (!r.ok) {
         restorePlan(run, snap);
@@ -283,6 +333,11 @@ async function planFixStage(run) {
         restorePlan(run, snap);
         return retry(run, "plan-fix", `${feedback}\n\n另外，修改後的計畫沒有通過格式檢查，已還原：\n${ordered}`, "plan_fix");
     }
+    const handoffError = finishHandoff(run, outcome, "writer");
+    if (handoffError) {
+        restorePlan(run, snap);
+        return retry(run, "plan-fix", handoffError, "plan_fix");
+    }
     acceptPlan(run, ordered);
     writeFileSync(flowFile(run, "feedback.md"), feedback); // 保留審查意見，讓下一輪審查者知道上次提了什麼
     const attempts = { ...run.attempts };
@@ -299,45 +354,54 @@ async function arbitratePlan(run) {
     const panel = arbiterPanel(run.cycle, `${run.id}:arbiter`, run.planWriter, run.planReviewer);
     const mode = panel.length > 1 ? "雙盲交叉仲裁" : "第三方仲裁";
     const verdicts = [];
-    for (const arbiter of panel) {
+    for (const [slot, arbiter] of panel.entries()) {
         info(run, `⚖️  ${mode}（${arbiter}）`);
         const snap = snapshotPlan(run);
         rmSync(flowFile(run, "plan-arbiter.json"), { force: true });
-        const { r } = await agentStep(run, arbiter, "plan-arbiter", renderPrompt("plan-arbiter", { requirement: run.requirement }), {
-            kind: "review",
+        const outcome = await agentStep(run, arbiter, "plan-arbiter", renderPrompt("plan-arbiter", { requirement: run.requirement }), {
+            kind: "review", slot, blind: true,
             reset: async () => { await discardChanges(worktreeDir(run.id)); restorePlan(run, snap); },
         });
+        const { r } = outcome;
         await discardChanges(worktreeDir(run.id));
         restorePlan(run, snap);
-        const result = r.ok ? readJsonFile(flowFile(run, "plan-arbiter.json"), ReviewResult) : undefined;
-        if (result?.ok) {
-            mkdirSync(join(runDir(run.id), "reviews"), { recursive: true });
-            renameSync(flowFile(run, "plan-arbiter.json"), join(runDir(run.id), "reviews", `plan-arbiter-${arbitrationRound}-${arbiter}.json`));
+        const result = r.ok ? readJsonFile(flowFile(run, "plan-arbiter.json"), ArbiterResult) : undefined;
+        const handoffError = result?.ok ? finishHandoff(run, outcome, "reviewer", { target: "plan", verdict: result.data.verdict }) : undefined;
+        if (!result?.ok || handoffError) {
+            const outputError = !r.ok ? `Agent 執行失敗：${r.summary}` : !result ? "未產生有效裁決" : result.ok ? "未產生有效裁決" : result.error;
+            const reason = handoffError ?? outputError;
+            info(run, `   ⏸️  ${arbiter} 未產生有效裁決：${reason}`);
+            return { ...run, stage: "paused", pausedStage: "plan_review", pauseReason: `${arbiter} 仲裁未產生有效裁決：${reason}` };
         }
-        const verdict = result?.ok ? result.data.verdict : "abstain";
-        const notes = result?.ok ? result.data.items.map((i) => `- ${i.criterion}：${i.note}`) : [`- 未產生有效裁決（${r.ok ? "輸出格式錯誤" : r.summary}）`];
-        info(run, `   ${verdict === "approve" ? "✓" : verdict === "abstain" ? "…" : "✗"} ${arbiter}：${verdict === "approve" ? "可以執行" : verdict === "abstain" ? "未裁決" : "不可執行"}`);
-        verdicts.push({ arbiter, verdict, notes });
+        mkdirSync(join(runDir(run.id), "reviews"), { recursive: true });
+        renameSync(flowFile(run, "plan-arbiter.json"), join(runDir(run.id), "reviews", `plan-arbiter-${arbitrationRound}-${arbiter}.json`));
+        const verdict = result.data.verdict;
+        const notes = result.data.items.map((i) => `<issue criterion="${escapeXml(i.criterion)}">${escapeXml(i.note)}</issue>`);
+        const markdownNotes = result.data.items.map((i) => `- ${i.criterion}：${i.note}`);
+        info(run, `   ${verdict === "approve" ? "✓" : "✗"} ${arbiter}：${verdict === "approve" ? "可以執行" : "不可執行"}`);
+        verdicts.push({ arbiter, verdict, notes, markdownNotes });
     }
     rmSync(flowFile(run, "dispute.md"), { 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, arbitrationRound, config.maxAttempts);
+    const decision = arbitrationDecision(verdicts.map((v) => v.verdict), cfg.tieBreak);
+    if (decision === "invalid")
+        throw new Error("仲裁結果缺少有效裁決");
     const summary = unanimous
         ? `${mode}一致核准`
         : approvals === 0
             ? `${mode}沒有任何一方核准${decision === "revise" ? "，交回計畫修訂" : ""}`
             : `${mode}意見分歧，依 tieBreak=${cfg.tieBreak} ${cfg.tieBreak === "proceed" ? "繼續實作" : "停止"}`;
-    const record = verdicts.map((v) => `### ${v.arbiter}（${v.verdict}）\n\n${v.notes.join("\n")}`).join("\n\n");
+    const feedbackRecord = verdicts.map((v) => opinion(v.arbiter, v.notes, v.verdict)).join("\n\n");
     if (decision === "revise") {
         const attempts = { ...run.attempts, "plan-arbitration": arbitrationRound };
         delete attempts["plan-review"];
         rmSync(flowFile(run, "plan-review-last.txt"), { force: true });
-        writeFileSync(flowFile(run, "feedback.md"), `# 仲裁要求修訂（第 ${arbitrationRound} 次）\n\n${summary}\n\n${record}\n`);
+        writeFileSync(flowFile(run, "feedback.md"), `# 仲裁要求修訂（第 ${arbitrationRound} 次）\n\n${summary}\n\n${feedbackRecord}\n`);
         info(run, `   → ${summary}`);
         return { ...run, attempts, stage: "plan_fix" };
     }
-    writeFileSync(flowFile(run, "plan.md"), `${readFileSync(flowFile(run, "plan.md"), "utf8")}\n\n## 仲裁紀錄\n\n**結果：${summary}**\n\n${record}\n`);
+    writeFileSync(flowFile(run, "plan.md"), `${readFileSync(flowFile(run, "plan.md"), "utf8")}\n\n## 仲裁紀錄\n\n**結果：${summary}**\n\n${verdicts.map((v) => `### ${v.arbiter}（${v.verdict}）\n\n${v.markdownNotes.join("\n")}`).join("\n\n")}\n`);
     if (decision === "proceed") {
         info(run, `   → ${summary}`);
         return planSettled(run, "plan-review");
@@ -363,7 +427,8 @@ async function implementStage(run) {
         const key = `${task.id}:tests`;
         info(run, `🧪 [${progress}] 撰寫測試（${agents.tests}）`);
         const before = await headCommit(repo);
-        const { r, agent: testsAuthor } = await agentStep(run, agents.tests, `${task.id}-tests`, renderPrompt("implement-tests", { task: taskJson, testPattern: cfg.testPattern, testCmd }), { kind: "write", reset: () => resetTo(repo, before) });
+        const outcome = await agentStep(run, agents.tests, `${task.id}-tests`, renderPrompt("implement-tests", { task: taskJson, testPattern: cfg.testPattern, testCmd }), { kind: "write", reset: () => resetTo(repo, before) });
+        const { r, agent: testsAuthor } = outcome;
         if (!r.ok) {
             await resetTo(repo, before);
             return retry(run, key, `Agent 執行失敗：${r.summary}`, "implement");
@@ -381,6 +446,11 @@ async function implementStage(run) {
             await resetTo(repo, before);
             return retry(run, key, "測試在功能尚未實作前就全部通過，代表測試沒有驗證到新行為。請撰寫會因功能尚未實作而失敗的測試。", "implement");
         }
+        const handoffError = finishHandoff(run, outcome, "writer");
+        if (handoffError) {
+            await resetTo(repo, before);
+            return retry(run, key, handoffError, "implement");
+        }
         writeFileSync(flowFile(run, "red-output.txt"), red.output);
         info(run, `🔴 [${progress}] 測試如預期失敗`);
         return { ...succeed(run, key, "implement"), taskPhase: "code", testsCommit: commit, lastTestsAuthor: testsAuthor };
@@ -392,7 +462,8 @@ async function implementStage(run) {
         throw new Error("缺少 testsCommit，狀態不一致");
     info(run, `🛠️  [${progress}] 實作（${agents.code}，測試由 ${run.lastTestsAuthor ?? agents.tests} 撰寫）`);
     const redOutput = existsSync(flowFile(run, "red-output.txt")) ? readFileSync(flowFile(run, "red-output.txt"), "utf8") : "";
-    const { r, agent: codeAuthor } = await agentStep(run, agents.code, `${task.id}-code`, renderPrompt("implement-code", { task: taskJson, testCmd, redOutput: tail(redOutput, 3000) }), { kind: "write", reset: () => resetTo(repo, testsCommit) });
+    const outcome = await agentStep(run, agents.code, `${task.id}-code`, renderPrompt("implement-code", { task: taskJson, testCmd, redOutput: tail(redOutput, 3000) }), { kind: "write", reset: () => resetTo(repo, testsCommit) });
+    const { r, agent: codeAuthor } = outcome;
     if (!r.ok)
         return retry(run, key, `Agent 執行失敗：${r.summary}`, "implement");
     await commitAll(repo, `feat(${task.id}): ${task.title} [${codeAuthor}]`);
@@ -406,6 +477,11 @@ async function implementStage(run) {
         info(run, `   ✗ 測試仍未通過${logHint(run, green.seq)}`);
         return retry(run, key, `測試仍未通過：\n\n\`\`\`\n${tail(green.output)}\n\`\`\``, "implement");
     }
+    const handoffError = finishHandoff(run, outcome, "writer");
+    if (handoffError) {
+        await resetTo(repo, testsCommit);
+        return retry(run, key, handoffError, "implement");
+    }
     info(run, `🟢 [${progress}] 完成`);
     return {
         ...succeed(run, key, "implement"),
@@ -454,10 +530,11 @@ async function fixStage(run) {
     const repo = worktreeDir(run.id);
     const feedback = readFeedback(run);
     const before = await headCommit(repo);
-    const { r, agent: actual } = await agentStep(run, agent, "fix", renderPrompt("fix", { testPattern: cfg.testPattern }), {
+    const outcome = await agentStep(run, agent, "fix", renderPrompt("fix", { testPattern: cfg.testPattern }), {
         kind: "write",
         reset: () => resetTo(repo, before),
     });
+    const { r, agent: actual } = outcome;
     if (!r.ok)
         return retry(run, "fix", `${feedback}\n\n（上次修正時 Agent 執行失敗：${r.summary}）`, "fix");
     await commitAll(repo, `fix: ${why} [${actual}]`);
@@ -467,6 +544,11 @@ async function fixStage(run) {
         await resetTo(repo, before);
         return retry(run, "fix", `${feedback}\n\n另外：不可刪除測試檔來讓檢查通過，已還原：${deleted.join(", ")}`, "fix");
     }
+    const handoffError = finishHandoff(run, outcome, "writer");
+    if (handoffError) {
+        await resetTo(repo, before);
+        return retry(run, "fix", handoffError, "fix");
+    }
     // 修正者成為新的作者，下一輪審查會換成別人
     return { ...to(run, "verify"), lastWriter: actual };
 }
@@ -479,18 +561,22 @@ async function reviewStage(run) {
         .map((s) => s.slice(1, -1));
     const issues = [];
     let firstObjector;
-    for (const reviewer of panel) {
+    for (const [slot, reviewer] of panel.entries()) {
         info(run, `👀 程式碼審查（${reviewer}）`);
         rmSync(flowFile(run, "review.json"), { force: true });
-        const { r } = await agentStep(run, reviewer, "review", renderPrompt("review", { reviewer, authors: authors.join("、") || "未知" }), {
-            kind: "review",
+        const outcome = await agentStep(run, reviewer, "review", renderPrompt("review", { reviewer, authors: authors.join("、") || "未知" }), {
+            kind: "review", slot,
         });
+        const { r } = outcome;
         await discardChanges(repo); // 審查者不可改程式碼
         if (!r.ok)
             return retry(run, "review-run", `Agent 執行失敗：${r.summary}`, "review");
         const review = readJsonFile(flowFile(run, "review.json"), ReviewResult);
         if (!review.ok)
             return retry(run, "review-run", review.error, "review");
+        const handoffError = finishHandoff(run, outcome, "reviewer", { target: "code", verdict: review.data.verdict });
+        if (handoffError)
+            return retry(run, "review-run", handoffError, "review");
         renameSync(flowFile(run, "review.json"), flowFile(run, `review-${reviewer}.json`));
         if (review.data.verdict === "approve") {
             info(run, `   ✓ ${reviewer} 核准`);
@@ -498,11 +584,9 @@ async function reviewStage(run) {
         }
         info(run, `   ✗ ${reviewer} 要求修改`);
         firstObjector ??= reviewer;
-        issues.push(`### ${reviewer} 的意見\n\n` +
-            review.data.items
-                .filter((i) => i.status !== "met")
-                .map((i) => `- **${i.criterion}**（${i.status}）：${i.note}`)
-                .join("\n"));
+        issues.push(opinion(reviewer, review.data.items
+            .filter((i) => i.status !== "met")
+            .map((i) => reviewIssue(i.criterion, i.status, i.note))));
     }
     if (!firstObjector)
         return succeed(run, "review", "pr");
@@ -513,6 +597,9 @@ 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("、")}` };
     const repo = worktreeDir(run.id);
     const remotes = (await git(repo, "remote")).split("\n").filter(Boolean);
     if (!remotes.includes("origin")) {
@@ -546,6 +633,7 @@ const STAGES = {
 /** 一路推進到需要人介入（awaiting_approval、paused）或結束（done / failed）為止；每一步都寫回檔案，中斷後可接續 */
 export async function advance(initial) {
     let run = initial;
+    recoverHandoff(run.id);
     for (;;) {
         if (["done", "failed", "awaiting_approval", "paused"].includes(run.stage))
             return run;

package/dist/feedback.js

@@ -0,0 +1,15 @@
+/** agent 提供的文字必須跳脫，才不會打斷意見的 XML 邊界。 */
+export function escapeXml(value) {
+    return value.replace(/[&<>"']/g, (char) => ({
+        "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&apos;",
+    })[char]);
+}
+export function reviewIssue(criterion, status, note) {
+    return `<issue criterion="${escapeXml(criterion)}" status="${escapeXml(status)}">${escapeXml(note)}</issue>`;
+}
+export function opinion(author, issues, verdict) {
+    const name = escapeXml(author);
+    const outcome = verdict ? ` verdict="${escapeXml(verdict)}"` : "";
+    return `<opinion author="${name}"${outcome}>\n${issues.join("\n")}\n</opinion>`;
+}
+//# sourceMappingURL=feedback.js.map