dsh-all-usage 1.1.18 → 1.2.1

package/lib/session-sync.js

@@ -1,841 +1,976 @@
-import { RETIRED_WORKSPACE_ID, retargetLedgerRecord } from './ledger.js'
-import { contextTimeKey, extractUsageEvent, pickPricingTime, touchContextTimes, workspacePathKey } from './usage-core.js'
-
-const RECONCILE_INTERVAL_MS = 120000
-const RECONCILE_HINT_DELAY_MS = 3000
-const WORKSPACE_SYNC_DEBOUNCE_MS = 300
-// The registry event is a fast path, not a guarantee: a change that lands while a
-// baseline runs used to be dropped outright, and a missed event left the plugin
-// stale until the next restart. The (in-memory) registry list is polled as well.
-const WORKSPACE_PROBE_INTERVAL_MS = 30000
-
-export function createSessionSync(host) {
-  const { ctx, state } = host
-  const { sessionPersistence } = host.services
-  const {
-    validEventTime,
-    identityFromRoute,
-    identityFromMessage,
-    coerceIdentity,
-    addTurn,
-    addUsage,
-    resetAggregationState,
-  } = host.aggregation
-  const { beginSync, noteSyncError, markStatsChanged } = host
-  const {
-    sessionEvents,
-    buildLedgerRecord,
-    applyLedgerRecord,
-    storeLedgerRecord,
-    replaceLedgerRecord,
-    persistLedgerRecord,
-    drainLedgerWrites,
-  } = host.ledger
-  const backfillUnpricedCosts = (...args) => host.pricing.backfillUnpricedCosts(...args)
-  const reconcileTemporalPricing = (...args) => host.pricing.reconcileTemporalPricing(...args)
-  const safeContextTimeout = async (ms) => {
-    if (state.disposed) return false
-    try {
-      await ctx.timeout(ms)
-      return !state.disposed
-    } catch (err) {
-      if (!state.disposed) console.error('[all-usage] context timer unavailable:', err)
-      return false
-    }
-  }
-
-  function foldEvent(wsId, time, type, data, sid, seq, materialization = 'live') {
-    if ((type === 'turn/end' || type === 'assistant/message' || type === 'assistant/chunk') && !validEventTime(time)) return
-    if (type === 'request/context') {
-      state.sessionModel.set(sid, identityFromRoute(data, state.sessionModel.get(sid)))
-      if (validEventTime(time)) {
-        let times = state.sessionContextTimes.get(sid)
-        if (times === undefined) { times = new Map(); state.sessionContextTimes.set(sid, times) }
-        touchContextTimes(times, contextTimeKey(data && data.turn, data && data.step), time)
-      }
-    } else if (type === 'request/header') {
-      state.sessionModel.set(sid, identityFromRoute(data, state.sessionModel.get(sid)))
-    } else if (type === 'turn/end') {
-      addTurn(wsId, time, sid, data && typeof data.turn === 'number' ? data.turn : null, state.sessionModel.get(sid), materialization, seq)
-    } else if (type === 'assistant/message' || type === 'assistant/chunk') {
-      const usageEvent = extractUsageEvent({ type, time, data, seq })
-      if (usageEvent === null) return
-      const identity = usageEvent.kind === 'message' ? identityFromMessage(data, state.sessionModel.get(sid)) : coerceIdentity(state.sessionModel.get(sid))
-      state.sessionModel.set(sid, identity)
-      const pricing = pickPricingTime(state.sessionContextTimes.get(sid), time, usageEvent.turn, usageEvent.step)
-      addUsage(wsId, time, usageEvent.usage, identity, sid, data, seq, materialization, pricing.time, pricing.source)
-    }
-  }
-  function foldEvents(wsId, events, fromSeq, sid, materialization = 'scan') {
-    // Full folds keep their callers responsible for atomicity: runBaseline and
-    // syncLiveSession remove the session's old usage/turn/context/identity
-    // first when the snapshot is authoritative (see rebuildSession below), so
-    // usage deleted by a history rewrite disappears from the aggregate.
-    for (const ev of events) {
-      if (fromSeq !== undefined) {
-        const s = typeof ev.seq === 'number' ? ev.seq : -1
-        if (s <= fromSeq) continue
-      }
-      if (ev.type === 'turn/end' || ev.type === 'assistant/message' || ev.type === 'assistant/chunk' || ev.type === 'request/context' || ev.type === 'request/header') foldEvent(wsId, ev.time, ev.type, ev.data, sid, ev.seq, materialization)
-    }
-  }
-  function lastSeqOf(events) {
-    let last = -1
-    for (const ev of events) {
-      const s = Number.isSafeInteger(ev.seq) ? ev.seq : -1
-      if (s > last) last = s
-    }
-    return last
-  }
-  function sequenceProfile(events) {
-    let previous = -1
-    let last = -1
-    let nonMonotonic = false
-    let hasInvalid = false
-    for (const ev of events) {
-      const seq = ev && Number.isSafeInteger(ev.seq) && ev.seq >= 0 ? ev.seq : -1
-      if (seq < 0) { hasInvalid = true; continue }
-      if (seq <= previous) nonMonotonic = true
-      previous = seq
-      if (seq > last) last = seq
-    }
-    return { lastSeq: last, nonMonotonic, hasInvalid }
-  }
-  function enqueue(sid, task) {
-    const prev = state.chains.get(sid) || Promise.resolve()
-    const next = prev.then(() => task(), () => task())
-    state.chains.set(sid, next)
-    const cleanup = () => { if (state.chains.get(sid) === next) state.chains.delete(sid) }
-    void next.then(cleanup, cleanup)
-    return next
-  }
-  function markLedgerDirty(sid) {
-    if (typeof sid !== 'string' || sid === '') return
-    state.ledgerDirtySessions.add(sid)
-    state.ledgerDirtyEpochs.set(sid, (state.ledgerDirtyEpochs.get(sid) || 0) + 1)
-  }
-  function buildWorkspaceSnapshot(workspaces) {
-    const wsMeta = new Map()
-    const pathIndex = new Map()
-    const memberOf = new Map()
-    for (const w of workspaces) {
-      const id = w && w.id
-      const path = w && typeof w.path === 'string' ? w.path : ''
-      const title = w && typeof w.title === 'string' ? w.title : ''
-      if (id === undefined) continue
-      wsMeta.set(id, { id, title, path })
-      if (path !== '') pathIndex.set(workspacePathKey(path), id)
-      if (w && Array.isArray(w.sessionIds)) {
-        for (const sid of w.sessionIds) memberOf.set(sid, id)
-      }
-    }
-    return { wsMeta, pathIndex, memberOf }
-  }
-  function installWorkspaceSnapshot(next) {
-    let metadataChanged = state.wsMeta.size !== next.wsMeta.size || state.pathIndex.size !== next.pathIndex.size || state.memberOf.size !== next.memberOf.size
-    if (!metadataChanged) {
-      for (const [id, value] of next.wsMeta) {
-        const previous = state.wsMeta.get(id)
-        if (previous === undefined || previous.title !== value.title || previous.path !== value.path) { metadataChanged = true; break }
-      }
-    }
-    if (!metadataChanged) {
-      for (const [path, id] of next.pathIndex) if (state.pathIndex.get(path) !== id) { metadataChanged = true; break }
-    }
-    if (!metadataChanged) {
-      for (const [sid, id] of next.memberOf) if (state.memberOf.get(sid) !== id) { metadataChanged = true; break }
-    }
-    state.wsMeta.clear()
-    state.pathIndex.clear()
-    state.memberOf.clear()
-    for (const [id, value] of next.wsMeta) state.wsMeta.set(id, value)
-    for (const [path, id] of next.pathIndex) state.pathIndex.set(path, id)
-    for (const [sid, id] of next.memberOf) state.memberOf.set(sid, id)
-    if (metadataChanged) markStatsChanged('metadata')
-    return metadataChanged
-  }
-  function workspaceForCwd(cwd) {
-    if (typeof cwd !== 'string' || cwd === '') return undefined
-    return state.pathIndex.get(workspacePathKey(cwd))
-  }
-  // DSH 0.1.5 replaced \`sessionPersistence.listSnapshots()\` with \`list()\`; both
-  // return per-session \`{ header, revision }\` rows. Without a revision the
-  // ledger-reuse fast path never fires, so every baseline re-reads every log.
-  async function loadSessionRevisions() {
-    const source = sessionPersistence
-    if (source === undefined || source === null) return null
-    const read = typeof source.list === 'function'
-      ? () => source.list()
-      : (typeof source.listSnapshots === 'function' ? () => source.listSnapshots() : null)
-    if (read === null) return null
-    const rows = await read()
-    if (!Array.isArray(rows)) return null
-    const revisions = new Map()
-    for (const row of rows) {
-      const rid = row && row.header && typeof row.header.id === 'string' ? row.header.id : undefined
-      if (rid !== undefined && row && typeof row.revision === 'string') revisions.set(rid, row.revision)
-    }
-    return revisions
-  }
-  function wsForLiveSession(session, sid) {
-    let wsId = state.memberOf.get(sid)
-    if (wsId !== undefined) return wsId
-    const header = session && session.header
-    const cwd = header && typeof header.cwd === 'string' ? header.cwd : ''
-    wsId = workspaceForCwd(cwd)
-    if (wsId !== undefined) state.memberOf.set(sid, wsId)
-    return wsId
-  }
-  function cancelLiveResync(sid) {
-    const timer = state.liveResyncTimers.get(sid)
-    if (timer !== undefined) {
-      clearTimeout(timer)
-      state.liveResyncTimers.delete(sid)
-    }
-    state.liveResyncAttempts.delete(sid)
-    state.liveResyncPending.delete(sid)
-  }
-  function scheduleLiveResync(sid, wsId, generation) {
-    if (state.disposed || generation !== state.aggregationGeneration || !state.liveResyncPending.has(sid) || state.liveResyncTimers.has(sid)) return
-    const attempt = state.liveResyncAttempts.get(sid) || 0
-    const delay = Math.min(30000, 1000 * Math.pow(2, Math.min(attempt, 5)))
-    const timer = setTimeout(() => {
-      state.liveResyncTimers.delete(sid)
-      if (state.disposed || generation !== state.aggregationGeneration || !state.liveResyncPending.has(sid)) return
-      void enqueue(sid, () => resyncLiveSession(sid, wsId, generation))
-    }, delay)
-    state.liveResyncTimers.set(sid, timer)
-    if (timer && typeof timer.unref === 'function') timer.unref()
-  }
-  function foldLiveFallback(sid, wsId, event) {
-    if (event === null || event === undefined) return
-    const seq = Number.isSafeInteger(event.seq) && event.seq >= 0 ? event.seq : -1
-    foldEvent(wsId, event.time, event.type, event.data, sid, seq, 'live')
-    if (seq >= 0) {
-      const current = state.sessionSeq.get(sid)
-      if (current === undefined || seq > current) state.sessionSeq.set(sid, seq)
-    }
-    state.sessionCount.add(sid)
-  }
-  async function syncLiveSession(sid, wsId, event, generation) {
-    try {
-      const snap = await ctx.sessionQuery.readSession(sid)
-      if (state.disposed || generation !== state.aggregationGeneration) return true
-      if (snap && Array.isArray(snap.events)) {
-        const snapshotLast = lastSeqOf(snap.events)
-        const snapshotProfile = sequenceProfile(snap.events)
-        const eventSeq = event === null || event === undefined ? -1 : (Number.isSafeInteger(event.seq) && event.seq >= 0 ? event.seq : -1)
-        // The snapshot may replace the session only when it is provably
-        // complete AND it already contains the triggering event: a timer / full
-        // resync (no event), or an explicitly contained, monotonic event
-        // stream. A snapshot that merely has a higher tail than the event is
-        // NOT proof — the event could be a live append the snapshot missed (or
-        // the snapshot could have been rewritten without it), so the event is
-        // upserted and the session stays pending for a follow-up alignment.
-        // Events without a usable seq never trigger a destructive replacement.
-        const containsEvent = event !== null && event !== undefined && eventSeq >= 0 && snap.events.some((candidate) => candidate && Number.isSafeInteger(candidate.seq) && candidate.seq === eventSeq)
-        const authoritative = event === null || event === undefined ? true : eventSeq < 0 ? false : containsEvent && !snapshotProfile.nonMonotonic && !snapshotProfile.hasInvalid
-        if (authoritative) {
-          host.aggregation.removeSession(sid)
-          // The authoritative snapshot is the new truth for both the in-memory
-          // aggregate and the durable ledger: rebuild the record from scratch
-          // and persist it, so a restart after a live history rewrite cannot
-          // resurrect usage that the snapshot deleted.
-          const rebuiltRecord = buildLedgerRecord({ id: sid, events: snap.events }, wsId, 'scan', undefined, null, true)
-          if (rebuiltRecord !== null) {
-            const canonical = replaceLedgerRecord(rebuiltRecord)
-            if (canonical === rebuiltRecord) {
-              void persistLedgerRecord(rebuiltRecord).then(() => {
-                if (state.ledgerWriteFailedSessions && state.ledgerWriteFailedSessions.has(sid)) {
-                  console.error('[all-usage] authoritative resync ledger persist failed; session stays dirty:', sid)
-                  noteSyncError('resync-ledger-persist-failed')
-                }
-              })
-            }
-          }
-        }
-        foldEvents(wsId, snap.events, undefined, sid, 'live')
-        let nextLast = snapshotLast
-        const needsFollowup = !authoritative && event !== null && event !== undefined
-        if (needsFollowup) {
-          foldLiveFallback(sid, wsId, event)
-          const current = state.sessionSeq.get(sid)
-          nextLast = Math.max(nextLast, current === undefined ? -1 : current)
-        }
-        state.sessionSeq.set(sid, nextLast)
-        state.sessionCount.add(sid)
-        if (needsFollowup) {
-          // The snapshot is behind: keep the pending flag so the follow-up
-          // resync realigns the cursor once the missing history arrives.
-          scheduleLiveResync(sid, wsId, generation)
-        } else {
-          state.liveResyncPending.delete(sid)
-          cancelLiveResync(sid)
-        }
-        return true
-      }
-    } catch (err) {
-      // Keep the event as a fallback and retry a complete session state.sync later.
-    }
-    return false
-  }
-  async function resyncLiveSession(sid, wsId, generation) {
-    if (state.disposed || generation !== state.aggregationGeneration || !state.liveResyncPending.has(sid)) return
-    if (await syncLiveSession(sid, wsId, null, generation)) return
-    state.liveResyncAttempts.set(sid, (state.liveResyncAttempts.get(sid) || 0) + 1)
-    scheduleLiveResync(sid, wsId, generation)
-  }
-  async function processLiveEvent(sid, wsId, event, generation = state.aggregationGeneration) {
-    if (state.disposed || generation !== state.aggregationGeneration) return
-    const seq = Number.isSafeInteger(event.seq) ? event.seq : -1
-    const last = state.sessionSeq.get(sid)
-    const needsSync = last === undefined || state.liveResyncPending.has(sid) || (seq >= 0 && seq > last + 1)
-    if (needsSync) {
-      state.liveResyncPending.add(sid)
-      if (await syncLiveSession(sid, wsId, event, generation)) return
-      foldLiveFallback(sid, wsId, event)
-      state.liveResyncAttempts.set(sid, (state.liveResyncAttempts.get(sid) || 0) + 1)
-      scheduleLiveResync(sid, wsId, generation)
-      return
-    }
-    if (seq < 0) {
-      foldLiveFallback(sid, wsId, event)
-      return
-    }
-    if (seq <= last) return
-    foldLiveFallback(sid, wsId, event)
-  }
-
-  // ---------- durable usage ledger ----------
-  function scheduleNativeBaselineRetry(generation, delay) {
-    if (state.disposed || state.baselineFallbackTimer !== null) return
-    state.baselineFallbackTimer = setTimeout(() => {
-      state.baselineFallbackTimer = null
-      if (!state.disposed && generation === state.aggregationGeneration && !state.scan.started && !state.scan.done) void runBaseline(generation)
-    }, delay)
-    if (state.baselineFallbackTimer && typeof state.baselineFallbackTimer.unref === 'function') state.baselineFallbackTimer.unref()
-  }
-  function scheduleBaselineRetry(generation = state.aggregationGeneration) {
-    if (state.disposed || state.baselineRetryScheduled || state.scan.done || generation !== state.aggregationGeneration) return
-    state.baselineRetryScheduled = true
-    const delay = state.baselineRetryDelay
-    state.baselineRetryDelay = Math.min(state.baselineRetryDelay * 2, 30000)
-    void safeContextTimeout(delay).then((ready) => {
-      if (generation !== state.aggregationGeneration) return undefined
-      state.baselineRetryScheduled = false
-      if (ready && !state.scan.started && !state.scan.done) return runBaseline(generation)
-      if (!ready && !state.disposed) scheduleNativeBaselineRetry(generation, delay)
-      return undefined
-    })
-  }
-  function scanOneSession(sid, record, wsId, generation, snapshots) {
-    return enqueue(sid, async () => {
-      if (state.disposed || generation !== state.aggregationGeneration) return
-      try {
-        if (state.sessionSeq.has(sid) && !state.liveResyncPending.has(sid)) return
-        // v1.0.8: when the persisted log revision is unchanged since the last ledger
-        // write, the whole readSession (full event transfer) is skipped — the ledger
-        // record is applied directly and the live feed keeps catching new events.
-        const previousRecord = state.ledgerRecords.get(sid)
-        const revision = snapshots === null ? undefined : snapshots.get(sid)
-        if (!state.liveResyncPending.has(sid) && previousRecord !== undefined && previousRecord.needsUpgrade !== true && previousRecord.rebuildRequired === undefined && previousRecord.workspaceId === wsId && typeof previousRecord.lastRevision === 'string' && typeof revision === 'string' && revision === previousRecord.lastRevision) {
-          state.sync.sessionsSkippedByRevision += 1
-          applyLedgerRecord(previousRecord, 'ledger-reuse')
-          state.sessionSeq.set(sid, previousRecord.lastSeq)
-          state.sessionCount.add(sid)
-          markStatsChanged('scan')
-          return
-        }
-        state.sync.sessionsRead += 1
-        markStatsChanged('scan')
-        const snap = await ctx.sessionQuery.readSession(sid)
-        if (state.disposed || generation !== state.aggregationGeneration) return
-        if (snap && Array.isArray(snap.events)) {
-          // v1.0.7: incremental seed — the durable ledger doubles as a per-session
-          // cursor (cc-switch session_log_sync mtime+offset parity). An unchanged
-          // session applies its canonical record directly and never re-folds;
-          // a changed session seeds the previous record once, then folds only the
-          // new tail (previously every listed session was re-read and fully rebuilt).
-          const sequence = sequenceProfile(snap.events)
-          const currentLastSeq = sequence.lastSeq
-          const previous = state.ledgerRecords.get(sid)
-          const canFoldTail = previous !== undefined && previous.needsUpgrade !== true && previous.rebuildRequired === undefined && previous.workspaceId === wsId && !sequence.nonMonotonic && !sequence.hasInvalid && previous.lastSeq >= 0 && currentLastSeq > previous.lastSeq
-          if (canFoldTail) {
-            applyLedgerRecord(previous, 'ledger-reuse')
-            foldEvents(wsId, snap.events, previous.lastSeq, sid, 'scan')
-          } else {
-            // A changed revision with no new tail may still contain a replacement;
-            // rebuild from the complete read instead of trusting lastSeq alone.
-            foldEvents(wsId, snap.events, undefined, sid, 'scan')
-          }
-          const ledger = buildLedgerRecord({ id: sid, header: record.header, events: snap.events }, wsId, 'scan', revision, previous, !sequence.hasInvalid)
-          const canonical = ledger === null ? state.ledgerRecords.get(sid) : (canFoldTail ? storeLedgerRecord(ledger) : replaceLedgerRecord(ledger))
-          if (canonical === ledger) {
-            void persistLedgerRecord(ledger)
-          }
-          const observedLastSeq = state.sessionSeq.get(sid)
-          const nextLastSeq = Math.max(currentLastSeq, observedLastSeq === undefined ? -1 : observedLastSeq)
-          state.sessionSeq.set(sid, nextLastSeq)
-          state.sessionCount.add(sid)
-          if (observedLastSeq === undefined || observedLastSeq <= currentLastSeq) cancelLiveResync(sid)
-          else scheduleLiveResync(sid, wsId, generation)
-        }
-      } catch (err) {
-        if (generation !== state.aggregationGeneration) return
-        state.sync.sessionsFailed += 1
-        state.scan.failed += 1
-        noteSyncError('session-read-failed')
-        const saved = state.ledgerRecords.get(sid)
-        if (saved !== undefined) {
-          applyLedgerRecord(saved, 'ledger-recovery')
-          if (saved.turns.length > 0 || saved.usage.length > 0) state.sync.sessionsRestoredFromLedger += 1
-          state.sessionSeq.set(sid, -1)
-          state.sessionCount.add(sid)
-        } else {
-          state.sessionSeq.set(sid, -1)
-        }
-      } finally {
-        if (generation === state.aggregationGeneration) {
-          state.scan.scanned += 1
-          markStatsChanged('scan')
-        }
-      }
-    })
-  }
-
-  async function runBaseline(generation = state.aggregationGeneration) {
-    if (state.scan.started || state.disposed || generation !== state.aggregationGeneration) return
-    state.scan.started = true
-    beginSync()
-    await Promise.all([state.ledgerReady, state.pricingReady])
-    if (state.disposed || generation !== state.aggregationGeneration) return
-    let setupFailed = false
-    try {
-      const workspaces = ctx.workspaceRegistry.list()
-      installWorkspaceSnapshot(buildWorkspaceSnapshot(workspaces))
-    } catch (err) {
-      console.error('[all-usage] workspace list failed:', err)
-      setupFailed = true
-      noteSyncError('workspace-list-failed')
-    }
-    let records = null
-    try {
-      records = await ctx.sessionQuery.listSessions()
-    } catch (err) {
-      console.error('[all-usage] session list failed:', err)
-      if (state.disposed || generation !== state.aggregationGeneration) return
-      noteSyncError('session-list-failed')
-    }
-    if (state.disposed || generation !== state.aggregationGeneration) return
-    // v1.0.8: cheap per-session change signal (header line + stat, no full-log read)
-    let snapshots = null
-    try {
-      const revisions = await loadSessionRevisions()
-      if (state.disposed || generation !== state.aggregationGeneration) return
-      if (revisions !== null) {
-        state.sync.persistenceSnapshotsAvailable = true
-        snapshots = revisions
-      }
-    } catch (err) {
-      console.error('[all-usage] session persistence snapshots unavailable:', err)
-      if (state.disposed || generation !== state.aggregationGeneration) return
-      state.sync.persistenceSnapshotsAvailable = false
-      markStatsChanged('scan')
-    }
-    if (state.disposed || generation !== state.aggregationGeneration) return
-    if (setupFailed || !Array.isArray(records)) {
-      // A transient registry failure must not be reported as a completed empty state.scan.
-      state.scan.started = false
-      markStatsChanged('scan')
-      scheduleBaselineRetry(generation)
-      return
-    }
-    state.scan.total = records.length
-    state.sync.sessionsTotal = records.length
-    markStatsChanged('scan')
-    const listedSessionIds = new Set()
-    for (const record of records) {
-      if (record === undefined || record === null || record.header === undefined) continue
-      const sid = record.header.id
-      const cwd = typeof record.header.cwd === 'string' ? record.header.cwd : ''
-      const wsId = workspaceForCwd(cwd)
-      if (sid !== undefined && wsId !== undefined) listedSessionIds.add(sid)
-    }
-    for (const [sid, record] of state.ledgerRecords) {
-      if (!listedSessionIds.has(sid)) {
-        // Recorded usage survives deletion. A session whose workspace, cwd or
-        // log is gone still counts from its ledger row; only legacy synthetic
-        // rows, which never belonged to a registered workspace, stay excluded.
-        if (typeof record.workspaceId === 'string' && record.workspaceId.startsWith('unregistered:')) continue
-        // Usage from a workspace that is no longer registered is summed into the
-        // shared deleted bucket, so history survives without a row per dead
-        // workspace. The stored row keeps its original workspace id and cwd.
-        const retired = typeof record.workspaceId !== 'string' || !state.wsMeta.has(record.workspaceId)
-        const carriesUsage = record.turns.length > 0 || record.usage.length > 0
-        // An empty row must not advertise a bucket that holds nothing.
-        if (retired && carriesUsage) state.retiredBucketUsed = true
-        applyLedgerRecord(retired ? retargetLedgerRecord(record) : record, retired ? 'ledger-retired' : 'ledger-recovery')
-        if (carriesUsage) state.sync.sessionsRestoredFromLedger += 1
-      }
-    }
-    if (state.sync.sessionsRestoredFromLedger > 0) markStatsChanged('scan')
-    for (const record of records) {
-      if (state.disposed || generation !== state.aggregationGeneration) return
-      if (record === undefined || record === null || record.header === undefined) {
-        state.scan.scanned += 1
-        markStatsChanged('scan')
-        continue
-      }
-      const sid = record.header.id
-      const cwd = typeof record.header.cwd === 'string' ? record.header.cwd : ''
-      const wsId = workspaceForCwd(cwd)
-      if (sid === undefined || wsId === undefined) {
-        state.scan.scanned += 1
-        markStatsChanged('scan')
-        continue
-      }
-      listedSessionIds.add(sid)
-      await scanOneSession(sid, record, wsId, generation, snapshots)
-      if (!(await safeContextTimeout(0))) {
-        state.scan.started = false
-        noteSyncError('baseline-yield-unavailable')
-        scheduleBaselineRetry(generation)
-        return
-      }
-    }
-    if (state.disposed || generation !== state.aggregationGeneration) return
-    await drainLedgerWrites()
-    if (state.disposed || generation !== state.aggregationGeneration) return
-    const costBackfill = backfillUnpricedCosts()
-    if (costBackfill.priced > 0) {
-      await drainLedgerWrites()
-      markStatsChanged('pricing')
-    }
-    if (state.disposed || generation !== state.aggregationGeneration) return
-    const temporalReconcile = reconcileTemporalPricing()
-    if (temporalReconcile.reconciled > 0) {
-      await drainLedgerWrites()
-      markStatsChanged('pricing')
-    }
-    if (state.disposed || generation !== state.aggregationGeneration) return
-    state.knownSessionIds.clear()
-    for (const sid of listedSessionIds) state.knownSessionIds.add(sid)
-    state.scan.done = true
-    if (state.workspaceSyncDeferred) {
-      state.workspaceSyncDeferred = false
-      scheduleWorkspaceSync()
-    }
-    state.sync.lastCompletedAt = Date.now()
-    if (state.sync.sessionsFailed === 0) {
-      state.sync.lastErrorAt = 0
-      state.sync.lastErrorCode = null
-    }
-    markStatsChanged('scan')
-    if (state.reconcilePending) scheduleReconcileHint()
-  }
-
-  function scheduleWorkspaceSync() {
-    if (state.disposed) return
-    if (state.workspaceSyncTimer !== null) return
-    state.workspaceSyncTimer = setTimeout(() => {
-      state.workspaceSyncTimer = null
-      if (!state.disposed) void runWorkspaceSync()
-    }, WORKSPACE_SYNC_DEBOUNCE_MS)
-    if (state.workspaceSyncTimer && typeof state.workspaceSyncTimer.unref === 'function') state.workspaceSyncTimer.unref()
-  }
-  async function runWorkspaceSync() {
-    if (state.disposed) return
-    if (state.workspaceSyncInFlight) {
-      state.workspaceSyncPending = true
-      return
-    }
-    state.workspaceSyncInFlight = true
-    state.sync.workspaceSyncRuns += 1
-    try {
-      await synchronizeWorkspaceRegistry()
-    } catch (err) {
-      console.error('[all-usage] workspace synchronize failed:', err)
-      noteSyncError('workspace-sync-failed')
-    } finally {
-      state.workspaceSyncInFlight = false
-      if (state.workspaceSyncPending) {
-        state.workspaceSyncPending = false
-        scheduleWorkspaceSync()
-      }
-    }
-  }
-  async function synchronizeWorkspaceRegistry() {
-    if (state.disposed) return
-    // A registry change that lands while a baseline is running used to be
-    // dropped outright, which is why a new workspace could stay invisible until
-    // the next restart. Remember it and re-run once the scan settles.
-    if (!state.scan.done) {
-      state.workspaceSyncDeferred = true
-      state.sync.workspaceSyncDeferred += 1
-      return
-    }
-    let workspaces
-    try {
-      workspaces = ctx.workspaceRegistry.list()
-    } catch (err) {
-      console.error('[all-usage] workspace list failed:', err)
-      noteSyncError('workspace-list-failed')
-      return
-    }
-    const next = buildWorkspaceSnapshot(workspaces)
-    const removedWs = new Set()
-    for (const id of state.wsMeta.keys()) if (!next.wsMeta.has(id)) removedWs.add(id)
-    const addedWs = new Set()
-    for (const id of next.wsMeta.keys()) if (!state.wsMeta.has(id)) addedWs.add(id)
-    state.sync.workspaceSyncAdded += addedWs.size
-    state.sync.workspaceSyncRemoved += removedWs.size
-    // Reuse path: no membership change — metadata only, zero rescan.
-    if (removedWs.size === 0 && addedWs.size === 0) {
-      installWorkspaceSnapshot(next)
-      return
-    }
-    // Retire path: a deregistered workspace keeps everything it recorded. The
-    // ledger's promise is that flushed usage survives deletion, so sessions are
-    // re-applied under the shared deleted bucket instead of being subtracted and
-    // dropped. New sessions still cannot enter the workspace: pathIndex only
-    // ever carries registered workspaces, so workspaceForCwd() no longer
-    // resolves its cwd and the scan skips it.
-    if (removedWs.size > 0) {
-      const retiredSids = new Set()
-      for (const [sid, record] of state.ledgerRecords) {
-        if (record === null || record === undefined || !removedWs.has(record.workspaceId)) continue
-        retiredSids.add(sid)
-      }
-      for (const [sid, id] of state.memberOf) if (removedWs.has(id)) retiredSids.add(sid)
-      let moved = 0
-      for (const sid of retiredSids) {
-        if (typeof sid !== 'string' || sid === '') continue
-        // Re-key the live aggregate first: usage folded from the feed but not yet
-        // persisted has no ledger row to replay, and a session the registry no
-        // longer lists is never re-scanned afterwards.
-        moved += host.aggregation.retargetSession(sid, RETIRED_WORKSPACE_ID)
-        const record = state.ledgerRecords.get(sid)
-        // Keep the in-memory record aligned with the aggregate; the persisted row
-        // keeps its original workspace id and cwd, so recovery re-derives this.
-        if (record !== undefined && (record.turns.length > 0 || record.usage.length > 0)) moved += 1
-        if (record !== undefined) state.ledgerRecords.set(sid, retargetLedgerRecord(record))
-      }
-      if (moved > 0) state.retiredBucketUsed = true
-    }
-    installWorkspaceSnapshot(next)
-    // Add path: scan only the sessions that belong to newly registered workspaces.
-    if (addedWs.size === 0) return
-    let records = null
-    try {
-      records = await ctx.sessionQuery.listSessions()
-    } catch (err) {
-      console.error('[all-usage] session list failed:', err)
-      noteSyncError('session-list-failed')
-    }
-    if (!Array.isArray(records)) return
-    state.sync.sessionsTotal = records.length
-    markStatsChanged('scan')
-    let snapshots = null
-    try {
-      snapshots = await loadSessionRevisions()
-    } catch (err) {
-      console.error('[all-usage] session persistence snapshots unavailable:', err)
-    }
-    for (const record of records) {
-      if (state.disposed) return
-      if (record === undefined || record === null || record.header === undefined) continue
-      const sid = record.header.id
-      const cwd = typeof record.header.cwd === 'string' ? record.header.cwd : ''
-      const wsId = workspaceForCwd(cwd)
-      if (sid === undefined || wsId === undefined) continue
-      if (!addedWs.has(wsId)) continue
-      state.knownSessionIds.add(sid)
-      scanOneSession(sid, record, wsId, state.aggregationGeneration, snapshots)
-    }
-  }
-
-  function sessionIdsFromRecords(records) {
-    const ids = new Set()
-    for (const record of records) {
-      if (record === undefined || record === null || record.header === undefined) continue
-      const sid = record.header.id
-      const cwd = typeof record.header.cwd === 'string' ? record.header.cwd : ''
-      const wsId = workspaceForCwd(cwd)
-      if (sid !== undefined && wsId !== undefined) ids.add(sid)
-    }
-    return ids
-  }
-  async function reconcileSessions() {
-    if (state.disposed || state.reconcileInFlight || !state.scan.done) return
-    state.reconcilePending = false
-    state.reconcileInFlight = true
-    try {
-      const records = await ctx.sessionQuery.listSessions()
-      if (state.disposed || !Array.isArray(records)) return
-      const currentIds = sessionIdsFromRecords(records)
-      let removed = false
-      for (const sid of state.knownSessionIds) {
-        if (!currentIds.has(sid)) { removed = true; break }
-      }
-      if (removed && !state.disposed && state.scan.done) {
-        console.info('[all-usage] session removal detected; rebuilding usage index')
-        const generation = resetAggregationState()
-        void runBaseline(generation)
-        return
-      }
-      state.knownSessionIds.clear()
-      for (const sid of currentIds) state.knownSessionIds.add(sid)
-    } catch (err) {
-      console.error('[all-usage] session reconciliation failed:', err)
-      noteSyncError('session-reconcile-failed')
-    } finally {
-      state.reconcileInFlight = false
-      if (state.reconcilePending && !state.disposed) scheduleReconcileHint()
-    }
-  }
-  function scheduleReconcileHint() {
-    if (state.disposed) return
-    state.reconcilePending = true
-    if (state.reconcileHintScheduled || state.reconcileInFlight) return
-    state.reconcileHintScheduled = true
-    const generation = state.aggregationGeneration
-    void safeContextTimeout(RECONCILE_HINT_DELAY_MS).then((ready) => {
-      if (generation !== state.aggregationGeneration) return
-      state.reconcileHintScheduled = false
-      if (ready && !state.disposed) void reconcileSessions()
-    }, () => {
-      if (generation === state.aggregationGeneration) state.reconcileHintScheduled = false
-    })
-  }
-  function scheduleReconcileTimer() {
-    if (state.disposed || state.reconcileTimer !== null) return
-    state.reconcileTimer = setTimeout(() => {
-      state.reconcileTimer = null
-      if (!state.disposed) {
-        void reconcileSessions()
-        scheduleReconcileTimer()
-      }
-    }, RECONCILE_INTERVAL_MS)
-    if (state.reconcileTimer && typeof state.reconcileTimer.unref === 'function') state.reconcileTimer.unref()
-  }
-  // Belt and braces for the registry probe: the event fast path can be missed
-  // (dropped while scanning, or never delivered), and unlike the event this
-  // cannot silently leave the workspace list stale until a restart.
-  function scheduleWorkspaceProbeTimer() {
-    if (state.disposed || state.workspaceProbeTimer !== null) return
-    state.workspaceProbeTimer = setTimeout(() => {
-      state.workspaceProbeTimer = null
-      if (!state.disposed) {
-        void runWorkspaceSync()
-        scheduleWorkspaceProbeTimer()
-      }
-    }, WORKSPACE_PROBE_INTERVAL_MS)
-    if (state.workspaceProbeTimer && typeof state.workspaceProbeTimer.unref === 'function') state.workspaceProbeTimer.unref()
-  }
-
-  // ---------- live feed ----------
-  ctx.on('session/event', (session, event) => {
-    if (state.disposed) return
-    if (event === undefined || event === null) return
-    const type = event.type
-    if (type !== 'turn/end' && type !== 'assistant/message' && type !== 'assistant/chunk' && type !== 'request/context' && type !== 'request/header') return
-    const sid = session && session.id
-    if (typeof sid !== 'string') return
-    markLedgerDirty(sid)
-    const wsId = wsForLiveSession(session, sid)
-    if (wsId === undefined) return
-    const generation = state.aggregationGeneration
-    state.knownSessionIds.add(sid)
-    enqueue(sid, () => processLiveEvent(sid, wsId, event, generation))
-  })
-  ctx.on('session/flush', async (session) => {
-    if (state.disposed || session === null || typeof session !== 'object' || typeof session.id !== 'string') return
-    const sid = session.id
-    const previous = state.ledgerRecords.get(sid)
-    const eventList = sessionEvents(session)
-    // DSH sequences events with seq === log index: the tail event gives the
-    // latest sequence in O(1) without scanning a 500K-event session twice.
-    const tailEvent = eventList.length > 0 ? eventList[eventList.length - 1] : null
-    const currentLastSeq = tailEvent !== null && Number.isSafeInteger(tailEvent.seq) && tailEvent.seq >= 0 ? tailEvent.seq : lastSeqOf(eventList)
-    const hasNewEvents = state.ledgerDirtySessions.has(sid) || state.ledgerWriteFailedSessions.has(sid) || (previous === undefined && currentLastSeq >= 0) || (previous !== undefined && currentLastSeq > previous.lastSeq)
-    if (!hasNewEvents) return
-    const dirtyEpoch = state.ledgerDirtyEpochs.get(sid) || 0
-    await Promise.all([state.ledgerReady, state.pricingReady])
-    if (state.disposed) return
-    const wsId = wsForLiveSession(session, sid)
-    if (wsId === undefined) return
-    // Any dirty flush whose log contains invalid sequences may have rewritten
-    // history (even when a new tail was appended) or carries contract-external
-    // events; refuse to fold it and rebuild the whole usage index instead, so
-    // the in-memory aggregate and the persisted ledger cannot disagree.
-    if (previous !== undefined && eventList.length > 0) {
-      const sequence = sequenceProfile(eventList)
-      if (sequence.hasInvalid) {
-        if (state.scan.done && !state.disposed) {
-          console.info('[all-usage] invalid sequences in flushed log; rebuilding usage index')
-          // Persist the rebuild flag so the baseline cannot fast-path the stale
-          // record (the persistence revision may still match a lagging log).
-          const current = state.ledgerRecords.get(sid)
-          if (current !== undefined) {
-            current.rebuildRequired = 'invalid-flush-sequence'
-            current.needsUpgrade = true
-            void persistLedgerRecord(current)
-          }
-          const generation = resetAggregationState()
-          void runBaseline(generation)
-        }
-        return
-      }
-    }
-    const ledger = buildLedgerRecord(session, wsId, 'flush', undefined, previous)
-    if (ledger === null) return
-    const canonical = storeLedgerRecord(ledger)
-    if (canonical === ledger) void persistLedgerRecord(ledger)
-    if (state.ledgerDirtyEpochs.get(sid) === dirtyEpoch) {
-      state.ledgerDirtySessions.delete(sid)
-      state.ledgerDirtyEpochs.delete(sid)
-    }
-  })
-  ctx.on('session/disposed', () => {
-    if (!state.disposed) scheduleReconcileHint()
-  })
-  // Workspace registry probe: DSH emits domain/changed after every durable
-  // workspace-domain write (create/delete/rename/reorder/archive/attach/detach).
-  // On any such change we re-read workspaceRegistry.list() and, when membership
-  // changed, rescan only the affected workspaces — unchanged ones keep their
-  // computed aggregates and ledger untouched.
-  ctx.on('domain/changed', (change) => {
-    if (state.disposed) return
-    if (change === undefined || change === null) return
-    if (change.domain !== 'workspace') return
-    if (change.table !== 'workspaces' && change.table !== '') return
-    state.sync.workspaceProbeEvents += 1
-    scheduleWorkspaceSync()
-  })
-
-  return {
-    foldEvent,
-    foldEvents,
-    lastSeqOf,
-    sequenceProfile,
-    enqueue,
-    wsForLiveSession,
-    cancelLiveResync,
-    scheduleLiveResync,
-    foldLiveFallback,
-    syncLiveSession,
-    resyncLiveSession,
-    processLiveEvent,
-    scheduleNativeBaselineRetry,
-    scheduleBaselineRetry,
-    runBaseline,
-    synchronizeWorkspaceRegistry,
-    scheduleWorkspaceSync,
-    sessionIdsFromRecords,
-    reconcileSessions,
-    scheduleReconcileHint,
-    scheduleReconcileTimer,
-    scheduleWorkspaceProbeTimer,
-    markLedgerDirty
-  }
-}
+import { RETIRED_WORKSPACE_ID, retargetLedgerRecord } from './ledger.js'
+import { contextTimeKey, extractUsageEvent, pickPricingTime, touchContextTimes, usageStepKey, workspacePathKey } from './usage-core.js'
+
+const RECONCILE_INTERVAL_MS = 120000
+const RECONCILE_HINT_DELAY_MS = 3000
+const WORKSPACE_SYNC_DEBOUNCE_MS = 300
+// The registry event is a fast path, not a guarantee: a change that lands while a
+// baseline runs used to be dropped outright, and a missed event left the plugin
+// stale until the next restart. The (in-memory) registry list is polled as well.
+const WORKSPACE_PROBE_INTERVAL_MS = 30000
+
+export function createSessionSync(host) {
+  const { ctx, state } = host
+  state.retiringWorkspaceIds = state.retiringWorkspaceIds || new Set()
+  if (!(state.liveResyncTriggers instanceof Map)) state.liveResyncTriggers = new Map()
+  const { sessionPersistence } = host.services
+  const {
+    validEventTime,
+    identityFromRoute,
+    identityFromMessage,
+    coerceIdentity,
+    addTurn,
+    addUsage,
+    resetAggregationState,
+  } = host.aggregation
+  const { beginSync, noteSyncError, markStatsChanged } = host
+  const {
+    sessionEvents,
+    buildLedgerRecord,
+    applyLedgerRecord,
+    storeLedgerRecord,
+    replaceLedgerRecord,
+    persistLedgerRecord,
+    drainLedgerWrites,
+  } = host.ledger
+  const safeContextTimeout = async (ms) => {
+    if (state.disposed) return false
+    try {
+      await ctx.timeout(ms)
+      return !state.disposed
+    } catch (err) {
+      if (!state.disposed) console.error('[all-usage] context timer unavailable:', err)
+      return false
+    }
+  }
+  // Session history reads prefer the official observation API: one immutable cut
+  // with projection work skipped, released through the lease's Symbol.dispose.
+  // A Host without observeSession keeps the legacy readSession snapshot.
+  function readSessionSnapshot(sid) {
+    const query = ctx.sessionQuery
+    if (typeof query.observeSession === 'function') return query.observeSession(sid, { projectionMode: 'none' })
+    return query.readSession(sid)
+  }
+  // Releasing is synchronous and only applies to a lease; a readSession snapshot
+  // carries no disposal protocol and needs no action.
+  function releaseSessionSnapshot(snap) {
+    if (snap === null || snap === undefined) return
+    const dispose = typeof Symbol.dispose === 'symbol' ? snap[Symbol.dispose] : undefined
+    if (typeof dispose === 'function') dispose.call(snap)
+  }
+
+  function foldEvent(wsId, time, type, data, sid, seq, materialization = 'live') {
+    // The durable record keeps the original workspace id. Its in-memory
+    // contribution must follow a removal immediately, including queued live
+    // events that captured the old mapping before retirement began.
+    if (state.retiringWorkspaceIds.has(wsId)) wsId = RETIRED_WORKSPACE_ID
+    if ((type === 'turn/end' || type === 'assistant/message' || type === 'assistant/chunk') && !validEventTime(time)) return
+    if (type === 'request/context') {
+      state.sessionModel.set(sid, identityFromRoute(data, state.sessionModel.get(sid)))
+      if (validEventTime(time)) {
+        let times = state.sessionContextTimes.get(sid)
+        if (times === undefined) { times = new Map(); state.sessionContextTimes.set(sid, times) }
+        touchContextTimes(times, contextTimeKey(data && data.turn, data && data.step), time)
+      }
+    } else if (type === 'request/header') {
+      state.sessionModel.set(sid, identityFromRoute(data, state.sessionModel.get(sid)))
+    } else if (type === 'turn/end') {
+      addTurn(wsId, time, sid, data && typeof data.turn === 'number' ? data.turn : null, state.sessionModel.get(sid), materialization, seq)
+    } else if (type === 'assistant/message' || type === 'assistant/chunk') {
+      const usageEvent = extractUsageEvent({ type, time, data, seq })
+      if (usageEvent === null) return
+      const identity = usageEvent.kind === 'message' ? identityFromMessage(data, state.sessionModel.get(sid)) : coerceIdentity(state.sessionModel.get(sid))
+      state.sessionModel.set(sid, identity)
+      const pricing = pickPricingTime(state.sessionContextTimes.get(sid), time, usageEvent.turn, usageEvent.step)
+      addUsage(wsId, time, usageEvent.usage, identity, sid, data, seq, materialization, pricing.time, pricing.source)
+    }
+  }
+  function foldEvents(wsId, events, fromSeq, sid, materialization = 'scan') {
+    // Full folds keep their callers responsible for atomicity: runBaseline and
+    // syncLiveSession remove the session's old usage/turn/context/identity
+    // first when the snapshot is authoritative (see rebuildSession below), so
+    // usage deleted by a history rewrite disappears from the aggregate.
+    for (const ev of events) {
+      if (fromSeq !== undefined) {
+        const s = typeof ev.seq === 'number' ? ev.seq : -1
+        if (s <= fromSeq) continue
+      }
+      if (ev.type === 'turn/end' || ev.type === 'assistant/message' || ev.type === 'assistant/chunk' || ev.type === 'request/context' || ev.type === 'request/header') foldEvent(wsId, ev.time, ev.type, ev.data, sid, ev.seq, materialization)
+    }
+  }
+  function lastSeqOf(events) {
+    let last = -1
+    for (const ev of events) {
+      const s = Number.isSafeInteger(ev.seq) ? ev.seq : -1
+      if (s > last) last = s
+    }
+    return last
+  }
+  function sequenceProfile(events) {
+    let previous = -1
+    let last = -1
+    let nonMonotonic = false
+    let hasInvalid = false
+    for (const ev of events) {
+      const seq = ev && Number.isSafeInteger(ev.seq) && ev.seq >= 0 ? ev.seq : -1
+      if (seq < 0) { hasInvalid = true; continue }
+      if (seq <= previous) nonMonotonic = true
+      previous = seq
+      if (seq > last) last = seq
+    }
+    return { lastSeq: last, nonMonotonic, hasInvalid }
+  }
+  function enqueue(sid, task) {
+    const prev = state.chains.get(sid) || Promise.resolve()
+    const next = prev.then(() => task(), () => task())
+    state.chains.set(sid, next)
+    const cleanup = () => { if (state.chains.get(sid) === next) state.chains.delete(sid) }
+    void next.then(cleanup, cleanup)
+    return next
+  }
+  function markLedgerDirty(sid) {
+    if (typeof sid !== 'string' || sid === '') return
+    state.ledgerDirtySessions.add(sid)
+    state.ledgerDirtyEpochs.set(sid, (state.ledgerDirtyEpochs.get(sid) || 0) + 1)
+  }
+  function buildWorkspaceSnapshot(workspaces) {
+    const wsMeta = new Map()
+    const pathIndex = new Map()
+    const memberOf = new Map()
+    for (const w of workspaces) {
+      const id = w && w.id
+      const path = w && typeof w.path === 'string' ? w.path : ''
+      const title = w && typeof w.title === 'string' ? w.title : ''
+      if (id === undefined) continue
+      wsMeta.set(id, { id, title, path })
+      if (path !== '') pathIndex.set(workspacePathKey(path), id)
+      if (w && Array.isArray(w.sessionIds)) {
+        for (const sid of w.sessionIds) memberOf.set(sid, id)
+      }
+    }
+    return { wsMeta, pathIndex, memberOf }
+  }
+  function installWorkspaceSnapshot(next) {
+    let metadataChanged = state.wsMeta.size !== next.wsMeta.size || state.pathIndex.size !== next.pathIndex.size || state.memberOf.size !== next.memberOf.size
+    if (!metadataChanged) {
+      for (const [id, value] of next.wsMeta) {
+        const previous = state.wsMeta.get(id)
+        if (previous === undefined || previous.title !== value.title || previous.path !== value.path) { metadataChanged = true; break }
+      }
+    }
+    if (!metadataChanged) {
+      for (const [path, id] of next.pathIndex) if (state.pathIndex.get(path) !== id) { metadataChanged = true; break }
+    }
+    if (!metadataChanged) {
+      for (const [sid, id] of next.memberOf) if (state.memberOf.get(sid) !== id) { metadataChanged = true; break }
+    }
+    state.wsMeta.clear()
+    state.pathIndex.clear()
+    state.memberOf.clear()
+    for (const [id, value] of next.wsMeta) { state.retiringWorkspaceIds.delete(id); state.wsMeta.set(id, value) }
+    for (const [path, id] of next.pathIndex) state.pathIndex.set(path, id)
+    for (const [sid, id] of next.memberOf) state.memberOf.set(sid, id)
+    if (metadataChanged) markStatsChanged('metadata')
+    return metadataChanged
+  }
+  function workspaceForCwd(cwd) {
+    if (typeof cwd !== 'string' || cwd === '') return undefined
+    return state.pathIndex.get(workspacePathKey(cwd))
+  }
+  // DSH 0.1.5 replaced \`sessionPersistence.listSnapshots()\` with \`list()\`; both
+  // return per-session \`{ header, revision }\` rows. Without a revision the
+  // ledger-reuse fast path never fires, so every baseline re-reads every log.
+  async function loadSessionRevisions() {
+    const source = sessionPersistence
+    if (source === undefined || source === null) return null
+    const read = typeof source.list === 'function'
+      ? () => source.list()
+      : (typeof source.listSnapshots === 'function' ? () => source.listSnapshots() : null)
+    if (read === null) return null
+    const rows = await read()
+    if (!Array.isArray(rows)) return null
+    const revisions = new Map()
+    for (const row of rows) {
+      const rid = row && row.header && typeof row.header.id === 'string' ? row.header.id : undefined
+      if (rid !== undefined && row && typeof row.revision === 'string') revisions.set(rid, row.revision)
+    }
+    return revisions
+  }
+  function wsForLiveSession(session, sid) {
+    let wsId = state.memberOf.get(sid)
+    if (wsId !== undefined) return wsId
+    const header = session && session.header
+    const cwd = header && typeof header.cwd === 'string' ? header.cwd : ''
+    wsId = workspaceForCwd(cwd)
+    if (wsId !== undefined) state.memberOf.set(sid, wsId)
+    return wsId
+  }
+  function cancelLiveResync(sid) {
+    const timer = state.liveResyncTimers.get(sid)
+    if (timer !== undefined) {
+      clearTimeout(timer)
+      state.liveResyncTimers.delete(sid)
+    }
+    state.liveResyncAttempts.delete(sid)
+    state.liveResyncPending.delete(sid)
+    state.liveResyncTriggers.delete(sid)
+  }
+  function usageEventSignature(event) {
+    const data = event.data || {}
+    const message = data.message || {}
+    const usage = event.type === 'assistant/chunk' ? data.chunk && data.chunk.usage : data.usage
+    return JSON.stringify([event.seq, event.time, event.type, data.turn, data.step, data.usageId, data.sampleId, data.requestId, data.callId, data.stepId, data.messageId, message.id, message.source, usage])
+  }
+  function retainLiveResyncTrigger(sid, key, event) {
+    let pending = state.liveResyncTriggers.get(sid)
+    if (pending === undefined) { pending = new Map(); state.liveResyncTriggers.set(sid, pending) }
+    const seq = Number.isSafeInteger(event.seq) ? event.seq : -1
+    const previous = pending.get(key)
+    if (previous !== undefined && previous.seq > seq) return
+    pending.set(key, { seq, signature: usageEventSignature(event) })
+  }
+  function snapshotCoversTriggers(sid, events) {
+    const pending = state.liveResyncTriggers.get(sid)
+    if (pending === undefined || pending.size === 0) return true
+    const candidates = new Map()
+    for (const event of events) {
+      if (event === null || typeof event !== 'object' || (event.type !== 'assistant/message' && event.type !== 'assistant/chunk') || event.data === null || typeof event.data !== 'object') continue
+      const seq = Number.isSafeInteger(event.seq) ? event.seq : -1
+      const key = usageStepKey(sid, event.data, seq, event.time)
+      if (!pending.has(key)) continue
+      const frame = extractUsageEvent(event)
+      if (frame === null) continue
+      const previous = candidates.get(key)
+      if (previous === undefined || seq > previous.seq) candidates.set(key, { seq, signature: usageEventSignature(event) })
+    }
+    for (const [key, expected] of pending) {
+      const found = candidates.get(key)
+      if (found === undefined || found.seq < expected.seq || (found.seq === expected.seq && found.signature !== expected.signature)) return false
+    }
+    return true
+  }
+  function scheduleLiveResync(sid, wsId, generation) {
+    if (state.disposed || generation !== state.aggregationGeneration || !state.liveResyncPending.has(sid) || state.liveResyncTimers.has(sid)) return
+    const attempt = state.liveResyncAttempts.get(sid) || 0
+    const delay = Math.min(30000, 1000 * Math.pow(2, Math.min(attempt, 5)))
+    const timer = setTimeout(() => {
+      state.liveResyncTimers.delete(sid)
+      if (state.disposed || generation !== state.aggregationGeneration || !state.liveResyncPending.has(sid)) return
+      void enqueue(sid, () => resyncLiveSession(sid, wsId, generation))
+    }, delay)
+    state.liveResyncTimers.set(sid, timer)
+    if (timer && typeof timer.unref === 'function') timer.unref()
+  }
+  function foldLiveFallback(sid, wsId, event) {
+    if (event === null || event === undefined) return
+    const seq = Number.isSafeInteger(event.seq) && event.seq >= 0 ? event.seq : -1
+    foldEvent(wsId, event.time, event.type, event.data, sid, seq, 'live')
+    if (seq >= 0) {
+      const current = state.sessionSeq.get(sid)
+      if (current === undefined || seq > current) state.sessionSeq.set(sid, seq)
+    }
+    state.sessionCount.add(sid)
+  }
+  async function syncLiveSession(sid, wsId, event, generation) {
+    let snap
+    try {
+      snap = await readSessionSnapshot(sid)
+      if (state.disposed || generation !== state.aggregationGeneration) return true
+      const events = snap === null || snap === undefined ? undefined : snap.events
+      if (Array.isArray(events)) {
+        const snapshotLast = lastSeqOf(events)
+        const snapshotProfile = sequenceProfile(events)
+        const eventSeq = event === null || event === undefined ? -1 : (Number.isSafeInteger(event.seq) && event.seq >= 0 ? event.seq : -1)
+        // The snapshot may replace the session only when it is provably
+        // complete AND it already contains the triggering event: a timer / full
+        // resync (no event), or an explicitly contained, monotonic event
+        // stream. A snapshot that merely has a higher tail than the event is
+        // NOT proof — the event could be a live append the snapshot missed (or
+        // the snapshot could have been rewritten without it), so the event is
+        // upserted and the session stays pending for a follow-up alignment.
+        // Events without a usable seq never trigger a destructive replacement.
+        const containsEvent = event !== null && event !== undefined && eventSeq >= 0 && events.some((candidate) => candidate && Number.isSafeInteger(candidate.seq) && candidate.seq === eventSeq)
+        const coversTriggers = snapshotCoversTriggers(sid, events)
+        const authoritative = (event === null || event === undefined ? true : eventSeq < 0 ? false : containsEvent) && !snapshotProfile.nonMonotonic && !snapshotProfile.hasInvalid && coversTriggers
+        // A pending usage trigger can only be settled by a complete, sequence-valid
+        // rebuild. Even a snapshot containing it is unsafe to fold as live data when
+        // unrelated sequence damage makes the snapshot ambiguous.
+        if (state.liveResyncTriggers.has(sid) && (!coversTriggers || snapshotProfile.nonMonotonic || snapshotProfile.hasInvalid)) return false
+        if (authoritative) {
+          host.aggregation.removeSession(sid)
+          // The authoritative snapshot is the new truth for both the in-memory
+          // aggregate and the durable ledger: rebuild the record from scratch
+          // and persist it, so a restart after a live history rewrite cannot
+          // resurrect usage that the snapshot deleted.
+          const rebuiltRecord = buildLedgerRecord({ id: sid, events }, wsId, 'scan', undefined, null, true)
+          if (rebuiltRecord !== null) {
+            const canonical = replaceLedgerRecord(rebuiltRecord)
+            if (canonical === rebuiltRecord) {
+              void persistLedgerRecord(rebuiltRecord).then(() => {
+                if (state.ledgerWriteFailedSessions && state.ledgerWriteFailedSessions.has(sid)) {
+                  console.error('[all-usage] authoritative resync ledger persist failed; session stays dirty:', sid)
+                  noteSyncError('resync-ledger-persist-failed')
+                }
+              })
+            }
+          }
+        }
+        // Complete persisted history may have reversed timestamps even when
+        // its sequences are canonical. Only incomplete fallback folds use the
+        // live replay heuristics.
+        foldEvents(wsId, events, undefined, sid, authoritative ? 'scan' : 'live')
+        let nextLast = snapshotLast
+        const needsFollowup = !authoritative && event !== null && event !== undefined
+        if (needsFollowup) {
+          foldLiveFallback(sid, wsId, event)
+          const current = state.sessionSeq.get(sid)
+          nextLast = Math.max(nextLast, current === undefined ? -1 : current)
+        }
+        state.sessionSeq.set(sid, nextLast)
+        state.sessionCount.add(sid)
+        if (needsFollowup) {
+          // The snapshot is behind: keep the pending flag so the follow-up
+          // resync realigns the cursor once the missing history arrives.
+          scheduleLiveResync(sid, wsId, generation)
+        } else {
+          state.liveResyncPending.delete(sid)
+          cancelLiveResync(sid)
+        }
+        return true
+      }
+    } catch (err) {
+      // Keep the event as a fallback and retry a complete session state.sync later.
+    } finally {
+      // The lease is held for the whole read — success, failure, or a generation
+      // change — and released only once this call is completely done. A legacy
+      // readSession snapshot carries no disposal protocol.
+      releaseSessionSnapshot(snap)
+    }
+    return false
+  }
+  async function resyncLiveSession(sid, wsId, generation) {
+    if (state.disposed || generation !== state.aggregationGeneration || !state.liveResyncPending.has(sid)) return
+    if (await syncLiveSession(sid, wsId, null, generation)) return
+    state.liveResyncAttempts.set(sid, (state.liveResyncAttempts.get(sid) || 0) + 1)
+    scheduleLiveResync(sid, wsId, generation)
+  }
+  async function processLiveEvent(sid, wsId, event, generation = state.aggregationGeneration) {
+    if (state.disposed || generation !== state.aggregationGeneration) return
+    const seq = Number.isSafeInteger(event.seq) ? event.seq : -1
+    const last = state.sessionSeq.get(sid)
+    const frame = extractUsageEvent(event)
+    const key = frame === null ? null : usageStepKey(sid, frame.data, seq, event.time)
+    // A known key can be replaced only after authoritative alignment once its
+    // detail is evicted. A replay-shaped new key also needs proof before the live
+    // replay fence can discard it, so preserve either trigger through retries.
+    const digest = state.perSession.get(sid)
+    const knownKey = key !== null && digest?.keys.has(key)
+    const evictedCorrection = knownKey && !state.usageByStep.has(key)
+    const replayShapedAppend = key !== null && !knownKey && digest !== undefined && (event.time < digest.newestTime || state.turnRecords.has(sid + ':turn:' + frame.turn))
+    // A fresh sequence can still look like a replay after a clock correction or
+    // late usage delivery. Prove it against persisted history before rejecting it.
+    const needsUsageSync = seq > (last ?? -1) && (evictedCorrection || replayShapedAppend)
+    const needsSync = last === undefined || state.liveResyncPending.has(sid) || (seq >= 0 && seq > last + 1) || needsUsageSync
+    if (needsSync) {
+      if (needsUsageSync) retainLiveResyncTrigger(sid, key, event)
+      state.liveResyncPending.add(sid)
+      if (await syncLiveSession(sid, wsId, event, generation)) return
+      // Keep sync-triggering usage out of the cube until history proves whether
+      // it is an addition or a replacement for an evicted contribution.
+      if (!evictedCorrection) foldLiveFallback(sid, wsId, event)
+      state.liveResyncAttempts.set(sid, (state.liveResyncAttempts.get(sid) || 0) + 1)
+      scheduleLiveResync(sid, wsId, generation)
+      return
+    }
+    if (seq < 0) {
+      foldLiveFallback(sid, wsId, event)
+      return
+    }
+    if (seq <= last) return
+    foldLiveFallback(sid, wsId, event)
+  }
+
+  // ---------- durable usage ledger ----------
+  function scheduleNativeBaselineRetry(generation, delay) {
+    if (state.disposed || state.baselineFallbackTimer !== null) return
+    state.baselineFallbackTimer = setTimeout(() => {
+      state.baselineFallbackTimer = null
+      if (!state.disposed && generation === state.aggregationGeneration && !state.scan.started && !state.scan.done) void runBaseline(generation)
+    }, delay)
+    if (state.baselineFallbackTimer && typeof state.baselineFallbackTimer.unref === 'function') state.baselineFallbackTimer.unref()
+  }
+  function scheduleBaselineRetry(generation = state.aggregationGeneration) {
+    if (state.disposed || state.baselineRetryScheduled || state.scan.done || generation !== state.aggregationGeneration) return
+    state.baselineRetryScheduled = true
+    const delay = state.baselineRetryDelay
+    state.baselineRetryDelay = Math.min(state.baselineRetryDelay * 2, 30000)
+    void safeContextTimeout(delay).then((ready) => {
+      if (generation !== state.aggregationGeneration) return undefined
+      state.baselineRetryScheduled = false
+      if (ready && !state.scan.started && !state.scan.done) return runBaseline(generation)
+      if (!ready && !state.disposed) scheduleNativeBaselineRetry(generation, delay)
+      return undefined
+    })
+  }
+  function scanOneSession(sid, record, wsId, generation, snapshots) {
+    return enqueue(sid, async () => {
+      if (state.disposed || generation !== state.aggregationGeneration) return
+      // Held across the awaits below: the resident cache may drop the record while
+      // the session log is being read, and the recovery path still needs it.
+      let loadedRecord
+      let snap
+      try {
+        if (state.sessionSeq.has(sid) && !state.liveResyncPending.has(sid)) return
+        // v1.0.8: when the persisted log revision is unchanged since the last ledger
+        // write, the whole readSession (full event transfer) is skipped — the ledger
+        // record is applied directly and the live feed keeps catching new events.
+        // The record is not resident any more: a cold start enumerates the ledger
+        // keys and every session reads its own document here, on demand.
+        if (state.ledgerRecords.get(sid) === undefined) await host.ledger.recordFor(sid)
+        const previousRecord = state.ledgerRecords.get(sid)
+        loadedRecord = previousRecord
+        const revision = snapshots === null ? undefined : snapshots.get(sid)
+        if (!state.liveResyncPending.has(sid) && previousRecord !== undefined && previousRecord.needsUpgrade !== true && previousRecord.rebuildRequired === undefined && previousRecord.workspaceId === wsId && typeof previousRecord.lastRevision === 'string' && typeof revision === 'string' && revision === previousRecord.lastRevision) {
+          state.sync.sessionsSkippedByRevision += 1
+          applyLedgerRecord(previousRecord, 'ledger-reuse')
+          state.sessionSeq.set(sid, previousRecord.lastSeq)
+          state.sessionCount.add(sid)
+          markStatsChanged('scan')
+          return
+        }
+        state.sync.sessionsRead += 1
+        markStatsChanged('scan')
+        snap = await readSessionSnapshot(sid)
+        if (state.disposed || generation !== state.aggregationGeneration) return
+        if (snap && Array.isArray(snap.events)) {
+          if (state.liveResyncTriggers.has(sid) && !snapshotCoversTriggers(sid, snap.events)) {
+            state.liveResyncPending.add(sid)
+            const saved = state.ledgerRecords.get(sid) !== undefined ? state.ledgerRecords.get(sid) : previousRecord
+            if (!state.sessionSeq.has(sid) && saved !== undefined) {
+              applyLedgerRecord(saved, 'ledger-recovery')
+              state.sessionSeq.set(sid, saved.lastSeq)
+              state.sessionCount.add(sid)
+            }
+            scheduleLiveResync(sid, wsId, generation)
+            return
+          }
+          // v1.0.7: incremental seed — the durable ledger doubles as a per-session
+          // cursor (cc-switch session_log_sync mtime+offset parity). An unchanged
+          // session applies its canonical record directly and never re-folds;
+          // a changed session seeds the previous record once, then folds only the
+          // new tail (previously every listed session was re-read and fully rebuilt).
+          const sequence = sequenceProfile(snap.events)
+          const currentLastSeq = sequence.lastSeq
+          const hasPendingTrigger = state.liveResyncTriggers.has(sid)
+          const previous = hasPendingTrigger ? null : state.ledgerRecords.get(sid) !== undefined ? state.ledgerRecords.get(sid) : previousRecord
+          if (hasPendingTrigger) host.aggregation.removeSession(sid)
+          const canFoldTail = !hasPendingTrigger && previous !== undefined && previous.needsUpgrade !== true && previous.rebuildRequired === undefined && previous.workspaceId === wsId && !sequence.nonMonotonic && !sequence.hasInvalid && previous.lastSeq >= 0 && currentLastSeq > previous.lastSeq
+          if (canFoldTail) {
+            applyLedgerRecord(previous, 'ledger-reuse')
+            foldEvents(wsId, snap.events, previous.lastSeq, sid, 'scan')
+          } else {
+            // A changed revision with no new tail may still contain a replacement;
+            // rebuild from the complete read instead of trusting lastSeq alone.
+            foldEvents(wsId, snap.events, undefined, sid, 'scan')
+          }
+          const ledger = buildLedgerRecord({ id: sid, header: record.header, events: snap.events }, wsId, 'scan', revision, previous, !sequence.hasInvalid)
+          const canonical = ledger === null ? (state.ledgerRecords.get(sid) !== undefined ? state.ledgerRecords.get(sid) : previousRecord) : (canFoldTail ? storeLedgerRecord(ledger) : replaceLedgerRecord(ledger))
+          if (canonical === ledger) {
+            void persistLedgerRecord(ledger)
+          }
+          const observedLastSeq = state.sessionSeq.get(sid)
+          const nextLastSeq = Math.max(currentLastSeq, observedLastSeq === undefined ? -1 : observedLastSeq)
+          state.sessionSeq.set(sid, nextLastSeq)
+          state.sessionCount.add(sid)
+          if (observedLastSeq === undefined || observedLastSeq <= currentLastSeq) cancelLiveResync(sid)
+          else scheduleLiveResync(sid, wsId, generation)
+        }
+      } catch (err) {
+        if (generation !== state.aggregationGeneration) return
+        state.sync.sessionsFailed += 1
+        state.scan.failed += 1
+        noteSyncError('session-read-failed')
+        const saved = state.ledgerRecords.get(sid) !== undefined ? state.ledgerRecords.get(sid) : loadedRecord
+        if (saved !== undefined) {
+          applyLedgerRecord(saved, 'ledger-recovery')
+          if (saved.turns.length > 0 || saved.usage.length > 0) state.sync.sessionsRestoredFromLedger += 1
+          state.sessionSeq.set(sid, -1)
+          state.sessionCount.add(sid)
+        } else {
+          state.sessionSeq.set(sid, -1)
+        }
+      } finally {
+        // The lease is released once the read and the fold are over; the scan
+        // bookkeeping still has to run even if the lease disposal does not.
+        try {
+          releaseSessionSnapshot(snap)
+        } finally {
+          if (generation === state.aggregationGeneration) {
+            state.scan.scanned += 1
+            markStatsChanged('scan')
+          }
+        }
+      }
+    })
+  }
+
+  async function runBaseline(generation = state.aggregationGeneration) {
+    if (state.scan.started || state.disposed || generation !== state.aggregationGeneration) return
+    state.scan.started = true
+    beginSync()
+    await Promise.all([state.ledgerReady, state.pricingReady])
+    if (state.disposed || generation !== state.aggregationGeneration) return
+    let setupFailed = false
+    try {
+      const workspaces = ctx.workspaceRegistry.list()
+      installWorkspaceSnapshot(buildWorkspaceSnapshot(workspaces))
+    } catch (err) {
+      console.error('[all-usage] workspace list failed:', err)
+      setupFailed = true
+      noteSyncError('workspace-list-failed')
+    }
+    let records = null
+    try {
+      records = await ctx.sessionQuery.listSessions()
+    } catch (err) {
+      console.error('[all-usage] session list failed:', err)
+      if (state.disposed || generation !== state.aggregationGeneration) return
+      noteSyncError('session-list-failed')
+    }
+    if (state.disposed || generation !== state.aggregationGeneration) return
+    // v1.0.8: cheap per-session change signal (header line + stat, no full-log read)
+    let snapshots = null
+    try {
+      const revisions = await loadSessionRevisions()
+      if (state.disposed || generation !== state.aggregationGeneration) return
+      if (revisions !== null) {
+        state.sync.persistenceSnapshotsAvailable = true
+        snapshots = revisions
+      }
+    } catch (err) {
+      console.error('[all-usage] session persistence snapshots unavailable:', err)
+      if (state.disposed || generation !== state.aggregationGeneration) return
+      state.sync.persistenceSnapshotsAvailable = false
+      markStatsChanged('scan')
+    }
+    if (state.disposed || generation !== state.aggregationGeneration) return
+    if (setupFailed || !Array.isArray(records)) {
+      // A transient registry failure must not be reported as a completed empty state.scan.
+      state.scan.started = false
+      markStatsChanged('scan')
+      scheduleBaselineRetry(generation)
+      return
+    }
+    state.scan.total = records.length
+    state.sync.sessionsTotal = records.length
+    markStatsChanged('scan')
+    const listedSessionIds = new Set()
+    for (const record of records) {
+      if (record === undefined || record === null || record.header === undefined) continue
+      const sid = record.header.id
+      const cwd = typeof record.header.cwd === 'string' ? record.header.cwd : ''
+      const wsId = workspaceForCwd(cwd)
+      if (sid !== undefined && wsId !== undefined) listedSessionIds.add(sid)
+    }
+    const ledgerKeyList = Array.from(state.ledgerKeys)
+    for (let keyIndex = 0; keyIndex < ledgerKeyList.length; keyIndex += 1) {
+      if (keyIndex % 32 === 0) await host.ledger.loadRecords(ledgerKeyList.slice(keyIndex, keyIndex + 32))
+      const sid = ledgerKeyList[keyIndex]
+      if (listedSessionIds.has(sid)) continue
+      const record = await host.ledger.recordFor(sid)
+      if (record !== undefined && record !== null) {
+        // Recorded usage survives deletion. A session whose workspace, cwd or
+        // log is gone still counts from its ledger row; only legacy synthetic
+        // rows, which never belonged to a registered workspace, stay excluded.
+        if (typeof record.workspaceId === 'string' && record.workspaceId.startsWith('unregistered:')) continue
+        // Usage from a workspace that is no longer registered is summed into the
+        // shared deleted bucket, so history survives without a row per dead
+        // workspace. The stored row keeps its original workspace id and cwd.
+        const retired = typeof record.workspaceId !== 'string' || !state.wsMeta.has(record.workspaceId)
+        const carriesUsage = record.turns.length > 0 || record.usage.length > 0
+        // An empty row must not advertise a bucket that holds nothing.
+        if (retired && carriesUsage) state.retiredBucketUsed = true
+        applyLedgerRecord(retired ? retargetLedgerRecord(record) : record, retired ? 'ledger-retired' : 'ledger-recovery')
+        if (carriesUsage) state.sync.sessionsRestoredFromLedger += 1
+      }
+    }
+    if (state.sync.sessionsRestoredFromLedger > 0) markStatsChanged('scan')
+    // Prefetch a small window of documents so the reads of the sessions the scan is
+    // about to visit overlap the folding work (kept aligned with the records array).
+    const scanIds = records.map((entry) => (entry !== null && entry !== undefined && entry.header !== undefined && typeof entry.header.id === 'string' ? entry.header.id : null))
+    for (let scanIndex = 0; scanIndex < records.length; scanIndex += 1) {
+      const record = records[scanIndex]
+      if (scanIndex % 24 === 0) await host.ledger.loadRecords(scanIds.slice(scanIndex, scanIndex + 24))
+      if (state.disposed || generation !== state.aggregationGeneration) return
+      if (record === undefined || record === null || record.header === undefined) {
+        state.scan.scanned += 1
+        markStatsChanged('scan')
+        continue
+      }
+      const sid = record.header.id
+      const cwd = typeof record.header.cwd === 'string' ? record.header.cwd : ''
+      const wsId = workspaceForCwd(cwd)
+      if (sid === undefined || wsId === undefined) {
+        state.scan.scanned += 1
+        markStatsChanged('scan')
+        continue
+      }
+      listedSessionIds.add(sid)
+      await scanOneSession(sid, record, wsId, generation, snapshots)
+      if (!(await safeContextTimeout(0))) {
+        state.scan.started = false
+        noteSyncError('baseline-yield-unavailable')
+        scheduleBaselineRetry(generation)
+        return
+      }
+    }
+    if (state.disposed || generation !== state.aggregationGeneration) return
+    await drainLedgerWrites()
+    if (state.disposed || generation !== state.aggregationGeneration) return
+    const pricingReconciliation = await host.pricing.reconcileUsageCosts({ backfill: true })
+    if (pricingReconciliation.backfill.priced > 0 || pricingReconciliation.temporal.reconciled > 0) {
+      await drainLedgerWrites()
+      markStatsChanged('pricing')
+    }
+    if (state.disposed || generation !== state.aggregationGeneration) return
+    // Everything above (folding, backfill, temporal reconcile) needs the rows; from
+    // here on they are only needed to render logs, so the settled sessions hand
+    // theirs back to the ledger and are read again on demand.
+    const evicted = host.aggregation.evictColdRows()
+    if (evicted.rows > 0) console.info('[all-usage] dropped ' + evicted.rows + ' resident usage rows from ' + evicted.sessions + ' settled sessions')
+    state.knownSessionIds.clear()
+    for (const sid of listedSessionIds) state.knownSessionIds.add(sid)
+    state.scan.done = true
+    if (state.workspaceSyncDeferred) {
+      state.workspaceSyncDeferred = false
+      scheduleWorkspaceSync()
+    }
+    state.sync.lastCompletedAt = Date.now()
+    if (state.sync.sessionsFailed === 0) {
+      state.sync.lastErrorAt = 0
+      state.sync.lastErrorCode = null
+    }
+    markStatsChanged('scan')
+    if (state.reconcilePending) scheduleReconcileHint()
+  }
+
+  function scheduleWorkspaceSync() {
+    if (state.disposed) return
+    if (state.workspaceSyncTimer !== null) return
+    state.workspaceSyncTimer = setTimeout(() => {
+      state.workspaceSyncTimer = null
+      if (!state.disposed) void runWorkspaceSync()
+    }, WORKSPACE_SYNC_DEBOUNCE_MS)
+    if (state.workspaceSyncTimer && typeof state.workspaceSyncTimer.unref === 'function') state.workspaceSyncTimer.unref()
+  }
+  async function runWorkspaceSync() {
+    if (state.disposed) return
+    if (state.workspaceSyncInFlight) {
+      state.workspaceSyncPending = true
+      return
+    }
+    state.workspaceSyncInFlight = true
+    state.sync.workspaceSyncRuns += 1
+    try {
+      await synchronizeWorkspaceRegistry()
+    } catch (err) {
+      console.error('[all-usage] workspace synchronize failed:', err)
+      noteSyncError('workspace-sync-failed')
+    } finally {
+      state.workspaceSyncInFlight = false
+      if (state.workspaceSyncPending) {
+        state.workspaceSyncPending = false
+        scheduleWorkspaceSync()
+      }
+    }
+  }
+  async function synchronizeWorkspaceRegistry() {
+    if (state.disposed) return
+    // A registry change that lands while a baseline is running used to be
+    // dropped outright, which is why a new workspace could stay invisible until
+    // the next restart. Remember it and re-run once the scan settles.
+    if (!state.scan.done) {
+      state.workspaceSyncDeferred = true
+      state.sync.workspaceSyncDeferred += 1
+      return
+    }
+    let workspaces
+    try {
+      workspaces = ctx.workspaceRegistry.list()
+    } catch (err) {
+      console.error('[all-usage] workspace list failed:', err)
+      noteSyncError('workspace-list-failed')
+      return
+    }
+    const next = buildWorkspaceSnapshot(workspaces)
+    const removedWs = new Set()
+    for (const id of state.wsMeta.keys()) if (!next.wsMeta.has(id)) removedWs.add(id)
+    const addedWs = new Set()
+    for (const id of next.wsMeta.keys()) if (!state.wsMeta.has(id)) addedWs.add(id)
+    for (const id of removedWs) state.retiringWorkspaceIds.add(id)
+    state.sync.workspaceSyncAdded += addedWs.size
+    state.sync.workspaceSyncRemoved += removedWs.size
+    // Reuse path: no membership change — metadata only, zero rescan.
+    if (removedWs.size === 0 && addedWs.size === 0) {
+      installWorkspaceSnapshot(next)
+      return
+    }
+    // Retire path: a deregistered workspace keeps everything it recorded. The
+    // ledger's promise is that flushed usage survives deletion, so sessions are
+    // re-applied under the shared deleted bucket instead of being subtracted and
+    // dropped. New sessions still cannot enter the workspace: pathIndex only
+    // ever carries registered workspaces, so workspaceForCwd() no longer
+    // resolves its cwd and the scan skips it.
+    if (removedWs.size > 0) {
+      const retiredSids = new Set()
+      for (const sid of state.ledgerKeys) {
+        const record = await host.ledger.recordFor(sid)
+        if (record === null || record === undefined || !removedWs.has(record.workspaceId)) continue
+        retiredSids.add(sid)
+      }
+      for (const [sid, id] of state.memberOf) if (removedWs.has(id)) retiredSids.add(sid)
+      let moved = 0
+      for (const sid of retiredSids) {
+        if (typeof sid !== 'string' || sid === '') continue
+        // retargetSession() walks the session's rows: bring back any that were
+        // dropped from memory, or the workspace split would keep the old bucket.
+        if (typeof host.ledger.loadRowsForSession === 'function') await host.ledger.loadRowsForSession(sid)
+        // Re-key the live aggregate first: usage folded from the feed but not yet
+        // persisted has no ledger row to replay, and a session the registry no
+        // longer lists is never re-scanned afterwards.
+        moved += host.aggregation.retargetSession(sid, RETIRED_WORKSPACE_ID)
+        const record = state.ledgerRecords.get(sid)
+        // Keep the in-memory record aligned with the aggregate; the persisted row
+        // keeps its original workspace id and cwd, so recovery re-derives this.
+        if (record !== undefined && (record.turns.length > 0 || record.usage.length > 0)) moved += 1
+        if (record !== undefined) state.ledgerRecords.set(sid, retargetLedgerRecord(record))
+      }
+      if (moved > 0) state.retiredBucketUsed = true
+    }
+    installWorkspaceSnapshot(next)
+    // Add path: scan only the sessions that belong to newly registered workspaces.
+    if (addedWs.size === 0) return
+    let records = null
+    try {
+      records = await ctx.sessionQuery.listSessions()
+    } catch (err) {
+      console.error('[all-usage] session list failed:', err)
+      noteSyncError('session-list-failed')
+    }
+    if (!Array.isArray(records)) return
+    state.sync.sessionsTotal = records.length
+    markStatsChanged('scan')
+    let snapshots = null
+    try {
+      snapshots = await loadSessionRevisions()
+    } catch (err) {
+      console.error('[all-usage] session persistence snapshots unavailable:', err)
+    }
+    for (const record of records) {
+      if (state.disposed) return
+      if (record === undefined || record === null || record.header === undefined) continue
+      const sid = record.header.id
+      const cwd = typeof record.header.cwd === 'string' ? record.header.cwd : ''
+      const wsId = workspaceForCwd(cwd)
+      if (sid === undefined || wsId === undefined) continue
+      if (!addedWs.has(wsId)) continue
+      state.knownSessionIds.add(sid)
+      scanOneSession(sid, record, wsId, state.aggregationGeneration, snapshots)
+    }
+  }
+
+  function sessionIdsFromRecords(records) {
+    const ids = new Set()
+    for (const record of records) {
+      if (record === undefined || record === null || record.header === undefined) continue
+      const sid = record.header.id
+      const cwd = typeof record.header.cwd === 'string' ? record.header.cwd : ''
+      const wsId = workspaceForCwd(cwd)
+      if (sid !== undefined && wsId !== undefined) ids.add(sid)
+    }
+    return ids
+  }
+  async function reconcileSessions() {
+    if (state.disposed || state.reconcileInFlight || !state.scan.done) return
+    state.reconcilePending = false
+    state.reconcileInFlight = true
+    try {
+      const records = await ctx.sessionQuery.listSessions()
+      if (state.disposed || !Array.isArray(records)) return
+      const currentIds = sessionIdsFromRecords(records)
+      let removed = false
+      for (const sid of state.knownSessionIds) {
+        if (!currentIds.has(sid)) { removed = true; break }
+      }
+      if (removed && !state.disposed && state.scan.done) {
+        console.info('[all-usage] session removal detected; rebuilding usage index')
+        const generation = resetAggregationState()
+        void runBaseline(generation)
+        return
+      }
+      state.knownSessionIds.clear()
+      for (const sid of currentIds) state.knownSessionIds.add(sid)
+    } catch (err) {
+      console.error('[all-usage] session reconciliation failed:', err)
+      noteSyncError('session-reconcile-failed')
+    } finally {
+      state.reconcileInFlight = false
+      if (state.reconcilePending && !state.disposed) scheduleReconcileHint()
+    }
+  }
+  function scheduleReconcileHint() {
+    if (state.disposed) return
+    state.reconcilePending = true
+    if (state.reconcileHintScheduled || state.reconcileInFlight) return
+    state.reconcileHintScheduled = true
+    const generation = state.aggregationGeneration
+    void safeContextTimeout(RECONCILE_HINT_DELAY_MS).then((ready) => {
+      if (generation !== state.aggregationGeneration) return
+      state.reconcileHintScheduled = false
+      if (ready && !state.disposed) void reconcileSessions()
+    }, () => {
+      if (generation === state.aggregationGeneration) state.reconcileHintScheduled = false
+    })
+  }
+  function scheduleReconcileTimer() {
+    if (state.disposed || state.reconcileTimer !== null) return
+    state.reconcileTimer = setTimeout(() => {
+      state.reconcileTimer = null
+      if (!state.disposed) {
+        void reconcileSessions()
+        scheduleReconcileTimer()
+      }
+    }, RECONCILE_INTERVAL_MS)
+    if (state.reconcileTimer && typeof state.reconcileTimer.unref === 'function') state.reconcileTimer.unref()
+  }
+  // Belt and braces for the registry probe: the event fast path can be missed
+  // (dropped while scanning, or never delivered), and unlike the event this
+  // cannot silently leave the workspace list stale until a restart.
+  function scheduleWorkspaceProbeTimer() {
+    if (state.disposed || state.workspaceProbeTimer !== null) return
+    state.workspaceProbeTimer = setTimeout(() => {
+      state.workspaceProbeTimer = null
+      if (!state.disposed) {
+        void runWorkspaceSync()
+        scheduleWorkspaceProbeTimer()
+      }
+    }, WORKSPACE_PROBE_INTERVAL_MS)
+    if (state.workspaceProbeTimer && typeof state.workspaceProbeTimer.unref === 'function') state.workspaceProbeTimer.unref()
+  }
+
+  // ---------- live feed ----------
+  ctx.on('session/event', (session, event) => {
+    if (state.disposed) return
+    if (event === undefined || event === null) return
+    const type = event.type
+    if (type !== 'turn/end' && type !== 'assistant/message' && type !== 'assistant/chunk' && type !== 'request/context' && type !== 'request/header') return
+    const sid = session && session.id
+    if (typeof sid !== 'string') return
+    markLedgerDirty(sid)
+    const wsId = wsForLiveSession(session, sid)
+    if (wsId === undefined) return
+    const generation = state.aggregationGeneration
+    state.knownSessionIds.add(sid)
+    enqueue(sid, () => processLiveEvent(sid, wsId, event, generation))
+  })
+  ctx.on('session/flush', async (session) => {
+    if (state.disposed || session === null || typeof session !== 'object' || typeof session.id !== 'string') return
+    const sid = session.id
+    // Flush changes the same record as live resync and pricing. Serialize the
+    // complete read/build/write checkpoint with those mutations.
+    return enqueue(sid, async () => {
+      if (state.disposed) return
+      const previous = state.ledgerRecords.get(sid) !== undefined ? state.ledgerRecords.get(sid) : await host.ledger.recordFor(sid)
+      const eventList = sessionEvents(session)
+      // DSH sequences events with seq === log index: the tail event gives the
+      // latest sequence in O(1) without scanning a 500K-event session twice.
+      const tailEvent = eventList.length > 0 ? eventList[eventList.length - 1] : null
+      const currentLastSeq = tailEvent !== null && Number.isSafeInteger(tailEvent.seq) && tailEvent.seq >= 0 ? tailEvent.seq : lastSeqOf(eventList)
+      const hasNewEvents = state.ledgerDirtySessions.has(sid) || state.ledgerWriteFailedSessions.has(sid) || (previous === undefined && currentLastSeq >= 0) || (previous !== undefined && currentLastSeq > previous.lastSeq)
+      if (!hasNewEvents) return
+      const dirtyEpoch = state.ledgerDirtyEpochs.get(sid) || 0
+      await Promise.all([state.ledgerReady, state.pricingReady])
+      if (state.disposed) return
+      const wsId = wsForLiveSession(session, sid)
+      if (wsId === undefined) return
+      // Any dirty flush whose log contains invalid sequences may have rewritten
+      // history (even when a new tail was appended) or carries contract-external
+      // events; refuse to fold it and rebuild the whole usage index instead, so
+      // the in-memory aggregate and the persisted ledger cannot disagree.
+      if (previous !== undefined && eventList.length > 0) {
+        const sequence = sequenceProfile(eventList)
+        if (sequence.hasInvalid) {
+          if (state.scan.done && !state.disposed) {
+            console.info('[all-usage] invalid sequences in flushed log; rebuilding usage index')
+            // Persist the rebuild flag so the baseline cannot fast-path the stale
+            // record (the persistence revision may still match a lagging log).
+            const current = state.ledgerRecords.get(sid)
+            if (current !== undefined) {
+              current.rebuildRequired = 'invalid-flush-sequence'
+              current.needsUpgrade = true
+              void persistLedgerRecord(current)
+            }
+            const generation = resetAggregationState()
+            void runBaseline(generation)
+          }
+          return
+        }
+      }
+      const ledger = buildLedgerRecord(session, wsId, 'flush', undefined, previous)
+      if (ledger === null) return
+      const canonical = storeLedgerRecord(ledger)
+      if (canonical === ledger) {
+        const persisted = persistLedgerRecord(ledger)
+        // This is an explicit checkpoint; bypass the background debounce.
+        await drainLedgerWrites()
+        await persisted
+      }
+      if (state.ledgerDirtyEpochs.get(sid) === dirtyEpoch) {
+        state.ledgerDirtySessions.delete(sid)
+        state.ledgerDirtyEpochs.delete(sid)
+      }
+    })
+  })
+  ctx.on('session/disposed', () => {
+    if (!state.disposed) scheduleReconcileHint()
+  })
+  // Workspace registry probe: DSH emits domain/changed after every durable
+  // workspace-domain write (create/delete/rename/reorder/archive/attach/detach).
+  // On any such change we re-read workspaceRegistry.list() and, when membership
+  // changed, rescan only the affected workspaces — unchanged ones keep their
+  // computed aggregates and ledger untouched.
+  ctx.on('domain/changed', (change) => {
+    if (state.disposed) return
+    if (change === undefined || change === null) return
+    if (change.domain !== 'workspace') return
+    if (change.table !== 'workspaces' && change.table !== '') return
+    state.sync.workspaceProbeEvents += 1
+    scheduleWorkspaceSync()
+  })
+
+  return {
+    foldEvent,
+    foldEvents,
+    lastSeqOf,
+    sequenceProfile,
+    enqueue,
+    wsForLiveSession,
+    cancelLiveResync,
+    scheduleLiveResync,
+    foldLiveFallback,
+    syncLiveSession,
+    resyncLiveSession,
+    processLiveEvent,
+    scheduleNativeBaselineRetry,
+    scheduleBaselineRetry,
+    runBaseline,
+    synchronizeWorkspaceRegistry,
+    scheduleWorkspaceSync,
+    sessionIdsFromRecords,
+    reconcileSessions,
+    scheduleReconcileHint,
+    scheduleReconcileTimer,
+    scheduleWorkspaceProbeTimer,
+    markLedgerDirty
+  }
+}