dsh-token-total 1.1.5 → 1.1.6

package/README.md

@@ -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);
@@ -2937,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);
@@ -2970,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;
@@ -3026,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");
@@ -3128,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.5",
+  "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-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
   }