dsh-token-total 1.1.3 → 1.1.5

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

package/src/session-usage.ts

@@ -1,48 +1,12 @@
-/**
- * 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).
- */
-
-import type {
-  UsageSessionEvent,
-  UsageSessionHandle,
-  UsageSessionHeader,
-  UsageSessionPersistence,
-  UsageSessionSnapshot,
-  UsageSessionStore,
-} from './context-types.ts'
+/** Per-session owned usage, including every readable descendant. */
+import type { UsageSessionPersistence, UsageSessionStore } from './context-types.ts'
 import { UsageFold } from './collector.ts'
+import { readUsageTree, type UsageSessionLog } from './session-tree.ts'
 import type { SessionUsageTotals, SessionUsageTree } from './wire.ts'
 
 export type { SessionUsageTotals, SessionUsageTree } from './wire.ts'
 
-const ZERO: SessionUsageTotals = {
-  uncachedInputTokens: 0,
-  outputTokens: 0,
-  cacheReadTokens: 0,
-  cacheWriteTokens: 0,
-}
-
+const zero = (): SessionUsageTotals => ({ uncachedInputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 })
 function add(into: SessionUsageTotals, from: SessionUsageTotals): void {
   into.uncachedInputTokens += from.uncachedInputTokens
   into.outputTokens += from.outputTokens
@@ -50,81 +14,13 @@ function add(into: SessionUsageTotals, from: SessionUsageTotals): void {
   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 = 4_000
-/** 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: UsageSessionHeader | UsageSessionSnapshot): UsageSessionHeader | null {
-  const snap = item as { header?: { id?: unknown } }
-  if (snap !== null && typeof snap === 'object' && 'header' in snap
-    && snap.header !== null && typeof snap.header === 'object'
-    && typeof snap.header.id === 'string') {
-    return snap.header as UsageSessionHeader
-  }
-  const row = item as UsageSessionHeader
-  return typeof row?.id === 'string' && row.id !== '' ? row : null
-}
-
-function inheritedCount(cut: unknown): number {
-  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: UsageSessionPersistence,
-  id: string,
-  signal?: AbortSignal,
-): Promise<{ events: readonly UsageSessionEvent[]; inheritedCut: number }> {
-  if (typeof persistence.open === 'function') {
-    const handle = await persistence.open(id, 'read', signal === undefined ? undefined : { signal })
-    try {
-      const inheritedCut = inheritedCount(handle.inheritedEventCount)
-      const collected: UsageSessionEvent[] = []
-      let offset = 0
-      const PAGE = 500
-      for (;;) {
-        signal?.throwIfAborted()
-        const slice = await handle.read(offset, PAGE, signal === undefined ? undefined : { signal })
-        const page = ((slice && slice.events) ? slice.events : []) as readonly UsageSessionEvent[]
-        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: UsageSessionPersistence,
-  id: string,
-  signal?: AbortSignal,
-  live?: UsageSessionHandle,
-): Promise<{ totals: SessionUsageTotals; compaction: SessionUsageTotals }> {
-  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: UsageSessionLog): { totals: SessionUsageTotals; compaction: SessionUsageTotals } {
   const fold = new UsageFold()
-  const totals: SessionUsageTotals = { ...ZERO }
-  const compaction: SessionUsageTotals = { ...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: SessionUsageTotals = {
       uncachedInputTokens: sample.inputTokens,
@@ -133,28 +29,27 @@ async function sumOneSession(
       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 = 4_000
+const CACHE_MAX = 64
+
 export class SessionUsageService {
-  /** Short-lived tree reads; any live event can invalidate tree membership. */
   private cache = new Map<string, { at: number; value: SessionUsageTree }>()
-  /** Any event can introduce a new descendant while an async read is running. */
   private 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: string): void {
     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: UsageSessionPersistence,
     sessions: UsageSessionStore | undefined,
@@ -165,69 +60,25 @@ export class SessionUsageService {
     const hit = this.cache.get(rootId)
     if (hit !== undefined && Date.now() - hit.at < CACHE_TTL_MS) return hit.value
     const generation = this.generation
-
-    const headers = await this.listHeaders(persistence, signal)
-    const children = new Map<string, string[]>()
-    for (const header of headers) {
-      const parent = header.parentSession
-      if (typeof parent !== 'string' || parent === '') continue
-      const bucket = children.get(parent)
-      if (bucket === undefined) children.set(parent, [header.id])
-      else bucket.push(header.id)
-    }
-    // A brand-new live subagent may not be materialized in persistence yet;
-    // the live store still knows its parent, so fold those in too.
-    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 === undefined) children.set(parent, [handle.id])
-      else if (!bucket.includes(handle.id)) bucket.push(handle.id)
-    }
-
-    const descendants: string[] = []
-    const seen = new Set<string>([rootId])
-    const queue = [rootId]
-    while (queue.length > 0) {
-      const current = queue.shift() as string
-      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: SessionUsageTotals = { ...ZERO }
-    for (const id of descendants) {
-      const one = await sumOneSession(persistence, id, signal, live.get(id))
-      add(subagents, one.totals)
-    }
-    const total: SessionUsageTotals = { ...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: SessionUsageTree = { self, selfCompaction: root.compaction, subagents, total, subagentSessions: descendants.length }
-
+    const value: SessionUsageTree = {
+      self: own.totals,
+      selfCompaction: own.compaction,
+      subagents,
+      total,
+      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(), value })
     }
     return value
   }
-
-  private async listHeaders(
-    persistence: UsageSessionPersistence,
-    signal?: AbortSignal,
-  ): Promise<UsageSessionHeader[]> {
-    const useAlphaList = typeof persistence.open === 'function'
-    const raw = useAlphaList
-      ? await persistence.list(signal === undefined ? undefined : { signal })
-      : await persistence.list(signal as never)
-    return (raw as Array<UsageSessionHeader | UsageSessionSnapshot>)
-      .map(headerOf)
-      .filter((h): h is UsageSessionHeader => h !== null)
-  }
 }