dowafu 0.1.0

package/dist/providers.js

@@ -0,0 +1,151 @@
+// plan_dispatch_v1.4.md §5：providers.json 載入與驗證。fail closed——api 欄缺失或
+// store:true 即中止（exit 2），不套用預設值繼續跑（§10 步驟 3）。
+import { readFile } from "node:fs/promises";
+import { DispatchError } from "./types.js";
+function parseReasoning(raw, providerName) {
+    if (!raw || typeof raw !== "object") {
+        return { style: null, allowed: [] };
+    }
+    const r = raw;
+    const style = r.style;
+    if (style !== undefined && style !== "openai" && style !== "deepseek" && style !== "gemini" && style !== "anthropic") {
+        throw new DispatchError(`providers.json: ${providerName}.reasoning.style 值不合法："${String(style)}"`, 2);
+    }
+    const allowed = Array.isArray(r.allowed) ? r.allowed.filter((v) => typeof v === "string") : [];
+    const modelOverrides = r.modelOverrides && typeof r.modelOverrides === "object"
+        ? r.modelOverrides
+        : undefined;
+    // §5：default 是「工單 effort 留白時實際送出的值」——不得回退到「不送參數」。
+    // allowed 非空時必填，且須在 allowed 內；allowed 為空時 default 不存在（該 provider
+    // 尚未驗證、不可用，連 default 都無從指定）。
+    let def;
+    if (r.default !== undefined) {
+        if (typeof r.default !== "string") {
+            throw new DispatchError(`providers.json: ${providerName}.reasoning.default 須為字串`, 2);
+        }
+        def = r.default;
+    }
+    if (allowed.length > 0 && def === undefined) {
+        throw new DispatchError(`providers.json: ${providerName}.reasoning.default 缺失——allowed 非空時必填，不得回退到「不送參數」`, 2);
+    }
+    if (def !== undefined && !allowed.includes(def)) {
+        throw new DispatchError(`providers.json: ${providerName}.reasoning.default "${def}" 不在 allowed 內（${allowed.length > 0 ? allowed.join(", ") : "（空）"}）`, 2);
+    }
+    return { style: style ?? null, allowed, default: def, modelOverrides };
+}
+// plan_fixes_v1.0.md §4：pricing 為選填——缺席的 provider／模型無法估算成本（cost.ts
+// 回傳 null，不是 0），不強制每個 provider 都要有價目。有填就驗完整，格式錯即中止
+// （fail closed，與本檔其餘欄位一致），不悄悄忽略壞掉的價目導致成本估算安靜地錯。
+function parsePositiveNumber(v, label) {
+    if (typeof v !== "number" || !(v > 0)) {
+        throw new DispatchError(`providers.json: ${label} 須為正數，實際為 ${JSON.stringify(v)}`, 2);
+    }
+    return v;
+}
+function parsePricing(raw, providerName) {
+    if (raw === undefined)
+        return undefined;
+    if (!raw || typeof raw !== "object") {
+        throw new DispatchError(`providers.json: ${providerName}.pricing 不是物件`, 2);
+    }
+    const out = {};
+    for (const [model, entry] of Object.entries(raw)) {
+        if (!entry || typeof entry !== "object") {
+            throw new DispatchError(`providers.json: ${providerName}.pricing.${model} 不是物件`, 2);
+        }
+        const e = entry;
+        out[model] = {
+            inputPerM: parsePositiveNumber(e.inputPerM, `${providerName}.pricing.${model}.inputPerM`),
+            outputPerM: parsePositiveNumber(e.outputPerM, `${providerName}.pricing.${model}.outputPerM`),
+            ...(e.cachedInputPerM !== undefined
+                ? { cachedInputPerM: parsePositiveNumber(e.cachedInputPerM, `${providerName}.pricing.${model}.cachedInputPerM`) }
+                : {}),
+            ...(e.cacheWritePerM !== undefined
+                ? { cacheWritePerM: parsePositiveNumber(e.cacheWritePerM, `${providerName}.pricing.${model}.cacheWritePerM`) }
+                : {}),
+        };
+    }
+    return out;
+}
+function parseProviderConfig(name, raw) {
+    if (!raw || typeof raw !== "object") {
+        throw new DispatchError(`providers.json: provider "${name}" 的設定不是物件`, 2);
+    }
+    const r = raw;
+    // §5：api 欄無預設值，介面選擇不容猜測——缺失即中止。
+    if (r.api !== "responses" && r.api !== "gemini-native" && r.api !== "anthropic-messages") {
+        throw new DispatchError(`providers.json: ${name}.api 缺失或不合法（須為 "responses"、"gemini-native" 或 "anthropic-messages"），實際為 ${JSON.stringify(r.api)}`, 2);
+    }
+    // §5：store 不可為 true——違反設計原則 6（零留存）即中止。
+    if (r.store === true) {
+        throw new DispatchError(`providers.json: ${name}.store 為 true，違反設計原則 6（零留存）。載入即中止，不得依賴伺服器端狀態。`, 2);
+    }
+    const store = r.store === null ? null : false; // 未填視為 false
+    if (typeof r.baseURL !== "string" || r.baseURL.length === 0) {
+        throw new DispatchError(`providers.json: ${name}.baseURL 缺失`, 2);
+    }
+    // §5：models 白名單。未填（或非陣列）視為空陣列 = 不做型號檢查。
+    const models = Array.isArray(r.models) ? r.models.filter((v) => typeof v === "string") : [];
+    // §5：charsPerToken。未填時用 CLI 全域值——保留 null，不在此處套 1.0（CLI 端才知道
+    // 使用者傳入的 --chars-per-token 是多少）。
+    if (r.charsPerToken !== undefined && (typeof r.charsPerToken !== "number" || !(r.charsPerToken > 0))) {
+        throw new DispatchError(`providers.json: ${name}.charsPerToken 須為正數`, 2);
+    }
+    const charsPerToken = typeof r.charsPerToken === "number" ? r.charsPerToken : null;
+    return {
+        baseURL: r.baseURL,
+        api: r.api,
+        store,
+        toolCalling: r.toolCalling === true,
+        reasoning: parseReasoning(r.reasoning, name),
+        models,
+        charsPerToken,
+        tpmLimit: typeof r.tpmLimit === "number" ? r.tpmLimit : null,
+        maxSpokeTokens: typeof r.maxSpokeTokens === "number" ? r.maxSpokeTokens : null,
+        pricing: parsePricing(r.pricing, name),
+    };
+}
+// plan_dispatch_v1.10.md §24.3：providers.json 隨工具出貨，不可覆寫（方案 D）。
+// formatVersion 沿用 `_dispatch.md` 首行 `<!-- format: v1 -->` 的既有做法——版本檢查
+// 在載入時做，不符即中止，防跨版本漂移（一份舊版 providers.json 寫著已證實不生效的
+// 參數路徑，可能回顯、不報錯，行為完全不受控，facts_dispatch.md 2026-08-06 已有實例）。
+export const PROVIDERS_FORMAT_VERSION = 1;
+export function parseProvidersFile(json) {
+    if (!json || typeof json !== "object") {
+        throw new DispatchError("providers.json 格式不是物件", 2);
+    }
+    const { formatVersion, ...providerEntries } = json;
+    if (formatVersion !== PROVIDERS_FORMAT_VERSION) {
+        throw new DispatchError(`providers.json: formatVersion 不符（預期 ${PROVIDERS_FORMAT_VERSION}，實際 ${JSON.stringify(formatVersion)}）。` +
+            `這通常代表 --providers 指向了舊版或不相容的檔案。`, 2);
+    }
+    const out = {};
+    for (const [name, raw] of Object.entries(providerEntries)) {
+        out[name] = parseProviderConfig(name, raw);
+    }
+    return out;
+}
+export async function loadProviders(filePath) {
+    let text;
+    try {
+        text = await readFile(filePath, "utf8");
+    }
+    catch {
+        throw new DispatchError(`找不到 providers.json：${filePath}`, 2);
+    }
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch (err) {
+        throw new DispatchError(`providers.json 不是合法 JSON：${err.message}`, 2);
+    }
+    return parseProvidersFile(json);
+}
+export function getProviderConfig(providers, name) {
+    const config = providers[name];
+    if (!config) {
+        throw new DispatchError(`providers.json 未定義 provider "${name}"`, 2);
+    }
+    return config;
+}

package/dist/rate-limit.js

@@ -0,0 +1,27 @@
+// plan_dispatch_v1.4.md §13：429 等待秒數的三段 fallback。任一階段解析失敗即落入下一段，
+// 不猜測。純函式，供單元測試（本節三段 fallback 完全未經實測，見 facts_dispatch.md）。
+const BACKOFF_SECONDS = [2, 4, 8, 16, 32];
+export function parseRetryAfter(headerValue, messageText, attemptIndex, // 第幾次撞牆（0-based），決定退避秒數
+now = Date.now()) {
+    if (headerValue) {
+        const trimmed = headerValue.trim();
+        if (/^\d+(\.\d+)?$/.test(trimmed)) {
+            return { seconds: Number(trimmed), source: "header" };
+        }
+        const parsed = Date.parse(trimmed);
+        if (!Number.isNaN(parsed)) {
+            const diffSeconds = (parsed - now) / 1000;
+            if (diffSeconds > 0) {
+                return { seconds: diffSeconds, source: "header" };
+            }
+        }
+    }
+    if (messageText) {
+        const match = messageText.match(/(\d+(?:\.\d+)?)\s*s(?:ec(?:onds?)?)?\b/i);
+        if (match) {
+            return { seconds: Number(match[1]), source: "message" };
+        }
+    }
+    const index = Math.max(0, Math.min(attemptIndex, BACKOFF_SECONDS.length - 1));
+    return { seconds: BACKOFF_SECONDS[index], source: "backoff" };
+}

package/dist/raw-integrity.js

@@ -0,0 +1,49 @@
+// plan_dispatch_v1.5.md §8「Adapter 的自我檢查：raw 完整性」。
+//
+// 送出請求前，adapter 必須驗證 conversation 中每個 assistant turn 的 raw 都完整出現在
+// 該請求裡；不符即拋錯，標為實作缺陷（非 API 錯誤）。理由：實測（facts Test C）證實
+// 「漏帶整個 item」不會被 API 偵測——模型照樣完成，只是靜默失去推理連續性，唯一線索是
+// reasoning_tokens 異常偏低，不會進 errors[]。竄改會 400，漏帶不會；而漏帶恰好是過濾條件
+// 寫錯一行就會發生的那種錯誤。偵測責任因此不能放在 API 回饋上，必須是 adapter 自己主動驗證。
+//
+// 兩種 raw 形狀，對應兩個 adapter：
+// - responses（openai/deepseek）：assistant turn 的 raw 是「陣列」（該輪 response.output
+//   整包），續接時逐一展開塞進 input 陣列——檢查「陣列中每個 item 是否都在 input 裡」。
+// - gemini-native：assistant turn 的 raw 是「單一物件」（{role:"model", parts:[...]}），
+//   續接時整個物件原樣放回 contents 陣列——檢查「這個物件是否整個出現在 contents 裡」。
+//
+// 判準是參照相等（===），不是結構相等：兩個 adapter 目前都是直接把 turn.raw 原樣塞入
+// 請求，不做任何轉換，故參照相等是正確且唯一有意義的比對方式——它驗證的是「真的是同一個
+// 物件被傳過去」，而非「長得像的東西存在」，後者會掩蓋掉真正的 bug（例如重新建構出一個
+// 內容相似但簽章欄位被序列化過程改寫的複製品）。若未來 adapter 需要對 raw 做任何正規化，
+// 這個判準本身就需要重新設計——那是規格問題，不是這裡的實作可以自行決定的。
+export class RawIntegrityError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RawIntegrityError";
+    }
+}
+export function checkRawArrayIntegrity(conv, builtInput) {
+    for (const turn of conv.turns) {
+        if (turn.role !== "assistant")
+            continue;
+        if (!Array.isArray(turn.raw)) {
+            throw new RawIntegrityError("raw 完整性檢查失敗：assistant turn 的 raw 不是陣列（responses adapter 預期 raw 為上一輪 response.output 陣列）");
+        }
+        for (const item of turn.raw) {
+            if (!builtInput.includes(item)) {
+                const type = item?.type ?? "?";
+                throw new RawIntegrityError(`raw 完整性檢查失敗：assistant turn 有一個 item（type=${type}）未以原樣出現在送出的請求中，疑似續接時被過濾掉`);
+            }
+        }
+    }
+}
+export function checkRawObjectIntegrity(conv, builtContents) {
+    for (const turn of conv.turns) {
+        if (turn.role !== "assistant")
+            continue;
+        if (!builtContents.includes(turn.raw)) {
+            throw new RawIntegrityError("raw 完整性檢查失敗：assistant turn 的 raw 未以原樣出現在送出的 contents 中，疑似續接時被重建或漏帶");
+        }
+    }
+}

package/dist/report.js

@@ -0,0 +1,101 @@
+// plan_dispatch_v1.4.md §11：派工報表（呼叫前）。模型錯了、effort 不如預期、介面走錯、
+// 成本量級不對，在送出前就看得到。不使用 ✓／✗ 標記——TPM 是滑動窗，429 等待會動態改變
+// 實際並行數，靜態估算無法精確預測。
+export function effectiveCap(spoke, cli) {
+    return spoke.providerConfig.maxSpokeTokens ?? cli.maxSpokeTokens;
+}
+export function effectiveCharsPerToken(spoke, cli) {
+    return spoke.providerConfig.charsPerToken ?? cli.charsPerToken;
+}
+function formatProvidersSource(src) {
+    if (src.kind === "bundled")
+        return `出貨（formatVersion ${src.formatVersion}）`;
+    return `外部檔 ${src.path}（formatVersion ${src.formatVersion}）`;
+}
+// v1.10 §10：三態不得合併——「未忽略」是需要處理的狀態，「無法判定」不是，措辭須區分。
+//
+// hub 驗收（2026-08-06）：措辭原寫「未被目標專案的 .gitignore 涵蓋」，但 v1.11 §24.5
+// 已訂輸出目錄屬呼叫端 cwd，checkGitignore 檢查的也是 cwd 所屬的 repo——cwd 與
+// --repo-root 指的目標專案是兩回事（v1.11 §10 修的正是這個基準不一致）。「目標專案」
+// 這個詞在 cwd ≠ repoRoot 時會指錯對象，故改為不預設兩者相同的措辭。
+function formatGitignoreWarning(status, outDir) {
+    if (status === "ignored")
+        return null;
+    if (status === "not_ignored") {
+        return `  ⚠ 輸出目錄 ${outDir} 未被輸出目錄所在的 git repo 忽略`;
+    }
+    return `  ℹ 無法判定輸出目錄 ${outDir} 是否被 .gitignore 涵蓋（非 git repo 或 git 不可用）`;
+}
+export function buildReport(ticketId, spokes, estimates, allowlistEstimates, cli, outDir, meta) {
+    const estByAgent = new Map(estimates.map((e) => [e.agent, e.estimatedTokens]));
+    const lines = [`即將派工 ${ticketId}：`];
+    // v1.10 §11：repoRoot 明列於報表，與 store 同性質的可見性保證——白名單是整套隔離的
+    // 唯一支點（§7），其邊界由「從哪個目錄下指令」決定，這件事在報表上必須看得見，否則
+    // 使用者無從發現自己在錯的目錄下跑。
+    lines.push(`  repoRoot   ${meta.repoRoot}`);
+    lines.push(`  providers  ${formatProvidersSource(meta.providersSource)}`);
+    for (const spoke of spokes) {
+        const est = estByAgent.get(spoke.agent) ?? 0;
+        const cap = effectiveCap(spoke, cli);
+        lines.push(`  ${spoke.agent.padEnd(20)} → ${spoke.provider.padEnd(8)} / ${spoke.model.padEnd(20)} ` +
+            `[${spoke.providerConfig.api}] effort=${spoke.effort ?? "—"} lang=${spoke.lang} ` +
+            `store=${spoke.providerConfig.store === false ? "false" : "n/a"} ` +
+            `est. ${est.toLocaleString()}  cap ${cap.toLocaleString()}`);
+    }
+    const totalEst = estimates.reduce((s, e) => s + e.estimatedTokens, 0);
+    const worstTotal = spokes.reduce((s, spoke) => s + effectiveCap(spoke, cli), 0);
+    // plan_fixes_v1.0.md §3：舊標籤「合計初始估算」被外部 hub 誤讀成整輪派工的成本估算——
+    // 這個數字只涵蓋 system prompt ＋ buildFirstUserText() 產出的第一則訊息，不含工單與
+    // 允許清單本身（那些是 spoke 自己用 tool call 讀進去的）。實測差距 27 倍（2,593 vs
+    // 71,482）。標籤明講範圍，並緊接印出允許清單總量，讓兩個數字一起出現、不必自己去找。
+    lines.push(`  初始 prompt 估算 ${totalEst.toLocaleString()} tokens（僅 system prompt＋首則訊息，不含工單與允許清單；本閘門的估算上限 ${cli.maxTokens.toLocaleString()}）`);
+    // §14：獨立於閘門一之外，只呈現不設閘門——閘門一不含允許清單與工單內容（issue_log_v2.0.md
+    // 2026-08-07），此數字才是「若整個允許清單都被讀完」的量級參考，門檻待樣本累積後再定。
+    const totalAllowlistTokens = allowlistEstimates.reduce((s, e) => s + e.estimatedTokens, 0);
+    const totalAllowlistFiles = allowlistEstimates.reduce((s, e) => s + e.fileCount, 0);
+    lines.push(`  允許清單總量估算 ${totalAllowlistTokens.toLocaleString()} tokens（${totalAllowlistFiles} 檔）`);
+    // plan_dispatch_v2.4.md §14：口徑說明——避免此數字被誤讀為預期消耗。三件事：
+    // (1) 字元數的上限估計，不是預期消耗；(2) 不去重，同一檔出現在多支清單會重複計入
+    // （正確行為：兩支各讀一次就是兩份成本）；(3) 實測程式碼素材約 3.5 字元／token，
+    // 故實際消耗通常遠低於此數（charsPerToken 假設 1.0，係數本身刻意不動，見 §14）。
+    lines.push(`    └ 上限估計，不去重；實測程式碼素材約 3.5 字元／token，實際消耗通常遠低於此數`);
+    // issue_log_v2.1.md（第 8、9 次）：多數模型一輪只叫一個檔，每輪重送全部歷史，故清單靠前
+    // 的檔會被重複計費多次。這一行是「順序造成的放大量」，也是唯一 hub 改得動的成本槓桿——
+    // 只印排序能省的部分，不印預估總量：總量還受「批次讀 vs 逐個讀」影響（模型決定，我們
+    // 控制不了），印出來會被當成預期值。省下的百分比則不受 charsPerToken 偏差影響（分子分母
+    // 抵銷），是這裡唯一可信的絕對數字。
+    const seqAsListed = allowlistEstimates.reduce((s, e) => s + e.sequential.asListed, 0);
+    const seqSorted = allowlistEstimates.reduce((s, e) => s + e.sequential.sorted, 0);
+    if (seqAsListed > 0) {
+        const savedPct = Math.round(((seqAsListed - seqSorted) / seqAsListed) * 100);
+        lines.push(`  逐個讀的順序放大量 ${seqAsListed.toLocaleString()} tokens（清單內容被重送的總量）`);
+        if (savedPct >= 5) {
+            lines.push(`    └ ⚠ 大檔排清單最後可降至 ${seqSorted.toLocaleString()}（本項省 ${savedPct}%）`);
+        }
+        else {
+            lines.push(`    └ 目前順序已接近最佳（重排最多再省 ${savedPct}%）`);
+        }
+        lines.push(`      本項不含初始 prompt 與工單（不受排序影響），故總成本的節省比例低於此數`);
+    }
+    lines.push(`  最壞總消耗 ≈ ${worstTotal.toLocaleString()} tokens（各 spoke 之 cap 加總）`);
+    lines.push(`  並行度 ${cli.concurrency}`);
+    const byProvider = new Map();
+    for (const spoke of spokes) {
+        const est = estByAgent.get(spoke.agent) ?? 0;
+        const entry = byProvider.get(spoke.provider) ?? { tpmLimit: spoke.providerConfig.tpmLimit, peak: 0 };
+        entry.peak += est;
+        byProvider.set(spoke.provider, entry);
+    }
+    for (const [provider, { tpmLimit, peak }] of byProvider) {
+        if (tpmLimit === null)
+            continue;
+        lines.push(`  ${provider} tpmLimit ${tpmLimit.toLocaleString()}，靜態估算峰值 ${peak.toLocaleString()}`);
+        lines.push(`    └ 僅為靜態指標，不預測執行中的 TPM 曲線（429 等待會改變實際並行數）`);
+    }
+    const allowedCount = spokes.reduce((s, spoke) => s + spoke.allowedReadsResolved.length, 0);
+    lines.push(`  允許讀取 ${allowedCount} 個檔案，輸出至 ${outDir}/`);
+    const gitignoreWarning = formatGitignoreWarning(meta.gitignoreStatus, outDir);
+    if (gitignoreWarning)
+        lines.push(gitignoreWarning);
+    return lines.join("\n");
+}

package/dist/runner.js

@@ -0,0 +1,328 @@
+// plan_dispatch_v1.4.md §13/§14：單一 spoke 的 tool-use 迴圈、runtime 閘門二（累積 token
+// 上限）、429 等待、逾時、重試、收束呼叫。狀態機見 §13。
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { buildFinalizeUserText, buildFirstUserText, buildSystemPrompt } from "./prompt.js";
+import { ALLOWLIST_REJECT_MESSAGE, checkAllowlist } from "./whitelist.js";
+import { findUnknownUsageKeys, sumUsage, usageProviderKeyFor } from "./usage.js";
+import { estimateCostUsd } from "./cost.js";
+import { describeError, ProviderHttpError } from "./mask.js";
+import { parseRetryAfter } from "./rate-limit.js";
+import { RawIntegrityError } from "./raw-integrity.js";
+import { classifyError } from "./error-classify.js";
+const MAX_FILE_BYTES = 200 * 1024; // §13：單檔 200KB 上限，防「單輪讀入巨檔」異常
+const MAX_ROUNDS = 60; // 安全上限，遠高於實務上的 --max-tool-calls，純防無窮迴圈 bug
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function executeToolCall(call, spoke, repoRoot) {
+    const requestedPath = typeof call.args.path === "string" ? call.args.path : "";
+    const startedAt = Date.now();
+    const check = checkAllowlist(spoke.allowSet, requestedPath, repoRoot);
+    if (!check.allowed) {
+        return {
+            resultText: ALLOWLIST_REJECT_MESSAGE,
+            log: { path: requestedPath, allowed: false, reason: check.reason, startedAt, durationMs: Date.now() - startedAt },
+        };
+    }
+    try {
+        const buf = await readFile(check.realPath);
+        let content = buf.toString("utf8");
+        if (buf.byteLength > MAX_FILE_BYTES) {
+            content = buf.subarray(0, MAX_FILE_BYTES).toString("utf8") + "\n...(檔案超過 200KB 上限，內容已截斷)";
+        }
+        return {
+            resultText: content,
+            log: { path: requestedPath, allowed: true, startedAt, durationMs: Date.now() - startedAt },
+        };
+    }
+    catch {
+        return {
+            resultText: ALLOWLIST_REJECT_MESSAGE,
+            log: { path: requestedPath, allowed: false, reason: "not_found", startedAt, durationMs: Date.now() - startedAt },
+        };
+    }
+}
+async function sendWithResilience(adapter, conv, sendOpts, cfg, ctx) {
+    let generalAttempt = 0;
+    let rateLimitAttempt = 0;
+    // §6：每次錯誤都記（不只終局那次）——中斷或失敗時完全沒有線索的問題，源頭是逐次錯誤
+    // 從未落過檔，不是只有最後一次。message／errorBody 已在 describeError 內遮蔽。
+    const recordError = (err, message, status, errorBody) => {
+        ctx.errors.push(message);
+        const request = err instanceof ProviderHttpError ? err.request : undefined;
+        ctx.rawErrors.push({ round: ctx.round, status, message, errorBody, request });
+        ctx.onEvent({ type: "round_error", agent: ctx.agent, round: ctx.round, status, message });
+    };
+    for (;;) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), cfg.timeoutMs);
+        try {
+            const result = await adapter.send(conv, { ...sendOpts, signal: controller.signal });
+            clearTimeout(timer);
+            return { ok: true, result };
+        }
+        catch (err) {
+            clearTimeout(timer);
+            if (err instanceof RawIntegrityError) {
+                // §8：raw 完整性違反是實作缺陷，不是 API 錯誤——重試只會確定性地再次觸發同一個
+                // bug（下一輪的 conv 結構仍帶著同樣的漏洞），不消耗任何網路呼叫也不可能成功。
+                // 立即判定失敗，不進入一般失敗的重試計數。
+                recordError(err, `raw 完整性檢查失敗（實作缺陷，不重試）：${err.message}`, null);
+                return { ok: false, kind: "failed" };
+            }
+            const info = describeError(err);
+            if (info.is429) {
+                rateLimitAttempt++;
+                if (rateLimitAttempt > cfg.rateLimitRetries) {
+                    recordError(err, `429 撞牆次數超過 --rate-limit-retries (${cfg.rateLimitRetries})`, info.status ?? 429, info.errorBody);
+                    return { ok: false, kind: "rate_limited" };
+                }
+                const { seconds, source } = parseRetryAfter(info.retryAfterHeader, info.message, rateLimitAttempt - 1);
+                if (seconds > cfg.maxRateWaitSec) {
+                    recordError(err, `429 要求等待 ${seconds}s，超過 --max-rate-wait ${cfg.maxRateWaitSec}s`, info.status ?? 429, info.errorBody);
+                    return { ok: false, kind: "rate_limited" };
+                }
+                ctx.rateLimitHits.push({ at: Date.now(), waitSeconds: seconds, source });
+                ctx.onEvent({ type: "rate_limit_wait", agent: ctx.agent, seconds, source });
+                // §13：429 等待期間釋放 --concurrency 名額，結束後重新取得
+                cfg.semaphore.release();
+                await sleep(seconds * 1000);
+                ctx.addWaitedMs(seconds * 1000);
+                await cfg.semaphore.acquire();
+                continue; // 不計入 retries
+            }
+            // §13：錯誤分類依 HTTP status code，不解析錯誤訊息字串。確定性錯誤（其他 4xx）
+            // 重試必然再撞同一個錯，不消耗 --retries、直接判定失敗。
+            if (classifyError(info.status) === "permanent") {
+                recordError(err, info.message ?? String(err), info.status ?? null, info.errorBody);
+                return { ok: false, kind: "failed" };
+            }
+            generalAttempt++;
+            recordError(err, info.message ?? String(err), info.status ?? null, info.errorBody);
+            if (generalAttempt > cfg.retries) {
+                return { ok: false, kind: "failed" };
+            }
+            await sleep(generalAttempt === 1 ? 1000 : 4000);
+        }
+    }
+}
+export async function runSpoke(spoke, adapter, ticketDir, options) {
+    const startedAt = Date.now();
+    const systemPrompt = buildSystemPrompt(spoke.agentBody, spoke.lang);
+    const firstUserText = buildFirstUserText(path.resolve(ticketDir), spoke.agent, spoke.allowedReadsRelative, options.repoRoot, spoke.lang);
+    const conv = { systemPrompt, turns: [{ role: "user", text: firstUserText }] };
+    let toolCallCount = 0;
+    let cumulativeUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0, available: true };
+    const toolCalls = [];
+    const rateLimitHits = [];
+    const errors = [];
+    const rawRequests = [];
+    const rawResponses = [];
+    const rawErrors = [];
+    let waitedMs = 0;
+    let modelReturned = null;
+    let requestId = null;
+    let store = "unknown";
+    let finishReason = null;
+    let finishReasonRaw = null;
+    let finalText = null;
+    let status = "succeeded";
+    let budgetTrigger;
+    let finalizeMode = false;
+    let attempts = 0;
+    const unknownUsageKeys = [];
+    const seenUnknownUsageKeys = new Set();
+    // plan_dispatch_v2.7.md §29 規格七之二：改用 usage.ts 的窮盡式對照表，不再用三元運算子
+    // 猜——三元運算子的「其餘」分支會讓新 provider 靜默落到既有某一家的允許清單，型別檢查
+    // 抓不到（同一份 commit 之外的第二個「新增 provider 忘記同步」實例，見 createAdapterFor）。
+    const unknownUsageProviderKey = usageProviderKeyFor(spoke.providerConfig.api);
+    const estimatedPromptTokens = Math.ceil((systemPrompt.length + firstUserText.length) / options.charsPerToken);
+    options.onEvent({ type: "spoke_start", agent: spoke.agent, provider: spoke.provider, model: spoke.model });
+    for (let round = 1; round <= MAX_ROUNDS; round++) {
+        attempts++;
+        const outcome = await sendWithResilience(adapter, conv, { model: spoke.model, effort: spoke.effort, enableTools: !finalizeMode }, {
+            timeoutMs: options.timeoutMs,
+            retries: finalizeMode ? 0 : options.retries, // §13：收束呼叫一般失敗不重試
+            rateLimitRetries: options.rateLimitRetries,
+            maxRateWaitSec: options.maxRateWaitSec,
+            semaphore: options.semaphore,
+        }, {
+            agent: spoke.agent,
+            round,
+            errors,
+            rawErrors,
+            rateLimitHits,
+            onEvent: options.onEvent,
+            addWaitedMs: (ms) => {
+                waitedMs += ms;
+            },
+        });
+        if (!outcome.ok) {
+            const hasContent = rawResponses.length > 0;
+            if (outcome.kind === "rate_limited") {
+                status = hasContent ? "truncated:rate_limit" : "failed";
+            }
+            else {
+                // v1.8 §13：「終局」只指不再重試（finalizeMode 已在呼叫端把 retries 傳成 0），
+                // 不指狀態標記——狀態一律依判定原則（有無已付費取得的內容），與是否為收束呼叫
+                // 無關。v1.6 曾把兩者混為一談（!finalizeMode && hasContent），造成收束呼叫遇
+                // 一般失敗時，即使前面幾輪已有內容，也一律回 failed，與 429 路徑的對稱處置不一致。
+                status = hasContent ? "truncated:error" : "failed";
+            }
+            break;
+        }
+        const { result } = outcome;
+        rawRequests.push(result.request);
+        rawResponses.push(result.response);
+        modelReturned = result.meta.modelReturned;
+        requestId = result.meta.requestId;
+        store = result.meta.store;
+        finishReason = result.meta.finishReason;
+        finishReasonRaw = result.meta.finishReasonRaw;
+        cumulativeUsage = sumUsage(cumulativeUsage, result.usage);
+        // v2.6 §26 規格六：偵測器不得有能力弄死主流程——包 try/catch，失敗時視同無新發現，
+        // 靜默跳過該輪（偵測器是輔助，不是派工能否成立的條件）。
+        try {
+            const detected = findUnknownUsageKeys(unknownUsageProviderKey, result.usageRaw);
+            const newKeys = detected.filter((k) => !seenUnknownUsageKeys.has(k));
+            if (newKeys.length > 0) {
+                newKeys.forEach((k) => seenUnknownUsageKeys.add(k));
+                unknownUsageKeys.push(...newKeys);
+                options.onEvent({ type: "unknown_usage_keys", agent: spoke.agent, keys: newKeys, round });
+            }
+        }
+        catch {
+            // 規格六：靜默跳過，不影響派工
+        }
+        const toolCallsThisRound = result.turn.role === "assistant" ? result.turn.toolCalls : [];
+        options.onEvent({
+            type: "round",
+            agent: spoke.agent,
+            round,
+            usage: result.usage,
+            hasToolCalls: toolCallsThisRound.length > 0,
+        });
+        conv.turns.push(result.turn);
+        if (!result.usage.available) {
+            status = "truncated:usage_unavailable";
+            errors.push(`round ${round}: usage 不可用（usageMissing），保守收束`);
+            finalText = result.meta.text ?? finalText;
+            if (toolCallsThisRound.length === 0 || finalizeMode)
+                break;
+            finalizeMode = true;
+            conv.turns.push({ role: "user", text: buildFinalizeUserText(spoke.lang) });
+            continue;
+        }
+        if (toolCallsThisRound.length === 0) {
+            finalText = result.meta.text;
+            break;
+        }
+        if (finalizeMode) {
+            // 收束呼叫理論上不帶 tool，仍收到 tool call 屬異常，防禦性丟棄不執行
+            errors.push(`round ${round}: 收束呼叫仍回傳 tool call，忽略`);
+            finalText = result.meta.text;
+            break;
+        }
+        // §14：兩道推理上限，檢查順序為單輪尖峰 → 累積推理 → 累積總量。累積上限抓不到單點
+        // 尖峰（實測：第四段單輪 13,615 推理 token，累積上限 400,000 遠遠碰不到），故單輪
+        // 檢查優先；三者共用 truncated:budget 狀態，budgetTrigger 記來源供事後診斷。
+        const roundReasoningTokens = result.usage.reasoningTokens ?? 0;
+        if (options.maxRoundReasoningTokens !== null && roundReasoningTokens > options.maxRoundReasoningTokens) {
+            status = "truncated:budget";
+            budgetTrigger = "reasoning_round";
+            finalizeMode = true;
+            conv.turns.push({ role: "user", text: buildFinalizeUserText(spoke.lang) });
+            continue;
+        }
+        const cumulativeReasoningTokens = cumulativeUsage.reasoningTokens ?? 0;
+        if (cumulativeReasoningTokens > options.maxSpokeReasoningTokens) {
+            status = "truncated:budget";
+            budgetTrigger = "reasoning";
+            finalizeMode = true;
+            conv.turns.push({ role: "user", text: buildFinalizeUserText(spoke.lang) });
+            continue;
+        }
+        if (cumulativeUsage.totalTokens >= options.maxSpokeTokens) {
+            status = "truncated:budget";
+            budgetTrigger = "total";
+            finalizeMode = true;
+            conv.turns.push({ role: "user", text: buildFinalizeUserText(spoke.lang) });
+            continue;
+        }
+        let hitToolLimit = false;
+        for (const call of toolCallsThisRound) {
+            toolCallCount++;
+            if (toolCallCount > options.maxToolCalls) {
+                // §7：被拒的呼叫仍計入上限；觸限後不執行，直接改走收束。這次呼叫連白名單判定都
+                // 沒跑到，仍記入 toolCalls[]（reason: tool_limit_exceeded）以求可觀測性——
+                // 「查 run.jsonl 就能重建它到底讀了什麼、幾次被拒」不該因觸限而漏一段。
+                hitToolLimit = true;
+                const log = {
+                    path: typeof call.args.path === "string" ? call.args.path : "",
+                    allowed: false,
+                    reason: "tool_limit_exceeded",
+                    startedAt: Date.now(),
+                    durationMs: 0,
+                };
+                toolCalls.push(log);
+                options.onEvent({ type: "tool_call", agent: spoke.agent, path: log.path, allowed: false, reason: log.reason });
+                conv.turns.push({ role: "tool", callId: call.id, result: "已達 --max-tool-calls 上限，未執行" });
+                continue;
+            }
+            const { resultText, log } = await executeToolCall(call, spoke, options.repoRoot);
+            toolCalls.push(log);
+            options.onEvent({ type: "tool_call", agent: spoke.agent, path: log.path, allowed: log.allowed, reason: log.reason });
+            conv.turns.push({ role: "tool", callId: call.id, result: resultText });
+        }
+        if (hitToolLimit) {
+            status = "truncated:tool_limit";
+            finalizeMode = true;
+            conv.turns.push({ role: "user", text: buildFinalizeUserText(spoke.lang) });
+        }
+    }
+    const finishedAt = Date.now();
+    // plan_fixes_v1.0.md §4：以請求時的型號查價（spoke.model，非 modelReturned）——價目
+    // 是「配置了要付這個模型的錢」，與伺服器實際服務的模型無關。缺價目資料時回傳 null。
+    const costUsd = estimateCostUsd(cumulativeUsage, spoke.providerConfig.api, spoke.providerConfig.pricing?.[spoke.model]);
+    options.onEvent({
+        type: "spoke_end",
+        agent: spoke.agent,
+        status,
+        latencyMs: finishedAt - startedAt,
+        totalTokens: cumulativeUsage.totalTokens,
+        estimatedPromptTokens,
+        costUsd,
+        budgetTrigger,
+    });
+    return {
+        agent: spoke.agent,
+        provider: spoke.provider,
+        api: spoke.providerConfig.api,
+        modelRequested: spoke.model,
+        modelReturned,
+        effort: spoke.effort,
+        store,
+        status,
+        budgetTrigger,
+        finalText,
+        usage: cumulativeUsage,
+        costUsd,
+        finishReason,
+        finishReasonRaw,
+        toolCalls,
+        rateLimitHits,
+        unknownUsageKeys,
+        attempts,
+        errors,
+        requestId,
+        startedAt,
+        finishedAt,
+        latencyMs: finishedAt - startedAt,
+        waitedMs,
+        estimatedPromptTokens,
+        rawRequests,
+        rawResponses,
+        rawErrors,
+    };
+}

package/dist/secret-env.js

@@ -0,0 +1,6 @@
+// plan_dispatch_v1.4.md §12／plan_dispatch_v2.7.md §29 規格七：registerSecrets 的來源清單
+// 是硬編的，不是自動掃描——API key 的解析（`${provider}_API_KEY` 慣例）會自動成立，但遮罩
+// 不會。清單獨立成檔（而非留在 cli.ts 內聯宣告），是為了讓測試能直接匯入比對，不需要匯入
+// 有 main() 副作用的 cli.ts 本體（cli-args.ts 拆分同一理由）。新增 provider 時漏加這裡，
+// 該 provider 的金鑰就可能原樣出現在錯誤訊息、raw/*.request.json 或 run.jsonl 中。
+export const SECRET_ENV_VARS = ["DEEPSEEK_API_KEY", "GEMINI_API_KEY", "OPENAI_API_KEY", "ANTHROPIC_API_KEY"];