dsh-all-usage 1.0.8 → 1.0.9

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to `dsh-all-usage` are documented here.
 
+## [1.0.9] - 2026-08-26
+
+### Added
+
+- Added a lightweight, guarded `/api/all-usage/status` contract with a per-Host instance ID, monotonic stats revision, scan progress, and non-sensitive sync-health counters.
+- Added sync-health visibility for revision-skipped sessions, actual log reads, ledger-only recoveries, failures, persistence snapshot availability, and last completed baseline time.
+- Added revision-driven Client refresh: after the initial scan, the dashboard polls only lightweight status and fetches the full historical snapshot only when the Host instance or stats revision changes.
+
+### Fixed
+
+- Preserved the last successful usage view after status or full-snapshot failures, exposed a retry action, and added bounded retry backoff instead of silently discarding refresh errors.
+
 ## [1.0.8] - 2026-08-23
 
 ### Added
@@ -62,6 +74,7 @@ All notable changes to `dsh-all-usage` are documented here.
 - Allowed same-origin browser balance GET requests that omit `Origin` while retaining token protection.
 - Standardized English date buckets, range filters, streaks, heatmap dates, and export timestamps on UTC.
 
+[1.0.9]: https://github.com/ParticleLight/dsh-all-usage/releases/tag/v1.0.9
 [1.0.8]: https://github.com/ParticleLight/dsh-all-usage/releases/tag/v1.0.8
 [1.0.7]: https://github.com/ParticleLight/dsh-all-usage/releases/tag/v1.0.7
 [1.0.6]: https://github.com/ParticleLight/dsh-all-usage/releases/tag/v1.0.6

package/README.md

@@ -19,14 +19,15 @@ DeepSeek Harness 全量用量看板：按模型、供应商、工作区和时间
 - **界面语言**：在看板顶部切换中文与 English；选择会保存到浏览器本地
 - **完整历史与增量重建**：基线扫描全部可读历史会话；独立用量账本同时作为每会话游标——未变化的会话直接复用账本，新增事件只增量回填，长历史重启不再全量重建
 - **重启免读**：用持久化日志的 revision 作为每会话的变更信号（只读头部行 + stat，不读全量）——日志未变的会话重启时连事件都不读，直接从账本复用；仅日志变化（新增/修改）的会话才做增量读取
+- **数据健康与按需刷新**：扫描完成后浏览器只检查轻量状态版本，只有用量、别名或同步状态变化时才拉完整历史；显示本次数据更新时间、历史扫描健康、revision 免读、实际读取、账本恢复和失败，网络异常保留上次成功数据并可重试
 - **Token 口径**：输入按「未含缓存命中」计，缓存命中 / 写入与推理独立成桶；全 0 用量的重放事件不会覆盖已记录的真实用量，仅缓存命中的请求也会计入
 
 ### 最近更新
 
-**v1.0.8**
+**v1.0.9**
 
-- 重启免读：用持久化日志的 revision 做每会话变更信号，未变化会话重启时完全不读事件，直接复用账本；仅在日志变化时增量读取
-- 账本记录持久化每会话的日志 revision（旧记录首次重读后自动回填）
+- 按需刷新：扫描完成后只轮询轻量状态，Host instance 或统计 revision 变化时才拉完整历史快照
+- 数据健康：显示本次数据更新时间与历史扫描健康，以及 revision 免读、实际读取、账本恢复、失败与优化可用性；刷新失败保留上次成功数据并支持重试
 
 完整版本记录见 [CHANGELOG.md](CHANGELOG.md)。
 
@@ -81,6 +82,7 @@ dsh plugin --profile web add github:ParticleLight/dsh-all-usage
 - 会话删除后，已成功 flush 的用量仍从独立账本恢复；会话销毁提示和周期对账只负责触发重建，不会删除账本记录
 - 同一会话的同一 `turn / step` 只保留一份最终 usage；重试或替换消息会替换旧贡献，不重复累计
 - 输入 Token 按「未含缓存命中」计（缓存命中 / 写入独立成桶）；全 0 用量的重放事件不会覆盖已记录的真实用量，纯缓存命中的请求仍会计入
+- 轻量状态接口只公开 Host 实例、统计 revision、扫描进度与同步计数，不公开会话 ID、工作区路径、提示词或回复正文；完整快照仅在状态变化或手动刷新时获取
 - 看板中的总处理量 = 输入 + 输出 + 缓存读写 + 推理；缓存命中表示复用的上下文 Token，不等于新生成 Token 或实际费用
 - 余额查询走 DeepSeek 官方 `/user/balance` 接口；未配置 API Key 时卡片显示引导文案
 - 仅统计能归属到已注册工作区（按会话 cwd 匹配）的会话
@@ -105,14 +107,15 @@ A full usage dashboard for DeepSeek Harness. Analyze tokens, cache behavior, acc
 - **Interface language**: switch between Chinese and English from the dashboard header; your choice persists locally in the browser
 - **Full history & incremental rebuild**: the baseline scans every readable historical session; the durable usage ledger doubles as a per-session cursor, so unchanged sessions are reused straight from the ledger and only newly appended events are folded — long histories restart without a full rebuild
 - **Restart with no re-read**: the persisted log revision (a header-line + stat via `sessionPersistence.listSnapshots()`) acts as a per-session change signal — sessions whose log is unchanged are applied from the ledger on restart without reading their events at all; only changed/new sessions are read incrementally
+- **Data health and on-demand refresh**: after a scan completes, the browser polls only a lightweight status revision and fetches full history only after usage, alias, or sync state changes; it shows the latest full-data update, historical scan health, revision skips, rereads, ledger recovery, and failures while preserving last-good data on network errors
 - **Token accounting semantics**: input tokens are fresh (exclude cache hits/writes, which sit in separate buckets along with reasoning); all-zero usage replays never overwrite recorded usage, while cache-only requests still count
 
 ### Latest Update
 
-**v1.0.8**
+**v1.0.9**
 
-- Restart with no re-read: the persisted log revision acts as a per-session change signal, so unchanged sessions are applied from the ledger on restart without reading any events; only changed logs are read incrementally
-- The ledger now stores each session's log revision; existing rows are re-read once and backfilled automatically
+- On-demand refresh: after the scan completes, the dashboard polls lightweight status and fetches full history only when the Host instance or stats revision changes
+- Data health: latest full-data update, historical scan health, revision skips, rereads, ledger recovery, failures, and optimization availability are visible; failed refreshes keep last-good data and expose retry
 
 See [CHANGELOG.md](CHANGELOG.md) for the complete version history.
 
@@ -161,6 +164,7 @@ The profile patch layer hot-reloads; save the file and refresh the page.
 - After a session is deleted, successfully flushed usage is restored from the separate ledger; disposal hints and periodic reconciliation trigger rebuilds without deleting ledger rows
 - For each session and logical `turn / step`, only the final usage contribution is kept; retries or replaced messages do not double-count
 - Input tokens are fresh (exclude cache hits/writes, which sit in their own buckets); all-zero usage replays do not overwrite recorded usage and pure cache-read requests still count
+- The lightweight status endpoint exposes only Host instance, stats revision, scan progress, and sync counters. It does not expose session IDs, workspace paths, prompts, or reply bodies; full snapshots are fetched only after status changes or a manual refresh
 - Processed tokens = input + output + cache read/write + reasoning; a cache hit means reused context, not newly generated tokens or actual cost
 - Balance data comes from DeepSeek’s official `/user/balance` endpoint; the card shows guidance when no API key is configured
 - English mode uses UTC for date buckets, range filters, streaks, heatmap dates, and export timestamps; Chinese mode uses local time

package/lib/client.js

@@ -58,6 +58,25 @@ window.__ModuleLoader__.load({
         isCurrent(seq) { return seq === latest },
       }
     }
+    function snapshotVersion(data) {
+      if (data === null || typeof data !== 'object') return null
+      const instanceId = typeof data.instanceId === 'string' ? data.instanceId : ''
+      const revision = typeof data.revision === 'number' && Number.isFinite(data.revision) ? data.revision : null
+      return instanceId === '' || revision === null ? null : instanceId + ':' + revision
+    }
+    function statusRequiresFullSnapshot(status, snapshot) {
+      if (status === null || typeof status !== 'object' || snapshot === null || typeof snapshot !== 'object') return true
+      const statusVersion = snapshotVersion(status)
+      const snapshotVersionValue = snapshotVersion(snapshot)
+      if (statusVersion === null || snapshotVersionValue === null || statusVersion !== snapshotVersionValue) return true
+      const statusScan = status.scan
+      const snapshotScan = snapshot.scan
+      return !!(statusScan && snapshotScan && !!statusScan.done !== !!snapshotScan.done)
+    }
+    function retryDelayFor(failures) {
+      const count = Math.max(1, Math.min(4, typeof failures === 'number' && Number.isFinite(failures) ? failures : 1))
+      return 5000 * Math.pow(2, count - 1)
+    }
     function rangeFilenamePart(range, customRange, utc) {
       if (range !== 'custom') return range
       const normalized = normalizeCustomRange(customRange, utc)
@@ -327,6 +346,9 @@ window.__ModuleLoader__.load({
 .uh-alias-ok:active { transform:scale(.96); }
 .uh-anim-panel { animation:uh-panel-in .28s ease both; }
 .uh-progress { font-size:12px; color:var(--dsw-alias-label-secondary); display:flex; align-items:center; gap:10px; }
+.uh-sync-health { margin-top:8px; padding:8px 12px; display:flex; align-items:center; flex-wrap:wrap; gap:6px; border:1px solid var(--dsw-alias-border-l1); border-radius:10px; color:var(--dsw-alias-label-secondary); background:var(--dsw-alias-bg-layer-1); font-size:11px; line-height:1.45; }
+.uh-sync-health.uh-stale { color:var(--dsw-alias-warning, #a55b00); border-color:color-mix(in srgb, var(--dsw-alias-warning, #d9822b) 45%, var(--dsw-alias-border-l1)); }
+.uh-sync-retry { border:0; background:transparent; color:inherit; font:inherit; text-decoration:underline; cursor:pointer; padding:0 2px; }
 .uh-bar { flex:1; height:6px; border-radius:3px; background:var(--dsw-alias-bg-layer-2); overflow:hidden; max-width:340px; }
 .uh-fill { height:100%; background:var(--dsw-alias-brand-primary); border-radius:3px; transition:width .3s ease; }
 .uh-cards { display:grid; grid-template-columns:repeat(auto-fit, minmax(200px, 1fr)); gap:10px; }
@@ -496,6 +518,10 @@ window.__ModuleLoader__.load({
       if (!r.ok) throw new Error('HTTP ' + r.status)
       return r.json()
     })
+    const getStatus = () => fetch('/api/all-usage/status', { headers: { accept: 'application/json' } }).then((r) => {
+      if (!r.ok) throw new Error('HTTP ' + r.status)
+      return r.json()
+    })
     const getBalance = (force, requestToken) => fetch('/api/all-usage/balance' + (force ? '?force=1' : ''), { headers: { accept: 'application/json', 'x-all-usage-request-token': requestToken } }).then((r) => {
       if (!r.ok) throw new Error('HTTP ' + r.status)
       return r.json()
@@ -525,6 +551,9 @@ window.__ModuleLoader__.load({
       const calendarNow = new Date()
       const latestCalendarDate = fmtDate(calendarNow, useUtc)
       const [stats, setStats] = React.useState(null)
+      const [status, setStatus] = React.useState(null)
+      const [statsError, setStatsError] = React.useState('')
+      const [lastStatsAt, setLastStatsAt] = React.useState(0)
       const [balance, setBalance] = React.useState(null)
       const [range, setRange] = React.useState('90d')
       const [customRange, setCustomRange] = React.useState({ start: '', end: '' })
@@ -539,9 +568,12 @@ window.__ModuleLoader__.load({
       const languageMenuRef = React.useRef(null)
       const statsGateRef = React.useRef(null)
       if (statsGateRef.current === null) statsGateRef.current = createRequestGate()
+      const statusGateRef = React.useRef(null)
+      if (statusGateRef.current === null) statusGateRef.current = createRequestGate()
       const balanceGateRef = React.useRef(null)
       if (balanceGateRef.current === null) balanceGateRef.current = createRequestGate()
       const statsGate = statsGateRef.current
+      const statusGate = statusGateRef.current
       const balanceGate = balanceGateRef.current
       const refreshRef = React.useRef(() => {})
       const setLanguage = (next) => { if (typeof props.onLanguageChange === 'function') props.onLanguageChange(next === 'en' ? 'en' : 'zh') }
@@ -551,6 +583,16 @@ window.__ModuleLoader__.load({
         let alive = true
         let scanDone = false
         let requestToken = ''
+        let appliedSnapshot = null
+        let fullFailures = 0
+        let statusFailures = 0
+        let retryTimer = null
+        const clearRetry = () => {
+          if (retryTimer !== null) {
+            clearTimeout(retryTimer)
+            retryTimer = null
+          }
+        }
         const refreshBalance = (force) => {
           if (requestToken === '') return
           const seq = balanceGate.next()
@@ -559,24 +601,84 @@ window.__ModuleLoader__.load({
             if (data) setBalance(data)
           }, () => {})
         }
+        const scheduleRetry = (kind) => {
+          if (!alive || retryTimer !== null) return
+          const failures = kind === 'full' ? (fullFailures += 1) : (statusFailures += 1)
+          retryTimer = setTimeout(() => {
+            retryTimer = null
+            if (!alive) return
+            if (kind === 'full') refreshStats()
+            else refreshStatus()
+          }, retryDelayFor(failures))
+        }
         const refreshStats = () => {
+          statusGate.next()
           const seq = statsGate.next()
           getStats().then((data) => {
             if (!alive || !statsGate.isCurrent(seq)) return
-            if (data && data.scan) scanDone = !!data.scan.done
-            const nextToken = data && typeof data.requestToken === 'string' ? data.requestToken : ''
+            if (data === null || typeof data !== 'object') {
+              setStatsError('full')
+              scheduleRetry('full')
+              return
+            }
+            appliedSnapshot = data
+            if (data.scan) scanDone = !!data.scan.done
+            const nextToken = typeof data.requestToken === 'string' ? data.requestToken : ''
             const tokenChanged = nextToken !== '' && nextToken !== requestToken
             requestToken = nextToken
+            fullFailures = 0
+            clearRetry()
+            setStatsError('')
+            setLastStatsAt(Date.now())
+            setStatus(data)
             setStats(data)
             if (tokenChanged) refreshBalance(false)
-          }, () => {})
+          }, () => {
+            if (!alive || !statsGate.isCurrent(seq)) return
+            setStatsError('full')
+            scheduleRetry('full')
+          })
+        }
+        const refreshStatus = () => {
+          if (appliedSnapshot === null) { refreshStats(); return }
+          const seq = statusGate.next()
+          getStatus().then((data) => {
+            if (!alive || !statusGate.isCurrent(seq)) return
+            if (data === null || typeof data !== 'object') {
+              setStatsError('status')
+              scheduleRetry('status')
+              return
+            }
+            statusFailures = 0
+            const requiresFullSnapshot = statusRequiresFullSnapshot(data, appliedSnapshot)
+            if (data.scan) scanDone = !!data.scan.done
+            // Do not render a newer status beside an older full snapshot. A full
+            // fetch owns the state transition when instance/revision diverges.
+            if (requiresFullSnapshot) {
+              refreshStats()
+              return
+            }
+            setStatus(data)
+            clearRetry()
+            setStatsError('')
+          }, () => {
+            if (!alive || !statusGate.isCurrent(seq)) return
+            setStatsError('status')
+            scheduleRetry('status')
+          })
         }
         refreshStats()
-        const fast = timer.interval(() => { if (!scanDone) refreshStats() }, 2000)
-        const slow = timer.interval(() => { if (scanDone) refreshStats() }, 15000)
+        const fast = timer.interval(() => { if (!scanDone && retryTimer === null) refreshStats() }, 2000)
+        const slow = timer.interval(() => { if (scanDone && retryTimer === null) refreshStatus() }, 15000)
         const bal = timer.interval(() => { refreshBalance(false) }, 60000)
-        refreshRef.current = () => { refreshStats(); refreshBalance(true) }
-        return () => { alive = false; fast(); slow(); bal() }
+        refreshRef.current = () => {
+          clearRetry()
+          fullFailures = 0
+          statusFailures = 0
+          refreshStats()
+          refreshBalance(true)
+        }
+        return () => { alive = false; clearRetry(); fast(); slow(); bal() }
       }, [])
 
       React.useEffect(() => {
@@ -622,12 +724,23 @@ window.__ModuleLoader__.load({
       const animatedTurns = useCountUp(agg.totals.turns, timer)
 
       if (stats === null) {
+        const failed = statsError !== ''
         return React.createElement('div', { className: 'uh-page' },
-          React.createElement('div', { className: 'uh-panel' }, React.createElement('div', { className: 'uh-empty' }, tr('正在加载用量统计…', 'Loading usage statistics…'))),
+          React.createElement('div', { className: 'uh-panel' },
+            React.createElement('div', { className: 'uh-empty' }, failed
+              ? tr('无法加载用量统计。请重试。', 'Unable to load usage statistics. Please retry.')
+              : tr('正在加载用量统计…', 'Loading usage statistics…'),
+            ),
+            failed ? React.createElement('div', { style: { textAlign: 'center' } },
+              React.createElement('button', { className: 'uh-refresh', onClick: onRefresh }, React.createElement(LineIcon, { name: 'refresh', size: 14 }), tr('重试', 'Retry')),
+            ) : null,
+          ),
         )
       }
 
-      const scan = stats.scan || { done: true, started: true, scanned: 0, total: 0, failed: 0 }
+      const statusPayload = status !== null && typeof status === 'object' ? status : stats
+      const scan = statusPayload && statusPayload.scan ? statusPayload.scan : (stats.scan || { done: true, started: true, scanned: 0, total: 0, failed: 0 })
+      const sync = statusPayload && statusPayload.sync ? statusPayload.sync : (stats.sync || {})
       const workspaces = Array.isArray(stats.workspaces) ? stats.workspaces : []
       const aliases = stats.aliases && typeof stats.aliases === 'object' ? stats.aliases : {}
       const wsById = new Map()
@@ -985,6 +1098,25 @@ window.__ModuleLoader__.load({
       const scanning = !scan.done
       const pct = scan.total > 0 ? Math.min(100, Math.round((scan.scanned / scan.total) * 100)) : 40
       const isEmpty = scan.done && dayRows.length === 0 && stats.totals.turns === 0
+      const syncCompletedAt = typeof sync.lastCompletedAt === 'number' && sync.lastCompletedAt > 0 ? new Date(sync.lastCompletedAt).toLocaleString(language === 'en' ? 'en-US' : 'zh-CN') : ''
+      const lastStatsText = lastStatsAt > 0 ? new Date(lastStatsAt).toLocaleString(language === 'en' ? 'en-US' : 'zh-CN') : ''
+      const healthTitle = syncCompletedAt === '' ? undefined : (language === 'en' ? 'Historical scan completed ' + syncCompletedAt : '历史扫描完成于 ' + syncCompletedAt)
+      const healthText = language === 'en'
+        ? (lastStatsText !== '' ? 'Updated ' + lastStatsText : (scanning ? 'Refreshing data' : 'Update state pending'))
+          + ' · ' + (sync.sessionsSkippedByRevision || 0) + ' revision reused'
+          + ' · ' + (sync.sessionsRead || 0) + ' read'
+          + ((sync.sessionsRestoredFromLedger || 0) > 0 ? ' · ' + sync.sessionsRestoredFromLedger + ' ledger restored' : '')
+          + ((sync.sessionsFailed || 0) > 0 ? ' · ' + sync.sessionsFailed + ' failed' : '')
+          + ' · ' + (sync.persistenceSnapshotsAvailable === true ? 'revision optimization on' : 'full-read fallback')
+        : (lastStatsText !== '' ? '已更新 ' + lastStatsText : (scanning ? '正在更新数据' : '数据更新准备中'))
+          + ' · revision 复用 ' + (sync.sessionsSkippedByRevision || 0)
+          + ' · 实际读取 ' + (sync.sessionsRead || 0)
+          + ((sync.sessionsRestoredFromLedger || 0) > 0 ? ' · 账本恢复 ' + sync.sessionsRestoredFromLedger : '')
+          + ((sync.sessionsFailed || 0) > 0 ? ' · 失败 ' + sync.sessionsFailed : '')
+          + ' · ' + (sync.persistenceSnapshotsAvailable === true ? '免读优化已启用' : '全量读取回退')
+      const staleText = statsError === '' ? '' : (language === 'en'
+        ? 'Usage data may be stale' + (lastStatsText !== '' ? '; last full update ' + lastStatsText : '')
+        : '用量数据可能已过期' + (lastStatsText !== '' ? '；上次完整更新 ' + lastStatsText : ''))
 
       return React.createElement('div', { className: 'uh-page' },
         React.createElement('div', { className: 'uh-head' },
@@ -1049,6 +1181,11 @@ window.__ModuleLoader__.load({
           React.createElement('span', {}, language === 'en' ? 'Scanning historical sessions: ' + scan.scanned + ' / ' + scan.total + (scan.failed > 0 ? ' (' + scan.failed + ' failed to read)' : '') : '正在统计历史会话 ' + scan.scanned + ' / ' + scan.total + (scan.failed > 0 ? '（' + scan.failed + ' 个读取失败）' : '')),
           React.createElement('div', { className: 'uh-bar' }, React.createElement('div', { className: 'uh-fill', style: { width: pct + '%' } })),
         ) : null,
+        React.createElement('div', { className: 'uh-sync-health' + (staleText !== '' ? ' uh-stale' : ''), title: staleText !== '' ? undefined : healthTitle },
+          React.createElement(LineIcon, { name: staleText !== '' ? 'refresh' : 'clock', size: 14 }),
+          React.createElement('span', {}, staleText !== '' ? staleText : healthText),
+          staleText !== '' ? React.createElement('button', { className: 'uh-sync-retry', onClick: onRefresh }, tr('重试', 'Retry')) : null,
+        ),
         isEmpty ? React.createElement('div', { className: 'uh-panel' },
           React.createElement('div', { className: 'uh-empty' }, tr('还没有使用记录。开始对话后，这里会点亮。', 'No usage recorded yet. This area will light up after you start a conversation.')),
         ) : React.createElement(React.Fragment, null,
@@ -1189,10 +1326,11 @@ window.__ModuleLoader__.load({
     exports.inject = ['timer', 'slots']
     exports.apply = (ctx) => {
       const slots = ctx.get('slots')
-      if (slots === undefined) return
+      const timer = ctx.get('timer')
+      if (slots === undefined || timer === undefined) return
       slots.inject('sidebar.footer.action', () => slots.register(
         { name: 'sidebar.footer.action', id: 'all-usage', order: 10 },
-        (props) => React.createElement(UsageSidebarEntry, { wide: props.wide, timerCtx: ctx }),
+        (props) => React.createElement(UsageSidebarEntry, { wide: props.wide, timerCtx: timer }),
       ))
     }
     return module.exports;

package/lib/index.js

@@ -102,6 +102,23 @@ function apply(ctx) {
   let aliasWriteChain = Promise.resolve()
   let balanceCache = { fetchedAt: 0, payload: null }
   const requestToken = randomBytes(32).toString('base64url')
+  // A non-secret identity distinguishes HMR/restart revision resets from a stale page.
+  const instanceId = randomBytes(12).toString('base64url')
+  let statsRevision = 0
+  let statsUpdatedAt = Date.now()
+  let statsDirtyScheduled = false
+  const sync = {
+    lastStartedAt: 0,
+    lastCompletedAt: 0,
+    lastErrorAt: 0,
+    lastErrorCode: null,
+    persistenceSnapshotsAvailable: false,
+    sessionsTotal: 0,
+    sessionsRead: 0,
+    sessionsSkippedByRevision: 0,
+    sessionsRestoredFromLedger: 0,
+    sessionsFailed: 0,
+  }
   const ledgerRecords = new Map()
   let ledgerUnit = null
   let ledgerReady = Promise.resolve()
@@ -132,6 +149,55 @@ function apply(ctx) {
   function num(v) {
     return typeof v === 'number' && Number.isFinite(v) ? v : 0
   }
+  // Coalesce synchronous aggregation writes without adding a timer lifecycle.
+  function markStatsChanged() {
+    if (disposed || statsDirtyScheduled) return
+    statsDirtyScheduled = true
+    const flush = () => {
+      statsDirtyScheduled = false
+      if (disposed) return
+      statsRevision += 1
+      statsUpdatedAt = Date.now()
+    }
+    if (typeof queueMicrotask === 'function') queueMicrotask(flush)
+    else Promise.resolve().then(flush)
+  }
+  function resetSyncState() {
+    sync.lastStartedAt = 0
+    sync.lastCompletedAt = 0
+    sync.lastErrorAt = 0
+    sync.lastErrorCode = null
+    sync.persistenceSnapshotsAvailable = false
+    sync.sessionsTotal = 0
+    sync.sessionsRead = 0
+    sync.sessionsSkippedByRevision = 0
+    sync.sessionsRestoredFromLedger = 0
+    sync.sessionsFailed = 0
+  }
+  function beginSync() {
+    resetSyncState()
+    sync.lastStartedAt = Date.now()
+    markStatsChanged()
+  }
+  function noteSyncError(code) {
+    sync.lastErrorAt = Date.now()
+    sync.lastErrorCode = code
+    markStatsChanged()
+  }
+  function syncSnapshot() {
+    return {
+      lastStartedAt: sync.lastStartedAt,
+      lastCompletedAt: sync.lastCompletedAt,
+      lastErrorAt: sync.lastErrorAt,
+      lastErrorCode: sync.lastErrorCode,
+      persistenceSnapshotsAvailable: sync.persistenceSnapshotsAvailable,
+      sessionsTotal: sync.sessionsTotal,
+      sessionsRead: sync.sessionsRead,
+      sessionsSkippedByRevision: sync.sessionsSkippedByRevision,
+      sessionsRestoredFromLedger: sync.sessionsRestoredFromLedger,
+      sessionsFailed: sync.sessionsFailed,
+    }
+  }
   async function safeContextTimeout(ms) {
     if (disposed) return false
     try {
@@ -168,7 +234,9 @@ function apply(ctx) {
     scan.scanned = 0
     scan.total = 0
     scan.failed = 0
+    resetSyncState()
     baselineRetryDelay = 1000
+    markStatsChanged()
     return aggregationGeneration
   }
   function ensureDay(dayMap, date) {
@@ -275,6 +343,7 @@ function apply(ctx) {
     const next = { seq: eventSeq, wsId, time, values, modelId, sid }
     usageByStep.set(key, next)
     adjustUsage(wsId, time, values, modelId, 1, sid)
+    markStatsChanged()
   }
   function addDayTurn(dayMap, date, wsId, sid) {
     const day = ensureDay(dayMap, date)
@@ -287,6 +356,7 @@ function apply(ctx) {
     totals.turns += 1
     addDayTurn(byDay, dayKey(time), wsId, sid)
     addDayTurn(byDayUtc, dayKeyUtc(time), wsId, sid)
+    markStatsChanged()
   }
   function routeLabel(route) {
     if (route && typeof route.model === 'string' && route.model !== '') return (typeof route.provider === 'string' && route.provider !== '' ? route.provider + ' / ' : '') + route.model
@@ -363,7 +433,10 @@ function apply(ctx) {
     if (record === null || record === undefined) return
     for (const turn of record.turns) addTurn(turn.workspaceId, turn.time, record.sessionId)
     for (const item of record.usage) adjustUsage(item.workspaceId, item.time, item.values, item.modelId, 1, record.sessionId)
-    if (record.turns.length > 0 || record.usage.length > 0) sessionCount.add(record.sessionId)
+    if (record.turns.length > 0 || record.usage.length > 0) {
+      sessionCount.add(record.sessionId)
+      if (record.usage.length > 0) markStatsChanged()
+    }
   }
   function ledgerRank(record) {
     return [typeof record.lastSeq === 'number' ? record.lastSeq : -1, record.source === 'flush' ? 1 : 0, typeof record.updatedAt === 'number' ? record.updatedAt : 0]
@@ -508,6 +581,7 @@ function apply(ctx) {
   async function runBaseline(generation = aggregationGeneration) {
     if (scan.started || disposed || generation !== aggregationGeneration) return
     scan.started = true
+    beginSync()
     await ledgerReady
     if (disposed || generation !== aggregationGeneration) return
     let setupFailed = false
@@ -527,19 +601,25 @@ function apply(ctx) {
     } 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 (disposed || generation !== aggregationGeneration) return
+      noteSyncError('session-list-failed')
     }
+    if (disposed || generation !== aggregationGeneration) return
     // v1.0.8: cheap per-session change signal (header line + stat, no full-log read)
     let snapshots = null
     if (sessionPersistence !== undefined && typeof sessionPersistence.listSnapshots === 'function') {
       try {
         const rows = await sessionPersistence.listSnapshots()
+        if (disposed || generation !== aggregationGeneration) return
         if (Array.isArray(rows)) {
+          sync.persistenceSnapshotsAvailable = true
           snapshots = new Map()
           for (const row of rows) {
             const rid = row && row.header && typeof row.header.id === 'string' ? row.header.id : undefined
@@ -548,16 +628,22 @@ function apply(ctx) {
         }
       } catch (err) {
         console.error('[all-usage] session persistence snapshots unavailable:', err)
+        if (disposed || generation !== aggregationGeneration) return
+        sync.persistenceSnapshotsAvailable = false
+        markStatsChanged()
       }
     }
     if (disposed || generation !== aggregationGeneration) return
     if (setupFailed || !Array.isArray(records)) {
       // A transient registry failure must not be reported as a completed empty scan.
       scan.started = false
+      markStatsChanged()
       scheduleBaselineRetry(generation)
       return
     }
     scan.total = records.length
+    sync.sessionsTotal = records.length
+    markStatsChanged()
     const listedSessionIds = new Set()
     for (const record of records) {
       if (record === undefined || record === null || record.header === undefined) continue
@@ -567,12 +653,17 @@ function apply(ctx) {
       if (sid !== undefined && wsId !== undefined) listedSessionIds.add(sid)
     }
     for (const [sid, record] of ledgerRecords) {
-      if (!listedSessionIds.has(sid)) applyLedgerRecord(record)
+      if (!listedSessionIds.has(sid)) {
+        applyLedgerRecord(record)
+        if (record.turns.length > 0 || record.usage.length > 0) sync.sessionsRestoredFromLedger += 1
+      }
     }
+    if (sync.sessionsRestoredFromLedger > 0) markStatsChanged()
     for (const record of records) {
       if (disposed || generation !== aggregationGeneration) return
       if (record === undefined || record === null || record.header === undefined) {
         scan.scanned += 1
+        markStatsChanged()
         continue
       }
       const sid = record.header.id
@@ -580,6 +671,7 @@ function apply(ctx) {
       const wsId = cwd === '' ? undefined : pathIndex.get(cwd)
       if (sid === undefined || wsId === undefined) {
         scan.scanned += 1
+        markStatsChanged()
         continue
       }
       listedSessionIds.add(sid)
@@ -593,14 +685,18 @@ function apply(ctx) {
           const previousRecord = ledgerRecords.get(sid)
           const revision = snapshots === null ? undefined : snapshots.get(sid)
           if (previousRecord !== undefined && typeof previousRecord.lastRevision === 'string' && typeof revision === 'string' && revision === previousRecord.lastRevision) {
+            sync.sessionsSkippedByRevision += 1
             applyLedgerRecord(previousRecord)
             for (const item of previousRecord.usage) {
               usageByStep.set(item.key, { seq: item.seq, wsId: item.workspaceId, time: item.time, values: item.values, modelId: item.modelId, sid })
             }
             sessionSeq.set(sid, previousRecord.lastSeq)
             sessionCount.add(sid)
+            markStatsChanged()
             return
           }
+          sync.sessionsRead += 1
+          markStatsChanged()
           const snap = await ctx.sessionQuery.readSession(sid)
           if (disposed || generation !== aggregationGeneration) return
           if (snap && Array.isArray(snap.events)) {
@@ -644,21 +740,29 @@ function apply(ctx) {
             sessionCount.add(sid)
           }
         } catch (err) {
+          if (generation !== aggregationGeneration) return
+          sync.sessionsFailed += 1
+          noteSyncError('session-read-failed')
           const saved = ledgerRecords.get(sid)
           if (saved !== undefined) {
             applyLedgerRecord(saved)
+            if (saved.turns.length > 0 || saved.usage.length > 0) sync.sessionsRestoredFromLedger += 1
             sessionSeq.set(sid, -1)
             sessionCount.add(sid)
-          } else if (generation === aggregationGeneration) {
+          } else {
             sessionSeq.set(sid, -1)
             scan.failed += 1
           }
         } finally {
-          if (generation === aggregationGeneration) scan.scanned += 1
+          if (generation === aggregationGeneration) {
+            scan.scanned += 1
+            markStatsChanged()
+          }
         }
       })
       if (!(await safeContextTimeout(0))) {
         scan.started = false
+        noteSyncError('baseline-yield-unavailable')
         scheduleBaselineRetry(generation)
         return
       }
@@ -669,6 +773,12 @@ function apply(ctx) {
     knownSessionIds.clear()
     for (const sid of listedSessionIds) knownSessionIds.add(sid)
     scan.done = true
+    sync.lastCompletedAt = Date.now()
+    if (sync.sessionsFailed === 0) {
+      sync.lastErrorAt = 0
+      sync.lastErrorCode = null
+    }
+    markStatsChanged()
     if (reconcilePending) scheduleReconcileHint()
   }
 
@@ -705,6 +815,7 @@ function apply(ctx) {
       for (const sid of currentIds) knownSessionIds.add(sid)
     } catch (err) {
       console.error('[all-usage] session reconciliation failed:', err)
+      noteSyncError('session-reconcile-failed')
     } finally {
       reconcileInFlight = false
       if (reconcilePending && !disposed) scheduleReconcileHint()
@@ -778,6 +889,7 @@ function apply(ctx) {
           const value = g[key]
           if (typeof value === 'string' && value.trim() !== '') aliases[key] = value
         }
+        markStatsChanged()
       }
     } catch (err) {
       console.error('[all-usage] alias storage unavailable:', err)
@@ -799,6 +911,7 @@ function apply(ctx) {
     if (alias === '') delete aliases[wsId]
     else aliases[wsId] = alias
     persistAliases()
+    markStatsChanged()
     return { ok: true, aliases: Object.assign({}, aliases) }
   }
   ctx.effect(() => () => {
@@ -825,6 +938,12 @@ function apply(ctx) {
   })
 
   // ---------- snapshot for the client ----------
+  function scanSnapshot() {
+    return { started: scan.started, done: scan.done, scanned: scan.scanned, total: scan.total, failed: scan.failed }
+  }
+  function statusSnapshot() {
+    return { instanceId, revision: statsRevision, updatedAt: statsUpdatedAt, scan: scanSnapshot(), sync: syncSnapshot() }
+  }
   function serializeDays(dayMap) {
     const result = []
     for (const pair of dayMap) {
@@ -846,7 +965,7 @@ function apply(ctx) {
   }
   function snapshot() {
     return {
-      scan: { started: scan.started, done: scan.done, scanned: scan.scanned, total: scan.total, failed: scan.failed },
+      ...statusSnapshot(),
       generatedAt: Date.now(),
       requestToken,
       workspaces: Array.from(wsMeta.values(), (w) => ({ id: w.id, title: w.title, path: w.path })),
@@ -980,6 +1099,16 @@ function apply(ctx) {
   // ---------- HTTP data routes for the client half ----------
   if (webServer !== undefined) {
     const rejectRequest = (res) => sendJson(res, 403, { ok: false, message: 'forbidden' })
+    ctx.effect(() => webServer.register({
+      kind: 'exact',
+      path: '/api/all-usage/status',
+      handler: (req, res) => {
+        if (req.method !== 'GET') { res.statusCode = 405; res.end(); return }
+        if (!isTrustedLocalApiRequest(req, false)) { rejectRequest(res); return }
+        if (!scan.started) void runBaseline()
+        sendJson(res, 200, statusSnapshot())
+      },
+    }))
     ctx.effect(() => webServer.register({
       kind: 'exact',
       path: '/api/all-usage',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-all-usage",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "DeepSeek Harness usage dashboard with model, provider, workspace, cache, balance, and CSV insights",
   "repository": {
     "type": "git",