dsh-token-total 1.0.0 → 1.0.2

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

@@ -0,0 +1,54 @@
+/** Pure billing helpers shared by the session-tree hook and composer pills. */
+import type { SessionUsageTotals, SessionUsageTree } from '../wire.ts'
+
+const ZERO: SessionUsageTotals = {
+  uncachedInputTokens: 0,
+  outputTokens: 0,
+  cacheReadTokens: 0,
+  cacheWriteTokens: 0,
+}
+
+/** 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,
+    outputTokens: self.outputTokens + tree.subagents.outputTokens,
+    cacheReadTokens: self.cacheReadTokens + tree.subagents.cacheReadTokens,
+    cacheWriteTokens: self.cacheWriteTokens + tree.subagents.cacheWriteTokens,
+  }
+}
+
+/** One consistent split for the pill, cache hit rate and every dialog row. */
+export function sessionUsageForDisplay(
+  native: SessionUsageTotals | undefined,
+  tree: SessionUsageTree | null,
+): SessionUsageTree {
+  // 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,
+    subagents,
+    total: tree === null ? self : combinedTotals(tree, self),
+    subagentSessions: tree?.subagentSessions ?? 0,
+  }
+}
+
+export function hasAnyTokens(totals: SessionUsageTotals | undefined): boolean {
+  return totals !== undefined && billedTotal(totals) > 0
+}
+
+export function billedTotal(totals: SessionUsageTotals): number {
+  return totals.uncachedInputTokens + totals.cacheReadTokens
+    + totals.cacheWriteTokens + totals.outputTokens
+}
+
+export function cacheHitPercentOf(totals: SessionUsageTotals): number | null {
+  const hit = totals.cacheReadTokens
+  const miss = totals.uncachedInputTokens + totals.cacheWriteTokens
+  return hit + miss === 0 ? null : (hit / (hit + miss)) * 100
+}

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

@@ -1,115 +1,62 @@
-/**
- * The composer row's window onto the WHOLE session tree.
- *
- * dsh's native `tokenUsage` projection is the main agent of the current
- * session only: a session that delegates to subagents (each subagent is its
- * own persisted session, linked by `header.parentSession`) shows a fraction of
- * what it actually spent, and nothing in the shipped UI shows the rest. The
- * host half answers that question over `/token-total/api/session`, replaying
- * the root log plus every descendant's log; this hook is the browser end.
- *
- * Refresh policy: the request is cheap on the host (its tree cache is
- * invalidated by live events), and the native usage figure moves exactly when
- * a call settles — so a change in the native signature is the trigger to
- * re-ask. There is no timer: an idle session costs nothing.
- *
- * Failure policy: the pill must never break the composer, so a failed request
- * keeps the last good answer and simply does not retry until the next trigger.
- */
+/** The composer row's window onto the whole session tree. The native usage
+ * projection only moves for main-agent calls, so poll the displayed session
+ * even before its first child appears. Requests are serialized and late answers
+ * from a previous session are discarded. Failures keep the last good reading. */
 import { useEffect, useRef, useState } from 'react'
 import { fetchSessionUsage } from './api.ts'
+import { combinedTotals } from './session-usage-core.ts'
 import type { SessionUsageTotals, SessionUsageTree } from '../wire.ts'
 
-const ZERO: SessionUsageTotals = {
-  uncachedInputTokens: 0,
-  outputTokens: 0,
-  cacheReadTokens: 0,
-  cacheWriteTokens: 0,
-}
-
-function add(into: SessionUsageTotals, from: SessionUsageTotals): SessionUsageTotals {
-  return {
-    uncachedInputTokens: into.uncachedInputTokens + from.uncachedInputTokens,
-    outputTokens: into.outputTokens + from.outputTokens,
-    cacheReadTokens: into.cacheReadTokens + from.cacheReadTokens,
-    cacheWriteTokens: into.cacheWriteTokens + from.cacheWriteTokens,
-  }
-}
-
-/** Fold a tree into the flat shape the pill's dialog renders. */
-export function combinedTotals(tree: SessionUsageTree): SessionUsageTotals {
-  return add(tree.self, tree.subagents)
-}
-
-/** Whether a totals record carries any billable token at all. */
-export function hasAnyTokens(totals: SessionUsageTotals | undefined): boolean {
-  if (totals === undefined) return false
-  return totals.uncachedInputTokens + totals.outputTokens
-    + totals.cacheReadTokens + totals.cacheWriteTokens > 0
-}
-
-/** Total billed tokens of a flat totals record (prompt side + completion). */
-export function billedTotal(totals: SessionUsageTotals): number {
-  return totals.uncachedInputTokens + totals.cacheReadTokens
-    + totals.cacheWriteTokens + totals.outputTokens
-}
-
-/** Cache hit rate over the prompt side, or null when nothing was prompted. */
-export function cacheHitPercentOf(totals: SessionUsageTotals): number | null {
-  const hit = totals.cacheReadTokens
-  const miss = totals.uncachedInputTokens + totals.cacheWriteTokens
-  if (hit + miss === 0) return null
-  return (hit / (hit + miss)) * 100
-}
+export { billedTotal, cacheHitPercentOf, combinedTotals, hasAnyTokens } from './session-usage-core.ts'
 
 export interface SessionTreeReading {
   tree: SessionUsageTree | null
-  /** main + subagents, or null before the first successful answer. */
+  /** Authoritative log-based main + all descendant usage after the tree loads. */
   totals: SessionUsageTotals | null
 }
 
-/** How often a session that HAS subagents re-asks. The native figure only moves
- *  when the main agent's own call settles, so without this a subagent still
- *  working (or one that just finished) would not update the pill. A session
- *  with no subagents never polls: nothing exists to miss. */
-const SUBAGENT_POLL_MS = 4_000
+const SESSION_POLL_MS = 4_000
 
-/**
- * Subscribe to one session's whole-tree usage.
- *
- * `signature` is any string that changes when the native usage figure moves;
- * passing it in keeps this hook out of the projection seat and lets the caller
- * decide what "a new call settled" means for its own pill. A session that turns
- * out to have subagents additionally re-asks on a slow beat, because subagent
- * spend lands in a different session log and no native figure moves for it.
- */
 export function useSessionUsage(sessionId: string | undefined, signature: string): SessionTreeReading {
-  const [tree, setTree] = useState<SessionUsageTree | null>(null)
-  const latest = useRef<string>('')
-  const [beat, setBeat] = useState(0)
-  const hasSubagents = (tree?.subagentSessions ?? 0) > 0
-  useEffect(() => {
-    if (!hasSubagents) return
-    const handle = setInterval(() => { setBeat(Date.now()) }, SUBAGENT_POLL_MS)
-    return () => { clearInterval(handle) }
-  }, [hasSubagents])
+  const [reading, setReading] = useState<{ sessionId: string; tree: SessionUsageTree } | null>(null)
+  const refresh = useRef<(() => void) | null>(null)
   useEffect(() => {
     if (typeof sessionId !== 'string' || sessionId === '') return
-    const key = `${sessionId}|${signature}|${beat}`
-    if (latest.current === key) return
-    latest.current = key
-    let cancelled = false
-    void fetchSessionUsage(sessionId).then((value) => {
-      if (cancelled) return
-      setTree(value)
-    }).catch(() => {
-      // Keep the previous reading; the next trigger retries.
-      latest.current = ''
-    })
+    let active = true
+    let pending = false
+    let again = false
+    const request = (): void => {
+      if (!active) return
+      if (pending) {
+        again = true
+        return
+      }
+      pending = true
+      void fetchSessionUsage(sessionId).then((tree) => {
+        if (active) setReading({ sessionId, tree })
+      }).catch(() => {
+        // Retry on the next beat/signature; do not replace good data with zero.
+      }).finally(() => {
+        pending = false
+        if (active && again) {
+          again = false
+          request()
+        }
+      })
+    }
+    refresh.current = request
+    const handle = setInterval(request, SESSION_POLL_MS)
     return () => {
-      cancelled = true
+      active = false
+      refresh.current = null
+      clearInterval(handle)
     }
-  }, [sessionId, signature, beat])
-  const totals = tree === null ? null : combinedTotals(tree)
-  return { tree, totals }
+  }, [sessionId])
+  useEffect(() => {
+    refresh.current?.()
+  }, [sessionId, signature])
+  // Key the answer on its session, not just effect cleanup: the very first
+  // render after switching must not show the previous session's descendants.
+  const tree = reading !== null && reading.sessionId === sessionId ? reading.tree : null
+  return { tree, totals: tree === null ? null : combinedTotals(tree) }
 }

package/src/collector.ts

@@ -3,10 +3,10 @@
  * Two sources feed the same fold:
  *
  * - live: `session/event` subscription — every committed session event
- *   reaches this plugin after the fact. `assistant/message` carries the
- *   step's final `usage` (TokenUsage); `assistant/chunk` carries an early
- *   `usage` sample from the streaming adapter; `request/context` carries the
- *   provider/model route. A completed call's usage is attributed to the model
+ *   reaches this plugin after the fact. Assistant messages expose final usage,
+ *   and modern message/attempt streams retain raw usage even on failed calls.
+ *   Legacy `assistant/chunk` reports an early sample; `request/context` carries
+ *   the provider/model route. A completed call's usage is attributed to the model
  *   the request used — in priority order: the message's own `source`
  *   (authoritative per call), then the session's last-known route, which
  *   comes from observed `request/context` events OR is lazily seeded from
@@ -27,11 +27,10 @@
  *   >= 0.1.2-rc.1, 0 for a non-forked session), and the replay skips it —
  *   the parent's own backfill already counted those events.
  *
- * Idempotence: within ONE session, the same (turn, step) may report usage
- * more than once (a streaming sample then the final assistant/message;
- * compaction replays). The fold emits each (turn, step) key exactly once and
- * keeps the newest values in its own state — see the replaceSample note for
- * why the store observably keeps the FIRST emission. Cross-session
+ * Idempotence: within ONE session, repeated reports for the same (turn, step)
+ * emit only signed bucket corrections: the accumulated usage is last-wins.
+ * A started retry closes that replacement slot because its predecessor was a
+ * separately billed attempt. Cross-session
  * (turn, step) collisions are NOT deduped: two sessions both own a turn 1 /
  * step 1, and each must count. The store's per-day rows accumulate, so
  * re-folding the same log must not add twice: live events are only folded
@@ -51,6 +50,8 @@ interface UsageEventData {
   turn?: number
   step?: number
   usage?: { inputTokens: number; outputTokens: number; cacheReadTokens?: number; cacheWriteTokens?: number; reasoningTokens?: number }
+  /** v2+ durable Assistant stream: usage is a raw (never packed) chunk. */
+  stream?: readonly { type?: string; chunk?: { type?: string; usage?: UsageEventData['usage'] } }[]
 }
 
 /** The assistant/message payload. */
@@ -170,6 +171,11 @@ export class UsageFold {
       // reasonix emits TurnDone regardless of the run's error.
       return { day: dayKey(ev.time), hour: hourKey(ev.time), inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, turn: true }
     }
+    if (ev.type === 'llm/retry-started') {
+      // A retry is a separate billed attempt even though it shares turn/step.
+      const key = this.keyOf(ev)
+      if (key !== null) this.seen.delete(key)
+    }
     if (ev.type === 'step/start' || ev.type === 'llm/retry-started') {
       // Attribution note: agent-loop appends step/start BEFORE request/context
       // (core/agent-loop agent.ts), so the FIRST request marker of a fresh —
@@ -194,17 +200,32 @@ export class UsageFold {
         request: true,
       }
     }
-    // `assistant/chunk` only exists on DSH <= 0.1.2 (streaming usage sample);
-    // 0.1.3+ logs attempts as `assistant/attempt` (no usage) and the final
-    // `assistant/message` stays authoritative. Kept as a dead branch for rc.1.
+    // Legacy streaming event. Modern hosts commit the complete stream on an
+    // assistant/message OR assistant/attempt, including failed/aborted calls.
     if (ev.type === 'assistant/chunk') {
       const data = ev.data as AssistantChunkData
       const usage = data.chunk?.type === 'usage' ? data.chunk.usage : undefined
       return usage ? this.replaceSample(ev, usage) : null
     }
-    if (ev.type === 'assistant/message') {
+    if (ev.type === 'assistant/message' || ev.type === 'assistant/attempt') {
       const data = ev.data as AssistantMessageData
-      return data.usage ? this.replaceSample(ev, data.usage) : null
+      let usage = ev.type === 'assistant/message' ? data.usage : undefined
+      if (usage === undefined && Array.isArray(data.stream)) {
+        for (let i = data.stream.length - 1; i >= 0; i--) {
+          const record = data.stream[i]
+          if (record?.type === 'chunk' && record.chunk?.type === 'usage') {
+            usage = record.chunk.usage
+            break
+          }
+        }
+      }
+      // `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)
     return null
@@ -213,53 +234,71 @@ export class UsageFold {
   private replaceSample(ev: UsageSessionEvent, usage: UsageEventData['usage']): UsageSample | null {
     const usage2 = usage
     if (!usage2) return null
-    // A sample with nothing at all is noise; a pure-cache call (zero
-    // uncached input AND zero output but real cache traffic) still counts —
-    // its cacheRead/cacheWrite buckets are real provider-reported tokens.
-    if (
-      (usage2.inputTokens ?? 0)
-      + (usage2.outputTokens ?? 0)
-      + (usage2.cacheReadTokens ?? 0)
-      + (usage2.cacheWriteTokens ?? 0)
-      <= 0
-    ) {
-      return null
-    }
     const key = this.keyOf(ev)
     const sample: UsageSample = {
       day: dayKey(ev.time),
       hour: hourKey(ev.time),
-      inputTokens: usage2.inputTokens,
-      outputTokens: usage2.outputTokens,
+      inputTokens: usage2.inputTokens ?? 0,
+      outputTokens: usage2.outputTokens ?? 0,
       cacheReadTokens: usage2.cacheReadTokens ?? 0,
       cacheWriteTokens: usage2.cacheWriteTokens ?? 0,
     }
-    if (key === null) {
-      // No (turn, step) marker: every emission counts (no dedupe slot). The
-      // shipped adapters always stamp both on usage events, so this path is
-      // a defensive tail, not a live double-count source. ponytail: a
-      // synthetic key (e.g. by time+usage hash) could dedupe it if an
-      // adapter ever reports usage without turn/step.
-      return sample
-    }
-    const prev = this.seen.get(key)
-    // Track the newest report internally either way; the fold must NEVER
-    // mutate an object the store already received.
+    const prev = key === null ? undefined : this.seen.get(key)
+    // A first all-zero report carries no traffic. A later zero report may
+    // replace a nonzero sample, so it must emit a negative correction.
+    if (!prev && sample.inputTokens + sample.outputTokens + sample.cacheReadTokens + sample.cacheWriteTokens <= 0) return null
+    if (key === null) return sample
     this.seen.set(key, sample)
     if (prev) {
-      // Duplicate report for a known (turn, step): swallow it. The shipped
-      // adapters emit the identical TokenUsage on the streaming chunk and
-      // the final message (llm-deepseek yields one `pendingUsage` at DONE;
-      // llm-pi-ai only on done/error), so first == last observationally.
-      // ponytail: true last-wins would need store-side delta corrections
-      // keyed by (session, turn, step); add them only if an adapter ever
-      // reports differing values for one call.
-      return null
+      const correction: UsageSample = {
+        day: prev.day,
+        hour: prev.hour,
+        model: prev.model,
+        inputTokens: sample.inputTokens - prev.inputTokens,
+        outputTokens: sample.outputTokens - prev.outputTokens,
+        cacheReadTokens: sample.cacheReadTokens - prev.cacheReadTokens,
+        cacheWriteTokens: sample.cacheWriteTokens - prev.cacheWriteTokens,
+      }
+      // Keep the original bucket identity across cumulative samples.
+      sample.day = prev.day
+      sample.hour = prev.hour
+      sample.model = prev.model
+      if (correction.inputTokens === 0 && correction.outputTokens === 0 && correction.cacheReadTokens === 0 && correction.cacheWriteTokens === 0) return null
+      return correction
+    }
+    // The collector fills in model attribution on this returned copy. Retain
+    // the same identity privately for any correction, without ever mutating
+    // a sample already handed to the store.
+    const emitted = { ...sample }
+    this.seen.set(key, emitted)
+    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,
     }
-    // First emission: hand the store its own copy. The internal object stays
-    // fold-owned — mutating it on a later duplicate would rewrite the sample
-    // already sitting in the store's write path through the shared reference.
-    return { ...sample }
   }
 
   /**
@@ -413,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++ })
       }
     })
   }
@@ -587,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
@@ -620,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
@@ -638,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)
@@ -651,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 (;;) {
@@ -771,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
     }