dowafu 0.1.0

package/dist/audit.js

@@ -0,0 +1,123 @@
+// plan_dispatch_v1.4.md §15：確定性稽核，全部以程式判定，不經模型。純函式，吃 spoke 的
+// finalText 與允許讀取清單，吐結構化稽核結果。「疑似」而非「fail」的界線見 §15 說明——
+// 禁止內容關鍵詞必有誤判，故只標記交 hub 判讀，不得自動刪改 spoke 原文。
+import { splitTopLevelSections } from "./ticket.js";
+export const FIXED_CLOSING_LINE = "以上為觀察與問題，採用與否由 hub 與使用者裁決。";
+// 英文工單走英文模板，收尾句與章節名也跟著換。稽核**兩套都認**且不看工單語言——spoke
+// 偶爾會用另一種語言作答，那是產出品質的事，不該讓稽核整份判 fail 而蓋掉真正的訊號。
+export const FIXED_CLOSING_LINE_EN = "These are observations and questions. Whether to adopt them is for the hub and the user to decide.";
+const OBSERVATIONS_SECTIONS = ["觀察", "Observations"];
+const CANNOT_VERIFY_SECTIONS = ["無法驗證", "Cannot verify"];
+function getSection(sections, names) {
+    for (const n of names) {
+        const body = sections.get(n);
+        if (body !== undefined)
+            return body;
+    }
+    return undefined;
+}
+const SUSPECT_PHRASES = ["應該改成", "建議採用", "嚴重度", "高風險", "應廢止"];
+// 抓看起來像相對路徑的引用：至少一層目錄＋副檔名，容許前後有反引號與 :行號。
+// plan_dispatch_v1.12.md §15：字元類須容許中括號，否則 Next.js 動態路由段（[id]、
+// [...slug]、[[...slug]]）會把路徑從中括號後截斷——截斷後的字串當然不在允許清單內，
+// 於是每一條合法引用都被誤判為清單外（首次外部派工實測：三個 spoke 全部誤報）。
+// 比對方式維持精確集合比對不變，只改路徑抽取的容許字元。
+const PATH_REGEX = /`?([\w.\-[\]]+(?:\/[\w.\-[\]]+)+\.[A-Za-z0-9]{1,10})(?::\d+)?`?/g;
+// plan_dispatch_v1.9.md §15：稽核的職責是記錄，不是規範 spoke 的表達結構。原本只認
+// 範本的平鋪編號（"1. "），deepseek 用「## 問題 N」＋「**觀察 N.N**」的巢狀結構時被判成
+// 0 條——而那次是三份回報中最豐富的一份。放寬為多種常見形式皆計入，依序嘗試、採第一個
+// 有命中的樣式；一種都沒命中時記 null（「數不出來」），不得降級為 0（「沒有」）。
+const OBSERVATION_PATTERNS = [
+    /^\d+\.\s/, // 頂層有序清單："1. "（範本原定格式）
+    /^\*\*\d+\.\s/, // 粗體包住編號："**1. 內容**"（plan_fixes_v1.0.md §1：兩輪各中一次，數不出來時誤判「無法計數」）
+    /^(?:\*\*)?觀察\s*\d+(?:\.\d+)?(?:\*\*)?[:：]/, // 巢狀觀察標記："**觀察 1.1**：" 或 "觀察 1："
+    /^#{2,4}\s*觀察\s*\d+/, // 標題形式："### 觀察 1"
+    /^(?:\*\*)?Observation\s*\d+(?:\.\d+)?(?:\*\*)?[:：]/i, // 英文模板的巢狀標記
+    /^#{2,4}\s*Observation\s*\d+/i, // 英文模板的標題形式
+];
+function countObservations(observationsBody) {
+    if (observationsBody.trim().length === 0)
+        return 0; // 章節存在但確實空白＝明確的零，不是數不出來
+    const lines = observationsBody.split(/\r?\n/).map((l) => l.trim());
+    for (const pattern of OBSERVATION_PATTERNS) {
+        const count = lines.filter((l) => pattern.test(l)).length;
+        if (count > 0)
+            return count;
+    }
+    return null; // 章節有內容，但沒有一種已知樣式命中——無法辨識，不是沒有
+}
+// 找出 targetPath 第一次出現的頂層章節（依文件順序）。用同一個 PATH_REGEX 逐章節重新
+// 抽取比對，而非對章節內文字做 includes 子字串比對，避免相近路徑互相誤判。
+function findSection(sections, targetPath) {
+    for (const [heading, body] of sections) {
+        const pathsInSection = new Set([...body.matchAll(PATH_REGEX)].map((m) => m[1]));
+        if (pathsInSection.has(targetPath))
+            return heading;
+    }
+    return null;
+}
+// 若 citedPath 是某個允許清單項目的路徑後綴（以 "/" 為界，非任意子字串），回傳該項目
+// 原始字串——供讀者判斷是否為縮寫，而非臆測。
+function findSuffixSource(citedPath, allowedRelativePaths) {
+    return allowedRelativePaths.find((allowed) => allowed.length > citedPath.length &&
+        allowed.endsWith(citedPath) &&
+        allowed[allowed.length - citedPath.length - 1] === "/");
+}
+export function auditSpoke(finalText, allowedRelativePaths) {
+    if (!finalText) {
+        return {
+            finalLinePass: false,
+            observationCount: null, // 完全沒有內容可數，不是「數出來是零」
+            citedPaths: [],
+            citedPathsOutsideAllowlist: [],
+            citedPathsOutsideAllowlistDetail: [],
+            cannotVerifySectionPresent: false,
+            suspectPhrases: [],
+        };
+    }
+    const lines = finalText.split(/\r?\n/).map((l) => l.trim());
+    const lastNonEmpty = [...lines].reverse().find((l) => l.length > 0) ?? "";
+    const finalLinePass = lastNonEmpty === FIXED_CLOSING_LINE || lastNonEmpty === FIXED_CLOSING_LINE_EN;
+    const sections = splitTopLevelSections(finalText);
+    const observationsSection = getSection(sections, OBSERVATIONS_SECTIONS);
+    const observationCount = observationsSection !== undefined ? countObservations(observationsSection) : null;
+    const cannotVerifySectionPresent = CANNOT_VERIFY_SECTIONS.some((n) => sections.has(n));
+    const citedPaths = [...new Set([...finalText.matchAll(PATH_REGEX)].map((m) => m[1]))];
+    const allowedSet = new Set(allowedRelativePaths);
+    // 熱修補（issue_log_v1.1.md）：「無法驗證」章節內的路徑必然在允許清單之外——§16 回報
+    // 模板定義該欄為「需要但讀不到的檔案」，出現清單外路徑是模板要求的正確行為，不是 §15
+    // 要防的「臆測或引用工單原文」。故清單外判定排除只出現在該章節的路徑；citedPaths 本身
+    // 維持完整記錄不變，記錄（§12）與判定（§15）是不同職責。
+    //
+    // 「只出現在」是關鍵字——同一路徑若跨「觀察」與「無法驗證」兩節出現，觀察節那筆仍須被
+    // 抓到（那正是 §15 要防的訊號：先在觀察節臆測引用，再於無法驗證節「自首」寫不在清單內，
+    // 藉此讓臆測那筆連帶被放行）。故須先算出「無法驗證節以外」引用了哪些路徑，只有兩者皆
+    // 不成立（在無法驗證節出現、且未在別處出現）才排除。
+    //
+    // 取捨：spoke 若在「無法驗證」欄裡編造一個不存在、且未在別處引用的路徑，此處抓不到。
+    // 可接受——該欄本來就是列「讀不到的檔案」，單獨出現在那裡不構成 §15 要防的訊號。
+    const cannotVerifySectionText = getSection(sections, CANNOT_VERIFY_SECTIONS) ?? "";
+    const pathsCitedInCannotVerifySection = new Set([...cannotVerifySectionText.matchAll(PATH_REGEX)].map((m) => m[1]));
+    const elsewhereText = [...sections.entries()]
+        .filter(([heading]) => !CANNOT_VERIFY_SECTIONS.includes(heading))
+        .map(([, body]) => body)
+        .join("\n");
+    const pathsCitedElsewhere = new Set([...elsewhereText.matchAll(PATH_REGEX)].map((m) => m[1]));
+    const pathsOnlyInCannotVerify = new Set([...pathsCitedInCannotVerifySection].filter((p) => !pathsCitedElsewhere.has(p)));
+    const citedPathsOutsideAllowlist = citedPaths.filter((p) => !allowedSet.has(p) && !pathsOnlyInCannotVerify.has(p));
+    const suspectPhrases = SUSPECT_PHRASES.filter((phrase) => finalText.includes(phrase));
+    const citedPathsOutsideAllowlistDetail = citedPathsOutsideAllowlist.map((p) => ({
+        path: p,
+        section: findSection(sections, p),
+        suffixOf: findSuffixSource(p, allowedRelativePaths),
+    }));
+    return {
+        finalLinePass,
+        observationCount,
+        citedPaths,
+        citedPathsOutsideAllowlist,
+        citedPathsOutsideAllowlistDetail,
+        cannotVerifySectionPresent,
+        suspectPhrases,
+    };
+}

package/dist/cli-args.js

@@ -0,0 +1,138 @@
+// plan_dispatch_v1.4.md §9：CLI 引數解析與說明文字，抽成純函式（不含任何 I/O）以便單元
+// 測試——`src/cli.ts` 是真正的進入點（bottom 有 `main().catch()` 的副作用呼叫），import
+// 它來測 parseArgs 會直接跑掉整支程式；拆到這裡後 cli.ts 只是薄殼。
+//
+// plan_dispatch_v1.10.md §9：新增 --repo-root／--providers／--json／--help／--version，
+// 並收緊兩處：多餘 positional 即中止（原靜默忽略，違反 fail closed）；無參數／--help 印
+// 完整用法（原僅一行）。
+import { DispatchError } from "./types.js";
+import { getCommandName } from "./pkg-info.js";
+export const HELP_TEXT = `用法：${getCommandName()} <ticket-dir> [options]
+
+  --repo-root <dir>        白名單邊界與 .claude/agents 的根，預設 cwd
+  --providers <path>       整檔取代出貨的 providers.json
+  --json                   stdout 只印結果 JSON，其餘輸出改走 stderr
+  --out <dir>              落檔目錄，預設 tmp/spoke/
+  --concurrency <n>        同時執行的 spoke 數，預設 2
+  --max-tokens <n>         呼叫前估算閘門（各 spoke 初始 prompt 總和），預設 200000
+  --max-spoke-tokens <n>   單一 spoke 執行期累積上限（實際 usage），預設 400000
+  --timeout <sec>          單次 API 呼叫逾時（不是整支 spoke），預設 600
+  --retries <n>            單輪呼叫的重試次數（僅暫時性錯誤），預設 2
+  --chars-per-token <n>    閘門一估算係數，預設 1.0（可由 providers.json 逐家覆寫）
+  --max-spoke-reasoning-tokens <n>  單一 spoke 的推理 token 累積上限，預設 50000
+  --max-round-reasoning-tokens <n>  單輪推理 token 上限，預設 null（不檢查）
+  --rate-limit-retries <n> 429 專用重試次數，預設 5（不計入 --retries）
+  --max-rate-wait <sec>    單次 429 等待上限，預設 30
+  --max-tool-calls <n>     單一 spoke 的 read_file 呼叫上限，預設 30
+  --dry-run                解析、驗證、估算、印報表，不呼叫 API
+  --yes                    略過派工確認。非互動環境（stdin 不是 TTY）沒帶就中止
+  --help, -h               印本說明後結束（exit 0）
+  --version, -V            印版本號後結束（exit 0）`;
+const DEFAULTS = {
+    out: "tmp/spoke",
+    concurrency: 2,
+    maxTokens: 200_000,
+    maxSpokeTokens: 400_000,
+    // plan_fixes_v1.0.md §2b：實測單次 API 呼叫曾達 559s（token 只多 18%、輪數相同，
+    // 耗時卻是 2.7 倍，判定為對方伺服器負載、不可歸因），300 太容易誤砍未卡住的呼叫。
+    timeoutSec: 600,
+    // §14：重試是輪級不是 spoke 級（sendWithResilience 收的是當前 conversation），成本
+    // 增量遠小於 v1.6 誤述的「1+N 次全額計費」；多輪長執行窗口中的網路波動是真實風險，
+    // 故預設由 0 改 2（v1.7 裁示）。
+    retries: 2,
+    rateLimitRetries: 5,
+    maxRateWaitSec: 30,
+    maxToolCalls: 30,
+    charsPerToken: 1.0,
+    maxSpokeReasoningTokens: 50_000,
+    maxRoundReasoningTokens: null,
+    json: false,
+    dryRun: false,
+    yes: false,
+};
+export function parseArgs(argv) {
+    // --help／--version 可出現在任何位置，且優先於其他一切解析——不要求先有 ticketDir。
+    if (argv.includes("--help") || argv.includes("-h"))
+        return { mode: "help" };
+    if (argv.includes("--version") || argv.includes("-V"))
+        return { mode: "version" };
+    const options = { ...DEFAULTS };
+    let ticketDir;
+    const numFlag = (name, apply) => {
+        flagHandlers[name] = (v) => {
+            const n = Number(v);
+            if (!Number.isFinite(n))
+                throw new DispatchError(`--${name} 需要數字，收到：${v}`, 2);
+            apply(n);
+        };
+    };
+    const flagHandlers = {};
+    flagHandlers["out"] = (v) => (options.out = v);
+    flagHandlers["repo-root"] = (v) => (options.repoRoot = v);
+    flagHandlers["providers"] = (v) => (options.providersPath = v);
+    numFlag("concurrency", (n) => (options.concurrency = n));
+    numFlag("max-tokens", (n) => (options.maxTokens = n));
+    numFlag("max-spoke-tokens", (n) => (options.maxSpokeTokens = n));
+    numFlag("timeout", (n) => (options.timeoutSec = n));
+    numFlag("retries", (n) => (options.retries = n));
+    numFlag("rate-limit-retries", (n) => (options.rateLimitRetries = n));
+    numFlag("max-rate-wait", (n) => (options.maxRateWaitSec = n));
+    numFlag("max-tool-calls", (n) => (options.maxToolCalls = n));
+    numFlag("chars-per-token", (n) => (options.charsPerToken = n));
+    numFlag("max-spoke-reasoning-tokens", (n) => (options.maxSpokeReasoningTokens = n));
+    numFlag("max-round-reasoning-tokens", (n) => (options.maxRoundReasoningTokens = n));
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--dry-run") {
+            options.dryRun = true;
+        }
+        else if (arg === "--yes") {
+            options.yes = true;
+        }
+        else if (arg === "--json") {
+            options.json = true;
+        }
+        else if (arg.startsWith("--")) {
+            const name = arg.slice(2);
+            const handler = flagHandlers[name];
+            if (!handler)
+                throw new DispatchError(`未知選項：${arg}\n\n${HELP_TEXT}`, 2);
+            const value = argv[++i];
+            if (value === undefined)
+                throw new DispatchError(`--${name} 缺少值`, 2);
+            handler(value);
+        }
+        else if (ticketDir === undefined) {
+            ticketDir = arg;
+        }
+        else {
+            // v1.10 §9：多餘的 positional 原本被靜默忽略（`hub-dispatch a b` 只跑 a），
+            // 與設計原則 2（fail closed）不一致，改為中止。
+            throw new DispatchError(`多餘的引數：${arg}（工單目錄已是 "${ticketDir}"）\n\n${HELP_TEXT}`, 2);
+        }
+    }
+    if (!ticketDir) {
+        throw new DispatchError(HELP_TEXT, 2);
+    }
+    return { mode: "run", ticketDir, options };
+}
+export function formatEvent(event) {
+    switch (event.type) {
+        case "spoke_start":
+            return `[${event.agent}] 開始 → ${event.provider}/${event.model}`;
+        case "round":
+            return `[${event.agent}] round ${event.round} usage=${JSON.stringify(event.usage)} toolCalls=${event.hasToolCalls}`;
+        case "unknown_usage_keys":
+            return `[${event.agent}] ⚠ round ${event.round} 出現未知 usage 欄位：${event.keys.join(", ")}`;
+        case "tool_call":
+            return `[${event.agent}] read_file(${event.path}) ${event.allowed ? "允許" : `拒絕(${event.reason})`}`;
+        case "rate_limit_wait":
+            return `[${event.agent}] 429，等待 ${event.seconds}s（來源：${event.source}）`;
+        case "round_error":
+            return `[${event.agent}] ⚠ round ${event.round} 錯誤 status=${event.status ?? "—"}：${event.message}`;
+        case "spoke_end":
+            return (`[${event.agent}] 結束 status=${event.status} latency=${event.latencyMs}ms totalTokens=${event.totalTokens}` +
+                ` cost=${event.costUsd === null ? "無價目資料" : `$${event.costUsd.toFixed(4)}`}` +
+                (event.budgetTrigger ? ` budgetTrigger=${event.budgetTrigger}` : ""));
+    }
+}

package/dist/cli.js

@@ -0,0 +1,304 @@
+#!/usr/bin/env node
+// plan_dispatch_v1.4.md §9/§10：CLI 入口，串起 §10 執行流程 1–10。
+// plan_dispatch_v1.10.md §10：新增步驟 0（設定解析）與步驟 6.5（gitignore 三態檢查），
+// 皆在任何 API 呼叫之前。引數解析、說明文字、事件格式化拆到 cli-args.ts（純函式，
+// 供單元測試）；此檔只負責串接與 I/O。
+import path from "node:path";
+import { createInterface } from "node:readline/promises";
+import { DispatchError } from "./types.js";
+import { loadTicket } from "./ticket.js";
+import { loadProviders, PROVIDERS_FORMAT_VERSION } from "./providers.js";
+import { resolveSpokes } from "./validate.js";
+import { estimateTokens, estimateAllowlistTokens, estimateSequentialRead, checkGateOne } from "./gate.js";
+import { buildFirstUserText, buildSystemPrompt } from "./prompt.js";
+import { buildReport, effectiveCap, effectiveCharsPerToken } from "./report.js";
+import { runSpoke } from "./runner.js";
+import { Semaphore } from "./semaphore.js";
+import { createResponsesAdapter } from "./adapters/responses.js";
+import { createGeminiAdapter } from "./adapters/gemini-native.js";
+import { createAnthropicAdapter } from "./adapters/anthropic-messages.js";
+import { auditSpoke } from "./audit.js";
+import { auditToolCalls } from "./tool-call-audit.js";
+import { ensureOutDir, persistSpokeResult, RunLogWriter, writeSummary } from "./output.js";
+import { registerSecrets, maskString, maskDeep } from "./mask.js";
+import { SECRET_ENV_VARS } from "./secret-env.js";
+import { resolveDispatchHome, loadDispatchEnv } from "./dispatch-home.js";
+import { bundledProvidersPath, getPackageVersion } from "./pkg-info.js";
+import { checkGitignore } from "./gitignore-check.js";
+import { buildJsonPayload, buildJsonPlan } from "./json-output.js";
+import { parseArgs, formatEvent, HELP_TEXT } from "./cli-args.js";
+function createAdapterFor(spoke) {
+    const apiKey = process.env[`${spoke.provider.toUpperCase()}_API_KEY`];
+    if (!apiKey) {
+        // resolveSpokes 已檢查過，此處為型別窄化防禦
+        throw new DispatchError(`內部錯誤：${spoke.provider} 的 API key 遺失`, 2);
+    }
+    // §29 規格十：窮盡式分派，不留「其餘落到 gemini」的 fallback——那會讓未來第四家 provider
+    // 靜默走錯 adapter。switch 缺 case 時 TypeScript 因「不是每條路徑都回傳值」編譯失敗。
+    switch (spoke.providerConfig.api) {
+        case "responses":
+            return createResponsesAdapter({
+                baseURL: spoke.providerConfig.baseURL,
+                apiKey,
+                store: spoke.providerConfig.store,
+                reasoning: spoke.providerConfig.reasoning,
+            });
+        case "gemini-native":
+            return createGeminiAdapter({ apiKey, baseURL: spoke.providerConfig.baseURL });
+        case "anthropic-messages":
+            return createAnthropicAdapter({
+                baseURL: spoke.providerConfig.baseURL,
+                apiKey,
+                reasoning: spoke.providerConfig.reasoning,
+            });
+    }
+}
+function makeLogger(json) {
+    return { info: (msg) => (json ? console.error(msg) : console.log(msg)) };
+}
+async function confirm(message, output) {
+    // 非互動環境（agent 經 shell 呼叫時 stdin 不是 TTY）沒有人能回答這個提示。
+    // fail closed：先前這裡 return true，等於唯一的付費閘門是操作文件裡的一句話；
+    // 要在這種環境派工必須明確帶 --yes。
+    if (!process.stdin.isTTY)
+        return false;
+    const rl = createInterface({ input: process.stdin, output });
+    const answer = await rl.question(message);
+    rl.close();
+    return answer.trim().toLowerCase() === "y";
+}
+async function main() {
+    const parsed = parseArgs(process.argv.slice(2));
+    if (parsed.mode === "help") {
+        console.log(HELP_TEXT);
+        return;
+    }
+    if (parsed.mode === "version") {
+        console.log(getPackageVersion());
+        return;
+    }
+    const { ticketDir, options } = parsed;
+    const log = makeLogger(options.json);
+    // §10 步驟 0：設定解析——DISPATCH_HOME → .env → providers 來源 → formatVersion。
+    // 全部在任何 API 呼叫之前，成本為零。§24.4：明文禁止讀 cwd 的 .env，故不用
+    // `import "dotenv/config"`（那會讀 cwd），改為明確指定 dispatchHome 下的路徑。
+    const dispatchHome = resolveDispatchHome();
+    loadDispatchEnv(dispatchHome);
+    registerSecrets(SECRET_ENV_VARS.map((k) => process.env[k]));
+    // v1.10 §9：--repo-root 只影響白名單邊界、.claude/agents 位置、_docs/ 拒絕判定；
+    // 工單目錄仍相對 cwd 解析，不要求位於 repoRoot 內（見 resolveSpokes 呼叫處）。
+    const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
+    const ticketId = path.basename(path.resolve(ticketDir));
+    // §10 步驟 1–2：工單解析＋允許清單存在性（loadTicket／resolveSpokes 內部 fail closed）
+    const ticket = await loadTicket(ticketDir);
+    // §10 步驟 3／v1.10 §24.3：providers.json 隨工具出貨、不可覆寫（方案 D）；
+    // --providers 是唯一逃生口，整檔取代，一樣過 formatVersion 檢查。
+    const providersPath = options.providersPath ? path.resolve(options.providersPath) : bundledProvidersPath();
+    const providersSource = options.providersPath
+        ? { kind: "explicit", path: providersPath, formatVersion: PROVIDERS_FORMAT_VERSION }
+        : { kind: "bundled", formatVersion: PROVIDERS_FORMAT_VERSION };
+    const providers = await loadProviders(providersPath);
+    // §10 步驟 4–5：effort 值域、API key 齊備、models 白名單（resolveSpokes 內部）
+    const spokes = await resolveSpokes(ticket, providers, repoRoot);
+    // §10 步驟 6／§14 閘門一：呼叫前估算
+    const estimates = spokes.map((spoke) => {
+        const systemPrompt = buildSystemPrompt(spoke.agentBody, spoke.lang);
+        const firstUserText = buildFirstUserText(path.resolve(ticketDir), spoke.agent, spoke.allowedReadsRelative, repoRoot, spoke.lang);
+        const charsPerToken = effectiveCharsPerToken(spoke, options);
+        return {
+            agent: spoke.agent,
+            estimatedTokens: estimateTokens(systemPrompt, charsPerToken) + estimateTokens(firstUserText, charsPerToken),
+        };
+    });
+    checkGateOne(estimates, options.maxTokens);
+    // plan_dispatch_v2.0.md §14：允許清單總量估算，獨立於閘門一之外，只呈現不設閘門
+    // （閘門一不含允許清單內容，見 gate.ts 的說明）。與 estimates 同一模式：算一次，
+    // 報表與 --json plan 共用，不重複讀檔。
+    const allowlistEstimates = spokes.map((spoke) => ({
+        agent: spoke.agent,
+        estimatedTokens: estimateAllowlistTokens(spoke.allowedReadsResolved, effectiveCharsPerToken(spoke, options)),
+        fileCount: spoke.allowedReadsResolved.length,
+        sequential: estimateSequentialRead(spoke.allowedReadsResolved, effectiveCharsPerToken(spoke, options)),
+    }));
+    const outDir = path.join(options.out, ticketId);
+    // §10 步驟 6.5／v1.11 §10：輸出目錄的 gitignore 三態檢查，警告不擋執行。判定基準
+    // 必須與 outDir 的解析基準一致——outDir 相對 cwd（v1.11 §24.5），故不傳 repoRoot，
+    // 用 checkGitignore 的預設值（process.cwd()）。
+    const gitignoreStatus = checkGitignore(outDir);
+    // v1.11 §25：plan 在此刻（步驟 6 之後）已完全確定，與是否實際執行無關——dry-run／
+    // cancelled／executed 三種 mode 的 --json 輸出皆含同一份 plan。
+    const plan = buildJsonPlan(spokes, estimates, allowlistEstimates, options);
+    const buildPayload = (mode, results, audits, toolCallAudits, exitCode) => buildJsonPayload({
+        ticketId,
+        repoRoot,
+        outDir,
+        providersSource,
+        mode,
+        plan,
+        gitignoreStatus,
+        results,
+        audits,
+        toolCallAudits,
+        exitCode,
+    });
+    // §10 步驟 7／§11：派工報表
+    const report = buildReport(ticketId, spokes, estimates, allowlistEstimates, options, outDir, {
+        repoRoot,
+        providersSource,
+        gitignoreStatus,
+    });
+    log.info(report);
+    if (options.dryRun) {
+        log.info("\n--dry-run：僅解析／驗證／估算／印報表，未呼叫任何 API。");
+        if (options.json) {
+            console.log(JSON.stringify(maskDeep(buildPayload("dry-run", [], new Map(), new Map(), 0))));
+        }
+        return;
+    }
+    if (!options.yes) {
+        const ok = await confirm("繼續？[y/N] ", options.json ? process.stderr : process.stdout);
+        if (!ok) {
+            log.info(process.stdin.isTTY
+                ? "已取消，未呼叫任何 API。"
+                : "非互動環境（stdin 不是 TTY）無人可確認，已取消，未呼叫任何 API。要在此環境派工請明確加上 --yes。");
+            if (options.json) {
+                console.log(JSON.stringify(maskDeep(buildPayload("cancelled", [], new Map(), new Map(), 0))));
+            }
+            return;
+        }
+    }
+    let outDirReady = true;
+    try {
+        await ensureOutDir(outDir);
+    }
+    catch (err) {
+        outDirReady = false;
+        console.error(`落檔目錄不可寫：${outDir}`);
+        console.error(maskString(String(err)));
+    }
+    const runLog = outDirReady ? new RunLogWriter(path.join(outDir, "run.jsonl")) : null;
+    const semaphore = new Semaphore(options.concurrency);
+    const onEvent = (event) => {
+        log.info(formatEvent(event));
+        runLog?.append(event);
+    };
+    // §10 步驟 8：信號量控制發起，Promise.allSettled 只負責收尾
+    const settled = await Promise.allSettled(spokes.map(async (spoke) => {
+        await semaphore.acquire();
+        try {
+            const adapter = createAdapterFor(spoke);
+            const result = await runSpoke(spoke, adapter, ticketDir, {
+                repoRoot,
+                timeoutMs: options.timeoutSec * 1000,
+                retries: options.retries,
+                rateLimitRetries: options.rateLimitRetries,
+                maxRateWaitSec: options.maxRateWaitSec,
+                maxToolCalls: options.maxToolCalls,
+                maxSpokeTokens: effectiveCap(spoke, options),
+                maxSpokeReasoningTokens: options.maxSpokeReasoningTokens,
+                maxRoundReasoningTokens: options.maxRoundReasoningTokens,
+                charsPerToken: effectiveCharsPerToken(spoke, options),
+                semaphore,
+                onEvent,
+            });
+            // §13（一）：每支 spoke 完成即落檔，不等 Promise.allSettled——多 spoke 並行、
+            // 其中一支慢很多時，快的那支已付費的產出不因慢的還在跑而暴露在中斷風險下。
+            if (outDirReady) {
+                await persistSpokeResult(outDir, result, (msg) => console.error(msg));
+            }
+            return result;
+        }
+        finally {
+            semaphore.release();
+        }
+    }));
+    const results = settled.map((s, i) => {
+        if (s.status === "fulfilled")
+            return s.value;
+        // §13：spoke 本身的錯誤已在 runSpoke 內部收斂為 status:"failed"；這裡是防禦，
+        // 理論上不該發生（runSpoke 不對外拋錯）。
+        const spoke = spokes[i];
+        return {
+            agent: spoke.agent,
+            provider: spoke.provider,
+            api: spoke.providerConfig.api,
+            modelRequested: spoke.model,
+            modelReturned: null,
+            effort: spoke.effort,
+            store: "unknown",
+            status: "failed",
+            finalText: null,
+            usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0, available: false },
+            costUsd: null,
+            finishReason: null,
+            finishReasonRaw: null,
+            toolCalls: [],
+            rateLimitHits: [],
+            unknownUsageKeys: [],
+            attempts: 0,
+            errors: [maskString(String(s.reason))],
+            requestId: null,
+            startedAt: Date.now(),
+            finishedAt: Date.now(),
+            latencyMs: 0,
+            waitedMs: 0,
+            estimatedPromptTokens: 0,
+            rawRequests: [],
+            rawResponses: [],
+            rawErrors: [],
+        };
+    });
+    // §10 步驟 9：確定性稽核
+    const audits = new Map(results.map((r) => {
+        const spoke = spokes.find((sp) => sp.agent === r.agent);
+        return [r.agent, auditSpoke(r.finalText, spoke.allowedReadsRelative)];
+    }));
+    // plan_dispatch_v2.0.md §15（一）：tool 呼叫是執行資料不是文字，獨立於 auditSpoke 之外判定。
+    const toolCallAudits = new Map(results.map((r) => {
+        const spoke = spokes.find((sp) => sp.agent === r.agent);
+        return [r.agent, auditToolCalls(r.agent, r.toolCalls, spoke.allowedReadsRelative.length)];
+    }));
+    // §10 步驟 10：落檔 + stdout 摘要。這裡的迴圈定位已改變（v2.4 §13 規格二）：
+    // per-spoke 落檔已在 spokes.map 內完成，此處是「落檔失敗的重試」，不再是
+    // rejected 分支的兜底——真實 result 重寫一次是冪等的（writeFile 覆蓋）。
+    if (outDirReady) {
+        for (const r of results) {
+            await persistSpokeResult(outDir, r, (msg) => console.error(msg));
+        }
+        await writeSummary(outDir, ticketId, results, audits, toolCallAudits);
+        await runLog?.flush();
+        log.info(`\n落檔完成：${outDir}/`);
+    }
+    else {
+        // 落檔目錄不可寫時，不讓已付費的結果消失——完整結果改印到 stderr（json 模式下
+        // stdout 仍須維持只有最後那個單一 JSON 物件的契約，不能把這份診斷用資料混進去）。
+        log.info("\n落檔目錄不可寫，完整報告已改印於 stderr：");
+        console.error(JSON.stringify(maskDeep(results), null, 2));
+    }
+    const allFailed = results.every((r) => r.status === "failed");
+    const exitCode = allFailed ? 4 : 0;
+    if (allFailed) {
+        process.exitCode = exitCode;
+    }
+    if (options.json) {
+        console.log(JSON.stringify(maskDeep(buildPayload("executed", results, audits, toolCallAudits, exitCode))));
+    }
+    else {
+        log.info("\n" + buildStdoutSummary(results));
+    }
+}
+function buildStdoutSummary(results) {
+    return results
+        .map((r) => `${r.agent}: ${r.status}  model=${r.modelReturned ?? "—"}  token=${r.usage.totalTokens}  ` +
+        `cost=${r.costUsd === null ? "無價目資料" : `$${r.costUsd.toFixed(4)}`}  耗時=${r.latencyMs}ms`)
+        .join("\n");
+}
+main().catch((err) => {
+    if (err instanceof DispatchError) {
+        console.error(maskString(err.message));
+        process.exitCode = err.exitCode;
+        return;
+    }
+    console.error(maskString(String(err)));
+    process.exitCode = 1;
+});

package/dist/cost.js

@@ -0,0 +1,54 @@
+// plan_fixes_v1.0.md §4：成本用單價換算，不只給 token 數——實測 token 只差 18%，
+// 依官方單價實算卻差 23.2 倍（單價本身差 10.7×〜26.8×）。只看 token 數會嚴重誤判
+// 成本量級（issue_log_v2.3.md：外部 hub 依 token 判「gemini 貴 2.5 倍」，是這個誤判
+// 的實例）。純函式，不做 I/O，供單元測試。
+//
+// 兩個必須處理的細節（§4）：
+//
+// 1. gemini 的 thoughtsTokenCount（正規化後的 reasoningTokens）不是 candidatesTokenCount
+//    （outputTokens）的子集——官方帳目關係是 promptTokenCount + candidatesTokenCount +
+//    thoughtsTokenCount = totalTokenCount（usage.ts 已驗證），且官方文件明文「Output
+//    price (including thinking tokens)」，故兩者都要計費，outputTokens 之外要另加
+//    reasoningTokens。openai／deepseek／anthropic 的 reasoning／thinking token 是
+//    output 的子集，已經含在 outputTokens 裡，不可再加，否則重複計費。
+//
+// 2. anthropic 的 inputTokens 有快取時「不含」快取部分——cachedTokens（cache_read）與
+//    cacheWriteTokens（cache_creation）是另外兩個獨立欄位，總量是四者之和（usage.ts
+//    已驗證）。openai／deepseek／gemini 相反：cachedTokens／cacheWriteTokens 是
+//    inputTokens 的子集（官方對「快取命中」的計費方式是「原生 input 價的一部分改用
+//    快取價」），要從 inputTokens 扣掉才是「非快取價」該計費的量，否則會把快取部分
+//    重複計成原價。
+// exhaustive 對照表，缺一支會被 TypeScript 擋下——與 usage.ts 的 usageProviderKeyFor
+// 同樣理由：不留「其餘」預設分支，逼新增第四家 provider 時必須手動同步。
+const REASONING_INCLUDED_IN_OUTPUT = {
+    responses: true, // openai／deepseek：reasoning_tokens ⊆ output_tokens
+    "gemini-native": false, // thoughtsTokenCount 與 candidatesTokenCount 是並列，非子集
+    "anthropic-messages": true, // thinking_tokens ⊆ output_tokens
+};
+const CACHED_IS_SUBSET_OF_INPUT = {
+    responses: true,
+    "gemini-native": true,
+    "anthropic-messages": false, // input_tokens 已排除快取部分，四者並列相加
+};
+// pricing 缺席（該模型無價目資料）或 usage 不可用時回傳 null，不是 0——「無法估算」與
+// 「估出來是零」必須可區分，否則報表會把「沒資料」誤讀成「免費」。
+export function estimateCostUsd(usage, api, pricing) {
+    if (!pricing)
+        return null;
+    if (!usage.available)
+        return null;
+    const cachedTokens = usage.cachedTokens ?? 0;
+    const cacheWriteTokens = usage.cacheWriteTokens ?? 0;
+    const reasoningTokens = usage.reasoningTokens ?? 0;
+    const cachedIsSubset = CACHED_IS_SUBSET_OF_INPUT[api];
+    const regularInputTokens = cachedIsSubset
+        ? Math.max(0, usage.inputTokens - cachedTokens - cacheWriteTokens)
+        : usage.inputTokens;
+    const billableOutputTokens = REASONING_INCLUDED_IN_OUTPUT[api] ? usage.outputTokens : usage.outputTokens + reasoningTokens;
+    const cachedPricePerM = pricing.cachedInputPerM ?? pricing.inputPerM;
+    const cacheWritePricePerM = pricing.cacheWritePerM ?? pricing.inputPerM;
+    return ((regularInputTokens / 1_000_000) * pricing.inputPerM +
+        (cachedTokens / 1_000_000) * cachedPricePerM +
+        (cacheWriteTokens / 1_000_000) * cacheWritePricePerM +
+        (billableOutputTokens / 1_000_000) * pricing.outputPerM);
+}

package/dist/dispatch-home.js

@@ -0,0 +1,23 @@
+// plan_dispatch_v1.10.md §24.4：API key 的載入順序與位置。ambient process.env 優先
+// （CI、一次性覆寫），其次 $DISPATCH_HOME/.env；dotenv 預設不覆寫既有變數，故 ambient
+// 優先自然成立，不需額外邏輯。
+//
+// 明文禁令：dispatch 不得讀取 cwd 的 `.env`——cwd 是被審專案，`import "dotenv/config"`
+// 會把該專案的整份 `.env`（資料庫密碼、第三方 token、webhook secret）載入一個正對三家
+// 外部 API 發請求的行程，而 §12 的遮蔽名單認不出那些秘密。此檔取代原本
+// `src/cli.ts` 頂部的 `import "dotenv/config"`。
+import dotenv from "dotenv";
+import os from "node:os";
+import path from "node:path";
+export function resolveDispatchHome(env = process.env, homedir = os.homedir) {
+    if (env.DISPATCH_HOME)
+        return env.DISPATCH_HOME;
+    if (env.XDG_CONFIG_HOME)
+        return path.join(env.XDG_CONFIG_HOME, "dispatch");
+    return path.join(homedir(), ".config", "dispatch");
+}
+// 唯一允許呼叫 dotenv 的地方——`path` 一律明確指定為 dispatchHome 下的 `.env`，
+// 絕不留白（留白即回退成 dotenv 預設讀 cwd 的 `.env`，正是本函式存在的目的所要杜絕的）。
+export function loadDispatchEnv(dispatchHome) {
+    dotenv.config({ path: path.join(dispatchHome, ".env") });
+}