agentflowctl 0.4.0 → 0.6.0

package/dist/engine.js

@@ -2,14 +2,16 @@ import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync
 import { join } from "node:path";
 import { z } from "zod";
 import { config } from "./config.js";
+import { arbitrationDecision } from "./arbitration.js";
 import { detectProjectDefaults, withProjectDefaults } from "./detect.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";
@@ -29,6 +31,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)));
@@ -38,7 +48,7 @@ async function agentStep(run, planned, step, prompt, mode) {
             if (mode.kind === "review") {
                 throw new QuotaPause(`${agent} 的額度已用完；${step} 是審查步驟，不由另一家代打`);
             }
-            const sub = availableAgent(run.cycle, agent, [...exhausted]);
+            const sub = availableAgent(run.cycle, agent, [...exhausted], `${run.id}:${step}:sub`);
             if (!sub)
                 throw new QuotaPause(`所有 agent 的額度都已用完（${[...exhausted].join("、")}）`);
             const note = step.endsWith("-code") && sub === run.lastTestsAuthor ? "測試與實作由同一家負責" : undefined;
@@ -46,11 +56,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);
@@ -58,6 +70,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)
@@ -110,9 +144,10 @@ function loadOrderedTasks(run) {
 }
 // ───────────────────────── 各階段 ─────────────────────────
 async function specStage(run) {
-    const agent = specAgent(run.cycle);
+    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");
@@ -124,6 +159,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");
 }
 // ── 規格與計畫檔案：審查者與仲裁者只能讀，不能改 ──
@@ -170,40 +208,50 @@ function announceTasks(run, ordered) {
     const cfg = loadRepoConfig();
     info(run, `📋 共 ${ordered.length} 個任務：${ordered.map((t) => t.id).join(" → ")}`);
     ordered.forEach((t, i) => {
-        const a = taskAgents(run.cycle, i, cfg.tddSplit);
+        const a = taskAgents(run.cycle, i, cfg.tddSplit, run.id);
         info(run, `   ${t.id} 測試：${a.tests}　實作：${a.code}`);
     });
 }
 /** 計畫定案後：預設直接開始實作；--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);
     if (!run.autopilot) {
         info(run, `✋ 計畫已通過審查，請檢視 ${flowFile(run, "plan.md")}，確認後執行 agentflowctl approve ${run.id}`);
     }
-    return { ...succeed(run, key, next), taskIndex: 0, taskPhase: "tests" };
+    const settled = succeed(run, key, next);
+    const attempts = { ...settled.attempts };
+    delete attempts["plan-arbitration"];
+    return { ...settled, attempts, taskIndex: 0, taskPhase: "tests" };
 }
 async function planStage(run) {
-    const agent = planAgent(run.cycle);
+    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 };
 }
 async function planReviewStage(run) {
     const cfg = loadRepoConfig();
-    const author = run.planWriter ?? planAgent(run.cycle);
-    const panel = reviewers(run.cycle, author, cfg.planReviewQuorum);
+    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;
@@ -211,7 +259,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)
@@ -221,6 +270,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`));
@@ -259,11 +311,17 @@ async function planReviewStage(run) {
 }
 async function planFixStage(run) {
     const cfg = loadRepoConfig();
-    const agent = planFixAgent(run.cycle, { strategy: cfg.fixStrategy, planWriter: run.planWriter, planReviewer: run.planReviewer });
+    const agent = planFixAgent(run.cycle, {
+        strategy: cfg.fixStrategy,
+        planWriter: run.planWriter,
+        planReviewer: run.planReviewer,
+        seed: `${run.id}:plan-fix:${run.attempts["plan-review"] ?? 0}`,
+    });
     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);
@@ -274,6 +332,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 };
@@ -286,39 +349,56 @@ async function planFixStage(run) {
  */
 async function arbitratePlan(run) {
     const cfg = loadRepoConfig();
-    const panel = arbiterPanel(run.cycle, run.planWriter, run.planReviewer);
+    const arbitrationRound = (run.attempts["plan-arbitration"] ?? 0) + 1;
+    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-${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" ? "未裁決" : "不可執行"}`);
+        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) => `- ${i.criterion}：${i.note}`);
+        info(run, `   ${verdict === "approve" ? "✓" : "✗"} ${arbiter}：${verdict === "approve" ? "可以執行" : "不可執行"}`);
         verdicts.push({ arbiter, verdict, notes });
     }
     rmSync(flowFile(run, "dispute.md"), { force: true });
     const approvals = verdicts.filter((v) => v.verdict === "approve").length;
     const unanimous = approvals === verdicts.length;
-    const decision = unanimous ? "proceed" : approvals === 0 ? "stop" : cfg.tieBreak;
+    const decision = arbitrationDecision(verdicts.map((v) => v.verdict), cfg.tieBreak);
+    if (decision === "invalid")
+        throw new Error("仲裁結果缺少有效裁決");
     const summary = unanimous
         ? `${mode}一致核准`
         : approvals === 0
-            ? `${mode}沒有任何一方核准`
+            ? `${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");
+    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`);
+        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`);
     if (decision === "proceed") {
         info(run, `   → ${summary}`);
@@ -339,13 +419,14 @@ async function implementStage(run) {
     const testCmd = `${cfg.install} && ${cfg.test}`;
     const progress = `${run.taskIndex + 1}/${tasks.length} ${task.id} ${task.title}`;
     const taskJson = JSON.stringify(task, null, 2);
-    const agents = taskAgents(run.cycle, run.taskIndex, cfg.tddSplit);
+    const agents = taskAgents(run.cycle, run.taskIndex, cfg.tddSplit, run.id);
     // ── 紅燈：只寫測試，而且測試必須失敗 ──
     if (run.taskPhase === "tests") {
         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");
@@ -363,6 +444,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 };
@@ -374,7 +460,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}]`);
@@ -388,6 +475,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"),
@@ -424,16 +516,23 @@ async function verifyStage(run) {
 async function fixStage(run) {
     const cfg = loadRepoConfig();
     const source = run.fixSource ?? "verify";
-    const agent = fixAgent(run.cycle, { source, strategy: cfg.fixStrategy, lastWriter: run.lastWriter, lastReviewer: run.lastReviewer });
+    const agent = fixAgent(run.cycle, {
+        source,
+        strategy: cfg.fixStrategy,
+        lastWriter: run.lastWriter,
+        lastReviewer: run.lastReviewer,
+        seed: `${run.id}:fix:${run.attempts.review ?? 0}`,
+    });
     const why = source === "review" ? `依 ${run.lastReviewer ?? "reviewer"} 的審查意見` : "修正驗證錯誤";
     info(run, `🩹 ${why}（${agent}）`);
     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}]`);
@@ -443,30 +542,39 @@ 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 };
 }
 async function reviewStage(run) {
     const cfg = loadRepoConfig();
     const repo = worktreeDir(run.id);
-    const panel = reviewers(run.cycle, run.lastWriter, cfg.reviewQuorum);
+    const panel = reviewers(run.cycle, run.lastWriter, cfg.reviewQuorum, `${run.id}:review:${run.attempts.review ?? 0}`);
     writeFileSync(flowFile(run, "diff.patch"), await git(repo, "diff", `${run.baseBranch}...HEAD`));
     const authors = [...new Set((await git(repo, "log", "--format=%s", `${run.baseBranch}..HEAD`)).match(/\[[^\]]+\]$/gm) ?? [])]
         .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} 核准`);
@@ -489,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")) {
@@ -522,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/handoff.js

@@ -0,0 +1,109 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+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");
+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`);
+const Receipt = z.object({ callKey: z.string(), source: HandoffSource, response: HandoffResponse, role: z.enum(["writer", "reviewer"]) });
+function writeAtomic(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, content);
+    renameSync(tmp, path);
+}
+export function readHandoff(id) {
+    const path = handoffPath(id);
+    if (!existsSync(path))
+        return { version: 1, issues: [] };
+    return HandoffLedger.parse(JSON.parse(readFileSync(path, "utf8")));
+}
+export function openActions(ledger, target) {
+    return ledger.issues.filter((item) => item.kind === "action"
+        && (item.status === "open" || item.status === "proposed_resolved")
+        && (!target || item.targetStage === target));
+}
+export function reviewHandoffGate(ledger, target, verdict) {
+    if (verdict !== "approve")
+        return undefined;
+    const pending = openActions(ledger, target);
+    return pending.length ? `審查核准與未結交接事項矛盾：${pending.map((item) => item.id).join("、")}` : undefined;
+}
+export function previewHandoff(ledger, callKey, source, response, role) {
+    source = HandoffSource.parse(source);
+    response = HandoffResponse.parse(response);
+    if (source.callKey !== callKey)
+        throw new Error("交接呼叫識別碼不一致");
+    if (ledger.appliedCalls?.includes(callKey))
+        return ledger;
+    const now = new Date().toISOString();
+    const issues = ledger.issues.map((item) => ({ ...item }));
+    for (const [index, item] of response.newIssues.entries()) {
+        const id = createHash("sha256").update(`${callKey}:${index}`).digest("hex").slice(0, 16);
+        if (issues.some((existing) => existing.id === id))
+            throw new Error(`交接事項 id 重複：${id}`);
+        issues.push({ id, source, ...item, status: "open", updatedAt: now });
+    }
+    for (const disposition of response.dispositions) {
+        const issue = issues.find((item) => item.id === disposition.id);
+        if (!issue)
+            throw new Error(`找不到交接事項：${disposition.id}`);
+        if (issue.kind !== "action")
+            throw new Error(`參考資訊不可結案：${disposition.id}`);
+        if (issue.status === "resolved" || issue.status === "accepted")
+            throw new Error(`交接事項已結案：${disposition.id}`);
+        if (role === "writer" && disposition.status !== "proposed_resolved")
+            throw new Error("作者只能提出已修正，不能自行結案");
+        if (role === "reviewer" && disposition.status === "proposed_resolved")
+            throw new Error("審查者須明確結案或接受風險");
+        issue.status = disposition.status;
+        issue.resolution = { agent: source.agent, reason: disposition.reason, evidence: disposition.evidence };
+        issue.updatedAt = now;
+    }
+    return HandoffLedger.parse({ version: 1, issues, appliedCalls: [...(ledger.appliedCalls ?? []), callKey] });
+}
+export function mergeHandoff(id, callKey, source, response, role) {
+    const next = previewHandoff(readHandoff(id), callKey, source, response, role);
+    writeAtomic(handoffPath(id), JSON.stringify(next, null, 2));
+    return next;
+}
+/** 只把目前步驟需要處理的事項投影給 agent。 */
+export function prepareHandoff(id, _callKey, target, blind) {
+    const items = readHandoff(id).issues.filter((item) => item.targetStage === target && (item.kind === "info" || item.status === "open" || item.status === "proposed_resolved"));
+    const lines = items.map((item) => {
+        const source = blind ? "" : `\n來源：${item.source.stage}／${item.source.agent}`;
+        const resolution = item.resolution ? `\n處理理由：${item.resolution.reason}\n處理證據：${item.resolution.evidence}` : "";
+        return `## ${item.id}：${item.summary}\n證據：${item.evidence}\n狀態：${item.status}${resolution}${source}`;
+    });
+    mkdirSync(flowDir(id), { recursive: true });
+    writeFileSync(join(flowDir(id), "handoff-context.md"), `# 待處理交接事項\n\n${lines.length ? lines.join("\n\n") : "目前沒有待處理事項。"}\n`);
+    rmSync(responsePath(id), { force: true });
+}
+export function validateHandoffResponse(id) {
+    return readJsonFile(responsePath(id), HandoffResponse);
+}
+/** 已通過原有關卡的回覆先記收據，再合併；中斷後可重播。 */
+export function acceptHandoff(id, callKey, source, response, role) {
+    const checked = Receipt.parse({ callKey, source, response, role });
+    previewHandoff(readHandoff(id), callKey, source, response, role);
+    const path = receiptPath(id, callKey);
+    writeAtomic(path, JSON.stringify(checked));
+    mergeHandoff(id, callKey, source, response, role);
+    rmSync(path, { force: true });
+}
+export function recoverHandoff(id) {
+    const dir = receiptsDir(id);
+    if (!existsSync(dir))
+        return;
+    for (const name of readdirSync(dir).filter((f) => f.endsWith(".json"))) {
+        const path = join(dir, name);
+        const receipt = Receipt.parse(JSON.parse(readFileSync(path, "utf8")));
+        mergeHandoff(id, receipt.callKey, receipt.source, receipt.response, receipt.role);
+        rmSync(path);
+    }
+}
+//# sourceMappingURL=handoff.js.map

package/dist/paths.js

@@ -17,6 +17,7 @@ export const agentflowctlDir = () => join(projectRoot(), ".agentflowctl");
 export const runsDir = () => join(agentflowctlDir(), "runs");
 export const runDir = (id) => join(runsDir(), id);
 export const logDir = (id) => join(runDir(id), "logs");
+export const handoffPath = (id) => join(runDir(id), "handoff.json");
 /** 每個 run 一個 git worktree，Agent 只在這裡工作，不碰你正在編輯的檔案 */
 export const worktreesDir = () => join(agentflowctlDir(), "worktrees");
 export const worktreeDir = (id) => join(worktreesDir(), id);