dowafu 0.1.0

package/dist/semaphore.js

@@ -0,0 +1,25 @@
+// plan_dispatch_v1.4.md §9/§13：--concurrency 用信號量控制發起；429 等待期間 release()，
+// 結束後重新 acquire()。release() 優先直接把名額交給排隊者，不經過 available 計數，
+// 避免「release 後又被別人搶先 acquire」的競態窗口。
+export class Semaphore {
+    available;
+    queue = [];
+    constructor(max) {
+        this.available = max;
+    }
+    acquire() {
+        if (this.available > 0) {
+            this.available--;
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => this.queue.push(resolve));
+    }
+    release() {
+        const next = this.queue.shift();
+        if (next) {
+            next();
+            return;
+        }
+        this.available++;
+    }
+}

package/dist/ticket.js

@@ -0,0 +1,156 @@
+// plan_dispatch_v1.4.md §4：工單目錄解析。純函式（吃 markdown 字串、吐結構化資料），
+// 檔案系統存取另外在 loadTicket() 做，方便單元測試不必 mock 檔案系統。
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { DispatchError } from "./types.js";
+const FORMAT_MARKER = "<!-- format: v1 -->";
+function splitTableRow(line) {
+    const trimmed = line.trim().replace(/^\|/, "").replace(/\|$/, "");
+    return trimmed.split("|").map((cell) => cell.trim());
+}
+function isSeparatorRow(cells) {
+    return cells.length > 0 && cells.every((c) => /^:?-{2,}:?$/.test(c));
+}
+// §4：`_dispatch.md`。model/provider/agent 必填，無預設值；留白或寫 "default" 視為缺失。
+export function parseDispatchTable(markdown) {
+    const lines = markdown.split(/\r?\n/);
+    const firstNonBlank = lines.find((l) => l.trim().length > 0);
+    if (firstNonBlank?.trim() !== FORMAT_MARKER) {
+        throw new DispatchError(`_dispatch.md 首行須為 ${FORMAT_MARKER}，實際為：${firstNonBlank?.trim() ?? "(空白)"}`, 2);
+    }
+    const headerIndex = lines.findIndex((l) => /^\s*\|\s*agent\s*\|/i.test(l));
+    if (headerIndex === -1 || !isSeparatorRow(splitTableRow(lines[headerIndex + 1] ?? ""))) {
+        throw new DispatchError("_dispatch.md 找不到派工表（缺 | agent | ... | 表頭或分隔列）", 2);
+    }
+    const headerCells = splitTableRow(lines[headerIndex]).map((c) => c.toLowerCase());
+    const rows = [];
+    for (let i = headerIndex + 2; i < lines.length; i++) {
+        const line = lines[i];
+        if (!line.trim().startsWith("|"))
+            break;
+        const cells = splitTableRow(line);
+        const get = (col) => {
+            const idx = headerCells.indexOf(col);
+            return idx === -1 ? "" : (cells[idx] ?? "").trim();
+        };
+        const agent = get("agent");
+        const provider = get("provider");
+        const model = get("model");
+        const effort = get("effort");
+        const isMissing = (v) => v.length === 0 || v.toLowerCase() === "default";
+        if (isMissing(agent) || isMissing(provider) || isMissing(model)) {
+            throw new DispatchError(`_dispatch.md 第 ${i + 1} 行缺 agent/provider/model 必填欄位（留白或寫 "default" 視為缺失）：${line}`, 2);
+        }
+        rows.push({ agent, provider, model, effort: effort.length > 0 ? effort : undefined });
+    }
+    if (rows.length === 0) {
+        throw new DispatchError("_dispatch.md 派工表沒有任何資料列", 2);
+    }
+    return rows;
+}
+// 匯出供 audit.ts 重用（回報模板同樣是 `# 標題` 結構）。
+export function splitTopLevelSections(markdown) {
+    const lines = markdown.split(/\r?\n/);
+    const sections = new Map();
+    let currentHeading = null;
+    let buffer = [];
+    const flush = () => {
+        if (currentHeading !== null) {
+            sections.set(currentHeading, buffer.join("\n").trim());
+        }
+    };
+    for (const line of lines) {
+        const match = line.match(/^#\s+(.+?)\s*$/);
+        if (match) {
+            flush();
+            currentHeading = match[1];
+            buffer = [];
+        }
+        else if (currentHeading !== null) {
+            buffer.push(line);
+        }
+    }
+    flush();
+    return sections;
+}
+function parseBulletList(body) {
+    return body
+        .split(/\r?\n/)
+        .map((l) => l.match(/^-\s+(.+)$/)?.[1]?.trim())
+        .filter((v) => Boolean(v && v.length > 0));
+}
+// §4：`_shared.md`。「待審段落」缺失或空即中止；「前提」缺失為警告（空前提合法）。
+export function parseSharedDoc(markdown) {
+    const sections = splitTopLevelSections(markdown);
+    const reviewText = sections.get("待審段落") ?? sections.get("Under review");
+    if (!reviewText || reviewText.length === 0) {
+        // issue_log_v2.1.md：這個錯誤實測撞過兩次，而兩次的成因都不是「忘了寫」——是內嵌的
+        // 規劃書自帶 `#` 標題，被 splitTopLevelSections 當成新區塊，把待審段落切斷了。
+        // 原訊息「缺或內容為空」會讓人先去查自己有沒有寫，方向就錯了。標題存在卻空白時，
+        // 直接指名是誰切斷了它。
+        if (sections.has("待審段落") || sections.has("Under review")) {
+            const stray = [...sections.keys()].filter((k) => k !== "待審段落" && k !== "Under review" && !k.startsWith("前提") && k !== "Premises");
+            if (stray.length > 0) {
+                throw new DispatchError(`_shared.md 的「# 待審段落」有標題但內容為空——被後面這些 \`#\` 標題切斷了：` +
+                    `${stray.map((s) => `「# ${s}」`).join("、")}。` +
+                    `工單以 \`#\` 切分區塊，內嵌的規劃書若自帶 \`#\` 標題請降成 \`##\`。` +
+                    `（注意：在「# 待審段落」下面補一行文字雖然能通過檢查，但規劃書本體仍會留在` +
+                    `後面那個區塊裡，spoke 收到的待審段落等於是空的。）`, 2);
+            }
+        }
+        throw new DispatchError('_shared.md 缺「# 待審段落」（或英文工單的「# Under review」）或內容為空', 2);
+    }
+    const premisesBody = sections.get("前提（不受審）") ?? sections.get("前提") ?? sections.get("Premises");
+    const premises = premisesBody ? parseBulletList(premisesBody) : [];
+    return { premises, reviewText };
+}
+// §4：`<agent>.md`。「具體問題」缺失或空即中止；「允許讀取」缺失為警告（空清單合法）。
+export function parseAgentTicket(markdown) {
+    const sections = splitTopLevelSections(markdown);
+    // 先中文後英文。命中哪一套就是這份工單的語言——不看內文，只看標記，因為內文可能
+    // 中英混雜（英文規劃書配中文問題是常見寫法），標記則是作者明確選的。
+    const zhQuestions = sections.get("具體問題");
+    const enQuestions = sections.get("Questions");
+    const lang = zhQuestions !== undefined ? "zh" : enQuestions !== undefined ? "en" : "zh";
+    const questions = zhQuestions ?? enQuestions;
+    if (!questions || questions.length === 0) {
+        throw new DispatchError('<agent>.md 缺「# 具體問題」（或英文工單的「# Questions」）或內容為空', 2);
+    }
+    const allowedBody = sections.get("允許讀取") ?? sections.get("Allowed reads");
+    const allowedReads = allowedBody ? parseBulletList(allowedBody) : [];
+    return { questions, allowedReads, lang };
+}
+// 檔案系統存取層：讀工單目錄、組出完整 Ticket。
+export async function loadTicket(ticketDir) {
+    const dispatchPath = path.join(ticketDir, "_dispatch.md");
+    const sharedPath = path.join(ticketDir, "_shared.md");
+    let dispatchText;
+    try {
+        dispatchText = await readFile(dispatchPath, "utf8");
+    }
+    catch {
+        throw new DispatchError(`找不到 ${dispatchPath}`, 2);
+    }
+    let sharedText;
+    try {
+        sharedText = await readFile(sharedPath, "utf8");
+    }
+    catch {
+        throw new DispatchError(`找不到 ${sharedPath}`, 2);
+    }
+    const rows = parseDispatchTable(dispatchText);
+    const shared = parseSharedDoc(sharedText);
+    const perAgent = new Map();
+    for (const row of rows) {
+        const agentPath = path.join(ticketDir, `${row.agent}.md`);
+        let agentText;
+        try {
+            agentText = await readFile(agentPath, "utf8");
+        }
+        catch {
+            throw new DispatchError(`找不到 ${agentPath}（_dispatch.md 列了 agent "${row.agent}"）`, 2);
+        }
+        perAgent.set(row.agent, parseAgentTicket(agentText));
+    }
+    return { ticketDir, rows, shared, perAgent };
+}

package/dist/tool-call-audit.js

@@ -0,0 +1,19 @@
+// plan_dispatch_v2.0.md §15（一）：稽核表補「tool 呼叫」欄。這是對執行資料（run.jsonl 的
+// toolCalls[]）的判定，刻意獨立於 audit.ts 之外——audit.ts 的 auditSpoke 是對 spoke 產出
+// 文字的確定性判定，純函式吃 finalText，不吃執行資料，這個純度是它現有測試的基礎。
+// tool 呼叫記錄不是文字，不塞進 auditSpoke。
+import path from "node:path";
+function isTicketFile(requestedPath, agent) {
+    const base = path.basename(requestedPath);
+    return base === "_shared.md" || base === `${agent}.md`;
+}
+export function auditToolCalls(agent, toolCalls, allowedReadsCount) {
+    const total = toolCalls.length;
+    const allowed = toolCalls.filter((t) => t.allowed).length;
+    const rejected = total - allowed;
+    // total > 0 護欄：空陣列的 .every() 恆真，避免「一次 tool 都沒呼叫」被誤判為「只讀了
+    // 工單檔」——兩者是不同訊號，前者連工單都沒讀，非本項要抓的「讀了工單卻不讀程式碼」。
+    const allTicketFiles = total > 0 && toolCalls.every((t) => isTicketFile(t.path, agent));
+    const zeroSourceRead = allTicketFiles && allowedReadsCount > 0;
+    return { total, allowed, rejected, allowedReadsCount, zeroSourceRead };
+}

package/dist/types.js

@@ -0,0 +1,11 @@
+// plan_dispatch_v1.4.md §8：中性表示。raw 原樣保留，不解構重組；toolCalls 是唯讀投影，
+// 核心不得用它重建請求（adapter 續接一律用 raw）。
+// fail-closed 錯誤：帶 exit code，CLI 層 catch 後對應 process.exit（§10）。
+export class DispatchError extends Error {
+    exitCode;
+    constructor(message, exitCode) {
+        super(message);
+        this.exitCode = exitCode;
+        this.name = "DispatchError";
+    }
+}

package/dist/usage.js

@@ -0,0 +1,224 @@
+// plan_dispatch_v1.4.md §12：usage 正規化層。key 是 provider＋端點，不是只有 provider——
+// 實測四套命名互不相同（facts_dispatch.md）。純函式，供單元測試。
+function isNumber(v) {
+    return typeof v === "number" && Number.isFinite(v);
+}
+// openai／deepseek 的 /v1/responses：input_tokens / output_tokens / total_tokens
+export function normalizeResponsesUsage(raw) {
+    const r = (raw ?? {});
+    const inputTokens = isNumber(r.input_tokens) ? r.input_tokens : undefined;
+    const outputTokens = isNumber(r.output_tokens) ? r.output_tokens : undefined;
+    let totalTokens = isNumber(r.total_tokens) ? r.total_tokens : undefined;
+    // 缺 totalTokens 一律以 input + output 補（§12）
+    if (totalTokens === undefined && inputTokens !== undefined && outputTokens !== undefined) {
+        totalTokens = inputTokens + outputTokens;
+    }
+    const inputDetails = r.input_tokens_details;
+    const outputDetails = r.output_tokens_details;
+    const cachedTokens = isNumber(inputDetails?.cached_tokens) ? inputDetails.cached_tokens : undefined;
+    const cacheWriteTokens = isNumber(inputDetails?.cache_write_tokens)
+        ? inputDetails.cache_write_tokens
+        : undefined;
+    const reasoningTokens = isNumber(outputDetails?.reasoning_tokens)
+        ? outputDetails.reasoning_tokens
+        : undefined;
+    return {
+        inputTokens: inputTokens ?? 0,
+        outputTokens: outputTokens ?? 0,
+        totalTokens: totalTokens ?? 0,
+        cachedTokens,
+        cacheWriteTokens,
+        reasoningTokens,
+        // v2.5 規格二：快取欄位不得影響 available。openai 的 input_tokens_details 有一種形狀
+        // （('image_tokens','text_tokens')，實測 79 次）完全沒有 cache_write_tokens，屬正常情形。
+        available: inputTokens !== undefined && outputTokens !== undefined && totalTokens !== undefined,
+    };
+}
+// gemini generateContent：promptTokenCount / candidatesTokenCount / totalTokenCount。
+// thoughtsTokenCount 是 v1.8 才新增的欄位——開啟 thinkingConfig 之前的實測從未觀察到它
+// （facts_dispatch.md 寫的是「無對應欄位」），§20 驗證腳本確認開啟後會出現且隨值縮放
+// （low 133 → high 1,805）。與 openai 的 reasoning_tokens 同樣只記錄不參與 totalTokens
+// 計算——totalTokenCount 由 API 直接給值時一律優先採用，不重算。
+export function normalizeGeminiUsage(raw) {
+    const r = (raw ?? {});
+    const inputTokens = isNumber(r.promptTokenCount) ? r.promptTokenCount : undefined;
+    const outputTokens = isNumber(r.candidatesTokenCount) ? r.candidatesTokenCount : undefined;
+    const reasoningTokens = isNumber(r.thoughtsTokenCount) ? r.thoughtsTokenCount : undefined;
+    const cachedTokens = isNumber(r.cachedContentTokenCount) ? r.cachedContentTokenCount : undefined;
+    let totalTokens = isNumber(r.totalTokenCount) ? r.totalTokenCount : undefined;
+    // plan_dispatch_v1.12.md §12／§14：gemini 的帳目關係是 promptTokenCount +
+    // candidatesTokenCount + thoughtsTokenCount = totalTokenCount（實測 592+79+321=992）——
+    // thoughtsTokenCount 不是 candidatesTokenCount 的子集，與 openai／deepseek 的
+    // reasoning_tokens ⊆ output_tokens 相反。缺 totalTokenCount 時的回補公式若沿用
+    // input+output（子集假設下才成立），會在 thoughtsTokenCount 存在時漏算，故此處須把
+    // reasoningTokens 一併算入。
+    if (totalTokens === undefined && inputTokens !== undefined && outputTokens !== undefined) {
+        totalTokens = inputTokens + outputTokens + (reasoningTokens ?? 0);
+    }
+    return {
+        inputTokens: inputTokens ?? 0,
+        outputTokens: outputTokens ?? 0,
+        totalTokens: totalTokens ?? 0,
+        reasoningTokens,
+        cachedTokens,
+        // v2.5 規格二：implicit caching 下限 4,096 token，小 prompt 本來就不會有這個欄位，
+        // 缺席不得使 available 轉 false（facts_dispatch.md 2026-08-08 更正條目二）
+        available: inputTokens !== undefined && outputTokens !== undefined && totalTokens !== undefined,
+    };
+}
+// plan_dispatch_v2.7.md §29 規格十／十一：anthropic Messages API 的 usage 欄位名，實測
+// 確認（scripts/verify-providers.ts，見 facts_dispatch.md）——input_tokens／
+// cache_creation_input_tokens／cache_read_input_tokens／cache_creation／output_tokens／
+// output_tokens_details（含 thinking_tokens）／service_tier／inference_geo。
+export function normalizeAnthropicUsage(raw) {
+    const r = (raw ?? {});
+    const inputTokens = isNumber(r.input_tokens) ? r.input_tokens : undefined;
+    const outputTokens = isNumber(r.output_tokens) ? r.output_tokens : undefined;
+    const cacheReadTokens = isNumber(r.cache_read_input_tokens) ? r.cache_read_input_tokens : undefined;
+    const cacheCreationTokens = isNumber(r.cache_creation_input_tokens) ? r.cache_creation_input_tokens : undefined;
+    const outputDetails = r.output_tokens_details;
+    const reasoningTokens = isNumber(outputDetails?.thinking_tokens) ? outputDetails.thinking_tokens : undefined;
+    // 規格十：Anthropic 無 total_tokens 欄位，須自行加總。且 input_tokens 在有快取時不含快取
+    // 部分（官方 usage 範例三者並列），故正確總量是 input+output+快取讀取+快取寫入的四者之和，
+    // 不是 input+output 兩者（那個公式是 openai／deepseek 的形狀，此處會低估）。
+    const totalTokens = (inputTokens ?? 0) + (outputTokens ?? 0) + (cacheReadTokens ?? 0) + (cacheCreationTokens ?? 0);
+    return {
+        inputTokens: inputTokens ?? 0,
+        outputTokens: outputTokens ?? 0,
+        totalTokens,
+        cachedTokens: cacheReadTokens,
+        cacheWriteTokens: cacheCreationTokens,
+        reasoningTokens,
+        available: inputTokens !== undefined && outputTokens !== undefined,
+    };
+}
+const STOP_VALUES = new Set(["completed", "STOP", "end_turn"]);
+export function normalizeFinishReason(raw) {
+    const finishReasonRaw = raw ?? null;
+    if (raw && STOP_VALUES.has(raw)) {
+        return { finishReason: "stop", finishReasonRaw };
+    }
+    return { finishReason: raw ?? "unknown", finishReasonRaw };
+}
+// v2.5 規格三：兩邊皆缺席時輸出 undefined，不是 0——「沒有資料」與「量測值為 0」必須
+// 可區分，否則 run.jsonl 裡的 0 會被誤讀為一次量測結果。
+function addOptional(a, b) {
+    if (a === undefined && b === undefined)
+        return undefined;
+    return (a ?? 0) + (b ?? 0);
+}
+export function sumUsage(a, b) {
+    return {
+        inputTokens: a.inputTokens + b.inputTokens,
+        outputTokens: a.outputTokens + b.outputTokens,
+        totalTokens: a.totalTokens + b.totalTokens,
+        cachedTokens: addOptional(a.cachedTokens, b.cachedTokens),
+        cacheWriteTokens: addOptional(a.cacheWriteTokens, b.cacheWriteTokens),
+        reasoningTokens: addOptional(a.reasoningTokens, b.reasoningTokens),
+        available: a.available && b.available,
+    };
+}
+export const EMPTY_USAGE = {
+    inputTokens: 0,
+    outputTokens: 0,
+    totalTokens: 0,
+    available: true,
+};
+// plan_dispatch_v2.6.md §26 規格二：允許清單緊鄰對應的正規化函式，不放 providers.json——
+// 「正規化層認得哪些 key」是程式內部知識，距離讀取邏輯越遠越容易漏更新（這正是本版要防
+// 的事）。清單須含所有已知 key，不只「有讀的 key」；已知但刻意不讀的也要列入並註明理由，
+// 否則每次派工都會誤報，把真正的新欄位訊號淹掉。清單依據：tmp/external-runs/ 十次真實
+// 派工的 raw 全量掃描（§27），逐一開檔核對而非憑欄位名猜測。
+const RESPONSES_USAGE_KEYS = new Set(["input_tokens", "output_tokens", "total_tokens", "input_tokens_details", "output_tokens_details"]);
+const RESPONSES_INPUT_DETAILS_KEYS = new Set(["cached_tokens", "cache_write_tokens"]);
+// image_tokens／text_tokens：已知，不參與計算。註：本機十次真實派工的 raw 裡，這兩個
+// key 實際只出現在同一份 response 的另一個頂層欄位 tool_usage.image_gen.*_tokens_details
+// （與 usage 完全無關的欄位，不在本偵測器掃描範圍內——見規格一），從未在
+// usage.output_tokens_details 本身出現過。列在此處純屬防禦：即便官方日後把它併入
+// usage.output_tokens_details，也不會被誤報成新欄位。
+const RESPONSES_OUTPUT_DETAILS_KEYS = new Set(["reasoning_tokens", "image_tokens", "text_tokens"]);
+const GEMINI_USAGE_KEYS = new Set([
+    "promptTokenCount",
+    "candidatesTokenCount",
+    "totalTokenCount",
+    "thoughtsTokenCount",
+    "cachedContentTokenCount",
+    "promptTokensDetails",
+    "cacheTokensDetails", // 已知，不參與計算：cachedContentTokenCount 的 modality 拆分（v2.5 未讀，14 次）
+    "serviceTier", // 已知，不參與計算
+]);
+// 規格一：巢狀節點只走已知的三個，不做無限遞迴——cacheTokensDetails 雖與
+// promptTokensDetails 同形狀，但不在這三個之列，只列為已知頂層 key，不遞迴檢查其內容。
+const GEMINI_PROMPT_DETAILS_ITEM_KEYS = new Set(["modality", "tokenCount"]);
+// plan_dispatch_v2.7.md §29 規格七之二：以 scripts/verify-providers.ts 對真實 API 的回應
+// 為準（見 facts_dispatch.md），不照官方文件猜——文件另提過 server_tool_use 這個欄位，但
+// 本次實測（純 client-side read_file 工具，非 Anthropic 伺服器端工具）從未出現過，故不列入；
+// 依 v2.6 §26 的既有紀律，未出現的欄位交由本偵測器在真正撞到時示警，再核對後補入，不預先
+// 整批加入猜測值。
+const ANTHROPIC_USAGE_KEYS = new Set([
+    "input_tokens",
+    "output_tokens",
+    "cache_creation_input_tokens",
+    "cache_read_input_tokens",
+    "cache_creation",
+    "output_tokens_details",
+    "service_tier",
+    "inference_geo",
+]);
+const ANTHROPIC_CACHE_CREATION_KEYS = new Set(["ephemeral_5m_input_tokens", "ephemeral_1h_input_tokens"]);
+const ANTHROPIC_OUTPUT_DETAILS_KEYS = new Set(["thinking_tokens"]);
+function collectUnknownKeys(obj, known, pathPrefix) {
+    return Object.keys(obj)
+        .filter((k) => !known.has(k))
+        .map((k) => (pathPrefix ? `${pathPrefix}.${k}` : k));
+}
+function isPlainRecord(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+// 規格七之二：exhaustive 分派，不留「其餘落到 X」的預設分支——switch 缺少任一 case 時，
+// TypeScript 會因「不是每條路徑都回傳值」而編譯失敗，逼未來新增第四家 provider 時必須
+// 手動同步這裡，不會靜默落到既有某一家的允許清單（v2.6 的 unknownUsageProviderKey 三元
+// 運算子正是這樣被 "anthropic-messages" 加入後靜默吃掉，型別檢查抓不到）。
+export function usageProviderKeyFor(api) {
+    switch (api) {
+        case "responses":
+            return "responses";
+        case "gemini-native":
+            return "gemini";
+        case "anthropic-messages":
+            return "anthropic";
+    }
+}
+export function findUnknownUsageKeys(providerKey, usageRaw) {
+    if (!isPlainRecord(usageRaw))
+        return [];
+    if (providerKey === "responses") {
+        const unknown = collectUnknownKeys(usageRaw, RESPONSES_USAGE_KEYS, "");
+        if (isPlainRecord(usageRaw.input_tokens_details)) {
+            unknown.push(...collectUnknownKeys(usageRaw.input_tokens_details, RESPONSES_INPUT_DETAILS_KEYS, "input_tokens_details"));
+        }
+        if (isPlainRecord(usageRaw.output_tokens_details)) {
+            unknown.push(...collectUnknownKeys(usageRaw.output_tokens_details, RESPONSES_OUTPUT_DETAILS_KEYS, "output_tokens_details"));
+        }
+        return unknown;
+    }
+    if (providerKey === "anthropic") {
+        const unknown = collectUnknownKeys(usageRaw, ANTHROPIC_USAGE_KEYS, "");
+        if (isPlainRecord(usageRaw.cache_creation)) {
+            unknown.push(...collectUnknownKeys(usageRaw.cache_creation, ANTHROPIC_CACHE_CREATION_KEYS, "cache_creation"));
+        }
+        if (isPlainRecord(usageRaw.output_tokens_details)) {
+            unknown.push(...collectUnknownKeys(usageRaw.output_tokens_details, ANTHROPIC_OUTPUT_DETAILS_KEYS, "output_tokens_details"));
+        }
+        return unknown;
+    }
+    const unknown = collectUnknownKeys(usageRaw, GEMINI_USAGE_KEYS, "");
+    if (Array.isArray(usageRaw.promptTokensDetails)) {
+        for (const el of usageRaw.promptTokensDetails) {
+            if (isPlainRecord(el)) {
+                unknown.push(...collectUnknownKeys(el, GEMINI_PROMPT_DETAILS_ITEM_KEYS, "promptTokensDetails"));
+            }
+        }
+    }
+    return unknown;
+}

package/dist/validate.js

@@ -0,0 +1,100 @@
+// plan_dispatch_v1.4.md §4/§7/§18：工單與 providers.json 的交叉驗證，組出每個 spoke
+// 執行所需的完整、已驗證資料（ResolvedSpoke）。第 1–5 步全部在任何 API 呼叫之前完成，
+// 成本為零（§10）。
+import fs from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { DispatchError } from "./types.js";
+import { buildAllowSet } from "./whitelist.js";
+function apiKeyEnvFor(provider) {
+    return `${provider.toUpperCase()}_API_KEY`;
+}
+function stripFrontmatter(markdown) {
+    const match = markdown.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n([\s\S]*)$/);
+    return (match ? match[1] : markdown).trim();
+}
+async function readAgentBody(agentsDir, agent) {
+    const agentDefPath = path.join(agentsDir, `${agent}.md`);
+    let text;
+    try {
+        text = await readFile(agentDefPath, "utf8");
+    }
+    catch {
+        throw new DispatchError(`找不到 agent 定義檔 ${agentDefPath}（_dispatch.md 列了 "${agent}"）`, 2);
+    }
+    return stripFrontmatter(text);
+}
+function isUnderDocsDir(repoRoot, resolved) {
+    const docsRoot = path.resolve(repoRoot, "_docs");
+    return resolved === docsRoot || resolved.startsWith(docsRoot + path.sep);
+}
+export async function resolveSpokes(ticket, providers, repoRoot, agentsDir = path.join(repoRoot, ".claude", "agents")) {
+    const resolved = [];
+    for (const row of ticket.rows) {
+        const providerConfig = providers[row.provider];
+        if (!providerConfig) {
+            throw new DispatchError(`_dispatch.md 的 "${row.agent}" 列引用了未定義於 providers.json 的 provider "${row.provider}"`, 2);
+        }
+        // §18：只檢查本次工單用到的 provider，缺即中止。
+        const envName = apiKeyEnvFor(row.provider);
+        if (!process.env[envName]) {
+            throw new DispatchError(`缺少環境變數 ${envName}（"${row.agent}" 列需要 provider "${row.provider}"）`, 2);
+        }
+        // §5：model 須在 providers.json 的 models 白名單內；白名單為空 = 不做型號檢查。
+        if (providerConfig.models.length > 0 && !providerConfig.models.includes(row.model)) {
+            throw new DispatchError(`"${row.agent}" 列的 model "${row.model}" 不在 provider "${row.provider}" 的 models 白名單內` +
+                `（允許：${providerConfig.models.join(", ")}）`, 2);
+        }
+        // §4：effort 填了但不在該 provider 的 allowed 內即中止（含 allowed 為空陣列）。
+        if (row.effort !== undefined && !providerConfig.reasoning.allowed.includes(row.effort)) {
+            throw new DispatchError(`"${row.agent}" 列的 effort "${row.effort}" 不在 provider "${row.provider}" 的允許值域內` +
+                `（允許值：${providerConfig.reasoning.allowed.length > 0 ? providerConfig.reasoning.allowed.join(", ") : "（空——尚未驗證，任何值皆拒絕）"}）`, 2);
+        }
+        // §5：「留白」不再是「不送任何 reasoning 參數」，而是送 reasoning.default。
+        // allowed 為空時 default 不存在——該 provider 不可用，即使 effort 留白也中止。
+        const effectiveEffort = row.effort ?? providerConfig.reasoning.default;
+        if (effectiveEffort === undefined) {
+            throw new DispatchError(`"${row.agent}" 列的 effort 留白，但 provider "${row.provider}" 未設 reasoning.default` +
+                `（allowed 為空 = 尚未驗證，該 provider 不可用）`, 2);
+        }
+        const agentTicket = ticket.perAgent.get(row.agent);
+        if (!agentTicket) {
+            // loadTicket() 已保證存在，此處為型別窄化與防禦
+            throw new DispatchError(`內部錯誤：找不到 "${row.agent}" 的工單內容`, 2);
+        }
+        // §4「針對 hub 會寫錯」：_docs/ 一律拒絕；允許清單逐一驗證存在，任一不存在即中止並指名。
+        const allowedReadsResolved = [];
+        for (const rel of agentTicket.allowedReads) {
+            const resolvedPath = path.resolve(repoRoot, rel);
+            if (isUnderDocsDir(repoRoot, resolvedPath)) {
+                throw new DispatchError(`"${row.agent}" 的允許讀取清單指向 _docs/（spoke 禁區）：${rel}`, 2);
+            }
+            let real;
+            try {
+                real = fs.realpathSync(resolvedPath);
+            }
+            catch {
+                throw new DispatchError(`"${row.agent}" 的允許讀取清單指向不存在的路徑：${rel}`, 2);
+            }
+            allowedReadsResolved.push(real);
+        }
+        const agentBody = await readAgentBody(agentsDir, row.agent);
+        const sharedPath = path.join(ticket.ticketDir, "_shared.md");
+        const ownAgentPath = path.join(ticket.ticketDir, `${row.agent}.md`);
+        const allowSet = buildAllowSet([sharedPath, ownAgentPath, ...allowedReadsResolved]);
+        resolved.push({
+            agent: row.agent,
+            provider: row.provider,
+            providerConfig,
+            model: row.model,
+            effort: effectiveEffort,
+            agentBody,
+            questions: agentTicket.questions,
+            allowSet,
+            allowedReadsResolved,
+            allowedReadsRelative: agentTicket.allowedReads,
+            lang: agentTicket.lang,
+        });
+    }
+    return resolved;
+}

package/dist/whitelist.js

@@ -0,0 +1,38 @@
+// plan_dispatch_v1.4.md §7：白名單判定，集中於核心，不下放 adapter（三套 adapter 各自
+// 實作必然漂移）。精確路徑集合比對，非前綴比對。純函式，供單元測試，不需 mock 任何 provider。
+import fs from "node:fs";
+import path from "node:path";
+// 入集端也做 realpath（§7）。呼叫前應已用 validateAllowedPathsExist 驗過存在性；
+// 這裡若仍解析失敗就靜默略過——不在集合裡的路徑本來就會被拒絕，不需要另外報錯。
+export function buildAllowSet(paths) {
+    const set = new Set();
+    for (const p of paths) {
+        try {
+            set.add(fs.realpathSync(path.resolve(p)));
+        }
+        catch {
+            // 略過：不存在的路徑不會進集合，checkAllowlist 對它的判定自然是拒絕
+        }
+    }
+    return set;
+}
+// 判定：allowSet.has(realpath(resolve(requested)))。路徑不存在時 realpathSync 拋錯——
+// 視同拒絕，回傳「不存在或不在允許範圍」，不區分兩者（避免用錯誤訊息探測檔案系統）；
+// reason 分類僅供 run.jsonl 記錄用，不影響回給 spoke 的訊息。
+export function checkAllowlist(allowSet, requestedPath, repoRoot) {
+    let real;
+    try {
+        real = fs.realpathSync(path.resolve(repoRoot, requestedPath));
+    }
+    catch {
+        return { allowed: false, reason: "not_found" };
+    }
+    if (allowSet.has(real)) {
+        return { allowed: true, realPath: real };
+    }
+    const resolvedRoot = fs.realpathSync(path.resolve(repoRoot));
+    const insideRepo = real === resolvedRoot || real.startsWith(resolvedRoot + path.sep);
+    return { allowed: false, reason: insideRepo ? "not_in_allowlist" : "outside_repo" };
+}
+// 統一回給 spoke 的訊息：不區分「不存在」與「不在允許範圍」。
+export const ALLOWLIST_REJECT_MESSAGE = "不存在或不在允許範圍";

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "dowafu",
+  "version": "0.1.0",
+  "description": "Send a section of your design doc to external LLMs for review. They read only the files you whitelist, and nothing is billed until you confirm.",
+  "keywords": [
+    "llm",
+    "cli",
+    "code-review",
+    "design-review",
+    "agent",
+    "openai",
+    "deepseek",
+    "gemini",
+    "anthropic"
+  ],
+  "license": "MIT",
+  "author": "Eddy Chang",
+  "homepage": "https://github.com/eyesofkids/dowafu#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eyesofkids/dowafu.git"
+  },
+  "bugs": {
+    "url": "https://github.com/eyesofkids/dowafu/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "dowafu": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "providers.json",
+    "publish"
+  ],
+  "scripts": {
+    "verify:providers": "tsx scripts/verify-providers.ts",
+    "dispatch": "tsx src/cli.ts",
+    "test": "tsx --test 'src/**/*.test.ts'",
+    "lint": "eslint .",
+    "check:skills": "bash scripts/check-publish.sh",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "tsc -p tsconfig.build.json && chmod +x dist/cli.js",
+    "prepublishOnly": "npm run test && npm run lint && npm run typecheck && npm run build"
+  },
+  "dependencies": {
+    "dotenv": "^16.4.5",
+    "openai": "^4.68.4"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.10.2",
+    "eslint": "^10.8.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.66.0"
+  }
+}