agentflowctl 0.1.0

package/dist/engine.js

@@ -0,0 +1,540 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { config } from "./config.js";
+import { changedFiles, commitAll, discardChanges, git, headCommit, resetTo } from "./git.js";
+import { flowDir, logDir, projectRoot, runDir, worktreeDir } from "./paths.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 { addCost, addSubstitution, agentRuns, getCost, saveRun } from "./store.js";
+import { orderTasks } from "./tasks.js";
+import { readJsonFile, renderPrompt, tail } from "./util.js";
+// ───────────────────────── 共用工具 ─────────────────────────
+const info = (run, msg) => console.log(`[${run.id}] ${msg}`);
+const flowFile = (run, name) => join(flowDir(run.id), name);
+const to = (run, stage) => ({ ...run, stage });
+function target(run, name) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    return { runId: run.id, cwd: worktreeDir(run.id), logFile: join(logDir(run.id), `${stamp}-${name}.log`) };
+}
+/** 額度用完而必須停下：審查類步驟，或所有 agent 的額度都用完 */
+export class QuotaPause extends Error {
+    constructor(message) {
+        super(message);
+    }
+}
+/** 這次執行中已確認額度用完的 agent；程序結束即清空，resume 時會重新嘗試 */
+const exhausted = new Set();
+async function agentStep(run, planned, step, prompt, mode) {
+    const cfg = loadRepoConfig();
+    const reset = mode.reset ?? (() => discardChanges(worktreeDir(run.id)));
+    let agent = planned;
+    for (;;) {
+        if (exhausted.has(agent)) {
+            if (mode.kind === "review") {
+                throw new QuotaPause(`${agent} 的額度已用完；${step} 是審查步驟，不由另一家代打`);
+            }
+            const sub = availableAgent(run.cycle, agent, [...exhausted]);
+            if (!sub)
+                throw new QuotaPause(`所有 agent 的額度都已用完（${[...exhausted].join("、")}）`);
+            const note = step.endsWith("-code") && sub === run.lastTestsAuthor ? "測試與實作由同一家負責" : undefined;
+            addSubstitution(run.id, { step, planned, actual: sub, note });
+            info(run, `🔁 ${agent} 額度已用完，${step} 由 ${sub} 代打${note ? `（注意：${note}）` : ""}`);
+            agent = sub;
+        }
+        const r = await runAgent(agent, resolveAgent(cfg, agent), target(run, `${step}-${agent}`), prompt, {
+            stripApiKeys: cfg.auth === "subscription",
+        });
+        addCost(run.id, { stage: step, agent, usd: r.costUsd, inputTokens: r.inputTokens, outputTokens: r.outputTokens });
+        if (!r.quotaExhausted)
+            return { r, agent };
+        info(run, `⛽ ${agent} 的額度已用完`);
+        exhausted.add(agent);
+        await reset();
+        // 迴圈回到開頭：review 會停下，write 會找代打
+    }
+}
+function readFeedback(run) {
+    const p = flowFile(run, "feedback.md");
+    return existsSync(p) ? readFileSync(p, "utf8") : "";
+}
+/** 關卡未通過：寫入 feedback.md 給下一次嘗試參考，超過上限就讓整個 run 失敗 */
+function retry(run, key, reason, backTo) {
+    const n = (run.attempts[key] ?? 0) + 1;
+    const attempts = { ...run.attempts, [key]: n };
+    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)}` };
+    }
+    info(run, `⚠️  ${key} 未通過，重試（${n}/${config.maxAttempts}）`);
+    return { ...run, attempts, stage: backTo };
+}
+function succeed(run, key, next) {
+    rmSync(flowFile(run, "feedback.md"), { force: true });
+    const attempts = { ...run.attempts };
+    delete attempts[key];
+    return { ...run, attempts, stage: next };
+}
+/** 設定檔放在主專案根目錄，未 commit 的修改也會生效 */
+export function loadRepoConfig() {
+    const p = join(projectRoot(), "flow.config.json");
+    if (!existsSync(p))
+        return RepoConfig.parse({});
+    const r = readJsonFile(p, RepoConfig);
+    if (!r.ok)
+        throw new Error(r.error);
+    return r.data;
+}
+function loadOrderedTasks(run) {
+    const r = readJsonFile(flowFile(run, "tasks.ordered.json"), TaskList);
+    if (!r.ok)
+        throw new Error(r.error);
+    return r.data;
+}
+// ───────────────────────── 各階段 ─────────────────────────
+async function specStage(run) {
+    const agent = specAgent(run.cycle);
+    info(run, `📝 產生規格（${agent}）`);
+    const { r } = await agentStep(run, agent, "spec", renderPrompt("spec", { requirement: run.requirement }), { kind: "write" });
+    await discardChanges(worktreeDir(run.id)); // 這個階段只允許寫 .flow/
+    if (!r.ok)
+        return retry(run, "spec", `Agent 執行失敗：${r.summary}`, "spec");
+    if (!existsSync(flowFile(run, "spec.md")))
+        return retry(run, "spec", "缺少 .flow/spec.md", "spec");
+    const ac = readJsonFile(flowFile(run, "acceptance.json"), AcceptanceList);
+    if (!ac.ok)
+        return retry(run, "spec", ac.error, "spec");
+    const ids = ac.data.map((a) => a.id);
+    if (new Set(ids).size !== ids.length)
+        return retry(run, "spec", "驗收條件 id 有重複", "spec");
+    return succeed(run, "spec", "plan");
+}
+// ── 規格與計畫檔案：審查者與仲裁者只能讀，不能改 ──
+const PLAN_FILES = ["spec.md", "acceptance.json", "plan.md", "tasks.json"];
+function snapshotPlan(run) {
+    return Object.fromEntries(PLAN_FILES.map((f) => [f, existsSync(flowFile(run, f)) ? readFileSync(flowFile(run, f), "utf8") : undefined]));
+}
+/** 把被審查者動過的計畫檔案還原成審查前的內容 */
+function restorePlan(run, snap) {
+    const changed = [];
+    for (const f of PLAN_FILES) {
+        const now = existsSync(flowFile(run, f)) ? readFileSync(flowFile(run, f), "utf8") : undefined;
+        if (now === snap[f])
+            continue;
+        changed.push(f);
+        if (snap[f] === undefined)
+            rmSync(flowFile(run, f), { force: true });
+        else
+            writeFileSync(flowFile(run, f), snap[f]);
+    }
+    return changed;
+}
+/** 計畫的確定性關卡：檔案齊全、格式正確、任務 DAG 合法且涵蓋所有驗收條件 */
+function validatePlan(run) {
+    if (!existsSync(flowFile(run, "spec.md")))
+        return "缺少 .flow/spec.md";
+    if (!existsSync(flowFile(run, "plan.md")))
+        return "缺少 .flow/plan.md";
+    const ac = readJsonFile(flowFile(run, "acceptance.json"), AcceptanceList);
+    if (!ac.ok)
+        return ac.error;
+    const ids = ac.data.map((a) => a.id);
+    if (new Set(ids).size !== ids.length)
+        return "驗收條件 id 有重複";
+    const tasks = readJsonFile(flowFile(run, "tasks.json"), TaskList);
+    if (!tasks.ok)
+        return tasks.error;
+    return orderTasks(tasks.data, new Set(ids));
+}
+function acceptPlan(run, ordered) {
+    writeFileSync(flowFile(run, "tasks.ordered.json"), JSON.stringify(ordered, null, 2));
+}
+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);
+        info(run, `   ${t.id} 測試：${a.tests}　實作：${a.code}`);
+    });
+}
+/** 計畫定案後：預設直接開始實作；--manual-plan 時才停下來等人 */
+function planSettled(run, key) {
+    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" };
+}
+async function planStage(run) {
+    const agent = planAgent(run.cycle);
+    info(run, `🗺️  拆解任務（${agent}）`);
+    const cfg = loadRepoConfig();
+    const { r, agent: actual } = await agentStep(run, agent, "plan", renderPrompt("plan", { testPattern: cfg.testPattern }), { kind: "write" });
+    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");
+    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 round = (run.attempts["plan-review"] ?? 0) + 1;
+    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 { 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); } });
+        await discardChanges(worktreeDir(run.id));
+        const tampered = restorePlan(run, snap);
+        if (tampered.length)
+            info(run, `   ↩️  已還原審查者修改的檔案：${tampered.join(", ")}`);
+        if (!r.ok)
+            return retry(run, "plan-review-run", `Agent 執行失敗：${r.summary}`, "plan_review");
+        const review = readJsonFile(flowFile(run, "plan-review.json"), ReviewResult);
+        if (!review.ok)
+            return retry(run, "plan-review-run", review.error, "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`));
+        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) => `- **${i.criterion}**（${i.status}）：${i.note}`);
+        issueLines.push(...lines);
+        issues.push(`### ${reviewer} 的意見\n\n${lines.join("\n")}`);
+    }
+    if (!firstObjector)
+        return planSettled(run, "plan-review");
+    const report = `計畫審查要求修改：\n\n${issues.join("\n\n")}`;
+    // 僵持偵測：意見和上一輪完全相同，代表修改沒有進展
+    const lastPath = flowFile(run, "plan-review-last.txt");
+    const fingerprint = [...issueLines].sort().join("\n");
+    const stalled = existsSync(lastPath) && readFileSync(lastPath, "utf8") === fingerprint;
+    writeFileSync(lastPath, fingerprint);
+    const exhausted = round >= config.maxAttempts;
+    if ((stalled || exhausted) && cfg.planArbiter) {
+        // 雙盲：帶有審查者名稱的 feedback.md 不留在 worktree，完整報告另存到 worktree 外
+        rmSync(flowFile(run, "feedback.md"), { force: true });
+        mkdirSync(join(runDir(run.id), "reviews"), { recursive: true });
+        writeFileSync(join(runDir(run.id), "reviews", "dispute-full.md"), report);
+        // 給仲裁者的爭議清單不含任何模型名稱
+        writeFileSync(flowFile(run, "dispute.md"), `# 尚未解決的審查意見\n\n${[...new Set(issueLines)].join("\n")}\n`);
+        info(run, `⚖️  計畫審查${stalled ? "意見沒有變化" : `已達 ${round} 輪`}，交付仲裁`);
+        return arbitratePlan({ ...run, planReviewer: firstObjector });
+    }
+    return { ...retry(run, "plan-review", report, "plan_fix"), planReviewer: firstObjector };
+}
+async function planFixStage(run) {
+    const cfg = loadRepoConfig();
+    const agent = planFixAgent(run.cycle, { strategy: cfg.fixStrategy, planWriter: run.planWriter, planReviewer: run.planReviewer });
+    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); } });
+    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");
+    }
+    const ordered = validatePlan(run);
+    if (typeof ordered === "string") {
+        restorePlan(run, snap);
+        return retry(run, "plan-fix", `${feedback}\n\n另外，修改後的計畫沒有通過格式檢查，已還原：\n${ordered}`, "plan_fix");
+    }
+    acceptPlan(run, ordered);
+    writeFileSync(flowFile(run, "feedback.md"), feedback); // 保留審查意見，讓下一輪審查者知道上次提了什麼
+    const attempts = { ...run.attempts };
+    delete attempts["plan-fix"];
+    return { ...run, attempts, stage: "plan_review", planWriter: actual };
+}
+/**
+ * 仲裁：有第三方就由第三方判斷；只有兩家時，兩家各自在全新 context 中雙盲判斷，
+ * 並且看不到誰是作者、誰是審查者。結果依 tieBreak 決定分歧時怎麼辦。
+ */
+async function arbitratePlan(run) {
+    const cfg = loadRepoConfig();
+    const panel = arbiterPanel(run.cycle, run.planWriter, run.planReviewer);
+    const mode = panel.length > 1 ? "雙盲交叉仲裁" : "第三方仲裁";
+    const verdicts = [];
+    for (const arbiter of panel) {
+        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",
+            reset: async () => { await discardChanges(worktreeDir(run.id)); restorePlan(run, snap); },
+        });
+        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 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 });
+    }
+    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 summary = unanimous
+        ? `${mode}一致核准`
+        : approvals === 0
+            ? `${mode}沒有任何一方核准`
+            : `${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");
+    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}`);
+        return planSettled(run, "plan-review");
+    }
+    return { ...run, stage: "failed", failedStage: "plan_review", failureReason: `${summary}，需要人工決定（見 plan.md 的仲裁紀錄）` };
+}
+async function implementStage(run) {
+    const tasks = loadOrderedTasks(run);
+    const task = tasks[run.taskIndex];
+    if (!task) {
+        info(run, "✅ 所有任務完成");
+        return to(run, "verify");
+    }
+    const cfg = loadRepoConfig();
+    const repo = worktreeDir(run.id);
+    const testRe = new RegExp(cfg.testPattern);
+    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);
+    // ── 紅燈：只寫測試，而且測試必須失敗 ──
+    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) });
+        if (!r.ok) {
+            await resetTo(repo, before);
+            return retry(run, key, `Agent 執行失敗：${r.summary}`, "implement");
+        }
+        const commit = await commitAll(repo, `test(${task.id}): ${task.title} [${testsAuthor}]`);
+        if (!commit)
+            return retry(run, key, "沒有任何檔案變更，這個階段必須撰寫測試。", "implement");
+        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");
+        }
+        const red = await runCommand(target(run, `${task.id}-red`), testCmd);
+        if (red.ok) {
+            await resetTo(repo, before);
+            return retry(run, key, "測試在功能尚未實作前就全部通過，代表測試沒有驗證到新行為。請撰寫會因功能尚未實作而失敗的測試。", "implement");
+        }
+        writeFileSync(flowFile(run, "red-output.txt"), red.output);
+        info(run, `🔴 [${progress}] 測試如預期失敗`);
+        return { ...succeed(run, key, "implement"), taskPhase: "code", testsCommit: commit, lastTestsAuthor: testsAuthor };
+    }
+    // ── 綠燈：實作到測試通過，而且不可動測試 ──
+    const key = `${task.id}:code`;
+    const testsCommit = run.testsCommit;
+    if (!testsCommit)
+        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) });
+    if (!r.ok)
+        return retry(run, key, `Agent 執行失敗：${r.summary}`, "implement");
+    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");
+    }
+    const green = await runCommand(target(run, `${task.id}-green`), testCmd);
+    if (!green.ok)
+        return retry(run, key, `測試仍未通過：\n\n\`\`\`\n${tail(green.output)}\n\`\`\``, "implement");
+    info(run, `🟢 [${progress}] 完成`);
+    return {
+        ...succeed(run, key, "implement"),
+        taskIndex: run.taskIndex + 1,
+        taskPhase: "tests",
+        testsCommit: undefined,
+        lastTestsAuthor: undefined,
+        lastWriter: codeAuthor,
+    };
+}
+async function verifyStage(run) {
+    info(run, "🔍 執行驗證");
+    const cfg = loadRepoConfig();
+    const results = [];
+    const install = await runCommand(target(run, "verify-install"), cfg.install);
+    if (!install.ok) {
+        results.push({ name: "install", ok: false, output: tail(install.output) });
+    }
+    else {
+        for (const check of cfg.checks) {
+            const r = await runCommand(target(run, `verify-${check.name}`), check.cmd);
+            info(run, `   ${r.ok ? "✓" : "✗"} ${check.name}`);
+            results.push({ name: check.name, ok: r.ok, output: tail(r.output, 3000) });
+        }
+    }
+    writeFileSync(flowFile(run, "verify.json"), JSON.stringify(results, null, 2));
+    const failed = results.filter((r) => !r.ok);
+    if (failed.length === 0)
+        return succeed(run, "verify", "review");
+    const report = failed.map((f) => `## ${f.name} 失敗\n\n\`\`\`\n${f.output}\n\`\`\``).join("\n\n");
+    return { ...retry(run, "verify", report, "fix"), fixSource: "verify" };
+}
+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 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 }), {
+        kind: "write",
+        reset: () => resetTo(repo, before),
+    });
+    if (!r.ok)
+        return retry(run, "fix", `${feedback}\n\n（上次修正時 Agent 執行失敗：${r.summary}）`, "fix");
+    await commitAll(repo, `fix: ${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 retry(run, "fix", `${feedback}\n\n另外：不可刪除測試檔來讓檢查通過，已還原：${deleted.join(", ")}`, "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);
+    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) {
+        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",
+        });
+        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");
+        renameSync(flowFile(run, "review.json"), flowFile(run, `review-${reviewer}.json`));
+        if (review.data.verdict === "approve") {
+            info(run, `   ✓ ${reviewer} 核准`);
+            continue;
+        }
+        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"));
+    }
+    if (!firstObjector)
+        return succeed(run, "review", "pr");
+    return {
+        ...retry(run, "review", `程式碼審查要求修改：\n\n${issues.join("\n\n")}`, "fix"),
+        fixSource: "review",
+        lastReviewer: firstObjector,
+    };
+}
+async function prStage(run) {
+    const repo = worktreeDir(run.id);
+    const remotes = (await git(repo, "remote")).split("\n").filter(Boolean);
+    if (!remotes.includes("origin")) {
+        info(run, `✅ 沒有 origin，分支 ${run.branch} 已在本機 repo 中，可以直接檢視或合併`);
+        return to(run, "done");
+    }
+    info(run, "🚀 推送分支");
+    await git(repo, "push", "-u", "origin", run.branch);
+    const title = run.requirement.split("\n")[0].slice(0, 72);
+    const spec = existsSync(flowFile(run, "spec.md")) ? readFileSync(flowFile(run, "spec.md"), "utf8") : "";
+    const bodyPath = join(runDir(run.id), "pr-body.md");
+    writeFileSync(bodyPath, `> 由 agentflowctl 自動產生（run: ${run.id}，參與的 agent：${run.cycle.join("、")}，花費約 $${getCost(run.id).toFixed(2)}）\n\n${spec}`);
+    const r = await exec("gh", ["pr", "create", "--head", run.branch, "--base", run.baseBranch, "--title", title, "--body-file", bodyPath], { cwd: repo });
+    if (r.code !== 0) {
+        info(run, `⚠️  gh pr create 失敗，分支已推送，請手動建立 PR：${r.stderr.trim()}`);
+        return to(run, "done");
+    }
+    return { ...to(run, "done"), prUrl: r.stdout.trim() };
+}
+const STAGES = {
+    spec: specStage,
+    plan: planStage,
+    plan_review: planReviewStage,
+    plan_fix: planFixStage,
+    implement: implementStage,
+    verify: verifyStage,
+    fix: fixStage,
+    review: reviewStage,
+    pr: prStage,
+};
+/** 一路推進到需要人介入（awaiting_approval、paused）或結束（done / failed）為止；每一步都寫回檔案，中斷後可接續 */
+export async function advance(initial) {
+    let run = initial;
+    for (;;) {
+        if (["done", "failed", "awaiting_approval", "paused"].includes(run.stage))
+            return run;
+        const stage = run.stage;
+        const runs = agentRuns(run.id);
+        if (runs >= run.maxAgentRuns) {
+            return saveRun({
+                ...run,
+                stage: "failed",
+                failedStage: stage,
+                failureReason: `已執行 agent ${runs} 次，達到上限 ${run.maxAgentRuns}（可用 resume --max-agent-runs 調高）`,
+            });
+        }
+        const cost = getCost(run.id);
+        if (run.budgetUsd !== undefined && cost >= run.budgetUsd) {
+            return saveRun({
+                ...run,
+                stage: "failed",
+                failedStage: stage,
+                failureReason: `估計花費 $${cost.toFixed(2)}，超過預算 $${run.budgetUsd}`,
+            });
+        }
+        try {
+            run = saveRun(await STAGES[stage](run));
+        }
+        catch (err) {
+            if (err instanceof QuotaPause) {
+                info(run, `⏸️  暫停：${err.message}`);
+                return saveRun({ ...run, stage: "paused", pausedStage: stage, pauseReason: err.message });
+            }
+            return saveRun({ ...run, stage: "failed", failedStage: stage, failureReason: err.message });
+        }
+    }
+}
+//# sourceMappingURL=engine.js.map

package/dist/git.js

@@ -0,0 +1,59 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { exec } from "./proc.js";
+/**
+ * agentflowctl 執行 git 時一律停用 hooks 與 fsmonitor。
+ * Agent 現在直接在你的電腦上執行，理論上可以寫入 .git；
+ * 這樣至少確保 agentflowctl 自己的 git 操作不會觸發 repo 內的任何程式。
+ */
+const NO_HOOKS = join(tmpdir(), "agentflowctl-no-hooks"); // 空目錄，各平台通用（Windows 沒有 /dev/null）
+mkdirSync(NO_HOOKS, { recursive: true });
+const SAFE = ["-c", `core.hooksPath=${NO_HOOKS}`, "-c", "core.fsmonitor=false"];
+const AUTHOR = ["-c", "user.name=agentflowctl", "-c", "user.email=agentflowctl@localhost"];
+export async function git(repo, ...args) {
+    const r = await exec("git", [...SAFE, "-C", repo, ...args]);
+    if (r.code !== 0)
+        throw new Error(`git ${args.join(" ")} 失敗：${r.stderr.trim()}`);
+    return r.stdout.trim();
+}
+/** 把路徑加進所有 worktree 共用的 info/exclude（只加一次） */
+export async function excludePaths(root, patterns) {
+    let common = await git(root, "rev-parse", "--git-common-dir");
+    if (!isAbsolute(common))
+        common = join(root, common);
+    const file = join(common, "info", "exclude");
+    const current = existsSync(file) ? readFileSync(file, "utf8") : "";
+    const missing = patterns.filter((p) => !current.split("\n").includes(p));
+    if (missing.length)
+        appendFileSync(file, `\n${missing.join("\n")}\n`);
+}
+/** 從基底分支建立新的 worktree 與分支，共用同一份 git 物件，不需要重新 clone */
+export async function addWorktree(root, dest, base, branch) {
+    await excludePaths(root, [".agentflowctl/", ".flow/"]);
+    await git(root, "worktree", "add", "-b", branch, dest, base);
+}
+export async function removeWorktree(root, dest) {
+    await git(root, "worktree", "remove", "--force", dest);
+}
+export const headCommit = (repo) => git(repo, "rev-parse", "HEAD");
+/** 有變更才 commit，回傳新的 commit hash；沒有變更回傳 undefined */
+export async function commitAll(repo, message) {
+    await git(repo, "add", "-A");
+    if (!(await git(repo, "status", "--porcelain")))
+        return undefined;
+    await git(repo, ...AUTHOR, "commit", "-m", message);
+    return headCommit(repo);
+}
+/** 回到指定 commit 並清掉未追蹤檔案（被 exclude 或 .gitignore 的檔案不受影響） */
+export async function resetTo(repo, commit) {
+    await git(repo, "reset", "--hard", commit);
+    await git(repo, "clean", "-fd");
+}
+export const discardChanges = (repo) => resetTo(repo, "HEAD");
+export async function changedFiles(repo, from, to, filter) {
+    const args = ["diff", "--name-only", ...(filter ? [`--diff-filter=${filter}`] : []), from, to];
+    const out = await git(repo, ...args);
+    return out ? out.split("\n") : [];
+}
+//# sourceMappingURL=git.js.map

package/dist/paths.js

@@ -0,0 +1,22 @@
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+let root;
+/** 目前所在的 git 專案根目錄；agentflowctl 的所有資料都放在 <root>/.agentflowctl/ */
+export function projectRoot() {
+    if (!root) {
+        try {
+            root = execFileSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim();
+        }
+        catch {
+            throw new Error("請在 git 專案資料夾內執行 agentflowctl");
+        }
+    }
+    return root;
+}
+export const agentflowctlDir = () => join(projectRoot(), ".agentflowctl");
+export const runDir = (id) => join(agentflowctlDir(), "runs", id);
+export const logDir = (id) => join(runDir(id), "logs");
+/** 每個 run 一個 git worktree，Agent 只在這裡工作，不碰你正在編輯的檔案 */
+export const worktreeDir = (id) => join(agentflowctlDir(), "worktrees", id);
+export const flowDir = (id) => join(worktreeDir(id), ".flow");
+//# sourceMappingURL=paths.js.map

package/dist/proc.js

@@ -0,0 +1,40 @@
+import { spawn } from "node:child_process";
+export function exec(cmd, args, opts = {}) {
+    return new Promise((resolve, reject) => {
+        const env = { ...process.env, ...opts.env };
+        for (const key of opts.unsetEnv ?? [])
+            delete env[key];
+        const child = spawn(cmd, args, {
+            cwd: opts.cwd,
+            env,
+            shell: opts.shell ?? false,
+        });
+        let stdout = "";
+        let stderr = "";
+        let pending = "";
+        child.stdout.on("data", (d) => {
+            const s = d.toString();
+            stdout += s;
+            if (!opts.onStdoutLine)
+                return;
+            pending += s;
+            const lines = pending.split("\n");
+            pending = lines.pop() ?? "";
+            lines.forEach((line) => opts.onStdoutLine?.(line));
+        });
+        child.stderr.on("data", (d) => {
+            stderr += d.toString();
+        });
+        child.on("error", reject);
+        child.on("close", (code) => {
+            if (opts.onStdoutLine && pending)
+                opts.onStdoutLine(pending);
+            resolve({ code: code ?? 1, stdout, stderr });
+        });
+        child.stdin.on("error", () => { }); // 子程序不讀 stdin 時忽略 EPIPE
+        child.stdin.end(opts.input ?? "");
+    });
+}
+/** 以系統 shell 執行一整行指令（用於 install、test、build 等專案指令） */
+export const execShell = (command, opts = {}) => exec(command, [], { ...opts, shell: true });
+//# sourceMappingURL=proc.js.map