agentflowctl 0.5.0 → 0.7.0

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/logs.js

@@ -2,6 +2,7 @@ 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";
+import { parseResultMeta } from "./resultMeta.js";
 /**
  * 每次執行 agent 或專案指令都寫成一份 log：
  * - 檔名：<三位數序號>-<階段>-<步驟>-<agent>.log，專案指令的 agent 欄位是 cmd
@@ -96,35 +97,57 @@ function findError(ev) {
     const hit = walk(ev, 0);
     return hit ? { message: clip(pick(hit)), fatal: false } : undefined;
 }
-function renderEvent(ev) {
+/** worktree 絕對路徑改成相對路徑：`<worktree>/x` → `x`，單獨的 `<worktree>` → `.` */
+const relativeToWorktree = (s) => s.replace(/[^\s'"=]*\/\.agentflowctl\/worktrees\/[^/\s'"]+(\/)?/g, (_m, slash) => (slash ? "" : "."));
+/** 去掉 codex 這類 CLI 包在指令外面的 `/bin/zsh -lc '...'` */
+function unwrapShell(cmd) {
+    const m = cmd.match(/^\/bin\/(?:ba|z)?sh\s+-l?c\s+(['"])([\s\S]*)\1$/);
+    if (!m)
+        return cmd;
+    const [, quote, inner] = m;
+    // 單引號包裝裡的 '"'"' 或 '\'' 是被跳脫的單引號，內容太複雜時保留原樣
+    if (quote === "'" && inner.includes("'"))
+        return cmd;
+    if (quote === '"' && /(^|[^\\])"/.test(inner))
+        return cmd;
+    return inner;
+}
+/** 精簡顯示的工具內容：只留第一行，並註明原本有幾行 */
+function compactDetail(detail) {
+    const lines = relativeToWorktree(unwrapShell(detail.trim())).split("\n");
+    const first = clip(lines[0], 200);
+    return lines.length > 1 ? `${first}　…（共 ${lines.length} 行）` : first;
+}
+function renderEvent(ev, full, lastText) {
     switch (ev.kind) {
         case "text":
             return `💬 ${indent(ev.text.trim())}`;
-        case "tool":
-            return `🔧 ${ev.name}${ev.detail ? `: ${indent(ev.detail.trim())}` : ""}`;
+        case "tool": {
+            const detail = ev.detail?.trim();
+            if (!detail)
+                return `🔧 ${ev.name}`;
+            return `🔧 ${ev.name}: ${full ? indent(detail) : compactDetail(detail)}`;
+        }
         case "usage":
             return `📊 用量 input ${ev.inputTokens ?? "?"} / output ${ev.outputTokens ?? "?"} tokens`;
-        case "done":
-            return `🏁 ${ev.ok ? "完成" : "失敗"}${ev.summary ? `：${indent(ev.summary.trim())}` : ""}`;
+        case "done": {
+            const summary = ev.summary?.trim();
+            // 最後一則回覆通常就是 summary，精簡模式不再重印一次
+            const show = summary && (full || summary !== lastText);
+            return `🏁 ${ev.ok ? "完成" : "失敗"}${show ? `：${indent(summary)}` : ""}`;
+        }
     }
 }
-/** 把一份 log 轉成人看得懂的版本；最後附上錯誤整理，讓失敗原因一眼可見 */
-export function renderLog(text, file = "") {
+function analyzeLog(text, full) {
     const { header, footer, body, stderr } = parseLog(text);
-    const out = [];
+    const lines = [];
     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("");
+    let lastText;
+    let doneSummary;
     const adapter = header?.adapter ? ADAPTERS[header.adapter] : undefined;
     if (!adapter || header?.agent === CMD_AGENT) {
-        out.push(...body);
+        lines.push(...body);
+        lastText = body.slice(-15).join("\n").trim() || undefined;
     }
     else {
         let skipped = 0;
@@ -134,9 +157,13 @@ export function renderLog(text, file = "") {
             const events = adapter.parse(line);
             if (events.length) {
                 for (const ev of events) {
-                    const s = renderEvent(ev);
+                    const s = renderEvent(ev, full, lastText);
                     if (s)
-                        out.push(s);
+                        lines.push(s);
+                    if (ev.kind === "text")
+                        lastText = ev.text.trim();
+                    if (ev.kind === "done")
+                        doneSummary = ev.summary?.trim() || undefined;
                     if (ev.kind === "done" && !ev.ok)
                         errors.push(`agent 回報失敗${ev.summary ? `：${indent(ev.summary.trim())}` : ""}`);
                 }
@@ -144,7 +171,7 @@ export function renderLog(text, file = "") {
             }
             const json = tryJson(line);
             if (!json) {
-                out.push(`📄 ${line}`);
+                lines.push(`📄 ${line}`);
                 continue;
             }
             const err = findError(json);
@@ -152,22 +179,51 @@ export function renderLog(text, file = "") {
                 skipped++;
                 continue;
             }
-            out.push(`${err.fatal ? "❌" : "⚠️ "} ${indent(err.message)}`);
+            lines.push(`${err.fatal ? "❌" : "⚠️ "} ${indent(err.message)}`);
             if (err.fatal)
                 errors.push(`錯誤事件：${indent(err.message)}`);
         }
         if (skipped)
-            out.push(`（另有 ${skipped} 行其他事件未顯示，可用 --raw 查看）`);
+            lines.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;
+    return { header, footer, lines, errors, stderrText, lastText, doneSummary };
+}
+const logTitle = (header) => header
+    ? `${header.stage} / ${header.step} / ${header.agent}${header.adapter && header.adapter !== header.agent ? `（adapter ${header.adapter}）` : ""}`
+    : "（沒有檔頭）";
+/** 把一份 log 轉成人看得懂的版本；最後附上錯誤整理，讓失敗原因一眼可見。預設精簡工具內容，opts.full 時完整顯示 */
+export function renderLog(text, file = "", opts = {}) {
+    const { header, footer, lines, errors, stderrText } = analyzeLog(text, opts.full ?? false);
+    const out = [];
+    out.push(`${logSeq(file) ? `#${logSeq(file)}  ` : ""}${logTitle(header)}`);
+    out.push(`開始 ${localTime(header?.startedAt)}　` +
+        (footer ? `結束 ${localTime(footer.endedAt)}　結束碼 ${footer.code}　${footer.ok ? "✓ 成功" : "✗ 失敗"}` : "… 沒有結束紀錄（還在執行或被中斷）"));
+    if (file)
+        out.push(`檔案 ${file}`);
+    out.push("", ...lines);
     if (errors.length)
         out.push("", "── 錯誤 ──", ...errors, ...(stderrText ? [stderrText] : []));
     else if (stderrText)
         out.push("", "── 其他輸出 ──", stderrText);
     return out.join("\n");
 }
+/** 一份 log 的結果摘要：給 run 停下時直接印在終端機，不用再另外查 log */
+export function summarizeLog(text) {
+    const a = analyzeLog(text, false);
+    const reply = a.doneSummary ?? a.lastText;
+    const meta = reply ? parseResultMeta(reply) ?? (a.lastText ? parseResultMeta(a.lastText) : undefined) : undefined;
+    const failed = a.footer ? !a.footer.ok : false;
+    return {
+        title: logTitle(a.header),
+        ok: a.footer?.ok,
+        meta,
+        text: meta ? undefined : reply && clip(reply, 600),
+        errors: failed ? [...a.errors, ...(a.stderrText ? [a.stderrText] : [])] : [],
+    };
+}
 //# sourceMappingURL=logs.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);

package/dist/resultMeta.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+/** Agent 回覆結尾的 <result> 中繼資料（格式定義在各 prompt 的 <reply_format>） */
+export const ResultMeta = z.object({
+    status: z.enum(["done", "blocked"]),
+    summary: z.string().default(""),
+    filesChanged: z.array(z.string()).default([]),
+    concerns: z.string().default(""),
+});
+const tagText = (xml, tag) => xml.match(new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`))?.[1]?.trim();
+/** 取回覆中最後一個 <result> 區塊；沒有或格式不合時回傳 undefined，不影響關卡判斷 */
+export function parseResultMeta(text) {
+    const block = [...text.matchAll(/<result>([\s\S]*?)<\/result>/g)].at(-1)?.[1];
+    if (block === undefined)
+        return undefined;
+    const files = tagText(block, "files_changed") ?? "";
+    const parsed = ResultMeta.safeParse({
+        status: tagText(block, "status"),
+        summary: tagText(block, "summary"),
+        filesChanged: [...files.matchAll(/<file>([\s\S]*?)<\/file>/g)].map((m) => m[1].trim()).filter(Boolean),
+        concerns: tagText(block, "concerns"),
+    });
+    return parsed.success ? parsed.data : undefined;
+}
+//# sourceMappingURL=resultMeta.js.map

package/dist/runner.js

@@ -1,12 +1,12 @@
 import { appendFileSync, mkdirSync } from "node:fs";
 import { dirname } from "node:path";
-import { z } from "zod";
 import { ADAPTERS } from "./agents/index.js";
 import { projectRoot, runDir } from "./paths.js";
 import { config } from "./config.js";
 import { CMD_AGENT, footerLine, headerLine, logSeq, STDERR_MARK } from "./logs.js";
 import { exec, execShell } from "./proc.js";
 import { tail } from "./util.js";
+import { parseResultMeta } from "./resultMeta.js";
 /**
  * 判斷 agent 失敗是否因為方案額度或速率限制。
  * 各家的錯誤訊息會隨版本變動，這裡用寬鬆的樣式比對，且只在執行失敗時才檢查，避免誤判正常輸出。
@@ -22,28 +22,7 @@ const QUOTA_PATTERNS = [
     /\b429\b/,
 ];
 export const isQuotaError = (text) => QUOTA_PATTERNS.some((p) => p.test(text));
-/** Agent 回覆結尾的 <result> 中繼資料（格式定義在各 prompt 的 <reply_format>） */
-export const ResultMeta = z.object({
-    status: z.enum(["done", "blocked"]),
-    summary: z.string().default(""),
-    filesChanged: z.array(z.string()).default([]),
-    concerns: z.string().default(""),
-});
-const tagText = (xml, tag) => xml.match(new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`))?.[1]?.trim();
-/** 取回覆中最後一個 <result> 區塊；沒有或格式不合時回傳 undefined，不影響關卡判斷 */
-export function parseResultMeta(text) {
-    const block = [...text.matchAll(/<result>([\s\S]*?)<\/result>/g)].at(-1)?.[1];
-    if (block === undefined)
-        return undefined;
-    const files = tagText(block, "files_changed") ?? "";
-    const parsed = ResultMeta.safeParse({
-        status: tagText(block, "status"),
-        summary: tagText(block, "summary"),
-        filesChanged: [...files.matchAll(/<file>([\s\S]*?)<\/file>/g)].map((m) => m[1].trim()).filter(Boolean),
-        concerns: tagText(block, "concerns"),
-    });
-    return parsed.success ? parsed.data : undefined;
-}
+export { parseResultMeta, ResultMeta } from "./resultMeta.js";
 function appendLog(file, text) {
     mkdirSync(dirname(file), { recursive: true });
     appendFileSync(file, text.endsWith("\n") ? text : `${text}\n`);

package/dist/schemas.js

@@ -14,6 +14,50 @@ export const Stage = z.enum([
     "done",
     "failed",
 ]);
+export const HandoffSource = z.object({
+    stage: Stage,
+    step: z.string().min(1),
+    agent: z.string().min(1),
+    callKey: z.string().min(1),
+});
+const HandoffKind = z.enum(["action", "info"]);
+const HandoffTarget = z.enum(["plan", "code"]);
+const HandoffStatus = z.enum(["open", "proposed_resolved", "resolved", "accepted"]);
+export const HandoffResponse = z.object({
+    newIssues: z.array(z.object({
+        kind: HandoffKind,
+        summary: z.string().trim().min(1),
+        evidence: z.string().trim().min(1),
+        targetStage: HandoffTarget,
+    })),
+    dispositions: z.array(z.object({
+        id: z.string().min(1),
+        status: z.enum(["proposed_resolved", "resolved", "accepted"]),
+        reason: z.string().trim().min(1),
+        evidence: z.string().trim().min(1),
+    })),
+});
+export const HandoffIssue = z.object({
+    id: z.string().min(1),
+    source: HandoffSource,
+    kind: HandoffKind,
+    summary: z.string().min(1),
+    evidence: z.string().min(1),
+    targetStage: HandoffTarget,
+    status: HandoffStatus,
+    resolution: z.object({
+        agent: z.string(),
+        reason: z.string(),
+        evidence: z.string(),
+    }).optional(),
+    updatedAt: z.string(),
+});
+export const HandoffLedger = z.object({
+    version: z.literal(1),
+    issues: z.array(HandoffIssue),
+    /** 用來辨識沒有新增事項的回覆是否已經合併。 */
+    appliedCalls: z.array(z.string()).optional(),
+});
 /** Agent 在 spec 階段產出的 .flow/acceptance.json */
 export const AcceptanceList = z
     .array(z.object({
@@ -39,6 +83,11 @@ export const ReviewResult = z.object({
         note: z.string().default(""),
     })),
 });
+/** 仲裁者可能用 reject 表示否決；讀取時正規化，保留相同的理由欄位。 */
+export const ArbiterResult = ReviewResult.extend({
+    verdict: z.enum(["approve", "changes_requested", "reject"])
+        .transform((verdict) => verdict === "reject" ? "changes_requested" : verdict),
+});
 /** 一個 agent 的定義；名稱（agents 的 key）用在 cycle 裡 */
 export const AgentDef = z.object({
     adapter: z.enum(["claude", "codex", "gemini", "command"]),

package/dist/stopReport.js

@@ -0,0 +1,79 @@
+import { join } from "node:path";
+import { summarizeLog } from "./logs.js";
+const pad = (s) => s.split("\n").join("\n     ");
+const clip = (s, max) => (s.length <= max ? s : `${s.slice(0, max)}…`);
+/** 一份 log 的結果：標題、<result> 的摘要與疑慮；失敗時附上錯誤整理 */
+function outcomeLines(entry, text) {
+    const s = summarizeLog(text);
+    const mark = s.ok === undefined ? "…" : s.ok ? "✓" : "✗";
+    const out = [`  #${entry.seq} ${s.title} ${mark}`];
+    if (s.meta) {
+        if (s.meta.status === "blocked")
+            out.push("     狀態：blocked");
+        if (s.meta.summary)
+            out.push(`     摘要：${pad(s.meta.summary)}`);
+        if (s.meta.concerns)
+            out.push(`     疑慮：${pad(s.meta.concerns)}`);
+    }
+    else if (s.text) {
+        out.push(`     ${pad(s.text)}`);
+    }
+    for (const e of s.errors)
+        out.push(`     ${pad(clip(e, 1500))}`);
+    return out;
+}
+/**
+ * run 停下來（Ctrl-C、失敗、暫停、等待核准）時要直接印在終端機的內容：
+ * 最近一步的結果、未結交接事項，以及接下來可以執行的指令。完成的 run 不印。
+ */
+export function stopReport(i) {
+    const { run, logs } = i;
+    if (run.stage === "done")
+        return [];
+    const out = [];
+    const last = logs.at(-1);
+    const running = last && !last.footer ? last : undefined;
+    const finished = logs.filter((e) => e.footer);
+    const lastFailed = finished.filter((e) => !e.footer.ok).at(-1);
+    // 失敗時優先看失敗的那一步，其餘情況看最後完成的一步
+    const shown = run.stage === "failed" && lastFailed ? lastFailed : finished.at(-1);
+    if (running || shown) {
+        out.push("", "── 結果 ──");
+        if (running) {
+            const title = summarizeLog(i.read(running.file)).title;
+            out.push(`  ${i.interrupted ? "中斷於" : "進行中"} #${running.seq} ${title}（沒有結束紀錄，resume 時會重跑這一步）`);
+        }
+        if (shown)
+            out.push(...outcomeLines(shown, i.read(shown.file)));
+    }
+    if (i.open.length) {
+        out.push("", "── 未結交接事項 ──");
+        for (const item of i.open)
+            out.push(`  [${item.targetStage}] ${item.id} ${item.summary}（${item.status}）`);
+    }
+    const cmd = (c, why) => `  ${c.padEnd(40)} ${why}`;
+    const actions = [];
+    if (run.stage === "failed") {
+        if (lastFailed)
+            actions.push(cmd(`agentflowctl logs ${run.id} ${lastFailed.seq}`, "看失敗步驟的完整 log"));
+        actions.push(cmd(`cd ${i.worktree}`, "需要時手動修正"));
+        actions.push(cmd(`agentflowctl resume ${run.id}`, `從 ${run.failedStage ?? "失敗的階段"} 重試`));
+        actions.push(cmd(`agentflowctl cancel ${run.id}`, "放棄這個 run"));
+    }
+    else if (run.stage === "paused") {
+        actions.push(cmd(`agentflowctl resume ${run.id}`, "額度恢復後接續"));
+    }
+    else if (run.stage === "awaiting_approval") {
+        actions.push(cmd(`less ${join(i.worktree, ".flow", "plan.md")}`, "檢視計畫"));
+        actions.push(cmd(`agentflowctl approve ${run.id}`, "核准並開始實作"));
+    }
+    else {
+        if (shown)
+            actions.push(cmd(`agentflowctl logs ${run.id} ${shown.seq}`, "看上一步的完整 log"));
+        actions.push(cmd(`agentflowctl resume ${run.id}`, `從 ${run.stage} 接續`));
+        actions.push(cmd(`agentflowctl cancel ${run.id}`, "放棄這個 run"));
+    }
+    out.push("", "── 下一步 ──", ...actions);
+    return out;
+}
+//# sourceMappingURL=stopReport.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentflowctl",
   "license": "MIT",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "跨廠商 AI 開發 harness：Claude Code、Codex、Gemini 輪流實作、審查、修正",
   "keywords": [
     "ai",

package/prompts/fix.md

@@ -6,6 +6,17 @@
 目前的工作目錄就是專案（agentflowctl 為這次任務建立的專用 git worktree）。
 </context>
 
+<handoff>
+先閱讀 .flow/handoff-context.md，處理與本階段有關的待辦事項。完成時寫入 .flow/handoff-response.json；即使沒有事項也必須寫出空陣列：
+
+```json
+{ "newIssues": [], "dispositions": [] }
+```
+
+新增事項格式：{ "kind": "action 或 info", "summary": "具體問題", "evidence": "檔案位置或檢查證據", "targetStage": "plan 或 code" }。
+處置格式：{ "id": "既有事項 ID", "status": "proposed_resolved、resolved 或 accepted", "reason": "具體處理理由", "evidence": "檔案、commit 或檢查結果" }。撰寫者只能用 proposed_resolved 提出修正；審查者可以用 resolved 或 accepted 結案。重要疑慮必須放在這份檔案，不能只寫在回覆的 <concerns>。
+</handoff>
+
 <inputs>
 - .flow/feedback.md：失敗的檢查（型別、lint、測試、建置）或審查意見
 - .flow/spec.md 與 .flow/acceptance.json：規格

package/prompts/implement-code.md

@@ -6,6 +6,17 @@
 目前的工作目錄就是專案（agentflowctl 為這次任務建立的專用 git worktree）。
 </context>
 
+<handoff>
+先閱讀 .flow/handoff-context.md，處理與本階段有關的待辦事項。完成時寫入 .flow/handoff-response.json；即使沒有事項也必須寫出空陣列：
+
+```json
+{ "newIssues": [], "dispositions": [] }
+```
+
+新增事項格式：{ "kind": "action 或 info", "summary": "具體問題", "evidence": "檔案位置或檢查證據", "targetStage": "plan 或 code" }。
+處置格式：{ "id": "既有事項 ID", "status": "proposed_resolved、resolved 或 accepted", "reason": "具體處理理由", "evidence": "檔案、commit 或檢查結果" }。撰寫者只能用 proposed_resolved 提出修正；審查者可以用 resolved 或 accepted 結案。重要疑慮必須放在這份檔案，不能只寫在回覆的 <concerns>。
+</handoff>
+
 <task>
 ```json
 {{task}}

package/prompts/implement-tests.md

@@ -6,6 +6,17 @@
 目前的工作目錄就是專案（agentflowctl 為這次任務建立的專用 git worktree）。
 </context>
 
+<handoff>
+先閱讀 .flow/handoff-context.md，處理與本階段有關的待辦事項。完成時寫入 .flow/handoff-response.json；即使沒有事項也必須寫出空陣列：
+
+```json
+{ "newIssues": [], "dispositions": [] }
+```
+
+新增事項格式：{ "kind": "action 或 info", "summary": "具體問題", "evidence": "檔案位置或檢查證據", "targetStage": "plan 或 code" }。
+處置格式：{ "id": "既有事項 ID", "status": "proposed_resolved、resolved 或 accepted", "reason": "具體處理理由", "evidence": "檔案、commit 或檢查結果" }。撰寫者只能用 proposed_resolved 提出修正；審查者可以用 resolved 或 accepted 結案。重要疑慮必須放在這份檔案，不能只寫在回覆的 <concerns>。
+</handoff>
+
 <task>
 ```json
 {{task}}

package/prompts/plan-arbiter.md

@@ -6,6 +6,17 @@
 目前的工作目錄就是專案（agentflowctl 為這次任務建立的專用 git worktree）。
 </context>
 
+<handoff>
+先閱讀 .flow/handoff-context.md，處理與本階段有關的待辦事項。完成時寫入 .flow/handoff-response.json；即使沒有事項也必須寫出空陣列：
+
+```json
+{ "newIssues": [], "dispositions": [] }
+```
+
+新增事項格式：{ "kind": "action 或 info", "summary": "具體問題", "evidence": "檔案位置或檢查證據", "targetStage": "plan 或 code" }。
+處置格式：{ "id": "既有事項 ID", "status": "proposed_resolved、resolved 或 accepted", "reason": "具體處理理由", "evidence": "檔案、commit 或檢查結果" }。撰寫者只能用 proposed_resolved 提出修正；審查者可以用 resolved 或 accepted 結案。重要疑慮必須放在這份檔案，不能只寫在回覆的 <concerns>。
+</handoff>
+
 <requirement>
 {{requirement}}
 </requirement>
@@ -36,10 +47,11 @@
 ```
 
 dispute.md 裡的每一條意見都要列一筆並說明你的判斷。
+`verdict` 只能寫 `approve` 或 `changes_requested`。若計畫有會導致錯誤結果、遺漏需求或無法驗收的問題，請寫 `changes_requested`，不要寫 `reject`。
 </output_format>
 
 <constraints>
-- 只能寫入 .flow/plan-arbiter.json，不可修改規格、計畫或任何程式碼。
+- 只能寫入 .flow/plan-arbiter.json 與 .flow/handoff-response.json，不可修改規格、計畫或任何程式碼。
 </constraints>
 
 <reply_format>

package/prompts/plan-fix.md

@@ -6,6 +6,17 @@
 目前的工作目錄就是專案（agentflowctl 為這次任務建立的專用 git worktree）。
 </context>
 
+<handoff>
+先閱讀 .flow/handoff-context.md，處理與本階段有關的待辦事項。完成時寫入 .flow/handoff-response.json；即使沒有事項也必須寫出空陣列：
+
+```json
+{ "newIssues": [], "dispositions": [] }
+```
+
+新增事項格式：{ "kind": "action 或 info", "summary": "具體問題", "evidence": "檔案位置或檢查證據", "targetStage": "plan 或 code" }。
+處置格式：{ "id": "既有事項 ID", "status": "proposed_resolved、resolved 或 accepted", "reason": "具體處理理由", "evidence": "檔案、commit 或檢查結果" }。撰寫者只能用 proposed_resolved 提出修正；審查者可以用 resolved 或 accepted 結案。重要疑慮必須放在這份檔案，不能只寫在回覆的 <concerns>。
+</handoff>
+
 <requirement>
 {{requirement}}
 </requirement>

package/prompts/plan-review.md

@@ -6,6 +6,17 @@
 目前的工作目錄就是專案（agentflowctl 為這次任務建立的專用 git worktree）。
 </context>
 
+<handoff>
+先閱讀 .flow/handoff-context.md，處理與本階段有關的待辦事項。完成時寫入 .flow/handoff-response.json；即使沒有事項也必須寫出空陣列：
+
+```json
+{ "newIssues": [], "dispositions": [] }
+```
+
+新增事項格式：{ "kind": "action 或 info", "summary": "具體問題", "evidence": "檔案位置或檢查證據", "targetStage": "plan 或 code" }。
+處置格式：{ "id": "既有事項 ID", "status": "proposed_resolved、resolved 或 accepted", "reason": "具體處理理由", "evidence": "檔案、commit 或檢查結果" }。撰寫者只能用 proposed_resolved 提出修正；審查者可以用 resolved 或 accepted 結案。重要疑慮必須放在這份檔案，不能只寫在回覆的 <concerns>。
+</handoff>
+
 <requirement>
 {{requirement}}
 </requirement>
@@ -46,7 +57,7 @@
 </output_format>
 
 <constraints>
-- 只能寫入 .flow/plan-review.json，不可修改規格、計畫或任何程式碼，其他變更都會被還原。
+- 只能寫入 .flow/plan-review.json 與 .flow/handoff-response.json，不可修改規格、計畫或任何程式碼，其他變更都會被還原。
 </constraints>
 
 <reply_format>

package/prompts/plan.md

@@ -6,6 +6,17 @@
 目前的工作目錄就是專案（agentflowctl 為這次任務建立的專用 git worktree）。
 </context>
 
+<handoff>
+先閱讀 .flow/handoff-context.md，處理與本階段有關的待辦事項。完成時寫入 .flow/handoff-response.json；即使沒有事項也必須寫出空陣列：
+
+```json
+{ "newIssues": [], "dispositions": [] }
+```
+
+新增事項格式：{ "kind": "action 或 info", "summary": "具體問題", "evidence": "檔案位置或檢查證據", "targetStage": "plan 或 code" }。
+處置格式：{ "id": "既有事項 ID", "status": "proposed_resolved、resolved 或 accepted", "reason": "具體處理理由", "evidence": "檔案、commit 或檢查結果" }。撰寫者只能用 proposed_resolved 提出修正；審查者可以用 resolved 或 accepted 結案。重要疑慮必須放在這份檔案，不能只寫在回覆的 <concerns>。
+</handoff>
+
 <inputs>
 - .flow/spec.md
 - .flow/acceptance.json