dowafu 0.1.0

package/dist/dotenv-invariant.js

@@ -0,0 +1,66 @@
+// plan_dispatch_v1.11.md §20：「不做某事」的規格，其測試必須在該事被做了時失敗。
+// v1.10 §24.4 立的禁令（不得讀 cwd 的 .env）原本只靠 `dispatch-home.test.ts` 守住——但
+// 那支測試守的是 `loadDispatchEnv` 這個函式的行為，不是禁令本身：`import "dotenv/config"`
+// 是模組層級副作用，只有「載入該模組」才會觸發；沒有任何測試 import `cli.ts`，故把
+// `import "dotenv/config"` 加回 `cli.ts` 頂部，既有測試依然全綠。
+//
+// 這裡改用靜態掃描：對 `src/**` 與 `scripts/**` 的原始碼逐行比對，不需執行、不需金鑰、
+// 涵蓋所有現在與未來的檔案——子行程測試只能覆蓋被 spawn 的那一支入口，不取代此項。
+import fs from "node:fs";
+import path from "node:path";
+// 唯一允許 `import dotenv from "dotenv"`（載入整個套件，而非 side-effect 的
+// "dotenv/config" 子路徑）的檔案——它是 §24.4 明訂「唯一允許呼叫 dotenv 的地方」。
+export const ALLOWED_BARE_DOTENV_IMPORT_FILE = path.join("src", "dispatch-home.ts");
+// 只比對「行首（去除縮排後）即為 import 陳述式」的形式，故不會誤判 `//` 開頭、
+// 說明這條禁令本身的註解行（本檔與 dispatch-home.ts／dispatch-home.test.ts／cli.ts
+// 皆有這類註解，字面上含有 "dotenv/config" 字串，但不是真正的 import）。
+//
+// 已知涵蓋邊界（hub 驗收 2026-08-06 fixture 實測確認，刻意不擴大 regex 去堵）：
+// 1. 動態 import——`const x = await import("dotenv/config")` 不會被偵測，因為它不是
+//    行首的 `import` 陳述式。
+// 2. 跨行 import——`import {\n  ...\n} from "dotenv/config"` 不會被偵測，因為比對
+//    是逐「行」進行，模組指定字串沒有跟 `import` 出現在同一行。
+// 不修的理由：要正確排除本檔自己這類說明註解會讓 regex 明顯變複雜，而這道防線要擋的
+// 威脅模型是「有人為了方便把那一行原樣加回來」，不是刻意規避掃描——收益不成比例。
+// 若日後真的出現這兩種寫法，判斷是否值得為此升級掃描邏輯（例如改成解析整個檔案而非
+// 逐行比對），而不是預先做。
+const DOTENV_CONFIG_IMPORT_PATTERN = /^\s*import\b.*["']dotenv\/config["']/;
+const BARE_DOTENV_IMPORT_PATTERN = /^\s*import\b.*["']dotenv["']/;
+function listTsFiles(dir) {
+    if (!fs.existsSync(dir))
+        return [];
+    const out = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            out.push(...listTsFiles(full));
+        }
+        else if (entry.isFile() && full.endsWith(".ts")) {
+            out.push(full);
+        }
+    }
+    return out;
+}
+export function scanDotenvInvariant(repoRoot) {
+    const files = ["src", "scripts"].flatMap((d) => listTsFiles(path.join(repoRoot, d)));
+    const violations = [];
+    for (const file of files) {
+        const relFile = path.relative(repoRoot, file);
+        const lines = fs.readFileSync(file, "utf8").split(/\r?\n/);
+        lines.forEach((line, i) => {
+            if (DOTENV_CONFIG_IMPORT_PATTERN.test(line)) {
+                violations.push({ file: relFile, line: i + 1, text: line.trim(), kind: "dotenv/config" });
+                return; // 一行不會同時命中兩種樣式（"dotenv/config" 與 "dotenv" 的引號內容不同）
+            }
+            if (BARE_DOTENV_IMPORT_PATTERN.test(line) && relFile !== ALLOWED_BARE_DOTENV_IMPORT_FILE) {
+                violations.push({
+                    file: relFile,
+                    line: i + 1,
+                    text: line.trim(),
+                    kind: "bare-dotenv-outside-allowed-file",
+                });
+            }
+        });
+    }
+    return violations;
+}

package/dist/error-classify.js

@@ -0,0 +1,13 @@
+// plan_dispatch_v1.8.md §13：錯誤分類依 HTTP status code，不解析錯誤訊息字串——訊息格式
+// 各家不同且會改版，status code 是穩定契約。429 不在此分類範圍內（runner.ts 在呼叫此函式
+// 之前已用 describeError().is429 攔截，走獨立的 429 等待路徑）。
+// 暫時性：5xx、408，以及無 HTTP 回應的網路層錯誤（status 為 undefined——連線重置、DNS
+// 失敗、AbortController 逾時）。確定性：其他 4xx（400 參數錯、401、403、404…），重試
+// 必然再撞同一個錯，不重試。
+export function classifyError(status) {
+    if (status === undefined)
+        return "transient";
+    if (status >= 500 || status === 408)
+        return "transient";
+    return "permanent";
+}

package/dist/gate.js

@@ -0,0 +1,37 @@
+// plan_dispatch_v1.4.md §14 閘門一：呼叫前估算，擋量級錯誤。chars/4 粗估，刻意不精算——
+// 目的是攔截「把整個 repo 塞進允許清單」這類量級錯誤，非精算成本。超限即中止（exit 3），
+// 此檢查在任何 API 呼叫之前，成本為零。
+import fs from "node:fs";
+import { DispatchError } from "./types.js";
+// §14：charsPerToken 預設 1.0（不是 chars/4）——實測 chars/4 對中文系統性低估 2.7–4 倍，
+// 低估比高估危險，此閘門寧可誤報。providers.json 可逐家覆寫（見 cli.ts 呼叫端）。
+function estimateTokensFromChars(chars, charsPerToken) {
+    return Math.ceil(chars / charsPerToken);
+}
+export function estimateTokens(text, charsPerToken) {
+    return estimateTokensFromChars(text.length, charsPerToken);
+}
+export function estimateAllowlistTokens(filePaths, charsPerToken) {
+    const totalChars = filePaths.reduce((sum, p) => sum + fs.readFileSync(p, "utf8").length, 0);
+    return estimateTokensFromChars(totalChars, charsPerToken);
+}
+export function estimateSequentialRead(filePaths, charsPerToken) {
+    const sizes = filePaths.map((p) => fs.readFileSync(p, "utf8").length);
+    const amplify = (ordered) => {
+        const n = ordered.length;
+        const chars = ordered.reduce((sum, s, i) => sum + s * (n - i), 0);
+        return estimateTokensFromChars(chars, charsPerToken);
+    };
+    return {
+        asListed: amplify(sizes),
+        sorted: amplify([...sizes].sort((a, b) => a - b)),
+    };
+}
+export function checkGateOne(estimates, maxTokens) {
+    const total = estimates.reduce((sum, e) => sum + e.estimatedTokens, 0);
+    if (total > maxTokens) {
+        const detail = estimates.map((e) => `  ${e.agent}: ${e.estimatedTokens}`).join("\n");
+        throw new DispatchError(`閘門一超限：合計初始估算 ${total} tokens 超過 --max-tokens ${maxTokens}\n${detail}`, 3);
+    }
+    return total;
+}

package/dist/gitignore-check.js

@@ -0,0 +1,24 @@
+// plan_dispatch_v1.10.md §10：輸出目錄的 gitignore 三態檢查（使用者裁示：檢查並警告，
+// 不擋執行）。判定用 `git check-ignore -q`，三態不得合併——「未忽略」是需要處理的狀態，
+// 「無法判定」不是（§10「三態不得合併」）。
+//
+// plan_dispatch_v1.11.md §10：判定基準必須與 outDir 的解析基準一致——兩者皆為 cwd，
+// 不是 --repo-root。v1.10 用 `-C <repoRoot>` 判定，但 outDir 是相對 cwd 解析的
+// （v1.11 §24.5：工單目錄／輸出目錄屬呼叫端 cwd，白名單邊界／agents 才屬 repoRoot），
+// cwd ≠ repoRoot 時等於問錯 repo——git 對工作樹外的路徑回 fatal（exit 128），被舊邏輯
+// 吞成 unknown，防線恰好在唯一有價值的情境（跨專案）靜默失效。
+// 一般化規則：任何「對某路徑做判定」的檢查，其基準必須與該路徑的解析基準相同。
+import { spawnSync } from "node:child_process";
+// `cwd` 預設 `process.cwd()`——不接受呼叫端傳入 repoRoot 之類的其他基準；可覆寫純粹是
+// 為了單元測試（例如以 temp git repo 取代真正的 process.cwd()），production 呼叫端
+// （cli.ts）一律用預設值，不傳第二個參數，結構上就不會再誤傳 repoRoot。
+export function checkGitignore(outDir, cwd = process.cwd()) {
+    const result = spawnSync("git", ["check-ignore", "-q", outDir], { cwd });
+    if (result.error)
+        return "unknown"; // git 不存在或無法執行
+    if (result.status === 0)
+        return "ignored";
+    if (result.status === 1)
+        return "not_ignored";
+    return "unknown"; // 其他 exit code：非 git repo（128）等，或路徑不在該 cwd 所屬的工作樹內
+}

package/dist/json-output.js

@@ -0,0 +1,80 @@
+// plan_dispatch_v1.10.md §25：--json 輸出契約。純函式，把 SpokeRunResult／AuditResult
+// 轉成 schema 定義的形狀——不在這裡做任何 I/O，方便不落地任何檔案就單元測試。
+//
+// 原文不進 JSON——維持 §16「stdout 只印摘要，不印原文」，hub 依「先原文、後融合」紀律
+// 自行 Read 落檔。observationCount 保留 number | null（v1.9 §15），序列化時不得降級為 0。
+//
+// plan_dispatch_v1.11.md §25：新增 mode／plan／gitignoreStatus。`plan` 在步驟 6 之後
+// 就已完全確定，三種 mode（dry-run／cancelled／executed）皆有，與是否實際執行無關；
+// `spokes` 維持「執行結果」語意，dry-run／cancelled 時仍是空陣列——這是對的，不要改。
+import { effectiveCap } from "./report.js";
+export function buildJsonPlan(spokes, estimates, allowlistEstimates, cli) {
+    const estByAgent = new Map(estimates.map((e) => [e.agent, e.estimatedTokens]));
+    const allowlistByAgent = new Map(allowlistEstimates.map((e) => [e.agent, e]));
+    return spokes.map((spoke) => ({
+        agent: spoke.agent,
+        provider: spoke.provider,
+        api: spoke.providerConfig.api,
+        modelRequested: spoke.model,
+        effort: spoke.effort,
+        store: spoke.providerConfig.store === false ? "false" : "n/a",
+        estimatedTokens: estByAgent.get(spoke.agent) ?? 0,
+        cap: effectiveCap(spoke, cli),
+        allowlistEstimatedTokens: allowlistByAgent.get(spoke.agent)?.estimatedTokens ?? 0,
+        allowlistFileCount: allowlistByAgent.get(spoke.agent)?.fileCount ?? 0,
+    }));
+}
+export function buildJsonSpoke(result, audit, toolCallAudit) {
+    const allowed = result.toolCalls.filter((t) => t.allowed).length;
+    return {
+        agent: result.agent,
+        provider: result.provider,
+        api: result.api,
+        modelRequested: result.modelRequested,
+        modelReturned: result.modelReturned,
+        effort: result.effort ?? "",
+        store: result.store,
+        status: result.status,
+        budgetTrigger: result.budgetTrigger ?? null,
+        usage: result.usage,
+        costUsd: result.costUsd,
+        latencyMs: result.latencyMs,
+        waitedMs: result.waitedMs,
+        attempts: result.attempts,
+        toolCalls: {
+            total: result.toolCalls.length,
+            allowed,
+            rejected: result.toolCalls.length - allowed,
+        },
+        audit: audit
+            ? {
+                closingLine: audit.finalLinePass,
+                observationCount: audit.observationCount, // number | null 原樣保留，不得降級為 0
+                pathsOutsideAllowlist: audit.citedPathsOutsideAllowlist,
+                hasUnverifiableSection: audit.cannotVerifySectionPresent,
+                suspectMatches: audit.suspectPhrases,
+                zeroSourceRead: toolCallAudit?.zeroSourceRead ?? false,
+            }
+            : {
+                closingLine: false,
+                observationCount: null,
+                pathsOutsideAllowlist: [],
+                hasUnverifiableSection: false,
+                suspectMatches: [],
+                zeroSourceRead: toolCallAudit?.zeroSourceRead ?? false,
+            },
+    };
+}
+export function buildJsonPayload(args) {
+    return {
+        ticketId: args.ticketId,
+        repoRoot: args.repoRoot,
+        outDir: args.outDir,
+        providersSource: args.providersSource,
+        mode: args.mode,
+        plan: args.plan,
+        gitignoreStatus: args.gitignoreStatus,
+        spokes: args.results.map((r) => buildJsonSpoke(r, args.audits.get(r.agent), args.toolCallAudits.get(r.agent))),
+        exitCode: args.exitCode,
+    };
+}

package/dist/mask.js

@@ -0,0 +1,83 @@
+// plan_dispatch_v1.4.md §12：API key 不得出現在任何落檔、stdout 或錯誤訊息中。
+// 遮蔽同時套用於 run.jsonl、raw/*.json 與 stdout 三個出口。刻意不對 error 物件
+// 做 JSON.stringify(error)：SDK 的 error 物件可能帶著 request headers。
+const REDACTED_HEADER_KEYS = new Set([
+    "authorization",
+    "x-api-key",
+    "api-key",
+    "x-goog-api-key",
+]);
+let secretValues = [];
+// 啟動時登錄本次載入的所有金鑰值，逐一從輸出字串中剔除；正則是 sk-/AIza 等已知前綴的兜底，
+// 不倚賴單一機制。
+export function registerSecrets(values) {
+    secretValues = values.filter((v) => Boolean(v && v.length > 0));
+}
+export function maskString(input) {
+    let out = input;
+    for (const secret of secretValues) {
+        out = out.split(secret).join("***REDACTED***");
+    }
+    out = out.replace(/sk-[A-Za-z0-9]{10,}/g, "***REDACTED***");
+    out = out.replace(/ghp_[A-Za-z0-9]{10,}/g, "***REDACTED***");
+    out = out.replace(/AIza[A-Za-z0-9_-]{10,}/g, "***REDACTED***");
+    return out;
+}
+export function maskHeaders(headers) {
+    if (!headers || typeof headers !== "object")
+        return undefined;
+    const out = {};
+    for (const [key, value] of Object.entries(headers)) {
+        out[key] = REDACTED_HEADER_KEYS.has(key.toLowerCase())
+            ? "***REDACTED***"
+            : maskString(String(value));
+    }
+    return out;
+}
+export function maskDeep(value) {
+    if (typeof value === "string")
+        return maskString(value);
+    if (Array.isArray(value))
+        return value.map(maskDeep);
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, maskDeep(v)]));
+    }
+    return value;
+}
+export function describeError(err) {
+    if (err && typeof err === "object") {
+        const anyErr = err;
+        const status = typeof anyErr.status === "number" ? anyErr.status : undefined;
+        const headers = maskHeaders(anyErr.headers);
+        const message = typeof anyErr.message === "string" ? maskString(anyErr.message) : undefined;
+        const errorBody = anyErr.error && typeof anyErr.error === "object"
+            ? { message: maskString(JSON.stringify(anyErr.error)) }
+            : undefined;
+        return {
+            status,
+            is429: status === 429,
+            retryAfterHeader: headers?.["retry-after"] ?? headers?.["Retry-After"] ?? null,
+            message,
+            errorBody,
+            headers,
+        };
+    }
+    return { is429: false, retryAfterHeader: null, message: maskString(String(err)) };
+}
+// 供 adapter 拋出時附掛 status/headers/error（責一致的形狀給 describeError 讀）。
+export class ProviderHttpError extends Error {
+    status;
+    headers;
+    error;
+    request;
+    constructor(message, status, headers, error, 
+    // §13：「raw 帶回導致的 400」須保留該次完整請求供比對，故錯誤本身也帶著它。
+    request) {
+        super(message);
+        this.status = status;
+        this.headers = headers;
+        this.error = error;
+        this.request = request;
+        this.name = "ProviderHttpError";
+    }
+}

package/dist/output.js

@@ -0,0 +1,152 @@
+// plan_dispatch_v1.4.md §12/§16：落檔與 run.jsonl。寫入序列化——前一次 appendFile 未
+// resolve 前不發下一次；呼叫平行，寫入序列。所有落檔內容在寫入前經 maskDeep 遮蔽（§12）。
+import { appendFile, mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { maskDeep, maskString } from "./mask.js";
+export class RunLogWriter {
+    filePath;
+    queue = Promise.resolve();
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    // plan_dispatch_v2.4.md §12（一）：ts 語意為「append 被呼叫的當下」，即事件發生時刻，
+    // 故在此（方法本體）取時間，不得延後到 queue 的 then callback 內——落盤時間會被檔案
+    // 系統阻塞與 queue 排隊污染，失去診斷「哪一輪慢」的價值。ts 於 maskDeep 之後加入，
+    // 避免遮蔽邏輯誤傷時間字串。
+    append(event) {
+        const ts = new Date().toISOString();
+        const masked = maskDeep(event);
+        const line = JSON.stringify({ ...masked, ts }) + "\n";
+        // §12（二）：單次 appendFile 失敗只影響該行，不得毒化 queue——否則其後每一次
+        // append 都不會執行，且 flush() 也會 rejected，等於一次瞬時寫入失敗讓該次派工
+        // 其餘所有事件全部遺失。失敗以 stderr 留痕，不靜默吞掉。
+        this.queue = this.queue.then(() => appendFile(this.filePath, line, "utf8")).catch((err) => {
+            console.error(`run.jsonl 寫入失敗：${maskString(String(err))}`);
+        });
+    }
+    async flush() {
+        await this.queue;
+    }
+}
+export async function ensureOutDir(outDir) {
+    await mkdir(path.join(outDir, "raw"), { recursive: true });
+    // §13：「同一工單重跑會覆蓋同名輸出目錄——刻意行為」。其餘產物（summary.md、
+    // <agent>.md、raw/*.json）走 writeFile 自然覆蓋，唯獨 run.jsonl 走 appendFile
+    // ——§12 的 append 是為**單次執行內**的中斷安全，不是跨次累積。不在此清空的話，
+    // 重跑會把上一次的事件留著，而 toolCalls[] 正是偵測「零讀取」的唯一依據
+    // （issue_log_v2.0.md 2026-08-07：hub 驗收時據此數錯 9／22 vs 實際 7／20）。
+    await writeFile(path.join(outDir, "run.jsonl"), "", "utf8");
+}
+// §13：raw 一律無條件覆寫。v2.4 實作期間曾加過「空 raw 不覆蓋磁碟上的非空內容」守衛
+// （由 v2.4 §20 的一條測試要求逼出來），驗收時撤除：它破壞了 §13「同一工單重跑會覆蓋
+// 同名輸出目錄」——重跑時該 spoke 若零 raw，上一次的內容會留著冒充本次證據，與
+// 21bbd83 修掉的 run.jsonl 污染同型，而 raw/ 是「當時究竟送了什麼出去」的唯一證據。
+// 「防禦性空 result 覆寫已付費內容」那條路徑的保證，由 persistSpokeResult 的
+// 「例外不外傳」單獨承擔——例外不外傳之後，results[i] 永遠是 runSpoke 的真實回傳值。
+export async function writeRawFiles(outDir, agent, result) {
+    await writeFile(path.join(outDir, "raw", `${agent}.request.json`), JSON.stringify(maskDeep(result.rawRequests), null, 2), "utf8");
+    await writeFile(path.join(outDir, "raw", `${agent}.response.json`), JSON.stringify(maskDeep(result.rawResponses), null, 2), "utf8");
+    // plan_fixes_v1.0.md §6：先前失敗時 request/response 兩份都是 []（兩者只記成功輪次），
+    // 中斷或失敗時完全沒有線索。獨立於上面兩份之外——不動既有「僅成功輪次」的語意，
+    // 逐次錯誤（含重試中途、非終局那次）另開一份，空陣列＝未撞過任何錯誤。
+    await writeFile(path.join(outDir, "raw", `${agent}.errors.json`), JSON.stringify(maskDeep(result.rawErrors), null, 2), "utf8");
+}
+// §13：「原文產出」欄——failed 無產出；其餘（含 truncated:*）皆落檔，即使不完整，
+// 因為那是已經付過錢的內容。
+export async function writeSpokeText(outDir, agent, result) {
+    if (result.status === "failed")
+        return;
+    const content = result.finalText ?? `(無法取得完整回報，執行狀態：${result.status})`;
+    await writeFile(path.join(outDir, `${agent}.md`), content, "utf8");
+}
+// plan_dispatch_v2.4.md §13（一）：每支 spoke 完成即落檔的落地點。落檔例外不得外傳——
+// 落檔失敗不得使呼叫端的 promise rejected、不得改變該 spoke 的 status（落檔是產物持久化，
+// 不是執行結果），但必須留下痕跡：寫入 result.errors[] 並經 onError 回報。
+// writeSpokeText、writeRawFiles 各自包住例外，其一失敗不影響另一個執行。
+export async function persistSpokeResult(outDir, result, onError) {
+    try {
+        await writeSpokeText(outDir, result.agent, result);
+    }
+    catch (err) {
+        const msg = `落檔失敗（${result.agent}.md）：${maskString(String(err))}`;
+        result.errors.push(msg);
+        onError(msg);
+    }
+    try {
+        await writeRawFiles(outDir, result.agent, result);
+    }
+    catch (err) {
+        const msg = `落檔失敗（${result.agent} raw/）：${maskString(String(err))}`;
+        result.errors.push(msg);
+        onError(msg);
+    }
+}
+function formatStoreCell(store) {
+    return store === "false" ? "false" : store;
+}
+const BUDGET_TRIGGER_LABEL = {
+    total: "總量",
+    reasoning: "推理累積",
+    reasoning_round: "推理單輪尖峰",
+};
+// §14：truncated:budget 需顯示觸發來源；reasoning_round 是「模型在某一輪卡住」的異常訊號，
+// 與正常的總量／累積推理超支後續動作不同（前者查 prompt 或換 effort，後者調門檻），
+// 須顯眼區分，不能跟其他 truncated:budget 混在一起看起來像同一種情況。
+function formatStatusCell(r) {
+    if (r.status !== "truncated:budget" || !r.budgetTrigger)
+        return r.status;
+    const label = BUDGET_TRIGGER_LABEL[r.budgetTrigger];
+    const flag = r.budgetTrigger === "reasoning_round" ? "⚠ 異常尖峰・" : "";
+    return `${r.status}（${flag}${label}）`;
+}
+// plan_dispatch_v2.0.md §15（二）：清單外引用附出現章節與疑似縮寫來源，讓讀者不必自己去猜
+// （issue_log_v2.0.md 2026-08-07：曾有 hub 因為裸字串誤判成稽核器的 bug，推錯了方向）。
+function formatOutsideAllowlistCell(detail) {
+    if (detail.length === 0)
+        return "無";
+    return detail
+        .map((d) => {
+        const sectionPart = d.section ? `「${d.section}」節` : "章節外";
+        const suffixPart = d.suffixOf ? `；疑似 ${d.suffixOf} 的縮寫` : "";
+        return `${d.path}（${sectionPart}${suffixPart}）`;
+    })
+        .join(",");
+}
+export function buildSummaryMarkdown(ticketId, results, audits, toolCallAudits) {
+    const rows = results.map((r) => {
+        const a = audits.get(r.agent);
+        const t = toolCallAudits.get(r.agent);
+        const cells = [];
+        // plan_dispatch_v2.6.md §26 規格四：hub 會讀的地方才有用（「順序放大量」印進乾跑報表
+        // 後 hub 才真的重排清單，第 10 次派工，省 52%），放最前面顯眼標示。
+        if (r.unknownUsageKeys.length > 0) {
+            cells.push(`⚠ 未知 usage 欄位：${r.provider} ${r.unknownUsageKeys.join(", ")}`);
+        }
+        // §15（一）：沒看程式碼就作答的簽名，放最前面顯眼標示——見 tool-call-audit.ts。
+        if (t?.zeroSourceRead) {
+            cells.push(`⚠ 零原始碼讀取（允許 ${t.allowedReadsCount} 檔）`);
+        }
+        if (t) {
+            cells.push(`工具呼叫:${t.total}（允許 ${t.allowed}／拒絕 ${t.rejected}）`);
+        }
+        if (a) {
+            cells.push(`收尾句:${a.finalLinePass ? "pass" : "fail"}`, `觀察:${a.observationCount ?? "無法計數"}`, // v1.9 §15：null（數不出來）與 0（明確為零）須可區分，不得混印
+            `清單外引用:${formatOutsideAllowlistCell(a.citedPathsOutsideAllowlistDetail)}`, `無法驗證欄:${a.cannotVerifySectionPresent ? "pass" : "fail"}`, `疑似禁止內容:${a.suspectPhrases.length > 0 ? a.suspectPhrases.join(",") : "無"}`);
+        }
+        const auditCell = cells.length > 0 ? cells.join(" / ") : "(無法稽核)";
+        // plan_fixes_v1.0.md §4：無價目資料須與「估出來是 $0」區分，不能印成空白或 0——
+        // 兩者對讀者的意義完全不同（沒資料 vs 免費）。
+        const costCell = r.costUsd === null ? "無價目資料" : `$${r.costUsd.toFixed(4)}`;
+        return `| ${r.agent} | ${r.provider} | ${r.api} | ${r.modelRequested} | ${r.modelReturned ?? "—"} | ${r.effort ?? "—"} | ${formatStoreCell(r.store)} | ${formatStatusCell(r)} | ${r.latencyMs}ms | ${r.usage.totalTokens} | ${costCell} | ${auditCell} |`;
+    });
+    return `# dispatch summary — ${ticketId}
+
+| agent | provider | api | model(請求) | model(回傳) | effort | store | status | 耗時 | token | 估算成本 | 稽核 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+${rows.join("\n")}
+`;
+}
+export async function writeSummary(outDir, ticketId, results, audits, toolCallAudits) {
+    const md = buildSummaryMarkdown(ticketId, results, audits, toolCallAudits);
+    await writeFile(path.join(outDir, "summary.md"), md, "utf8");
+}

package/dist/pkg-info.js

@@ -0,0 +1,35 @@
+// plan_dispatch_v1.10.md §24.2/§24.3：套件出貨資源（providers.json、package.json 的
+// version）皆相對於本檔（`src/pkg-info.ts` 編譯後為 `dist/pkg-info.ts`，與 `dist/cli.js`
+// 同層）以 `import.meta.url` 解析——不假設 cwd，因為 v1 的目標是「從任意目錄執行」。
+//
+// §24.2：`new URL("../providers.json", import.meta.url)` 在 `pnpm link --global` 下
+// 是否解析得到，是規劃書明訂「必須實跑確認」的一步（Node 對 symlink 預設解析 realpath，
+// 但這是推論不是實測）——已實跑驗證通過，見 issue_log 2026-08-06。
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+// package root 相對於本檔的位置：src/pkg-info.ts 與 dist/pkg-info.ts 都在 rootDir 正下方
+// 一層（tsconfig.build.json 的 rootDir:"src" 保證兩者深度一致），故 "../" 恆指向 package root。
+function packageRootURL(relativePath) {
+    return new URL(`../${relativePath}`, import.meta.url);
+}
+export function bundledProvidersPath() {
+    return fileURLToPath(packageRootURL("providers.json"));
+}
+export function getPackageVersion() {
+    const pkgPath = fileURLToPath(packageRootURL("package.json"));
+    const raw = JSON.parse(readFileSync(pkgPath, "utf8"));
+    return raw.version ?? "0.0.0";
+}
+// 指令名同樣取自 package.json，理由與上面一致：這份原始碼會在不同的套件名下出貨，
+// 把名字寫死在說明文字裡，就會出現「--help 教你打 A、實際裝成 B」的落差——而那種落差
+// 不會報錯，只會讓照做的人打不到指令。取 bin 的第一個 key；bin 是字串形式時它等於套件名。
+export function getCommandName() {
+    const pkgPath = fileURLToPath(packageRootURL("package.json"));
+    const raw = JSON.parse(readFileSync(pkgPath, "utf8"));
+    if (raw.bin && typeof raw.bin === "object") {
+        const first = Object.keys(raw.bin)[0];
+        if (first)
+            return first;
+    }
+    return raw.name ?? "cli";
+}

package/dist/prompt.js

@@ -0,0 +1,105 @@
+// plan_dispatch_v1.4.md §8：system prompt 與第一個 user turn 的組裝規格。
+// 三段依序串接：agent body（frontmatter 已由 validate.ts 剝除）＋ 回報模板（dispatch 側維護，
+// 不寫進 agent 檔）＋ 工具說明。
+// plan_dispatch_v2.0.md §16：從源頭消除「清單外引用」噪音——spoke 自行縮寫路徑會被 §15
+// 稽核標記為清單外，即使指的其實是清單內的檔案（issue_log_v2.0.md 2026-08-07 的真實案例）。
+import path from "node:path";
+// 英文工單走這一份。內容與中文版逐條對應——同樣先「觀察／依據／原文」，同樣以固定收尾句
+// 結束，因為稽核靠那句話判斷回報有沒有寫完。翻譯時刻意保留祈使句與「原文是主要依據、
+// 行號是輔助」這兩處措辭：實測顯示 spoke 對句型敏感，描述句會被當成建議略過。
+const REPORT_TEMPLATE_EN = `# Observations
+1. <observation>
+   Evidence: <file:line, or explicit reasoning>
+   Quote: <when citing a file, copy that one line verbatim; write "reasoning" when the evidence is reasoning>
+   —— when citing a file, the path must match the string in "Allowed reads" character for character; do not abbreviate it or write the filename alone.
+   —— **the quote is the primary evidence, the line number is secondary**: the hub locates the
+     real position by matching the quote, so quote verbatim. Copy only the line you are sure
+     of rather than rewriting one from memory.
+
+# Cannot verify
+- <files you needed but could not read, or gaps in the list>; write "none" if there are none
+
+These are observations and questions. Whether to adopt them is for the hub and the user to decide.`;
+const REPORT_TEMPLATE = `# 觀察
+1. <觀察>
+   依據：<檔案:行號 或 明確推理>
+   原文：<引用檔案時，逐字複製該處的一行原文；依據為推理時寫「推理」>
+   ——引用檔案時，路徑須與「允許讀取」清單中的字串逐字相同，不得縮寫或只寫檔名。
+   ——**原文是主要依據，行號是輔助**：hub 會用原文比對出實際位置，所以原文必須逐字，
+     寧可只複製確定的那一行，也不要憑印象重寫。
+
+# 無法驗證
+- <需要但讀不到的檔案，或清單不足之處>；沒有則寫「無」
+
+以上為觀察與問題，採用與否由 hub 與使用者裁決。`;
+// plan_dispatch_v2.1.md §8（二）：工具說明只提「工單」，從未說允許清單的程式碼也要讀——
+// 零讀取的第二個成因（issue_log_v2.0.md 2026-08-07「provider 端完整 log」）。
+const TOOL_NOTE = "你有一個工具 `read_file(path)`。工單與允許讀取的程式碼檔案都不在本 prompt 中，\n須自行讀取；未讀過的檔案不得出現在「依據」中。";
+const TOOL_NOTE_EN = "You have one tool, `read_file(path)`. Neither the ticket nor the code files you are\nallowed to read are in this prompt; read them yourself. A file you have not read must not\nappear in \"Evidence\".";
+// plan_dispatch_v2.1.md §8（二）：組裝順序改為 agent body → 工具說明 → 回報模板。原順序
+// （agent body → 回報模板 → 工具說明）讓工具說明掉在回報模板的固定收尾句之後，在結構上
+// 像附註——而那正是唯一說明「你有工具」的段落（provider log system-1.txt 全文證實）。
+export function buildSystemPrompt(agentBody, lang = "zh") {
+    const toolNote = lang === "en" ? TOOL_NOTE_EN : TOOL_NOTE;
+    const template = lang === "en" ? REPORT_TEMPLATE_EN : REPORT_TEMPLATE;
+    return [agentBody.trim(), toolNote, template].join("\n\n");
+}
+// plan_dispatch_v2.1.md §8（一）：步驟 3 原為「需要時讀取」的條件句、且未列路徑——provider
+// log 顯示模型嚴格照句型行事，命令句（步驟 1、2）會執行、條件句（步驟 3）不會。改為與
+// 步驟 1、2 同句型的命令句，並逐條列出允許清單路徑。綁定條件是「要引用就必須先讀」，不是
+// 「必須讀完整份清單」——清單寧寬勿窄時硬性全讀會浪費 token，且與 §7「被拒呼叫仍計入
+// --max-tool-calls」的成本模型衝突。
+function buildStep3(allowedReadsRelative, lang) {
+    if (allowedReadsRelative.length === 0) {
+        return lang === "en"
+            ? "3. There are no readable files this time; answer from the section under review alone."
+            : "3. 本次無允許讀取檔案，僅依待審段落作答。";
+    }
+    const head = lang === "en"
+        ? "3. read_file each of the files below — any file you intend to cite in \"Evidence\" must be read first:"
+        : "3. 逐一 read_file 下列檔案——凡是要在「依據」中引用的檔案，必須先讀過：";
+    return [head, ...allowedReadsRelative.map((p) => `   - ${p}`)].join("\n");
+}
+// issue_log_v2.1.md：步驟 1、2 給絕對路徑、步驟 3 給相對路徑，spoke 看到兩種格式就會混用
+// ——引用時寫成絕對路徑，稽核便判為「清單外引用」。第 7 次派工 11 筆、第 9 次 7 筆全是這種
+// 噪音，而第 9 次同一欄裡還混著 2 筆「真的沒給檔」，假警報淹沒了真訊號。統一成相對路徑後
+// spoke 全程只看得到一種格式。白名單那側本來就兩種都收（whitelist.ts:37 走
+// path.resolve(repoRoot, requested)），故不需配合修改。
+//
+// 但工單目錄**不保證位於 repoRoot 內**——cli.ts 明文「工單目錄仍相對 cwd 解析，不要求位於
+// repoRoot 內」。在外時轉相對會得到 ../.. 這種更難讀、也更容易被誤用的字串，故維持絕對。
+function displayTicketDir(ticketDir, repoRoot) {
+    if (!repoRoot)
+        return ticketDir;
+    const rel = path.relative(repoRoot, ticketDir);
+    if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel))
+        return ticketDir;
+    return rel;
+}
+export function buildFirstUserText(ticketDir, agent, allowedReadsRelative, repoRoot, lang = "zh") {
+    const dir = displayTicketDir(ticketDir, repoRoot);
+    if (lang === "en") {
+        return `Do these in order:
+1. read_file("${dir}/_shared.md") — the premises and the section under review
+2. read_file("${dir}/${agent}.md") — your questions and your list of readable files
+${buildStep3(allowedReadsRelative, lang)}
+4. Produce your report in the template given in the system prompt
+
+Paths in "Allowed reads" are relative to the repo root, not to the ticket directory.
+Files outside the list are refused. Do not retry a refused file; record what is missing
+under "Cannot verify".`;
+    }
+    return `依序執行：
+1. read_file("${dir}/_shared.md") — 取得前提與待審段落
+2. read_file("${dir}/${agent}.md") — 取得你的具體問題與允許讀取清單
+${buildStep3(allowedReadsRelative, lang)}
+4. 依 system prompt 的回報模板產出
+
+「允許讀取」清單內的路徑相對於 repo 根目錄，不是相對於工單目錄。
+清單外的檔案會被拒絕。被拒時不要重試，在「無法驗證」欄記下缺什麼。`;
+}
+export function buildFinalizeUserText(lang = "zh") {
+    return lang === "en"
+        ? "You have reached the execution limit. Produce your report now from what you already have; do not call any more tools."
+        : "已達執行上限，請依現有資訊直接產出目前的回報，不要再呼叫工具。";
+}