@kenz1117/dsh-ui-usage-billing 1.5.1 → 1.6.1

package/lib/index.js

@@ -5157,7 +5157,11 @@ async function fetchDeclaredBody(url, raw, apiKey) {
 			if (!response.ok) throw new HttpStatusError("http-error", response.status);
 			const text = await response.text();
 			if (text.length > MAX_BODY_BYTES) throw new HttpStatusError("body-too-large", 413);
-			return JSON.parse(text);
+			try {
+				return JSON.parse(text);
+			} catch (cause) {
+				throw new HttpStatusError("parse-error", 0);
+			}
 		} finally {
 			clearTimeout(timer);
 		}
@@ -5664,6 +5668,38 @@ async function fetchLivePricing() {
 	};
 }
 //#endregion
+//#region lib/types/silent.js
+/**
+* 静默吞错的结构化记录（S-6）：「缺失=未配置」类 catch 的统一出口。
+*
+* 本仓 78 处 server 端 catch 多数是有意的静默（文件缺失=首次运行、凭据未
+* 配置=跳过该 provider），此前唯一载体是注释——用户报「X 不工作」时只能靠
+* 猜。本工具把这些静默升级为**节流的结构化日志**：同 reason 5 分钟最多一条
+* info，宿主日志可 grep `swallowed:`，诊断时看得到「哪个环节吞了什么」，
+* 而又不把已知常态刷成告警噪音。
+*
+* 不取代 console.warn——已知异常需要用户行动的（账本损坏、刷新失败）继续
+* warn；这里只收「确认无害的静默」。节流状态导出重置仅供测试。
+*/
+const THROTTLE_MS = 3e5;
+const lastLoggedAt = /* @__PURE__ */ new Map();
+/**
+* 记录一次有意的静默吞错。
+* @param reason - 稳定的短横线 reason 键（如 `reconcile-ref-missing`），节流以此为粒度。
+* @param error - 可选的原始异常（Error 打 message，其他值原样）。
+*/
+function swallowed(reason, error) {
+	const now = Date.now();
+	const last = lastLoggedAt.get(reason);
+	if (last !== void 0 && now - last < THROTTLE_MS) return;
+	lastLoggedAt.set(reason, now);
+	if (error === void 0) {
+		console.info(`[usage-billing] swallowed: ${reason}`);
+		return;
+	}
+	console.info(`[usage-billing] swallowed: ${reason}`, error instanceof Error ? error.message : error);
+}
+//#endregion
 //#region lib/types/subscriptions.js
 /**
 * Subscription-plan quota polling (node half): how much of each coding/token
@@ -6063,7 +6099,9 @@ async function collectZai(keys, config, timeoutMs) {
 		try {
 			subscription = await requestJson(`${host}/api/biz/subscription/list`, init, timeoutMs);
 			if (zaiEnvelopeStatus(subscription) !== void 0) subscription = null;
-		} catch {}
+		} catch {
+			swallowed("zai-plan-metadata-missing");
+		}
 		const parsed = parseZai(quota, subscription);
 		return {
 			provider: config.provider,
@@ -6831,36 +6869,17 @@ async function queryRelayQuotas(ctx, routes) {
 	return await Promise.all(routes.map(async (route) => queryRelayQuota(ctx, route)));
 }
 //#endregion
-//#region lib/types/client/usage-billing-settings.js
+//#region lib/types/guard.js
 /**
-* usage-stats 工具开关的共享设置契约（node 与 client 两端共用）。
+* 共享 loopback 守卫（v1.5.2 抽自 src/index.ts）。
 *
-* 旧宿主（≤0.1.6）把该开关存设置命名空间；宿主 0.1.7+ 起注册面移除，改存插件
-* 条目 config 的 volatile 字段（Config schema 投影），写回经 settings.update，
-* 提交后引用原位更新、`usage_stats` 工具即时注册/注销（无需重载应用）。
-* client 半区在「设置」Tab 渲染开关并经 /api/billing/usage-tool 写入，node 半区
-* 按宿主世代选择通道。缺省的默认行为是关闭——避免该工具默认占用模型每次请求
-* 的上下文（coding 场景通常在仪表盘看用量）。
-*/
-/** 设置命名空间 id（小写 kebab-case）。 */
-const BILLING_SETTINGS_NAMESPACE = "ui-usage-billing";
-/** 该命名空间下用户可编辑的字段名。 */
-const ENABLE_USAGE_STATS_TOOL_FIELD = "enableUsageStatsTool";
-//#endregion
-//#region lib/types/index.js
-/**
-* Usage billing surface plugin, node half.
+* 端点只供本机浏览器用，局域网/远端请求一律拒绝，避免面板数据（含中转站
+* origin 与余额）外泄。三层防御：peer socket（最可信）+ Host 头精确字面量
+* （防 `127.0.0.1.evil.com` 这类 DNS rebinding 域名）+ trustedHosts 白名单
+* （反向代理场景的精确主机名放行）。Origin 头独立校验（写操作用）。
 *
-* Serves `/api/billing/usage-stats`: real usage aggregated from every
-* persisted session log (see `aggregate.ts`) — the browser dashboard reads it
-* instead of showing an empty snapshot. Aggregation is stale-while-revalidate:
-* requests get a short wait budget and fall back to the freshest persisted
-* snapshot while a slow full fold keeps running in the background (a heavy
-* user's first fold takes minutes and must not starve the single-process
-* host's RPC). When `sessionPersistence` is unavailable (or aggregation
-* fails), the configured `statsPath` / `DSH_USAGE_STATS` / conventional JSON
-* file is served as a fallback, and a missing file answers `{ error }` so the
-* dashboard shows zeros, never fabricated samples.
+* 设计要点：精确字面量匹配（`startsWith('127.')` 会被 `127.0.0.1.evil.com`
+* 穿透，必须正则）。IPv6 字面量带方括号（`[::1]:3080`）单独剥离。
 */
 /** Peer 地址是否为回环（本地）。回环防护：本插件的端点只供本机浏览器用，
 *  局域网/远端请求一律拒绝，避免面板数据（含中转站 origin 与余额）外泄。 */
@@ -6896,6 +6915,9 @@ function normalizeTrustedHosts(hosts) {
 	const names = hosts.filter((host) => typeof host === "string").map((host) => hostNameOf(host)).filter((host) => host !== "");
 	return new Set(names);
 }
+/** 校验 Host 头是本机回环（精确 127.0.0.0/8 / ::1 / localhost 或空，供 curl 不带 Host 的极简请求）。
+*  拒绝 `127.0.0.1.attacker.com` 这类以 `127.` 开头但解析到外部的 DNS rebinding 域名：
+*  只用 `startsWith('127.')` 会被它穿透，必须精确匹配回环 IP 的字面量。 */
 function isLoopbackHost(req, trustedHosts = /* @__PURE__ */ new Set()) {
 	const host = req.headers.host;
 	if (host === void 0 || host === "") return true;
@@ -6936,144 +6958,627 @@ function guardLoopback(req, res, trustedHosts = /* @__PURE__ */ new Set()) {
 	}
 	return true;
 }
+//#endregion
+//#region lib/types/routes/notify-claim.js
 /**
-* 设置命名空间校验（上游 alpha.1 `settingsNamespace` 的本地化，issue #28）：
-* alpha.2 起该函数不再从 `@deepseek-ai/dsh-settings` 导出，但上游内部保留
-* 同一 pattern——本地按同一规则校验，预览宿主 API 漂移不再影响插件装载。
-*/
-const SETTINGS_NAMESPACE_PATTERN = /^[a-z][a-z0-9-]*$/;
-/** 校验并透过合法命名空间 id；非法值 fail-loud（与上游原行为一致）。 */
-function validateSettingsNamespace(value) {
-	if (!SETTINGS_NAMESPACE_PATTERN.test(value)) throw new TypeError(`settings namespace "${value}" must match ${String(SETTINGS_NAMESPACE_PATTERN)}`);
-	return value;
+* 路由：POST /api/billing/notify-claim
+*
+* 跨实例提醒认领（issue #44）：多实例（CLI + 桌面等）合法共存，各自轮询
+* 会重复弹通知。两级去重——进程内 Set 挡同进程的并发/重渲染（trigger 与仪表盘
+* 是两个组件实例，effect 同周期并发时本地 store 标记读到的还是旧值）；跨进程走
+* 认领端点（先到先得），另一实例刚发过则跳过。端点不可达（旧版本/网络故障）
+* 时放行，退化为原有 per-客户端去重。通知构造失败（平台限制）静默。
+*
+* 路由文件职责：handler + 模块级 `notifyClaims` 单例（与 `loadNotifications`
+* 共享内存状态——先到先得认领）。文件持久化（`writeFileAtomic`）由 index.ts 装配
+* 器通过 `claimsPath` 注入；handler 拿到路径后自行管理读写。
+*/
+/** 模块级认领表：loaded 表示是否已从磁盘反序列化；keys 是先到先得序。 */
+const notifyClaims = {
+	loaded: false,
+	keys: []
+};
+/** 注册路由到 cordis webServer effect；handler 闭包外只读 deps。 */
+function registerNotifyClaimRoute(ctx, deps) {
+	ctx.effect(() => ctx.webServer.register({
+		kind: "exact",
+		path: "/api/billing/notify-claim",
+		handler: async (req, res) => {
+			if (!guardLoopback(req, res, deps.trustedHosts)) return;
+			if (req.method !== "POST") {
+				res.writeHead(405, { "content-type": "application/json; charset=utf-8" });
+				res.end(JSON.stringify({ error: "method not allowed" }));
+				return;
+			}
+			if (!isLoopbackOrigin(req.headers.origin) || !(req.headers["content-type"] ?? "").toLowerCase().includes("application/json")) {
+				res.writeHead(403, { "content-type": "application/json; charset=utf-8" });
+				res.end(JSON.stringify({ error: "forbidden: loopback only" }));
+				return;
+			}
+			try {
+				let body = "";
+				for await (const chunk of req) {
+					body += String(chunk);
+					if (body.length > 2048) {
+						res.writeHead(413, { "content-type": "application/json; charset=utf-8" });
+						res.end(JSON.stringify({ error: "body too large" }));
+						return;
+					}
+				}
+				const parsed = JSON.parse(body === "" ? "{}" : body);
+				if (typeof parsed.key !== "string" || parsed.key === "" || parsed.key.length > 200) {
+					res.writeHead(400, { "content-type": "application/json; charset=utf-8" });
+					res.end(JSON.stringify({ error: "invalid key" }));
+					return;
+				}
+				if (!notifyClaims.loaded) {
+					notifyClaims.loaded = true;
+					try {
+						const stored = JSON.parse(await readFile(deps.claimsPath, "utf8"));
+						if (Array.isArray(stored.keys)) notifyClaims.keys = stored.keys.filter((k) => typeof k === "string");
+					} catch {
+						swallowed("notify-claims-file-unreadable");
+					}
+				}
+				if (notifyClaims.keys.includes(parsed.key)) {
+					res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+					res.end(JSON.stringify({ claimed: false }));
+					return;
+				}
+				notifyClaims.keys.push(parsed.key);
+				if (notifyClaims.keys.length > 400) notifyClaims.keys = notifyClaims.keys.slice(-200);
+				writeFileAtomic(deps.claimsPath, JSON.stringify({ keys: notifyClaims.keys }), {
+					mode: 384,
+					dirMode: 448
+				}).catch(() => {});
+				res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+				res.end(JSON.stringify({ claimed: true }));
+			} catch {
+				res.writeHead(400, { "content-type": "application/json; charset=utf-8" });
+				res.end(JSON.stringify({ error: "invalid" }));
+			}
+		}
+	}), "usage-billing: notify-claim route");
 }
-/** usage_stats 工具开关的设置命名空间 id（下端与 node 共用同一常量）。 */
-const usageBillingSettingsNs = validateSettingsNamespace(BILLING_SETTINGS_NAMESPACE);
-/** 该命名空间的 wire schema：`enableUsageStatsTool` 布尔，默认关闭（issue 诉求）。 */
-const UsageBillingSettingsSchema = z.object({ [ENABLE_USAGE_STATS_TOOL_FIELD]: z.boolean().default(false) });
-/**
-* Loader 挂载时对条目 config 做校验的 Config 声明：`enableUsageStatsTool` 标记
-* volatile，宿主 0.1.7+ 设置系统据此把它投影为可实时编辑的开关（describe/update）。
-* schemastery 非严格 object 透传未声明键，其余 config 字段不受影响；未导出 Config
-* 的旧宿主直接把原始 config 交给 apply，普通布尔形态由读取端兼容。
-*/
-const Config = z.object({ [ENABLE_USAGE_STATS_TOOL_FIELD]: z.boolean().default(false).volatile() });
-/** 实时定价的后台刷新间隔（毫秒）：汇率/模型价低频变化，6 小时一次足够。 */
-const PRICING_REFRESH_INTERVAL_MS = 216e5;
-/** 历史回放预热的延迟：等宿主启动高峰（插件加载 / 路由挂载）过去再全量折叠，
-*  避免抢启动期的 CPU；纯延迟不阻塞任何请求，面板提前打开也只会提前聚合。 */
-const WARMUP_DELAY_MS = 3e3;
-/** 订阅套餐额度缓存时长（毫秒）：上游配额 API 低频变化，5 分钟足够。 */
-const SUBSCRIPTION_CACHE_MS = 3e5;
-const BALANCE_CACHE_MS = 3e5;
-/** DeepSeek 余额查询的默认凭据引用（与 llm-deepseek 的默认引用一致）。 */
-const DEFAULT_BALANCE_API_KEY_ENV = "DEEPSEEK_API_KEY";
-/**
-* 本插件版本号：从包自身的 package.json 读取（单一来源），随 usage-stats
-* 下发，供「设置 → 插件信息卡」展示。发布版 lib/index.js 相对包根解析。
-*/
-const PACKAGE_VERSION = createRequire(import.meta.url)("../package.json").version ?? "0.0.0";
-/** 统计快照的落盘节流（毫秒）：快照只服务聚合失败回退与重启首屏（展示级
-*  新鲜度即可），降到 5 分钟一次——原子写含上一版备份是两次全量 JSON 落盘，
-*  重度用户快照上百 KB，跟随前端轮询 30 秒写一次纯属写放大。 */
-const SNAPSHOT_INTERVAL_MS = 3e5;
-/** usage-stats 响应的等待预算（毫秒）：聚合在此预算内完成就回实时数据，
-*  超预算立即回最近快照（stale-while-revalidate），后台折叠继续跑。
-*  轻量用户暖缓存下的聚合是毫秒级，预算几乎不会触发。 */
-const RESPONSE_BUDGET_MS = 1500;
-/** 鉴权失败告警冷却（毫秒）：同一 provider 在窗口内只提示一次，避免 30 秒轮询刷屏。 */
-const AUTH_WARN_COOLDOWN_MS = 18e5;
+//#endregion
+//#region lib/types/routes/pricing.js
 /**
-* 鉴权失败分类告警（P1-5）：余额 / 订阅查询返回 unauthorized 时，按
-* `source:provider` 去重并冷却告警，提示检查 llm-pi-ai 里该 provider 的 apiKeyEnv。
+* 路由：GET /api/billing/pricing + POST /api/billing/pricing/refresh
+*
+* 实时定价（汇率 + OpenRouter 模型价 + models.dev 目录外补充）的 GET/POST 同
+* concern，合一个文件：
+* - GET 由前端 30s 轮询 + 弹窗初始拉取触发，返回完整价目表文档（live + 内置
+*   目录 + 别名表 + syncedAt）。
+* - POST 是费率条「立即同步」按钮触发，强制服务端重新拉取一次；写操作额外
+*   校验 Origin 与 Content-Type。
+*
+* 路由文件只关心 HTTP 层：响应体序列化与缓存（pricingBodyCache）由 index.ts
+* 装配器通过 `body()` 闭包注入；服务端重拉逻辑（refreshPricing + 价格目录代际
+* 变化触发 reprice）也在装配器里，路由只通过 `refresh()` 触发。
 */
-const authWarnedAt = /* @__PURE__ */ new Map();
-function warnAuthOnce(source, provider, displayName) {
-	const key = `${source}:${provider}`;
-	const now = Date.now();
-	const last = authWarnedAt.get(key);
-	if (last !== void 0 && now - last < AUTH_WARN_COOLDOWN_MS) return;
-	authWarnedAt.set(key, now);
-	console.warn(`[usage-billing] ${displayName}（${provider}）鉴权失败：请检查 llm-pi-ai 设置中该 provider 的凭据环境变量是否正确/有效。`);
+/** GET /api/billing/pricing。 */
+function registerGetRoute(ctx, deps) {
+	ctx.effect(() => ctx.webServer.register({
+		kind: "exact",
+		path: "/api/billing/pricing",
+		handler: async (req, res) => {
+			if (!guardLoopback(req, res, deps.trustedHosts)) return;
+			res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+			res.end(deps.body());
+		}
+	}), "usage-billing: pricing route");
 }
-/** 锁等待上限：账本提交是毫秒级 read-render-commit，2s 已数倍于正常持锁时长。 */
-const LEDGER_LOCK_WAIT_MS = 2e3;
-/**
-* 锁年龄超过该值判为崩溃残留的孤儿锁。正常持锁是毫秒级文件提交，没有活跃
-* writer 会合法持有 60s；库层刻意不做年龄判定（它无法假设调用方的操作时长），
-* 本调用方知道自己操作的上界，可以给出有依据的清理阈值。
-*/
-const STALE_LEDGER_LOCK_MS = 6e4;
-/**
-* 锁等待超时后的孤儿锁自愈（issue #48）：仅当锁文件年龄超过
-* STALE_LEDGER_LOCK_MS 才清理，避免误删慢 writer 的活跃锁。
-* @param ledgerPath - 账本文件路径（锁为其 `.lock` 兄弟文件）。
-* @returns 是否清理了孤儿锁；false = 锁已消失或太新鲜，调用方上抛原错误。
-*/
-async function reclaimStaleLedgerLock(ledgerPath) {
-	let ageMs;
-	try {
-		ageMs = Date.now() - (await lstat(`${ledgerPath}.lock`)).mtimeMs;
-	} catch {
-		return false;
-	}
-	if (ageMs < STALE_LEDGER_LOCK_MS) return false;
-	console.warn(`[usage-billing] 账本锁已存在 ${Math.round(ageMs / 1e3)}s（崩溃残留），清理后重试：${ledgerPath}.lock`);
-	await rm(`${ledgerPath}.lock`, { force: true });
-	return true;
+/** POST /api/billing/pricing/refresh。 */
+function registerRefreshRoute(ctx, deps) {
+	ctx.effect(() => ctx.webServer.register({
+		kind: "exact",
+		path: "/api/billing/pricing/refresh",
+		handler: async (req, res) => {
+			if (!guardLoopback(req, res, deps.trustedHosts)) return;
+			if (req.method !== "POST") {
+				res.writeHead(405, { "content-type": "application/json; charset=utf-8" });
+				res.end(JSON.stringify({ error: "method not allowed" }));
+				return;
+			}
+			if (!isLoopbackOrigin(req.headers.origin)) {
+				res.writeHead(403, { "content-type": "application/json; charset=utf-8" });
+				res.end(JSON.stringify({ error: "forbidden: loopback only" }));
+				return;
+			}
+			if (!(req.headers["content-type"] ?? "").toLowerCase().includes("application/json")) {
+				res.writeHead(415, { "content-type": "application/json; charset=utf-8" });
+				res.end(JSON.stringify({ error: "unsupported content-type" }));
+				return;
+			}
+			await deps.refresh();
+			res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+			res.end(deps.body());
+		}
+	}), "usage-billing: pricing refresh route");
+}
+/** 一次性注册两条同 concern 路由。 */
+function registerPricingRoutes(ctx, deps) {
+	registerGetRoute(ctx, deps);
+	registerRefreshRoute(ctx, deps);
 }
+//#endregion
+//#region lib/types/routes/balance.js
 /**
-* Create the atomic file-backed durable-ledger store. The previous complete file
-* is retained as `.bak`; a malformed/missing main file falls back to that backup.
+* 路由：GET /api/billing/balance
+*
+* 多平台余额（DeepSeek / Kimi / StepFun / SiliconFlow / xAI / 智谱 / 腾讯云
+* TokenHub 等）+ 用户自定义余额 + 声明端点 + 余额差对账。5 分钟缓存（避免
+* 每 30s 后台轮询打上游），in-flight 去重（并发请求共享同一次进行中的刷新）。
+*
+* 路由文件只关心 HTTP 缓存逻辑：5 分钟过期判定 + 失败时仍发旧缓存（不挂起
+* 已 writeHead 的响应）。上游查询（queryBalances / queryCustomBalances /
+* queryDeclaredEndpoints / reconcileBalanceDelta）在装配器里跑，路由只通过
+* `cached()` 与 `refreshOnce()` 拿到结果。
 */
-function createFileUsageLedgerStore(ledgerPath) {
-	return {
-		async load() {
-			for (const path of [ledgerPath, `${ledgerPath}.bak`]) try {
-				const parsed = JSON.parse(await readFile(path, "utf8"));
-				if (parsed !== null && typeof parsed === "object") {
-					const candidate = parsed;
-					if (candidate.version === 1 && Array.isArray(candidate.sessions)) return parsed;
-				}
-			} catch {}
-		},
-		async save(document) {
-			await mkdir(dirname(ledgerPath), {
-				recursive: true,
-				mode: 448
-			});
-			const commit = async () => {
-				let existing;
-				let existingDoc;
-				try {
-					existing = await readFile(ledgerPath, "utf8");
-					const parsed = JSON.parse(existing);
-					if (parsed.version === 1 && Array.isArray(parsed.sessions)) existingDoc = parsed;
-				} catch {
-					existing = void 0;
-				}
-				if (existing !== void 0) await writeFileAtomic(`${ledgerPath}.bak`, existing, {
-					mode: 384,
-					dirMode: 448
-				});
-				const merged = existingDoc === void 0 ? document : mergeUsageLedgerDocuments(document, existingDoc);
-				await writeFileAtomic(ledgerPath, JSON.stringify(merged), {
-					mode: 384,
-					dirMode: 448
-				});
-			};
+function registerBalanceRoute(ctx, deps) {
+	ctx.effect(() => ctx.webServer.register({
+		kind: "exact",
+		path: "/api/billing/balance",
+		handler: async (req, res) => {
+			if (!guardLoopback(req, res, deps.trustedHosts)) return;
+			res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+			if (Date.now() - deps.cached().at < deps.cacheMs) {
+				res.end(JSON.stringify(deps.cached().doc));
+				return;
+			}
 			try {
-				await withFileLock(ledgerPath, commit, { waitMs: LEDGER_LOCK_WAIT_MS });
+				await deps.refreshOnce();
 			} catch (error) {
-				if (!(error instanceof Error) || !error.message.includes("timed out waiting for the writer lock")) throw error;
-				if (!await reclaimStaleLedgerLock(ledgerPath)) throw error;
-				await withFileLock(ledgerPath, commit, { waitMs: LEDGER_LOCK_WAIT_MS });
+				console.warn("[usage-billing] refreshBalances failed; serving cached balances:", error);
 			}
+			res.end(JSON.stringify(deps.cached().doc));
 		}
-	};
+	}), "usage-billing: balance route");
 }
-/** Required services: the web server, the persisted session log store, and user settings. */
-const inject = [
+//#endregion
+//#region lib/types/routes/usage-tool.js
+/**
+* 路由：GET/POST /api/billing/usage-tool
+*
+* usage_stats 工具开关：插件自带的读/写接口（不依赖宿主浏览器设置白名单）。
+* GET 返回当前是否注入；POST 写设置命名空间（重启应用后工具注入随新值生效）。
+*
+* 双世代宿主（issue #19 + #28 + v1.4.19）的接线在装配器里完成：
+* - 旧宿主 ≤0.1.6 走 `settings.register` 命名空间 scope。
+* - 宿主 0.1.7+ 注册面已移除，走 volatile config 投影。
+* 装配器提供 `read` / `write` 闭包，路由文件不感知双世代——`read()` 已内部分支
+* （scope 存在时读 scope，否则读 volatile + config base），`write(next)` 同理。
+* 工具注入由装配器的 `syncUsageTool` 驱动：写回后路由通过 `syncTool()` 显式调用一次
+* （幂等），覆盖「写回成功但引用未即时可见」的组合（测试替身不提交）。
+*/
+function registerUsageToolRoute(ctx, deps) {
+	ctx.effect(() => ctx.webServer.register({
+		kind: "exact",
+		path: "/api/billing/usage-tool",
+		handler: async (req, res) => {
+			if (!guardLoopback(req, res, deps.trustedHosts)) return;
+			if (req.method !== "GET" && req.method !== "POST") {
+				res.writeHead(405, { "content-type": "application/json; charset=utf-8" });
+				res.end(JSON.stringify({ error: "method not allowed" }));
+				return;
+			}
+			if (req.method === "POST") {
+				if (!isLoopbackOrigin(req.headers.origin)) {
+					res.writeHead(403, { "content-type": "application/json; charset=utf-8" });
+					res.end(JSON.stringify({ error: "forbidden: loopback only" }));
+					return;
+				}
+				if (!(req.headers["content-type"] ?? "").toLowerCase().includes("application/json")) {
+					res.writeHead(415, { "content-type": "application/json; charset=utf-8" });
+					res.end(JSON.stringify({ error: "unsupported content-type" }));
+					return;
+				}
+			}
+			res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+			if (req.method === "GET") {
+				res.end(JSON.stringify({ enabled: deps.read() }));
+				return;
+			}
+			try {
+				let body = "";
+				for await (const chunk of req) {
+					body += String(chunk);
+					if (body.length > 512) {
+						res.writeHead(413, { "content-type": "application/json; charset=utf-8" });
+						res.end(JSON.stringify({ error: "body too large" }));
+						return;
+					}
+				}
+				const next = JSON.parse(body === "" ? "{}" : body).enabled === true;
+				await deps.write(next);
+				deps.syncTool();
+				res.end(JSON.stringify({
+					ok: true,
+					enabled: next
+				}));
+			} catch (error) {
+				console.warn("[usage-billing] usage-tool toggle write-back failed:", error);
+				res.end(JSON.stringify({ error: "invalid" }));
+			}
+		}
+	}), "usage-billing: usage-tool route");
+}
+//#endregion
+//#region lib/types/routes/subscriptions.js
+/**
+* 路由：GET /api/billing/subscriptions
+*
+* 订阅套餐额度（Kimi / Z.ai Coding / OpenCode / MiniMax / OpenRouter / Claude /
+* CommandCode / 腾讯云 TokenHub 等）。5 分钟缓存 + in-flight 去重（与 balance
+* 同模式——并发请求共享同一次进行中的刷新）。
+*
+* 路由文件只关心 HTTP 缓存逻辑：超时或未命中时触发 refreshOnce，失败时仍用
+* 旧缓存（不挂起已 writeHead 的响应）。上游查询（collectSubscriptions +
+* resolveSubscriptionKeys + 适配器 + 套餐知识库）在装配器里跑。
+*/
+function registerSubscriptionsRoute(ctx, deps) {
+	ctx.effect(() => ctx.webServer.register({
+		kind: "exact",
+		path: "/api/billing/subscriptions",
+		handler: async (req, res) => {
+			if (!guardLoopback(req, res, deps.trustedHosts)) return;
+			res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+			if (Date.now() - deps.cached().at >= deps.cacheMs) try {
+				await deps.refreshOnce();
+			} catch (error) {
+				console.warn("[usage-billing] refreshQuotas failed; serving cached quotas:", error);
+			}
+			res.end(JSON.stringify({ quotas: deps.cached().quotas }));
+		}
+	}), "usage-billing: subscriptions route");
+}
+//#endregion
+//#region lib/types/routes/relay-quotas.js
+/**
+* 路由：GET /api/billing/relay-quotas
+*
+* 中转站额度（New API / Sub2API 余额 + 滚动窗口）。5 分钟缓存 + in-flight
+* 去重。诊断（每条路由的 origin / kind）随响应下发，供「我的中转站为什么不显
+* 示」自查。
+*
+* 路由文件只关心 HTTP 缓存 + 诊断序列化。上游查询（queryRelayQuotas +
+* 路由筛选 + isOfficialBaseUrl 排除）在装配器里跑。
+*/
+function registerRelayQuotasRoute(ctx, deps) {
+	ctx.effect(() => ctx.webServer.register({
+		kind: "exact",
+		path: "/api/billing/relay-quotas",
+		handler: async (req, res) => {
+			if (!guardLoopback(req, res, deps.trustedHosts)) return;
+			res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+			if (Date.now() - deps.cached().at >= deps.cacheMs) try {
+				await deps.refreshOnce();
+			} catch (error) {
+				console.warn("[usage-billing] refreshRelay failed; serving cached relay quotas:", error);
+			}
+			const diagnostics = deps.cached().quotas.map((row) => ({
+				route: row.route,
+				origin: row.origin,
+				kind: row.kind
+			}));
+			res.end(JSON.stringify({
+				quotas: deps.cached().quotas,
+				diagnostics
+			}));
+		}
+	}), "usage-billing: relay-quotas route");
+}
+//#endregion
+//#region lib/types/routes/usage-stats.js
+/**
+* 路由：GET /api/billing/usage-stats
+*
+* 实时用量聚合文档（byDay / byModel / bySession / bySite / byTurn / perf 等）。
+* stale-while-revalidate：聚合是全量扫描（重度用户上万条会话的冷启动折叠以
+* 分钟计），HTTP 请求绝不全程等它——只给 RESPONSE_BUDGET_MS 的等待预算，超
+* 预算立即回最近一次快照；后台折叠完成后快照随之刷新（挂在聚合 promise 上，
+* 与响应路径解耦）。宿主是单进程，慢响应期间事件循环被折叠占住，会话/模型
+* 列表 RPC 会一起饿死（用户反馈的启动卡顿）。
+*
+* 路由文件只关心 HTTP 拼装：
+* - decorate（注入 PACKAGE_VERSION / 预算 / 阈值）
+* - 聚合预算（Promise.race + setTimeout.unref）
+* - 响应体缓存（`statsBodyCache`：装饰 + 序列化结果按 doc 引用 + config 字段
+*   缓存，30s 轮询期间复用）
+* - 失败路径（聚合失败 → 读快照候选 → 仍无则 `{ error }`）
+*
+* 聚合器（`aggregator.aggregate()` / `sessionUsageOf()`）+ 快照读写 + 配置在
+* 装配器里跑，路由只通过 Deps 拿到回调。
+*/
+/** 聚合文档核心结构的 wire 校验（S-7 可观察性金丝雀）。
+*
+*  客户端 loadUsageStats 已有逐字段 typeof 守卫（渲染层兜底），本校验是
+*  服务端边界的漂移告警：聚合器字段改名/类型漂移时，30s 轮询的第一轮就在
+*  宿主日志留下 `[usage-billing]` 告警，而不是等用户面板渲染崩了报 issue。
+*
+*  语义是「告警不拦截」：校验失败仍照常下发（客户端自行兜底），绝不因
+*  schema 漂移把仪表盘整个 500——与「degrade, never fabricate」同一姿态。
+*
+*  只校验 fresh 聚合路径（快照兜底路径不校验：旧快照本就可能缺新字段，
+*  校验它们只会产生永久的假阳性告警）。
+*
+*  实现说明：刻意手写 typeof 检查而不用 schemastery——schemastery 是 config
+*  库，object schema 对 null / 数组 / 标量输入走宽容强转（补默认值）而非抛错，
+*  无法表达「形状必须精确」的校验语义。手写检查只认精确类型，缺字段即漂移。
+*  导出供测试。 */
+const NUM = (v) => typeof v === "number" && Number.isFinite(v);
+/** 一个 ModelUsage 桶的核心数字字段（客户端渲染硬依赖）。
+*  `withReasoning`：byModel / byDay / total 的桶含 reasoning；byDayModels 的
+*  三维格接口只有 6 个数字字段（无 reasoning），复用同一检查会产生假阳性。 */
+function modelUsageError(value, path, withReasoning = true) {
+	if (value === null || typeof value !== "object") return `${path} 不是对象`;
+	const keys = withReasoning ? [
+		"calls",
+		"input",
+		"output",
+		"cacheHit",
+		"cacheMiss",
+		"cost",
+		"reasoning"
+	] : [
+		"calls",
+		"input",
+		"output",
+		"cacheHit",
+		"cacheMiss",
+		"cost"
+	];
+	for (const key of keys) if (!NUM(value[key])) return `${path}.${key} 不是有限数字`;
+	return null;
+}
+/** 校验一份聚合文档；返回漂移原因（null = 形状正常）。纯只读，不改 doc。 */
+function usageStatsShapeError(doc) {
+	if (doc === null || typeof doc !== "object" || Array.isArray(doc)) return "文档不是对象";
+	const d = doc;
+	if (!NUM(d.version)) return "version 不是有限数字";
+	if (!NUM(d.updatedAt)) return "updatedAt 不是有限数字";
+	const total = modelUsageError(d.total, "total");
+	if (total !== null) return total;
+	for (const [field, cellCheck] of [
+		["byModel", (cell, p) => modelUsageError(cell, p)],
+		["byDay", (cell, p) => modelUsageError(cell, p)],
+		["byDayModels", (cell, p) => {
+			if (cell === null || typeof cell !== "object") return `${p} 不是对象`;
+			for (const [modelKey, usage] of Object.entries(cell)) {
+				const err = modelUsageError(usage, `${p}.${modelKey}`, false);
+				if (err !== null) return err;
+			}
+			return null;
+		}]
+	]) {
+		const bucket = d[field];
+		if (bucket === void 0) return `${field} 缺失（聚合路径恒带；快照兜底才允许缺）`;
+		if (bucket === null || typeof bucket !== "object") return `${field} 不是对象`;
+		for (const [key, cell] of Object.entries(bucket)) {
+			const err = cellCheck(cell, `${field}.${key}`);
+			if (err !== null) return err;
+		}
+	}
+	const bySession = d.bySession;
+	if (!Array.isArray(bySession)) return "bySession 不是数组";
+	for (const [index, row] of bySession.entries()) {
+		if (row === null || typeof row !== "object") return `bySession[${index}] 不是对象`;
+		const r = row;
+		if (typeof r.id !== "string" || r.id === "") return `bySession[${index}].id 不是非空字符串`;
+		if (!NUM(r.calls)) return `bySession[${index}].calls 不是有限数字`;
+		if (!NUM(r.cost)) return `bySession[${index}].cost 不是有限数字`;
+		if (!NUM(r.lastActive)) return `bySession[${index}].lastActive 不是有限数字`;
+	}
+	return null;
+}
+function registerUsageStatsRoute(ctx, deps) {
+	let statsBodyCache;
+	ctx.effect(() => ctx.webServer.register({
+		kind: "exact",
+		path: "/api/billing/usage-stats",
+		handler: async (req, res) => {
+			if (!guardLoopback(req, res, deps.trustedHosts)) return;
+			res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
+			const decorate = (doc) => ({
+				...doc,
+				pluginVersion: deps.packageVersion,
+				...deps.config.monthlyBudget === void 0 ? {} : { budget: deps.config.monthlyBudget },
+				...deps.config.lowBalanceThreshold === void 0 ? {} : { lowBalanceThreshold: deps.config.lowBalanceThreshold }
+			});
+			const statsBodyOf = (doc) => {
+				const budget = deps.config.monthlyBudget;
+				const threshold = deps.config.lowBalanceThreshold;
+				if (statsBodyCache !== void 0 && statsBodyCache.doc === doc && statsBodyCache.budget === budget && statsBodyCache.threshold === threshold) return statsBodyCache.body;
+				const shapeError = usageStatsShapeError(doc);
+				if (shapeError !== null) console.warn("[usage-billing] usage-stats document shape drift (serving anyway):", shapeError);
+				const body = JSON.stringify(decorate(doc));
+				statsBodyCache = {
+					doc,
+					budget,
+					threshold,
+					body
+				};
+				return body;
+			};
+			const aggregating = deps.aggregator.aggregate();
+			aggregating.then((stats) => {
+				deps.persistSnapshot(decorate(stats));
+			}, () => {});
+			let fresh;
+			try {
+				fresh = await Promise.race([aggregating.then((stats) => stats), new Promise((resolve) => {
+					setTimeout(() => {
+						resolve(void 0);
+					}, deps.responseBudgetMs).unref();
+				})]);
+			} catch (error) {
+				console.error("[usage-billing] usage-stats aggregate failed, falling back to snapshot:", error);
+			}
+			if (fresh !== void 0) {
+				res.end(statsBodyOf(fresh));
+				return;
+			}
+			for (const candidate of deps.candidates) {
+				const doc = await deps.readSnapshot(candidate);
+				if (doc === null) continue;
+				res.end(JSON.stringify(decorate(doc)));
+				return;
+			}
+			res.end(JSON.stringify({ error: "usage stats unavailable" }));
+		}
+	}), "usage-billing: usage-stats route");
+}
+//#endregion
+//#region lib/types/client/usage-billing-settings.js
+/** 设置命名空间 id（小写 kebab-case）。 */
+const BILLING_SETTINGS_NAMESPACE = "ui-usage-billing";
+/** 该命名空间下用户可编辑的字段名。 */
+const ENABLE_USAGE_STATS_TOOL_FIELD = "enableUsageStatsTool";
+//#endregion
+//#region lib/types/index.js
+/**
+* Usage billing surface plugin, node half.
+*
+* Serves `/api/billing/usage-stats`: real usage aggregated from every
+* persisted session log (see `aggregate.ts`) — the browser dashboard reads it
+* instead of showing an empty snapshot. Aggregation is stale-while-revalidate:
+* requests get a short wait budget and fall back to the freshest persisted
+* snapshot while a slow full fold keeps running in the background (a heavy
+* user's first fold takes minutes and must not starve the single-process
+* host's RPC). When `sessionPersistence` is unavailable (or aggregation
+* fails), the configured `statsPath` / `DSH_USAGE_STATS` / conventional JSON
+* file is served as a fallback, and a missing file answers `{ error }` so the
+* dashboard shows zeros, never fabricated samples.
+*/
+const SETTINGS_NAMESPACE_PATTERN = /^[a-z][a-z0-9-]*$/;
+/** 校验并透过合法命名空间 id；非法值 fail-loud（与上游原行为一致）。 */
+function validateSettingsNamespace(value) {
+	if (!SETTINGS_NAMESPACE_PATTERN.test(value)) throw new TypeError(`settings namespace "${value}" must match ${String(SETTINGS_NAMESPACE_PATTERN)}`);
+	return value;
+}
+/** usage_stats 工具开关的设置命名空间 id（下端与 node 共用同一常量）。 */
+const usageBillingSettingsNs = validateSettingsNamespace(BILLING_SETTINGS_NAMESPACE);
+/** 该命名空间的 wire schema：`enableUsageStatsTool` 布尔，默认关闭（issue 诉求）。 */
+const UsageBillingSettingsSchema = z.object({ [ENABLE_USAGE_STATS_TOOL_FIELD]: z.boolean().default(false) });
+/** 实时定价的后台刷新间隔（毫秒）：汇率/模型价低频变化，6 小时一次足够。 */
+/** 实时定价的后台刷新间隔（毫秒）：汇率/模型价低频变化，6 小时一次足够。 */
+const PRICING_REFRESH_INTERVAL_MS = 216e5;
+/** 历史回放预热的延迟：等宿主启动高峰（插件加载 / 路由挂载）过去再全量折叠，
+*  避免抢启动期的 CPU；纯延迟不阻塞任何请求，面板提前打开也只会提前聚合。 */
+const WARMUP_DELAY_MS = 3e3;
+/** 订阅套餐额度缓存时长（毫秒）：上游配额 API 低频变化，5 分钟足够。 */
+const SUBSCRIPTION_CACHE_MS = 3e5;
+const BALANCE_CACHE_MS = 3e5;
+/** DeepSeek 余额查询的默认凭据引用（与 llm-deepseek 的默认引用一致）。 */
+const DEFAULT_BALANCE_API_KEY_ENV = "DEEPSEEK_API_KEY";
+/**
+* 本插件版本号：从包自身的 package.json 读取（单一来源），随 usage-stats
+* 下发，供「设置 → 插件信息卡」展示。发布版 lib/index.js 相对包根解析。
+*/
+const PACKAGE_VERSION = createRequire(import.meta.url)("../package.json").version ?? "0.0.0";
+/** 统计快照的落盘节流（毫秒）：快照只服务聚合失败回退与重启首屏（展示级
+*  新鲜度即可），降到 5 分钟一次——原子写含上一版备份是两次全量 JSON 落盘，
+*  重度用户快照上百 KB，跟随前端轮询 30 秒写一次纯属写放大。 */
+const SNAPSHOT_INTERVAL_MS = 3e5;
+/** usage-stats 响应的等待预算（毫秒）：聚合在此预算内完成就回实时数据，
+*  超预算立即回最近快照（stale-while-revalidate），后台折叠继续跑。
+*  轻量用户暖缓存下的聚合是毫秒级，预算几乎不会触发。 */
+const RESPONSE_BUDGET_MS = 1500;
+/** 鉴权失败告警冷却（毫秒）：同一 provider 在窗口内只提示一次，避免 30 秒轮询刷屏。 */
+const AUTH_WARN_COOLDOWN_MS = 18e5;
+/**
+* 鉴权失败分类告警（P1-5）：余额 / 订阅查询返回 unauthorized 时，按
+* `source:provider` 去重并冷却告警，提示检查 llm-pi-ai 里该 provider 的 apiKeyEnv。
+*/
+const authWarnedAt = /* @__PURE__ */ new Map();
+function warnAuthOnce(source, provider, displayName) {
+	const key = `${source}:${provider}`;
+	const now = Date.now();
+	const last = authWarnedAt.get(key);
+	if (last !== void 0 && now - last < AUTH_WARN_COOLDOWN_MS) return;
+	authWarnedAt.set(key, now);
+	console.warn(`[usage-billing] ${displayName}（${provider}）鉴权失败：请检查 llm-pi-ai 设置中该 provider 的凭据环境变量是否正确/有效。`);
+}
+/** 锁等待上限：账本提交是毫秒级 read-render-commit，2s 已数倍于正常持锁时长。 */
+const LEDGER_LOCK_WAIT_MS = 2e3;
+/**
+* 锁年龄超过该值判为崩溃残留的孤儿锁。正常持锁是毫秒级文件提交，没有活跃
+* writer 会合法持有 60s；库层刻意不做年龄判定（它无法假设调用方的操作时长），
+* 本调用方知道自己操作的上界，可以给出有依据的清理阈值。
+*/
+const STALE_LEDGER_LOCK_MS = 6e4;
+/**
+* 锁等待超时后的孤儿锁自愈（issue #48）：仅当锁文件年龄超过
+* STALE_LEDGER_LOCK_MS 才清理，避免误删慢 writer 的活跃锁。
+* @param ledgerPath - 账本文件路径（锁为其 `.lock` 兄弟文件）。
+* @returns 是否清理了孤儿锁；false = 锁已消失或太新鲜，调用方上抛原错误。
+*/
+async function reclaimStaleLedgerLock(ledgerPath) {
+	let ageMs;
+	try {
+		ageMs = Date.now() - (await lstat(`${ledgerPath}.lock`)).mtimeMs;
+	} catch {
+		return false;
+	}
+	if (ageMs < STALE_LEDGER_LOCK_MS) return false;
+	console.warn(`[usage-billing] 账本锁已存在 ${Math.round(ageMs / 1e3)}s（崩溃残留），清理后重试：${ledgerPath}.lock`);
+	await rm(`${ledgerPath}.lock`, { force: true });
+	return true;
+}
+/**
+* Create the atomic file-backed durable-ledger store. The previous complete file
+* is retained as `.bak`; a malformed/missing main file falls back to that backup.
+*/
+function createFileUsageLedgerStore(ledgerPath) {
+	return {
+		async load() {
+			for (const path of [ledgerPath, `${ledgerPath}.bak`]) try {
+				const parsed = JSON.parse(await readFile(path, "utf8"));
+				if (parsed !== null && typeof parsed === "object") {
+					const candidate = parsed;
+					if (candidate.version === 1 && Array.isArray(candidate.sessions)) return parsed;
+				}
+			} catch {
+				swallowed("ledger-main-unreadable");
+			}
+		},
+		async save(document) {
+			await mkdir(dirname(ledgerPath), {
+				recursive: true,
+				mode: 448
+			});
+			const commit = async () => {
+				let existing;
+				let existingDoc;
+				try {
+					existing = await readFile(ledgerPath, "utf8");
+					const parsed = JSON.parse(existing);
+					if (parsed.version === 1 && Array.isArray(parsed.sessions)) existingDoc = parsed;
+				} catch {
+					existing = void 0;
+				}
+				if (existing !== void 0) await writeFileAtomic(`${ledgerPath}.bak`, existing, {
+					mode: 384,
+					dirMode: 448
+				});
+				const merged = existingDoc === void 0 ? document : mergeUsageLedgerDocuments(document, existingDoc);
+				await writeFileAtomic(ledgerPath, JSON.stringify(merged), {
+					mode: 384,
+					dirMode: 448
+				});
+			};
+			try {
+				await withFileLock(ledgerPath, commit, { waitMs: LEDGER_LOCK_WAIT_MS });
+			} catch (error) {
+				if (!(error instanceof Error) || !error.message.includes("timed out waiting for the writer lock")) throw error;
+				if (!await reclaimStaleLedgerLock(ledgerPath)) throw error;
+				await withFileLock(ledgerPath, commit, { waitMs: LEDGER_LOCK_WAIT_MS });
+			}
+		}
+	};
+}
+/** Required services: the web server, the persisted session log store, and user settings. */
+const inject = [
 	"webServer",
 	"sessionPersistence",
 	"credentials",
@@ -7279,7 +7784,9 @@ async function resolveSubscriptionKeys(settings, credentials) {
 		try {
 			const resolved = await credentials.resolve(credentialRef(env));
 			if (resolved?.value !== void 0 && resolved.value !== "") keys[key] = resolved.value;
-		} catch {}
+		} catch (error) {
+			swallowed("credential-resolve-failed", error);
+		}
 	}
 	if (providers?.["zai-coding-cn"]?.apiKeyEnv !== void 0 && keys.zaiCnApiKey !== "") keys.zaiRegion = "bigmodel-cn";
 	if (keys.opencodeApiKey === "") keys.opencodeApiKey = await readOpenCodeToken();
@@ -7305,7 +7812,9 @@ async function resolveSubscriptionKeys(settings, credentials) {
 async function readOpenCodeToken() {
 	try {
 		return parseOpenCodeAuthDocument(JSON.parse(await readFile(join(homedir(), ".local", "share", "opencode", "auth.json"), "utf8")));
-	} catch {}
+	} catch {
+		swallowed("opencode-auth-missing");
+	}
 	return "";
 }
 /**
@@ -7397,7 +7906,9 @@ function apply(ctx, config = {}) {
 				const candidate = ref;
 				if (typeof candidate.date === "string" && typeof candidate.total === "number" && typeof candidate.granted === "number" && typeof candidate.topped === "number" && typeof candidate.currency === "string") reconcileRef = candidate;
 			}
-		} catch {}
+		} catch {
+			swallowed("reconcile-ref-missing");
+		}
 	})();
 	const persistReconcileRef = () => {
 		if (reconcileRef === null) return;
@@ -7466,83 +7977,32 @@ function apply(ctx, config = {}) {
 					mode: 384,
 					dirMode: 448
 				});
-			} catch {}
+			} catch {
+				swallowed("snapshot-bak-missing");
+			}
 			try {
 				await writeFileAtomic(snapshotPath, payload, {
 					mode: 384,
 					dirMode: 448
 				});
-			} catch {}
+			} catch {
+				swallowed("snapshot-write-failed");
+			}
 		})();
 	};
 	/** 读一个快照候选并解析成对象：主文件优先；主文件损坏时回退上一版 `.bak`（P0-3 崩溃恢复）。 */
 	const readSnapshot = async (candidate) => {
 		for (const path of [candidate, `${candidate}.bak`]) try {
 			return JSON.parse(await readFile(path, "utf8"));
-		} catch {}
+		} catch {
+			swallowed("snapshot-candidate-unreadable");
+		}
 		return null;
 	};
-	const notifyClaimsPath = `${snapshotPath}.notify-claims.json`;
-	const notifyClaims = {
-		loaded: false,
-		keys: []
-	};
-	ctx.effect(() => ctx.webServer.register({
-		kind: "exact",
-		path: "/api/billing/notify-claim",
-		handler: async (req, res) => {
-			if (!guardLoopback(req, res, trustedHosts)) return;
-			if (req.method !== "POST") {
-				res.writeHead(405, { "content-type": "application/json; charset=utf-8" });
-				res.end(JSON.stringify({ error: "method not allowed" }));
-				return;
-			}
-			if (!isLoopbackOrigin(req.headers.origin) || !(req.headers["content-type"] ?? "").toLowerCase().includes("application/json")) {
-				res.writeHead(403, { "content-type": "application/json; charset=utf-8" });
-				res.end(JSON.stringify({ error: "forbidden: loopback only" }));
-				return;
-			}
-			try {
-				let body = "";
-				for await (const chunk of req) {
-					body += String(chunk);
-					if (body.length > 2048) {
-						res.end(JSON.stringify({ error: "body too large" }));
-						return;
-					}
-				}
-				const parsed = JSON.parse(body === "" ? "{}" : body);
-				if (typeof parsed.key !== "string" || parsed.key === "" || parsed.key.length > 200) {
-					res.writeHead(400, { "content-type": "application/json; charset=utf-8" });
-					res.end(JSON.stringify({ error: "invalid key" }));
-					return;
-				}
-				if (!notifyClaims.loaded) {
-					notifyClaims.loaded = true;
-					try {
-						const stored = JSON.parse(await readFile(notifyClaimsPath, "utf8"));
-						if (Array.isArray(stored.keys)) notifyClaims.keys = stored.keys.filter((k) => typeof k === "string");
-					} catch {}
-				}
-				if (notifyClaims.keys.includes(parsed.key)) {
-					res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
-					res.end(JSON.stringify({ claimed: false }));
-					return;
-				}
-				notifyClaims.keys.push(parsed.key);
-				if (notifyClaims.keys.length > 400) notifyClaims.keys = notifyClaims.keys.slice(-200);
-				writeFileAtomic(notifyClaimsPath, JSON.stringify({ keys: notifyClaims.keys }), {
-					mode: 384,
-					dirMode: 448
-				}).catch(() => {});
-				res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
-				res.end(JSON.stringify({ claimed: true }));
-			} catch {
-				res.writeHead(400, { "content-type": "application/json; charset=utf-8" });
-				res.end(JSON.stringify({ error: "invalid" }));
-			}
-		}
-	}), "usage-billing: notify-claim route");
+	registerNotifyClaimRoute(ctx, {
+		trustedHosts,
+		claimsPath: `${snapshotPath}.notify-claims.json`
+	});
 	let usageToolDisposer;
 	let usageToolRegister;
 	const syncUsageTool = () => {
@@ -7743,40 +8203,11 @@ function apply(ctx, config = {}) {
 			clearInterval(timer);
 		};
 	}, "usage-billing: pricing refresh timer");
-	ctx.effect(() => ctx.webServer.register({
-		kind: "exact",
-		path: "/api/billing/pricing",
-		handler: async (req, res) => {
-			if (!guardLoopback(req, res, trustedHosts)) return;
-			res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
-			res.end(pricingBody());
-		}
-	}), "usage-billing: pricing route");
-	ctx.effect(() => ctx.webServer.register({
-		kind: "exact",
-		path: "/api/billing/pricing/refresh",
-		handler: async (req, res) => {
-			if (!guardLoopback(req, res, trustedHosts)) return;
-			if (req.method !== "POST") {
-				res.writeHead(405, { "content-type": "application/json; charset=utf-8" });
-				res.end(JSON.stringify({ error: "method not allowed" }));
-				return;
-			}
-			if (!isLoopbackOrigin(req.headers.origin)) {
-				res.writeHead(403, { "content-type": "application/json; charset=utf-8" });
-				res.end(JSON.stringify({ error: "forbidden: loopback only" }));
-				return;
-			}
-			if (!(req.headers["content-type"] ?? "").toLowerCase().includes("application/json")) {
-				res.writeHead(415, { "content-type": "application/json; charset=utf-8" });
-				res.end(JSON.stringify({ error: "unsupported content-type" }));
-				return;
-			}
-			await refreshPricing();
-			res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
-			res.end(pricingBody());
-		}
-	}), "usage-billing: pricing refresh route");
+	registerPricingRoutes(ctx, {
+		trustedHosts,
+		body: pricingBody,
+		refresh: refreshPricing
+	});
 	let balanceCache = {
 		at: 0,
 		doc: { balances: [] }
@@ -7807,7 +8238,9 @@ function apply(ctx, config = {}) {
 			let todayOfficialCost = 0;
 			try {
 				todayOfficialCost = (await aggregator.aggregate()).byDay[today]?.officialCost ?? 0;
-			} catch {}
+			} catch {
+				swallowed("reconcile-aggregate-skipped");
+			}
 			const result = reconcileBalanceDelta(reconcileRef, official, todayOfficialCost, today, now);
 			const refChanged = result.ref !== null && result.ref !== reconcileRef;
 			reconcileRef = result.ref;
@@ -7837,80 +8270,22 @@ function apply(ctx, config = {}) {
 		});
 		return balanceInflight;
 	};
-	ctx.effect(() => ctx.webServer.register({
-		kind: "exact",
-		path: "/api/billing/balance",
-		handler: async (req, res) => {
-			if (!guardLoopback(req, res, trustedHosts)) return;
-			res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
-			if (Date.now() - balanceCache.at < BALANCE_CACHE_MS) {
-				res.end(JSON.stringify(balanceCache.doc));
-				return;
-			}
-			try {
-				await refreshBalanceOnce();
-			} catch (error) {
-				console.warn("[usage-billing] refreshBalances failed; serving cached balances:", error);
-			}
-			res.end(JSON.stringify(balanceCache.doc));
-		}
-	}), "usage-billing: balance route");
-	ctx.effect(() => ctx.webServer.register({
-		kind: "exact",
-		path: "/api/billing/usage-tool",
-		handler: async (req, res) => {
-			if (!guardLoopback(req, res, trustedHosts)) return;
-			if (req.method !== "GET" && req.method !== "POST") {
-				res.writeHead(405, { "content-type": "application/json; charset=utf-8" });
-				res.end(JSON.stringify({ error: "method not allowed" }));
-				return;
-			}
-			res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
-			const enabled = usageSettingsScope !== void 0 ? usageSettingsScope.get().enableUsageStatsTool : readUsageStatsToggle(config);
-			if (req.method === "GET") {
-				res.end(JSON.stringify({ enabled }));
-				return;
-			}
-			if (!isLoopbackOrigin(req.headers.origin)) {
-				res.writeHead(403, { "content-type": "application/json; charset=utf-8" });
-				res.end(JSON.stringify({ error: "forbidden: loopback only" }));
-				return;
-			}
-			if (!(req.headers["content-type"] ?? "").toLowerCase().includes("application/json")) {
-				res.writeHead(415, { "content-type": "application/json; charset=utf-8" });
-				res.end(JSON.stringify({ error: "unsupported content-type" }));
-				return;
-			}
-			try {
-				let body = "";
-				for await (const chunk of req) {
-					body += String(chunk);
-					if (body.length > 512) {
-						res.end(JSON.stringify({ error: "body too large" }));
-						return;
-					}
-				}
-				const next = JSON.parse(body === "" ? "{}" : body).enabled === true;
-				if (usageSettingsScope !== void 0) {
-					await usageSettingsScope.update({ enableUsageStatsTool: next });
-					syncUsageTool();
-				} else if (liveSettings !== void 0) {
-					await liveSettings.update(liveSettings.ns, { [ENABLE_USAGE_STATS_TOOL_FIELD]: next });
-					syncUsageTool();
-				} else {
-					res.end(JSON.stringify({ error: "settings unavailable" }));
-					return;
-				}
-				res.end(JSON.stringify({
-					ok: true,
-					enabled: next
-				}));
-			} catch (error) {
-				console.warn("[usage-billing] usage-tool toggle write-back failed:", error);
-				res.end(JSON.stringify({ error: "invalid" }));
-			}
-		}
-	}), "usage-billing: usage-tool route");
+	registerBalanceRoute(ctx, {
+		trustedHosts,
+		cached: () => balanceCache,
+		refreshOnce: refreshBalanceOnce,
+		cacheMs: BALANCE_CACHE_MS
+	});
+	registerUsageToolRoute(ctx, {
+		trustedHosts,
+		read: () => usageSettingsScope !== void 0 ? usageSettingsScope.get().enableUsageStatsTool : readUsageStatsToggle(config),
+		write: async (next) => {
+			if (usageSettingsScope !== void 0) await usageSettingsScope.update({ enableUsageStatsTool: next });
+			else if (liveSettings !== void 0) await liveSettings.update(liveSettings.ns, { [ENABLE_USAGE_STATS_TOOL_FIELD]: next });
+			else throw new Error("settings unavailable");
+		},
+		syncTool: syncUsageTool
+	});
 	let quotaCache = {
 		at: 0,
 		quotas: []
@@ -7954,20 +8329,12 @@ function apply(ctx, config = {}) {
 		});
 		return quotasInflight;
 	};
-	ctx.effect(() => ctx.webServer.register({
-		kind: "exact",
-		path: "/api/billing/subscriptions",
-		handler: async (req, res) => {
-			if (!guardLoopback(req, res, trustedHosts)) return;
-			res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
-			if (Date.now() - quotaCache.at >= SUBSCRIPTION_CACHE_MS) try {
-				await refreshQuotasOnce();
-			} catch (error) {
-				console.warn("[usage-billing] refreshQuotas failed; serving cached quotas:", error);
-			}
-			res.end(JSON.stringify({ quotas: quotaCache.quotas }));
-		}
-	}), "usage-billing: subscriptions route");
+	registerSubscriptionsRoute(ctx, {
+		trustedHosts,
+		cached: () => quotaCache,
+		refreshOnce: refreshQuotasOnce,
+		cacheMs: SUBSCRIPTION_CACHE_MS
+	});
 	let relayCache = {
 		at: 0,
 		quotas: []
@@ -7997,81 +8364,22 @@ function apply(ctx, config = {}) {
 		});
 		return relayInflight;
 	};
-	ctx.effect(() => ctx.webServer.register({
-		kind: "exact",
-		path: "/api/billing/relay-quotas",
-		handler: async (req, res) => {
-			if (!guardLoopback(req, res, trustedHosts)) return;
-			res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
-			if (Date.now() - relayCache.at >= SUBSCRIPTION_CACHE_MS) try {
-				await refreshRelayOnce();
-			} catch (error) {
-				console.warn("[usage-billing] refreshRelay failed; serving cached relay quotas:", error);
-			}
-			const diagnostics = relayCache.quotas.map((row) => ({
-				route: row.route,
-				origin: row.origin,
-				kind: row.kind
-			}));
-			res.end(JSON.stringify({
-				quotas: relayCache.quotas,
-				diagnostics
-			}));
-		}
-	}), "usage-billing: relay-quotas route");
-	let statsBodyCache;
-	ctx.effect(() => ctx.webServer.register({
-		kind: "exact",
-		path: "/api/billing/usage-stats",
-		handler: async (req, res) => {
-			if (!guardLoopback(req, res, trustedHosts)) return;
-			res.writeHead(200, { "content-type": "application/json; charset=utf-8" });
-			const decorate = (doc) => ({
-				...doc,
-				pluginVersion: PACKAGE_VERSION,
-				...config.monthlyBudget === void 0 ? {} : { budget: config.monthlyBudget },
-				...config.lowBalanceThreshold === void 0 ? {} : { lowBalanceThreshold: config.lowBalanceThreshold }
-			});
-			const statsBodyOf = (doc) => {
-				const budget = config.monthlyBudget;
-				const threshold = config.lowBalanceThreshold;
-				if (statsBodyCache !== void 0 && statsBodyCache.doc === doc && statsBodyCache.budget === budget && statsBodyCache.threshold === threshold) return statsBodyCache.body;
-				const body = JSON.stringify(decorate(doc));
-				statsBodyCache = {
-					doc,
-					budget,
-					threshold,
-					body
-				};
-				return body;
-			};
-			const aggregating = aggregator.aggregate();
-			aggregating.then((stats) => {
-				persistSnapshot(decorate(stats));
-			}, () => {});
-			let fresh;
-			try {
-				fresh = await Promise.race([aggregating.then((stats) => stats), new Promise((resolve) => {
-					setTimeout(() => {
-						resolve(void 0);
-					}, RESPONSE_BUDGET_MS).unref();
-				})]);
-			} catch (error) {
-				console.error("[usage-billing] usage-stats aggregate failed, falling back to snapshot:", error);
-			}
-			if (fresh !== void 0) {
-				res.end(statsBodyOf(fresh));
-				return;
-			}
-			for (const candidate of candidates) {
-				const doc = await readSnapshot(candidate);
-				if (doc === null) continue;
-				res.end(JSON.stringify(decorate(doc)));
-				return;
-			}
-			res.end(JSON.stringify({ error: "usage stats unavailable" }));
-		}
-	}), "usage-billing: usage-stats route");
+	registerRelayQuotasRoute(ctx, {
+		trustedHosts,
+		cached: () => relayCache,
+		refreshOnce: refreshRelayOnce,
+		cacheMs: SUBSCRIPTION_CACHE_MS
+	});
+	registerUsageStatsRoute(ctx, {
+		trustedHosts,
+		aggregator,
+		config,
+		candidates,
+		persistSnapshot,
+		readSnapshot,
+		packageVersion: PACKAGE_VERSION,
+		responseBudgetMs: RESPONSE_BUDGET_MS
+	});
 }
 //#endregion
-export { Config, adaptSessionPersistence, apply, createFileUsageLedgerStore, guardLoopback, inject, normalizeTrustedHosts, readPiAiProviderRoutes, readRegisteredProviderIds, resolveSubscriptionKeys };
+export { adaptSessionPersistence, apply, createFileUsageLedgerStore, guardLoopback, hostNameOf, inject, isLoopbackHost, isLoopbackOrigin, isLoopbackPeer, normalizeTrustedHosts, readPiAiProviderRoutes, readRegisteredProviderIds, resolveSubscriptionKeys };