dsh-token-total 1.1.2 → 1.1.4

package/lib/index.js

@@ -1526,6 +1526,134 @@ async function resolveModelNames(modelRefs, llm) {
 	return names;
 }
 //#endregion
+//#region src/session-tree.ts
+function headerOf(item) {
+	if (!item || typeof item !== "object") return null;
+	const header = "header" in item ? item.header : item;
+	return header && typeof header.id === "string" && header.id !== "" ? header : null;
+}
+function inheritedCount(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+}
+function throwIfCanceled(error, signal) {
+	signal?.throwIfAborted();
+	if (error && typeof error === "object" && "name" in error && error.name === "AbortError") throw error;
+}
+/** Never send raw exceptions to the client: they may contain paths or secrets. */
+function readIssue(sessionId, error) {
+	const name = error && typeof error === "object" && "name" in error ? error.name : "";
+	const code = error && typeof error === "object" && "code" in error ? error.code : "";
+	return {
+		sessionId,
+		reason: name === "SessionPersistenceCorruptionError" || name === "SessionFormatError" ? "corrupt" : name === "SessionPersistenceNotFoundError" || code === "ENOENT" ? "missing" : "unavailable"
+	};
+}
+async function readSession(persistence, id, header, live, signal) {
+	signal?.throwIfAborted();
+	if (typeof live?.snapshotEvents === "function" && typeof live.inheritedEventCount === "number") return {
+		id,
+		header,
+		live,
+		events: live.snapshotEvents(),
+		inheritedCut: inheritedCount(live.inheritedEventCount)
+	};
+	if (typeof persistence.open === "function") {
+		const options = signal === void 0 ? void 0 : { signal };
+		const handle = await persistence.open(id, "read", options);
+		try {
+			const events = [];
+			for (let offset = 0;;) {
+				signal?.throwIfAborted();
+				const page = await handle.read(offset, 500, options);
+				if (!page.events.length) break;
+				for (const event of page.events) events.push(event);
+				offset += page.events.length;
+			}
+			return {
+				id,
+				header: header ?? handle.header,
+				live,
+				events,
+				inheritedCut: inheritedCount(handle.inheritedEventCount)
+			};
+		} finally {
+			await handle.close().catch(() => {});
+		}
+	}
+	if (typeof persistence.inspect === "function") {
+		const inspection = await persistence.inspect(id, signal);
+		signal?.throwIfAborted();
+		return {
+			id,
+			header: header ?? inspection.meta,
+			live,
+			events: inspection.events,
+			inheritedCut: inheritedCount(inspection.inheritedEventCount)
+		};
+	}
+	throw new Error("no readable persistence seam (need open or inspect)");
+}
+async function readUsageTree(persistence, sessions, rootId, signal) {
+	signal?.throwIfAborted();
+	const rows = await persistence.list(typeof persistence.open === "function" ? signal === void 0 ? void 0 : { signal } : signal);
+	const headers = /* @__PURE__ */ new Map();
+	for (const row of rows) {
+		const header = headerOf(row);
+		if (header) headers.set(header.id, header);
+	}
+	const live = new Map((sessions?.list() ?? []).map((handle) => [handle.id, handle]));
+	const children = /* @__PURE__ */ new Map();
+	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);
+	};
+	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);
+	const ids = [];
+	const seen = /* @__PURE__ */ new Set([rootId]);
+	const queue = [rootId];
+	for (let index = 0; index < queue.length; index++) for (const id of children.get(queue[index]) ?? []) {
+		if (seen.has(id)) continue;
+		seen.add(id);
+		ids.push(id);
+		queue.push(id);
+	}
+	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);
+	let next = 0;
+	const workers = await Promise.allSettled(Array.from({ length: Math.min(4, ids.length) }, async () => {
+		for (;;) {
+			signal?.throwIfAborted();
+			const index = next++;
+			if (index >= ids.length) return;
+			const id = ids[index];
+			try {
+				logs[index] = await readSession(persistence, id, headers.get(id), live.get(id), signal);
+			} catch (error) {
+				throwIfCanceled(error, signal);
+				issues[index] = readIssue(id, error);
+			}
+		}
+	}));
+	for (const worker of workers) if (worker.status === "rejected") throw worker.reason;
+	signal?.throwIfAborted();
+	const descendants = logs.filter((log) => log !== void 0);
+	const unreadableSessions = issues.filter((issue) => issue !== void 0);
+	return {
+		root,
+		descendants,
+		coverage: {
+			complete: unreadableSessions.length === 0,
+			totalSessions: ids.length + 1,
+			readableSessions: descendants.length + 1,
+			unreadableSessions
+		}
+	};
+}
+//#endregion
 //#region src/context-window.ts
 /** ASCII-ish characters per token (the host estimator's ratio). */
 const ASCII_CHARS_PER_TOKEN = 4;
@@ -1995,7 +2123,7 @@ function mergeUsageCompositions(parts) {
 }
 //#endregion
 //#region src/session-detail.ts
-const zero = () => ({
+const zero$1 = () => ({
 	uncachedInputTokens: 0,
 	outputTokens: 0,
 	cacheReadTokens: 0,
@@ -2082,43 +2210,6 @@ function usageOutputTokens(x) {
 	const value = (x?.usage ?? x)?.outputTokens;
 	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
 }
-function headerOf$1(item) {
-	const x = item;
-	if (x?.header?.id && typeof x.header.id === "string") return x.header;
-	return typeof x?.id === "string" && x.id ? x : null;
-}
-async function read(p, id, live) {
-	if (live?.snapshotEvents && typeof live.inheritedEventCount === "number") return {
-		events: live.snapshotEvents(),
-		cut: Math.max(0, live.inheritedEventCount)
-	};
-	if (p.open) {
-		const h = await p.open(id, "read");
-		const out = [];
-		try {
-			for (let off = 0;;) {
-				const page = await h.read(off, 500);
-				if (!page.events.length) break;
-				out.push(...page.events);
-				off += page.events.length;
-			}
-		} finally {
-			await h.close().catch(() => {});
-		}
-		return {
-			events: out,
-			cut: Math.max(0, Number(h.inheritedEventCount) || 0)
-		};
-	}
-	if (p.inspect) {
-		const x = await p.inspect(id);
-		return {
-			events: x.events,
-			cut: Math.max(0, Number(x.inheritedEventCount) || 0)
-		};
-	}
-	throw new Error("no readable persistence seam (need open or inspect)");
-}
 function nameOf(h, id) {
 	const x = h;
 	if (typeof x?.name === "string" && x.name) return x.name;
@@ -2126,10 +2217,10 @@ function nameOf(h, id) {
 	if (typeof x?.cwd === "string" && x.cwd) return x.cwd.split(/[\\/]/).filter(Boolean).pop() || id;
 	return id;
 }
-async function one(p, id, header, live) {
-	const { events, cut } = await read(p, id, live);
+function one(log) {
+	const { id, header, live, events, inheritedCut: cut } = log;
 	const fold = new UsageFold();
-	const totals = zero();
+	const totals = zero$1();
 	const records = [];
 	const byKey = /* @__PURE__ */ new Map();
 	let route = live?.requestContext?.() ?? {};
@@ -2205,14 +2296,14 @@ async function one(p, id, header, live) {
 					provider: r.provider || route.provider || "",
 					model: r.model || route.model || "",
 					status: "running",
-					totals: zero(),
+					totals: zero$1(),
 					firstTokenMs: null,
 					decodeMs: null,
 					tokensPerSecond: null,
 					turnName: "",
 					effort,
 					_attempt: ev.type === "llm/retry-started" ? 1 : 0,
-					_lastUsage: zero()
+					_lastUsage: zero$1()
 				};
 				records.push(rec);
 				byKey.set(key, rec);
@@ -2232,14 +2323,14 @@ async function one(p, id, header, live) {
 					provider: r.provider || route.provider || "",
 					model: r.model || route.model || "",
 					status: "running",
-					totals: zero(),
+					totals: zero$1(),
 					firstTokenMs: null,
 					decodeMs: null,
 					tokensPerSecond: null,
 					turnName: "",
 					effort,
 					_attempt: 0,
-					_lastUsage: zero()
+					_lastUsage: zero$1()
 				};
 				records.push(rec);
 				byKey.set(key, rec);
@@ -2326,32 +2417,16 @@ async function one(p, id, header, live) {
 	};
 }
 async function buildSessionUsageDetail(persistence, sessions, rootId, ctx) {
-	const headers = (await persistence.list(typeof persistence.open === "function" ? void 0 : void 0)).map(headerOf$1).filter((x) => x !== null);
-	const live = new Map((sessions?.list() ?? []).map((x) => [x.id, x]));
-	const children = /* @__PURE__ */ new Map();
-	for (const h of headers) if (h.parentSession) children.set(h.parentSession, [...children.get(h.parentSession) ?? [], h.id]);
-	for (const h of live.values()) {
-		const p = h.header?.parentSession ?? h.parentSession;
-		if (p) children.set(p, [...(children.get(p) ?? []).filter((x) => x !== h.id), h.id]);
-	}
-	const ids = [];
-	const seen = /* @__PURE__ */ new Set([rootId]);
-	const q = [rootId];
-	while (q.length) for (const c of children.get(q.shift()) ?? []) if (!seen.has(c)) {
-		seen.add(c);
-		ids.push(c);
-		q.push(c);
-	}
-	const all = [rootId, ...ids];
-	const parts = await Promise.all(all.map((id) => one(persistence, id, headers.find((h) => h.id === id), live.get(id))));
-	const totals = zero();
+	const { root, descendants, coverage } = await readUsageTree(persistence, sessions, rootId);
+	const parts = [root, ...descendants].map(one);
+	const totals = zero$1();
 	const models = /* @__PURE__ */ new Map();
 	const records = parts.flatMap((x) => x.records);
 	for (const p of parts) add$1(totals, p.totals);
 	for (const r of records) {
 		const key = r.model || "(unknown)";
 		const m = models.get(key) ?? {
-			totals: zero(),
+			totals: zero$1(),
 			requests: 0,
 			providers: /* @__PURE__ */ new Set()
 		};
@@ -2405,6 +2480,7 @@ async function buildSessionUsageDetail(persistence, sessions, rootId, ctx) {
 	const firsts = records.filter((x) => x.status === "completed").map((x) => x.firstTokenMs).filter((x) => x !== null);
 	return {
 		sessionId: rootId,
+		coverage,
 		totals,
 		requests: parts.reduce((n, p) => n + p.requests, 0),
 		averageFirstTokenMs: firsts.length ? firsts.reduce((a, b) => a + b, 0) / firsts.length : null,
@@ -2811,82 +2887,25 @@ function buildUsageRoute(ctx, deps) {
 }
 //#endregion
 //#region src/session-usage.ts
-const ZERO = {
+const zero = () => ({
 	uncachedInputTokens: 0,
 	outputTokens: 0,
 	cacheReadTokens: 0,
 	cacheWriteTokens: 0
-};
+});
 function add(into, from) {
 	into.uncachedInputTokens += from.uncachedInputTokens;
 	into.outputTokens += from.outputTokens;
 	into.cacheReadTokens += from.cacheReadTokens;
 	into.cacheWriteTokens += from.cacheWriteTokens;
 }
-/** How long one computed tree stays hot. The pill refreshes on its own clock,
-*  and a live session's numbers move at step granularity, not per frame. */
-const CACHE_TTL_MS = 4e3;
-/** Absolute ceiling on cached trees, so a long-lived host with many sessions
-*  cannot grow this map without bound. */
-const CACHE_MAX = 64;
-/** Normalize a `list()` row (alpha snapshots or rc.1 header rows). */
-function headerOf(item) {
-	const snap = item;
-	if (snap !== null && typeof snap === "object" && "header" in snap && snap.header !== null && typeof snap.header === "object" && typeof snap.header.id === "string") return snap.header;
-	const row = item;
-	return typeof row?.id === "string" && row.id !== "" ? row : null;
-}
-function inheritedCount(cut) {
-	return typeof cut === "number" && Number.isSafeInteger(cut) && cut >= 0 ? cut : 0;
-}
-/** Read one stored session's events through whichever persistence seam the
-*  host line exposes (alpha open/read/close wins; rc.1 inspect is the tail). */
-async function readEvents(persistence, id, signal) {
-	if (typeof persistence.open === "function") {
-		const handle = await persistence.open(id, "read", signal === void 0 ? void 0 : { signal });
-		try {
-			const inheritedCut = inheritedCount(handle.inheritedEventCount);
-			const collected = [];
-			let offset = 0;
-			const PAGE = 500;
-			for (;;) {
-				signal?.throwIfAborted();
-				const slice = await handle.read(offset, PAGE, signal === void 0 ? void 0 : { signal });
-				const page = slice && slice.events ? slice.events : [];
-				if (page.length === 0) break;
-				for (const ev of page) collected.push(ev);
-				offset += page.length;
-			}
-			return {
-				events: collected,
-				inheritedCut
-			};
-		} finally {
-			await handle.close().catch(() => {});
-		}
-	}
-	if (typeof persistence.inspect === "function") {
-		const inspection = await persistence.inspect(id, signal);
-		return {
-			events: inspection.events,
-			inheritedCut: inheritedCount(inspection.inheritedEventCount)
-		};
-	}
-	throw new Error("no readable persistence seam (need open or inspect)");
-}
-/** Sum one session's own usage (its main agent) from its log. */
-async function sumOneSession(persistence, id, signal, live) {
-	signal?.throwIfAborted();
-	const { events, inheritedCut } = typeof live?.snapshotEvents === "function" && typeof live.inheritedEventCount === "number" ? {
-		events: live.snapshotEvents(),
-		inheritedCut: inheritedCount(live.inheritedEventCount)
-	} : await readEvents(persistence, id, signal);
+function sumOneSession(log) {
 	const fold = new UsageFold();
-	const totals = { ...ZERO };
-	const compaction = { ...ZERO };
-	for (const ev of events) {
-		if (inheritedCut > 0 && typeof ev.seq === "number" && ev.seq < inheritedCut) continue;
-		const sample = fold.fold(ev);
+	const totals = zero();
+	const compaction = zero();
+	for (const event of log.events) {
+		if (event.seq < log.inheritedCut) continue;
+		const sample = fold.fold(event);
 		if (sample === null || sample.turn) continue;
 		const buckets = {
 			uncachedInputTokens: sample.inputTokens,
@@ -2895,77 +2914,47 @@ async function sumOneSession(persistence, id, signal, live) {
 			cacheWriteTokens: sample.cacheWriteTokens
 		};
 		add(totals, buckets);
-		if (ev.type === "compaction/summary") add(compaction, buckets);
+		if (event.type === "compaction/summary") add(compaction, buckets);
 	}
 	return {
 		totals,
 		compaction
 	};
 }
+const CACHE_TTL_MS = 4e3;
+const CACHE_MAX = 64;
 var SessionUsageService = class {
-	/** Short-lived tree reads; any live event can invalidate tree membership. */
 	cache = /* @__PURE__ */ new Map();
-	/** Any event can introduce a new descendant while an async read is running. */
 	generation = 0;
-	/** Invalidate conservatively: an unseen session may be a newly-created child
-	*  of ANY cached root, so membership-only invalidation is not safe. */
+	/** New events can introduce descendants of any cached root. */
 	invalidate(_sessionId) {
 		this.generation++;
 		this.cache.clear();
 	}
-	/** Resolve the whole session tree rooted at `rootId` and sum its usage.
-	*  `self` is the root's own usage, `subagents` every descendant's, `total`
-	*  the sum. Unreadable logs reject rather than publishing partial totals;
-	*  callers can retain their last good display while surfacing the error. */
+	/** 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. */
 	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 headers = await this.listHeaders(persistence, signal);
-		const children = /* @__PURE__ */ new Map();
-		for (const header of headers) {
-			const parent = header.parentSession;
-			if (typeof parent !== "string" || parent === "") continue;
-			const bucket = children.get(parent);
-			if (bucket === void 0) children.set(parent, [header.id]);
-			else bucket.push(header.id);
-		}
-		const live = new Map((sessions?.list() ?? []).map((handle) => [handle.id, handle]));
-		for (const handle of live.values()) {
-			const parent = handle.header?.parentSession ?? handle.parentSession;
-			if (typeof parent !== "string" || parent === "" || parent === handle.id) continue;
-			const bucket = children.get(parent);
-			if (bucket === void 0) children.set(parent, [handle.id]);
-			else if (!bucket.includes(handle.id)) bucket.push(handle.id);
-		}
-		const descendants = [];
-		const seen = /* @__PURE__ */ new Set([rootId]);
-		const queue = [rootId];
-		while (queue.length > 0) {
-			const current = queue.shift();
-			for (const child of children.get(current) ?? []) {
-				if (seen.has(child)) continue;
-				seen.add(child);
-				descendants.push(child);
-				queue.push(child);
-			}
-		}
-		const root = await sumOneSession(persistence, rootId, signal, live.get(rootId));
-		const self = root.totals;
-		const subagents = { ...ZERO };
-		for (const id of descendants) add(subagents, (await sumOneSession(persistence, id, signal, live.get(id))).totals);
-		const total = { ...self };
+		const { root, descendants, coverage } = await readUsageTree(persistence, sessions, rootId, signal);
+		const own = sumOneSession(root);
+		const subagents = zero();
+		for (const log of descendants) add(subagents, sumOneSession(log).totals);
+		const total = { ...own.totals };
 		add(total, subagents);
 		const value = {
-			self,
-			selfCompaction: root.compaction,
+			self: own.totals,
+			selfCompaction: own.compaction,
 			subagents,
 			total,
-			subagentSessions: descendants.length
+			subagentSessions: descendants.length,
+			coverage
 		};
 		signal?.throwIfAborted();
-		if (generation === this.generation) {
+		if (coverage.complete && generation === this.generation) {
 			if (this.cache.size >= CACHE_MAX) this.cache.clear();
 			this.cache.set(rootId, {
 				at: Date.now(),
@@ -2974,9 +2963,6 @@ var SessionUsageService = class {
 		}
 		return value;
 	}
-	async listHeaders(persistence, signal) {
-		return (typeof persistence.open === "function" ? await persistence.list(signal === void 0 ? void 0 : { signal }) : await persistence.list(signal)).map(headerOf).filter((h) => h !== null);
-	}
 };
 //#endregion
 //#region src/index.ts

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

@@ -7,7 +7,7 @@
 /** The locale namespace this plugin owns. */
 export declare const LOCALE_NS = "tokenTotal";
 /** The typed translator key union for the panel's locale seat. */
-export type TokenTotalKey = 'nav' | 'back' | 'range' | 'rangePreset.today' | 'rangePreset.3' | 'rangePreset.7' | 'rangePreset.30' | 'rangePreset.90' | 'rangeCustom' | 'from' | 'to' | 'refresh' | 'loading' | 'tokens' | 'tokensHint' | 'tokensUnit' | 'inputTokens' | 'outputTokens' | 'cacheTokens' | 'cachedTokens' | 'sessions' | 'requests' | 'requestsFailed' | 'activeDays' | 'cacheRate' | 'cacheRateHint' | 'cacheHitRate' | 'hitRateLegend' | 'topModel' | 'topModelHint' | 'heatmap' | 'heatLess' | 'heatMore' | 'dow.mon' | 'dow.tue' | 'dow.wed' | 'dow.thu' | 'dow.fri' | 'dow.sat' | 'dow.sun' | 'month.jan' | 'month.feb' | 'month.mar' | 'month.apr' | 'month.may' | 'month.jun' | 'month.jul' | 'month.aug' | 'month.sep' | 'month.oct' | 'month.nov' | 'month.dec' | 'dailyTrend' | 'hourlyTrend' | 'trendLimited' | 'usageRanking' | 'byModel' | 'byProvider' | 'tokensColumn' | 'cacheRateColumn' | 'providerModels' | 'other' | 'total' | 'percent' | 'asOf' | 'empty' | 'stats.counts' | 'stats.tokensPerSecond' | 'stats.cacheHit' | 'stats.cacheMiss' | 'stats.dialog.title' | 'stats.dialog.usageTitle' | 'stats.dialog.llmTime' | 'stats.dialog.toolTime' | 'stats.dialog.ttft' | 'stats.dialog.speed' | 'stats.dialog.main' | 'stats.dialog.subagents' | 'stats.dialog.subagentCount' | 'stats.dialog.treeTotal' | 'message.turnUsage.count' | 'message.turnUsage.cacheHit' | 'message.turnUsage.input' | 'message.turnUsage.cacheRead' | 'message.turnUsage.cacheWrite' | 'message.turnUsage.output';
+export type TokenTotalKey = 'nav' | 'back' | 'range' | 'rangePreset.today' | 'rangePreset.3' | 'rangePreset.7' | 'rangePreset.30' | 'rangePreset.90' | 'rangeCustom' | 'from' | 'to' | 'refresh' | 'loading' | 'tokens' | 'tokensHint' | 'tokensUnit' | 'inputTokens' | 'outputTokens' | 'cacheTokens' | 'cachedTokens' | 'sessions' | 'requests' | 'requestsFailed' | 'activeDays' | 'cacheRate' | 'cacheRateHint' | 'cacheHitRate' | 'hitRateLegend' | 'topModel' | 'topModelHint' | 'heatmap' | 'heatLess' | 'heatMore' | 'dow.mon' | 'dow.tue' | 'dow.wed' | 'dow.thu' | 'dow.fri' | 'dow.sat' | 'dow.sun' | 'month.jan' | 'month.feb' | 'month.mar' | 'month.apr' | 'month.may' | 'month.jun' | 'month.jul' | 'month.aug' | 'month.sep' | 'month.oct' | 'month.nov' | 'month.dec' | 'dailyTrend' | 'hourlyTrend' | 'trendLimited' | 'usageRanking' | 'byModel' | 'byProvider' | 'tokensColumn' | 'cacheRateColumn' | 'providerModels' | 'other' | 'total' | 'percent' | 'asOf' | 'empty' | 'stats.counts' | 'stats.tokensPerSecond' | 'stats.cacheHit' | 'stats.cacheMiss' | 'stats.dialog.title' | 'stats.dialog.usageTitle' | 'stats.partial' | 'stats.incomplete' | 'stats.dialog.llmTime' | 'stats.dialog.toolTime' | 'stats.dialog.ttft' | 'stats.dialog.speed' | 'stats.dialog.main' | 'stats.dialog.subagents' | 'stats.dialog.subagentCount' | 'stats.dialog.treeTotal' | 'message.turnUsage.count' | 'message.turnUsage.cacheHit' | 'message.turnUsage.input' | 'message.turnUsage.cacheRead' | 'message.turnUsage.cacheWrite' | 'message.turnUsage.output';
 export declare const en: Record<TokenTotalKey, string>;
 export declare const zh: Record<TokenTotalKey, string>;
 export declare const zhTW: Record<TokenTotalKey, string>;

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

@@ -32,6 +32,8 @@ export declare const usageZh: {
     noModels: string;
     scope: string;
     note: string;
+    partialCoverage: string;
+    partialTotals: string;
     failedLoad: string;
     retry: string;
     completed: string;

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

@@ -0,0 +1,16 @@
+import type { UsageSessionEvent, UsageSessionHandle, UsageSessionHeader, UsageSessionPersistence, UsageSessionStore } from './context-types.ts';
+import type { SessionUsageCoverage } from './wire.ts';
+/** Shared membership, ownership and failure semantics for both usage APIs.
+ * A bad descendant is isolated; root, catalog and cancellation failures reject. */
+export interface UsageSessionLog {
+    id: string;
+    header?: UsageSessionHeader;
+    live?: UsageSessionHandle;
+    events: readonly UsageSessionEvent[];
+    inheritedCut: number;
+}
+export declare function readUsageTree(persistence: UsageSessionPersistence, sessions: UsageSessionStore | undefined, rootId: string, signal?: AbortSignal): Promise<{
+    root: UsageSessionLog;
+    descendants: UsageSessionLog[];
+    coverage: SessionUsageCoverage;
+}>;

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

@@ -1,42 +1,14 @@
-/**
- * Per-session usage aggregation, INCLUDING subagent sessions.
- *
- * Why this exists: dsh's native `tokenUsage` projection covers only the main
- * agent of the current session — a session that delegates to subagents (whose
- * own logs are separate persisted sessions, linked by `header.parentSession`)
- * shows only a fraction of what it actually spent. This module answers "what
- * did this whole session tree cost".
- *
- * The store has no per-session dimension (it accumulates per day x model), so
- * this is computed ON DEMAND from the session logs: the root session plus every
- * descendant whose `parentSession` chain leads back to it, each replayed
- * through a fresh {@link UsageFold} (the same dedupe rules the backfill uses).
- *
- * Two correctness rules carried over from the backfill engine:
- *  - a forked log begins with the events it copied from its parent
- *    (`handle.inheritedEventCount`); that prefix is skipped, the parent owns it;
- *  - the fold dedupes per (turn, step) within one session, so a streaming
- *    sample followed by the final message counts once.
- *
- * Results are cached briefly: the composer pill polls, and replaying a long log
- * per poll would be wasteful. The cache is invalidated for a session as soon as
- * a new event lands (see the collector's live subscription).
- */
+/** Per-session owned usage, including every readable descendant. */
 import type { UsageSessionPersistence, UsageSessionStore } from './context-types.ts';
 import type { SessionUsageTree } from './wire.ts';
 export type { SessionUsageTotals, SessionUsageTree } from './wire.ts';
 export declare class SessionUsageService {
-    /** Short-lived tree reads; any live event can invalidate tree membership. */
     private cache;
-    /** Any event can introduce a new descendant while an async read is running. */
     private generation;
-    /** Invalidate conservatively: an unseen session may be a newly-created child
-     *  of ANY cached root, so membership-only invalidation is not safe. */
+    /** New events can introduce descendants of any cached root. */
     invalidate(_sessionId: string): void;
-    /** Resolve the whole session tree rooted at `rootId` and sum its usage.
-     *  `self` is the root's own usage, `subagents` every descendant's, `total`
-     *  the sum. Unreadable logs reject rather than publishing partial totals;
-     *  callers can retain their last good display while surfacing the error. */
+    /** 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. */
     tree(persistence: UsageSessionPersistence, sessions: UsageSessionStore | undefined, rootId: string, signal?: AbortSignal): Promise<SessionUsageTree>;
-    private listHeaders;
 }

package/lib/types/wire.d.ts

@@ -109,6 +109,20 @@ export interface SessionUsageTotals {
     cacheReadTokens: number;
     cacheWriteTokens: number;
 }
+/** A descendant that could not be read. Reasons are stable and sanitized;
+ * exception messages and filesystem paths never cross the wire. */
+export interface SessionUsageReadIssue {
+    sessionId: string;
+    reason: 'corrupt' | 'missing' | 'unavailable';
+}
+/** A partial response is usable, but its totals are explicitly not the whole
+ * tree. The root is always readable; older hosts may omit this field. */
+export interface SessionUsageCoverage {
+    complete: boolean;
+    totalSessions: number;
+    readableSessions: number;
+    unreadableSessions: SessionUsageReadIssue[];
+}
 /** What one session tree cost, split into the main agent and its subagents.
  *  The composer stats row renders this so a delegating session shows its whole
  *  spend (the native `tokenUsage` projection only covers the main agent). */
@@ -124,6 +138,7 @@ export interface SessionUsageTree {
     total: SessionUsageTotals;
     /** How many descendant sessions were counted. */
     subagentSessions: number;
+    coverage?: SessionUsageCoverage;
 }
 /** Request body of POST /token-total/api/session. */
 export interface SessionUsageRequest {
@@ -132,6 +147,7 @@ export interface SessionUsageRequest {
 /** Detailed per-session usage view used by the Usage tab. */
 export interface SessionUsageDetail {
     sessionId: string;
+    coverage?: SessionUsageCoverage;
     totals: SessionUsageTotals;
     requests: number;
     averageFirstTokenMs: number | null;

package/package.json

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

package/src/client/SessionUsageView.tsx

@@ -205,7 +205,12 @@ function Records({ detail, t }: { detail: SessionUsageDetail; t: T }): JSX.Eleme
 /** Pure presentation export also used by offline visual regression fixtures. */
 export function SessionUsageContent({ detail, t, updatedAt }: { detail: SessionUsageDetail; t: T; updatedAt?: number | null }): JSX.Element {
   return <>
-    <p className={css.scope}>{t('scope')}</p><Metrics detail={detail} t={t} /><Tables detail={detail} t={t} />
+    <p className={css.scope}>{t('scope')}</p>
+    {detail.coverage?.complete === false && <div className={css.error} role="status" data-session-usage-partial>
+      {t('partialCoverage', { count: String(detail.coverage.unreadableSessions.length) })}
+      <span title={detail.coverage.unreadableSessions.map(issue => issue.sessionId).join('\n')}>{t('partialTotals')}</span>
+    </div>}
+    <Metrics detail={detail} t={t} /><Tables detail={detail} t={t} />
     {/* The two live cards sit between the per-subagent/model tables and the
         request records: the left one describes what the next request carries
         right now, the right one what the whole session spent, while everything