agentflowctl 0.3.0 → 0.5.0

package/dist/engine.js

@@ -1,8 +1,12 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { z } from "zod";
 import { config } from "./config.js";
+import { arbitrationDecision } from "./arbitration.js";
+import { detectProjectDefaults, withProjectDefaults } from "./detect.js";
 import { changedFiles, commitAll, discardChanges, git, headCommit, resetTo } from "./git.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";
@@ -12,11 +16,11 @@ import { orderTasks } from "./tasks.js";
 import { readJsonFile, renderPrompt, tail } from "./util.js";
 // ───────────────────────── 共用工具 ─────────────────────────
 const info = (run, msg) => console.log(`[${run.id}] ${msg}`);
+const logHint = (run, seq) => `（agentflowctl logs ${run.id} ${seq}）`;
 const flowFile = (run, name) => join(flowDir(run.id), name);
 const to = (run, stage) => ({ ...run, stage });
-function target(run, name) {
-    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-    return { runId: run.id, cwd: worktreeDir(run.id), logFile: join(logDir(run.id), `${stamp}-${name}.log`) };
+function target(run, step, agent) {
+    return { runId: run.id, cwd: worktreeDir(run.id), logFile: nextLogFile(logDir(run.id), run.stage, step, agent), stage: run.stage, step };
 }
 /** 額度用完而必須停下：審查類步驟，或所有 agent 的額度都用完 */
 export class QuotaPause extends Error {
@@ -35,7 +39,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;
@@ -43,7 +47,7 @@ async function agentStep(run, planned, step, prompt, mode) {
             info(run, `🔁 ${agent} 額度已用完，${step} 由 ${sub} 代打${note ? `（注意：${note}）` : ""}`);
             agent = sub;
         }
-        const r = await runAgent(agent, resolveAgent(cfg, agent), target(run, `${step}-${agent}`), prompt);
+        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);
@@ -72,6 +76,7 @@ function readFeedback(run) {
 function retry(run, key, reason, backTo) {
     const n = (run.attempts[key] ?? 0) + 1;
     const attempts = { ...run.attempts, [key]: n };
+    mkdirSync(flowDir(run.id), { recursive: true });
     writeFileSync(flowFile(run, "feedback.md"), `# 前次嘗試未通過（第 ${n} 次）\n\n${reason}\n`);
     if (n >= config.maxAttempts) {
         return { ...run, attempts, stage: "failed", failedStage: backTo, failureReason: `${key} 連續失敗 ${n} 次：${tail(reason, 500)}` };
@@ -86,11 +91,14 @@ function succeed(run, key, next) {
     return { ...run, attempts, stage: next };
 }
 /** 設定檔放在主專案根目錄，未 commit 的修改也會生效 */
+/** 讀取 flow.config.json；沒寫的 install、test、checks 依專案現況偵測 */
 export function loadRepoConfig() {
-    const p = join(projectRoot(), "flow.config.json");
+    const root = projectRoot();
+    const detected = detectProjectDefaults(root);
+    const p = join(root, "flow.config.json");
     if (!existsSync(p))
-        return RepoConfig.parse({});
-    const r = readJsonFile(p, RepoConfig);
+        return RepoConfig.parse(withProjectDefaults({}, detected));
+    const r = readJsonFile(p, z.preprocess((raw) => withProjectDefaults(raw, detected), RepoConfig));
     if (!r.ok)
         throw new Error(r.error);
     return r.data;
@@ -103,7 +111,7 @@ 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" });
     await discardChanges(worktreeDir(run.id)); // 這個階段只允許寫 .flow/
@@ -163,7 +171,7 @@ 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}`);
     });
 }
@@ -175,10 +183,13 @@ function planSettled(run, key) {
     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" });
@@ -194,9 +205,9 @@ async function planStage(run) {
 }
 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;
@@ -252,7 +263,12 @@ 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);
@@ -279,7 +295,8 @@ 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) {
@@ -295,7 +312,7 @@ async function arbitratePlan(run) {
         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`));
+            renameSync(flowFile(run, "plan-arbiter.json"), join(runDir(run.id), "reviews", `plan-arbiter-${arbitrationRound}-${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}）`];
@@ -305,13 +322,21 @@ async function arbitratePlan(run) {
     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, arbitrationRound, config.maxAttempts);
     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}`);
@@ -332,7 +357,7 @@ 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`;
@@ -351,7 +376,7 @@ async function implementStage(run) {
             await resetTo(repo, before);
             return retry(run, key, `沒有新增或修改任何符合 /${cfg.testPattern}/ 的測試檔。`, "implement");
         }
-        const red = await runCommand(target(run, `${task.id}-red`), testCmd);
+        const red = await runCommand(target(run, `${task.id}-red`, CMD_AGENT), testCmd);
         if (red.ok) {
             await resetTo(repo, before);
             return retry(run, key, "測試在功能尚未實作前就全部通過，代表測試沒有驗證到新行為。請撰寫會因功能尚未實作而失敗的測試。", "implement");
@@ -376,9 +401,11 @@ async function implementStage(run) {
         await resetTo(repo, testsCommit);
         return retry(run, key, `實作階段不可修改測試檔，已還原你的變更：${touched.join(", ")}`, "implement");
     }
-    const green = await runCommand(target(run, `${task.id}-green`), testCmd);
-    if (!green.ok)
+    const green = await runCommand(target(run, `${task.id}-green`, CMD_AGENT), testCmd);
+    if (!green.ok) {
+        info(run, `   ✗ 測試仍未通過${logHint(run, green.seq)}`);
         return retry(run, key, `測試仍未通過：\n\n\`\`\`\n${tail(green.output)}\n\`\`\``, "implement");
+    }
     info(run, `🟢 [${progress}] 完成`);
     return {
         ...succeed(run, key, "implement"),
@@ -393,14 +420,15 @@ async function verifyStage(run) {
     info(run, "🔍 執行驗證");
     const cfg = loadRepoConfig();
     const results = [];
-    const install = await runCommand(target(run, "verify-install"), cfg.install);
+    const install = await runCommand(target(run, "install", CMD_AGENT), cfg.install);
     if (!install.ok) {
+        info(run, `   ✗ install${logHint(run, install.seq)}`);
         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}`);
+            const r = await runCommand(target(run, check.name, CMD_AGENT), check.cmd);
+            info(run, `   ${r.ok ? "✓" : "✗"} ${check.name}${r.ok ? "" : logHint(run, r.seq)}`);
             results.push({ name: check.name, ok: r.ok, output: tail(r.output, 3000) });
         }
     }
@@ -414,7 +442,13 @@ 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);
@@ -439,7 +473,7 @@ async function fixStage(run) {
 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));

package/dist/logs.js

@@ -0,0 +1,173 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { ADAPTERS } from "./agents/index.js";
+import { str, tryJson } from "./agents/types.js";
+/**
+ * 每次執行 agent 或專案指令都寫成一份 log：
+ * - 檔名：<三位數序號>-<階段>-<步驟>-<agent>.log，專案指令的 agent 欄位是 cmd
+ * - 第一行：`# agentflowctl {...}`，記錄階段、步驟、agent、開始時間
+ * - 中間：agent 的原始 stdout（JSON 行）或指令輸出，原樣保存；stderr 接在 `[stderr]` 之後
+ * - 最後一行：`# exit {...}`，記錄結束碼與是否成功；沒有這行代表還在執行或被中斷
+ */
+export const HEADER_PREFIX = "# agentflowctl ";
+export const FOOTER_PREFIX = "# exit ";
+export const STDERR_MARK = "[stderr]";
+/** 專案指令（install、測試、checks）的 agent 欄位 */
+export const CMD_AGENT = "cmd";
+const segment = (s) => s.replace(/[\s/\\:*?"<>|]+/g, "_");
+/** 下一份 log 的完整路徑；序號接在目錄裡最大的序號之後 */
+export function nextLogFile(dir, stage, step, agent) {
+    const seqs = existsSync(dir) ? readdirSync(dir).map((f) => Number(f.match(/^(\d+)-/)?.[1] ?? 0)) : [];
+    const seq = Math.max(0, ...seqs) + 1;
+    return join(dir, `${String(seq).padStart(3, "0")}-${segment(stage)}-${segment(step)}-${segment(agent)}.log`);
+}
+export const logSeq = (file) => Number(file.split(/[\\/]/).at(-1)?.match(/^(\d+)-/)?.[1] ?? 0);
+export const headerLine = (h) => `${HEADER_PREFIX}${JSON.stringify(h)}`;
+export const footerLine = (f) => `${FOOTER_PREFIX}${JSON.stringify(f)}`;
+function parseLog(text) {
+    const out = { body: [], stderr: [] };
+    let inStderr = false;
+    for (const line of text.split("\n")) {
+        if (line.startsWith(HEADER_PREFIX) && !out.header)
+            out.header = tryJson(line.slice(HEADER_PREFIX.length));
+        else if (line.startsWith(FOOTER_PREFIX))
+            out.footer = tryJson(line.slice(FOOTER_PREFIX.length));
+        else if (line === STDERR_MARK)
+            inStderr = true;
+        else
+            (inStderr ? out.stderr : out.body).push(line);
+    }
+    while (out.stderr.at(-1) === "")
+        out.stderr.pop();
+    while (out.body.at(-1) === "")
+        out.body.pop();
+    return out;
+}
+/** 依序號列出 run 的所有 log，只讀檔頭與檔尾 */
+export function listLogs(dir) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((f) => /^\d+-.*\.log$/.test(f))
+        .map((f) => {
+        const file = join(dir, f);
+        const { header, footer } = parseLog(readFileSync(file, "utf8"));
+        return { seq: logSeq(f), file, header, footer };
+    })
+        .sort((a, b) => a.seq - b.seq);
+}
+/** 執行結果：✓ 成功、✗ 失敗、… 沒有檔尾（還在執行或被中斷） */
+export const logMark = (e) => (!e.footer ? "…" : e.footer.ok ? "✓" : "✗");
+/** ISO 時間轉成本地時間 YYYY-MM-DD HH:mm:ss */
+export function localTime(iso) {
+    const d = iso ? new Date(iso) : undefined;
+    if (!d || Number.isNaN(d.getTime()))
+        return "?";
+    const p = (n) => String(n).padStart(2, "0");
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+}
+const clip = (s, max = 800) => (s.length <= max ? s : `${s.slice(0, max)}…（共 ${s.length} 字）`);
+const indent = (s, pad = "   ") => s.split("\n").join(`\n${pad}`);
+/** 從沒被 adapter 認得的 JSON 事件裡找錯誤：頂層的 error 類事件算失敗，工具回報的錯誤只當作提示 */
+function findError(ev) {
+    const pick = (o) => {
+        const err = o.error;
+        const nested = err && typeof err === "object" ? str(err.message) : undefined;
+        const content = Array.isArray(o.content)
+            ? o.content.map((c) => (c && typeof c === "object" ? str(c.text) : str(c))).filter(Boolean).join("\n")
+            : str(o.content);
+        return nested ?? str(err) ?? str(o.message) ?? (content || undefined) ?? str(o.result) ?? JSON.stringify(o);
+    };
+    if (ev.is_error === true || ev.error || /error|fail/i.test(str(ev.type) ?? "") || /error|fail/i.test(str(ev.subtype) ?? "")) {
+        return { message: clip(pick(ev)), fatal: true };
+    }
+    const walk = (v, depth) => {
+        if (!v || typeof v !== "object" || depth > 4)
+            return undefined;
+        if (!Array.isArray(v) && v.is_error === true)
+            return v;
+        for (const child of Object.values(v)) {
+            const hit = walk(child, depth + 1);
+            if (hit)
+                return hit;
+        }
+        return undefined;
+    };
+    const hit = walk(ev, 0);
+    return hit ? { message: clip(pick(hit)), fatal: false } : undefined;
+}
+function renderEvent(ev) {
+    switch (ev.kind) {
+        case "text":
+            return `💬 ${indent(ev.text.trim())}`;
+        case "tool":
+            return `🔧 ${ev.name}${ev.detail ? `: ${indent(ev.detail.trim())}` : ""}`;
+        case "usage":
+            return `📊 用量 input ${ev.inputTokens ?? "?"} / output ${ev.outputTokens ?? "?"} tokens`;
+        case "done":
+            return `🏁 ${ev.ok ? "完成" : "失敗"}${ev.summary ? `：${indent(ev.summary.trim())}` : ""}`;
+    }
+}
+/** 把一份 log 轉成人看得懂的版本；最後附上錯誤整理，讓失敗原因一眼可見 */
+export function renderLog(text, file = "") {
+    const { header, footer, body, stderr } = parseLog(text);
+    const out = [];
+    const errors = [];
+    const title = header
+        ? `${header.stage} / ${header.step} / ${header.agent}${header.adapter && header.adapter !== header.agent ? `（adapter ${header.adapter}）` : ""}`
+        : "（沒有檔頭）";
+    out.push(`${logSeq(file) ? `#${logSeq(file)}  ` : ""}${title}`);
+    out.push(`開始 ${localTime(header?.startedAt)}　` +
+        (footer ? `結束 ${localTime(footer.endedAt)}　結束碼 ${footer.code}　${footer.ok ? "✓ 成功" : "✗ 失敗"}` : "… 沒有結束紀錄（還在執行或被中斷）"));
+    if (file)
+        out.push(`檔案 ${file}`);
+    out.push("");
+    const adapter = header?.adapter ? ADAPTERS[header.adapter] : undefined;
+    if (!adapter || header?.agent === CMD_AGENT) {
+        out.push(...body);
+    }
+    else {
+        let skipped = 0;
+        for (const line of body) {
+            if (!line.trim())
+                continue;
+            const events = adapter.parse(line);
+            if (events.length) {
+                for (const ev of events) {
+                    const s = renderEvent(ev);
+                    if (s)
+                        out.push(s);
+                    if (ev.kind === "done" && !ev.ok)
+                        errors.push(`agent 回報失敗${ev.summary ? `：${indent(ev.summary.trim())}` : ""}`);
+                }
+                continue;
+            }
+            const json = tryJson(line);
+            if (!json) {
+                out.push(`📄 ${line}`);
+                continue;
+            }
+            const err = findError(json);
+            if (!err) {
+                skipped++;
+                continue;
+            }
+            out.push(`${err.fatal ? "❌" : "⚠️ "} ${indent(err.message)}`);
+            if (err.fatal)
+                errors.push(`錯誤事件：${indent(err.message)}`);
+        }
+        if (skipped)
+            out.push(`（另有 ${skipped} 行其他事件未顯示，可用 --raw 查看）`);
+    }
+    if (footer && footer.code !== 0)
+        errors.unshift(`結束碼 ${footer.code}`);
+    if (footer && !footer.ok && !errors.length)
+        errors.push("執行未通過（沒有更多錯誤訊息）");
+    const stderrText = stderr.length ? `stderr：\n   ${indent(clip(stderr.join("\n"), 4000))}` : undefined;
+    if (errors.length)
+        out.push("", "── 錯誤 ──", ...errors, ...(stderrText ? [stderrText] : []));
+    else if (stderrText)
+        out.push("", "── 其他輸出 ──", stderrText);
+    return out.join("\n");
+}
+//# sourceMappingURL=logs.js.map

package/dist/paths.js

@@ -14,9 +14,11 @@ export function projectRoot() {
     return root;
 }
 export const agentflowctlDir = () => join(projectRoot(), ".agentflowctl");
-export const runDir = (id) => join(agentflowctlDir(), "runs", id);
+export const runsDir = () => join(agentflowctlDir(), "runs");
+export const runDir = (id) => join(runsDir(), id);
 export const logDir = (id) => join(runDir(id), "logs");
 /** 每個 run 一個 git worktree，Agent 只在這裡工作，不碰你正在編輯的檔案 */
-export const worktreeDir = (id) => join(agentflowctlDir(), "worktrees", id);
+export const worktreesDir = () => join(agentflowctlDir(), "worktrees");
+export const worktreeDir = (id) => join(worktreesDir(), id);
 export const flowDir = (id) => join(worktreeDir(id), ".flow");
 //# sourceMappingURL=paths.js.map

package/dist/proc.js

@@ -1,12 +1,9 @@
 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,
+            env: { ...process.env, ...opts.env },
             shell: opts.shell ?? false,
         });
         let stdout = "";

package/dist/roles.js

@@ -2,78 +2,109 @@
  * 決定每個步驟由哪個 agent 執行。
  *
  * 規則只有三條：
- * 1. 審查者不能是最後寫程式的 agent。
+ * 1. 審查者不能是最後寫程式的 agent，多位審查者彼此不重複。
  * 2. 開啟 tddSplit 時，同一個任務的測試與實作由不同 agent 負責。
- * 3. 所有選擇都沿著同一個輪替順序（cycle）前進，所以不同公司的模型會輪流扮演各個角色。
+ * 3. 人選隨機決定，不依 cycle 的順序。cycle 只代表有哪些 agent 參與。
+ *
+ * 隨機以 seed（run id 加上步驟與輪次）決定：同一個 run 的同一步驟重算時會得到同樣的人，
+ * 所以 resume、或同一步驟在不同地方重算時結果一致。
  */
-/** 從 from 的下一位開始，找第一個不在 exclude 裡的 agent；全部被排除時退回下一位（單一 agent 也能運作） */
-export function nextAfter(cycle, from, exclude = []) {
-    const n = cycle.length;
-    const start = from === undefined ? -1 : cycle.indexOf(from);
-    for (let i = 1; i <= n; i++) {
-        const candidate = cycle[(start + i + n) % n];
-        if (!exclude.includes(candidate))
-            return candidate;
+/** FNV-1a 雜湊：把 seed 字串轉成 32 位元整數 */
+function hash(seed) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < seed.length; i++) {
+        h ^= seed.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
     }
-    return cycle[(start + 1 + n) % n];
+    return h >>> 0;
 }
-export const specAgent = (cycle) => cycle[0];
-export const planAgent = (cycle) => cycle[0];
-/** 第 i 個任務的測試由輪替順序的第 i 位負責，實作交給下一位 */
-export function taskAgents(cycle, taskIndex, tddSplit) {
-    const tests = cycle[taskIndex % cycle.length];
-    return { tests, code: tddSplit ? nextAfter(cycle, tests, [tests]) : tests };
+/** mulberry32：由 seed 決定的亂數產生器 */
+function rng(seed) {
+    let a = hash(seed);
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
 }
-/** 從最後寫程式的 agent 之後，依序挑出 quorum 位不重複、而且不是作者的 reviewer */
-export function reviewers(cycle, lastWriter, quorum) {
-    const picked = [];
-    let cursor = lastWriter;
-    for (let i = 0; i < cycle.length && picked.length < quorum; i++) {
-        const next = nextAfter(cycle, cursor, [...(lastWriter ? [lastWriter] : []), ...picked]);
-        if (picked.includes(next) || (next === lastWriter && cycle.length > 1))
-            break;
-        picked.push(next);
-        cursor = next;
+/** 由 seed 決定的洗牌，不改動原陣列 */
+export function shuffled(items, seed) {
+    const out = [...items];
+    const rand = rng(seed);
+    for (let i = out.length - 1; i > 0; i--) {
+        const j = Math.floor(rand() * (i + 1));
+        [out[i], out[j]] = [out[j], out[i]];
     }
-    return picked.length ? picked : [nextAfter(cycle, lastWriter)];
+    return out;
+}
+/** 隨機挑一位不在 exclude 裡的 agent；全部被排除時退回任一位（單一 agent 也能運作） */
+export function pick(cycle, seed, exclude = []) {
+    const order = shuffled(cycle, seed);
+    return order.find((c) => !exclude.includes(c)) ?? order[0];
+}
+/** 規格與計畫由同一位撰寫，計畫審查才能同時避開兩者的作者 */
+export const specAgent = (cycle, seed) => pick(cycle, `${seed}:author`);
+export const planAgent = specAgent;
+/**
+ * 每 cycle.length 個任務為一輪，每輪洗一次牌，所以每家輪完一次才會再輪到；
+ * 換輪時若新一輪第一位和上一輪最後一位相同，就把它往後移，避免同一家連續撰寫測試。
+ */
+function taskBag(cycle, seed, bag) {
+    const order = shuffled(cycle, `${seed}:tasks:${bag}`);
+    if (bag === 0 || order.length < 2)
+        return order;
+    const prevLast = taskBag(cycle, seed, bag - 1).at(-1);
+    return order[0] === prevLast ? [...order.slice(1), order[0]] : order;
+}
+/** 第 i 個任務的測試作者從洗好的牌依序取；實作者隨機挑一位測試作者以外的 agent */
+export function taskAgents(cycle, taskIndex, tddSplit, seed) {
+    const n = cycle.length;
+    const tests = taskBag(cycle, seed, Math.floor(taskIndex / n))[taskIndex % n];
+    return { tests, code: tddSplit ? pick(cycle, `${seed}:code:${taskIndex}`, [tests]) : tests };
+}
+/** 隨機挑出 quorum 位彼此不重複、而且不是作者的 reviewer */
+export function reviewers(cycle, lastWriter, quorum, seed) {
+    const picked = shuffled(cycle.filter((c) => c !== lastWriter), seed).slice(0, quorum);
+    return picked.length ? picked : [lastWriter ?? cycle[0]];
 }
 /**
  * 誰來修正：
  * - verify 失敗（型別、lint、建置這類機械性錯誤）：交給最後寫程式的 agent
- * - review 要求修改：ring 策略輪到 reviewer 的下一位；author 策略交回作者
+ * - review 要求修改：ring 策略隨機挑一位 reviewer 以外的 agent；author 策略交回作者
  */
 export function fixAgent(cycle, opts) {
     if (opts.source === "verify" || opts.strategy === "author")
         return opts.lastWriter ?? cycle[0];
-    return nextAfter(cycle, opts.lastReviewer, opts.lastReviewer ? [opts.lastReviewer] : []);
+    return pick(cycle, opts.seed, opts.lastReviewer ? [opts.lastReviewer] : []);
 }
-/** 計畫修正者：ring 策略輪到審查者的下一位；author 策略交回計畫作者 */
+/** 計畫修正者：ring 策略隨機挑一位審查者以外的 agent；author 策略交回計畫作者 */
 export function planFixAgent(cycle, opts) {
     if (opts.strategy === "author")
         return opts.planWriter ?? cycle[0];
-    return nextAfter(cycle, opts.planReviewer, opts.planReviewer ? [opts.planReviewer] : []);
+    return pick(cycle, opts.seed, opts.planReviewer ? [opts.planReviewer] : []);
 }
 /**
  * 仲裁小組：
- * - 有第三方（作者與最後審查者以外的 agent）→ 由第三方單獨仲裁
+ * - 有第三方（作者與最後審查者以外的 agent）→ 隨機挑一位第三方單獨仲裁
  * - 只有兩家 → 兩家各自在全新 context 中雙盲仲裁，避免讓一直反對的審查者同時當裁判
  * - 只有一家 → 只能由它自己仲裁
  */
-export function arbiterPanel(cycle, writer, reviewer) {
+export function arbiterPanel(cycle, seed, writer, reviewer) {
     const involved = [writer, reviewer].filter((x) => Boolean(x));
-    const third = cycle.find((c) => !involved.includes(c));
+    const third = shuffled(cycle, seed).find((c) => !involved.includes(c));
     if (third)
         return [third];
     return [...new Set(cycle)];
 }
 /**
- * 代打人選：原本的 agent 可用就用它；額度用完時，沿輪替順序找下一位還有額度的 agent。
+ * 代打人選：原本的 agent 可用就用它；額度用完時，隨機挑一位還有額度的 agent。
  * 全部都用完時回傳 undefined。
  */
-export function availableAgent(cycle, preferred, exhausted) {
+export function availableAgent(cycle, preferred, exhausted, seed) {
     if (!exhausted.includes(preferred))
         return preferred;
-    const next = nextAfter(cycle, preferred, exhausted);
-    return exhausted.includes(next) ? undefined : next;
+    return shuffled(cycle, seed).find((c) => !exhausted.includes(c));
 }
 //# sourceMappingURL=roles.js.map