dsh-token-total 1.1.3 → 1.1.4

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.3",
+  "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

package/src/client/StatsLineEnhanced.tsx

@@ -405,7 +405,8 @@ function UsagePill({ usage, tree, t, dialog, dock }: {
   const billed = display.total
   // Same aggregate as the official pill total: every prompt-side billing bucket plus output.
   const total = billedTotal(billed)
-  const totalText = t('message.turnUsage.count', { count: formatTokensCompact(total) })
+  const incomplete = display.coverage?.complete === false
+  const totalText = (incomplete ? '≥ ' : '') + t('message.turnUsage.count', { count: formatTokensCompact(total) })
   // Native formatting, one consistent scope: the ratio comes from the same
   // aggregate the headline uses, so "33M tok · 87%" can never contradict the
   // number printed beside it. The integer shape and its >99% guard are the
@@ -421,7 +422,8 @@ function UsagePill({ usage, tree, t, dialog, dock }: {
         className={css.pill}
         aria-haspopup="dialog"
         aria-expanded={open}
-        aria-label={cacheHitText === null ? totalText : totalText + ' · ' + cacheHitText}
+        aria-label={(incomplete ? t('stats.partial') + ' · ' : '') + (cacheHitText === null ? totalText : totalText + ' · ' + cacheHitText)}
+        title={incomplete ? t('stats.incomplete', { count: display.coverage!.unreadableSessions.length }) : undefined}
         onClick={() => { setOpen(!open) }}
       >
         <DatabaseIcon />
@@ -451,9 +453,14 @@ function UsagePill({ usage, tree, t, dialog, dock }: {
               <DatabaseIcon />
               {t('stats.dialog.usageTitle')}
             </span>
-            <span className={css.dialogTitleValue}>{exactCount(total)}</span>
+            <span className={css.dialogTitleValue}>{(incomplete ? '≥ ' : '') + exactCount(total)}</span>
           </div>
           <div className={css.dialogTitleRule} aria-hidden />
+          {incomplete && (
+            <p role="status" data-session-usage-partial>
+              {t('stats.incomplete', { count: display.coverage!.unreadableSessions.length })}
+            </p>
+          )}
           {/* Exactly the official dialog's rows, in the official order: the
               takeover adds the tree to the TOTAL, not to the breakdown. */}
           <dl className={css.dialogDetails} data-session-stats-usage>
@@ -509,7 +516,8 @@ export const StatsLineEnhanced = memo(function StatsLineEnhanced(
   // Refresh on main-agent settlements and poll for child-only activity.
   const tree = useSessionUsage(sessionId, usageSignature(usage, stats.steps))
   // A delegated-only session must still show its usage pill.
-  const hasTokens = hasAnyTokens(sessionUsageForDisplay(usage, tree.tree).total)
+  const display = sessionUsageForDisplay(usage, tree.tree)
+  const hasTokens = hasAnyTokens(display.total) || display.coverage?.complete === false
   if (stats.steps === 0 && !hasTokens) return null
   // data-composer-stats: through host 0.1.6-alpha.1 InputBar tightened the
   // composer bottom clearance while this row rendered (the official pills'
@@ -582,7 +590,8 @@ export const StatsUsageEntry = memo(function StatsUsageEntry(
 ) {
   const usage = useProjection('tokenUsage')
   const tree = useSessionUsage(sessionId, usageSignature(usage, usage === undefined ? 0 : 1))
-  const hasTokens = hasAnyTokens(sessionUsageForDisplay(usage, tree.tree).total)
+  const display = sessionUsageForDisplay(usage, tree.tree)
+  const hasTokens = hasAnyTokens(display.total) || display.coverage?.complete === false
   if (!hasTokens) return null
   return (
     <UsagePill

package/src/client/locales.ts

@@ -82,6 +82,8 @@ export type TokenTotalKey =
   | 'stats.cacheMiss'
   | 'stats.dialog.title'
   | 'stats.dialog.usageTitle'
+  | 'stats.partial'
+  | 'stats.incomplete'
   | 'stats.dialog.llmTime'
   | 'stats.dialog.toolTime'
   | 'stats.dialog.ttft'
@@ -170,6 +172,8 @@ export const en: Record<TokenTotalKey, string> = {
   'stats.cacheMiss': 'Cache miss',
   'stats.dialog.title': 'Time & speed',
   'stats.dialog.usageTitle': 'Token usage',
+  'stats.partial': 'Partial usage',
+  'stats.incomplete': '{count} subagent session(s) could not be read; totals are incomplete.',
   'stats.dialog.llmTime': 'LLM time',
   'stats.dialog.toolTime': 'Tool time',
   'stats.dialog.ttft': 'Mean TTFT',
@@ -259,6 +263,8 @@ export const zh: Record<TokenTotalKey, string> = {
   'stats.cacheMiss': '未命中缓存',
   'stats.dialog.title': '用时与速度',
   'stats.dialog.usageTitle': 'Token 用量',
+  'stats.partial': '部分用量',
+  'stats.incomplete': '有 {count} 个子会话暂不可读取，总计尚不完整。',
   'stats.dialog.llmTime': 'LLM 用时',
   'stats.dialog.toolTime': '工具用时',
   'stats.dialog.ttft': '首 token 平均',
@@ -348,6 +354,8 @@ export const zhTW: Record<TokenTotalKey, string> = {
   'stats.cacheMiss': '未命中快取',
   'stats.dialog.title': '用時與速度',
   'stats.dialog.usageTitle': 'Token 用量',
+  'stats.partial': '部分用量',
+  'stats.incomplete': '有 {count} 個子會話暫不可讀取，總計尚不完整。',
   'stats.dialog.llmTime': 'LLM 用時',
   'stats.dialog.toolTime': '工具用時',
   'stats.dialog.ttft': '首 token 平均',

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

@@ -35,6 +35,7 @@ export function sessionUsageForDisplay(
     subagents,
     total: tree === null ? self : combinedTotals(tree, self),
     subagentSessions: tree?.subagentSessions ?? 0,
+    ...(tree?.coverage ? { coverage: tree.coverage } : {}),
   }
 }
 

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

@@ -10,6 +10,7 @@ export const usageZh = {
   empty: '本会话还没有请求记录', noChildren: '暂无子代理', noModels: '暂无模型用量',
   scope: '本会话及所有子代理 · 历史日志累计',
   note: '统计包含本会话与全部后代的独立请求、重试和压缩调用，不重复计算继承历史。首 token 与速度仅使用已记录的时间信息，缺失时显示 —。',
+  partialCoverage: '有 {count} 个子会话暂不可读取。', partialTotals: '当前仅显示已读取用量，未将缺失用量视为零。',
   failedLoad: '用量读取失败，已保留上次结果。', retry: '重新读取', completed: '已完成', running: '进行中', failed: '失败', interrupted: '已中断',
   main: '主会话', turn: '轮', step: '步', started: '开始', duration: '耗时', firstDetail: '首 token',
   provider: '供应商', status: '状态', exact: '完整 token 数',
@@ -50,6 +51,7 @@ export const usageEn: Record<SessionUsageKey, string> = {
   empty: 'No requests in this session yet', noChildren: 'No subagents yet', noModels: 'No model usage yet',
   scope: 'This session and all subagents · Historical log totals',
   note: 'Includes independent requests, retries and compaction calls from this session and all descendants, without counting inherited history twice. Timing uses recorded timestamps only; missing values appear as —.',
+  partialCoverage: '{count} subagent session(s) could not be read.', partialTotals: 'Only readable usage is shown; missing usage is not treated as zero.',
   failedLoad: 'Could not read usage. The last successful result is preserved.', retry: 'Retry', completed: 'Completed', running: 'Running', failed: 'Failed', interrupted: 'Interrupted',
   main: 'Main session', turn: 'Turn', step: 'Step', started: 'Started', duration: 'Duration', firstDetail: 'First token',
   provider: 'Provider', status: 'Status', exact: 'Exact token count',
@@ -89,6 +91,7 @@ export const usageZhTW: Record<SessionUsageKey, string> = {
   loading: '正在讀取會話用量…', empty: '本會話還沒有請求記錄', noChildren: '暫無子代理', noModels: '暫無模型用量',
   scope: '本會話及所有子代理 · 歷史日誌累計',
   note: '統計包含本會話與全部後代的獨立請求、重試和壓縮呼叫，不重複計算繼承歷史。首 token 與速度僅使用已記錄的時間資訊，缺失時顯示 —。',
+  partialCoverage: '有 {count} 個子會話暫不可讀取。', partialTotals: '目前僅顯示已讀取用量，未將缺失用量視為零。',
   failedLoad: '用量讀取失敗，已保留上次結果。', retry: '重新讀取', completed: '已完成', running: '進行中', failed: '失敗', interrupted: '已中斷',
   main: '主會話', turn: '輪', step: '步', started: '開始', duration: '耗時', firstDetail: '首 token', provider: '供應商', status: '狀態', exact: '完整 token 數',
   answering: '正在回答...', firstWait: '首字耗時', sec: '秒', tokenWord: 'token', perSec: 'token/秒',

package/src/session-detail.ts

@@ -1,12 +1,5 @@
-import type {
-  Context,
-  UsageSessionEvent,
-  UsageSessionHandle,
-  UsageSessionHeader,
-  UsageSessionPersistence,
-  UsageSessionSnapshot,
-  UsageSessionStore,
-} from './context-types.ts'
+import type { Context, UsageSessionHeader, UsageSessionPersistence, UsageSessionStore } from './context-types.ts'
+import { readUsageTree, type UsageSessionLog } from './session-tree.ts'
 import { UsageFold } from './collector.ts'
 import { buildSessionContextWindow } from './context-window.ts'
 import { buildSessionUsageComposition, mergeUsageCompositions } from './usage-composition.ts'
@@ -83,22 +76,6 @@ function usageOutputTokens(x: any): number | null {
   const value = (x?.usage ?? x)?.outputTokens
   return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null
 }
-function headerOf(item: UsageSessionHeader | UsageSessionSnapshot): UsageSessionHeader | null {
-  const x: any = 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: UsageSessionPersistence, id: string, live?: UsageSessionHandle): Promise<{ events: readonly UsageSessionEvent[]; cut: number }> {
-  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: UsageSessionEvent[] = []
-    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)')
-}
 
 type MutableRecord = SessionUsageDetail['records'][number] & { _attempt: number; _lastUsage: SessionUsageTotals }
 function nameOf(h: UsageSessionHeader | undefined, id: string): string {
@@ -109,8 +86,8 @@ function nameOf(h: UsageSessionHeader | undefined, id: string): string {
   return id
 }
 
-async function one(p: UsageSessionPersistence, id: string, header: UsageSessionHeader | undefined, live: UsageSessionHandle | undefined) {
-  const { events, cut } = await read(p, id, live)
+function one(log: UsageSessionLog) {
+  const { id, header, live, events, inheritedCut: cut } = log
   const fold = new UsageFold(); const totals = zero(); const records: MutableRecord[] = []
   const byKey = new Map<string, MutableRecord>(); let route = live?.requestContext?.() ?? {}
   let ordinal = 0
@@ -214,14 +191,8 @@ async function one(p: UsageSessionPersistence, id: string, header: UsageSessionH
 }
 
 export async function buildSessionUsageDetail(persistence: UsageSessionPersistence, sessions: UsageSessionStore | undefined, rootId: string, ctx?: Context): Promise<SessionUsageDetail> {
-  const raw = await persistence.list(typeof persistence.open === 'function' ? undefined : undefined)
-  const headers = raw.map(headerOf).filter((x): x is UsageSessionHeader => x !== null)
-  const live = new Map((sessions?.list() ?? []).map(x => [x.id, x])); const children = new Map<string, string[]>()
-  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: string[] = []; const seen = 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 { root, descendants, coverage } = await readUsageTree(persistence, sessions, rootId)
+  const parts = [root, ...descendants].map(one)
   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 }))
@@ -248,5 +219,5 @@ export async function buildSessionUsageDetail(persistence: UsageSessionPersisten
   // The card is scoped to this session and every subagent, so its speed and
   // first-token average fold the same records its token totals do.
   const firsts = records.filter(x => x.status === 'completed').map(x => x.firstTokenMs).filter((x): x is number => x !== null)
-  return { sessionId: rootId, totals, requests: parts.reduce((n, p) => n + p.requests, 0), averageFirstTokenMs: firsts.length ? firsts.reduce((a, b) => a + b, 0) / firsts.length : null, tokensPerSecond: decodeRateOf(records), subagents, models: [...models.entries()].map(([model, x]) => { const name = displayNameOf(model, x.providers); return { model, ...(name ? { name } : {}), providers: [...x.providers].map(provider => providerNames[provider] || provider), totals: x.totals, requests: x.requests } }), records, routes: [...routeMap.values()], context: parts[0]?.context ?? null, composition: mergeUsageCompositions(parts.map(p => p.composition)) }
+  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, tokensPerSecond: decodeRateOf(records), subagents, models: [...models.entries()].map(([model, x]) => { const name = displayNameOf(model, x.providers); return { model, ...(name ? { name } : {}), providers: [...x.providers].map(provider => providerNames[provider] || provider), totals: x.totals, requests: x.requests } }), records, routes: [...routeMap.values()], context: parts[0]?.context ?? null, composition: mergeUsageCompositions(parts.map(p => p.composition)) }
 }

package/src/session-tree.ts

@@ -0,0 +1,146 @@
+import type {
+  UsageSessionEvent,
+  UsageSessionHandle,
+  UsageSessionHeader,
+  UsageSessionPersistence,
+  UsageSessionSnapshot,
+  UsageSessionStore,
+} from './context-types.ts'
+import type { SessionUsageCoverage, SessionUsageReadIssue } 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
+}
+
+function headerOf(item: UsageSessionHeader | UsageSessionSnapshot): UsageSessionHeader | null {
+  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: unknown): number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 0
+}
+
+function throwIfCanceled(error: unknown, signal?: AbortSignal): void {
+  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: string, error: unknown): SessionUsageReadIssue {
+  const name = error && typeof error === 'object' && 'name' in error ? error.name : ''
+  const code = error && typeof error === 'object' && 'code' in error ? error.code : ''
+  const reason = name === 'SessionPersistenceCorruptionError' || name === 'SessionFormatError'
+    ? 'corrupt'
+    : name === 'SessionPersistenceNotFoundError' || code === 'ENOENT' ? 'missing' : 'unavailable'
+  return { sessionId, reason }
+}
+
+async function readSession(
+  persistence: UsageSessionPersistence,
+  id: string,
+  header: UsageSessionHeader | undefined,
+  live: UsageSessionHandle | undefined,
+  signal?: AbortSignal,
+): Promise<UsageSessionLog> {
+  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 === undefined ? undefined : { signal }
+    const handle = await persistence.open(id, 'read', options)
+    try {
+      const events: UsageSessionEvent[] = []
+      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)')
+}
+
+export async function readUsageTree(
+  persistence: UsageSessionPersistence,
+  sessions: UsageSessionStore | undefined,
+  rootId: string,
+  signal?: AbortSignal,
+): Promise<{ root: UsageSessionLog; descendants: UsageSessionLog[]; coverage: SessionUsageCoverage }> {
+  signal?.throwIfAborted()
+  const rows = await persistence.list(typeof persistence.open === 'function'
+    ? signal === undefined ? undefined : { signal }
+    : signal)
+  const headers = new Map<string, UsageSessionHeader>()
+  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 = new Map<string, Set<string>>()
+  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)
+  }
+  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: string[] = []
+  const seen = 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: Array<UsageSessionLog | undefined> = new Array(ids.length)
+  const issues: Array<SessionUsageReadIssue | undefined> = new Array(ids.length)
+  let next = 0
+  // Bound full-log reads; preserve catalog order regardless of completion order.
+  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 is UsageSessionLog => log !== undefined)
+  const unreadableSessions = issues.filter((issue): issue is SessionUsageReadIssue => issue !== undefined)
+  return {
+    root,
+    descendants,
+    coverage: { complete: unreadableSessions.length === 0, totalSessions: ids.length + 1, readableSessions: descendants.length + 1, unreadableSessions },
+  }
+}