dsh-token-total 1.1.4 → 1.1.6

package/README.md

@@ -60,7 +60,7 @@ DSH（DeepSeek Harness）Web 插件：**Token 用量统计看板** + **单会话
   - 两张卡都由会话明细轮询驱动（每 1.5 秒一次），不额外起计时器；旧宿主只提供其中一份数据时，另一张卡显示空态而非整组消失，两份都缺时整组不渲染。窄视口下自动上下堆叠。
 
 - 浅色页面两行统计卡：第一行请求数量（附失败数）、总 tokens（附精确值）、缓存命中率（附命中 token）、token 速度（附平均首 token）；第二行输入、输出、缓存读取、缓存写入四个 token 桶。不显示费用。
-- 子代理明细使用每个子代理的**真实名称**（取自子代理标签，缺失时回退到会话标题、工作目录或会话 id）。
+- 子代理明细与请求记录使用每个子代理的**真实名称**：优先子代理自身标签，再取最新非空会话标题；旧 CLI 记录缺少标题时，读取本次会话树中实际父会话的 `subagent/catalog` 任务标签，最后才回退到日志头名称、工作目录或会话 id。只使用各日志的自有事件，不把继承的父标题／目录当作自身名称，不改写历史日志，也不改变 Token 统计。若直接打开旧子会话、实际父会话不在本次读取树中，则保留原有回退名称。
 - 中部为等宽、等高的 **子代理明细** 与 **按模型明细**；窄视口自动堆叠。使用固定列布局而非横向滚动，长名称省略并可悬浮查看全名，token 数同样可悬浮查看精确值。按模型明细的名称使用模型选择器的**显示名称**（路由 id 保留在悬浮提示中，无法解析时回退为 id）；当多行显示名称相同（忽略大小写与分隔符）时，在名称下方用灰色小字标明各自供应商以便区分。
 - 请求记录按**轮**折叠（压缩调用归入独立分组），**默认全部折叠**；展开某一轮可查看该轮每一次请求的时间、模型、tokens、命中率、状态与入 / 出 / 读 / 写明细，支持单组展开和全部展开 / 收起。失败尝试、实际重试、压缩调用纳入统计；仅继承的父会话历史不重复计算。
 - 页面每 1.5 秒串行读取当前会话明细，切换或离开 tab 会取消请求和计时器。统计含本会话及所有后代的自有历史日志，缺失的首 token / 速度显示 `—`，读取错误保留上次成功结果。
@@ -88,7 +88,9 @@ dsh plugin --profile <profile> add "file:D:\work\dsh-token-total"
 - **事件来源**：`sessionPersistence` 的会话日志。兼容 `assistant/message` 的顶层 `usage`，也读取消息及失败 `assistant/attempt` 的原始流式用量；同一次请求以最后一份用量为准，修正值按差额更新。插件订阅 `session/event` 实时增量累加，同时一次性回扫已有历史会话；`llm/retry-started` 会清空当前 `(turn, step)` 槽位，因此失败尝试和后续重试分别计入，不重复累加同一次请求的多份报告。
 - **本地持久化**：聚合结果写入 storage-domain 的 `token_total_history` 域（`$DSH_HOME/storages/` 下），纯本地、无外部依赖。回扫游标按会话记录已消费的事件序号，重启后从断点继续。
 - **上下文与花费估算**：两张卡都从该会话自身的日志重放「下一次请求会带上什么」——被 `compaction/prune` / `compaction/summary` 遮蔽的事件剔除、压缩摘要按注入记忆回放、工具目录取最近一次 `request/header`——再按字符类估算 token（ASCII 约 4 字符 / token，CJK 约 1 token / 字符），所以分桶上的数字都是近似值。左卡的真实占用取最近一次回答上报的 `totalTokens − outputTokens`；仅当两者相差超过 15%（说明上游有压缩或裁剪，日志里的历史比模型实际收到的多）时，才多出一行说明，并把「已用上下文」改用供应商实测值。右卡的分桶是「每次请求重放内容之和」，圆环中心的总量与缓存命中率直接取自 `usage` 记录，保持精确。
-- **单会话统计**：不走聚合存储（那里没有会话维度），而是按需重放该会话及全部子孙会话的自有日志；已加载会话优先使用实时事件快照，避免持久化缓冲造成漏算。结果缓存 4 秒，任意会话的新事件都会使缓存失效，包含此前尚未发现的子会话。前端从首次读取起每 4 秒刷新，显示时使用原生实时主会话用量、主会话压缩调用用量与子树用量之和，胶囊与弹窗共用同一口径；切换会话时立即清除旧会话读数。读取失败不会把部分子树当作成功结果覆盖已有读数。
+- **单会话统计**：不走聚合存储（那里没有会话维度），而是按需重放该会话及全部子孙会话的自有日志；已加载会话优先使用实时事件快照，避免持久化缓冲造成漏算。日志结果返回后以主会话与全部子树的自有用量为准，压缩调用已包含其中，胶囊与弹窗共用同一口径；尚未获得日志结果时回退到原生主会话投影。
+- **会话统计缓存**：完整结果使用最多 64 项的 LRU 缓存，60 秒到期且命中不续期。新事件只失效发生变化的会话及相关祖先，支持尚未出现在持久化目录中的子／孙会话；父链信息不足时保守失效，避免漏算。没有事件订阅接口的旧宿主仍每 4 秒重新校验。同一会话树、同一数据源的普通并发请求共用一次计算；显式取消信号保持独立。失败、取消或不完整的计算均不缓存，后续请求可以重试缺失的日志。
+- **会话统计刷新**：前台首次读取，并在每次请求完成后等待 4 秒再轮询；会话签名变化时即时刷新，慢请求期间的变化合并为一次追刷。页面隐藏时暂停后续轮询，恢复可见时立即刷新；切换或卸载会取消浏览器请求，并丢弃迟到的旧响应。相同结果不重复写入 React 状态。根日志或目录读取失败保留上次读数；部分子树不可读时显示可读用量与不完整标记，不把漏读当作完整统计。浏览器取消不等于取消宿主端已经开始的统计计算。
 - **缓存命中率** = 缓存命中 token ÷ 输入 token 总量（命中 + 未命中）。
 - **失败数量**：以宿主记录的 `assistant/attempt` 事件为准。宿主只有在流以错误结束、或调用在提交任何内容之前被取消时才写 `assistant/attempt`，其余调用一律写 `assistant/message`，两者恰好划分全部调用，所以该事件就是「一次失败的 provider 调用」的精确边界（`interrupted: true` 但已有内容的 `assistant/message` 不计为失败）。失败数是请求数的子集，不额外计入请求；失败调用若在流中断前已上报用量，token 仍按用量计入、不会丢失。该计数晚于日 / 小时两份游标引入，因此老版本升级后会额外做一次只写失败数的增量回扫（`failuresReady` 标记完成，不重复累加 token）。
 

package/lib/client.js

@@ -29423,8 +29423,8 @@ window.__ModuleLoader__.load({
 		*  every subagent session delegated from it. The native `tokenUsage` projection
 		*  covers only the main agent, so this is what makes a delegating session's
 		*  cost visible. */
-		async function fetchSessionUsage(sessionId) {
-			return post("session", { sessionId });
+		async function fetchSessionUsage(sessionId, signal) {
+			return post("session", { sessionId }, signal);
 		}
 		/** Log-owned requests and live route states for the per-session Usage view. */
 		async function fetchSessionDetail(sessionId, signal) {
@@ -31550,8 +31550,9 @@ window.__ModuleLoader__.load({
 		//#region src/client/use-session-usage.ts
 		/** The composer row's window onto the whole session tree. The native usage
 		* projection only moves for main-agent calls, so poll the displayed session
-		* even before its first child appears. Requests are serialized and late answers
-		* from a previous session are discarded. Failures keep the last good reading. */
+		* even before its first child appears. Hidden pages pause; slow responses do
+		* not queue timer retries. Disposed requests are aborted and late answers are
+		* discarded. Failures keep the last good reading. */
 		const SESSION_POLL_MS = 4e3;
 		function useSessionUsage(sessionId, signature) {
 			const [reading, setReading] = (0, react.useState)(null);
@@ -31559,34 +31560,61 @@ window.__ModuleLoader__.load({
 			(0, react.useEffect)(() => {
 				if (typeof sessionId !== "string" || sessionId === "") return;
 				let active = true;
-				let pending = false;
 				let again = false;
+				let lastResult;
+				let timer;
+				let controller;
+				const visible = () => typeof document === "undefined" || document.visibilityState !== "hidden";
+				const clearTimer = () => {
+					if (timer !== void 0) clearTimeout(timer);
+					timer = void 0;
+				};
 				const request = () => {
-					if (!active) return;
-					if (pending) {
+					if (!active || !visible()) return;
+					if (controller !== void 0) {
 						again = true;
 						return;
 					}
-					pending = true;
-					fetchSessionUsage(sessionId).then((tree) => {
-						if (active) setReading({
-							sessionId,
-							tree
-						});
+					clearTimer();
+					const current = new AbortController();
+					controller = current;
+					fetchSessionUsage(sessionId, current.signal).then((tree) => {
+						if (!active || controller !== current || current.signal.aborted) return;
+						const result = JSON.stringify(tree);
+						if (result !== lastResult) {
+							lastResult = result;
+							setReading({
+								sessionId,
+								tree
+							});
+						}
 					}).catch(() => {}).finally(() => {
-						pending = false;
-						if (active && again) {
+						if (controller !== current) return;
+						controller = void 0;
+						if (!active || !visible()) return;
+						if (again) {
 							again = false;
 							request();
-						}
+						} else timer = setTimeout(request, SESSION_POLL_MS);
 					});
 				};
+				const onVisibility = () => {
+					clearTimer();
+					if (!visible()) {
+						again = false;
+						controller?.abort();
+						controller = void 0;
+					} else request();
+				};
 				refresh.current = request;
-				const handle = setInterval(request, SESSION_POLL_MS);
+				if (typeof document !== "undefined") document.addEventListener("visibilitychange", onVisibility);
 				return () => {
 					active = false;
 					refresh.current = null;
-					clearInterval(handle);
+					clearTimer();
+					controller?.abort();
+					controller = void 0;
+					if (typeof document !== "undefined") document.removeEventListener("visibilitychange", onVisibility);
 				};
 			}, [sessionId]);
 			(0, react.useEffect)(() => {

package/lib/index.js

@@ -1593,7 +1593,7 @@ async function readSession(persistence, id, header, live, signal) {
 	}
 	throw new Error("no readable persistence seam (need open or inspect)");
 }
-async function readUsageTree(persistence, sessions, rootId, signal) {
+async function readUsageTree(persistence, sessions, rootId, signal, onCatalog) {
 	signal?.throwIfAborted();
 	const rows = await persistence.list(typeof persistence.open === "function" ? signal === void 0 ? void 0 : { signal } : signal);
 	const headers = /* @__PURE__ */ new Map();
@@ -1603,11 +1603,14 @@ async function readUsageTree(persistence, sessions, rootId, signal) {
 	}
 	const live = new Map((sessions?.list() ?? []).map((handle) => [handle.id, handle]));
 	const children = /* @__PURE__ */ new Map();
+	const parents = /* @__PURE__ */ new Map();
+	for (const id of [...headers.keys(), ...live.keys()]) parents.set(id, /* @__PURE__ */ new Set());
 	const link = (id, parent) => {
 		if (typeof parent !== "string" || parent === "" || parent === id) return;
 		const bucket = children.get(parent) ?? /* @__PURE__ */ new Set();
 		bucket.add(id);
 		children.set(parent, bucket);
+		parents.get(id)?.add(parent);
 	};
 	for (const header of headers.values()) link(header.id, header.parentSession);
 	for (const handle of live.values()) link(handle.id, handle.header?.parentSession ?? handle.parentSession);
@@ -1620,6 +1623,10 @@ async function readUsageTree(persistence, sessions, rootId, signal) {
 		ids.push(id);
 		queue.push(id);
 	}
+	onCatalog?.({
+		parents,
+		members: seen
+	});
 	const root = await readSession(persistence, rootId, headers.get(rootId), live.get(rootId), signal);
 	const logs = new Array(ids.length);
 	const issues = new Array(ids.length);
@@ -2217,8 +2224,11 @@ function nameOf(h, id) {
 	if (typeof x?.cwd === "string" && x.cwd) return x.cwd.split(/[\\/]/).filter(Boolean).pop() || id;
 	return id;
 }
-function one(log) {
-	const { id, header, live, events, inheritedCut: cut } = log;
+function ownEventsOf(log) {
+	return log.events.filter((e) => !(log.inheritedCut > 0 && typeof e.seq === "number" && e.seq < log.inheritedCut));
+}
+function one(log, parentCatalogLabel) {
+	const { id, header, live } = log;
 	const fold = new UsageFold();
 	const totals = zero$1();
 	const records = [];
@@ -2229,15 +2239,14 @@ function one(log) {
 	let effort = "";
 	let pendingTopic = "";
 	const turnTopics = /* @__PURE__ */ new Map();
-	const own = events.filter((e) => !(cut > 0 && typeof e.seq === "number" && e.seq < cut));
+	const own = ownEventsOf(log);
 	let label = "", title = "";
 	for (const ev of own) {
 		const d = ev.data ?? {};
 		if (!label && ev.type === "subagent/descriptor" && typeof d.label === "string" && d.label.trim()) label = d.label.trim();
-		if (!title && ev.type === "session/title" && typeof d.title === "string" && d.title.trim()) title = d.title.trim();
-		if (label && title) break;
+		if (ev.type === "session/title" && typeof d.title === "string" && d.title.trim()) title = d.title.trim();
 	}
-	const name = label || title || nameOf(header, id);
+	const name = label || title || parentCatalogLabel || nameOf(header, id);
 	const stepTokens = /* @__PURE__ */ new Map();
 	const closedSteps = /* @__PURE__ */ new Set();
 	for (const ev of own) {
@@ -2418,7 +2427,21 @@ function one(log) {
 }
 async function buildSessionUsageDetail(persistence, sessions, rootId, ctx) {
 	const { root, descendants, coverage } = await readUsageTree(persistence, sessions, rootId);
-	const parts = [root, ...descendants].map(one);
+	const logs = [root, ...descendants];
+	const catalogLabels = /* @__PURE__ */ new Map();
+	for (const log of logs) {
+		const labels = /* @__PURE__ */ new Map();
+		for (const event of ownEventsOf(log)) {
+			if (event.type !== "subagent/catalog") continue;
+			const data = event.data;
+			if (typeof data?.childId === "string" && data.childId && typeof data.label === "string" && data.label.trim()) labels.set(data.childId, data.label.trim());
+		}
+		catalogLabels.set(log.id, labels);
+	}
+	const parts = logs.map((log) => {
+		const parentId = log.header?.parentSession ?? log.live?.header?.parentSession ?? log.live?.parentSession;
+		return one(log, parentId === void 0 ? void 0 : catalogLabels.get(parentId)?.get(log.id));
+	});
 	const totals = zero$1();
 	const models = /* @__PURE__ */ new Map();
 	const records = parts.flatMap((x) => x.records);
@@ -2921,25 +2944,99 @@ function sumOneSession(log) {
 		compaction
 	};
 }
-const CACHE_TTL_MS = 4e3;
+const CACHE_TTL_MS = 6e4;
 const CACHE_MAX = 64;
 var SessionUsageService = class {
+	cacheTtlMs;
 	cache = /* @__PURE__ */ new Map();
-	generation = 0;
-	/** New events can introduce descendants of any cached root. */
-	invalidate(_sessionId) {
-		this.generation++;
-		this.cache.clear();
-	}
-	/** A bad descendant leaves the readable totals available with coverage.
-	* Never cache incomplete results: a repaired log must recover on the next read.
-	* Root, catalog and cancellation failures still reject without publishing zero. */
+	parents = /* @__PURE__ */ new Map();
+	catalogVersion = 0;
+	catalogOrder = 0;
+	appliedCatalogOrder = 0;
+	reads = /* @__PURE__ */ new Set();
+	inFlight = /* @__PURE__ */ new Map();
+	/** Events keep live trees fresh; the TTL bounds out-of-band catalog changes.
+	* Hosts without a live event hook can select the old four-second fallback. */
+	constructor(cacheTtlMs = CACHE_TTL_MS) {
+		this.cacheTtlMs = cacheTtlMs;
+	}
+	/** Invalidate the changed session and every old/new ancestor, not other trees.
+	* null is a known root; undefined means parent metadata was not supplied.
+	* An unknown parent chain conservatively falls back instead of missing a new
+	* child that appeared before the persistence catalog caught up. */
+	invalidate(sessionId, parentSession) {
+		this.catalogVersion++;
+		const previous = this.parents.get(sessionId);
+		const queue = [...previous ?? []];
+		let uncertain = previous === void 0 && parentSession === void 0;
+		if (parentSession !== void 0) {
+			const current = /* @__PURE__ */ new Set();
+			if (parentSession !== null && parentSession !== "" && parentSession !== sessionId) current.add(parentSession);
+			if (previous !== void 0) this.parents.set(sessionId, current);
+			queue.push(...current);
+		}
+		const affected = /* @__PURE__ */ new Set([sessionId]);
+		for (let index = 0; index < queue.length; index++) {
+			const id = queue[index];
+			if (affected.has(id)) continue;
+			affected.add(id);
+			const ancestors = this.parents.get(id);
+			if (ancestors === void 0) uncertain = true;
+			else queue.push(...ancestors);
+		}
+		const touches = (read) => {
+			if (affected.has(read.rootId)) return true;
+			for (const id of affected) if (read.members.has(id)) return true;
+			return false;
+		};
+		for (const [rootId, entry] of this.cache) if (uncertain || touches(entry.read)) this.cache.delete(rootId);
+		for (const read of this.reads) if (!read.catalogReady || uncertain || touches(read)) read.invalidated = true;
+	}
+	/** A bad descendant leaves readable totals available, but is never cached.
+	* Signal-less browser requests share one cold read per root. Explicit signals
+	* retain independent ownership and are passed through unchanged: aborting one
+	* caller cannot cancel another caller's readers or publish its partial totals. */
 	async tree(persistence, sessions, rootId, signal) {
 		signal?.throwIfAborted();
 		const hit = this.cache.get(rootId);
-		if (hit !== void 0 && Date.now() - hit.at < CACHE_TTL_MS) return hit.value;
-		const generation = this.generation;
-		const { root, descendants, coverage } = await readUsageTree(persistence, sessions, rootId, signal);
+		if (hit !== void 0 && hit.read.persistence === persistence && hit.read.sessions === sessions && Date.now() - hit.at < this.cacheTtlMs) {
+			this.cache.delete(rootId);
+			this.cache.set(rootId, hit);
+			return hit.value;
+		}
+		this.cache.delete(rootId);
+		const pending = this.inFlight.get(rootId);
+		if (signal === void 0 && pending !== void 0 && !pending.read.invalidated && pending.read.persistence === persistence && pending.read.sessions === sessions) return pending.promise;
+		const read = {
+			rootId,
+			persistence,
+			sessions,
+			members: /* @__PURE__ */ new Set([rootId]),
+			invalidated: false,
+			catalogReady: false,
+			catalogVersion: this.catalogVersion,
+			catalogOrder: ++this.catalogOrder
+		};
+		this.reads.add(read);
+		const promise = this.compute(read, signal).finally(() => {
+			this.reads.delete(read);
+			if (this.inFlight.get(rootId)?.read === read) this.inFlight.delete(rootId);
+		});
+		if (signal === void 0) this.inFlight.set(rootId, {
+			read,
+			promise
+		});
+		return promise;
+	}
+	async compute(read, signal) {
+		const { root, descendants, coverage } = await readUsageTree(read.persistence, read.sessions, read.rootId, signal, (catalog) => {
+			read.members = catalog.members;
+			read.catalogReady = true;
+			if (read.catalogVersion === this.catalogVersion && read.catalogOrder > this.appliedCatalogOrder) {
+				this.parents = new Map(catalog.parents);
+				this.appliedCatalogOrder = read.catalogOrder;
+			}
+		});
 		const own = sumOneSession(root);
 		const subagents = zero();
 		for (const log of descendants) add(subagents, sumOneSession(log).totals);
@@ -2954,11 +3051,18 @@ var SessionUsageService = class {
 			coverage
 		};
 		signal?.throwIfAborted();
-		if (coverage.complete && generation === this.generation) {
-			if (this.cache.size >= CACHE_MAX) this.cache.clear();
-			this.cache.set(rootId, {
+		const newer = this.cache.get(read.rootId);
+		if (coverage.complete && !read.invalidated && (newer === void 0 || newer.read.catalogOrder < read.catalogOrder)) {
+			for (const older of this.reads) if (older.rootId === read.rootId && older.persistence === read.persistence && older.sessions === read.sessions && older.catalogOrder < read.catalogOrder) older.invalidated = true;
+			this.cache.delete(read.rootId);
+			if (this.cache.size >= CACHE_MAX) {
+				const oldest = this.cache.keys().next().value;
+				if (oldest !== void 0) this.cache.delete(oldest);
+			}
+			this.cache.set(read.rootId, {
 				at: Date.now(),
-				value
+				value,
+				read
 			});
 		}
 		return value;
@@ -3010,7 +3114,8 @@ function apply(ctx, config = {}) {
 		source: config.source,
 		backfillConcurrency: config.backfillConcurrency
 	});
-	const sessionUsage = new SessionUsageService();
+	const sessionEvents = ctx;
+	const sessionUsage = new SessionUsageService(typeof sessionEvents.on === "function" ? void 0 : 4e3);
 	const trust = () => {
 		const runtime = ctx.get("webRuntime");
 		const startup = ctx.get("webStartup");
@@ -3112,9 +3217,13 @@ function apply(ctx, config = {}) {
 		collector.start();
 		const onEvent = (session) => {
 			const id = typeof session?.id === "string" ? session.id : "";
-			if (id !== "") sessionUsage.invalidate(id);
+			if (id === "") return;
+			const owner = ctx.sessions.get?.(id) ?? session;
+			const parent = owner.header?.parentSession ?? owner.parentSession;
+			const knownParent = owner.header !== void 0 || "parentSession" in owner;
+			sessionUsage.invalidate(id, knownParent ? parent ?? null : void 0);
 		};
-		ctx.on?.("session/event", onEvent);
+		sessionEvents.on?.("session/event", onEvent);
 		(async () => {
 			await rescan();
 			await ensureHourHistory();

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

@@ -28,6 +28,6 @@ export declare function rebuildStats(): Promise<BackfillStatus>;
  *  every subagent session delegated from it. The native `tokenUsage` projection
  *  covers only the main agent, so this is what makes a delegating session's
  *  cost visible. */
-export declare function fetchSessionUsage(sessionId: string): Promise<SessionUsageTree>;
+export declare function fetchSessionUsage(sessionId: string, signal?: AbortSignal): Promise<SessionUsageTree>;
 /** Log-owned requests and live route states for the per-session Usage view. */
 export declare function fetchSessionDetail(sessionId: string, signal?: AbortSignal): Promise<SessionUsageDetail>;

package/lib/types/session-tree.d.ts

@@ -9,7 +9,12 @@ export interface UsageSessionLog {
     events: readonly UsageSessionEvent[];
     inheritedCut: number;
 }
-export declare function readUsageTree(persistence: UsageSessionPersistence, sessions: UsageSessionStore | undefined, rootId: string, signal?: AbortSignal): Promise<{
+/** Metadata only: includes unreadable descendants and both persisted/live links. */
+export interface UsageTreeCatalog {
+    parents: ReadonlyMap<string, ReadonlySet<string>>;
+    members: ReadonlySet<string>;
+}
+export declare function readUsageTree(persistence: UsageSessionPersistence, sessions: UsageSessionStore | undefined, rootId: string, signal?: AbortSignal, onCatalog?: (catalog: UsageTreeCatalog) => void): Promise<{
     root: UsageSessionLog;
     descendants: UsageSessionLog[];
     coverage: SessionUsageCoverage;

package/lib/types/session-usage.d.ts

@@ -3,12 +3,26 @@ import type { UsageSessionPersistence, UsageSessionStore } from './context-types
 import type { SessionUsageTree } from './wire.ts';
 export type { SessionUsageTotals, SessionUsageTree } from './wire.ts';
 export declare class SessionUsageService {
+    private readonly cacheTtlMs;
     private cache;
-    private generation;
-    /** New events can introduce descendants of any cached root. */
-    invalidate(_sessionId: string): void;
-    /** A bad descendant leaves the readable totals available with coverage.
-     * Never cache incomplete results: a repaired log must recover on the next read.
-     * Root, catalog and cancellation failures still reject without publishing zero. */
+    private parents;
+    private catalogVersion;
+    private catalogOrder;
+    private appliedCatalogOrder;
+    private reads;
+    private inFlight;
+    /** Events keep live trees fresh; the TTL bounds out-of-band catalog changes.
+     * Hosts without a live event hook can select the old four-second fallback. */
+    constructor(cacheTtlMs?: number);
+    /** Invalidate the changed session and every old/new ancestor, not other trees.
+     * null is a known root; undefined means parent metadata was not supplied.
+     * An unknown parent chain conservatively falls back instead of missing a new
+     * child that appeared before the persistence catalog caught up. */
+    invalidate(sessionId: string, parentSession?: string | null): void;
+    /** A bad descendant leaves readable totals available, but is never cached.
+     * Signal-less browser requests share one cold read per root. Explicit signals
+     * retain independent ownership and are passed through unchanged: aborting one
+     * caller cannot cancel another caller's readers or publish its partial totals. */
     tree(persistence: UsageSessionPersistence, sessions: UsageSessionStore | undefined, rootId: string, signal?: AbortSignal): Promise<SessionUsageTree>;
+    private compute;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-token-total",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "description": "DSH web plugin: token 用量统计看板 + 单会话（主智能体 + 子智能体）用量统计。提供今日/近3天/近7天/近1月/近3月/自定义筛选、六个汇总卡片、活跃热力图、缓存命中率折线与分模型柱状图、按模型/按供应商 Top5 列表。",
   "icon": "./icon.svg",
   "type": "module",

package/src/client/api.ts

@@ -71,8 +71,8 @@ export async function rebuildStats(): Promise<BackfillStatus> {
  *  every subagent session delegated from it. The native `tokenUsage` projection
  *  covers only the main agent, so this is what makes a delegating session's
  *  cost visible. */
-export async function fetchSessionUsage(sessionId: string): Promise<SessionUsageTree> {
-  return post<SessionUsageTree>('session', { sessionId })
+export async function fetchSessionUsage(sessionId: string, signal?: AbortSignal): Promise<SessionUsageTree> {
+  return post<SessionUsageTree>('session', { sessionId }, signal)
 }
 
 /** Log-owned requests and live route states for the per-session Usage view. */

package/src/client/use-session-usage.ts

@@ -1,7 +1,8 @@
 /** The composer row's window onto the whole session tree. The native usage
  * projection only moves for main-agent calls, so poll the displayed session
- * even before its first child appears. Requests are serialized and late answers
- * from a previous session are discarded. Failures keep the last good reading. */
+ * even before its first child appears. Hidden pages pause; slow responses do
+ * not queue timer retries. Disposed requests are aborted and late answers are
+ * discarded. Failures keep the last good reading. */
 import { useEffect, useRef, useState } from 'react'
 import { fetchSessionUsage } from './api.ts'
 import { combinedTotals } from './session-usage-core.ts'
@@ -23,33 +24,64 @@ export function useSessionUsage(sessionId: string | undefined, signature: string
   useEffect(() => {
     if (typeof sessionId !== 'string' || sessionId === '') return
     let active = true
-    let pending = false
     let again = false
+    let lastResult: string | undefined
+    let timer: ReturnType<typeof setTimeout> | undefined
+    let controller: AbortController | undefined
+    const visible = (): boolean => typeof document === 'undefined' || document.visibilityState !== 'hidden'
+    const clearTimer = (): void => {
+      if (timer !== undefined) clearTimeout(timer)
+      timer = undefined
+    }
     const request = (): void => {
-      if (!active) return
-      if (pending) {
+      if (!active || !visible()) return
+      if (controller !== undefined) {
         again = true
         return
       }
-      pending = true
-      void fetchSessionUsage(sessionId).then((tree) => {
-        if (active) setReading({ sessionId, tree })
+      clearTimer()
+      const current = new AbortController()
+      controller = current
+      void fetchSessionUsage(sessionId, current.signal).then((tree) => {
+        if (!active || controller !== current || current.signal.aborted) return
+        const result = JSON.stringify(tree)
+        if (result !== lastResult) {
+          lastResult = result
+          setReading({ sessionId, tree })
+        }
       }).catch(() => {
         // Retry on the next beat/signature; do not replace good data with zero.
       }).finally(() => {
-        pending = false
-        if (active && again) {
+        if (controller !== current) return
+        controller = undefined
+        if (!active || !visible()) return
+        if (again) {
           again = false
           request()
+        } else {
+          timer = setTimeout(request, SESSION_POLL_MS)
         }
       })
     }
+    const onVisibility = (): void => {
+      clearTimer()
+      if (!visible()) {
+        again = false
+        controller?.abort()
+        controller = undefined
+      } else {
+        request()
+      }
+    }
     refresh.current = request
-    const handle = setInterval(request, SESSION_POLL_MS)
+    if (typeof document !== 'undefined') document.addEventListener('visibilitychange', onVisibility)
     return () => {
       active = false
       refresh.current = null
-      clearInterval(handle)
+      clearTimer()
+      controller?.abort()
+      controller = undefined
+      if (typeof document !== 'undefined') document.removeEventListener('visibilitychange', onVisibility)
     }
   }, [sessionId])
   useEffect(() => {

package/src/index.ts

@@ -12,7 +12,7 @@
  * the browser half over the fenced route.
  */
 
-import type { Context, UsageWebRuntime, UsageWebStartup } from './context-types.ts'
+import type { Context, UsageSessionHandle, UsageWebRuntime, UsageWebStartup } from './context-types.ts'
 import type { TrustInputs } from './trust-fence.ts'
 import { UsageStore } from './store.ts'
 import { UsageCollector } from './collector.ts'
@@ -72,10 +72,11 @@ export function apply(ctx: Context, config: TokenTotalConfig = {}): void {
     source: config.source,
     backfillConcurrency: config.backfillConcurrency,
   })
-  // Per-session (main + subagent) usage for the composer stats row. Its cache
-  // is invalidated on every live event of the touched session (see the
-  // collector subscription below), so the pill never shows a stale tree.
-  const sessionUsage = new SessionUsageService()
+  // Committed events invalidate only the touched tree and its ancestors. With
+  // that hook, unchanged histories can stay cached longer; older hosts without
+  // it retain four-second catalog revalidation rather than stale live totals.
+  const sessionEvents = ctx as unknown as { on?: (name: string, fn: (s: Partial<UsageSessionHandle>) => void) => void }
+  const sessionUsage = new SessionUsageService(typeof sessionEvents.on === 'function' ? undefined : 4_000)
 
   // The /token-total/api trust inputs, resolved live so the fence reads the same sources
   // the /api gateway derives them from. DSH 0.2.1-alpha.2 moved the explicit
@@ -242,15 +243,17 @@ export function apply(ctx: Context, config: TokenTotalConfig = {}): void {
 
   ctx.effect(() => {
     collector.start()
-    // Keep the per-session tree cache honest: every committed event of any
-    // session (main or subagent) changes at least one cached tree, so drop the
-    // ones that counted it. Observational only — a missing hook is harmless.
-    const onEvent = (session: { id?: unknown }): void => {
+    // Include live ancestry: a new child may not be in the persisted catalog
+    // yet. Missing metadata takes the service's conservative fallback path.
+    const onEvent = (session: Partial<UsageSessionHandle>): void => {
       const id = typeof session?.id === 'string' ? session.id : ''
-      if (id !== '') sessionUsage.invalidate(id)
+      if (id === '') return
+      const owner = ctx.sessions.get?.(id) ?? session
+      const parent = owner.header?.parentSession ?? owner.parentSession
+      const knownParent = owner.header !== undefined || 'parentSession' in owner
+      sessionUsage.invalidate(id, knownParent ? parent ?? null : undefined)
     }
-    ;(ctx as unknown as { on?: (name: string, fn: (s: { id?: unknown }) => void) => void })
-      .on?.('session/event', onEvent)
+    sessionEvents.on?.('session/event', onEvent)
     void (async () => {
       await rescan()
       await ensureHourHistory()

package/src/session-detail.ts

@@ -86,8 +86,12 @@ function nameOf(h: UsageSessionHeader | undefined, id: string): string {
   return id
 }
 
-function one(log: UsageSessionLog) {
-  const { id, header, live, events, inheritedCut: cut } = log
+function ownEventsOf(log: UsageSessionLog) {
+  return log.events.filter(e => !(log.inheritedCut > 0 && typeof e.seq === 'number' && e.seq < log.inheritedCut))
+}
+
+function one(log: UsageSessionLog, parentCatalogLabel?: string) {
+  const { id, header, live } = log
   const fold = new UsageFold(); const totals = zero(); const records: MutableRecord[] = []
   const byKey = new Map<string, MutableRecord>(); let route = live?.requestContext?.() ?? {}
   let ordinal = 0
@@ -96,18 +100,16 @@ function one(log: UsageSessionLog) {
   // the prompt usually lands before `turn/start`, so buffer it until the turn opens.
   let currentTurn = 0; let effort = ''; let pendingTopic = ''
   const turnTopics = new Map<number, string>()
-  const own = events.filter(e => !(cut > 0 && typeof e.seq === 'number' && e.seq < cut))
-  // Real session names: a subagent carries its delegation label on its
-  // `subagent/descriptor` event ("完成日志明细后端"), every session can carry a
-  // generated `session/title`; only fall back to the header/cwd/id guesses.
+  const own = ownEventsOf(log)
+  // Prefer the child's own delegation label or latest title. Older CLI records
+  // carry their task name only in the actual parent's subagent/catalog.
   let label = '', title = ''
   for (const ev of own) {
     const d: any = ev.data ?? {}
     if (!label && ev.type === 'subagent/descriptor' && typeof d.label === 'string' && d.label.trim()) label = d.label.trim()
-    if (!title && ev.type === 'session/title' && typeof d.title === 'string' && d.title.trim()) title = d.title.trim()
-    if (label && title) break
+    if (ev.type === 'session/title' && typeof d.title === 'string' && d.title.trim()) title = d.title.trim()
   }
-  const name = label || title || nameOf(header, id)
+  const name = label || title || parentCatalogLabel || nameOf(header, id)
   // Decode accounting mirrors the official `sessionStats` projection: a step
   // records its first token once (the earliest attempt wins, surviving an
   // in-step retry), and only the assembled `assistant/message` closes the
@@ -192,7 +194,23 @@ function one(log: UsageSessionLog) {
 
 export async function buildSessionUsageDetail(persistence: UsageSessionPersistence, sessions: UsageSessionStore | undefined, rootId: string, ctx?: Context): Promise<SessionUsageDetail> {
   const { root, descendants, coverage } = await readUsageTree(persistence, sessions, rootId)
-  const parts = [root, ...descendants].map(one)
+  const logs = [root, ...descendants]
+  const catalogLabels = new Map<string, Map<string, string>>()
+  for (const log of logs) {
+    const labels = new Map<string, string>()
+    for (const event of ownEventsOf(log)) {
+      if (event.type !== 'subagent/catalog') continue
+      const data = event.data as { childId?: unknown; label?: unknown } | null
+      if (typeof data?.childId === 'string' && data.childId && typeof data.label === 'string' && data.label.trim()) {
+        labels.set(data.childId, data.label.trim())
+      }
+    }
+    catalogLabels.set(log.id, labels)
+  }
+  const parts = logs.map(log => {
+    const parentId = log.header?.parentSession ?? log.live?.header?.parentSession ?? log.live?.parentSession
+    return one(log, parentId === undefined ? undefined : catalogLabels.get(parentId)?.get(log.id))
+  })
   const totals = zero(); const models = new Map<string, { totals: SessionUsageTotals; requests: number; providers: Set<string> }>(); const records = parts.flatMap(x => x.records); for (const p of parts) add(totals, p.totals)
   for (const r of records) { const key = r.model || '(unknown)'; const m = models.get(key) ?? { totals: zero(), requests: 0, providers: new Set<string>() }; add(m.totals, r.totals); m.requests++; if (r.provider) m.providers.add(r.provider); models.set(key, m) }
   const subagents = parts.slice(1).map(p => ({ sessionId: p.id, name: p.name, totals: p.totals, requests: p.requests, averageFirstTokenMs: p.averageFirstTokenMs, tokensPerSecond: p.tokensPerSecond }))

package/src/session-tree.ts

@@ -18,6 +18,12 @@ export interface UsageSessionLog {
   inheritedCut: number
 }
 
+/** Metadata only: includes unreadable descendants and both persisted/live links. */
+export interface UsageTreeCatalog {
+  parents: ReadonlyMap<string, ReadonlySet<string>>
+  members: ReadonlySet<string>
+}
+
 function headerOf(item: UsageSessionHeader | UsageSessionSnapshot): UsageSessionHeader | null {
   if (!item || typeof item !== 'object') return null
   const header = 'header' in item ? item.header : item
@@ -84,6 +90,7 @@ export async function readUsageTree(
   sessions: UsageSessionStore | undefined,
   rootId: string,
   signal?: AbortSignal,
+  onCatalog?: (catalog: UsageTreeCatalog) => void,
 ): Promise<{ root: UsageSessionLog; descendants: UsageSessionLog[]; coverage: SessionUsageCoverage }> {
   signal?.throwIfAborted()
   const rows = await persistence.list(typeof persistence.open === 'function'
@@ -96,11 +103,14 @@ export async function readUsageTree(
   }
   const live = new Map((sessions?.list() ?? []).map(handle => [handle.id, handle]))
   const children = new Map<string, Set<string>>()
+  const parents = new Map<string, Set<string>>()
+  for (const id of [...headers.keys(), ...live.keys()]) parents.set(id, new Set())
   const link = (id: string, parent: unknown): void => {
     if (typeof parent !== 'string' || parent === '' || parent === id) return
     const bucket = children.get(parent) ?? new Set<string>()
     bucket.add(id)
     children.set(parent, bucket)
+    parents.get(id)?.add(parent)
   }
   for (const header of headers.values()) link(header.id, header.parentSession)
   for (const handle of live.values()) link(handle.id, handle.header?.parentSession ?? handle.parentSession)
@@ -115,6 +125,9 @@ export async function readUsageTree(
       queue.push(id)
     }
   }
+  // Publish membership before any asynchronous log read, so events arriving
+  // during that read can invalidate the right root, including bad descendants.
+  onCatalog?.({ parents, members: seen })
   const root = await readSession(persistence, rootId, headers.get(rootId), live.get(rootId), signal)
   const logs: Array<UsageSessionLog | undefined> = new Array(ids.length)
   const issues: Array<SessionUsageReadIssue | undefined> = new Array(ids.length)

package/src/session-usage.ts

@@ -34,22 +34,85 @@ function sumOneSession(log: UsageSessionLog): { totals: SessionUsageTotals; comp
   return { totals, compaction }
 }
 
-const CACHE_TTL_MS = 4_000
+const CACHE_TTL_MS = 60_000
 const CACHE_MAX = 64
 
+interface TreeRead {
+  rootId: string
+  persistence: UsageSessionPersistence
+  sessions: UsageSessionStore | undefined
+  members: ReadonlySet<string>
+  invalidated: boolean
+  catalogReady: boolean
+  catalogVersion: number
+  catalogOrder: number
+}
+interface CachedTree {
+  at: number
+  value: SessionUsageTree
+  read: TreeRead
+}
+
 export class SessionUsageService {
-  private cache = new Map<string, { at: number; value: SessionUsageTree }>()
-  private generation = 0
+  private cache = new Map<string, CachedTree>()
+  private parents = new Map<string, ReadonlySet<string>>()
+  private catalogVersion = 0
+  private catalogOrder = 0
+  private appliedCatalogOrder = 0
+  private reads = new Set<TreeRead>()
+  private inFlight = new Map<string, { read: TreeRead; promise: Promise<SessionUsageTree> }>()
+
+  /** Events keep live trees fresh; the TTL bounds out-of-band catalog changes.
+   * Hosts without a live event hook can select the old four-second fallback. */
+  constructor(private readonly cacheTtlMs = CACHE_TTL_MS) {}
 
-  /** New events can introduce descendants of any cached root. */
-  invalidate(_sessionId: string): void {
-    this.generation++
-    this.cache.clear()
+  /** Invalidate the changed session and every old/new ancestor, not other trees.
+   * null is a known root; undefined means parent metadata was not supplied.
+   * An unknown parent chain conservatively falls back instead of missing a new
+   * child that appeared before the persistence catalog caught up. */
+  invalidate(sessionId: string, parentSession?: string | null): void {
+    this.catalogVersion++
+    const previous = this.parents.get(sessionId)
+    const queue = [...(previous ?? [])]
+    let uncertain = previous === undefined && parentSession === undefined
+    if (parentSession !== undefined) {
+      const current = new Set<string>()
+      if (parentSession !== null && parentSession !== '' && parentSession !== sessionId) current.add(parentSession)
+      // Do not accumulate unbounded event-only ids between catalog reads.
+      // Unknown hints still invalidate their ancestors immediately.
+      if (previous !== undefined) this.parents.set(sessionId, current)
+      queue.push(...current)
+    }
+    const affected = new Set([sessionId])
+    for (let index = 0; index < queue.length; index++) {
+      const id = queue[index]!
+      if (affected.has(id)) continue
+      affected.add(id)
+      const ancestors = this.parents.get(id)
+      if (ancestors === undefined) uncertain = true
+      else queue.push(...ancestors)
+    }
+    const touches = (read: TreeRead): boolean => {
+      if (affected.has(read.rootId)) return true
+      // A newer catalog may have moved an ancestor away from this older tree.
+      // Changes below that ancestor must still invalidate its old membership.
+      for (const id of affected) if (read.members.has(id)) return true
+      return false
+    }
+    for (const [rootId, entry] of this.cache) {
+      if (uncertain || touches(entry.read)) this.cache.delete(rootId)
+    }
+    // Detached older reads remain tracked until they settle. A new request must
+    // not join an invalidated read, and that read must never repopulate the cache.
+    for (const read of this.reads) {
+      if (!read.catalogReady || uncertain || touches(read)) read.invalidated = true
+    }
   }
 
-  /** A bad descendant leaves the readable totals available with coverage.
-   * Never cache incomplete results: a repaired log must recover on the next read.
-   * Root, catalog and cancellation failures still reject without publishing zero. */
+  /** A bad descendant leaves readable totals available, but is never cached.
+   * Signal-less browser requests share one cold read per root. Explicit signals
+   * retain independent ownership and are passed through unchanged: aborting one
+   * caller cannot cancel another caller's readers or publish its partial totals. */
   async tree(
     persistence: UsageSessionPersistence,
     sessions: UsageSessionStore | undefined,
@@ -58,9 +121,43 @@ export class SessionUsageService {
   ): Promise<SessionUsageTree> {
     signal?.throwIfAborted()
     const hit = this.cache.get(rootId)
-    if (hit !== undefined && Date.now() - hit.at < CACHE_TTL_MS) return hit.value
-    const generation = this.generation
-    const { root, descendants, coverage } = await readUsageTree(persistence, sessions, rootId, signal)
+    if (hit !== undefined && hit.read.persistence === persistence && hit.read.sessions === sessions
+      && Date.now() - hit.at < this.cacheTtlMs) {
+      // Map insertion order is the LRU; a hit must protect a popular history.
+      this.cache.delete(rootId)
+      this.cache.set(rootId, hit)
+      return hit.value
+    }
+    this.cache.delete(rootId)
+    const pending = this.inFlight.get(rootId)
+    if (signal === undefined && pending !== undefined && !pending.read.invalidated
+      && pending.read.persistence === persistence && pending.read.sessions === sessions) return pending.promise
+
+    const read: TreeRead = {
+      rootId, persistence, sessions, members: new Set([rootId]), invalidated: false,
+      catalogReady: false, catalogVersion: this.catalogVersion, catalogOrder: ++this.catalogOrder,
+    }
+    this.reads.add(read)
+    const promise = this.compute(read, signal).finally(() => {
+      this.reads.delete(read)
+      if (this.inFlight.get(rootId)?.read === read) this.inFlight.delete(rootId)
+    })
+    if (signal === undefined) this.inFlight.set(rootId, { read, promise })
+    return promise
+  }
+
+  private async compute(read: TreeRead, signal?: AbortSignal): Promise<SessionUsageTree> {
+    const { root, descendants, coverage } = await readUsageTree(
+      read.persistence, read.sessions, read.rootId, signal, (catalog) => {
+        read.members = catalog.members
+        read.catalogReady = true
+        // A slow older listing must not undo newer catalogs or event hints.
+        if (read.catalogVersion === this.catalogVersion && read.catalogOrder > this.appliedCatalogOrder) {
+          this.parents = new Map(catalog.parents)
+          this.appliedCatalogOrder = read.catalogOrder
+        }
+      },
+    )
     const own = sumOneSession(root)
     const subagents = zero()
     for (const log of descendants) add(subagents, sumOneSession(log).totals)
@@ -75,9 +172,20 @@ export class SessionUsageService {
       coverage,
     }
     signal?.throwIfAborted()
-    if (coverage.complete && generation === this.generation) {
-      if (this.cache.size >= CACHE_MAX) this.cache.clear()
-      this.cache.set(rootId, { at: Date.now(), value })
+    const newer = this.cache.get(read.rootId)
+    if (coverage.complete && !read.invalidated && (newer === undefined || newer.read.catalogOrder < read.catalogOrder)) {
+      // Retire older same-source snapshots before publishing. LRU eviction of
+      // this result must not let an older detached read be joined or cached.
+      for (const older of this.reads) {
+        if (older.rootId === read.rootId && older.persistence === read.persistence
+          && older.sessions === read.sessions && older.catalogOrder < read.catalogOrder) older.invalidated = true
+      }
+      this.cache.delete(read.rootId)
+      if (this.cache.size >= CACHE_MAX) {
+        const oldest = this.cache.keys().next().value
+        if (oldest !== undefined) this.cache.delete(oldest)
+      }
+      this.cache.set(read.rootId, { at: Date.now(), value, read })
     }
     return value
   }