dsh-token-total 1.1.2 → 1.1.4

package/src/client/StatsLineEnhanced.tsx

@@ -31,14 +31,14 @@
  * cannot see.
  *
  * Streaming throughput replaces the gauge pill's speed
- * figure with a live estimate of what is happening now. The figure is the
- * streaming step's measured rate while one streams and the LAST measured rate
- * once it settles — a session average describes the whole session's past, and
- * it cannot match the pace of the answer on screen, which is what users read
- * as the pill disagreeing with the stream in front of them. The official
- * session figure only shows on a session that has never streamed. That
- * subscription lives in
- * its own child component so stream deltas never re-render the pills. The live
+ * figure with a live estimate of what is happening now, and hands the slot back
+ * to the session's decode average when nothing is streaming. While a step
+ * streams the live rate is the only reading that can match the pace of the
+ * answer on screen; once the step settles it becomes a figure from a window
+ * nobody is watching any more, so the pill returns to the same quotient the
+ * usage view quotes (ΣoutputTokens / ΣdecodeMs) instead of freezing on the last
+ * measurement. That subscription lives in its own child component, so stream
+ * deltas never re-render the pills. The live
  * figure itself is measured by a bounded sliding window over observed token
  * growth (stats-line-core's StreamingRateSampler): the earlier cumulative
  * quotient charged a whole step's text to a window that had just opened, so a
@@ -181,14 +181,23 @@ const LIVE_SPEED_REFRESH_MS = 1_000
  * The gauge pill's always-on streaming speed slot.
  *
  * It subscribes to `legacy.partial` itself so per-frame deltas re-render only
- * this child, not the surrounding pills. The figure it carries is the CURRENT
- * stream's measured rate, and it stays that rate once the step settles:
- * tool execution and the gap between steps happen inside the same answer, and
- * the session average this slot used to fall back to there is a figure from
- * the whole session's past — a number that cannot match the pace of the answer
- * on screen, which is what reads as "not the real-time speed". The official
- * session figure is only a session's opening state, shown until the first
- * window measures anything.
+ * this child, not the surrounding pills. Two figures share the slot, chosen by
+ * whether a step is streaming right now:
+ *
+ * - while one is (`partial != null`), the measured rate of THAT stream — a
+ *   bounded sliding window over observed token growth (stats-line-core's
+ *   StreamingRateSampler), the only reading that can track the pace of the
+ *   answer currently on screen;
+ * - otherwise the session's own decode average, ΣoutputTokens / ΣdecodeMs —
+ *   the same quotient `decodeRateOf` quotes in the usage view. An idle composer
+ *   must not freeze on whatever the last window happened to measure: a settled
+ *   thirty-step turn kept showing its final second-long reading (57 tok/s)
+ *   beside the usage view's 156 tok/s for the same work, and the two read as a
+ *   contradiction rather than as two scopes of one number.
+ *
+ * The measured reading carries the step it was taken in, so a new step cannot
+ * inherit the previous one's figure before its own window publishes; nothing is
+ * held across the gap — the gap is exactly when the average applies.
  *
  * One window covers a whole step, across every output kind the accumulator
  * carries — reasoning, answer text, and Tool-call arguments — because the
@@ -199,13 +208,16 @@ const LIVE_SPEED_REFRESH_MS = 1_000
  * state, so no render reads a clock or mutates the window: a render React starts
  * and then discards must not decide what the next committed one displays. The
  * rate itself comes from stats-line-core's StreamingRateSampler — a bounded
- * window over observed token growth, smoothed, and held while nothing arrives.
+ * window over observed token growth, smoothed, and held while nothing arrives
+ * inside the step it belongs to.
  */
 function LiveSpeed({ useChat, scale, fallback, t }: {
   useChat: ChatSnapshotSelectorHook
   /** Correction measured from this session's settled steps (1 = raw prior). */
   scale: number
-  /** The official session figure, shown until the slot has measured its own. */
+  /** The session's own decode average (ΣoutputTokens / ΣdecodeMs): what the
+   *  slot shows whenever no step is streaming, and before the streaming step's
+   *  window has published its first reading. */
   fallback: string | null
   t: T
 }) {
@@ -223,18 +235,22 @@ function LiveSpeed({ useChat, scale, fallback, t }: {
     sampler.current = { key, rate: new StreamingRateSampler() }
   }
   const rate = sampler.current.rate
-  // The latest figure this slot has measured, held across step boundaries. A
-  // settled step's rate is still the conversation's current speed until the
-  // next step measures its own, so the display keeps it instead of switching to
-  // a session average the moment the stream goes quiet — holding it is the
-  // point, not a stale value to guard against, which is why no step tag rides
-  // along any more.
-  const [reading, setReading] = useState<number | null>(null)
+  // The figure last measured, tagged with the step it came from. The tag is
+  // what retires it: a reading taken in 3:4 never shows during 3:5, and with
+  // no step streaming (`key === null`) no tag can match at all, so the slot
+  // falls through to the session average on its own — no timer, no clearing
+  // effect, and no stale figure left standing after a turn settles.
+  const [reading, setReading] = useState<{ key: string; value: number } | null>(null)
   const scaleRef = useRef(scale)
   // Every delta re-runs this (its dependencies move), and the beat re-runs it once
   // a second so a step that has gone quiet still advances its window.
   const [beat, setBeat] = useState(0)
   useLayoutEffect(() => {
+    // Nothing is streaming: the slot shows the session average, and there is no
+    // window to advance. Skipping the observation also keeps a settled step's
+    // sampler from being fed a zero estimate, which would re-anchor it against
+    // text that is already counted.
+    if (key === null) return
     // A correction that moved re-prices the whole estimate, so growth already
     // counted under the old one must not be measured against the new one: that
     // would read as a burst the stream never produced.
@@ -244,11 +260,13 @@ function LiveSpeed({ useChat, scale, fallback, t }: {
     }
     rate.observe(tokens, Date.now())
     // A null here means the fresh window has not measured anything yet (a step
-    // that just opened, or one that re-anchored); the figure already on screen
-    // is still the best current reading, so it is left alone.
+    // that just opened, or one that re-anchored); the average stays up until
+    // this step's own window publishes something.
     const next = rate.ratePerSecond()
     if (next !== null) {
-      setReading(previous => (previous === next ? previous : next))
+      setReading(previous => (previous !== null && previous.key === key && previous.value === next
+        ? previous
+        : { key, value: next }))
     }
   }, [tokens, key, beat, rate, scale])
   // Keyed on "a step is streaming", not on the step identity: switching steps
@@ -259,9 +277,12 @@ function LiveSpeed({ useChat, scale, fallback, t }: {
     const handle = setInterval(() => { setBeat(Date.now()) }, LIVE_SPEED_REFRESH_MS)
     return () => { clearInterval(handle) }
   }, [streaming])
-  return <SpeedFigure text={reading === null
+  // The tag test is the whole selection rule: a reading only shows while the
+  // step that produced it is the step streaming now.
+  const measured = reading !== null && reading.key === key ? reading.value : null
+  return <SpeedFigure text={measured === null
     ? fallback
-    : t('stats.tokensPerSecond', { throughput: formatTokensPerSecond(reading) })} />
+    : t('stats.tokensPerSecond', { throughput: formatTokensPerSecond(measured) })} />
 }
 
 function TimePill({ stats, t, dialog, useChat, scale, dock }: {
@@ -278,9 +299,10 @@ function TimePill({ stats, t, dialog, useChat, scale, dock }: {
 }) {
   const { open, setOpen, rootRef, panelRef, pos } = useStatDialog(dialog)
   const counts = t('stats.counts', { turns: stats.turns, steps: stats.steps })
-  // The pill's accessible name stays on the official figure: a screen reader
-  // gets the durable session reading rather than a value that changes every
-  // second while a step streams.
+  // The session figure now serves both jobs: the pill's accessible name (a
+  // screen reader gets the durable session reading rather than a value that
+  // changes every second while a step streams) and the visible figure whenever
+  // no step is streaming.
   const officialTps = stats.decodeMs > 0
     ? t('stats.tokensPerSecond', {
       throughput: formatTokensPerSecond(stats.decodeTokens / (stats.decodeMs / 1_000)),
@@ -383,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
@@ -399,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 />
@@ -429,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>
@@ -487,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'
@@ -560,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 },
+  }
+}