dsh-usage-badge 0.1.12 → 0.1.13

package/README.md

@@ -83,7 +83,7 @@ dsh plugin --profile web remove dsh-usage-badge
 
 ## 已知限制
 
-- **首次启动要冷扫一遍全部会话日志**（本机 338 份 / 348 MB 实测约 19 秒，随机器负载浮动；按解码字节数让出事件循环，最长一次阻塞约 0.4 秒，宿主启动与界面都不会被卡住，徽标先显示「…」再填上数字）。**之后每次启动只读增量**：只解压新追加的那几帧 —— 同一台机器实测「1 个日志、2 KB、57 ms」，没有任何变化时「0 个、16 ms」。
+- **首次启动要冷扫一遍全部会话日志**（本机 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

@@ -353,6 +353,24 @@ dsh-usage-badge
 
 **等价性核对（真机）**：同一份 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()`，所以只会热身一次。
+
 ### `按年` 视图：年份列表属于数据，不属于代码
 
 历史不删，就迟早要看更早的年。这一年视图有三条决定：
@@ -399,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` 之后**不再被读**）、**读不出来的缓存文件被改名保留并新建一个**、**更新版本的库只读使用且绝不改名**、加载窗口必须大于快照窗口这条不变量、**增量折叠**（重启只读新追加的字节且读的字节数正好等于追加量、两天相加不翻倍、无变化时读 0、游标是日志大小而不是最早那天的戳、半行不算而补全后只算一次），以及 `按年` 路由（三年以前那一年照样读得到、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/` 的快照逐字段比对，确认官方页面仍能解析、价格未变 |

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

@@ -444,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())
@@ -487,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
   }
 
@@ -507,11 +517,20 @@ 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, tailed:number, bytesRead: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
@@ -602,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, tailed, bytesRead, 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,24 +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` +
-          ` (${status.tailed ?? 0} of them from the tail only, ${Math.round((status.bytesRead ?? 0) / 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}`)
+  /**
+   * 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) {
@@ -1085,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
       }
@@ -1099,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))
@@ -1106,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
@@ -1161,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
       }
@@ -1368,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;
@@ -1391,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
@@ -1413,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.12",
+  "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",