dowafu 0.3.0 → 0.3.2

package/README.md

@@ -39,6 +39,18 @@ npm install -g dowafu
 
 The command is `dowafu`.
 
+## First run
+
+Five steps, in this order. The first three cost nothing.
+
+1. **Install the CLI** — see above. `dowafu --version` should print a version number.
+2. **Copy one language pack into your project** — the commands are under "Driving it from an agent" below. Pick `publish/en/` or `publish/zh-tw/`; never mix the two.
+3. **Ask your agent to run `preflight`** — "run the preflight skill". It reports whether the wiring took, whether the lens definitions are where the CLI expects them, and whether `tmp/` is ignored by git. It reads and reports; it changes nothing.
+4. **Put your keys in place** — see "API keys" below. Only the providers you actually dispatch to need one. Your agent can create the directory and an empty template for you, but **do not paste a key into the conversation**: it stays in that conversation's history. Type the value into the file yourself.
+5. **Check the setup** — `dowafu --doctor`. It prints where the config directory resolved to, whether `.env` is there, which providers have a key (presence only, never the value), the bundled model whitelist, and the lens definitions it found. No API call, no cost, and no ticket required.
+
+Then write a ticket (below) and dry-run it — `dowafu <ticket-dir> --dry-run` is still free. The first thing that costs money is `--yes`.
+
 ## API keys
 
 Keys are read from `$DISPATCH_HOME/.env`, which defaults to `~/.config/dowafu/.env`
@@ -169,6 +181,8 @@ cp "$SRC"/.claude/agents/*.md "$TARGET/.claude/agents/"
 cp "$SRC/workflow_spec.md" "$TARGET/"
 ```
 
+Once the files are in place, have the agent run `preflight` before anything else — it is the check that tells you whether the copy actually took effect in this project's setup.
+
 See `publish/en/README.md` — or `publish/zh-tw/README.md` — for the details, each written
 in its own language.
 

package/dist/adapters/responses.js

@@ -75,7 +75,11 @@ export function createResponsesAdapter(config) {
             catch (err) {
                 if (err && typeof err === "object" && "status" in err) {
                     const anyErr = err;
-                    throw new ProviderHttpError(anyErr.message ?? m(config.lang, "responsesAdapterCallFailed"), anyErr.status ?? 0, anyErr.headers ?? {}, anyErr.error, params);
+                    throw new ProviderHttpError(anyErr.message ?? m(config.lang, "responsesAdapterCallFailed"), 
+                    // 連線層錯誤（APIConnectionError）帶著 status 欄位但值為 undefined，於是落到
+                    // 這個 `?? 0`。**0 是「沒有 HTTP 回應」的哨兵**，`classifyError` 據此判暫時性
+                    // 並重試——改動這裡的預設值之前先看 error-classify.ts 的註解。
+                    anyErr.status ?? 0, anyErr.headers ?? {}, anyErr.error, params);
                 }
                 throw err;
             }

package/dist/audit.js

@@ -2,6 +2,7 @@
 // finalText 與允許讀取清單，吐結構化稽核結果。「疑似」而非「fail」的界線見 §15 說明——
 // 禁止內容關鍵詞必有誤判，故只標記交 hub 判讀，不得自動刪改 spoke 原文。
 import { splitTopLevelSections } from "./ticket.js";
+import { REPORT_PLACEHOLDERS } from "./prompt.js";
 export const FIXED_CLOSING_LINE = "以上為觀察與問題，採用與否由 hub 與使用者裁決。";
 // 英文工單走英文模板，收尾句與章節名也跟著換。稽核**兩套都認**且不看工單語言——spoke
 // 偶爾會用另一種語言作答，那是產出品質的事，不該讓稽核整份判 fail 而蓋掉真正的訊號。
@@ -16,18 +17,38 @@ function getSection(sections, names) {
     }
     return undefined;
 }
-const SUSPECT_PHRASES = ["應該改成", "建議採用", "嚴重度", "高風險", "應廢止"];
-// plan_i18n_v1.2.md §4.1／i18n_classification_t2.md §五 #8-12：英文回報若只比對中文詞，
-// 稽核會靜默失效——不報錯、不變紅，只是什麼都抓不到。兩套並存同時比對，不隨 lang 切換
-// （spoke 可能用另一種語言作答，稽核本來就不看工單語言）。summary.md 需要分開標示是
-// 哪一套命中，供日後調整這份清單時有資料可依據，故 auditSpoke 分開回傳兩個陣列。
-const SUSPECT_PHRASES_EN = ["should be changed to", "recommend adopting", "severity", "high risk", "should be deprecated"];
 // 抓看起來像相對路徑的引用：至少一層目錄＋副檔名，容許前後有反引號與 :行號。
 // 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;
+function countOccurrences(text, needle) {
+    let count = 0;
+    let idx = 0;
+    for (;;) {
+        const found = text.indexOf(needle, idx);
+        if (found === -1)
+            return count;
+        count++;
+        idx = found + needle.length;
+    }
+}
+// external-luna-high-r3 的實際形態：spoke 把 `<觀察>` 當成 XML 標籤，自創 `</觀察>` 收尾。
+// 對每個佔位符一併查它的自創收尾標籤形態，不只查模板原樣的開標籤。
+function countTemplatePlaceholders(finalText) {
+    const hits = [];
+    for (const placeholder of REPORT_PLACEHOLDERS) {
+        const openCount = countOccurrences(finalText, placeholder);
+        if (openCount > 0)
+            hits.push({ placeholder, count: openCount });
+        const closingTag = `</${placeholder.slice(1)}`;
+        const closingCount = countOccurrences(finalText, closingTag);
+        if (closingCount > 0)
+            hits.push({ placeholder: closingTag, count: closingCount });
+    }
+    return hits;
+}
 // plan_dispatch_v1.9.md §15：稽核的職責是記錄，不是規範 spoke 的表達結構。原本只認
 // 範本的平鋪編號（"1. "），deepseek 用「## 問題 N」＋「**觀察 N.N**」的巢狀結構時被判成
 // 0 條——而那次是三份回報中最豐富的一份。放寬為多種常見形式皆計入，依序嘗試、採第一個
@@ -56,35 +77,16 @@ function countObservations(observationsBody) {
     }
     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) {
+// 工單 X1 v1.1 §六（使用者裁示 2026-08-15）：「清單外引用」欄拿掉的是判定，citedPaths 這個
+// 記錄本身保留——它是純資料，不含判斷，供日後「引用 vs 實際讀取」的交叉分析使用。
+export function auditSpoke(finalText) {
     if (!finalText) {
         return {
             finalLinePass: false,
             observationCount: null, // 完全沒有內容可數，不是「數出來是零」
             citedPaths: [],
-            citedPathsOutsideAllowlist: [],
-            citedPathsOutsideAllowlistDetail: [],
             cannotVerifySectionPresent: false,
-            suspectPhrases: [],
-            suspectPhrasesZh: [],
-            suspectPhrasesEn: [],
+            templatePlaceholdersFound: [],
         };
     }
     const lines = finalText.split(/\r?\n/).map((l) => l.trim());
@@ -95,45 +97,12 @@ export function auditSpoke(finalText, allowedRelativePaths) {
     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 suspectPhrasesZh = SUSPECT_PHRASES.filter((phrase) => finalText.includes(phrase));
-    const suspectPhrasesEn = SUSPECT_PHRASES_EN.filter((phrase) => finalText.includes(phrase));
-    const suspectPhrases = [...suspectPhrasesZh, ...suspectPhrasesEn];
-    const citedPathsOutsideAllowlistDetail = citedPathsOutsideAllowlist.map((p) => ({
-        path: p,
-        section: findSection(sections, p),
-        suffixOf: findSuffixSource(p, allowedRelativePaths),
-    }));
+    const templatePlaceholdersFound = countTemplatePlaceholders(finalText);
     return {
         finalLinePass,
         observationCount,
         citedPaths,
-        citedPathsOutsideAllowlist,
-        citedPathsOutsideAllowlistDetail,
         cannotVerifySectionPresent,
-        suspectPhrases,
-        suspectPhrasesZh,
-        suspectPhrasesEn,
+        templatePlaceholdersFound,
     };
 }

package/dist/cli-args.js

@@ -89,6 +89,7 @@ export function parseArgs(argv, lang) {
         return { mode: "version" };
     const options = { ...DEFAULTS };
     let ticketDir;
+    let doctorMode = false;
     const numFlag = (name, apply) => {
         flagHandlers[name] = (v) => {
             const n = Number(v);
@@ -127,6 +128,12 @@ export function parseArgs(argv, lang) {
         else if (arg === "--json") {
             options.json = true;
         }
+        else if (arg === "--doctor") {
+            // 工單 W1 §一之1：與 --help／--version 同一層短路，但要能分辨「多給了 ticket-dir」，
+            // 故不在頂部用 argv.includes() 直接短路，而是隨主迴圈掃完，迴圈後統一判定
+            // （見迴圈後方）——這樣 --doctor 與 --lang 之類的已知旗標仍可同時給、彼此不衝突。
+            doctorMode = true;
+        }
         else if (arg.startsWith("--")) {
             const name = arg.slice(2);
             const handler = flagHandlers[name];
@@ -149,6 +156,14 @@ export function parseArgs(argv, lang) {
             throw new DispatchError(m(lang, "tooManyArgs", arg, ticketDir, helpText), 2);
         }
     }
+    if (doctorMode) {
+        // 工單 W1 §一之1：doctor 不接受也不需要 ticket-dir——多給了（任何 positional）
+        // 就照既有的 tooManyArgs 處理，不悄悄忽略。
+        if (ticketDir !== undefined) {
+            throw new DispatchError(m(lang, "tooManyArgs", ticketDir, "--doctor", helpText), 2);
+        }
+        return { mode: "doctor" };
+    }
     if (!ticketDir) {
         throw new DispatchError(helpText, 2);
     }

package/dist/cli.js

@@ -23,6 +23,7 @@ import { ensureOutDir, outDirHasArtifacts, persistSpokeResult, RunLogWriter, wri
 import { registerSecrets, maskString, maskDeep } from "./mask.js";
 import { SECRET_ENV_VARS } from "./secret-env.js";
 import { resolveDispatchHome, loadDispatchEnv } from "./dispatch-home.js";
+import { buildDoctorReport } from "./doctor.js";
 import { bundledProvidersPath, getPackageVersion, getCommandName } from "./pkg-info.js";
 import { checkGitignore } from "./gitignore-check.js";
 import { buildJsonPayload, buildJsonPlan } from "./json-output.js";
@@ -94,6 +95,23 @@ async function main() {
         console.log(getPackageVersion());
         return;
     }
+    if (parsed.mode === "doctor") {
+        // 工單 W1 §一之2：語言走 messageLang（resolveFallbackLang），不受 --lang 影響——
+        // --doctor 可能正是拿來診斷 --lang／DISPATCH_LANG 本身壞掉的工具。
+        // §一之6：型號白名單走既有的 loadProviders／bundledProvidersPath，載入失敗印失敗原因、
+        // 不中止（doctor 本身 exit 一律 0，見下方 buildDoctorReport 的呼叫沒有任何 throw 路徑）。
+        let providersResult;
+        try {
+            const providers = await loadProviders(bundledProvidersPath(), messageLang);
+            providersResult = { ok: true, providers };
+        }
+        catch (err) {
+            const reason = err instanceof DispatchError ? err.message : maskString(String(err));
+            providersResult = { ok: false, reason };
+        }
+        console.log(buildDoctorReport(messageLang, getCommandName(), providersResult));
+        return;
+    }
     const { ticketDir, options } = parsed;
     const log = makeLogger(options.json);
     // plan_i18n_v1.3.md §二：--lang > DISPATCH_LANG > 內建預設，含九項組合判定
@@ -160,7 +178,13 @@ async function main() {
         exitCode,
     });
     // §10 步驟 7／§11：派工報表
-    const report = buildReport(ticketId, spokes, estimates, allowlistEstimates, options, outDir, { repoRoot, providersSource, gitignoreStatus }, lang);
+    const report = buildReport(ticketId, spokes, estimates, allowlistEstimates, options, outDir, {
+        repoRoot,
+        providersSource,
+        gitignoreStatus,
+        reviewTextChars: ticket.shared.reviewText.length,
+        strayHeadings: ticket.shared.strayHeadings,
+    }, lang);
     log.info(report);
     // 護欄的預告：乾跑不受影響（它不寫任何東西），但先講，免得實跑才發現被擋。
     const outDirDirty = await outDirHasArtifacts(outDir);
@@ -272,10 +296,7 @@ async function main() {
         };
     });
     // §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)];
-    }));
+    const audits = new Map(results.map((r) => [r.agent, auditSpoke(r.finalText)]));
     // plan_dispatch_v2.0.md §15（一）：tool 呼叫是執行資料不是文字，獨立於 auditSpoke 之外判定。
     const toolCallAudits = new Map(results.map((r) => {
         const spoke = spokes.find((sp) => sp.agent === r.agent);

package/dist/doctor.js

@@ -0,0 +1,114 @@
+// 工單 W1（fix_batch_4）§一：`dowafu --doctor`——零素材、零成本的設定自檢。
+//
+// 組字串的純函式，依賴（env／homedir／檔案探針）比照 dispatch-home.ts 的做法以參數注入，
+// 皆有指向真實環境的預設值——cli.ts 只需 `buildDoctorReport(lang, cmd, providersResult)`
+// 就能在正式環境跑，doctor.test.ts 則能整組覆寫、不碰真實家目錄。
+//
+// providers.json 的載入是唯一沒有走這條注入路徑的資料來源：那段是既有的 loadProviders／
+// bundledProvidersPath（async，且已有自己的驗證與錯誤訊息），改由 cli.ts 在呼叫本檔之前
+// 先 await 好、包成 DoctorProvidersResult 傳進來——本檔本體維持同步、純函式。
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { resolveDispatchHome } from "./dispatch-home.js";
+import { SECRET_ENV_VARS } from "./secret-env.js";
+import { PROVIDERS_FORMAT_VERSION } from "./providers.js";
+import { lensClosingLineStatus } from "./report.js";
+import { m } from "./messages.js";
+const DEFAULT_PROBE = {
+    fileExists: (p) => {
+        try {
+            return fs.existsSync(p);
+        }
+        catch {
+            return false;
+        }
+    },
+    readDir: (p) => {
+        try {
+            return fs.readdirSync(p);
+        }
+        catch {
+            return null;
+        }
+    },
+    readFile: (p) => {
+        try {
+            return fs.readFileSync(p, "utf8");
+        }
+        catch {
+            return null;
+        }
+    },
+};
+function buildConfigDirValue(lang, env, dispatchHome) {
+    if (dispatchHome === null)
+        return m(lang, "doctorConfigDirUnresolved");
+    if (env.DISPATCH_HOME)
+        return m(lang, "doctorConfigDirSourceDispatchHome", dispatchHome);
+    if (env.XDG_CONFIG_HOME)
+        return m(lang, "doctorConfigDirSourceXdgConfigHome", dispatchHome);
+    return m(lang, "doctorConfigDirSourceDefault", dispatchHome);
+}
+function buildEnvValue(lang, probe, dispatchHome) {
+    if (dispatchHome === null)
+        return m(lang, "doctorEnvUnresolvedValue");
+    const envPath = path.join(dispatchHome, ".env");
+    return probe.fileExists(envPath) ? m(lang, "doctorEnvPresentValue") : m(lang, "doctorEnvMissingValue", envPath);
+}
+function buildModelListValue(lang, providers) {
+    if (!providers.ok)
+        return m(lang, "doctorModelListLoadFailedValue", providers.reason);
+    const joiner = lang === "zh" ? "、" : ", ";
+    const items = Object.entries(providers.providers)
+        .map(([name, config]) => m(lang, "doctorProviderCountItem", name, config.models.length))
+        .join(joiner);
+    return m(lang, "doctorModelListValue", PROVIDERS_FORMAT_VERSION, items);
+}
+// 工單 X1 v1.1 §三：doctor 不再只認 `hole-finder` 這個名字——只裝 translation-* 一類 lens
+// 的專案先前會被回報 0 個，使用者會誤以為裝錯了。改列出 `.claude/agents/` 底下所有 `.md`，
+// 並依「檔案內文最後一句是不是固定收尾句」分成兩組（判定沿用 report.ts 的
+// lensClosingLineStatus，不在此重寫）。沒有收尾句不是錯誤——`explore-haiku.md` 就是這種。
+function buildLensValue(lang, probe, cwd) {
+    const lensDir = path.join(cwd, ".claude", "agents");
+    const entries = probe.readDir(lensDir);
+    if (entries === null)
+        return m(lang, "doctorLensDirMissingValue", lensDir);
+    const joiner = lang === "zh" ? "、" : ", ";
+    const mdFiles = entries.filter((f) => f.endsWith(".md"));
+    const withClosing = [];
+    const withoutClosing = [];
+    for (const file of mdFiles) {
+        const name = file.slice(0, -".md".length);
+        const content = probe.readFile(path.join(lensDir, file));
+        // 讀不到內容（不存在於這一刻、權限不足…）不得讓整支 doctor 失敗——歸入無收尾句一組。
+        // 取捨：輸出上這與「確實沒有收尾句」分不出來，讀者看到的都是「無收尾句」；工單允許
+        // 「無法判定」或「無收尾句」二選一，這裡選後者，不是宣稱「照實說」出兩者的差異。
+        const status = content !== null ? lensClosingLineStatus(content) : "none";
+        (status === "none" ? withoutClosing : withClosing).push(name);
+    }
+    // 熱修補（2026-08-15）：對「去掉 .md 的名字」排序，不是對檔名排序——'-'(45) < '.'(46)，
+    // 對檔名排序會讓無後綴的 hole-finder.md 排到 hole-finder-cost.md 之後，看起來像被降級。
+    withClosing.sort();
+    withoutClosing.sort();
+    const noClosingSuffix = withoutClosing.length > 0
+        ? m(lang, "doctorLensNoClosingSuffix", withoutClosing.length, withoutClosing.join(joiner))
+        : "";
+    const closingNames = withClosing.length > 0 ? withClosing.join(joiner) : m(lang, "noneLabel");
+    return m(lang, "doctorLensFoundValue", lensDir, mdFiles.length, withClosing.length, closingNames, noClosingSuffix);
+}
+export function buildDoctorReport(lang, cmd, providers, env = process.env, homedir = os.homedir, probe = DEFAULT_PROBE, cwd = process.cwd()) {
+    const dispatchHome = resolveDispatchHome(env, homedir);
+    const apiKeyList = SECRET_ENV_VARS.map((k) => `${k.replace(/_API_KEY$/, "")} ${env[k] ? "✓" : "✗"}`).join("  ");
+    const lines = [
+        m(lang, "doctorHeader", cmd),
+        m(lang, "doctorConfigDirLine", buildConfigDirValue(lang, env, dispatchHome)),
+        m(lang, "doctorEnvLine", buildEnvValue(lang, probe, dispatchHome)),
+        m(lang, "doctorApiKeyLine", apiKeyList),
+        m(lang, "doctorModelListLine", buildModelListValue(lang, providers)),
+        m(lang, "doctorLensLine", buildLensValue(lang, probe, cwd)),
+        "",
+        m(lang, "doctorFooter"),
+    ];
+    return lines.join("\n");
+}

package/dist/error-classify.js

@@ -1,11 +1,20 @@
 // 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…），重試
-// 必然再撞同一個錯，不重試。
+// 暫時性：5xx、408，以及無 HTTP 回應的網路層錯誤（連線重置、DNS 失敗、AbortController
+// 逾時）。確定性：其他 4xx（400 參數錯、401、403、404…），重試必然再撞同一個錯，不重試。
+//
+// **「無 HTTP 回應」有兩種表示法，兩種都要收**：`undefined`（錯誤物件根本沒有 status），
+// 以及 **`0`**——`adapters/responses.ts` 把 OpenAI SDK 的 `APIConnectionError` 正規化成
+// `anyErr.status ?? 0`，而那個 SDK 的連線錯誤**帶著 `status` 這個欄位、值為 undefined**，
+// 所以會走進 `?? 0`。`0` 不是合法的 HTTP status code，拿它當「沒有回應」的哨兵是安全的。
+//
+// v0.3.0 對測（2026-08-13）實地踩到：DeepSeek 連線失敗 → status 0 → 判成 permanent →
+// **`--retries` 一次都沒用上**，四支 spoke 在 1.2–1.5 秒內全部 failed。
+// 本函式的註解原本就寫著網路層錯誤該重試，是 `?? 0` 讓那個意圖失效；測試也只測了
+// `undefined`，剛好漏掉 `0`。
 export function classifyError(status) {
-    if (status === undefined)
+    if (status === undefined || status === 0)
         return "transient";
     if (status >= 500 || status === 408)
         return "transient";

package/dist/json-output.js

@@ -50,17 +50,15 @@ export function buildJsonSpoke(result, audit, toolCallAudit) {
             ? {
                 closingLine: audit.finalLinePass,
                 observationCount: audit.observationCount, // number | null 原樣保留，不得降級為 0
-                pathsOutsideAllowlist: audit.citedPathsOutsideAllowlist,
                 hasUnverifiableSection: audit.cannotVerifySectionPresent,
-                suspectMatches: audit.suspectPhrases,
+                templatePlaceholdersFound: audit.templatePlaceholdersFound,
                 zeroSourceRead: toolCallAudit?.zeroSourceRead ?? false,
             }
             : {
                 closingLine: false,
                 observationCount: null,
-                pathsOutsideAllowlist: [],
                 hasUnverifiableSection: false,
-                suspectMatches: [],
+                templatePlaceholdersFound: [],
                 zeroSourceRead: toolCallAudit?.zeroSourceRead ?? false,
             },
     };

package/dist/messages.js

@@ -45,6 +45,7 @@ const MESSAGES = {
   --max-tool-calls <n>     單一 spoke 的 read_file 呼叫上限，預設 30
   --dry-run                解析、驗證、估算、印報表，不呼叫 API
   --yes                    略過派工確認。非互動環境（stdin 不是 TTY）沒帶就中止
+  --doctor                 印出設定自檢（不呼叫 API、不花錢）後結束（exit 0）
   --help, -h               印本說明後結束（exit 0）
   --version, -V            印版本號後結束（exit 0）`,
         availableLangValues: () => "en、zh-tw、zh",
@@ -72,7 +73,9 @@ const MESSAGES = {
         outDirNotEmptyAbort: (outDir) => `輸出目錄已有產物，未派工、未呼叫任何 API：${outDir}\n` +
             `那是上一次跑出來的東西，覆蓋掉就沒了。兩條路：\n` +
             `  1. 換一個沒用過的 ticket-id 再派（建議，零成本）\n` +
-            `  2. 由使用者自行清掉那個目錄之後重跑——這是他的決定，不是你的`,
+            `  2. 由使用者自行清掉那個目錄之後重跑——這是他的決定，不是你的\n` +
+            `  * 上一次若是失敗收場（summary 全 failed、token 0），那底下沒有花過錢的東西，\n` +
+            `    換 id 或請使用者清掉都行——但仍然由使用者決定要不要清`,
         outDirNotEmptyDryRunWarning: (outDir) => `⚠ 輸出目錄已有產物：${outDir}\n  乾跑不受影響，但實跑會被擋下。換一個 ticket-id 即可。`,
         outDirWritten: (outDir) => `落檔完成：${outDir}/`,
         outDirFallbackStderr: () => "落檔目錄不可寫，完整報告已改印於 stderr：",
@@ -81,6 +84,10 @@ const MESSAGES = {
         blankPlaceholder: () => "(空白)",
         dispatchTableMissingHeader: () => "_dispatch.md 找不到派工表（缺 | agent | ... | 表頭或分隔列）",
         dispatchRowMissingFields: (n, line) => `_dispatch.md 第 ${n} 行缺 agent/provider/model 必填欄位（留白或寫 "default" 視為缺失）：${line}`,
+        duplicateAgentInDispatchTable: (agent, n) => `_dispatch.md 的 agent 欄重複：「${agent}」出現 ${n} 次。未派工、未呼叫任何 API。\n` +
+            `同一份 _dispatch.md 裡一個 agent 只能有一列。兩列同名會兩支都派出去、都計費，\n` +
+            `而 ${agent}.md 與 raw/${agent}.* 由後完成的那支覆蓋先完成的——留下哪一支不可控。\n` +
+            `要用同一個 lens 跑多個型號，拆成多個工單目錄（例如 <ticket-id>-luna、<ticket-id>-ds），各派一次。`,
         dispatchTableEmpty: () => "_dispatch.md 派工表沒有任何資料列",
         strayHeadingsCutReviewSection: (strayNames) => `_shared.md 的「# 待審段落」有標題但內容為空——被後面這些 \`#\` 標題切斷了：` +
             `${strayNames.map((s) => `「# ${s}」`).join("、")}。` +
@@ -125,19 +132,15 @@ const MESSAGES = {
         budgetTriggerLabel: (trigger) => ({ total: "總量", reasoning: "推理累積", reasoning_round: "推理單輪尖峰" })[trigger],
         anomalySpikeFlag: () => "⚠ 異常尖峰・",
         noneLabel: () => "無",
-        outsideAllowlistSection: (section) => `「${section}」節`,
-        outsideAllowlistNoSection: () => "章節外",
-        outsideAllowlistSuffixNote: (suffixOf) => `；疑似 ${suffixOf} 的縮寫`,
-        outsideAllowlistEntry: (path, detail) => `${path}（${detail}）`,
         unknownUsageKeysWarning: (provider, keys) => `⚠ 未知 usage 欄位：${provider} ${keys}`,
         zeroSourceReadWarning: (n) => `⚠ 零原始碼讀取（允許 ${n} 檔）`,
         toolCallStats: (total, allowed, rejected) => `工具呼叫:${total}（允許 ${allowed}／拒絕 ${rejected}）`,
         closingLineCell: (passFail) => `收尾句:${passFail}`,
         observationCountCell: (display) => `觀察:${display}`,
         cannotCountObservations: () => "無法計數",
-        outsideAllowlistCell: (detail) => `清單外引用:${detail}`,
         cannotVerifySectionCell: (passFail) => `無法驗證欄:${passFail}`,
-        suspectPhrasesCell: (detail) => `疑似禁止內容:${detail}`,
+        templatePlaceholderEntry: (placeholder, count) => `${placeholder}×${count}`,
+        templatePlaceholdersCell: (detail) => `佔位符:${detail}`,
         auditUnavailable: () => "(無法稽核)",
         summaryHeader: (ticketId) => `# dispatch summary — ${ticketId}
 
@@ -145,6 +148,10 @@ const MESSAGES = {
 | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |`,
         providersBundled: (formatVersion) => `出貨（formatVersion ${formatVersion}）`,
         providersExplicit: (path, formatVersion) => `外部檔 ${path}（formatVersion ${formatVersion}）`,
+        strayHeadingsWarning: (reviewChars, strayNames) => `  ⚠ _shared.md 的「# 待審段落」只有 ${reviewChars} 字，另有 ${strayNames.length} 個頂層章節：` +
+            `${strayNames.map((s) => `「# ${s}」`).join("、")}` +
+            `——待審段落可能被它們切斷了。工單以 \`#\` 切分區塊，內嵌文件若自帶 \`#\` 標題請降成 \`##\`，` +
+            `或用 \`\`\` 圍籬包起來。確認過是刻意的就忽略本行`,
         gitignoreNotIgnored: (outDir) => `  ⚠ 輸出目錄 ${outDir} 未被輸出目錄所在的 git repo 忽略`,
         gitignoreUnknown: (outDir) => `  ℹ 無法判定輸出目錄 ${outDir} 是否被 .gitignore 涵蓋（非 git repo 或 git 不可用）`,
         aboutToDispatch: (ticketId) => `即將派工 ${ticketId}：`,
@@ -176,6 +183,26 @@ const MESSAGES = {
         rawIntegrityNotArray: () => "raw 完整性檢查失敗：assistant turn 的 raw 不是陣列（responses adapter 預期 raw 為上一輪 response.output 陣列）",
         rawIntegrityItemNotFound: (type) => `raw 完整性檢查失敗：assistant turn 有一個 item（type=${type}）未以原樣出現在送出的請求中，疑似續接時被過濾掉`,
         rawIntegrityObjectNotFound: () => "raw 完整性檢查失敗：assistant turn 的 raw 未以原樣出現在送出的 contents 中，疑似續接時被重建或漏帶",
+        doctorHeader: (cmd) => `${cmd} doctor`,
+        doctorConfigDirLine: (value) => `  設定目錄    ${value}`,
+        doctorConfigDirSourceDispatchHome: (dir) => `${dir}（來源：DISPATCH_HOME）`,
+        doctorConfigDirSourceXdgConfigHome: (dir) => `${dir}（來源：XDG_CONFIG_HOME）`,
+        doctorConfigDirSourceDefault: (dir) => `${dir}（來源：預設；DISPATCH_HOME 與 XDG_CONFIG_HOME 都沒設）`,
+        doctorConfigDirUnresolved: () => "無法解析（沒有 HOME）",
+        doctorEnvLine: (value) => `  .env        ${value}`,
+        doctorEnvPresentValue: () => "有（不讀內容）",
+        doctorEnvMissingValue: (path) => `沒有：${path}`,
+        doctorEnvUnresolvedValue: () => "無法判定（設定目錄無法解析）",
+        doctorApiKeyLine: (value) => `  API key     ${value}（只看有沒有值，不看內容）`,
+        doctorProviderCountItem: (name, count) => `${name} ${count} 個`,
+        doctorModelListLine: (value) => `  型號白名單  ${value}`,
+        doctorModelListValue: (formatVersion, items) => `providers.json formatVersion ${formatVersion}：${items}`,
+        doctorModelListLoadFailedValue: (reason) => `無法載入：${reason}`,
+        doctorLensLine: (value) => `  lens 定義   ${value}`,
+        doctorLensFoundValue: (dirPath, total, closingCount, closingNames, noClosingSuffix) => `${dirPath} 找到 ${total} 個定義檔，其中 ${closingCount} 個具備固定收尾句：\n${" ".repeat(14)}${closingNames}${noClosingSuffix}`,
+        doctorLensNoClosingSuffix: (count, names) => `\n${" ".repeat(14)}（另 ${count} 個無收尾句：${names}）`,
+        doctorLensDirMissingValue: (dirPath) => `目錄不存在：${dirPath}`,
+        doctorFooter: () => "本指令不呼叫任何 API，不會花錢。缺的項目怎麼補，見 README 的〈API keys〉一節。",
     },
     en: {
         unknownOption: (arg, helpText) => `Unknown option: ${arg}\n\n${helpText}`,
@@ -201,6 +228,7 @@ const MESSAGES = {
   --max-tool-calls <n>     Per-spoke read_file call cap, default 30
   --dry-run                Parse, validate, estimate, and print the report only; no API calls
   --yes                    Skip the dispatch confirmation. Aborts in non-interactive environments (stdin not a TTY) unless given
+  --doctor                 Print the configuration self-check (no API call, no cost) and exit (exit 0)
   --help, -h               Print this help and exit (exit 0)
   --version, -V            Print the version and exit (exit 0)`,
         availableLangValues: () => "en, zh-tw, zh",
@@ -226,7 +254,9 @@ const MESSAGES = {
         outDirNotEmptyAbort: (outDir) => `The output directory already holds artifacts. Nothing was dispatched; no API was called: ${outDir}\n` +
             `Those came from a previous run, and overwriting them loses them. Two ways forward:\n` +
             `  1. Pick a ticket-id you have not used and dispatch under that (recommended; it costs nothing)\n` +
-            `  2. Have the user clear that directory themselves, then rerun — that call is theirs, not yours`,
+            `  2. Have the user clear that directory themselves, then rerun — that call is theirs, not yours\n` +
+            `  * If the previous run ended in failure (all failed, zero tokens), nothing under there was\n` +
+            `    paid for — a new id or the user clearing it are both fine, but it is still their call to clear`,
         outDirNotEmptyDryRunWarning: (outDir) => `⚠ The output directory already holds artifacts: ${outDir}\n  The dry run is unaffected, but the real run will be stopped. Pick a different ticket-id.`,
         outDirWritten: (outDir) => `Files written to: ${outDir}/`,
         outDirFallbackStderr: () => "Output directory is not writable; the full report was printed to stderr instead:",
@@ -235,6 +265,12 @@ const MESSAGES = {
         blankPlaceholder: () => "(blank)",
         dispatchTableMissingHeader: () => "_dispatch.md: dispatch table not found (missing | agent | ... | header or separator row)",
         dispatchRowMissingFields: (n, line) => `_dispatch.md line ${n} is missing required field(s) agent/provider/model (blank or "default" counts as missing): ${line}`,
+        duplicateAgentInDispatchTable: (agent, n) => `Duplicate agent in _dispatch.md: "${agent}" appears ${n} times. Nothing was dispatched; no API was called.\n` +
+            `One agent gets one row per _dispatch.md. Two rows with the same name dispatch both spokes and bill for both,\n` +
+            `while ${agent}.md and raw/${agent}.* are overwritten by whichever finishes last — which one survives is not\n` +
+            `under your control.\n` +
+            `To run one lens across several models, split it into separate ticket directories\n` +
+            `(for example <ticket-id>-luna and <ticket-id>-ds) and dispatch each once.`,
         dispatchTableEmpty: () => "_dispatch.md's dispatch table has no data rows",
         strayHeadingsCutReviewSection: (strayNames) => `_shared.md's "# Under review" heading exists but its content is empty — it was cut off by these ` +
             `\`#\` headings that follow: ${strayNames.map((s) => `"# ${s}"`).join(", ")}. ` +
@@ -284,19 +320,15 @@ const MESSAGES = {
         budgetTriggerLabel: (trigger) => ({ total: "total", reasoning: "cumulative reasoning", reasoning_round: "single-round reasoning spike" })[trigger],
         anomalySpikeFlag: () => "⚠ anomalous spike - ",
         noneLabel: () => "none",
-        outsideAllowlistSection: (section) => `the "${section}" section`,
-        outsideAllowlistNoSection: () => "outside any section",
-        outsideAllowlistSuffixNote: (suffixOf) => `; possibly an abbreviation of ${suffixOf}`,
-        outsideAllowlistEntry: (path, detail) => `${path} (${detail})`,
         unknownUsageKeysWarning: (provider, keys) => `⚠ Unknown usage field(s): ${provider} ${keys}`,
         zeroSourceReadWarning: (n) => `⚠ Zero source reads (allowed ${n} file(s))`,
         toolCallStats: (total, allowed, rejected) => `Tool calls:${total} (allowed ${allowed} / rejected ${rejected})`,
         closingLineCell: (passFail) => `Closing line:${passFail}`,
         observationCountCell: (display) => `Observations:${display}`,
         cannotCountObservations: () => "uncountable",
-        outsideAllowlistCell: (detail) => `Citations outside allowlist:${detail}`,
         cannotVerifySectionCell: (passFail) => `Cannot-verify section:${passFail}`,
-        suspectPhrasesCell: (detail) => `Suspect phrases:${detail}`,
+        templatePlaceholderEntry: (placeholder, count) => `${placeholder}×${count}`,
+        templatePlaceholdersCell: (detail) => `Template placeholders:${detail}`,
         auditUnavailable: () => "(audit unavailable)",
         summaryHeader: (ticketId) => `# dispatch summary — ${ticketId}
 
@@ -304,6 +336,10 @@ const MESSAGES = {
 | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |`,
         providersBundled: (formatVersion) => `bundled (formatVersion ${formatVersion})`,
         providersExplicit: (path, formatVersion) => `external file ${path} (formatVersion ${formatVersion})`,
+        strayHeadingsWarning: (reviewChars, strayNames) => `  ⚠ _shared.md's "# Under review" holds only ${reviewChars} characters, and ${strayNames.length} other ` +
+            `top-level heading(s) follow: ${strayNames.map((s) => `"# ${s}"`).join(", ")} — the section under review ` +
+            `may have been cut off by them. The ticket splits into sections by \`#\`; if an embedded document has its ` +
+            `own \`#\` headings, demote them to \`##\` or wrap the block in \`\`\` fences. Ignore this line if it is intended`,
         gitignoreNotIgnored: (outDir) => `  ⚠ Output directory ${outDir} is not ignored by the git repo it lives in`,
         gitignoreUnknown: (outDir) => `  ℹ Cannot determine whether output directory ${outDir} is covered by .gitignore (not a git repo, or git unavailable)`,
         aboutToDispatch: (ticketId) => `About to dispatch ${ticketId}:`,
@@ -335,6 +371,26 @@ const MESSAGES = {
         rawIntegrityNotArray: () => "Raw integrity check failed: assistant turn's raw is not an array (the responses adapter expects raw to be the prior round's response.output array)",
         rawIntegrityItemNotFound: (type) => `Raw integrity check failed: an assistant-turn item (type=${type}) was not found verbatim in the outgoing request — possibly filtered out during continuation`,
         rawIntegrityObjectNotFound: () => "Raw integrity check failed: assistant turn's raw was not found verbatim in the outgoing contents — possibly rebuilt or dropped during continuation",
+        doctorHeader: (cmd) => `${cmd} doctor`,
+        doctorConfigDirLine: (value) => `  Config dir   ${value}`,
+        doctorConfigDirSourceDispatchHome: (dir) => `${dir} (source: DISPATCH_HOME)`,
+        doctorConfigDirSourceXdgConfigHome: (dir) => `${dir} (source: XDG_CONFIG_HOME)`,
+        doctorConfigDirSourceDefault: (dir) => `${dir} (source: default; neither DISPATCH_HOME nor XDG_CONFIG_HOME is set)`,
+        doctorConfigDirUnresolved: () => "could not resolve (no HOME)",
+        doctorEnvLine: (value) => `  .env         ${value}`,
+        doctorEnvPresentValue: () => "present (contents not read)",
+        doctorEnvMissingValue: (path) => `not found: ${path}`,
+        doctorEnvUnresolvedValue: () => "cannot determine (config directory could not resolve)",
+        doctorApiKeyLine: (value) => `  API keys     ${value} (presence only; values are never read)`,
+        doctorProviderCountItem: (name, count) => `${name} ${count}`,
+        doctorModelListLine: (value) => `  Model list   ${value}`,
+        doctorModelListValue: (formatVersion, items) => `providers.json formatVersion ${formatVersion}: ${items}`,
+        doctorModelListLoadFailedValue: (reason) => `failed to load: ${reason}`,
+        doctorLensLine: (value) => `  Lens defs    ${value}`,
+        doctorLensFoundValue: (dirPath, total, closingCount, closingNames, noClosingSuffix) => `${dirPath} holds ${total} definition file(s), ${closingCount} with a fixed closing line:\n${" ".repeat(15)}${closingNames}${noClosingSuffix}`,
+        doctorLensNoClosingSuffix: (count, names) => `\n${" ".repeat(15)}(${count} more without a closing line: ${names})`,
+        doctorLensDirMissingValue: (dirPath) => `directory not found: ${dirPath}`,
+        doctorFooter: () => 'This command calls no API and costs nothing. To fill in what is missing, see "API keys" in the README.',
     },
 };
 export function m(lang, key, ...args) {