dowafu 0.4.0 → 0.5.0

package/dist/doctor.js

@@ -11,8 +11,6 @@ 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 = {
@@ -41,74 +39,136 @@ const DEFAULT_PROBE = {
         }
     },
 };
-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);
+// 工單 key-db §B-3 #6：逐 provider 印出實際生效的是哪一層，不是只印 process.env 的 ✓／✗。
+// keyStatusRows 由 cli.ts 呼叫 provider-key.ts 的 buildKeyStatusRows() 算好傳進來——
+// 本檔維持同步、純函式（見檔頭「providers.json 的載入是唯一沒有走這條注入路徑」的慣例，
+// DB 也一樣不在本檔內讀取）。
+function buildApiKeyValue(lang, rows) {
+    if (rows.length === 0)
+        return m(lang, "doctorApiKeySourceMissing");
+    return rows
+        .map((row) => {
+        const name = row.provider.toUpperCase();
+        const status = row.maskedTail === null
+            ? m(lang, "doctorApiKeySourceMissing")
+            : m(lang, "doctorApiKeySourceDb", row.maskedTail, row.updatedAt ? row.updatedAt.slice(0, 10) : "") +
+                (row.lastTestSucceeded === null || row.lastTestedAt === null || row.lastTestModel === null
+                    ? m(lang, "keyStatusUntested")
+                    : m(lang, row.lastTestSucceeded ? "keyStatusTestSucceeded" : "keyStatusTestFailed", row.lastTestModel, row.lastTestedAt.slice(0, 10)));
+        return m(lang, "doctorApiKeyRow", name, status);
+    })
+        .join("  ");
 }
-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 buildDaemonValue(lang, daemon) {
+    if (daemon?.alive)
+        return m(lang, "doctorDaemonAlive", daemon.pid);
+    return m(lang, "doctorDaemonMissing", daemon?.reason ?? "heartbeat_missing");
 }
-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);
+function buildConfigDirValue(lang, configDir) {
+    if (configDir.source === "unresolved")
+        return m(lang, "doctorConfigDirUnresolved");
+    if (configDir.source === "dispatch_home")
+        return m(lang, "doctorConfigDirSourceDispatchHome", configDir.path);
+    if (configDir.source === "xdg_config_home")
+        return m(lang, "doctorConfigDirSourceXdgConfigHome", configDir.path);
+    return m(lang, "doctorConfigDirSourceDefault", configDir.path);
+}
+// A（gaps #2）：本版根本不讀 `.env`，所以「這個檔不存在」不是一則診斷，是雜訊——它讀起來
+// 像「你少了這個檔」。**只有檔案真的在的時候才印那一行**，措辭沿用既有的「有，但本版不讀取」
+// ——那句對從 0.4.x 升上來、家目錄還躺著舊 `.env` 的人正好是需要的提醒。
+// 回傳 null 代表整行不印（不是印一行「沒有」）。
+function buildModelListValue(lang, models) {
+    if (!models.ok)
+        return m(lang, "doctorModelListLoadFailedValue", models.reason);
+    const name = models.mostExpensive
+        ? `${models.mostExpensive.provider}/${models.mostExpensive.model} ($${models.mostExpensive.outputPerM}/M)`
+        : m(lang, "noneLabel");
+    return m(lang, "doctorModelListValue", models.enabled, models.total, name);
 }
 // 工單 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);
+function buildLensData(probe, cwd) {
+    const dirPath = path.join(cwd, ".claude", "agents");
+    const entries = probe.readDir(dirPath);
     if (entries === null)
-        return m(lang, "doctorLensDirMissingValue", lensDir);
-    const joiner = lang === "zh" ? "、" : ", ";
-    const mdFiles = entries.filter((f) => f.endsWith(".md"));
+        return { found: false, dirPath };
     const withClosing = [];
     const withoutClosing = [];
-    for (const file of mdFiles) {
+    for (const file of entries.filter((f) => f.endsWith(".md"))) {
         const name = file.slice(0, -".md".length);
-        const content = probe.readFile(path.join(lensDir, file));
+        const content = probe.readFile(path.join(dirPath, 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);
+    return { found: true, dirPath, withClosing, withoutClosing };
 }
-export function buildDoctorReport(lang, cmd, providers, env = process.env, homedir = os.homedir, probe = DEFAULT_PROBE, cwd = process.cwd()) {
+function buildLensValue(lang, lenses) {
+    if (!lenses.found)
+        return m(lang, "doctorLensDirMissingValue", lenses.dirPath);
+    const joiner = lang === "zh" ? "、" : ", ";
+    const noClosingSuffix = lenses.withoutClosing.length > 0 ? m(lang, "doctorLensNoClosingSuffix", lenses.withoutClosing.length, lenses.withoutClosing.join(joiner)) : "";
+    const closingNames = lenses.withClosing.length > 0 ? lenses.withClosing.join(joiner) : m(lang, "noneLabel");
+    return m(lang, "doctorLensFoundValue", lenses.dirPath, lenses.withClosing.length + lenses.withoutClosing.length, lenses.withClosing.length, closingNames, noClosingSuffix);
+}
+export function buildDoctorReportData(cmd, providers, env = process.env, homedir = os.homedir, probe = DEFAULT_PROBE, cwd = process.cwd(), daemon, keyStatusRows = [], dbPath) {
     const dispatchHome = resolveDispatchHome(env, homedir);
-    const apiKeyList = SECRET_ENV_VARS.map((k) => `${k.replace(/_API_KEY$/, "")} ${env[k] ? "✓" : "✗"}`).join("  ");
+    const configDir = dispatchHome === null
+        ? { source: "unresolved" }
+        : env.DISPATCH_HOME
+            ? { source: "dispatch_home", path: dispatchHome }
+            : env.XDG_CONFIG_HOME
+                ? { source: "xdg_config_home", path: dispatchHome }
+                : { source: "default", path: dispatchHome };
+    const models = !providers.ok
+        ? { ok: false, reason: providers.reason }
+        : (() => {
+            const enabled = providers.models.filter((model) => model.enabled);
+            const mostExpensive = enabled.filter((model) => model.outputPerM !== undefined).sort((a, b) => (b.outputPerM ?? 0) - (a.outputPerM ?? 0))[0];
+            return {
+                ok: true,
+                enabled: enabled.length,
+                total: providers.models.length,
+                mostExpensive: mostExpensive && mostExpensive.outputPerM !== undefined
+                    ? { provider: mostExpensive.provider, model: mostExpensive.model, outputPerM: mostExpensive.outputPerM }
+                    : null,
+            };
+        })();
+    // cmd remains part of the human presentation header, not a diagnostic observation.
+    void cmd;
+    return {
+        configDir,
+        ...(dbPath ? { dbPath } : {}),
+        envFilePresent: dispatchHome !== null && probe.fileExists(path.join(dispatchHome, ".env")),
+        apiKeys: keyStatusRows.map((row) => ({ ...row })),
+        models,
+        daemon: daemon ?? { alive: false, reason: "heartbeat_missing" },
+        lenses: buildLensData(probe, cwd),
+    };
+}
+export function renderDoctorReport(lang, cmd, data) {
     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, "doctorConfigDirLine", buildConfigDirValue(lang, data.configDir)),
+        // A（gaps #1）：這一行印的是**這次真的會用到的** DB 檔——`--db` 帶了就是它。
+        // 先前 doctor 寫死走預設 DB，於是 `--doctor --db <別的>` 會對著另一個資料庫回答你。
+        ...(data.dbPath ? [m(lang, "doctorDbLine", data.dbPath)] : []),
+        ...(data.envFilePresent ? [m(lang, "doctorEnvLine", m(lang, "doctorEnvPresentValue"))] : []),
+        m(lang, "doctorApiKeyLine", buildApiKeyValue(lang, data.apiKeys)),
+        m(lang, "doctorModelListLine", buildModelListValue(lang, data.models)),
+        m(lang, "doctorDaemonLine", buildDaemonValue(lang, data.daemon)),
+        m(lang, "doctorLensLine", buildLensValue(lang, data.lenses)),
         "",
         m(lang, "doctorFooter"),
     ];
     return lines.join("\n");
 }
+export function buildDoctorReport(lang, cmd, providers, env = process.env, homedir = os.homedir, probe = DEFAULT_PROBE, cwd = process.cwd(), daemon, keyStatusRows = [], dbPath) {
+    return renderDoctorReport(lang, cmd, buildDoctorReportData(cmd, providers, env, homedir, probe, cwd, daemon, keyStatusRows, dbPath));
+}

package/dist/gate.js

@@ -12,12 +12,17 @@ function estimateTokensFromChars(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);
+// D1 consumes captured contents. The small filesystem fallback only keeps the old
+// unit-test helper callable; the CLI always passes DB content and never takes it.
+function compatibilityContent(value) {
+    return fs.existsSync(value) ? fs.readFileSync(value, "utf8") : value;
+}
+export function estimateAllowlistTokens(contents, charsPerToken) {
+    const totalChars = contents.reduce((sum, content) => sum + compatibilityContent(content).length, 0);
     return estimateTokensFromChars(totalChars, charsPerToken);
 }
-export function estimateSequentialRead(filePaths, charsPerToken) {
-    const sizes = filePaths.map((p) => fs.readFileSync(p, "utf8").length);
+export function estimateSequentialRead(contents, charsPerToken) {
+    const sizes = contents.map((content) => compatibilityContent(content).length);
     const amplify = (ordered) => {
         const n = ordered.length;
         const chars = ordered.reduce((sum, s, i) => sum + s * (n - i), 0);

package/dist/job.js

@@ -0,0 +1,97 @@
+import { randomUUID } from "node:crypto";
+import { now } from "./db.js";
+export const JOB_STATUSES = [
+    "pending_approval",
+    "approved",
+    "running",
+    "completed",
+    "failed",
+    "interrupted",
+    "rejected",
+];
+function one(db, sql, ...values) {
+    return db.prepare(sql).get(...values) ?? null;
+}
+export function getJob(db, id) {
+    return one(db, "SELECT * FROM jobs WHERE id = ?", id);
+}
+export function findJobsByIdPrefix(db, prefix) {
+    return db.prepare("SELECT * FROM jobs WHERE id LIKE ? ORDER BY id").all(`${prefix}%`);
+}
+export function listPendingApprovalJobs(db) {
+    return db.prepare("SELECT * FROM jobs WHERE status = 'pending_approval' ORDER BY created_at, id").all();
+}
+export function submitJob(db, ticket, id = randomUUID()) {
+    if (!db.prepare("SELECT 1 FROM tickets WHERE name = ?").get(ticket))
+        throw new Error(`ticket does not exist: ${ticket}`);
+    const createdAt = now();
+    db.prepare("INSERT INTO jobs (id, ticket, status, created_at) VALUES (?, ?, 'pending_approval', ?)").run(id, ticket, createdAt);
+    return getJob(db, id);
+}
+export function approveJob(db, id) {
+    return one(db, `UPDATE jobs
+       SET status = 'approved', approved_at = ?
+     WHERE id = ? AND status = 'pending_approval'
+     RETURNING *`, now(), id);
+}
+export function rejectJob(db, id) {
+    return one(db, `UPDATE jobs
+       SET status = 'rejected', finished_at = ?
+     WHERE id = ? AND status IN ('pending_approval', 'approved')
+     RETURNING *`, now(), id);
+}
+// This is deliberately one guarded UPDATE.  A second daemon can observe the same
+// approved row, but only one can transition it to running and receive it back.
+export function claimNextJob(db) {
+    const claimedAt = now();
+    return one(db, `UPDATE jobs
+       SET status = 'running', claimed_at = ?, heartbeat_at = ?
+     WHERE id = (
+       SELECT id FROM jobs WHERE status = 'approved' ORDER BY created_at, id LIMIT 1
+     ) AND status = 'approved'
+     RETURNING *`, claimedAt, claimedAt);
+}
+export function heartbeatJob(db, id) {
+    db.prepare("UPDATE jobs SET heartbeat_at = ? WHERE id = ? AND status = 'running'").run(now(), id);
+}
+export function finishJob(db, id, result) {
+    const status = result.error ? "failed" : "completed";
+    return one(db, `UPDATE jobs
+       SET status = ?, finished_at = ?, heartbeat_at = NULL, error = ?, cost_usd = ?
+     WHERE id = ? AND status = 'running'
+     RETURNING *`, status, now(), result.error ?? null, result.costUsd, id);
+}
+// A worker can outlive its daemon: it may persist a spoke result after the first reap has
+// marked its job interrupted.  Revisit only a bounded recent window (30 minutes, well over
+// the 15-second stale threshold and normal worker shutdown lag), rather than scanning all
+// historical interrupted jobs every five-second daemon tick.
+export const REAP_INTERRUPTED_LOOKBACK_MS = 30 * 60 * 1_000;
+// `resultCost` stays in daemon.ts because that module owns the result-cost calculation used
+// by normal finishJob too.  This function owns the state transition and asks its caller for
+// that existing calculation only after it finds a real (non-summary) spoke row.
+export function reapInterruptedJobs(db, staleBefore, resultCost, reapedAt = now()) {
+    const revisitAfter = new Date(Date.parse(reapedAt) - REAP_INTERRUPTED_LOOKBACK_MS).toISOString();
+    const candidates = db
+        .prepare(`SELECT id, status FROM jobs
+       WHERE (status = 'running' AND (heartbeat_at IS NULL OR heartbeat_at < ?))
+          OR (status = 'interrupted' AND finished_at >= ?)
+       ORDER BY id`)
+        .all(staleBefore, revisitAfter);
+    const hasResult = db.prepare("SELECT 1 FROM results WHERE job_id = ? AND agent != '__summary__' LIMIT 1");
+    const complete = db.prepare(`UPDATE jobs
+       SET status = 'completed', finished_at = ?, heartbeat_at = NULL, cost_usd = ?
+     WHERE id = ? AND status IN ('running', 'interrupted')`);
+    const interrupt = db.prepare(`UPDATE jobs
+       SET status = 'interrupted', finished_at = ?, heartbeat_at = NULL
+     WHERE id = ? AND status = 'running'`);
+    let changes = 0;
+    for (const job of candidates) {
+        if (hasResult.get(job.id)) {
+            changes += Number(complete.run(reapedAt, resultCost(job.id), job.id).changes);
+        }
+        else if (job.status === "running") {
+            changes += Number(interrupt.run(reapedAt, job.id).changes);
+        }
+    }
+    return changes;
+}

package/dist/liveness.js

@@ -0,0 +1,39 @@
+import fs from "node:fs";
+import { m } from "./messages.js";
+export const DAEMON_STALE_MS = 15_000;
+const DEFAULT_DEPS = {
+    readFile: fs.readFileSync,
+    writeFile: fs.writeFileSync,
+    kill: process.kill.bind(process),
+    now: Date.now,
+};
+export function daemonStatePath(dbPath) {
+    return `${dbPath}.daemon`;
+}
+export function writeHeartbeat(statePath, pid = process.pid, deps = DEFAULT_DEPS) {
+    deps.writeFile(statePath, JSON.stringify({ pid, at: deps.now() }));
+}
+export function daemonAlive(statePath, deps = DEFAULT_DEPS) {
+    let heartbeat;
+    try {
+        heartbeat = JSON.parse(deps.readFile(statePath, "utf8"));
+    }
+    catch {
+        return { alive: false, reason: "heartbeat_missing" };
+    }
+    if (!Number.isInteger(heartbeat.pid) || !Number.isFinite(heartbeat.at))
+        return { alive: false, reason: "heartbeat_missing" };
+    if (deps.now() - heartbeat.at > DAEMON_STALE_MS)
+        return { alive: false, reason: "heartbeat_stale" };
+    try {
+        deps.kill(heartbeat.pid, 0);
+    }
+    catch {
+        return { alive: false, reason: "pid_gone" };
+    }
+    return { alive: true, pid: heartbeat.pid };
+}
+// submit/status callers use this rather than treating an offline queue as success.
+export function daemonWarning(state, lang) {
+    return state.alive ? null : m(lang, "daemonOfflineWarning", state.reason);
+}

package/dist/mcp/http.js

@@ -0,0 +1,178 @@
+// 工單 C §A：daemon 上的 HTTP binding（Streamable HTTP、POST-only、無狀態）。
+// 協定層共用 protocol.ts 的 handleRpc，一行都不重複——HTTP 只是換一個傳輸層把訊息餵進去。
+//
+// 參考實作 tmp/mcp-mvp/http.mjs（128 行，claude.ai 與 Codex 兩個真 client 上跑通過）。
+// 照抄形狀，不照抄品質；C-1 的 body 上限判定時機刻意不同（見下方 onData）。
+import http from "node:http";
+import { findTokenIdForPresented } from "../api-token.js";
+import { createProtocol } from "./protocol.js";
+export const HTTP_PATH = "/mcp";
+export const DEFAULT_HTTP_PORT = 7391;
+export const DEFAULT_MAX_BODY_BYTES = 1_000_000;
+// C-2：計數存行程內記憶體即可（daemon 是單一行程）。刻意取捨——daemon 重啟時計數歸零，
+// 這不是漏洞，是「單人本機工具，重啟後重新累積」的可接受代價，見 report_c.md。
+export const DEFAULT_RATE_LIMIT_WINDOW_MS = 60_000;
+export const DEFAULT_RATE_LIMIT_MAX_REQUESTS = 30;
+// A-2 #12：憑證只記長度，絕不記值，log 與診斷輸出皆然。
+const SECRET_HEADER = /^(x-api-key|x-apikey|authorization|cookie|set-cookie)$/i;
+function headerSummary(headers) {
+    return Object.entries(headers)
+        .map(([key, value]) => (SECRET_HEADER.test(key) ? `${key}=<len:${String(value ?? "").length}>` : `${key}=${JSON.stringify(value)}`))
+        .join(" ");
+}
+// C-2：per-token，不是 per-IP——綁 127.0.0.1 + tunnel 之下所有外部流量的來源 IP 都相同，
+// per-IP 在這個形態下等於沒有。未認證請求（無效 token 或未帶）全部落在同一個 "unauth"
+// 桶，讓「猜 token 的人」本身受限，不因為每次換一個猜測值就重新得到額度。
+export function rateLimitBucketKey(tokenId) {
+    return tokenId ? `token:${tokenId}` : "unauth";
+}
+function createRateLimiter(windowMs, max) {
+    const buckets = new Map();
+    return {
+        check(key, nowMs) {
+            const bucket = buckets.get(key);
+            if (!bucket || nowMs - bucket.windowStart >= windowMs) {
+                buckets.set(key, { count: 1, windowStart: nowMs });
+                return { limited: false, retryAfterSec: 0 };
+            }
+            bucket.count += 1;
+            if (bucket.count > max) {
+                const retryAfterSec = Math.max(1, Math.ceil((bucket.windowStart + windowMs - nowMs) / 1000));
+                return { limited: true, retryAfterSec };
+            }
+            return { limited: false, retryAfterSec: 0 };
+        },
+    };
+}
+function writeJson(res, status, body, extraHeaders = {}) {
+    res.writeHead(status, { "content-type": "application/json", ...extraHeaders });
+    res.end(JSON.stringify(body));
+}
+// 拆成獨立、可單元測試的 request handler（不倚賴真的 socket），createHttpServer 只是把它
+// 接上 http.createServer。F 的多數變異鎖點都靠對這個函式餵假 req/res 驗證，不需要真連線。
+export function createRequestHandler(options) {
+    const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+    const rateLimiter = createRateLimiter(options.rateLimitWindowMs ?? DEFAULT_RATE_LIMIT_WINDOW_MS, options.rateLimitMax ?? DEFAULT_RATE_LIMIT_MAX_REQUESTS);
+    const nowMs = options.now ?? Date.now;
+    const log = options.log ?? ((line) => process.stderr.write(`${line}\n`));
+    const protocol = createProtocol({ db: options.db, dbPath: options.dbPath, lang: options.lang ?? "en" });
+    return (req, res) => {
+        const url = (req.url ?? "").split("?")[0];
+        log(`>>> ${req.method} ${url}  headers: ${headerSummary(req.headers)}`);
+        if (url !== HTTP_PATH) {
+            // 熱修補（票 C 驗收後）：404 原本不印回應行，於是 Codex 那七條 /.well-known/*
+            // 探測在 log 裡只看得到 `>>>` 沒有 `<<<`——看起來像伺服器沒回應，實際是回了 404。
+            // 「沒有紀錄」與「沒有發生」在排查時被讀成同一件事，那正是 igopms G-78。
+            writeJson(res, 404, { error: "not_found" });
+            log(`<<< 404 ${req.method} ${url}`);
+            return;
+        }
+        // A-3 #1：Codex 的 client 開場會送 GET /mcp（想開下行 SSE），拿到 405 之後照樣完成
+        // 握手（facts_mcp.md）。不要「順手」改成支援 SSE 下行。
+        if (req.method !== "POST") {
+            res.writeHead(405, { allow: "POST", "content-type": "application/json" });
+            res.end(JSON.stringify({ error: "method_not_allowed" }));
+            log(`<<< 405 ${req.method}`);
+            return;
+        }
+        // A-2 #4：防護順序固定 auth → accept → body，不可調換。rate limit 綁在 auth 的判定
+        // 結果上（用哪個桶）一併在這裡處理，仍在 accept／body 之前。
+        const presentedRaw = req.headers["x-api-key"];
+        const presented = typeof presentedRaw === "string" ? presentedRaw : undefined;
+        const tokenId = findTokenIdForPresented(options.db, presented);
+        const rl = rateLimiter.check(rateLimitBucketKey(tokenId), nowMs());
+        if (rl.limited) {
+            res.writeHead(429, { "retry-after": String(rl.retryAfterSec), "content-type": "application/json" });
+            res.end(JSON.stringify({ error: "rate_limited", retryAfterSeconds: rl.retryAfterSec }));
+            log(`<<< 429 bucket=${rateLimitBucketKey(tokenId)} retryAfter=${rl.retryAfterSec}s`);
+            return;
+        }
+        if (!tokenId) {
+            // A-3 #3：claude.ai 下拉選單的預設 header 是 x-apikey（少一個連字號）。401 本身不
+            // 提這件事（那是給未認證對象看的），但診斷輸出要點出來，否則使用者看到的 401 沒有線索。
+            const wrongName = req.headers["x-apikey"];
+            const hint = wrongName ? "  hint: received 'x-apikey' (missing the hyphen) — claude.ai's dropdown default header name" : "";
+            log(`    !!! 401 x-api-key=${presented ? `<len:${presented.length}>` : "(none)"}${hint}`);
+            writeJson(res, 401, { error: "unauthorized" });
+            return;
+        }
+        // mcp-handler 也是這樣要求的：少一種型別會 406，而 406 常被 client 呈現成「連不到」
+        // （A-3 #2；igopms G-77/G-78 燒掉整個排查成本的失敗形態）。
+        const accept = String(req.headers.accept ?? "");
+        if (!accept.includes("application/json") || !accept.includes("text/event-stream")) {
+            writeJson(res, 406, { error: "not_acceptable", detail: "Client must accept both application/json and text/event-stream" });
+            log(`<<< 406 accept=${JSON.stringify(accept)}`);
+            return;
+        }
+        // C-1：不照抄 MVP 的判定時機。一超過就 destroy，不要等對方送完——不然這個上限只擋得住
+        // 記憶體，擋不住頻寬與行程時間。
+        let size = 0;
+        const chunks = [];
+        let aborted = false;
+        req.on("data", (chunk) => {
+            if (aborted)
+                return;
+            size += chunk.length;
+            if (size > maxBodyBytes) {
+                aborted = true;
+                writeJson(res, 413, { error: "payload_too_large" });
+                log(`<<< 413 size>${maxBodyBytes}`);
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("error", () => {
+            aborted = true;
+        });
+        req.on("end", () => {
+            if (aborted)
+                return;
+            const raw = Buffer.concat(chunks).toString("utf8");
+            let msg;
+            try {
+                msg = JSON.parse(raw);
+            }
+            catch {
+                writeJson(res, 400, { jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse error" } });
+                return;
+            }
+            // 熱修補（票 C 驗收後）：印出 method 與 id。JSON-RPC 的錯誤是**包在 200 裡**回的，
+            // 所以原本只印 `<<< 200 sse` 等於什麼都沒說——排查 client 問題時最需要知道的
+            // 「它到底叫了什麼、我回了什麼錯」兩項全都看不到。MVP 當初會印整包 body，
+            // 我們沒接過來。這裡只印 method／id／錯誤碼，不印 body：tool 參數可能含工單內容。
+            const call = msg;
+            const method = call && typeof call.method === "string" ? call.method : "(no method)";
+            const callId = call && (typeof call.id === "string" || typeof call.id === "number") ? String(call.id) : "-";
+            log(`    → ${method} (id=${callId})`);
+            // A-1／A-2 #11：同一支 handleRpc，server/discover → -32601 這條也自動涵蓋，HTTP 不
+            // 另外處理。A-2 #10：不帶 mcp-session-id header——這裡從未加過，維持不加。
+            const outcome = protocol.handleRpc(msg, log);
+            if ("none" in outcome) {
+                res.writeHead(202);
+                res.end();
+                log(`<<< 202 (notification) ${method}`);
+                return;
+            }
+            const body = `event: message\ndata: ${JSON.stringify(outcome.response)}\n\n`;
+            res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache" });
+            res.end(body);
+            // 200 但帶 JSON-RPC error：這是「失敗長得像成功」在傳輸層的原形，一定要標出來。
+            const rpcError = outcome.response.error;
+            // 「成功」有三層，前兩層今天都被誤讀過一次：
+            //   HTTP 200        ≠ 成功——JSON-RPC 的 error 包在 200 裡
+            //   JSON-RPC 成功   ≠ 成功——tool 的失敗是 result.isError，不是 JSON-RPC error
+            // 第三層(tool 回的內容對不對)不是 log 該管的，但前兩層必須在這行分得出來。
+            const toolResult = outcome.response.result;
+            if (rpcError)
+                log(`<<< 200 sse  ${method} → JSON-RPC error ${rpcError.code}: ${rpcError.message}`);
+            else if (toolResult?.isError)
+                log(`<<< 200 sse  ${method} → tool isError`);
+            else
+                log(`<<< 200 sse  ${method} ok`);
+        });
+    };
+}
+export function createHttpServer(options) {
+    return http.createServer(createRequestHandler(options));
+}