dsh-usage-badge 0.1.11 → 0.1.13

package/README.md

@@ -83,7 +83,7 @@ dsh plugin --profile web remove dsh-usage-badge
 
 ## 已知限制
 
-- **首次启动要冷扫一遍全部会话日志**（200 多份实测约 10 秒；分片让出事件循环，界面不会卡住）。之后走增量，几乎瞬时。
+- **首次启动要冷扫一遍全部会话日志**（本机 338 份 / 348 MB 实测约 19 秒，随机器负载浮动；按解码字节数让出事件循环，最长一次阻塞约 0.4 秒，宿主启动与界面都不会被卡住，徽标先显示「…」再填上数字）。**之后每次启动只读增量**：只解压新追加的那几帧 —— 同一台机器实测「1 个日志、2 KB、57 ms」，没有任何变化时「0 个、16 ms」。**挂载插件本身不碰磁盘**（只登记一条路由，实测 0.75 ms），打开缓存库、读历史、折日志都发生在界面第一次请求时 —— 那时宿主早已启动完成。启动的每一段都有数字：日志里的 `ready in …`、面板上的**「上次启动」**一行会写明打开库 / 载入 / 列日志 / 折叠各用了多久，觉得慢时看这一行就知道慢在哪。
 - **历史依赖日志，但日志变短不再吃掉历史**：日志被删掉后靠缓存继续计入；缓存也丢了，那段历史就没了。同一个会话的日志**变短或还原成更早的备份**时，缓存会**把更完整的那份留着**（折叠结果变小就只作为备份副本存下，统计仍用完整的那份），要等日志真的更全、却不再包含某一天，那天才会被丢掉。**例外是改名**：会话是按「日志所在目录」识别的，把某个会话目录改名会让同一份用量各算一份（见下）。DSH 自己从不裁日志：格式升级时它另写一代新文件、旧代保留，而实测换代后统计结果逐项相同。
 - **日粒度区间仍只覆盖最近一年**：`近 7 日` / `近 30 日` / `近 12 个月` 与它们下面的滚动热力图都基于快照的最近 400 天。要看更早的日子，用 **`按年`**：那一档的月度合计、年度总额与**自然年热力图**都是直接查缓存库的，任何一年都在。
 - **只统计 DSH 记进日志的调用**：某个东西直接请求外部 API 且不向 DSH 上报 usage，这部分统计不到。

package/docs/design-notes.md

@@ -327,6 +327,50 @@ dsh-usage-badge
 
 删掉 `cache.sqlite` 与删掉 `cache.json` 的后果完全一样：下次启动冷扫一遍日志重建；只有「日志已被删除」的那段历史会随之消失。
 
+### 折叠的代价：只解码新增的那几个字节
+
+「DSH 启动很慢」查下来是这个插件自己：**每启动一次就把整份日志重新解码一遍**。本机实测（373 个日志 / 348 MB）：一次启动折 25 个日志要 **3.6 秒**，冷启动（没有缓存）**20 秒**，而耗时**八成在 zstd 解压**——12.7 MB 的日志解压 775 ms，解析 JSON 只要 133 ms。两个原因叠在一起：
+
+1. **游标取错了地方**：会话的 `fileSize`/`fileMtimeMs` 原来取自它**最早那一天的行走**（每天的行记的是写它的那次折叠的戳，而折叠只重写 payload 真的变了的天），所以长寿会话的最早一天带着几个月前的戳 —— 于是**每次启动都判定成「变了」**，多天的会话全部重折。现在 `resolveRows` 取会话行本身的游标（`sessions.file_size`），那才是「这份日志我折到哪儿了」。
+2. **变了就从头折**：游标的 `fileSize` 本来**就是**上次折到哪儿的字节偏移，所以「新增了 1 KB」不需要从第 0 字节重新解压。现在 `foldSession(file, previous, { fromByte })` 只读 `[fromByte, size)`：按 zstd **帧**切（一帧要么整个折进去，要么留给下一趟）、纯文本按**最后一个换行**切，末尾那半行只有在它自身是完整 JSON 时才算数（日志最后一行常常没有换行符，漏掉它就正好漏掉最新一次请求）。
+
+规则与代价：
+
+| | 改之前 | 改之后 |
+|---|---|---|
+| 启动（25 个日志有增量时） | 折 25 个、读 45 MB、**3.6 s** | 折 1 个、读 **2 KB**、**57 ms** |
+| 启动（无变化） | 每个多天会话都重折 | **0 个、16 ms** |
+| 冷启动（无缓存，338 个日志） | 19.6 s，单次阻塞可到 ~0.8 s | 18.6 s，**最长阻塞 ~0.4 s** |
+| 使用中（每次轮询） | 活动会话整份重解压 | 只解压新追加的帧 |
+
+三条不变量：
+
+- **折不全就重折**：只有「同一路径、比游标更长」才走增量；变短、换路径、无游标、无旧记录一律从头折 —— 尾部读法假设前缀没变。
+- **不删自己没看过的天**：增量折出来的记录只覆盖窗口内的天，所以 `put(record, { keepOtherDays: true })` 跳过「记录里没有的天就删掉」那一步。否则折一次今天就会把窗口外的历史删光。
+- **不许伪造新日期**：尾部里的某天若不在旧记录里（时钟跳了、日志被原地重写），这次折叠作废、改为从头折。`test/cache.verify.mjs` 里 8 条断言钉住这些（只读增量字节数、两天相加不翻倍、无变化读 0、游标是日志大小而不是旧天戳、半行不算/补全后只算一次）。
+
+剩下的一份成本是**冷启动必须把 348 MB 读一遍**（一次性的，之后每次启动都只读增量）。它现在是**按解码字节数让出事件循环**的（每 1 MB 让一次 —— 按帧让会适得其反：一个 12 MB 日志有 34 000 帧，`setImmediate` 往返比解码本身还贵，实测 21 s 变 52 s）：18.6 秒的总时长里最长阻塞 ~0.4 秒，宿主照常启动、界面照常响应，徽标先显示「…」再填上数字。
+
+**等价性核对（真机）**：同一份 334 MB / 338 个日志，「读快照 + 只折尾部」与「清空缓存全量重折」在**共同可见的 68 天上逐日完全一致**（input、请求数逐项相等）；库里另外多的 3 天来自**日志已被删除**的会话 —— 那正是缓存有意保留的历史，全量重折本来就看不回来。
+
+**挂载时插件什么都不做，是真的什么都不做**。DSH 的 Loader 在 `boot()` 里挂载整棵插件树，所以「晚点再加载这个插件」不是插件能选的 —— 能选的是**挂载之后干什么**。`apply()` 现在只做一件事：往 `ctx.webServer` 登记一条路由（实测 **0.75 ms**，不开库、不读价格表、不碰日志、连 `sessions` 目录都不列）。真正的活全部落在**界面第一次请求**上：那条请求不可能早于宿主启动完成。
+
+启动的每一段都有数字，不再靠感觉：
+
+| 段 | 什么时候做 | 含义 | 变大意味着 |
+|---|---|---|---|
+| 挂载 | DSH 启动时 | 登记路由 | 不该长大 |
+| 打开库 `storeMs` | 第一次请求 | 打开 `cache.sqlite`、设 pragma、查 schema | 磁盘慢 / 杀毒软件在扫那个文件 |
+| 载入 `loadMs` | 第一次请求 | 把窗口内的历史读进内存 | 缓存库大，或磁盘慢 |
+| 列日志 `listMs` | 每次折叠 | 递归遍历 `sessions` 目录 | 会话特别多，或磁盘慢 |
+| 折叠 `foldMs` | 每次折叠 | 解码新追加的字节 + 重建合并视图 | 增量确实很大（会同时报读了多少 KB / 折了几个日志） |
+
+`ready in …`（日志）与面板上的「上次启动」一行报的就是这条链路；`waitedMs` 单独记「从挂载到界面来问」等了多久 —— 那是宿主的启动时间，不是插件的成本。
+
+本机实测（348 MB / 341 个日志，已是最坏的那类安装）：`apply()` **0.75 ms**；第一次请求里打开库 22 ms、载入 46 ms、列日志 16 ms、折叠 41 ms（1 个日志、8 KB），**合计 ~103 ms**；之后每轮 18 ms 左右，没有变化时就只有列日志 + stat。
+
+**兜底计时器**：如果宿主压根没人打开界面（没人请求数据），`DSH_USAGE_BADGE_WARM_MS`（默认 3000 ms）之后也会自己热身一次，纯粹为了让日志里有那条 `ready` 行；两条路径都会走同一个 `warmOnce()`，所以只会热身一次。
+
 ### `按年` 视图：年份列表属于数据，不属于代码
 
 历史不删，就迟早要看更早的年。这一年视图有三条决定：
@@ -373,7 +417,7 @@ npm test
 | `test/pricing.verify.mjs` | 用临时 `DSH_HOME` + 合成会话日志跑真实宿主半，断言精确金额。第一组用例**逐字移植自桌面壳的 `pricing-key-case.verify.mjs`**（同样的 fixture、同样的期望值），用来证明移植后的定价与原实现一致；另覆盖上下文档位（严格大于、`"128K"` 紧凑写法、缓存 token 计入上下文）、峰谷 `days` 规则、跨币种换算、前缀行的四条优先级规则（精确行优先、长前缀优先、星号不是分隔符、裸 `*` 仍是死配置）、隐式前缀回退（官方行兜住自己的变体、分隔符边界让 `gpt-4` 吞不掉 `gpt-4o`、开关经 PUT 路由后在**同一个进程内**立刻重算），以及未匹配模型不计价的语义（哪些行算「匹配」、token 仍计入、快照列出被跳过的路由）、逐行/表级的 `honorHolidays`（既有「节假日盖过行内规则」也有「行内拒绝日历后照样收峰价」）、行编辑器的写入路径（整份 `overrides` 经 PUT 落盘、其它字段与两个开关不受影响）、**`default` 行是整体替换而非字段合并**（清空的字段真的消失、`{}` 被当成「没有这一行」）、以及**一行 `null` 覆盖行**被跳过而不是让 `/summary` 500 |
 | `test/holidays.verify.mjs` | 节假日日历的行为：工作日节假日全天空闲、**调休周末仍按空闲价**（政策原文说周末全天空闲）、旧配置里的 `holidays.workdays` 被忽略、关闭日历时回到旧的按星期行为、自定义 `extra`、同一个月内不同日子的分类互不干扰，以及**2027 年的单日端午/中秋**（同一天 10:30，节当天 x1、旁边的周三 x2）与 2027-02-14 调休周日 |
 | `test/official-pricing.verify.mjs` | 解析器对**中英文两个页面快照**的逐字段断言（含旧模型别名、时区识别与换算）；页面结构变化时会抛错而不是静默返回错价；`应用` 的合并语义（未知字段存活、已有的 `default` 行不动、没有 `default` 行时按官方第一条补一个并报告 `defaultFrom`、页面第一条确实是最便宜那档）；并用**被 stub 掉的 fetch** 跑通两个路由，最后验证应用后的价格真的参与计费（含未列出模型按生成的 default 行计价），以及兜底行的完整生命周期：删除 → 回到内置模板并把 `defaultSource` 报成 `template` → 再次应用从官方第一条生成回来 → 手改过的兜底行不会被应用覆盖 |
-| `test/cache.verify.mjs` | 缓存存储层：**两个后端跑同一套契约断言**（会话游标与桶的往返、`hourly` 槽位与逐请求记录、重写会话即替换它的日期集合、`years()` 的年份列表与有界区间读），以及只有跨重启才看得见的行为 —— **删掉会话日志后历史仍在**（新挂载的宿主照旧报出同样的金额）、**没有变化的一轮刷新不写文件**、**超出加载窗口的那天留在库里只是不读进来**（换个更宽的窗口还能取到）、旧 `cache.json` **迁移一次**并把旧文件改名为 `.migrated`（且 `.migrated` 之后**不再被读**）、**读不出来的缓存文件被改名保留并新建一个**、**更新版本的库只读使用且绝不改名**、加载窗口必须大于快照窗口这条不变量，以及 `按年` 路由（三年以前那一年照样读得到、12 个月恒定、`daily` 带节假日标记与 provider 拆分、没有数据的年份是 12 个空月而不是报错、非法年份 400）。 |
+| `test/cache.verify.mjs` | 缓存存储层：**两个后端跑同一套契约断言**（会话游标与桶的往返、`hourly` 槽位与逐请求记录、重写会话即替换它的日期集合、`years()` 的年份列表与有界区间读），以及只有跨重启才看得见的行为 —— **删掉会话日志后历史仍在**（新挂载的宿主照旧报出同样的金额）、**没有变化的一轮刷新不写文件**、**超出加载窗口的那天留在库里只是不读进来**（换个更宽的窗口还能取到）、旧 `cache.json` **迁移一次**并把旧文件改名为 `.migrated`（且 `.migrated` 之后**不再被读**）、**读不出来的缓存文件被改名保留并新建一个**、**更新版本的库只读使用且绝不改名**、加载窗口必须大于快照窗口这条不变量、**增量折叠**（重启只读新追加的字节且读的字节数正好等于追加量、两天相加不翻倍、无变化时读 0、游标是日志大小而不是最早那天的戳、半行不算而补全后只算一次），**启动让出宿主**（还没折叠的挂载如实说「没折过」而不是看起来没数据、等待与工作分开计时），以及 `按年` 路由（三年以前那一年照样读得到、12 个月恒定、`daily` 带节假日标记与 provider 拆分、没有数据的年份是 12 个空月而不是报错、非法年份 400）。 |
 | `test/client.render.mjs` | 用替身 Loader 加载浏览器 bundle，检查 slot 注册形状与 `id`，再用 `react-dom/server` 渲染两个面板，断言金额格式、区间页签（含 `按年`：下拉只列出宿主报的那几年、选中的那一年被选中、月份轴恒为 12、点数是 12 × 序列数、四张卡片是那一年的合计、这一档不画热力图、没有年份时不渲染空下拉）、四序列折线的条数与配色、图例开关（单独显示某一条时的折线条数，以及面积填充有没有跟着走）、悬停 tooltip 的装配、provider 页签、热力图的格数（371 − 今天之后的那几天）与分档、官方价格表内容、两个开关（前缀回退与未匹配模型计价：开/关两种状态各自渲染出的说明与动作、default 行的来源标注、以及「哪些模型没价格」的提示）、**覆盖行编辑器**（每行的编辑/删除动作、倍率与峰谷列恒定存在、表单用被编辑行的真实数值预填而不是空模板、自定义规则才展开规则字段、新增行不给删除按钮、**兜底行同样可编辑可删除且不提供那些不生效的字段**、**重名键与「改过的行」会被保存拦下**、**旧宿主不会被说成「兜底行还没有」**、以及「保留未显示字段」与拒绝写 NaN 的源码断言）、节假日徽标与日历区块、展开/收起两种行形态、**没有用量的那天金额仍贴右**（token 槽位渲染但为空）、**弹窗那一段 CSS 里不许出现任何宿主颜色令牌（`--dsw-`），必须自带浅色/深色两套 `--dub-*` 调色板**，以及空数据 / 稀疏 provider 两个边界不崩 |
 | `test/smoke.mjs` | 对着**本机真实**的 `$DSH_HOME` 跑一遍，打印徽标金额、今日 token 构成、当前峰谷档位、节假日日历状态、最近 7 天，以及滚动热力图那 371 天的分档分布（有用量的天数与四档各多少天，都挤在一档说明这张图会显得很平） |
 | `test/official-pricing.live.mjs` | **联网**核对：抓真实页面并与 `test/fixtures/` 的快照逐字段比对，确认官方页面仍能解析、价格未变 |
@@ -824,6 +868,7 @@ storages/usage-badge/host.lock     # { pid, startedAt, instanceId, hostname, at
 - **首次启动要冷扫一遍全部日志**（实测 209 份日志约 10 秒，分片让出事件循环，不会卡住宿主）。之后走增量：实测热启动 237ms、折叠 0 份。缓存文件丢失才会再次冷扫。
 - **历史依赖日志仍在盘上，但「变短」不再吃掉历史**：已删除的日志靠缓存里保留的贡献继续计入；缓存也丢了，那段历史就没了。日志**变短或还原成更早的备份**时不再删缓存里的天：折叠结果变小只会写进 `fallback` 槽位，`current`（读的时候认的那份）仍是更完整的那份。只有日志**更全**、却不再包含某一天时，那天才会被丢掉（section 8 有正反两个方向的断言）。**例外是改名**：会话身份是日志所在目录名，改名会让同一份用量各算一份。
 - **缓存只把最近 430 天装进内存**（`CACHE_WINDOW_DAYS`，比快照要的 400 天宽）：更早的行留在库里，`按年` 视图能直接查它们，但**日粒度**的区间（`近 N 日`）与热力图仍只覆盖最近一年。
+- **第一次折叠（或缓存被删掉之后）仍要把全部会话日志读一遍**：本机 348 MB / 338 个日志约 21 秒。它是按帧让出事件循环的（实测最长一次阻塞 203 ms），所以不会拖住宿主启动，但徽标会先显示「…」再填上数字；之后每次启动只读增量（同一台机器实测：1 个日志、2 KB、57 ms）。
 - **没有 `node:sqlite` 的运行时会退回旧的 JSON 缓存**：功能一样，但保存代价与常驻内存随历史长度增长（就是换 SQLite 之前的实测数字）。面板的 ⓘ 会写明当前用的是哪一种。
 - **云同步是手动触发的**：面板上的「立即同步」+「测试连接」是目前唯一的入口（价格表变更后的自动推送、启动后延迟一次都还没接）。数据仍然只在一台机器上直到你点它 —— 换机器、重装、或删掉缓存目录，都会丢掉「日志里已经没有」的那段历史（日志还在的部分能重新折出来）。设计见上面「云同步」一节。
 - **折叠结果是日志所在目录 × 日期**：缓存按 `(会话目录, 日期)` 存，所以把某个会话目录**改名**会让同一份用量出现两个会话，**各算一份**（实测 `¥1.5 → ¥3.0`）。行模型只能处理「同一个会话的多个副本」，管不了会话 id 本身漂移 —— 要修需要从日志 header 取稳定的会话 id。删日志、截断日志、还原旧备份这三种情况现在都不会丢历史。

package/lib/buckets.js

@@ -297,12 +297,18 @@ export function resolveRows(records) {
     const byDate = [...entry.winners.values()].sort((a, b) => (a.date < b.date ? -1 : a.date > b.date ? 1 : 0))
     for (const row of byDate) days.set(row.date, deserializeDay(row.routes))
     const winner = byDate[0] ?? null
+    // The session's stamp is its **cursor** — the log version this device last folded it from —
+    // not the stamp of one of its days. A day row keeps the stamp of the fold that wrote it, and a
+    // fold rewrites only the days whose buckets changed, so the oldest day of a long-lived session
+    // carries a months-old stamp. Reading the cursor off that day made every multi-day session look
+    // changed on every start, which re-folded the whole log (measured: 3.6 s per start, 20 s cold).
+    // The day stamp is only a fallback for a record that arrived without a cursor.
     resolved.push({
       sessionId: entry.sessionId,
       path: entry.path,
-      fileSize: winner?.fileSize ?? entry.fileSize ?? 0,
-      fileMtimeMs: winner?.fileMtimeMs ?? entry.fileMtimeMs ?? 0,
-      seq: winner?.seq ?? entry.seq ?? -1,
+      fileSize: entry.fileSize ?? winner?.fileSize ?? 0,
+      fileMtimeMs: entry.fileMtimeMs ?? winner?.fileMtimeMs ?? 0,
+      seq: entry.seq ?? winner?.seq ?? -1,
       provider: entry.provider,
       model: entry.model,
       days,

package/lib/cache-store.js

@@ -351,6 +351,9 @@ function createJsonStore({ path, log }) {
     put(record, options = {}) {
       const doc = ensureDocument()
       const at = options.at ?? Date.now()
+      // A tail fold carries only the days the appended bytes touched, so the days it does not
+      // mention are not rows the log lost — they are rows this fold never looked at.
+      const keepOtherDays = options.keepOtherDays === true
       const previous = documentToRecord(record.sessionId, doc.sessions[record.sessionId])
       const incoming = rowsOf(record, { source: LOCAL_SOURCE, at })
       const incomingKeys = new Set(incoming.map((row) => `${row.date}\u0000${row.source}`))
@@ -366,7 +369,7 @@ function createJsonStore({ path, log }) {
         //     reaches back to it. A row older than the incoming cursor was folded from a fuller log
         //     — a shorter one now, or a restored backup — and it is all that is left of those days.
         const theirs = rowSource(row) !== LOCAL_SOURCE || rowKind(row) === FALLBACK
-        const keep = theirs || incomingKeys.has(key) || !rowIsNewerOrEqual(cursor, row)
+        const keep = keepOtherDays || theirs || incomingKeys.has(key) || !rowIsNewerOrEqual(cursor, row)
         if (keep) kept.push(row)
       }
       // Grouped by `(date, source, kind)`: the `current` and `fallback` copies of one date share a
@@ -793,7 +796,7 @@ function createSqliteStore({ path, jsonPath, log, DatabaseSync, db: given = null
    *   - when the fold is shorter *and* drops a day, the day is rolled back rather than deleted —
    *     this is what a restored backup looks like, and it is the case the whole row model exists for.
    */
-  const writeSession = (record, { source = LOCAL_SOURCE, at = Date.now() } = {}) => {
+  const writeSession = (record, { source = LOCAL_SOURCE, at = Date.now(), keepOtherDays = false } = {}) => {
     writeCursor(record)
     const cursor = readCursor(record.sessionId)
     const incoming = rowsOf(record, { source, at })
@@ -817,6 +820,12 @@ function createSqliteStore({ path, jsonPath, log, DatabaseSync, db: given = null
     // log. Its `current` row goes with it — unless this log version is itself weaker than the copy
     // already stored, in which case a shortened log is treated as a rollback rather than as a
     // deletion, and the day is kept.
+    //
+    // `keepOtherDays` skips this whole step: a **tail fold** only ever looked at the appended
+    // bytes, so a day it does not mention is a day it never read, not one the log dropped. Without
+    // it, folding the last five minutes of a growing log would delete every day outside the loading
+    // window the record was built from.
+    if (keepOtherDays) return
     for (const row of stored.values()) {
       if (cursor && !rowIsNewerOrEqual(cursor, row)) continue
       deleteRow.run(record.sessionId, row.date, source, CURRENT)
@@ -1036,11 +1045,11 @@ function createSqliteStore({ path, jsonPath, log, DatabaseSync, db: given = null
      * short fold it just produced. Returning the resolved record is what makes "the cache kept it"
      * true in memory as well as on disk.
      */
-    put(record, { at = Date.now() } = {}) {
+    put(record, { at = Date.now(), keepOtherDays = false } = {}) {
       if (!writable) return null
       try {
         db.exec('BEGIN IMMEDIATE')
-        writeSession(record, { source: LOCAL_SOURCE, at })
+        writeSession(record, { source: LOCAL_SOURCE, at, keepOtherDays })
         db.exec('COMMIT')
       } catch (error) {
         try {

package/lib/client.js

@@ -1937,6 +1937,16 @@ html[data-theme="dark"] .dub-mask{
               '新增一行',
             ),
           ),
+          // How the last start spent its time. A slow start used to be a feeling; these are the
+          // numbers behind it, so "it is slow again" can say *which* phase grew.
+          config?.boot?.readyAt
+            ? h(
+                'div',
+                { className: 'dub-note' },
+                `上次启动：共 ${config.boot.totalMs} ms —— 打开库 ${config.boot.storeMs} ms · 载入 ${config.boot.loadMs} ms · 列日志 ${config.boot.listMs} ms · 折叠 ${config.boot.foldMs} ms` +
+                  `（${config.boot.folded}/${config.boot.files} 个日志，读 ${Math.round((config.boot.bytesRead ?? 0) / 1024)} KB；共 ${config.boot.sessions} 个会话）`,
+              )
+            : null,
           !effective
             ? h('div', { className: 'dub-note' }, '正在读取当前配置…')
             : h(

package/lib/fold.js

@@ -17,7 +17,7 @@
  * @module dsh-usage-badge/fold
  */
 
-import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { closeSync, openSync, readSync, readFileSync, readdirSync, statSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join, resolve } from 'node:path'
 import { zstdDecompressSync } from 'node:zlib'
@@ -57,34 +57,6 @@ export function resolveDshHome(configured, env = process.env) {
   return resolve(expandHome(chosen))
 }
 
-/**
- * Decode a log body that may hold one or more concatenated zstd frames.
- *
- * DSH appends frames as a session grows, so a `.zstd` log is a frame sequence
- * rather than one stream; `zstdDecompressSync` handles a single frame, so the
- * buffer is split on the frame magic first. A body with no frame magic is
- * returned as UTF-8, which keeps plain `.jsonl` and any partially written file
- * readable instead of throwing.
- */
-export function decodeLogBody(buf) {
-  const starts = []
-  let i = 0
-  while ((i = buf.indexOf(ZSTD_MAGIC, i)) !== -1) {
-    starts.push(i)
-    i += 1
-  }
-  if (starts.length === 0) return buf.toString('utf8')
-  if (typeof zstdDecompressSync !== 'function') {
-    throw new Error('this Node build has no zlib.zstdDecompressSync; a zstd session log cannot be read')
-  }
-  let out = ''
-  for (let k = 0; k < starts.length; k++) {
-    const end = k + 1 < starts.length ? starts[k + 1] : buf.length
-    out += zstdDecompressSync(buf.subarray(starts[k], end)).toString('utf8')
-  }
-  return out
-}
-
 function logParent(file) {
   const index = Math.max(file.lastIndexOf('\\'), file.lastIndexOf('/'))
   return index >= 0 ? file.slice(0, index) : ''
@@ -139,45 +111,129 @@ export function sessionIdFromLogPath(file) {
 }
 
 /**
- * Fold one session log into per-day, per-route buckets.
- *
- * Route attribution follows the log's own control events: `request/header` (and
- * `request/context`) carry the provider and model, and each `assistant/message`
- * carries the provider-reported `usage` for one completed request. Requests are
- * stamped with the hour they were *sent* where the log allows it, because a
- * streaming call can cross a peak/valley boundary and filing it by completion
- * would price it in the wrong band.
+ * Read a log's tail without reading the whole file.
  *
- * @returns {object|null} the session record, or null when the file is unreadable.
+ * The fold's cost is dominated by zstd decompression (measured on a real log: 12.7 MB took 775 ms
+ * to decode against 133 ms of `JSON.parse`), so re-decoding a log whose only change is an appended
+ * frame is the one thing worth avoiding. `from` is the byte offset the last fold consumed — which
+ * is exactly the `fileSize` the cursor already stores, so this needs no new field.
  */
-export function foldSession(file, previous) {
-  const sessionId = sessionIdFromLogPath(file)
-  let stat
+function readTail(file, from, size) {
+  if (!(from > 0)) return readFileSync(file)
+  const length = size - from
+  if (!(length > 0)) return Buffer.alloc(0)
+  const fd = openSync(file, 'r')
   try {
-    stat = statSync(file)
-  } catch {
-    return null
+    const buf = Buffer.allocUnsafe(length)
+    let read = 0
+    while (read < length) {
+      const n = readSync(fd, buf, read, length - read, from + read)
+      if (n <= 0) break
+      read += n
+    }
+    return read === length ? buf : buf.subarray(0, read)
+  } finally {
+    closeSync(fd)
   }
-  let body
+}
+
+/** Whether a fragment is exactly one complete JSON value — a torn append is not. */
+function isCompleteJsonLine(fragment) {
+  if (!fragment || !fragment.trim()) return false
   try {
-    body = readFileSync(file)
+    JSON.parse(fragment)
+    return true
   } catch {
-    return null
+    return false
   }
-  let text
-  try {
-    text = decodeLogBody(body)
-  } catch {
-    // An unreadable body keeps whatever this session contributed before, so a
-    // transient decompression failure cannot erase history.
-    return previous ?? null
+}
+
+/**
+ * Split a plain-text log into newline-aligned slices.
+ *
+ * Sliced rather than handed over whole so a large `.jsonl` log cannot hold the event loop for a
+ * second while the rest of the host waits. The final line may have no trailing newline yet — that
+ * is how the last request of an idle log looks, and dropping it would under-count the badge
+ * exactly where eyes are — so it counts when it parses, and a torn append is left for next time.
+ */
+function* plainChunks(text) {
+  const SLICE = 1 << 20
+  let offset = 0
+  while (offset < text.length) {
+    let end = Math.min(offset + SLICE, text.length)
+    if (end < text.length) {
+      const nl = text.lastIndexOf('\n', end - 1)
+      end = nl >= offset ? nl + 1 : text.length
+    }
+    let piece = text.slice(offset, end)
+    if (end >= text.length) {
+      const nl = piece.lastIndexOf('\n')
+      piece = piece.slice(0, nl + 1) + (isCompleteJsonLine(piece.slice(nl + 1)) ? piece.slice(nl + 1) : '')
+      if (!piece) return
+    }
+    yield { bytes: Buffer.byteLength(piece, 'utf8'), text: piece }
+    offset = end
   }
+}
 
-  const sessionDays = new Map()
-  let provider = null
-  let model = null
-  let maxSeq = -1
+/**
+ * The chunks of a body that may be folded, each carrying how many bytes it accounts for.
+ *
+ * A `.zstd` log is a sequence of independently decodable frames that DSH appends to, so "how much
+ * can I fold" is a question about frames, not bytes: a frame that does not decode (the appender is
+ * mid-write) or whose text stops mid-line is left for the next pass rather than folded half way.
+ * Anything that does not begin with a frame magic is plain text, consumed up to its last newline.
+ */
+function* foldableChunks(buf) {
+  const starts = []
+  let i = 0
+  while ((i = buf.indexOf(ZSTD_MAGIC, i)) !== -1) {
+    starts.push(i)
+    i += 1
+  }
+  if (starts.length === 0 || starts[0] !== 0) {
+    yield* plainChunks(buf.toString('utf8'))
+    return
+  }
+  if (typeof zstdDecompressSync !== 'function') {
+    throw new Error('this Node build has no zlib.zstdDecompressSync; a zstd session log cannot be read')
+  }
+  for (let k = 0; k < starts.length; k++) {
+    const end = k + 1 < starts.length ? starts[k + 1] : buf.length
+    let piece
+    try {
+      piece = zstdDecompressSync(buf.subarray(starts[k], end)).toString('utf8')
+    } catch {
+      return // an unfinished frame: the next pass picks it up
+    }
+    if (!piece.endsWith('\n')) {
+      // Only the last frame can be the end of a log, and then only when its final line is itself
+      // complete JSON; anything else is a torn append.
+      if (end === buf.length && isCompleteJsonLine(piece.slice(piece.lastIndexOf('\n') + 1))) {
+        yield { bytes: end - starts[k], text: piece }
+      }
+      return
+    }
+    yield { bytes: end - starts[k], text: piece }
+  }
+}
+
+/** A bucket copied deep enough that a fold can add to it without touching the stored record. */
+function cloneBucket(bucket) {
+  return {
+    ...bucket,
+    hourly: Array.isArray(bucket.hourly) ? bucket.hourly.map((hour) => ({ ...hour })) : bucket.hourly,
+    usageRecords: Array.isArray(bucket.usageRecords) ? bucket.usageRecords.map((usage) => ({ ...usage })) : bucket.usageRecords,
+  }
+}
 
+/**
+ * Add one decoded chunk's events to the fold state.
+ *
+ * Events land in `state.fresh` rather than in the day maps the previous record handed over, so a
+ * tail fold that has to be abandoned leaves that record exactly as it was.
+ */
+function foldText(text, state) {
   for (const line of text.split('\n')) {
     if (!line) continue
     let ev
@@ -187,25 +243,26 @@ export function foldSession(file, previous) {
       continue // a torn tail line is expected on a log being appended
     }
     const seq = typeof ev?.seq === 'number' ? ev.seq : -1
-    if (seq > maxSeq) maxSeq = seq
+    if (seq > state.seq) state.seq = seq
     const data = ev?.data ?? {}
     if (ev?.type === 'request/header') {
       const config = data.header?.config ?? {}
-      provider = config.provider ?? data.provider ?? null
-      model = config.model ?? data.model ?? null
+      state.provider = config.provider ?? data.provider ?? null
+      state.model = config.model ?? data.model ?? null
     } else if (ev?.type === 'request/context') {
-      provider = data.provider ?? provider
-      model = data.model ?? model
+      state.provider = data.provider ?? state.provider
+      state.model = data.model ?? state.model
     } else if (ev?.type === 'assistant/message') {
       const usage = data.usage
       if (!usage || typeof usage !== 'object') continue
-      const pm = provider ?? UNKNOWN
-      const mm = model ?? UNKNOWN
+      const pm = state.provider ?? UNKNOWN
+      const mm = state.model ?? UNKNOWN
       const date = dayKey(ev.time ?? Date.now())
-      let dayObj = sessionDays.get(date)
+      state.dates.add(date)
+      let dayObj = state.fresh.get(date)
       if (!dayObj) {
         dayObj = new Map()
-        sessionDays.set(date, dayObj)
+        state.fresh.set(date, dayObj)
       }
       const key = `${pm}|${mm}`
       const bucket = dayObj.get(key) ?? emptyBucket(pm, mm)
@@ -231,16 +288,115 @@ export function foldSession(file, previous) {
       dayObj.set(key, bucket)
     }
   }
+}
+
+/** Commit this pass's own buckets into the record's days, cloning what it shares with the old one. */
+function mergeFresh(state) {
+  for (const [date, dayObj] of state.fresh) {
+    const existing = state.days.get(date)
+    const target = existing ? new Map(existing) : new Map()
+    for (const [key, bucket] of dayObj) {
+      const known = target.get(key)
+      if (!known) {
+        target.set(key, bucket)
+        continue
+      }
+      const merged = cloneBucket(known)
+      addBucket(merged, bucket)
+      target.set(key, merged)
+    }
+    state.days.set(date, target)
+  }
+}
+
+/**
+ * Fold one session log into per-day, per-route buckets.
+ *
+ * Route attribution follows the log's own control events: `request/header` (and
+ * `request/context`) carry the provider and model, and each `assistant/message`
+ * carries the provider-reported `usage` for one completed request. Requests are
+ * stamped with the hour they were *sent* where the log allows it, because a
+ * streaming call can cross a peak/valley boundary and filing it by completion
+ * would price it in the wrong band.
+ *
+ * **Only the new bytes are decoded.** `fromByte` is where the previous fold stopped (the cursor's
+ * `fileSize`), and the tail is decoded on its own and merged into `previous`: re-decoding the whole
+ * log for one appended frame is what made a start with 25 grown logs cost 3.6 s and a cold cache
+ * 20 s. The returned `fileSize` is the offset this pass actually reached — a torn tail stays
+ * unfolded and is retried next time for the price of the few bytes it holds.
+ *
+ * @param {string} file
+ * @param {object|null} previous - the record this session already has; required for a tail fold.
+ * @param {{fromByte?:number, yieldBytes?:number}} [options]
+ * @returns {Promise<object|null>} the session record, or null when the file is unreadable.
+ */
+export async function foldSession(file, previous = null, { fromByte = 0, yieldBytes = 1 << 20 } = {}) {
+  const sessionId = sessionIdFromLogPath(file)
+  let stat
+  try {
+    stat = statSync(file)
+  } catch {
+    return null
+  }
+  const tail = fromByte > 0 && fromByte <= stat.size
+  let body
+  try {
+    body = readTail(file, tail ? fromByte : 0, stat.size)
+  } catch {
+    return null
+  }
+
+  const state = {
+    // A copy of the map, one level deep: `mergeFresh` replaces whole day entries and cloned
+    // buckets, so an abandoned tail fold cannot leave a mark on the record this session already has.
+    days: tail && previous?.days ? new Map(previous.days) : new Map(),
+    fresh: new Map(),
+    dates: new Set(),
+    provider: tail ? previous?.provider ?? null : null,
+    model: tail ? previous?.model ?? null : null,
+    seq: tail ? previous?.seq ?? -1 : -1,
+  }
+  // `body` holds the tail alone, so offsets inside it are buffer-relative; `consumed` is reported
+  // in file coordinates, which is what the cursor stores.
+  const shift = tail ? fromByte : 0
+  let consumed = shift
+  let sinceYield = 0
+  try {
+    for (const chunk of foldableChunks(body)) {
+      foldText(chunk.text, state)
+      consumed += chunk.bytes
+      // Yield on **bytes decoded**, not on a count of frames: a 12 MB log is ~34 000 frames, so
+      // yielding per few frames cost more in `setImmediate` round-trips than the decoding did
+      // (measured: a 338-log cold fold went from 21 s to 52 s). One megabyte is ~30 ms of zstd
+      // work — small enough that the host keeps breathing, rare enough to be free.
+      sinceYield += chunk.bytes
+      if (sinceYield >= yieldBytes) {
+        sinceYield = 0
+        await new Promise((resolve) => setImmediate(resolve))
+      }
+    }
+  } catch {
+    // An unreadable body keeps whatever this session contributed before, so a
+    // transient decompression failure cannot erase history.
+    return previous ?? null
+  }
+  mergeFresh(state)
 
   return {
     sessionId,
     path: file,
-    fileSize: stat.size,
+    fileSize: consumed,
     fileMtimeMs: stat.mtimeMs || 0,
-    seq: maxSeq,
-    provider,
-    model,
-    days: sessionDays,
+    seq: state.seq,
+    provider: state.provider,
+    model: state.model,
+    days: state.days,
+    // Which days this pass itself added. A tail fold may add a day (a session running past
+    // midnight does exactly that), but it may never add one *older* than the newest day the record
+    // already holds: an append only moves forward, so an older day means the log was rewritten
+    // rather than appended to, and the caller re-folds the session from the start.
+    touchedDates: [...state.dates],
+    foldedBytes: consumed,
   }
 }
 
@@ -288,6 +444,15 @@ export function createAggregator({ sessionsRoot, store, log = () => {} }) {
   const cursors = new Map()
   let days = new Map()
   let lastRefresh = null
+  /**
+   * Whether the stored history has been read into this process yet.
+   *
+   * `loadCache()` is deliberately **not** called when the plugin mounts: mounting happens inside DSH's
+   * own startup, and reading 300+ sessions' payloads there put forty-odd milliseconds (more on a cold
+   * disk, or under a virus scanner) on the host's boot path for numbers nothing has asked for yet.
+   * The first `refresh()` — which is what the badge's first request runs — does it instead.
+   */
+  let loadedOnce = false
 
   function mergeDays() {
     days = mergeRecords(records.values())
@@ -331,6 +496,7 @@ export function createAggregator({ sessionsRoot, store, log = () => {} }) {
     }
     mergeDays()
     if (!quiet) log(`cache loaded: ${records.size} session(s) from ${store.kind}`)
+    loadedOnce = true
     return records.size > 0
   }
 
@@ -351,12 +517,23 @@ export function createAggregator({ sessionsRoot, store, log = () => {} }) {
    * reason the store is not a single document, and it means there is no save timer to lose
    * work in and no moment where a burst of edits has to be batched.
    *
-   * @returns {Promise<{files:number, folded:number, ms:number}>} what this pass did.
+   * @returns {Promise<{files:number, folded:number, tailed:number, bytesRead:number, loadMs:number, listMs:number, ms:number}>} what this pass did.
    */
   async function refresh() {
     const started = Date.now()
+    let loadMs = 0
+    if (!loadedOnce) {
+      // The first pass of a process is where the stored history comes in — see `loadedOnce`.
+      const beforeLoad = Date.now()
+      loadCache()
+      loadMs = Date.now() - beforeLoad
+    }
+    const beforeList = Date.now()
     const files = listLogFiles(sessionsRoot)
+    const listMs = Date.now() - beforeList
     let folded = 0
+    let tailed = 0
+    let bytesRead = 0
     let sinceYield = 0
     for (const file of files) {
       const sessionId = sessionIdFromLogPath(file)
@@ -371,7 +548,35 @@ export function createAggregator({ sessionsRoot, store, log = () => {} }) {
         continue
       }
       const previous = records.get(sessionId)
-      const record = foldSession(file, previous)
+      // The cursor's `fileSize` is the byte offset the last fold consumed, so a log that only grew
+      // is folded from there. Everything else — a shorter log, a different path, no cursor, no
+      // record to fold into — is a full re-fold, because a tail read assumes the prefix is intact.
+      const tailFrom =
+        previous && cursor && cursor.path === file && cursor.fileSize > 0 && stat.size > cursor.fileSize
+          ? cursor.fileSize
+          : 0
+      let record = await foldSession(file, tailFrom > 0 ? previous : null, { fromByte: tailFrom })
+      let tail = tailFrom > 0 && Boolean(record)
+      if (tail && record !== previous) {
+        // A tail fold may add a day — a session running past midnight does exactly that — but the
+        // days it adds cannot be *older* than the newest one already folded: an append only moves
+        // forward. An older day means the file was rewritten in place, so the prefix this pass did
+        // not look at is not the prefix the record was built from; fold that session from the start.
+        let newest = ''
+        for (const date of previous.days?.keys() ?? []) if (date > newest) newest = date
+        const stale = newest !== '' && record.touchedDates?.some((date) => date < newest)
+        if (stale) {
+          record = await foldSession(file, previous, {})
+          tail = false
+        }
+      } else if (!record) {
+        tail = false
+      }
+      if (record) {
+        bytesRead += tail && tailFrom > 0 ? Math.max(0, (record.fileSize ?? 0) - tailFrom) : (record.fileSize ?? 0)
+        delete record.touchedDates
+        delete record.foldedBytes
+      }
       // `foldSession` hands the previous record straight back when it could not read the log, and
       // that record is already in the store — writing it again would replace the session's rows
       // with only the days this process happens to hold (the loading window), deleting the older
@@ -379,6 +584,7 @@ export function createAggregator({ sessionsRoot, store, log = () => {} }) {
       // fold, which is what a transient read failure wants.
       if (record && record !== previous) {
         folded++
+        if (tail) tailed++
         // Written back one session at a time, right here: a save costs the changed session's
         // days, not the whole history, so there is nothing to batch and no timer to lose it in.
         //
@@ -386,9 +592,13 @@ export function createAggregator({ sessionsRoot, store, log = () => {} }) {
         // the fold just produced, but when the log got shorter the store keeps the fuller copy
         // it already had — and then *that* is the truth, because the whole point of the row
         // model is that a shortened log cannot make history disappear.
+        //
+        // `keepOtherDays` is what makes a tail fold safe to write: the record it carries covers
+        // the loading window, not the session's whole history, so the days outside the window are
+        // this process's blind spot rather than rows the log no longer has.
         let effective = record
         try {
-          effective = store.put(record, { source: LOCAL_SOURCE }) ?? record
+          effective = store.put(record, { source: LOCAL_SOURCE, keepOtherDays: tail }) ?? record
         } catch (error) {
           log(`cache write failed for ${sessionId}: ${error?.message ?? error}`)
         }
@@ -411,7 +621,7 @@ export function createAggregator({ sessionsRoot, store, log = () => {} }) {
     // being refreshed — and, because nothing writes it again, that history stays in the store
     // for good rather than being erased by the log's absence.
     if (folded > 0) mergeDays()
-    lastRefresh = { files: files.length, folded, ms: Date.now() - started, at: Date.now() }
+    lastRefresh = { files: files.length, folded, tailed, bytesRead, loadMs, listMs, ms: Date.now() - started, at: Date.now() }
     return lastRefresh
   }
 

package/lib/index.js

@@ -87,6 +87,16 @@ const SNAPSHOT_TTL_MS = 2000
  */
 export const PRICING_PUSH_DELAY_MS = 3000
 
+/**
+ * How long the plugin waits before warming itself up when nobody has asked for numbers.
+ *
+ * The **first request** is what really starts the work (see `warmOnce`), and that request cannot
+ * arrive before the harness is up — so this timer is only the fallback for a host nobody is looking
+ * at. It is deliberately generous: mounting happens inside DSH's own startup, and nothing the plugin
+ * does belongs on that path.
+ */
+export const STARTUP_WARM_DELAY_MS = 3000
+
 /** How long after startup the first automatic sync runs, when sync is enabled. */
 export const STARTUP_SYNC_DELAY_MS = 8000
 
@@ -586,9 +596,46 @@ export function apply(ctx) {
   // The folded history lives in whichever store this runtime can offer — SQLite when
   // `node:sqlite` is there, the original single-document JSON otherwise. Either way it is one
   // file inside the plugin's own directory.
-  const store = createCacheStore({ dir: dataDir, log })
-  const aggregator = createAggregator({ sessionsRoot, store, log })
-  aggregator.loadCache()
+  //
+  // **Nothing is opened here.** `apply()` runs inside DSH's own startup, and a plugin must not put
+  // its I/O on that path: opening the database, reading the price table and parsing the stored
+  // history all happen on first use — which in practice is the interface's first request, long after
+  // the harness is up. `boot` records how long each phase took, so a slow start names its culprit.
+  let opened = null
+  function ensureOpen() {
+    if (opened) return opened
+    const storeOpenStarted = Date.now()
+    const store = createCacheStore({ dir: dataDir, log })
+    const storeMs = Date.now() - storeOpenStarted
+    const aggregator = createAggregator({ sessionsRoot, store, log })
+    // The price table is read here rather than at mount for the same reason; `refreshOnce()` re-reads
+    // it on every pass, so an edit still applies without a restart.
+    const { path: pricingSourcePath } = readRawPricing(pricingPaths)
+    if (pricingSourcePath === legacyPricingPath) {
+      log(`reading the price table from the pre-isolation path ${legacyPricingPath}; the next write moves it to ${pricingPath}`)
+    }
+    pricing = readPricing(pricingPaths)
+    rules = resolveHolidayRules(pricing.holidays)
+    opened = { store, aggregator }
+    boot.storeMs = storeMs
+    return opened
+  }
+  const boot = {
+    mountedAt: Date.now(),
+    at: 0,
+    waitedMs: 0,
+    storeMs: 0,
+    loadMs: 0,
+    listMs: 0,
+    foldMs: 0,
+    totalMs: 0,
+    files: 0,
+    sessions: 0,
+    folded: 0,
+    tailed: 0,
+    bytesRead: 0,
+    readyAt: 0,
+  }
 
   /**
    * The sync system, created **on first use** rather than when the plugin mounts.
@@ -611,7 +658,7 @@ export function apply(ctx) {
     if (!lock.acquired) log(`usage-badge is read-only here: ${lock.reason}`)
     const engine = new SyncEngine({
       dataDir,
-      store: lock.acquired ? store : null,
+      store: lock.acquired ? ensureOpen().store : null,
       log,
       config: document,
       state: document.state,
@@ -641,19 +688,20 @@ export function apply(ctx) {
     return system
   }
 
-  const { path: pricingSourcePath } = readRawPricing(pricingPaths)
-  if (pricingSourcePath === legacyPricingPath) {
-    log(`reading the price table from the pre-isolation path ${legacyPricingPath}; the next write moves it to ${pricingPath}`)
-  }
-  let pricing = readPricing(pricingPaths)
-  let rules = resolveHolidayRules(pricing.holidays)
+  let pricing = null
+  // A "nothing on" default so anything that reads `rules` before the first load (a log line, say)
+  // cannot trip over it; `ensureOpen()` replaces it with the real rules.
+  let rules = resolveHolidayRules(undefined)
   let snapshot = null
   let inFlight = null
   let official = null
+  /** The status of the warm-up pass, until the first snapshot has reported it. */
+  let firstStatus = null
 
   /** Serialize concurrent refreshes so a burst of polls folds the logs once. */
   function refreshOnce() {
     if (!inFlight) {
+      const { aggregator } = ensureOpen()
       inFlight = (async () => {
         const status = await aggregator.refresh()
         // Re-read pricing every pass so an edit applies without a restart.
@@ -871,7 +919,7 @@ export function apply(ctx) {
             // this reload is for) and the log says why, but the run is still what it was. `loadCache`
             // already swallows a store it cannot read; this covers everything else.
             try {
-              aggregator.loadCache({ quiet: true })
+              ensureOpen().aggregator.loadCache({ quiet: true })
             } catch (error) {
               log(`the folded view could not be reloaded after the sync: ${error?.message ?? error}`)
             }
@@ -906,7 +954,11 @@ export function apply(ctx) {
   }
 
   async function getSnapshot() {
-    const status = await refreshOnce()
+    const { store, aggregator } = ensureOpen()
+    // The first request reports the fold it caused, rather than immediately re-checking and reporting
+    // "nothing changed" — the numbers the caller is about to see came from that pass.
+    const status = firstStatus ?? (await refreshOnce())
+    firstStatus = null
     // Nothing changed and the previous payload is still fresh: reuse it rather
     // than re-costing every day on each poll.
     if (snapshot && status.folded === 0 && Date.now() - snapshot.generatedAt < SNAPSHOT_TTL_MS) return snapshot
@@ -1060,23 +1112,64 @@ export function apply(ctx) {
     log(`exit sync: ${instance.last?.result ?? outcome} — ${instance.last?.message ?? ''}`)
   }
 
-  async function warm() {
-    try {
-      const status = await refreshOnce()
-      // The SQLite store has already committed every session it folded; the JSON fallback
-      // batches, and a short-lived host would otherwise pay the full cold scan on every start.
-      aggregator.flush()
-      log(
-        `ready: ${aggregator.sessionCount} session(s) over ${status.files} log(s), folded ${status.folded} in ${status.ms}ms` +
-          `; cache: ${store.kind}` +
-          (rules.enabled ? `; holiday calendar on (${rules.holidays.size} holidays)` : ''),
-      )
-      if (rules.missingYears?.length) {
-        log(`holiday calendar has no data for ${rules.missingYears.join(', ')} — those days are treated as ordinary weekdays`)
-      }
-    } catch (error) {
-      log(`initial fold failed: ${error?.message ?? error}`)
+  /**
+   * The one warm-up pass: open, load the stored history, fold what changed, record the phases.
+   *
+   * It runs on the **first request**, not at mount. Mounting happens inside DSH's own startup and the
+   * plugin has no business doing I/O there — so nothing is opened until something actually asks for
+   * numbers, which is the interface's first poll, long after the harness is up. A fallback timer
+   * (`DSH_USAGE_BADGE_WARM_MS`) covers a host nobody is looking at; whichever happens first wins, and
+   * this is memoised so a burst of polls still only warms once.
+   */
+  let warmPromise = null
+  function warmOnce() {
+    if (warmPromise) return warmPromise
+    if (!boot.at) {
+      boot.at = Date.now()
+      boot.waitedMs = boot.at - boot.mountedAt
     }
+    warmPromise = (async () => {
+      const { store, aggregator } = ensureOpen()
+      try {
+        const status = await refreshOnce()
+        firstStatus = status
+        // The SQLite store has already committed every session it folded; the JSON fallback
+        // batches, and a short-lived host would otherwise pay the full cold scan on every start.
+        aggregator.flush()
+        const passMs = status.ms ?? 0
+        const loadMs = status.loadMs ?? 0
+        const listMs = status.listMs ?? 0
+        Object.assign(boot, {
+          loadMs,
+          listMs,
+          passMs,
+          // What is left of the pass once loading and listing are accounted for: the folding itself.
+          foldMs: Math.max(0, passMs - loadMs - listMs),
+          totalMs: Date.now() - boot.at,
+          files: status.files ?? 0,
+          sessions: aggregator.sessionCount,
+          folded: status.folded ?? 0,
+          tailed: status.tailed ?? 0,
+          bytesRead: status.bytesRead ?? 0,
+          readyAt: Date.now(),
+        })
+        log(
+          `ready in ${boot.totalMs}ms (${boot.waitedMs}ms after mount) — open ${boot.storeMs}ms, load ${boot.loadMs}ms,` +
+            ` list ${boot.listMs}ms, fold ${boot.foldMs}ms;` +
+            ` ${boot.sessions} session(s) over ${boot.files} log(s), ${boot.folded} folded` +
+            ` (${boot.tailed} from the tail only, ${Math.round(boot.bytesRead / 1024)} KB read)` +
+            `; cache: ${store.kind}` +
+            (rules.enabled ? `; holiday calendar on (${rules.holidays.size} holidays)` : ''),
+        )
+        if (rules.missingYears?.length) {
+          log(`holiday calendar has no data for ${rules.missingYears.join(', ')} — those days are treated as ordinary weekdays`)
+        }
+      } catch (error) {
+        log(`initial fold failed: ${error?.message ?? error}`)
+      }
+      return boot
+    })()
+    return warmPromise
   }
 
   async function handle(req, res) {
@@ -1084,7 +1177,12 @@ export function apply(ctx) {
     const route = url.pathname.slice(ROUTE_PREFIX.length) || '/'
 
     try {
+      // Every route needs the store and the price table; only the data routes additionally need the
+      // logs folded, so the fold waits for those (see `warmOnce`).
+      ensureOpen()
       if (route === '/summary' && (req.method === 'GET' || req.method === 'HEAD')) {
+        // The interface's first poll is what starts the plugin's work: see `warmOnce`.
+        await warmOnce()
         sendJson(res, 200, await getSnapshot())
         return
       }
@@ -1098,6 +1196,13 @@ export function apply(ctx) {
           sendJson(res, 400, { error: `year must be a four-digit calendar year, got ${JSON.stringify(year)}` })
           return
         }
+        // A year older than the loading window is only in the store, so this route needs the logs
+        // folded first — same warm-up the badge's own first request runs.
+        await warmOnce()
+        // This route never reports the warm pass, so do not let it be consumed by the next /summary:
+        // that one should judge the logs as they are when it asks.
+        firstStatus = null
+        const { store } = ensureOpen()
         const records = store.load({ since: `${year}-01-01`, until: `${year}-12-31` })
         const dayRows = mergeRecords(records)
         sendJson(res, 200, summarizeYear(dayRows, pricing, rules, year))
@@ -1105,6 +1210,7 @@ export function apply(ctx) {
       }
 
       if (route === '/config' && req.method === 'GET') {
+        const { store } = ensureOpen()
         const calendar = describeCalendar(rules)
         // The bundled table is reported separately from the resolved rules: a
         // deployment with the calendar off still needs to see what data is
@@ -1160,6 +1266,9 @@ export function apply(ctx) {
             // neither exists, so the built-in template is in force.
             pricingSource: raw.path,
           },
+          // How the last start spent its time. A slow start is then attributable instead of a
+          // feeling: the panel shows this line, and the same numbers go to the log.
+          boot: { ...boot },
         })
         return
       }
@@ -1367,16 +1476,40 @@ export function apply(ctx) {
     // asynchronous, and a value read after it would be whatever the environment holds by then — which a
     // test that sets an override for exactly this mount would already have taken away.
     const startupDelay = delayFor('DSH_USAGE_BADGE_STARTUP_SYNC_MS', STARTUP_SYNC_DELAY_MS)
+    // Same reasoning for the fallback warm-up: read the knob now, not inside the timer callback.
+    const warmDelay = delayFor('DSH_USAGE_BADGE_WARM_MS', STARTUP_WARM_DELAY_MS)
     // Unloading before the first fold finishes used to schedule the first sync *after* the unload: the
     // callback ran anyway, took the lock back, and synced through a store that had already been closed
     // (`statement has been finalized`), leaving a lock file behind for a host that was gone.
     let disposed = false
-    void warm().then(() => {
+    let warmTimer = null
+    /**
+     * Everything the plugin does automatically, in one place: warm the fold, then start the automatic
+     * sync and the remote-device read.
+     *
+     * The fold itself is **not** what this timer is for — the interface's first request does that
+     * (`warmOnce`), and that request cannot arrive before the harness is up. This is only the
+     * fallback for a host nobody is looking at, which is why it waits a moment: nothing here belongs
+     * in DSH's boot path. A zero delay means "warm on mount", which is what a test wants.
+     */
+    let scheduled = false
+    const begin = () => {
+      warmTimer = null
       if (disposed) return
-      scheduleStartupSync(startupDelay)
-      // Fire and forget: this only fills in what the server holds, for the panel's next read.
-      void refreshRemoteDevices()
-    })
+      void warmOnce().then(() => {
+        if (disposed) return
+        if (!scheduled) {
+          scheduled = true
+          scheduleStartupSync(startupDelay)
+          // Fire and forget: this only fills in what the server holds, for the panel's next read.
+          void refreshRemoteDevices()
+        }
+      })
+    }
+    if (warmDelay > 0) {
+      warmTimer = setTimeout(begin, warmDelay)
+      warmTimer.unref?.()
+    } else begin()
     // The disposer is **async on purpose**, and everything below depends on the order:
     //
     //   1. stop automatic work that would fire into a process that is going away;
@@ -1390,13 +1523,18 @@ export function apply(ctx) {
       disposed = true
       // Any pending automatic work is dropped on unload: a push that fires while the host is going away
       // would write state for a process that no longer exists.
+      if (warmTimer) clearTimeout(warmTimer)
       if (pricingPushTimer) clearTimeout(pricingPushTimer)
       if (startupSyncTimer) clearTimeout(startupSyncTimer)
       if (system?.running) log('unloading while a sync is in flight; it stops at its next step boundary')
-      try {
-        await syncOnExit()
-      } catch (error) {
-        log(`exit sync failed: ${error?.message ?? error}`)
+      // A host that was never asked for numbers never opened anything: there is no store to close, no
+      // lock to hand back, and nothing worth publishing on the way out.
+      if (opened) {
+        try {
+          await syncOnExit()
+        } catch (error) {
+          log(`exit sync failed: ${error?.message ?? error}`)
+        }
       }
       // **And the lock is handed back.** Not releasing it leaves `host.lock` naming this dead process, and a
       // re-mount inside the same process — a hot reload, or a test mounting the same home twice — is then
@@ -1412,10 +1550,13 @@ export function apply(ctx) {
         system.engine.abort()
         system.engine.release()
       }
+      // Unconditional, and `releaseLock` itself only removes a lock whose pid is this process: a lock left
+      // behind by an earlier mount of this same process (a hot reload) is ours to clean up even when this
+      // mount never created a sync system.
       releaseLock(dataDir)
-      aggregator.close()
+      if (opened) opened.aggregator.close()
     }
-  }, 'usage-badge: warm the fold, schedule the first sync, and close the cache on unload')
+  }, 'usage-badge: warm the fold on first use, schedule the first sync, and close the cache on unload')
 
   log(`mounted on ${ROUTE_PREFIX} (home: ${home}; data: ${dataDir})`)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-usage-badge",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "DeepSeek Harness 的用量徽标插件：侧边栏底部一行显示当天的 token 总量与估算费用，点开可看 24 小时 / 近 7 日 / 近 30 日 / 近 12 个月 / 按年用量，按 provider 筛选，并按 DeepSeek 官方定价与中国法定节假日计价。A usage badge plugin for DeepSeek Harness: today's tokens and estimated spend in the sidebar, with 24h / 7d / 30d / 12-month and per-year charts, official DeepSeek pricing and Chinese public holidays.",
   "type": "module",
   "main": "lib/index.js",