@kenz1117/dsh-ui-usage-billing 1.5.0-alpha.2 → 1.5.1

package/lib/index.js

@@ -2301,7 +2301,9 @@ const BUILTIN_MODEL_KEY_ALIASES = {
 	"deepseek-v4.1-flash": "flash",
 	"deepseek-v4.1-flash-expires-on-0910": "flash",
 	"deepseek-flash": "flash",
+	"deepseek-v4.1-flash-1017": "flash",
 	"deepseek/deepseek-v4.1-flash": "flash",
+	"deepseek/deepseek-v4.1-flash-1017": "flash",
 	"deepseek/deepseek-flash": "flash",
 	"deepseek/deepseek-v4-pro": "pro",
 	"deepseek-v4-pro": "pro",
@@ -2733,6 +2735,57 @@ function workspaceNameOf(cwd) {
 	if (cwd === void 0 || cwd === "") return "—";
 	return cwd.split(/[\\/]/).filter(Boolean).at(-1) ?? "—";
 }
+/**
+* 从会话 header 提取子智能体归并标记（直接父会话 id）：`origin: "subagent"`
+* （宿主的产品分类）或 `delegationDepth > 0`（持久化委派深度）任一命中即视为
+* 子会话。子会话但 header 无 parentSession（异常数据）返回 undefined——无法
+* 归位就按顶层会话处理，保守不标。导出供测试。
+*/
+function subParentOf(meta) {
+	if (meta.origin !== "subagent" && !((meta.delegationDepth ?? 0) > 0)) return void 0;
+	const parent = meta.parentSession;
+	return typeof parent === "string" && parent !== "" ? parent : void 0;
+}
+/**
+* 给会话行补后代合计（subCost/subCalls）：按 parentId 建子索引，对每行递归
+* 汇总全部后代子会话（多级委派整链计入根对话）。纯展示层归因——不改任何
+* 总额桶（子会话费用本就在 total/byDay/byModel 里，行级只是拆出来给人看）。
+* 环引用（异常数据）按 visited 跳过，不死循环。原地修改传入行。导出供测试。
+*/
+function foldSubagentFamilies(rows) {
+	const subsOf = /* @__PURE__ */ new Map();
+	for (const row of rows) {
+		const parent = row.parentId;
+		if (parent === void 0) continue;
+		const list = subsOf.get(parent);
+		if (list !== void 0) list.push(row);
+		else subsOf.set(parent, [row]);
+	}
+	const familyOf = (id, visited) => {
+		let cost = 0;
+		let calls = 0;
+		for (const child of subsOf.get(id) ?? []) {
+			if (visited.has(child.id)) continue;
+			visited.add(child.id);
+			cost += child.cost;
+			calls += child.calls;
+			const nested = familyOf(child.id, visited);
+			cost += nested.cost;
+			calls += nested.calls;
+		}
+		return {
+			cost,
+			calls
+		};
+	};
+	for (const row of rows) {
+		const family = familyOf(row.id, /* @__PURE__ */ new Set([row.id]));
+		if (family.calls > 0) {
+			row.subCalls = family.calls;
+			if (family.cost > 0) row.subCost = family.cost;
+		}
+	}
+}
 /** TTFT 尖峰阈值（毫秒）：超过计为一次尖峰样本，用于定位服务端抖动。 */
 const PERF_SPIKE_MS = 1e4;
 /** 全零摘要（合并的恒等元）。 */
@@ -2876,6 +2929,46 @@ function perfDigestsOf(samples) {
 	};
 }
 /**
+* 账本行谁更新：{@link UsageLedgerSession.foldedAt} 新者胜（缺失视为 0 =
+* 合并语义引入前的旧行）；时刻相同比 {@link UsageLedgerSession.foldVersion}
+* （新算法胜）；再相同视为等价，取 incoming（本进程刚折出的当前视图）。
+*/
+function ledgerRowWins(incoming, existing) {
+	const at = incoming.foldedAt ?? 0;
+	const bt = existing.foldedAt ?? 0;
+	if (at !== bt) return at > bt;
+	return (incoming.foldVersion ?? 1) > (existing.foldVersion ?? 1);
+}
+/**
+* 多实例账本合并（自审计延期项：save 路径 last-writer-wins 丢写）：同一
+* DSH_HOME 下多个宿主实例各自持有内存账本，整份覆盖式落盘会让后写者抹掉
+* 先写者刚保存的行。本进程要落的文档与磁盘现存文档按会话 id 行级合并：
+* 双方都有的行按「谁更新谁胜」，仅磁盘有的行（他实例写入、本进程内存没有）
+* 原样保留——账本行从不按 seen 剪除（见 aggregateOnce 尾部注释），合并不会
+* 复活已删会话。合并只发生在落盘边界：跨实例的即时可见性仍靠重启重载，
+* 此处保证的是磁盘上不丢数据（最终一致）。
+* @param document - 本进程刚聚合出的完整账本文档。
+* @param existing - 磁盘上现存（他实例可能写入过）的账本文档。
+* @returns 合并后的文档（sessions 行序：incoming 在前、existing 独有行按原序追加）。
+*/
+function mergeUsageLedgerDocuments(document, existing) {
+	const byId = /* @__PURE__ */ new Map();
+	for (const row of existing.sessions) byId.set(row.id, row);
+	const sessions = [];
+	for (const row of document.sessions) {
+		const prev = byId.get(row.id);
+		sessions.push(prev !== void 0 && ledgerRowWins(prev, row) ? prev : row);
+		byId.delete(row.id);
+	}
+	for (const row of byId.values()) sessions.push(row);
+	const applied = document.appliedMigrations === void 0 && existing.appliedMigrations === void 0 ? void 0 : [.../* @__PURE__ */ new Set([...document.appliedMigrations ?? [], ...existing.appliedMigrations ?? []])];
+	return {
+		...document,
+		sessions,
+		...applied === void 0 ? {} : { appliedMigrations: applied }
+	};
+}
+/**
 * 账本迁移注册表。首条迁移给 1.0.6 及更早的行回填 foldVersion = 1（它们全部出自
 * header 归因算法）；perf 摘要化迁移把 v15 及更早行的逐样本 `perf` 数组转换为
 * `perfDigest`/`perfHourDigest` 摘要（日志已删的行不再被重折，迁移是它们唯一的
@@ -3236,20 +3329,20 @@ function foldInto(fold, machine, events, subscriptionProviders, officialProvider
 		const unverifiedChannel = siteBucket === "unknown";
 		const priced = !subscription && !unverifiedChannel && isPriced(modelKey);
 		if (!subscription && !isPriced(modelKey)) fold.unpricedModels.add(modelKey);
-		const entry = priced ? modelOf(modelKey) : void 0;
-		const thisCost = entry === void 0 ? void 0 : computeCostAt(entry, {
+		const entry = modelOf(modelKey);
+		const thisCost = priced ? computeCostAt(entry, {
 			input: (usage.cacheReadTokens ?? 0) + usage.inputTokens + (usage.cacheWriteTokens ?? 0),
 			cacheHit: usage.cacheReadTokens ?? 0,
 			cacheMiss: usage.inputTokens + (usage.cacheWriteTokens ?? 0),
 			output: usage.outputTokens
-		}, event.time);
+		}, event.time) : void 0;
 		foldUsage(fold.total, usage, modelKey, subscription, event.time, official, thisCost, unverifiedChannel);
 		foldUsage(usageCell(fold.byModel, modelKey), usage, modelKey, subscription, event.time, official, thisCost, unverifiedChannel);
 		foldUsage(usageCell(fold.byDay, day), usage, modelKey, subscription, event.time, official, thisCost, unverifiedChannel);
 		foldUsage(modelDayCell(fold.byDayModels, day, modelKey), usage, modelKey, subscription, event.time, official, thisCost, unverifiedChannel);
 		foldUsage(modelDaySiteCell(fold.byDayModelsSite, day, modelKey, siteBucket), usage, modelKey, subscription, event.time, official, thisCost, unverifiedChannel);
 		foldUsage(usageCell(fold.bySite, siteBucket), usage, modelKey, subscription, event.time, official, thisCost, unverifiedChannel);
-		foldUsage(usageCell(fold.byTier, tierAt(event.time)), usage, modelKey, subscription, event.time, official, thisCost, unverifiedChannel);
+		if (entry.tierSemantics !== "latency") foldUsage(usageCell(fold.byTier, tierAt(event.time)), usage, modelKey, subscription, event.time, official, thisCost, unverifiedChannel);
 		if (subscription) fold.planCalls.set(modelKey, (fold.planCalls.get(modelKey) ?? 0) + 1);
 		if (subscription) {
 			const sitePlanKey = planSiteKey(day, modelKey, siteBucket);
@@ -3410,19 +3503,21 @@ function hourPerfOf(digest) {
 * 订阅豁免），历史账本行立即失效并全量重折，配置变更即时生效（issue #37）。
 * 判定函数无法序列化，统一记为 `fn`（任何函数形态互视为同一指纹）。
 */
-function configFingerprint(subscriptionMatcher, officialProviderIds, routeAliases, searchEstimate, modelKeyAliases = {}, registeredProviders = /* @__PURE__ */ new Set()) {
+function configFingerprint(subscriptionMatcher, officialProviderIds, routeAliases, searchEstimate, modelKeyAliases = {}, registeredProviders = /* @__PURE__ */ new Set(), routeOrigins = {}) {
 	const subs = typeof subscriptionMatcher === "function" ? "fn" : [...subscriptionMatcher].sort().join(",");
 	const officials = officialProviderIds === void 0 ? "" : [...officialProviderIds].sort().join(",");
 	const aliases = Object.keys(routeAliases).sort().map((key) => `${key}=${routeAliases[key]}`).join(",");
 	const modelKeys = Object.keys(modelKeyAliases).sort().map((key) => `${key}=${modelKeyAliases[key]}`).join(",");
 	const registered = [...registeredProviders].sort().join(",");
+	const origins = Object.keys(routeOrigins).sort().map((key) => `${key}=${routeOrigins[key]}`).join(",");
 	return [
 		subs,
 		officials,
 		aliases,
 		String(searchEstimate),
 		modelKeys,
-		registered
+		registered,
+		origins
 	].join("|");
 }
 /** 会话格式拒读（宿主 SessionFormatUnsupportedError）：日志完好，仅本构建读不了。
@@ -3473,8 +3568,13 @@ function createUsageAggregator(persistence, options = {}) {
 		return routes;
 	};
 	const searchEstimate = options.searchCallEstimateCny ?? .02;
-	const foldFingerprintOf = (registered) => configFingerprint(subscriptionMatcher, officialProviderIds, routeAliases, searchEstimate, options.modelKeyAliases, registered);
-	let foldFingerprint = foldFingerprintOf(/* @__PURE__ */ new Set());
+	const routeOriginsOf = (routes) => {
+		const origins = {};
+		for (const [route, view] of Object.entries(routes)) if (view.baseURL !== void 0 && view.baseURL !== "") origins[route] = view.baseURL;
+		return origins;
+	};
+	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;
 	/** 惰性失效（价目表时序）：账本/缓存行若以「当时不可计价」的模型落盘，
 	*  而价目表现在能计价了，该行必须重折——否则显示层按实时价算出的
@@ -3486,18 +3586,20 @@ function createUsageAggregator(persistence, options = {}) {
 	*  价目表变化后未受影响行（无 unpriced 模型）依旧零读取复用。 */
 	const foldNeedsReprice = (fold) => fold.unpricedModels.some((key) => isPriced(key));
 	/** 把一份（全量或增量）折叠结果登记进 durable ledger；内容无变化时不落盘。 */
-	const recordLedger = (id, cwd, stamp, fold) => {
+	const recordLedger = (id, cwd, stamp, fold, subOf) => {
 		if (options.ledger === void 0) return;
 		const entry = {
 			id,
 			...cwd === void 0 ? {} : { cwd },
+			...subOf === void 0 ? {} : { subOf },
 			...stamp === null ? {} : { stamp },
-			foldVersion: 22,
+			foldVersion: 23,
 			fingerprint: foldFingerprint,
+			foldedAt: Date.now(),
 			fold: serializeFold(fold)
 		};
 		const row = ledger.get(id);
-		if (row === void 0 || row.stamp !== entry.stamp || row.cwd !== entry.cwd || row.foldVersion !== entry.foldVersion || row.fingerprint !== entry.fingerprint || stamp === null && JSON.stringify(row.fold) !== JSON.stringify(entry.fold) || stamp !== null && foldNeedsReprice(row.fold)) {
+		if (row === void 0 || row.stamp !== entry.stamp || row.cwd !== entry.cwd || row.subOf !== entry.subOf || row.foldVersion !== entry.foldVersion || row.fingerprint !== entry.fingerprint || stamp === null && JSON.stringify(row.fold) !== JSON.stringify(entry.fold) || stamp !== null && foldNeedsReprice(row.fold)) {
 			ledger.set(id, entry);
 			ledgerNeedsSave = true;
 		}
@@ -3557,8 +3659,8 @@ function createUsageAggregator(persistence, options = {}) {
 		const now = Date.now();
 		await ensureLedgerLoaded();
 		const registeredProviders = options.resolveRegisteredProviders?.() ?? /* @__PURE__ */ new Set();
-		foldFingerprint = foldFingerprintOf(registeredProviders);
 		const roundRoutes = routesOf(registeredProviders);
+		foldFingerprint = foldFingerprintOf(registeredProviders, roundRoutes);
 		let metas;
 		try {
 			metas = await persistence.list();
@@ -3589,12 +3691,14 @@ function createUsageAggregator(persistence, options = {}) {
 			}
 			try {
 				const cwd = meta.cwd;
+				const subOf = subParentOf(meta);
 				const ledgerRow = ledger.get(id);
-				if (ledgerRow !== void 0 && ledgerRow.stamp !== void 0 && stamp !== null && ledgerRow.stamp === stamp && (ledgerRow.foldVersion ?? 1) === 22 && ledgerRow.fingerprint === foldFingerprint && !foldNeedsReprice(ledgerRow.fold)) {
+				if (ledgerRow !== void 0 && ledgerRow.stamp !== void 0 && stamp !== null && ledgerRow.stamp === stamp && (ledgerRow.foldVersion ?? 1) === 23 && ledgerRow.fingerprint === foldFingerprint && !foldNeedsReprice(ledgerRow.fold)) {
 					const fold = deserializedFoldOf(ledgerRow.fold);
 					folds.push({
 						id,
 						...cwd === void 0 ? {} : { cwd },
+						...subOf === void 0 ? {} : { subOf },
 						fold
 					});
 					included.add(id);
@@ -3607,6 +3711,7 @@ function createUsageAggregator(persistence, options = {}) {
 					folds.push({
 						id,
 						...meta.cwd === void 0 ? {} : { cwd: meta.cwd },
+						...subOf === void 0 ? {} : { subOf },
 						fold: hit.fold
 					});
 					included.add(id);
@@ -3635,10 +3740,11 @@ function createUsageAggregator(persistence, options = {}) {
 					folds.push({
 						id,
 						...cwd === void 0 ? {} : { cwd },
+						...subOf === void 0 ? {} : { subOf },
 						fold: previous.fold
 					});
 					included.add(id);
-					recordLedger(id, cwd, stamp, previous.fold);
+					recordLedger(id, cwd, stamp, previous.fold, subOf);
 					continue;
 				}
 				const { events, inheritedEventCount } = await persistence.readFrom(meta.id, sessionLogOffsetOf(0));
@@ -3664,10 +3770,11 @@ function createUsageAggregator(persistence, options = {}) {
 				folds.push({
 					id,
 					...cwd === void 0 ? {} : { cwd },
+					...subOf === void 0 ? {} : { subOf },
 					fold
 				});
 				included.add(id);
-				recordLedger(id, cwd, stamp, fold);
+				recordLedger(id, cwd, stamp, fold, subOf);
 			} catch (error) {
 				skipped.push(id);
 				const format = isFormatUnsupportedError(error);
@@ -3691,10 +3798,11 @@ function createUsageAggregator(persistence, options = {}) {
 			for (const entry of ledger.values()) {
 				if (included.has(entry.id)) continue;
 				try {
-					const stale = (entry.foldVersion ?? 1) < 22 || entry.fingerprint !== foldFingerprint;
+					const stale = (entry.foldVersion ?? 1) < 23 || entry.fingerprint !== foldFingerprint;
 					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)
 					});
@@ -3731,7 +3839,7 @@ function createUsageAggregator(persistence, options = {}) {
 		const perfHourModel = /* @__PURE__ */ new Map();
 		const perfModelDigest = /* @__PURE__ */ new Map();
 		const perfHourDigest = /* @__PURE__ */ new Map();
-		for (const { id: sessionId, cwd, fold, staleLedger } of folds) {
+		for (const { id: sessionId, cwd, subOf, fold, staleLedger } of folds) {
 			mergeUsageInto(total, fold.total);
 			roles.userChars += fold.roles.userChars;
 			roles.toolChars += fold.roles.toolChars;
@@ -3810,12 +3918,14 @@ function createUsageAggregator(persistence, options = {}) {
 				id: sessionId,
 				...fold.title !== void 0 ? { title: fold.title } : {},
 				...cwd !== void 0 ? { cwd } : {},
+				...subOf !== void 0 ? { parentId: subOf } : {},
 				...staleLedger === true ? { stale: true } : {},
 				calls: fold.total.calls,
 				cost: fold.total.cost,
 				lastActive: fold.lastActive
 			});
 		}
+		foldSubagentFamilies(sessionRows);
 		sessionRows.sort((a, b) => b.cost - a.cost || b.lastActive - a.lastActive);
 		turnRows.sort((a, b) => b.startedAt - a.startedAt);
 		const workspaces = [...workspaceMap.values()].sort((a, b) => b.cost - a.cost || b.lastActive - a.lastActive);
@@ -6933,15 +7043,21 @@ function createFileUsageLedgerStore(ledgerPath) {
 				mode: 448
 			});
 			const commit = async () => {
+				let existing;
+				let existingDoc;
 				try {
-					const existing = await readFile(ledgerPath, "utf8");
-					JSON.parse(existing);
-					await writeFileAtomic(`${ledgerPath}.bak`, existing, {
-						mode: 384,
-						dirMode: 448
-					});
-				} catch {}
-				await writeFileAtomic(ledgerPath, JSON.stringify(document), {
+					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
 				});
@@ -7665,69 +7781,78 @@ function apply(ctx, config = {}) {
 		at: 0,
 		doc: { balances: [] }
 	};
+	let balanceInflight;
+	const refreshBalance = async () => {
+		const piProviders = await readPiAiProviders(ctx.settings);
+		const providers = { ...piProviders };
+		const deepseekKey = providers["deepseek"]?.apiKeyEnv;
+		if (deepseekKey === void 0 || deepseekKey === "") providers["deepseek"] = {
+			...providers["deepseek"],
+			apiKeyEnv: config.balanceApiKeyEnv ?? DEFAULT_BALANCE_API_KEY_ENV
+		};
+		const balances = await queryBalances(ctx, providers);
+		const custom = await queryCustomBalances(ctx, config.customBalances ?? []);
+		const declared = await queryDeclaredEndpoints(ctx, piProviders, config.declaredEndpoints ?? []);
+		for (const row of [
+			...balances,
+			...custom,
+			...declared
+		]) if (row.error === "unauthorized") warnAuthOnce("balance", row.provider, row.displayName);
+		const official = balances.find((row) => row.provider === "deepseek");
+		let reconcile;
+		const reconcilable = official !== void 0 && official.totalBalance !== void 0 && (official.currency === void 0 || official.currency.toUpperCase() === "CNY");
+		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 {}
+			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: [
+				...balances,
+				...custom,
+				...declared
+			],
+			...reconcile === void 0 ? {} : { reconcile }
+		};
+		balanceCache = {
+			at: Date.now(),
+			doc
+		};
+	};
+	const refreshBalanceOnce = () => {
+		balanceInflight ??= refreshBalance().finally(() => {
+			balanceInflight = void 0;
+		});
+		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" });
-			const piProviders = await readPiAiProviders(ctx.settings);
-			const providers = { ...piProviders };
-			const deepseekKey = providers["deepseek"]?.apiKeyEnv;
-			if (deepseekKey === void 0 || deepseekKey === "") providers["deepseek"] = {
-				...providers["deepseek"],
-				apiKeyEnv: config.balanceApiKeyEnv ?? DEFAULT_BALANCE_API_KEY_ENV
-			};
 			if (Date.now() - balanceCache.at < BALANCE_CACHE_MS) {
 				res.end(JSON.stringify(balanceCache.doc));
 				return;
 			}
 			try {
-				const balances = await queryBalances(ctx, providers);
-				const custom = await queryCustomBalances(ctx, config.customBalances ?? []);
-				const declared = await queryDeclaredEndpoints(ctx, piProviders, config.declaredEndpoints ?? []);
-				for (const row of [
-					...balances,
-					...custom,
-					...declared
-				]) if (row.error === "unauthorized") warnAuthOnce("balance", row.provider, row.displayName);
-				const official = balances.find((row) => row.provider === "deepseek");
-				let reconcile;
-				const reconcilable = official !== void 0 && official.totalBalance !== void 0 && (official.currency === void 0 || official.currency.toUpperCase() === "CNY");
-				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 {}
-					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: [
-						...balances,
-						...custom,
-						...declared
-					],
-					...reconcile === void 0 ? {} : { reconcile }
-				};
-				balanceCache = {
-					at: Date.now(),
-					doc
-				};
-				res.end(JSON.stringify(doc));
+				await refreshBalanceOnce();
 			} catch (error) {
 				console.warn("[usage-billing] refreshBalances failed; serving cached balances:", error);
-				res.end(JSON.stringify(balanceCache.doc));
 			}
+			res.end(JSON.stringify(balanceCache.doc));
 		}
 	}), "usage-billing: balance route");
 	ctx.effect(() => ctx.webServer.register({
@@ -7822,6 +7947,13 @@ function apply(ctx, config = {}) {
 			quotas: rows
 		};
 	};
+	let quotasInflight;
+	const refreshQuotasOnce = () => {
+		quotasInflight ??= refreshQuotas().finally(() => {
+			quotasInflight = void 0;
+		});
+		return quotasInflight;
+	};
 	ctx.effect(() => ctx.webServer.register({
 		kind: "exact",
 		path: "/api/billing/subscriptions",
@@ -7829,7 +7961,7 @@ function apply(ctx, config = {}) {
 			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 refreshQuotas();
+				await refreshQuotasOnce();
 			} catch (error) {
 				console.warn("[usage-billing] refreshQuotas failed; serving cached quotas:", error);
 			}
@@ -7858,6 +7990,13 @@ function apply(ctx, config = {}) {
 			quotas: await queryRelayQuotas(ctx, routes)
 		};
 	};
+	let relayInflight;
+	const refreshRelayOnce = () => {
+		relayInflight ??= refreshRelay().finally(() => {
+			relayInflight = void 0;
+		});
+		return relayInflight;
+	};
 	ctx.effect(() => ctx.webServer.register({
 		kind: "exact",
 		path: "/api/billing/relay-quotas",
@@ -7865,7 +8004,7 @@ function apply(ctx, config = {}) {
 			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 refreshRelay();
+				await refreshRelayOnce();
 			} catch (error) {
 				console.warn("[usage-billing] refreshRelay failed; serving cached relay quotas:", error);
 			}
@@ -7880,6 +8019,7 @@ function apply(ctx, config = {}) {
 			}));
 		}
 	}), "usage-billing: relay-quotas route");
+	let statsBodyCache;
 	ctx.effect(() => ctx.webServer.register({
 		kind: "exact",
 		path: "/api/billing/usage-stats",
@@ -7892,6 +8032,19 @@ function apply(ctx, config = {}) {
 				...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));
@@ -7907,7 +8060,7 @@ function apply(ctx, config = {}) {
 				console.error("[usage-billing] usage-stats aggregate failed, falling back to snapshot:", error);
 			}
 			if (fresh !== void 0) {
-				res.end(JSON.stringify(decorate(fresh)));
+				res.end(statsBodyOf(fresh));
 				return;
 			}
 			for (const candidate of candidates) {

package/lib/types/aggregate.d.ts

@@ -389,6 +389,17 @@ export interface SessionUsageRow {
     title?: string;
     /** 会话创建时的工作目录（项目路径）；未知时缺失。 */
     cwd?: string;
+    /**
+     * 直接父会话 id（仅子智能体会话携带）：宿主 header 的 `origin: "subagent"`
+     * 会话经 parentSession 指向委派它的对话。fork/resume 的种子血缘
+     * （isSeeded）不满足子智能体门，不带本字段。旧宿主 header 无标记，
+     * 按顶层会话处理。
+     */
+    parentId?: string;
+    /** 全部后代子会话的费用合计（人民币元，多级委派整链递归）；无后代或后代全免费时缺失。 */
+    subCost?: number;
+    /** 全部后代子会话的调用数；无后代时缺失。 */
+    subCalls?: number;
     calls: number;
     cost: number;
     /** 最后一个事件的时间戳（毫秒）。 */
@@ -396,6 +407,20 @@ export interface SessionUsageRow {
     /** 数据来自旧算法折叠的持久账本行（日志已删/不可读，无法重算）；UI 据此标注置信度。 */
     stale?: boolean;
 }
+/**
+ * 从会话 header 提取子智能体归并标记（直接父会话 id）：`origin: "subagent"`
+ * （宿主的产品分类）或 `delegationDepth > 0`（持久化委派深度）任一命中即视为
+ * 子会话。子会话但 header 无 parentSession（异常数据）返回 undefined——无法
+ * 归位就按顶层会话处理，保守不标。导出供测试。
+ */
+export declare function subParentOf(meta: SessionHeader): string | undefined;
+/**
+ * 给会话行补后代合计（subCost/subCalls）：按 parentId 建子索引，对每行递归
+ * 汇总全部后代子会话（多级委派整链计入根对话）。纯展示层归因——不改任何
+ * 总额桶（子会话费用本就在 total/byDay/byModel 里，行级只是拆出来给人看）。
+ * 环引用（异常数据）按 visited 跳过，不死循环。原地修改传入行。导出供测试。
+ */
+export declare function foldSubagentFamilies(rows: SessionUsageRow[]): void;
 /** 每轮费用明细行：仪表盘「每轮费用」图的数据源。 */
 export interface TurnUsageRow {
     /** 会话 id（字符串形式）：不同会话的轮次号相互独立，展示时需区分。 */
@@ -563,6 +588,12 @@ export interface SerializedSessionFold {
 export interface UsageLedgerSession {
     id: string;
     cwd?: string;
+    /**
+     * 子智能体归并标记（直接父会话 id）：仅宿主 header 带 `origin: "subagent"`
+     * 的会话行携带。日志已删、只剩账本行时仍能归位到父对话；缺失 = 顶层会话
+     * （含 fork/resume 血缘）。可选字段，旧账本行缺失按顶层处理，无需迁移。
+     */
+    subOf?: string;
     /** Stable log stamp (mtime + size) when the persistence backend exposes it. */
     stamp?: string;
     /**
@@ -575,6 +606,12 @@ export interface UsageLedgerSession {
      * 更早写入的行（配置不参与复用判定）；与当前指纹不一致的行不复用、全量重折。
      */
     fingerprint?: string;
+    /**
+     * 该行最近一次折叠落盘的时刻（epoch 毫秒）。多实例共享同一账本文件时，
+     * save 侧按它做行级合并（后折覆盖先折），防止整份覆盖式落盘丢掉另一实例
+     * 刚写入的行；缺失 = 合并语义引入前的旧行，视为最旧。
+     */
+    foldedAt?: number;
     fold: SerializedSessionFold;
 }
 /** On-disk durable usage ledger. Versioned independently from the dashboard document. */
@@ -585,6 +622,19 @@ export interface UsageLedgerDocument {
     /** 已应用的一次性配置迁移 id 列表（随文档落盘；缺省 = 尚未跑过任何迁移）。 */
     appliedMigrations?: string[];
 }
+/**
+ * 多实例账本合并（自审计延期项：save 路径 last-writer-wins 丢写）：同一
+ * DSH_HOME 下多个宿主实例各自持有内存账本，整份覆盖式落盘会让后写者抹掉
+ * 先写者刚保存的行。本进程要落的文档与磁盘现存文档按会话 id 行级合并：
+ * 双方都有的行按「谁更新谁胜」，仅磁盘有的行（他实例写入、本进程内存没有）
+ * 原样保留——账本行从不按 seen 剪除（见 aggregateOnce 尾部注释），合并不会
+ * 复活已删会话。合并只发生在落盘边界：跨实例的即时可见性仍靠重启重载，
+ * 此处保证的是磁盘上不丢数据（最终一致）。
+ * @param document - 本进程刚聚合出的完整账本文档。
+ * @param existing - 磁盘上现存（他实例可能写入过）的账本文档。
+ * @returns 合并后的文档（sessions 行序：incoming 在前、existing 独有行按原序追加）。
+ */
+export declare function mergeUsageLedgerDocuments(document: UsageLedgerDocument, existing: UsageLedgerDocument): UsageLedgerDocument;
 /**
  * 折叠算法版本：归账语义变化时递增。v1 = 按 request/header 归账（稀疏 header 把
  * 两次 header 之间的用量串到上一个模型，订阅模型首当其冲，issue #14）；v2 =
@@ -599,7 +649,7 @@ export interface UsageLedgerDocument {
  * 会话费用只剩最近一段，issue #29）。
  * 持久账本行据此区分新旧算法：日志已删/不可读而只能沿用旧行时，UI 标注置信度提示。
  */
-export declare const FOLD_VERSION = 22;
+export declare const FOLD_VERSION = 23;
 /**
  * 一次性账本迁移：id 唯一，apply 在加载边界对原始文档执行，已应用过的跳过。
  * 未来账本/schema 字段变更（重命名、拆桶、语义调整）时，在此追加一条迁移并
@@ -695,7 +745,7 @@ export interface SessionUsageSummary {
  * 订阅豁免），历史账本行立即失效并全量重折，配置变更即时生效（issue #37）。
  * 判定函数无法序列化，统一记为 `fn`（任何函数形态互视为同一指纹）。
  */
-export declare function configFingerprint(subscriptionMatcher: SubscriptionMatcher, officialProviderIds: ReadonlySet<string> | undefined, routeAliases: Readonly<Record<string, string>>, searchEstimate: number, modelKeyAliases?: Readonly<Record<string, string>>, registeredProviders?: ReadonlySet<string>): string;
+export declare function configFingerprint(subscriptionMatcher: SubscriptionMatcher, officialProviderIds: ReadonlySet<string> | undefined, routeAliases: Readonly<Record<string, string>>, searchEstimate: number, modelKeyAliases?: Readonly<Record<string, string>>, registeredProviders?: ReadonlySet<string>, routeOrigins?: Readonly<Record<string, string>>): string;
 /**
  * Create the incremental usage aggregator.
  * @param persistence - the session persistence service.

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

@@ -178,6 +178,15 @@ interface SessionBillingRow {
     id: string;
     title?: string;
     cwd?: string;
+    /**
+     * 直接父会话 id（仅子智能体会话携带）：宿主把子智能体落成独立会话，
+     * header 的 origin: subagent + parentSession 指向委派它的对话。
+     */
+    parentId?: string;
+    /** 全部后代子会话费用合计（服务端递归算好）；无后代时缺失。 */
+    subCost?: number;
+    /** 全部后代子会话调用数；无后代时缺失。 */
+    subCalls?: number;
     /** 数据来自旧算法折叠的持久账本行（原始日志已删，无法重算）。 */
     stale?: boolean;
     calls: number;
@@ -187,6 +196,8 @@ interface SessionBillingRow {
     mergedCount?: number;
     /** 合并组的段明细（展示层专用）：一级行默认收起，展开后逐段显示。合并函数需 push，故非 readonly。 */
     children?: SessionBillingRow[];
+    /** 挂到本组下的子智能体行（展示层专用）：与段明细并列展开，带子智能体徽标。 */
+    subs?: SessionBillingRow[];
 }
 /** Usage stats structure from `.dsh-usage-stats.json`. */
 export interface UsageStats {