@kenz1117/dsh-ui-usage-billing 1.6.7 → 1.6.8

package/lib/index.js

@@ -3558,6 +3558,7 @@ function createUsageAggregator(persistence, options = {}) {
 	let ledgerNeedsSave = false;
 	let lastLedgerSaveAt = 0;
 	const unreadable = /* @__PURE__ */ new Map();
+	const titleHints = /* @__PURE__ */ new Map();
 	let inflight;
 	let ledgerAppliedMigrations;
 	let lastDoc;
@@ -3590,6 +3591,7 @@ function createUsageAggregator(persistence, options = {}) {
 	const foldFingerprintOf = (registered, routes) => configFingerprint(subscriptionMatcher, officialProviderIds, routeAliases, searchEstimate, options.modelKeyAliases, registered, routeOriginsOf(routes));
 	let foldFingerprint = foldFingerprintOf(/* @__PURE__ */ new Set(), {});
 	const FOLD_CHUNK_EVENTS = 8e3;
+	const FOLD_YIELD_SESSIONS = 8;
 	/** 惰性失效（价目表时序）：账本/缓存行若以「当时不可计价」的模型落盘，
 	*  而价目表现在能计价了，该行必须重折——否则显示层按实时价算出的
 	*  「目录价预估」与服务端 cost=0 并存，出现「明细比总额高」的双口径
@@ -3692,7 +3694,10 @@ function createUsageAggregator(persistence, options = {}) {
 		let formatUnreadable = 0;
 		let noLedgerUnreadable = 0;
 		let staleLedgerSessions = 0;
-		for (const meta of metas) {
+		for (const [metaIndex, meta] of metas.entries()) {
+			if (metaIndex > 0 && metaIndex % FOLD_YIELD_SESSIONS === 0) await new Promise((resolve) => {
+				setImmediate(resolve);
+			});
 			const id = String(meta.id);
 			seen.add(id);
 			const stamp = await stampOf(meta);
@@ -3798,8 +3803,13 @@ function createUsageAggregator(persistence, options = {}) {
 					stamp,
 					format
 				});
+				if (options.resolveSessionTitle !== void 0) {
+					const hint = options.resolveSessionTitle(meta);
+					if (hint !== void 0) titleHints.set(id, hint);
+				}
 				console.warn("[usage-billing] skip unreadable session", id, error);
 			}
+			if (included.has(id)) titleHints.delete(id);
 		}
 		for (const key of [...cache.keys()]) if (!seen.has(key)) cache.delete(key);
 		for (const key of [...unreadable.keys()]) if (!seen.has(key)) unreadable.delete(key);
@@ -3813,12 +3823,17 @@ function createUsageAggregator(persistence, options = {}) {
 				if (included.has(entry.id)) continue;
 				try {
 					const stale = (entry.foldVersion ?? 1) < 23 || entry.fingerprint !== foldFingerprint;
+					const fold = deserializedFoldOf(entry.fold);
+					const hint = titleHints.get(entry.id);
 					folds.push({
 						id: entry.id,
 						...entry.cwd === void 0 ? {} : { cwd: entry.cwd },
 						...entry.subOf === void 0 ? {} : { subOf: entry.subOf },
 						...stale ? { staleLedger: true } : {},
-						fold: deserializedFoldOf(entry.fold)
+						fold: hint === void 0 ? fold : {
+							...fold,
+							title: hint
+						}
 					});
 					included.add(entry.id);
 					if (stale) staleLedgerSessions += 1;
@@ -4055,6 +4070,9 @@ function createUsageAggregator(persistence, options = {}) {
 		async flush() {
 			if (inflight !== void 0) await inflight.catch(() => {});
 			await saveLedger(true);
+		},
+		lastDocOf() {
+			return lastDoc;
 		}
 	};
 }
@@ -7296,8 +7314,9 @@ function registerPricingRoutes(ctx, deps) {
 * TokenHub 等）+ 用户自定义余额 + 声明端点 + 余额差对账。5 分钟缓存（避免
 * 每 30s 后台轮询打上游），in-flight 去重（并发请求共享同一次进行中的刷新）。
 *
-* 路由文件只关心 HTTP 缓存逻辑：5 分钟过期判定 + 失败时仍发旧缓存（不挂起
-* 已 writeHead 的响应）。上游查询（queryBalances / queryCustomBalances /
+* 路由文件只关心 HTTP 缓存逻辑：5 分钟过期判定 + 刷新预算（超预算回旧
+* 缓存并标 stale，不把响应挂在长查询上）+ 失败时仍发旧缓存（不挂起已
+* writeHead 的响应）。上游查询（queryBalances / queryCustomBalances /
 * queryDeclaredEndpoints / reconcileBalanceDelta）在装配器里跑，路由只通过
 * `cached()` 与 `refreshOnce()` 拿到结果。
 */
@@ -7312,12 +7331,21 @@ function registerBalanceRoute(ctx, deps) {
 				res.end(JSON.stringify(deps.cached().doc));
 				return;
 			}
-			try {
-				await deps.refreshOnce();
-			} catch (error) {
+			let timedOut = false;
+			const onFailure = (error) => {
 				console.warn("[usage-billing] refreshBalances failed; serving cached balances:", error);
-			}
-			res.end(JSON.stringify(deps.cached().doc));
+			};
+			await Promise.race([deps.refreshOnce().then(() => void 0, onFailure), new Promise((resolve) => {
+				setTimeout(() => {
+					timedOut = true;
+					resolve();
+				}, deps.responseBudgetMs).unref();
+			})]);
+			const doc = deps.cached().doc;
+			res.end(JSON.stringify(timedOut ? {
+				...doc,
+				stale: true
+			} : doc));
 		}
 	}), "usage-billing: balance route");
 }
@@ -7422,12 +7450,19 @@ function registerSubscriptionsRoute(ctx, deps) {
 		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) {
+			let timedOut = false;
+			if (Date.now() - deps.cached().at >= deps.cacheMs) await Promise.race([deps.refreshOnce().then(() => void 0, (error) => {
 				console.warn("[usage-billing] refreshQuotas failed; serving cached quotas:", error);
-			}
-			res.end(JSON.stringify({ quotas: deps.cached().quotas }));
+			}), new Promise((resolve) => {
+				setTimeout(() => {
+					timedOut = true;
+					resolve();
+				}, deps.responseBudgetMs).unref();
+			})]);
+			res.end(JSON.stringify({
+				quotas: deps.cached().quotas,
+				...timedOut ? { stale: true } : {}
+			}));
 		}
 	}), "usage-billing: subscriptions route");
 }
@@ -7450,11 +7485,15 @@ function registerRelayQuotasRoute(ctx, deps) {
 		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) {
+			let timedOut = false;
+			if (Date.now() - deps.cached().at >= deps.cacheMs) await Promise.race([deps.refreshOnce().then(() => void 0, (error) => {
 				console.warn("[usage-billing] refreshRelay failed; serving cached relay quotas:", error);
-			}
+			}), new Promise((resolve) => {
+				setTimeout(() => {
+					timedOut = true;
+					resolve();
+				}, deps.responseBudgetMs).unref();
+			})]);
 			const diagnostics = deps.cached().quotas.map((row) => ({
 				route: row.route,
 				origin: row.origin,
@@ -7462,7 +7501,8 @@ function registerRelayQuotasRoute(ctx, deps) {
 			}));
 			res.end(JSON.stringify({
 				quotas: deps.cached().quotas,
-				diagnostics
+				diagnostics,
+				...timedOut ? { stale: true } : {}
 			}));
 		}
 	}), "usage-billing: relay-quotas route");
@@ -7617,10 +7657,21 @@ function registerUsageStatsRoute(ctx, deps) {
 				res.end(statsBodyOf(fresh));
 				return;
 			}
+			const recent = deps.lastDoc?.();
+			if (recent !== void 0) {
+				res.end(JSON.stringify({
+					...decorate(recent),
+					staleSnapshot: true
+				}));
+				return;
+			}
 			for (const candidate of deps.candidates) {
 				const doc = await deps.readSnapshot(candidate);
 				if (doc === null) continue;
-				res.end(JSON.stringify(decorate(doc)));
+				res.end(JSON.stringify({
+					...decorate(doc),
+					staleSnapshot: true
+				}));
 				return;
 			}
 			res.end(JSON.stringify({ error: "usage stats unavailable" }));
@@ -7693,6 +7744,24 @@ const WARMUP_DELAY_MS = 3e3;
 /** 订阅套餐额度缓存时长（毫秒）：上游配额 API 低频变化，5 分钟足够。 */
 const SUBSCRIPTION_CACHE_MS = 3e5;
 const BALANCE_CACHE_MS = 3e5;
+/**
+* 余额路由的总等待预算（毫秒）：超预算立刻回上一次成功的余额（stale 标记），
+* 刷新在后台继续。取 8s——与上游单次查询超时（FETCH_TIMEOUT_MS）对齐：上游
+* 真的不可达时多等没有意义，先把响应还给浏览器，别占着同源连接（issue #104）。
+*/
+const BALANCE_RESPONSE_BUDGET_MS = 8e3;
+/**
+* 订阅 / 中转站额度路由的总等待预算（毫秒）：与余额路由同口径（issue #104）。
+* 上游额度接口不可达时（8s 超时 × 重试 ≈ 10~16s），响应被长期挂住会占满浏览器
+* 的同源连接池——多标签页各挂一条即让宿主自己的资源请求排队，界面整体卡死。
+*/
+const QUOTA_RESPONSE_BUDGET_MS = 8e3;
+/**
+* 对账基线的最大可用年龄（毫秒）：超过则「今日官方费用」偏小，用它对账会
+* 报假漂移——此时跳过本轮对账，等后台补算完成后再恢复（issue #104）。
+* 取 5 分钟：与 usage-stats 的 30s 轮询 + 5 分钟快照节流同一量级。
+*/
+const RECONCILE_BASIS_MAX_AGE_MS = 3e5;
 /** DeepSeek 余额查询的默认凭据引用（与 llm-deepseek 的默认引用一致）。 */
 const DEFAULT_BALANCE_API_KEY_ENV = "DEEPSEEK_API_KEY";
 /**
@@ -7932,6 +8001,48 @@ function buildWorkspaceTitleResolver(ctx) {
 	};
 }
 /**
+* 构造「会话头 → 宿主侧会话标题」解析器（issue #103，可选依赖）。
+*
+* 插件的会话标题取自日志里的 `session/title` 事件——**日志读不动**时（宿主拒绝
+* 该格式/代际，插件折叠失败），只能吃账本旧行，标题会永远停在重命名前的值。
+* 宿主自己的会话投影缓存仍可能记得这个标题（`cachedSnapshot` / 既有能力
+* `cachedPredecessorTitle`：格式代际边缘的标题仍能跨边缘存活），用它兜底可让
+* 账单明细的标题跟随工作区。
+*
+* 宿主没有该服务（0.1.x 代际）或读取失败都返回 undefined：绝不抛错，行为与
+* 现状一致（可选依赖，不影响主流程）。
+* @param ctx - host context carrying the optional session projection cache.
+* @returns 标题解析函数；服务不可用时 undefined。
+*/
+function buildSessionTitleResolver(ctx) {
+	let cache;
+	try {
+		cache = ctx.get("sessionProjectionCache");
+	} catch {
+		return;
+	}
+	if (cache === void 0) return void 0;
+	const titleOf = (values) => {
+		const title = values?.title;
+		return typeof title === "string" && title !== "" ? title : void 0;
+	};
+	const cachedSnapshot = cache.cachedSnapshot;
+	const cachedPredecessorTitle = cache.cachedPredecessorTitle;
+	if (typeof cachedSnapshot !== "function" && typeof cachedPredecessorTitle !== "function") return void 0;
+	return (header) => {
+		try {
+			if (typeof cachedSnapshot === "function") {
+				const title = titleOf(cachedSnapshot(header, ["title"])?.values);
+				if (title !== void 0) return title;
+			}
+			if (typeof cachedPredecessorTitle === "function") return titleOf(cachedPredecessorTitle(header)?.values);
+			return;
+		} catch {
+			return;
+		}
+	};
+}
+/**
 * 凭据 seam 的宽容解析：ref 名 → 非空值；失败/缺失返回 undefined（多 surface 共用，
 * 失败按结构化静默记录）。
 */
@@ -8086,6 +8197,7 @@ function apply(ctx, config = {}) {
 		}).catch(() => {});
 	};
 	const workspaceTitleResolver = buildWorkspaceTitleResolver(ctx);
+	const sessionTitleResolver = buildSessionTitleResolver(ctx);
 	applyBuiltinCatalog(BUILTIN_MODEL_CATALOG, BUILTIN_MODEL_KEY_ALIASES);
 	applyUserModelAliases(config.modelKeyAliases);
 	let llmRegistryWarned = false;
@@ -8119,6 +8231,7 @@ function apply(ctx, config = {}) {
 		resolveRegisteredProviders: registeredProvidersOf,
 		...config.modelKeyAliases === void 0 ? {} : { modelKeyAliases: config.modelKeyAliases },
 		...workspaceTitleResolver === void 0 ? {} : { resolveWorkspaceTitle: workspaceTitleResolver },
+		...sessionTitleResolver === void 0 ? {} : { resolveSessionTitle: sessionTitleResolver },
 		...config.searchCallEstimateCny === void 0 ? {} : { searchCallEstimateCny: config.searchCallEstimateCny },
 		ledger: ledgerStore
 	});
@@ -8414,21 +8527,22 @@ function apply(ctx, config = {}) {
 		if (official !== void 0 && reconcilable) {
 			const now = Date.now();
 			const today = dayStamp(now);
-			let todayOfficialCost = 0;
-			try {
-				todayOfficialCost = (await aggregator.aggregate()).byDay[today]?.officialCost ?? 0;
-			} catch {
-				swallowed("reconcile-aggregate-skipped");
+			const recent = aggregator.lastDocOf();
+			if (recent !== void 0 && now - recent.updatedAt <= RECONCILE_BASIS_MAX_AGE_MS) {
+				const todayOfficialCost = recent?.byDay[today]?.officialCost ?? 0;
+				const result = reconcileBalanceDelta(reconcileRef, official, todayOfficialCost, today, now);
+				const refChanged = result.ref !== null && result.ref !== reconcileRef;
+				reconcileRef = result.ref;
+				if (result.event !== null && result.event.kind !== "flat") reconcile = {
+					...result.event,
+					provider: official.displayName,
+					...official.currency === void 0 ? {} : { currency: official.currency }
+				};
+				if (refChanged) persistReconcileRef();
+			} else {
+				aggregator.aggregate().catch(() => {});
+				swallowed("reconcile-basis-stale");
 			}
-			const result = reconcileBalanceDelta(reconcileRef, official, todayOfficialCost, today, now);
-			const refChanged = result.ref !== null && result.ref !== reconcileRef;
-			reconcileRef = result.ref;
-			if (result.event !== null && result.event.kind !== "flat") reconcile = {
-				...result.event,
-				provider: official.displayName,
-				...official.currency === void 0 ? {} : { currency: official.currency }
-			};
-			if (refChanged) persistReconcileRef();
 		}
 		const doc = {
 			balances: [
@@ -8453,7 +8567,8 @@ function apply(ctx, config = {}) {
 		trustedHosts,
 		cached: () => balanceCache,
 		refreshOnce: refreshBalanceOnce,
-		cacheMs: BALANCE_CACHE_MS
+		cacheMs: BALANCE_CACHE_MS,
+		responseBudgetMs: BALANCE_RESPONSE_BUDGET_MS
 	});
 	registerUsageToolRoute(ctx, {
 		trustedHosts,
@@ -8513,7 +8628,8 @@ function apply(ctx, config = {}) {
 		trustedHosts,
 		cached: () => quotaCache,
 		refreshOnce: refreshQuotasOnce,
-		cacheMs: SUBSCRIPTION_CACHE_MS
+		cacheMs: SUBSCRIPTION_CACHE_MS,
+		responseBudgetMs: QUOTA_RESPONSE_BUDGET_MS
 	});
 	let relayCache = {
 		at: 0,
@@ -8552,7 +8668,8 @@ function apply(ctx, config = {}) {
 		trustedHosts,
 		cached: () => relayCache,
 		refreshOnce: refreshRelayOnce,
-		cacheMs: SUBSCRIPTION_CACHE_MS
+		cacheMs: SUBSCRIPTION_CACHE_MS,
+		responseBudgetMs: QUOTA_RESPONSE_BUDGET_MS
 	});
 	registerUsageStatsRoute(ctx, {
 		trustedHosts,
@@ -8562,7 +8679,8 @@ function apply(ctx, config = {}) {
 		persistSnapshot,
 		readSnapshot,
 		packageVersion: PACKAGE_VERSION,
-		responseBudgetMs: RESPONSE_BUDGET_MS
+		responseBudgetMs: RESPONSE_BUDGET_MS,
+		lastDoc: () => aggregator.lastDocOf()
 	});
 }
 //#endregion

package/lib/types/aggregate.d.ts

@@ -164,6 +164,15 @@ export interface AggregateOptions {
     /** 工作区标题解析：给定会话 cwd 返回项目显示标题；undefined = 回退到 cwd 末级目录名
      *  （host 的 workspaceRegistry 为可选依赖，缺失时不注入，行为保持不变）。 */
     resolveWorkspaceTitle?: (cwd: string) => string | undefined;
+    /**
+     * 会话标题兜底解析：给定会话头（宿主持久层列表元数据）返回宿主侧的会话标题。
+     *
+     * 只在**日志读不动**的会话上用（宿主拒绝该格式/代际，插件折叠失败）：此时插件
+     * 只能吃账本里的旧行，标题会永远停在重命名前的值——宿主自己的投影缓存仍可能
+     * 记得这个标题（格式代际边缘的既定能力），用它兜底可让标题跟随工作区
+     * （issue #103）。读得动的会话一律以日志为准，本回调不参与。
+     */
+    resolveSessionTitle?: (header: SessionHeader) => string | undefined;
     /** 独立的持久用量账本。启用后，已经成功折叠过的会话即使随后从
      *  sessionPersistence 中永久删除，也会继续计入累计用量。 */
     ledger?: UsageLedgerStore;
@@ -735,6 +744,16 @@ export interface UsageAggregator {
      * @returns 会话累计；日志与账本均无该会话时 undefined（调用方自行兜底）。
      */
     sessionUsageOf(sessionId: string): Promise<SessionUsageSummary | undefined>;
+    /**
+     * 最近一次**已完成**的聚合文档（不触发新的折叠）。
+     *
+     * 供路由的 stale-while-revalidate 兜底用：当本轮折叠超过响应预算（宿主单进程
+     * 事件循环被重活折叠占住）时，落盘快照最多落后一个节流窗口（分钟级），而这里
+     * 的内存文档只落后一个聚合周期——两者都是「上次算好的」，但内存那份更新。
+     * 从未完成过一次聚合时返回 undefined（调用方回落到磁盘快照）。
+     * @returns 最近一次完成的聚合文档；尚无完成聚合时 undefined。
+     */
+    lastDocOf(): UsageStatsDocument | undefined;
     /** 立刻落盘未保存的账本改动（无视节流），供插件卸载时调用；
      *  进行中的聚合先等完再存，折叠失败仍保存已成功部分。 */
     flush(): Promise<void>;

package/lib/types/client/api/balance.d.ts

@@ -5,16 +5,20 @@
 import type { ProviderBalance, ReconcileNotice } from '../../pricing-shared.ts';
 /** Path to the account-balance endpoint served by this plugin's node half. */
 export declare const BALANCE_PATH = "/api/billing/balance";
+/** 余额文档（服务端响应体的白名单切片）。 */
+export interface BalanceDocSlice {
+    balances: readonly ProviderBalance[];
+    reconcile?: ReconcileNotice;
+    /** 服务端刷新超预算：本次余额来自上一次成功的查询（issue #104）。 */
+    stale?: boolean;
+}
 /**
  * 一次拉取 `/api/billing/balance` 的完整响应（余额行 + 对账提示）。余额与对账
  * 提示来自同一响应体，拆成两个函数会导致每 30 秒对同一端点发两次请求，故合并
  * 为单次 fetch；失败返回空值（余额 []、对账 undefined），由调用方降级。
  * @returns the balances and reconcile notice (both degraded on any failure).
  */
-export declare function fetchBalanceDoc(): Promise<{
-    balances: readonly ProviderBalance[];
-    reconcile?: ReconcileNotice;
-}>;
+export declare function fetchBalanceDoc(): Promise<BalanceDocSlice>;
 /**
  * 拉取官方余额差对账提示（drift 时非空），供余额面板展示；失败返回 undefined。
  * 复用 {@link fetchBalanceDoc} 的同一响应，导出供对账提示渲染测试单独解析。

package/lib/types/client/api/http.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 插件自有端点（/api/billing/*）的统一取数封装：超时底座。
+ *
+ * 背景（issue #104）：浏览器对同源最多 6 条并发连接，而旧实现里所有 fetch
+ * 都没有超时——服务端某次响应被上游查询拖住（报告者实测 45~60s）时，这条
+ * 连接会被长期占住；多标签页各挂一条即占满连接池，宿主自己的资源请求排队，
+ * 用户看到的是「整个 DSH 界面卡死」。
+ *
+ * 超时上限必须小于轮询间隔（30s），否则「超时中的请求」会与下一轮轮询重叠，
+ * 在途请求越堆越多。
+ */
+/**
+ * 客户端取插件端点的默认超时（毫秒）：小于 30s 轮询间隔，保证不与下一轮重叠。
+ *
+ * 取 12s：服务端三条轮询路由的总预算都是 8s（余额 / 订阅额度 / 中转站额度），
+ * usage-stats 是 1.5s——12s 给服务端留了 4s 余量，又远小于 30s 的轮询间隔，
+ * 超时的请求不会与下一轮重叠（issue #104 报告者建议值同为 12s）。
+ */
+export declare const BILLING_FETCH_TIMEOUT_MS = 12000;
+/** 取数选项：在标准 RequestInit 之上加一个超时覆盖。 */
+export interface BillingFetchInit extends RequestInit {
+    /** 超时（毫秒）；缺省 {@link BILLING_FETCH_TIMEOUT_MS}。 */
+    timeoutMs?: number;
+}
+/**
+ * 带超时的 fetch（插件端点专用）。
+ *
+ * 超时以 AbortController 实现（不用 AbortSignal.timeout）：宿主 UI 跑在
+ * 浏览器里，但插件的客户端代码也会被测试与宿主内嵌环境加载，显式
+ * AbortController 在任何实现上都可用。
+ * @param path - 端点路径（相对当前源）。
+ * @param init - 请求选项；`timeoutMs` 覆盖默认超时，`signal` 透传外部取消。
+ * @returns the response; rejects when the request times out or fails.
+ */
+export declare function fetchBilling(path: string, init?: BillingFetchInit): Promise<Response>;
+//# sourceMappingURL=http.d.ts.map

package/lib/types/client/api/subscriptions.d.ts

@@ -5,9 +5,15 @@
 import type { SubscriptionQuota } from '../../pricing-shared.ts';
 /** Path to the subscription-plan quota endpoint served by this plugin's node half. */
 export declare const SUBSCRIPTIONS_PATH = "/api/billing/subscriptions";
+/** 订阅额度响应（白名单切片）。 */
+export interface SubscriptionsDoc {
+    quotas: readonly SubscriptionQuota[];
+    /** 服务端刷新超预算：额度来自上一次成功的查询（issue #104）。 */
+    stale?: boolean;
+}
 /**
  * 拉取订阅套餐剩余额度（供订阅面板）；失败返回空列表。
  * @returns the quota rows, or an empty list on any failure.
  */
-export declare function fetchSubscriptions(): Promise<readonly SubscriptionQuota[]>;
+export declare function fetchSubscriptions(): Promise<SubscriptionsDoc>;
 //# sourceMappingURL=subscriptions.d.ts.map

package/lib/types/client/domain/types.d.ts

@@ -166,6 +166,12 @@ export interface UsageBillingInjected {
 export interface UsageStats {
     /** 服务端聚合时间戳（毫秒）；旧快照可能缺失。 */
     updatedAt?: number;
+    /**
+     * 本次下发的是「上次算好的」文档（聚合超响应预算或失败时的回落）：
+     * 内存里最近一次完成的聚合，或落盘快照。面板据此提示数据滞后，
+     * 避免把旧值（如重命名前的会话标题）当成最新值读。
+     */
+    staleSnapshot?: boolean;
     /** 宿主进程时区（IANA 名 + UTC 偏移）：天按此切分，副标题据此标注；旧快照可能缺失。 */
     timezone?: {
         name: string;

package/lib/types/client/locales.d.ts

@@ -1,5 +1,5 @@
 /** Locale dictionaries for the usage billing surface. */
-export type UsageBillingKey = 'title' | 'cost' | 'todayCost' | 'monthCost' | 'yearCost' | 'monthProjected' | 'liveTurn' | 'liveSession' | 'liveSessionSub' | 'calls' | 'cacheHitRate' | 'tokens' | 'inputTokens' | 'outputTokens' | 'avgCost' | 'kpiRange' | 'avgRangeToday' | 'avgRange7d' | 'avgRangeWeek' | 'avgRangeMonth' | 'avgRangeAll' | 'trend' | 'trend7d' | 'trend30d' | 'trendMetric' | 'trendMetricCost' | 'trendMetricTokens' | 'pricingSearch' | 'bandPinHint' | 'trendEmpty' | 'trendTotal' | 'roundsUnit' | 'healthModelsLive' | 'healthVendorsDown' | 'healthVendorsUnavailable' | 'budget' | 'budgetRemain' | 'budgetAmount' | 'budgetSummary' | 'sessions' | 'sessionTitle' | 'lastActive' | 'sessionOverflow' | 'budgetTierBody' | 'models' | 'providerBilling' | 'channelUnknown' | 'directTag' | 'relayTag' | 'unknownTag' | 'unknownChannelHint' | 'planCountUnit' | 'actual' | 'pricing' | 'input' | 'output' | 'cacheHit' | 'peak' | 'offPeak' | 'flat' | 'band' | 'close' | 'footer' | 'footerCredit' | 'lastUpdated' | 'noData' | 'todayRate' | 'rateLive' | 'rateBuiltin' | 'pricingSyncedAt' | 'pricingSyncNow' | 'pricingSyncing' | 'promoBadge' | 'promoUntil' | 'promoOpenEnded' | 'pricingTip' | 'pricingUnit' | 'pricingNotes' | 'ubPeak' | 'ubOff' | 'ubStd' | 'peakBand' | 'pricingSource' | 'noteCache' | 'noteBand' | 'noteSource' | 'balance' | 'recharge' | 'rechargeHint' | 'balanceUnconfigured' | 'balanceUnauthorized' | 'balanceUnreachable' | 'uncatalogued' | 'estimatedPricing' | 'balanceDays' | 'balanceLowBody' | 'reconcileDrift' | 'reconcileDismiss' | 'subscriptionNotConfigured' | 'subscriptionUnauthorized' | 'subscriptionUnavailable' | 'subscriptionInvalid' | 'subscriptionRateLimited' | 'subscriptionSession' | 'subscriptionWeekly' | 'subscriptionMonthly' | 'subscriptionBilling' | 'subscriptionRemaining' | 'subscriptionExhausted' | 'subscriptionReset' | 'subscriptionNoApi' | 'floatWindow' | 'floatModeCombined' | 'floatModeSubscription' | 'floatMode' | 'floatTargets' | 'floatWindowHint' | 'floatPrimaryToday' | 'floatPrimaryWeek' | 'floatPrimaryMonth' | 'floatNoTargets' | 'floatNoTargetsHint' | 'cardDisplay' | 'cardDisplayHint' | 'cardMetric' | 'cardMetricMoney' | 'cardMetricTokens' | 'cardSpan' | 'cardSpanDay' | 'cardSpanWeek' | 'cardSpanMonth' | 'cardDeltaBadge' | 'cardDeltaShow' | 'cardDeltaHide' | 'triggerMonthTokens' | 'triggerTodayTokens' | 'triggerWeekTokens' | 'subscriptionsStale' | 'staleLedgerNotice' | 'unreadableNotice' | 'unreadableFormatNotice' | 'unreadableNoLedgerNotice' | 'tokenCacheWrite' | 'toolRank' | 'toolName' | 'userPrices' | 'userPricesHint' | 'userPriceSave' | 'userPriceModel' | 'userPriceSource' | 'userPriceSourceHint' | 'userPriceOffPeak' | 'userPriceNormal' | 'userPriceCurrency' | 'userPriceAdd' | 'userPriceRemoveSelected' | 'userPriceSelect' | 'sessionStaleBadge' | 'sessionUntitled' | 'sessionSubCost' | 'sessionSubCalls' | 'sessionSubRow' | 'heatmapLess' | 'heatmapMore' | 'currency' | 'currencyCny' | 'currencyUsd' | 'currencyEur' | 'language' | 'heatmap' | 'rounds' | 'roundsHint' | 'anomaly' | 'model' | 'thModel' | 'thInputMiss' | 'thInputHit' | 'costAbbr' | 'tabOverview' | 'tabTrends' | 'tabProviders' | 'tabPricing' | 'tabSettings' | 'budgetHint' | 'peakAlertHint' | 'peakAlertDescPeak' | 'peakAlertDescOff' | 'peakAlertDescPeakZhipu' | 'peakAlertDescOffZhipu' | 'export' | 'exportCsvDay' | 'exportCsvSession' | 'exportJson' | 'peakShare' | 'peakSharePerCall' | 'offPeakSavings' | 'perfMax' | 'weekCost' | 'roleCost' | 'roleUser' | 'roleAssistant' | 'roleTool' | 'roleHint' | 'tierPeak' | 'tierOff' | 'tierToPeak' | 'tierToOff' | 'tierAlertEnterPeak' | 'tierAlertEnterOff' | 'tierAlertEnterPeakZhipu' | 'tierAlertEnterOffZhipu' | 'peakAlertTitlePeak' | 'peakAlertTitleOff' | 'peakAlert' | 'peakAlertLeadMin' | 'peakAlertPos' | 'peakAlertMode' | 'peakAlertPosCorner' | 'peakAlertPosCenter' | 'peakAlertModePeak' | 'peakAlertModeOff' | 'peakAlertModeBoth' | 'peakAlertWebNotify' | 'peakAlertPreview' | 'planTypeCode' | 'planTypeToken' | 'subscriptionFeePerMonth' | 'triggerToday' | 'triggerMonth' | 'subscriptionTag' | 'cellEstimateHint' | 'free' | 'perfSamples' | 'perfTtft' | 'perfP50' | 'perfP90' | 'perfTps' | 'perfLatency' | 'perfEstimated' | 'perfEmpty' | 'perfTpsUnit' | 'perfTitle' | 'perfHint' | 'perfAll' | 'perfChartEmpty' | 'heatmapYear' | 'heatmapHalf' | 'heatmapMonth' | 'metricCost' | 'metricTokens' | 'heatmapTotal' | 'activeDays' | 'streakDays' | 'subscriptionAutoDetect' | 'pluginAuthor' | 'pluginRepository' | 'pluginNpm' | 'pluginLicense' | 'tabToken' | 'tokenExport' | 'tokenExportCsv' | 'tokenReasoningShare' | 'tokenReasoningShort' | 'tokenIo' | 'tokenPeak' | 'densityLabel' | 'densityHint' | 'densityCompact' | 'densityDefault' | 'densityComfortable' | 'motionLabel' | 'motionHint' | 'motionOff' | 'motionSubtle' | 'motionRich' | 'settingsNavDisplayPref' | 'settingsNavBudget' | 'settingsNavAlert' | 'settingsNavDisplay' | 'settingsNavAdvanced' | 'settingsNavAbout' | 'settingsSearchPlaceholder' | 'settingsSearchEmpty' | 'sessionsViewAll' | 'sessionViewerSearch' | 'modelBudgetTitle' | 'modelBudgetHint' | 'modelBudgetBody' | 'modelBudgetPlaceholder' | 'moreWorksTitle' | 'adEngramName' | 'adEngramDesc' | 'adRainbowName' | 'adRainbowDesc' | 'kpiDescCacheHit' | 'kpiDescTokens' | 'kpiDescAvgCost' | 'kpiDescCalls' | 'kpiDescReasoning' | 'kpiDescIo' | 'kpiDescPeak' | 'healthDotLive' | 'healthDotFailed' | 'healthDotUnknown' | 'settingsSectionDisplay' | 'emptyHint' | 'tokenDaily' | 'tokenByModel' | 'tokenMiss' | 'tokenHit' | 'tokenOutput' | 'tokenViewStructure' | 'tokenViewModel' | 'tokenHitShort' | 'tokenMissShort' | 'tokenTotal' | 'tokenShare' | 'usageStatsTool' | 'usageStatsToolHint' | 'balanceGranted' | 'balanceTopped' | 'balanceDaily' | 'balanceDaysLong' | 'balanceDaysUnit' | 'popTodayModel' | 'popNoConsumption' | 'popTitle' | 'popDirectLead' | 'popSubLead' | 'unpricedHint' | 'searchEstimateHint' | 'siteListDisplay' | 'siteListDisplayHint' | 'liveCostBar' | 'liveCostBarHint' | 'liveCostBarPosition' | 'liveCostBarPosBelow' | 'liveCostBarPosAbove' | 'liveCostBarPosToolbar' | 'exportCsvSite' | 'panelRelayQuota' | 'relayBalance' | 'relayNoQuota' | 'relayWindowUsed' | 'relayKindNewApi' | 'relayKindSub2Api' | 'relayKindUnknown' | 'expandAll' | 'collapseAll' | 'todayOnly' | 'todayNoConsumption';
+export type UsageBillingKey = 'title' | 'cost' | 'todayCost' | 'monthCost' | 'yearCost' | 'monthProjected' | 'liveTurn' | 'liveSession' | 'liveSessionSub' | 'calls' | 'cacheHitRate' | 'tokens' | 'inputTokens' | 'outputTokens' | 'avgCost' | 'kpiRange' | 'avgRangeToday' | 'avgRange7d' | 'avgRangeWeek' | 'avgRangeMonth' | 'avgRangeAll' | 'trend' | 'trend7d' | 'trend30d' | 'trendMetric' | 'trendMetricCost' | 'trendMetricTokens' | 'pricingSearch' | 'bandPinHint' | 'trendEmpty' | 'trendTotal' | 'roundsUnit' | 'healthModelsLive' | 'healthVendorsDown' | 'healthVendorsUnavailable' | 'budget' | 'budgetRemain' | 'budgetAmount' | 'budgetSummary' | 'sessions' | 'sessionTitle' | 'lastActive' | 'sessionOverflow' | 'budgetTierBody' | 'models' | 'providerBilling' | 'channelUnknown' | 'directTag' | 'relayTag' | 'unknownTag' | 'unknownChannelHint' | 'planCountUnit' | 'actual' | 'pricing' | 'input' | 'output' | 'cacheHit' | 'peak' | 'offPeak' | 'flat' | 'band' | 'close' | 'footer' | 'footerCredit' | 'lastUpdated' | 'noData' | 'todayRate' | 'rateLive' | 'rateBuiltin' | 'pricingSyncedAt' | 'pricingSyncNow' | 'pricingSyncing' | 'promoBadge' | 'promoUntil' | 'promoOpenEnded' | 'pricingTip' | 'pricingUnit' | 'pricingNotes' | 'ubPeak' | 'ubOff' | 'ubStd' | 'peakBand' | 'pricingSource' | 'noteCache' | 'noteBand' | 'noteSource' | 'balance' | 'recharge' | 'rechargeHint' | 'balanceUnconfigured' | 'balanceUnauthorized' | 'balanceUnreachable' | 'uncatalogued' | 'estimatedPricing' | 'balanceDays' | 'balanceLowBody' | 'reconcileDrift' | 'reconcileDismiss' | 'subscriptionNotConfigured' | 'subscriptionUnauthorized' | 'subscriptionUnavailable' | 'subscriptionInvalid' | 'subscriptionRateLimited' | 'subscriptionSession' | 'subscriptionWeekly' | 'subscriptionMonthly' | 'subscriptionBilling' | 'subscriptionRemaining' | 'subscriptionExhausted' | 'subscriptionReset' | 'subscriptionNoApi' | 'floatWindow' | 'floatModeCombined' | 'floatModeSubscription' | 'floatMode' | 'floatTargets' | 'floatWindowHint' | 'floatPrimaryToday' | 'floatPrimaryWeek' | 'floatPrimaryMonth' | 'floatNoTargets' | 'floatNoTargetsHint' | 'cardDisplay' | 'cardDisplayHint' | 'cardMetric' | 'cardMetricMoney' | 'cardMetricTokens' | 'cardSpan' | 'cardSpanDay' | 'cardSpanWeek' | 'cardSpanMonth' | 'cardDeltaBadge' | 'cardDeltaShow' | 'cardDeltaHide' | 'triggerMonthTokens' | 'triggerTodayTokens' | 'triggerWeekTokens' | 'subscriptionsStale' | 'balanceStaleNotice' | 'staleLedgerNotice' | 'staleSnapshotNotice' | 'unreadableNotice' | 'unreadableFormatNotice' | 'unreadableNoLedgerNotice' | 'tokenCacheWrite' | 'toolRank' | 'toolName' | 'userPrices' | 'userPricesHint' | 'userPriceSave' | 'userPriceModel' | 'userPriceSource' | 'userPriceSourceHint' | 'userPriceOffPeak' | 'userPriceNormal' | 'userPriceCurrency' | 'userPriceAdd' | 'userPriceRemoveSelected' | 'userPriceSelect' | 'sessionStaleBadge' | 'sessionUntitled' | 'sessionSubCost' | 'sessionSubCalls' | 'sessionSubRow' | 'heatmapLess' | 'heatmapMore' | 'currency' | 'currencyCny' | 'currencyUsd' | 'currencyEur' | 'language' | 'heatmap' | 'rounds' | 'roundsHint' | 'anomaly' | 'model' | 'thModel' | 'thInputMiss' | 'thInputHit' | 'costAbbr' | 'tabOverview' | 'tabTrends' | 'tabProviders' | 'tabPricing' | 'tabSettings' | 'budgetHint' | 'peakAlertHint' | 'peakAlertDescPeak' | 'peakAlertDescOff' | 'peakAlertDescPeakZhipu' | 'peakAlertDescOffZhipu' | 'export' | 'exportCsvDay' | 'exportCsvSession' | 'exportJson' | 'peakShare' | 'peakSharePerCall' | 'offPeakSavings' | 'perfMax' | 'weekCost' | 'roleCost' | 'roleUser' | 'roleAssistant' | 'roleTool' | 'roleHint' | 'tierPeak' | 'tierOff' | 'tierToPeak' | 'tierToOff' | 'tierAlertEnterPeak' | 'tierAlertEnterOff' | 'tierAlertEnterPeakZhipu' | 'tierAlertEnterOffZhipu' | 'peakAlertTitlePeak' | 'peakAlertTitleOff' | 'peakAlert' | 'peakAlertLeadMin' | 'peakAlertPos' | 'peakAlertMode' | 'peakAlertPosCorner' | 'peakAlertPosCenter' | 'peakAlertModePeak' | 'peakAlertModeOff' | 'peakAlertModeBoth' | 'peakAlertWebNotify' | 'peakAlertPreview' | 'planTypeCode' | 'planTypeToken' | 'subscriptionFeePerMonth' | 'triggerToday' | 'triggerMonth' | 'subscriptionTag' | 'cellEstimateHint' | 'free' | 'perfSamples' | 'perfTtft' | 'perfP50' | 'perfP90' | 'perfTps' | 'perfLatency' | 'perfEstimated' | 'perfEmpty' | 'perfTpsUnit' | 'perfTitle' | 'perfHint' | 'perfAll' | 'perfChartEmpty' | 'heatmapYear' | 'heatmapHalf' | 'heatmapMonth' | 'metricCost' | 'metricTokens' | 'heatmapTotal' | 'activeDays' | 'streakDays' | 'subscriptionAutoDetect' | 'pluginAuthor' | 'pluginRepository' | 'pluginNpm' | 'pluginLicense' | 'tabToken' | 'tokenExport' | 'tokenExportCsv' | 'tokenReasoningShare' | 'tokenReasoningShort' | 'tokenIo' | 'tokenPeak' | 'densityLabel' | 'densityHint' | 'densityCompact' | 'densityDefault' | 'densityComfortable' | 'motionLabel' | 'motionHint' | 'motionOff' | 'motionSubtle' | 'motionRich' | 'settingsNavDisplayPref' | 'settingsNavBudget' | 'settingsNavAlert' | 'settingsNavDisplay' | 'settingsNavAdvanced' | 'settingsNavAbout' | 'settingsSearchPlaceholder' | 'settingsSearchEmpty' | 'sessionsViewAll' | 'sessionViewerSearch' | 'modelBudgetTitle' | 'modelBudgetHint' | 'modelBudgetBody' | 'modelBudgetPlaceholder' | 'moreWorksTitle' | 'adEngramName' | 'adEngramDesc' | 'adRainbowName' | 'adRainbowDesc' | 'kpiDescCacheHit' | 'kpiDescTokens' | 'kpiDescAvgCost' | 'kpiDescCalls' | 'kpiDescReasoning' | 'kpiDescIo' | 'kpiDescPeak' | 'healthDotLive' | 'healthDotFailed' | 'healthDotUnknown' | 'settingsSectionDisplay' | 'emptyHint' | 'tokenDaily' | 'tokenByModel' | 'tokenMiss' | 'tokenHit' | 'tokenOutput' | 'tokenViewStructure' | 'tokenViewModel' | 'tokenHitShort' | 'tokenMissShort' | 'tokenTotal' | 'tokenShare' | 'usageStatsTool' | 'usageStatsToolHint' | 'balanceGranted' | 'balanceTopped' | 'balanceDaily' | 'balanceDaysLong' | 'balanceDaysUnit' | 'popTodayModel' | 'popNoConsumption' | 'popTitle' | 'popDirectLead' | 'popSubLead' | 'unpricedHint' | 'searchEstimateHint' | 'siteListDisplay' | 'siteListDisplayHint' | 'liveCostBar' | 'liveCostBarHint' | 'liveCostBarPosition' | 'liveCostBarPosBelow' | 'liveCostBarPosAbove' | 'liveCostBarPosToolbar' | 'exportCsvSite' | 'panelRelayQuota' | 'relayBalance' | 'relayNoQuota' | 'relayWindowUsed' | 'relayKindNewApi' | 'relayKindSub2Api' | 'relayKindUnknown' | 'expandAll' | 'collapseAll' | 'todayOnly' | 'todayNoConsumption';
 export declare const NS = "usageBilling";
 export declare const zh: Record<UsageBillingKey, string>;
 export declare const en: Record<UsageBillingKey, string>;

package/lib/types/pricing-shared.d.ts

@@ -78,6 +78,12 @@ export interface BalanceResponse {
     balances: readonly ProviderBalance[];
     /** 官方余额差对账提示（对账开启且当日有余额消费时下发）。 */
     reconcile?: ReconcileNotice;
+    /**
+     * 本次余额来自上一次成功的查询（服务端刷新超预算，issue #104）：
+     * 上游查询被拖住时不再把响应长期挂起，改为回旧值并标记，客户端据此提示
+     * 「余额数据来自上次查询」。
+     */
+    stale?: boolean;
 }
 /** 官方余额差对账提示（drift 时携带供 UI 展示的已用/本地费用）。 */
 export interface ReconcileNotice {

package/lib/types/routes/balance.d.ts

@@ -5,8 +5,9 @@
  * TokenHub 等）+ 用户自定义余额 + 声明端点 + 余额差对账。5 分钟缓存（避免
  * 每 30s 后台轮询打上游），in-flight 去重（并发请求共享同一次进行中的刷新）。
  *
- * 路由文件只关心 HTTP 缓存逻辑：5 分钟过期判定 + 失败时仍发旧缓存（不挂起
- * 已 writeHead 的响应）。上游查询（queryBalances / queryCustomBalances /
+ * 路由文件只关心 HTTP 缓存逻辑：5 分钟过期判定 + 刷新预算（超预算回旧
+ * 缓存并标 stale，不把响应挂在长查询上）+ 失败时仍发旧缓存（不挂起已
+ * writeHead 的响应）。上游查询（queryBalances / queryCustomBalances /
  * queryDeclaredEndpoints / reconcileBalanceDelta）在装配器里跑，路由只通过
  * `cached()` 与 `refreshOnce()` 拿到结果。
  */
@@ -17,6 +18,11 @@ import type { ReconcileEvent } from '../reconcile.ts';
 export interface BalanceDoc {
     balances: readonly ProviderBalance[];
     reconcile?: ReconcileEvent;
+    /**
+     * 本次余额来自上一次成功的查询（刷新超预算，见 {@link BalanceDeps.responseBudgetMs}）。
+     * 客户端据此提示「余额数据来自上次查询」，别把旧值当最新读。
+     */
+    stale?: boolean;
 }
 interface CachedBalance {
     doc: BalanceDoc;
@@ -31,6 +37,16 @@ export interface BalanceDeps {
     refreshOnce: () => Promise<void>;
     /** 5 分钟缓存间隔（毫秒）。 */
     cacheMs: number;
+    /**
+     * 刷新的总等待预算（毫秒）：超预算立刻回上一次成功的余额。
+     *
+     * 存在的理由（issue #104）：浏览器对同源最多 6 条并发连接，而余额响应被
+     * 上游查询（最坏 8s 超时 × 重试）拖住时，这条连接会被长期占住；多标签页
+     * 各挂一条即占满连接池，宿主自己的资源请求排队——用户看到的是「整个 DSH
+     * 界面卡死」。预算到期后刷新在后台继续（in-flight 去重共享同一次刷新），
+     * 下一轮轮询即可拿到新值。
+     */
+    responseBudgetMs: number;
 }
 export declare function registerBalanceRoute(ctx: Context, deps: BalanceDeps): void;
 export {};

package/lib/types/routes/relay-quotas.d.ts

@@ -21,6 +21,14 @@ export interface RelayQuotasDeps {
     refreshOnce: () => Promise<void>;
     /** 5 分钟缓存间隔（毫秒）。 */
     cacheMs: number;
+    /**
+     * 刷新的总等待预算（毫秒）：超预算立刻回上一次成功的额度（stale 标记）。
+     *
+     * 与 balance 路由同因（issue #104）：中转站不可达时（8s 超时 × 重试）响应
+     * 会被长期挂住，占着浏览器的同源连接（每源 6 条）——多标签页各挂一条即让
+     * 宿主自己的资源请求排队，界面整体卡死。
+     */
+    responseBudgetMs: number;
 }
 export declare function registerRelayQuotasRoute(ctx: Context, deps: RelayQuotasDeps): void;
 export {};

package/lib/types/routes/subscriptions.d.ts

@@ -22,6 +22,14 @@ export interface SubscriptionsDeps {
     refreshOnce: () => Promise<void>;
     /** 5 分钟缓存间隔（毫秒）。 */
     cacheMs: number;
+    /**
+     * 刷新的总等待预算（毫秒）：超预算立刻回上一次成功的额度（stale 标记）。
+     *
+     * 与 balance 路由同因（issue #104）：上游额度接口不可达时（8s 超时 × 重试）
+     * 响应会被长期挂住，占着浏览器的同源连接（每源 6 条）——多标签页各挂一条
+     * 即让宿主自己的资源请求排队，界面整体卡死。
+     */
+    responseBudgetMs: number;
 }
 export declare function registerSubscriptionsRoute(ctx: Context, deps: SubscriptionsDeps): void;
 export {};

package/lib/types/routes/usage-stats.d.ts

@@ -37,6 +37,13 @@ export interface UsageStatsDeps {
     packageVersion: string;
     /** 等待预算（毫秒）：聚合在此预算内完成就回实时数据，超预算立即回最近快照。 */
     responseBudgetMs: number;
+    /**
+     * 最近一次**已完成**的聚合文档（只读，不触发新折叠）。
+     *
+     * 超预算时的第一回落：它比磁盘快照新（磁盘快照受落盘节流影响，最多落后数分钟；
+     * 内存文档只落后一个聚合周期）。从未完成过一次聚合时 undefined，继续回落磁盘快照。
+     */
+    lastDoc?: () => Record<string, unknown> | undefined;
 }
 /** 校验一份聚合文档；返回漂移原因（null = 形状正常）。纯只读，不改 doc。 */
 export declare function usageStatsShapeError(doc: unknown): string | null;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kenz1117/dsh-ui-usage-billing",
   "description": "Usage billing dashboard for DeepSeek Harness: sidebar cost metrics plus a full dashboard modal, priced from a current multi-provider catalog with real usage aggregated from session logs.",
-  "version": "1.6.7",
+  "version": "1.6.8",
   "keywords": [
     "deepseek-harness",
     "deepseek",