dsh-token-total 1.0.1 → 1.0.2

package/src/client/ContextUsageEntry.tsx

@@ -0,0 +1,89 @@
+import { createPortal } from 'react-dom'
+import { useEffect, useLayoutEffect, useRef, useState } from 'react'
+import { useAnchoredPosition, useDismissOnOutsidePointer } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
+import { MEASURE_STYLE } from './stat-dialog.ts'
+import { contextBreakdownSegments, contextOccupancy, formatContextTokens, type ContextBreakdownLike, type ContextPressureLike } from './context-meter-core.ts'
+import css from './ContextUsageEntry.module.css'
+
+export const CONTEXT_LOCALE_NS = 'tokenTotalContext'
+const keys = ['label', 'used', 'system', 'tools', 'messages', 'aria', 'thousand', 'million'] as const
+export type ContextLocaleKey = typeof keys[number]
+export const CONTEXT_LOCALES: Record<string, Record<ContextLocaleKey, string>> = {
+  zh: { label: '上下文', used: '已用上下文', system: '系统提示词', tools: '工具', messages: '对话', aria: '上下文占用 {percent}', thousand: '{value}千', million: '{value}百万' },
+  en: { label: 'Context', used: 'Context used', system: 'System', tools: 'Tools', messages: 'Conversation', aria: 'Context usage {percent}', thousand: '{value}K', million: '{value}M' },
+  'zh-TW': { label: '上下文', used: '已用上下文', system: '系統提示詞', tools: '工具', messages: '對話', aria: '上下文使用量 {percent}', thousand: '{value}千', million: '{value}百萬' },
+}
+
+type ProjectionMap = {
+  contextPressure: ContextPressureLike
+  contextBreakdown: ContextBreakdownLike
+}
+type UseContextProjection = <K extends keyof ProjectionMap & string>(key: K) => ProjectionMap[K] | undefined
+
+export interface ContextUsageEntryProps extends PropsLocale<typeof CONTEXT_LOCALE_NS> {
+  useProjection: UseContextProjection
+  installContextTakeover?: (anchor: HTMLElement) => () => void
+}
+
+export function ContextUsageEntry({ useProjection, t, installContextTakeover }: ContextUsageEntryProps): JSX.Element | null {
+  const pressure = useProjection('contextPressure')
+  const breakdown = useProjection('contextBreakdown')
+  const context = contextOccupancy(pressure)
+  const [open, setOpen] = useState(false)
+  const rootRef = useRef<HTMLSpanElement | null>(null)
+  const panelRef = useRef<HTMLDivElement | null>(null)
+  const position = useAnchoredPosition({ open: open && context !== null, anchorRef: rootRef, panelRef, side: 'top', gap: 8, margin: 12 })
+  useDismissOnOutsidePointer(rootRef, open && context !== null, setOpen, panelRef)
+  useLayoutEffect(() => {
+    const anchor = rootRef.current
+    if (anchor === null || context === null || installContextTakeover === undefined) return
+    return installContextTakeover(anchor)
+  }, [context !== null, installContextTakeover])
+  useEffect(() => { if (context === null && open) setOpen(false) }, [context, open])
+  useEffect(() => {
+    if (!open || context === null) return
+    const onKeyDown = (event: KeyboardEvent): void => { if (event.key === 'Escape') setOpen(false) }
+    document.addEventListener('keydown', onKeyDown)
+    return () => document.removeEventListener('keydown', onKeyDown)
+  }, [context, open])
+  if (context === null) return null
+  const percent = context.percent
+  const reading = `${percent}%`
+  const total = breakdown === undefined ? 0 : breakdown.systemTokens + breakdown.toolsTokens + breakdown.messageTokens
+  const segments = contextBreakdownSegments(percent, breakdown)
+  const format = (value: number): string => formatContextTokens(value, {
+    thousand: t('thousand'), million: t('million'),
+  })
+  const label = (part: 'system' | 'tools' | 'messages'): string => t(part)
+  return (
+    <span ref={rootRef} className={css.root} data-dsh-token-total-stat="context">
+      <button type="button" className={css.trigger} aria-label={t('aria', { percent: reading })} aria-haspopup="dialog" aria-expanded={open} onClick={() => setOpen(!open)}>
+        <svg viewBox="0 0 14 14" width="14" height="14" aria-hidden="true">
+          <circle className={css.track} cx="7" cy="7" r="5.5" />
+          <circle className={css.fill} cx="7" cy="7" r="5.5" strokeDasharray={`${2 * Math.PI * 5.5 * percent / 100} ${2 * Math.PI * 5.5}`} transform="rotate(-90 7 7)" />
+        </svg>
+        <span>{reading}</span>
+      </button>
+      {open && createPortal(
+        <div ref={panelRef} className={css.panel} style={position ?? MEASURE_STYLE} role="dialog" aria-label={t('used')}>
+          <div className={css.header}>
+            <span>{t('used')}</span><span className={css.percent}>{reading}</span>
+            <span className={css.figures}>{`~${format(context.usedTokens)} / ${format(context.contextWindow)}`}</span>
+          </div>
+          <div className={css.bar}>{segments.map(segment => <div key={segment.key} className={`${css.segment} ${css[segment.key] ?? ''}`} style={{ width: `${segment.width}%` }} />)}</div>
+          {breakdown !== undefined && total > 0 && <dl className={css.rows}>
+            {(['systemTokens', 'toolsTokens', 'messageTokens'] as const).map((key, index) => <div className={css.row} key={key}>
+              <dt><span className={`${css.swatch} ${css[key]}`} />{label((['system', 'tools', 'messages'] as const)[index])}</dt>
+              <dd>{`~${format(breakdown[key])}`}</dd>
+            </div>)}
+          </dl>}
+        </div>, document.body,
+      )}
+    </span>
+  )
+}
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface LocaleNamespaceMap { tokenTotalContext: ContextLocaleKey }
+}

package/src/client/StatsLineEnhanced.tsx

@@ -297,7 +297,7 @@ function TimePill({ stats, t, dialog, useChat, scale, dock }: {
     )
   }
   return (
-    <span ref={rootRef} className={anchorClass(dock)}>
+    <span ref={rootRef} className={anchorClass(dock)} data-dsh-token-total-stat>
       <button
         type="button"
         className={css.pill}
@@ -383,7 +383,7 @@ function UsagePill({ usage, tree, t, dialog, dock }: {
   const exactCount = (value: number): string =>
     t('message.turnUsage.count', { count: formatTokens(value) })
   return (
-    <span ref={rootRef} className={anchorClass(dock)}>
+    <span ref={rootRef} className={anchorClass(dock)} data-dsh-token-total-stat>
       <button
         type="button"
         className={css.pill}

package/src/client/TokenTotalPanel.tsx

@@ -282,7 +282,7 @@ export function TokenTotalPanel({ t }: { t: Translator }): JSX.Element {
  *  (zero input/output but real cache hits) or a failed-call day (requests
  *  but no tokens) both carry real usage and must not read as "no data". */
 function isEmptyRange(stats: TokenTotalRange): boolean {
-  return stats.tokens === 0 && stats.cacheHit === 0 && stats.requests === 0 && stats.turns === 0
+  return stats.tokens === 0 && stats.cacheHit === 0 && stats.requests === 0 && stats.failures === 0 && stats.turns === 0
 }
 
 function StatCards({ stats, t }: { stats: TokenTotalRange; t: Translator }) {
@@ -299,8 +299,10 @@ function StatCards({ stats, t }: { stats: TokenTotalRange; t: Translator }) {
     { icon: Database, label: t('cacheTokens'), value: formatCompact(stats.cacheTokens), sub: `${formatTokens(stats.cacheTokens)} ${t('tokensUnit')}` },
     // 缓存命中率 —cached share of all prompt tokens in the range.
     { icon: Activity, label: t('cacheRate'), value: cacheRateText(stats.cacheHit, stats.cacheMiss), hint: t('cacheRateHint'), sub: `${formatCompact(stats.cacheHit)} ${t('cachedTokens')}` },
-    // 请求数量 —provider calls (tokens or not).
-    { icon: MessagesSquare, label: t('requests'), value: String(stats.requests) },
+    // 请求数量 —provider calls (tokens or not). The failed share sits
+    // underneath, and only when there were any: a healthy range stays a
+    // single line. Failed calls are a SUBSET of requests, never additive.
+    { icon: MessagesSquare, label: t('requests'), value: String(stats.requests), sub: stats.failures > 0 ? `${t('requestsFailed')} ${stats.failures} · ${formatPercent((stats.failures / Math.max(stats.requests, 1)) * 100)}` : undefined },
   ]
   return (
     <div className={css.cards}>

package/src/client/context-meter-core.ts

@@ -0,0 +1,54 @@
+export interface ContextPressureLike {
+  projectedTokens?: number
+  pressureTokens?: number
+  contextWindow?: number
+}
+
+export interface ContextBreakdownLike {
+  systemTokens: number
+  toolsTokens: number
+  messageTokens: number
+}
+
+export interface ContextOccupancy {
+  percent: number
+  usedTokens: number
+  contextWindow: number
+}
+
+/** Mirrors the host meter's occupancy calculation exactly. */
+export function contextOccupancy(pressure: ContextPressureLike | undefined): ContextOccupancy | null {
+  const usedTokens = pressure?.projectedTokens ?? pressure?.pressureTokens
+  if (usedTokens === undefined || pressure?.contextWindow === undefined) return null
+  return {
+    percent: Math.min(100, Math.round(usedTokens / pressure.contextWindow * 100)),
+    usedTokens,
+    contextWindow: pressure.contextWindow,
+  }
+}
+
+export function contextBreakdownTotal(breakdown: ContextBreakdownLike | undefined): number {
+  return breakdown === undefined ? 0 : breakdown.systemTokens + breakdown.toolsTokens + breakdown.messageTokens
+}
+
+export function contextBreakdownSegments(
+  percent: number,
+  breakdown: ContextBreakdownLike | undefined,
+): Array<{ key: string; width: number }> {
+  const total = contextBreakdownTotal(breakdown)
+  if (breakdown === undefined || total === 0) return [{ key: 'total', width: percent }]
+  return [
+    { key: 'systemTokens', width: percent * breakdown.systemTokens / total },
+    { key: 'toolsTokens', width: percent * breakdown.toolsTokens / total },
+    { key: 'messageTokens', width: percent * breakdown.messageTokens / total },
+  ].filter(segment => segment.width > 0)
+}
+
+export function formatContextTokens(value: number, units: { thousand: string; million: string }): string {
+  const scaled = (candidate: number): string => candidate >= 100
+    ? String(Math.round(candidate))
+    : String(Math.round(candidate * 10) / 10)
+  if (value < 1e3) return String(value)
+  if (value < 1e6) return units.thousand.replace('{value}', scaled(value / 1e3))
+  return units.million.replace('{value}', scaled(value / 1e6))
+}

package/src/client/context-takeover.ts

@@ -0,0 +1,35 @@
+/** The host ContextMeter is hard-coded beside composer.dock, not a slot.
+ * Suppress only that recognizable sibling while our replacement is mounted;
+ * never hide a whole dock, slot wrapper, or another plugin's readout. */
+export function installContextTakeover(anchor: HTMLElement): () => void {
+  const dock = anchor.closest<HTMLElement>('[data-composer-dock]')
+  const view = anchor.ownerDocument.defaultView
+  if (dock === null || view === null) return () => {}
+  const hidden = new Map<HTMLElement, { display: string; priority: string }>()
+  const reconcile = (): void => {
+    for (const sibling of Array.from(dock.children)) {
+      if (!(sibling instanceof view.HTMLElement) || sibling.tagName !== 'SPAN'
+        || sibling.contains(anchor) || sibling.hasAttribute('data-slot-entry')
+        || sibling.hasAttribute('data-dsh-token-total-stat')
+        || hidden.has(sibling)) continue
+      // ContextMeter's stable SVG geometry, not a private CSS-module hash or
+      // a translated label. Current hosts mount its span directly in the dock.
+      if (sibling.querySelector('button[aria-haspopup="dialog"] svg[viewBox="0 0 14 14"] circle[cx="7"][cy="7"][r="5.5"]') === null) continue
+      hidden.set(sibling, { display: sibling.style.getPropertyValue('display'), priority: sibling.style.getPropertyPriority('display') })
+      sibling.setAttribute('data-dsh-token-total-native-context', '')
+      sibling.style.setProperty('display', 'none', 'important')
+    }
+  }
+  reconcile()
+  const observer = new view.MutationObserver(reconcile)
+  observer.observe(dock, { childList: true, subtree: true })
+  return () => {
+    observer.disconnect()
+    for (const [element, previous] of hidden) {
+      element.removeAttribute('data-dsh-token-total-native-context')
+      if (previous.display === '') element.style.removeProperty('display')
+      else element.style.setProperty('display', previous.display, previous.priority)
+    }
+    hidden.clear()
+  }
+}

package/src/client/index.tsx

@@ -34,6 +34,8 @@ import { ArrowLeft } from 'lucide-react'
 import { TokenTotalPanel } from './TokenTotalPanel.tsx'
 import { StatsIcon } from './stats-icon.tsx'
 import { StatsActivityEntry, StatsLineEnhanced, StatsUsageEntry } from './StatsLineEnhanced.tsx'
+import { ContextUsageEntry, CONTEXT_LOCALE_NS, CONTEXT_LOCALES } from './ContextUsageEntry.tsx'
+import { installContextTakeover } from './context-takeover.ts'
 import { LOCALE_NS, en, zh, zhTW, type TokenTotalKey } from './locales.ts'
 import { isCompatibleGlass, whenGlassReady } from './glass.ts'
 import css from './TokenTotalPanel.module.css'
@@ -117,14 +119,27 @@ const COMPOSER_DOCK = 'conversation.composer.dock'
 
 /** The pre-split takeover: ONE entry at the official 'stats' id, rendering the
  *  whole row (DSH <= 0.2.0-rc.2). */
-function installStatsRowEntry(ctx: Context): () => void {
+function installContextEntry(ctx: Context): () => void {
   return ctx.slots.register({
+    name: COMPOSER_DOCK,
+    id: 'token-total-context',
+    order: 2,
+    priority: -1,
+    locale: CONTEXT_LOCALE_NS,
+    inject: () => ({ installContextTakeover }),
+  }, ContextUsageEntry)
+}
+
+function installStatsRowEntry(ctx: Context): () => void {
+  const offStats = ctx.slots.register({
     name: COMPOSER_DOCK,
     id: 'stats',
     order: 0,
     priority: -1,
     locale: LOCALE_NS,
   }, StatsLineEnhanced)
+  const offContext = installContextEntry(ctx)
+  return () => { offContext(); offStats() }
 }
 
 /** The split takeover: one entry per official pill, each shadowed at its own
@@ -144,7 +159,8 @@ function installSplitDockEntries(ctx: Context): () => void {
     priority: -1,
     locale: LOCALE_NS,
   }, StatsUsageEntry)
-  return () => { offUsage(); offActivity() }
+  const offContext = installContextEntry(ctx)
+  return () => { offContext(); offUsage(); offActivity() }
 }
 
 export function apply(ctx: Context): void {
@@ -154,7 +170,9 @@ export function apply(ctx: Context): void {
     const offZh = ctx.locale.register(LOCALE_NS, 'zh', zh)
     const offEn = ctx.locale.register(LOCALE_NS, 'en', en)
     const offZhTw = ctx.locale.register(LOCALE_NS, 'zh-TW', zhTW)
-    return () => { offZh(); offEn(); offZhTw() }
+    const offContext = Object.entries(CONTEXT_LOCALES).map(([locale, dict]) =>
+      ctx.locale.register(CONTEXT_LOCALE_NS, locale, dict as Record<string, string>))
+    return () => { offZh(); offEn(); offZhTw(); for (const off of offContext) off() }
   }, 'dsh-token-total: dictionaries')
 
   // Join the background plugin's frosted-glass sheet when it is installed,

package/src/client/locales.ts

@@ -32,6 +32,7 @@ export type TokenTotalKey =
   | 'cachedTokens'
   | 'sessions'
   | 'requests'
+  | 'requestsFailed'
   | 'activeDays'
   | 'cacheRate'
   | 'cacheRateHint'
@@ -100,6 +101,7 @@ export const en: Record<TokenTotalKey, string> = {
   cachedTokens: 'cached',
   sessions: 'Sessions',
   requests: 'Requests',
+  requestsFailed: 'Failed',
   activeDays: 'Active days',
   cacheRate: 'Avg cache hit rate',
   cacheRateHint: 'Cached input tokens as a share of all input tokens in the range',
@@ -169,6 +171,7 @@ export const zh: Record<TokenTotalKey, string> = {
   cachedTokens: '缓存命中',
   sessions: '会话数量',
   requests: '请求数量',
+  requestsFailed: '失败',
   activeDays: '活跃天数',
   cacheRate: '缓存命中率',
   cacheRateHint: '时间段内缓存命中 token 占输入 token 的比例',
@@ -238,6 +241,7 @@ export const zhTW: Record<TokenTotalKey, string> = {
   cachedTokens: '快取命中',
   sessions: '會話數量',
   requests: '請求數量',
+  requestsFailed: '失敗',
   activeDays: '活躍天數',
   cacheRate: '快取命中率',
   cacheRateHint: '時間範圍內快取命中 token 佔輸入 token 的比例',

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

@@ -8,8 +8,7 @@ const ZERO: SessionUsageTotals = {
   cacheWriteTokens: 0,
 }
 
-/** Use the live main-agent projection when available. Never add tree.total to
- * it: that would count the main agent twice. The log is only the fallback. */
+/** Add the root and descendants once; tree.total is already that sum. */
 export function combinedTotals(tree: SessionUsageTree, self: SessionUsageTotals = tree.self): SessionUsageTotals {
   return {
     uncachedInputTokens: self.uncachedInputTokens + tree.subagents.uncachedInputTokens,
@@ -24,15 +23,12 @@ export function sessionUsageForDisplay(
   native: SessionUsageTotals | undefined,
   tree: SessionUsageTree | null,
 ): SessionUsageTree {
-  const extra = tree?.selfCompaction ?? ZERO
-  // Native tokenUsage counts message/attempt calls, but not compaction calls.
-  // tree.self already includes compaction, so add the supplement ONLY to native.
-  const self = native === undefined ? tree?.self ?? { ...ZERO } : {
-    uncachedInputTokens: native.uncachedInputTokens + extra.uncachedInputTokens,
-    outputTokens: native.outputTokens + extra.outputTokens,
-    cacheReadTokens: native.cacheReadTokens + extra.cacheReadTokens,
-    cacheWriteTokens: native.cacheWriteTokens + extra.cacheWriteTokens,
-  }
+  // The tree folds the full live/stored log, including failed attempts,
+  // retries, legacy chunks and compaction, and excludes fork-inherited usage.
+  // Native projections can omit those calls or include an inherited prefix;
+  // replacing tree.self (or taking bucket-wise maxima) would lose or double
+  // spend. Native is only the initial fallback while the tree is unavailable.
+  const self = tree?.self ?? native ?? { ...ZERO }
   const subagents = tree?.subagents ?? { ...ZERO }
   return {
     self,

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

@@ -11,7 +11,7 @@ export { billedTotal, cacheHitPercentOf, combinedTotals, hasAnyTokens } from './
 
 export interface SessionTreeReading {
   tree: SessionUsageTree | null
-  /** Log-based main + subagents. The pill substitutes the live main projection. */
+  /** Authoritative log-based main + all descendant usage after the tree loads. */
   totals: SessionUsageTotals | null
 }
 

package/src/collector.ts

@@ -219,6 +219,12 @@ export class UsageFold {
           }
         }
       }
+      // `assistant/attempt` is the host's record of a provider call that FAILED
+      // (its stream ended with an error or was cancelled before any content
+      // was committed); `assistant/message` is every call that committed.
+      // They partition the calls exactly, so the attempt event is the failure
+      // boundary — no error/retry bookkeeping needed downstream.
+      if (ev.type === 'assistant/attempt') return this.attemptSample(ev, usage)
       return usage ? this.replaceSample(ev, usage) : null
     }
     if (ev.type === 'compaction/summary') return this.compactionSample(ev)
@@ -268,6 +274,33 @@ export class UsageFold {
     return emitted
   }
 
+  /**
+   * Fold one `assistant/attempt` — a provider call that failed. Tokens follow
+   * the same last-report-wins rule as a committed message (the attempt's
+   * stream is the call's final word, so a usage chunk seen mid-stream is
+   * replaced or corrected, never added twice), but the call must ALWAYS be
+   * counted as one failure: `replaceSample` drops an all-zero first report,
+   * which is correct for the token buckets and would silently lose the
+   * failure. A failed call that reported no usage therefore contributes a
+   * zero-token failure marker instead of a null.
+   */
+  private attemptSample(ev: UsageSessionEvent, usage: UsageEventData['usage'] | undefined): UsageSample {
+    const sample = this.replaceSample(ev, usage)
+    if (sample) {
+      sample.failed = true
+      return sample
+    }
+    return {
+      day: dayKey(ev.time),
+      hour: hourKey(ev.time),
+      inputTokens: 0,
+      outputTokens: 0,
+      cacheReadTokens: 0,
+      cacheWriteTokens: 0,
+      failed: true,
+    }
+  }
+
   /**
    * Fold one `compaction/summary` — the one place a provider call's usage
    * reaches the log OUTSIDE the agent loop. The summarization call produces no
@@ -419,6 +452,9 @@ export class UsageCollector {
         // The hour table keeps its own boundary pair; write it on the same
         // tick so the two never drift apart.
         void this.store.markHoursLiveSequences(batch).catch(() => { this.status.recordFailures++ })
+        // The failure counter has its own pair as well (it was added after
+        // both token cursors were already full); same tick, same boundary.
+        void this.store.markFailuresLiveSequences(batch).catch(() => { this.status.recordFailures++ })
       }
     })
   }
@@ -593,14 +629,22 @@ export class UsageCollector {
     await this.scan(persistence, sessions, signal, 'hours')
   }
 
-  /** Shared replay engine behind {@link backfill} and {@link backfillHours}.
-   *  `target` selects the cursor pair, the write function, and the cursor
-   *  the completed sessions land in. */
+  /** The failure upgrade pass: replay every session the FAILURE cursors have
+   *  not seen, counting only failed calls. Neither the day nor the hour
+   *  cursor covers this counter (both were full when it arrived), and the
+   *  replay must not re-add tokens or requests. */
+  async backfillFailures(persistence: UsageSessionPersistence, sessions: UsageSessionStore, signal?: AbortSignal): Promise<void> {
+    await this.scan(persistence, sessions, signal, 'failures')
+  }
+
+  /** Shared replay engine behind {@link backfill}, {@link backfillHours} and
+   *  {@link backfillFailures}. `target` selects the cursor pair, the write
+   *  function, and the cursor the completed sessions land in. */
   private async scan(
     persistence: UsageSessionPersistence,
     sessions: UsageSessionStore,
     signal: AbortSignal | undefined,
-    target: 'all' | 'hours',
+    target: 'all' | 'hours' | 'failures',
   ): Promise<void> {
     if (this.status.running) return
     if (signal?.aborted) return
@@ -626,13 +670,21 @@ export class UsageCollector {
       // store already saw: the fold's replace semantics dedupe within one
       // pass only, so a full replay would double every counter. The hour
       // pass uses its own pair for the same reason.
-      const seen = target === 'hours' ? await this.store.hoursSeenSessions() : await this.store.seenSessions()
+      const seen = target === 'hours'
+        ? await this.store.hoursSeenSessions()
+        : target === 'failures'
+          ? await this.store.failuresSeenSessions()
+          : await this.store.seenSessions()
       // A pass that starts with an empty day cursor is a first install or a
       // rebuild: it writes both tables, so its completion is also the moment
       // the hour history becomes complete. An upgrade pass starts with a full
       // day cursor and must NOT claim that.
       const dayCursorWasEmpty = seen.size === 0
-      const liveSeq = target === 'hours' ? await this.store.hoursLiveSequences() : await this.store.liveSequences()
+      const liveSeq = target === 'hours'
+        ? await this.store.hoursLiveSequences()
+        : target === 'failures'
+          ? await this.store.failuresLiveSequences()
+          : await this.store.liveSequences()
       // seen alone decides target selection: a session enters
       // backfilledSessions only after its whole replayable range was cleanly
       // folded, so selecting it again would multiply that range by the boot
@@ -644,12 +696,13 @@ export class UsageCollector {
       const concurrency = this.options.backfillConcurrency ?? 4
       let next = 0
       const completed: string[] = []
-      // Each target writes and marks its own surfaces: the upgrade pass must
-      // not touch day rows (their cursors are already advanced) and must not
-      // mark day sessions seen.
+      // Each target writes and marks its own surfaces: the upgrade passes must
+      // not touch the counters their cursors already account for.
       const writeSample = target === 'hours'
         ? (sample: UsageSample): Promise<void> => this.store.recordHours(sample)
-        : (sample: UsageSample): Promise<void> => this.store.record(sample)
+        : target === 'failures'
+          ? (sample: UsageSample): Promise<void> => this.store.recordFailure(sample)
+          : (sample: UsageSample): Promise<void> => this.store.record(sample)
       const flushCompleted = async (): Promise<void> => {
         if (completed.length === 0) return
         const batch = completed.splice(0, completed.length)
@@ -657,10 +710,16 @@ export class UsageCollector {
           await this.store.markHoursSeenSessions(batch)
           return
         }
+        if (target === 'failures') {
+          await this.store.markFailuresSeenSessions(batch)
+          return
+        }
         await this.store.markSeenSessions(batch)
         // `record()` above wrote both tables, so the hour cursor advances in
         // the same batch.
         await this.store.markHoursSeenSessions(batch)
+        // ... and the failure counter was folded by the same replay.
+        await this.store.markFailuresSeenSessions(batch)
       }
       const worker = async () => {
         for (;;) {
@@ -777,15 +836,21 @@ export class UsageCollector {
       }
       await Promise.all(Array.from({ length: Math.min(concurrency, Math.max(1, targets.length)) }, worker))
       await flushCompleted()
-      // Claim the hour history only when this pass covered what it set out
-      // to cover. A first install / rebuild starts with an empty day cursor
-      // and double-writes; the upgrade pass is the hour pass itself. An
-      // aborted or erroring scan leaves the flag off, and the seen sets make
-      // the retry exact.
+      // Claim a surface only when this pass covered what it set out to cover.
+      // A pass that starts from an EMPTY cursor is a first install or a
+      // rebuild: it folds the whole history, so it completes every counter
+      // that rides the samples (the failure counter included, since `record`
+      // and `recordHours` both accumulate it). An aborted or erroring scan
+      // leaves the flags off, and the seen sets make the retry exact.
+      const clean = !signal?.aborted && this.status.error === undefined
       const hourPassCompleted = target === 'hours' || dayCursorWasEmpty
-      if (hourPassCompleted && !signal?.aborted && this.status.error === undefined) {
+      if (hourPassCompleted && clean) {
         await this.store.markHoursReady()
       }
+      const failuresPassCompleted = target === 'failures' || dayCursorWasEmpty
+      if (failuresPassCompleted && clean) {
+        await this.store.markFailuresReady()
+      }
     } finally {
       this.status.running = false
     }

package/src/index.ts

@@ -212,6 +212,34 @@ export function apply(ctx: Context, config: TokenTotalConfig = {}): void {
     await collector.backfillHours(ctx.sessionPersistence, ctx.sessions, controller.signal)
   }
 
+  // The failure counter arrived after BOTH token cursors were populated, so
+  // an existing store needs one more replay to recover historic failures.
+  // Same shape as the hour upgrade: only after the hour pass settled cleanly
+  // (a fresh install's passes already folded failures and set the flag, so
+  // this returns immediately), and with a live boundary for open sessions.
+  const ensureFailureHistory = async (): Promise<void> => {
+    await store.readyPromise()
+    if (await store.failuresReady()) return
+    if (!(await store.hasAnyDayRows())) return
+    if (collector.status.error !== undefined) return
+    const previous = await store.failuresLiveSequences()
+    const boundaries = new Map<string, number>()
+    for (const handle of ctx.sessions.list()) {
+      const seq = handle.seq
+      if (typeof seq === 'number' && Number.isFinite(seq) && seq >= 0) {
+        boundaries.set(handle.id, seq)
+        continue
+      }
+      const old = previous.get(handle.id)
+      boundaries.set(handle.id, typeof old === 'number' ? old : -1)
+    }
+    await store.markFailuresLiveSequences(boundaries)
+    scanController?.abort()
+    const controller = new AbortController()
+    scanController = controller
+    await collector.backfillFailures(ctx.sessionPersistence, ctx.sessions, controller.signal)
+  }
+
   ctx.effect(() => {
     collector.start()
     // Keep the per-session tree cache honest: every committed event of any
@@ -226,6 +254,7 @@ export function apply(ctx: Context, config: TokenTotalConfig = {}): void {
     void (async () => {
       await rescan()
       await ensureHourHistory()
+      await ensureFailureHistory()
     })()
     return () => {
       scanController?.abort()

package/src/query.ts

@@ -51,6 +51,14 @@ export interface UsageSample {
   cacheWriteTokens: number
   turn?: boolean // true for a completed-turn marker
   request?: boolean // true when this sample also counts one provider call
+  /** True when this sample also counts one FAILED provider call. The host
+   *  appends `assistant/attempt` (instead of `assistant/message`) when a
+   *  call's stream ends with an error or is cancelled before any content is
+   *  committed, so that event is the exact boundary of a failed call. The
+   *  marker is ORTHOGONAL to `request` and to the buckets: a failed call was
+   *  still opened by its own `step/start` (so it is already one request) and
+   *  a stream that died mid-flight may still report usage. */
+  failed?: boolean
 }
 
 export interface RangeFilter {
@@ -105,6 +113,7 @@ export function aggregateSamples(
     outputTokens: 0,
     cacheTokens: 0,
     requests: 0,
+    failures: 0,
     turns: 0,
     cacheHit: 0,
     cacheMiss: 0,
@@ -137,6 +146,7 @@ export function aggregateSamples(
   const bucketByProvider = new Map<string, Map<string, number>>()
   const bucketTotals = new Map<string, number>()
   const bucketRequests = new Map<string, number>()
+  const bucketFailures = new Map<string, number>()
   const bucketTurns = new Map<string, number>()
   const bucketCacheHit = new Map<string, number>()
   const bucketCacheMiss = new Map<string, number>()
@@ -153,18 +163,22 @@ export function aggregateSamples(
     // provider billed for this call — uncached input, output, cache reads
     // and writes. The hit/miss rate denominators below stay input-side only.
     const total = sample.inputTokens + sample.outputTokens + sample.cacheReadTokens + sample.cacheWriteTokens
+    // UsageFold emits signed bucket corrections. Even a net-zero correction
+    // can move prompt tokens between cache hit and miss, so only all-zero
+    // buckets are a marker with no token accounting.
+    const hasTokenDelta = sample.inputTokens !== 0 || sample.outputTokens !== 0
+      || sample.cacheReadTokens !== 0 || sample.cacheWriteTokens !== 0
+    if (sample.failed) {
+      out.failures++
+      bucketFailures.set(bucket, (bucketFailures.get(bucket) ?? 0) + 1)
+    }
     if (sample.request) {
-      // One provider call, whether or not it produced tokens — reasonix counts
-      // failed calls too. A marker with no buckets is a request and nothing
-      // else: it must not create a model row, mark its day active, or open an
-      // empty daily bucket. A marker that DOES carry buckets
-      // (`compaction/summary` states the call and its usage in one sample) is
-      // counted here and again through the token accounting below — the two
-      // count different things, so neither doubles the other.
       out.requests++
       bucketRequests.set(bucket, (bucketRequests.get(bucket) ?? 0) + 1)
-      if (total <= 0) continue
     }
+    // Pure markers must not create a model row or an active day. A marker
+    // carrying a correction still updates every billing/cache bucket below.
+    if (!hasTokenDelta) continue
     out.tokens += total
     out.inputTokens += sample.inputTokens
     out.outputTokens += sample.outputTokens
@@ -240,6 +254,7 @@ export function aggregateSamples(
       byModel: byModelObj,
       byProvider: byProviderObj,
       requests: bucketRequests.get(bucket) ?? 0,
+      failures: bucketFailures.get(bucket) ?? 0,
       turns: bucketTurns.get(bucket) ?? 0,
       cacheHit: bucketCacheHit.get(bucket) ?? 0,
       cacheMiss: bucketCacheMiss.get(bucket) ?? 0,