dsh-usage-badge 0.1.6 → 0.1.8

package/README.md

@@ -85,7 +85,7 @@ dsh plugin --profile web remove dsh-usage-badge
 - **历史依赖日志，但日志变短不再吃掉历史**：日志被删掉后靠缓存继续计入；缓存也丢了，那段历史就没了。同一个会话的日志**变短或还原成更早的备份**时，缓存会**把更完整的那份留着**（折叠结果变小就只作为备份副本存下，统计仍用完整的那份），要等日志真的更全、却不再包含某一天，那天才会被丢掉。**例外是改名**：会话是按「日志所在目录」识别的，把某个会话目录改名会让同一份用量各算一份（见下）。DSH 自己从不裁日志：格式升级时它另写一代新文件、旧代保留，而实测换代后统计结果逐项相同。
 - **日粒度区间仍只覆盖最近一年**：`近 7 日` / `近 30 日` / `近 12 个月` 与它们下面的滚动热力图都基于快照的最近 400 天。要看更早的日子，用 **`按年`**：那一档的月度合计、年度总额与**自然年热力图**都是直接查缓存库的，任何一年都在。
 - **只统计 DSH 记进日志的调用**：某个东西直接请求外部 API 且不向 DSH 上报 usage，这部分统计不到。
-- **云同步已经能用了**：把每天的用量与价格表备份到一台 WebDAV 服务器（Digest 认证），多台机器互相合并 —— 弹窗里多了「同步」页签：填地址、用户名、密码，点「测试连接」再「立即同步」。开启之后它还会**在启动后自己同步一次**，并在你**改完价格表几秒后自动推送**；服务器连不上时本地照常工作，绝不会因为同步失败而丢掉一次编辑。见 [docs/design-notes.md](docs/design-notes.md) 的「云同步（WebDAV + Digest）—— 设计」一节。
+- **云同步已经能用了**：把每天的用量与价格表备份到一台 WebDAV 服务器（Digest 认证），多台机器互相合并 —— 弹窗里多了「同步」页签：填地址、用户名、密码，点「测试连接」再「立即同步」。开启之后**三条自动触发**都会工作：**打开 DSH 后 8 秒自动同步一次**、**关闭 DSH 前自动同步一次**（最多等 3.5 秒，不会拖着不退出）、**改完价格表几秒后自动推送**；前两条在页签里各有一个开关。服务器连不上时本地照常工作，绝不会因为同步失败而丢掉一次编辑。**同步来的用量立刻计入**：拉取结束后徽标、日区间、热力图在同一次运行里就更新，不用重启 DSH（「按年」本来就是直查库）。见 [docs/design-notes.md](docs/design-notes.md) 的「云同步（WebDAV + Digest）—— 设计」一节。
   - 每台机器有自己的**设备名**，它只决定「这台机器的新数据写进哪个分区」，**不是**会话身份；远端所有设备的历史都会合并，所以**改设备名不会让用量累增**。但设备名在服务器上必须**唯一**：两台机器用同一个名字会互相覆盖分片，插件会拒绝发布并在面板里说明。
   - **删除不会跨设备传播**：本机删掉日志后，新机器不会再拉到那段历史，但**已经拉过它的机器**库里那份仍然在（远端从不因为本机的改动而删东西）。
 - **会话是按日志目录识别的**：把某个会话目录改名，同一份用量会被当成两个会话、各算一份（实测 ¥1.5 → ¥3.0）。删日志、日志变短、还原旧备份这三种情况都不会丢历史。**这不包括「设备」字段** —— 那只是这台机器往哪个分区写，改设备名不会让用量累增。
@@ -95,7 +95,7 @@ dsh plugin --profile web remove dsh-usage-badge
 
 ```sh
 npm install   # 只为测试装 react / react-dom
-npm test      # 11 个套件 845 条断言：包契约、定价、节假日、官方定价解析、缓存存储、同步分片、同步编排、宿主同步接线、自动触发、WebDAV(Digest)、浏览器半渲染
+npm test      # 11 个套件 865 条断言：包契约、定价、节假日、官方定价解析、缓存存储、同步分片、同步编排、宿主同步接线、自动触发、WebDAV(Digest)、浏览器半渲染
 ```
 
 云同步的前五步已经在真实的 `bytemark/webdav` 容器上核对通过。要自己核对一遍：

package/docs/design-notes.md

@@ -410,13 +410,17 @@ npm test
 - **`/usage-badge/sync` 路由**：`GET` 状态与配置（凭据只回 6 位前缀 + `hasCredential`）、`PUT|POST` 写配置（明文密码**当场**在宿主半里算成 HA1，也可以直接粘贴 HA1）、`POST /sync/test` 只做连接自检（连不上会**失败但不抛**）、`POST /sync/run` 跑一次。三个写入口都要求 loopback。
 - **面板第三个页签「同步」**：地址 / 用户名 / 密码 / 设备（带远端设备下拉 —— 那就是「重装后并入已有设备」的入口）/ 首次拉取年数 / 自签名证书开关，加「保存」「测试连接」「立即同步」，以及一段状态（上次结果、已发布月份、远端设备与各自的月份数、冲突文件提示、本机设备名与凭据状态）。**凭据字段永远回空**：页面能知道「配了」，永远不知道「是什么」。
 - **`HOST_API_VERSION` 6 → 7**，`REQUIRED_HOST_API` 同步跟上（`client.render.mjs` 有一条断言钉住两半相等）。
-- 插件**挂载时不创建任何东西**：`sync.json`、`host.lock` 都是第一次碰「同步」时才出现（拿锁 = 这个进程可以写）。这条有断言钉着，否则每个从不用同步的安装也会多出两个文件。
+- 插件**挂载时不创建任何东西**，**打开页签只看一眼也不创建**：`sync.json` 与 `host.lock` 都是第一次**真正决定了什么**（保存 / 测试连接 / 立即同步）时才出现（拿锁 = 这个进程可以写）。两条都有断言钉着 —— 否则每个从不用同步的安装会多出两个文件，而「我只是点开看一眼，它就写了两个文件」是同一件事的第二种形态。只读状态下的 `writable` 仍如实回答：`readLock` **读**一次锁文件（不写），并且**完全镜像 `acquireLock` 的判定**（任何活着的锁都算被占用，包括自己 pid 持有的），所以面板不会承诺一次引擎随后会拒绝的写入。
 
-**自动触发**（`lib/index.js`）：
+**自动触发**（`lib/index.js`）：一共三条，都可以在面板里开关（前两条）或由配置控制。
 
-- **启动后延迟一次**（`STARTUP_SYNC_DELAY_MS`，默认 8 秒）：只在**同步已经配置且开启**时才排期，所以从没开过同步的 home 不会因此多出 `sync.json`、锁或网络请求；延迟是为了让冷折叠与首屏先走完 —— 一上来就同步会和「让徽标先显示东西」抢时间；锁不在本实例手上时**跳过并说明**，而不是把锁从别人手里抢过来。
+- **启动后延迟一次**（`STARTUP_SYNC_DELAY_MS`，默认 8 秒，开关 `onStart`）：只在**同步已经配置且开启**时才排期，所以从没开过同步的 home 不会因此多出 `sync.json`、锁或网络请求；延迟是为了让冷折叠与首屏先走完 —— 一上来就同步会和「让徽标先显示东西」抢时间；锁不在本实例手上时**跳过并说明**，而不是把锁从别人手里抢过来。
+- **退出前同步一次**（`EXIT_SYNC_BUDGET_MS`，默认 3.5 秒，开关 `onExit`）：这是**真的被 await 的**，不是「发了就希望它跑完」。依据是查清了 DSH 的关闭链条（见下）：桌面端给宿主子进程发 `{type:'shutdown'}`，宿主 `await application.shutdown.shutdown(0)`，而 `createProcessShutdown` 是 `Promise.resolve().then(dispose).then(...)`，cordis 的 `dispose()` 又会收集各 effect disposer 的返回值、是 thenable 就 `task = result` 串下去 —— 所以**本插件的 disposer 返回一个 promise 就会被等到**（上限 `PROCESS_SHUTDOWN_TIMEOUT_MS = 5000`，之后 `process.exit`；桌面端另外最多等 10 秒子进程退出）。
+  - 顺序因此必须是：**先同步**（此时 store 还开着、锁还在手上）→ 再交还锁 → 最后 `aggregator.close()`。
+  - 预算到了就 `engine.abort()`：运行在**下一个阶段边界**停下，不会留下半张清单（上传走临时名 + 最后写清单）。预算为 0 表示「没时间做这件事」，测试与调试用它关掉这条。
+  - 配置从**磁盘**读：这一轮会话可能从没碰过同步（上次配好、这次没打开面板就关掉），那种情况下退出同步要自己把 system 建起来 —— 否则「配好了但没打开面板」就等于永远不同步。
 - **价格表变更后推一次**（`PRICING_PUSH_DELAY_MS`，默认 3 秒，去抖）：改完一行再改下一行是**一个**意图，所以等一小会儿；推的是 `pushPricing()` —— **只动价格表，不跑整轮**（价格编辑与分片无关，整轮会把整个远端清单拖进来）。它是 fire-and-forget：**连不上服务器绝不能让本地编辑失败**，留下的状态由面板报告。
-- 两个延迟都可以用环境变量覆盖（`DSH_USAGE_BADGE_STARTUP_SYNC_MS` / `DSH_USAGE_BADGE_PRICING_PUSH_MS`），这是 `test/sync-triggers.verify.mjs` 不必真等几秒的办法。**启动延迟在 `apply()` 里同步读取**，不在 warm 的回调里读 —— warm 是异步的，等它跑完再读，拿到的会是「那之后」的值（测试设的覆盖值那时已经被撤掉，于是它又变回 8 秒，测试只能干等）。
+- 三个时间都可以用环境变量覆盖（`DSH_USAGE_BADGE_STARTUP_SYNC_MS` / `DSH_USAGE_BADGE_EXIT_SYNC_MS` / `DSH_USAGE_BADGE_PRICING_PUSH_MS`），这是 `test/sync-triggers.verify.mjs` 不必真等几秒的办法。**启动延迟在 `apply()` 里同步读取**，不在 warm 的回调里读 —— warm 是异步的，等它跑完再读，拿到的会是「那之后」的值（测试设的覆盖值那时已经被撤掉，于是它又变回 8 秒，测试只能干等）。
 - 卸载时两个待触发的定时器都会被清掉，**锁也会交还**：宿主正在退出还去推一次，会为一个已经不存在的进程写状态；而留着锁会让下一次挂载（热重载、或同一进程里再挂一次）被自己的锁拒绝。
 
 ### 第六轮：一轮对抗性审查找到并修掉的问题
@@ -620,9 +624,10 @@ storages/usage-badge/sync.json         # 同步配置与状态
 
 - **来源维度**：`days` / `sessions` 增加一列来源（本设备 / 某个远端设备）。本地 fold 只能写本设备的行；远端导入的行**只读**，永不被本地 fold 波及 —— 否则「B 下载了 A 的历史，B 本地没有那些日志」会让 B 的下一轮 fold 把它们删光。
 - **导入远端行**时：若已存在同一 `(session, date)` 且那份的 `(maxSeq, fileSize)` 更大，则跳过（**旧机器不能覆盖新数据**）；否则写入。
-- **导入之后必须重载聚合器**：`refresh()` 的游标没变，不会自己发现库里的新行，否则同步来的历史要等到重启才可见。
+- **导入之后必须重载聚合器**：`refresh()` 的游标没变，不会自己发现库里的新行，否则同步来的历史要等到重启才可见。实现是 `runSync()` 里 `engine.run()` 返回之后的 `aggregator.loadCache({ quiet: true })` 加 `snapshot = null`，条件是引擎自己报的 **`storeChanged`**（真的是库里写进或删掉了行才为真，取值来自 `intakeRows()`/`dropSourceMonth()` 的返回值 —— 重放一份库里已经全有的分片写 0 行，就不该为此付一次全量重载，实测 16k 行的库一次约 0.9 秒）。宿主还要 `!system.syncAbort`：正在关闭的宿主不能去读一个马上要 close 的库（宽松条件实测会打印 `cache load failed: statement has been finalized`），而**因为别的原因被中止**（未来的「取消同步」）仍会重载，所以 `aborted` 分支也带上 `storeChanged`。**撤回（墓碑删行）走的是同一段**，否则「别人撤回了，你这里还在多算」会一直算到重启为止。`test/host-sync.verify.mjs` 的两个方向、**两个后端**都钉着。
+- **两个后端对「这个会话空了」必须给出同一种形状**：SQLite 的墓碑是 `DELETE FROM days`，`sessions` 行还在，于是 `load()` 返回一条**零行记录**；JSON 后端原先在最后一行被删时把整个 session 条目 `delete` 掉，`load()` 于是**少返回一条**。重载是 merge 语义（不能改成替换：只读库的 `put` 返回 null，内存里那次折叠是唯一的一份），它分不出「空了」和「从来没有过」——所以在 JSON 后端上墓碑撤回一直算到重启。现在 JSON 也保留空条目（`days: []`）。这是**只有两个后端都跑**才看得见的差异：契约套件（`cache.verify.mjs`）两个后端都跑却放过了它，因为它在「宿主重载」这一层，所以 `host-sync.verify.mjs` 也改成两个后端各跑一遍。
 - **「变短」要说出来**：折叠时若发现某会话的天数或总量变小，记一行日志、并在面板标一次「这段历史已脱离日志，缓存里仍保留」，让使用者能分辨「格式升级」和「真丢了东西」。
-- 读路径不变：`load()` 按窗口返回已 resolve 的记录；`按年` 仍是直接查库（[index.js:614-623](../lib/index.js#L614-L623)）。
+- 读路径不变：`load()` 按窗口返回已 resolve 的记录；`按年` 仍是直接查库（[index.js:1088-1099](../lib/index.js#L1088-L1099) —— 这条链接此前指向 `syncSystem()`，顺手改正）。
 
 ### 远端布局
 
@@ -783,9 +788,9 @@ storages/usage-badge/host.lock     # { pid, startedAt, instanceId, hostname, at
 | `test/webdav.verify.mjs` ✅ **已实现（60 项）** | 纯函数：RFC 2617 向量（`Mufasa` 例子逐字段）、无 `qop` 的 RFC 2069 写法、`stale=true` 重试、UTF-8 与带逗号的 realm、`uri` 必须是请求行里的原始路径（含 `%XX`）；以及对着假服务端的端到端：七个方法、`MOVE` 的 `Overwrite: F` 保护、404 语义、错误密码 / 一直挑战 / `SHA-256` / `Basic`-only 的四种失败各自报对原因 |
 | `test/webdav-server.mjs` ✅ **已实现（harness）** | 一个**假 WebDAV 服务端**（`node:http`，真发 Digest 挑战并按 `MD5(HA1:nonce:nc:cnonce:qop:HA2)` 校验，检查 `nc` 不回退、`uri` 与请求行一致），可切换 `qop: null`、`staleOnce`、`challengeEveryRequest`、`algorithm`、`scheme` 等恶意行为 |
 | `test/sync.verify.mjs` ✅ **已实现** | 分片与两个方向：路径／键的卫生（设备 id 与 `YYYY-MM` 不能带斜杠或穿越）、分片往返（stamp 与桶逐项保留）、**`source` 被改写成发布设备**、版本不符的分片与清单被具名拒绝、只发布本机 `current` 行（`fallback` 与别人的行都不发）、内容 sha256 决定「未变的月不重传」、首次拉取的窗口只限制拉取、`rowsToRecords()` 取最全 stamp、以及一次完整 trip（导出 → 空库导入 → 数字逐项相同、且**再导入一次不写任何东西**）。行模型的语义（截断/回滚/跨来源/从不删）由 `cache.verify.mjs` 的 section 8/9 覆盖，不在这里重测 |
-| `test/sync-engine.verify.mjs` ✅ **已实现** | 端到端两设备：发布只带自己的月份、第二次运行不重传、另一台空库拉取后**数字与归属都对**、同一天两个设备相加、缺分片报 `partial` 且不记为已应用、补上后自动重试、owner 锁挡住第二个宿主、`sync.json` 里是 HA1 而非明文、以及**配置写入不会覆盖上一次的状态** |
+| `test/sync-engine.verify.mjs` ✅ **已实现** | 端到端两设备：发布只带自己的月份、第二次运行不重传、另一台空库拉取后**数字与归属都对**、同一天两个设备相加、缺分片报 `partial` 且不记为已应用、补上后自动重试、owner 锁挡住第二个宿主、`sync.json` 里是 HA1 而非明文、**配置写入不会覆盖上一次的状态**，以及三条「run 没走到 `ok`、但库里已经变了」的路径都报 `storeChanged`：**拉到行之后发布失败**、**分片在途中被中止（`aborted`）**、**分片行数比清单少（导入照做、失败照报）**；再加上「重放一份已经全有的分片写 0 行 ⇒ `storeChanged: false`」（宿主不必为此重载） |
 | `test/sync.live.mjs` ✅ **已实现（联网）** | 真实的 `bytemark/webdav` 容器上跑完整流水线：A 发布一天 → B 空库拉取并计数 → 再同步一次零传输 → 清理自己建的两个设备目录（**不删 `usage-badge/` 本身**）。URL / 账号 / 密码从环境变量取，缺失就跳过 |
-| `test/host-sync.verify.mjs` ✅ **已实现** | 宿主半的接线：挂载**不创建任何东西**、读状态不落文件、`POST /sync` 把明文算成 HA1 且**明文永不落盘**、响应只回前缀、patch 保存不丢别的字段、非法 URL / 非法设备 id 被拒、连不上的服务器**失败但不抛**、一次真实 run 走完整条路（发布 + 建目录 + 状态回填）、以及第二个实例拿到同一份配置但**被拒绝同步** |
+| `test/host-sync.verify.mjs` ✅ **已实现** | 宿主半的接线：挂载**不创建任何东西**、读状态不落文件、`POST /sync` 把明文算成 HA1 且**明文永不落盘**、响应只回前缀、patch 保存不丢别的字段、非法 URL / 非法设备 id 被拒、连不上的服务器**失败但不抛**、一次真实 run 走完整条路（发布 + 建目录 + 状态回填）、第二个实例拿到同一份配置但**被拒绝同步**、以及**另一台机器同步来的用量在同一次进程里就计入徽标与日窗口（不重启）**——撤回方向也一样，且**两个后端各跑一遍**（这条差异只在 JSON 回退上出现，见「本地缓存」一节） |
 | `test/sync-triggers.verify.mjs` ✅ **已实现** | 两条自动触发：没配过同步的 home **什么都不做**（不建 `sync.json`、不拿锁、不发请求）；配好并开启的 home 启动后**自己同步一次**（服务器上出现设备目录、状态记下那次运行）；改一次价格表会**自动发布**（带上那次编辑、带设备副本、且不拖任何分片工作）；服务器连不上时本地编辑**照样成功**、本地表照样生效 |
 | ⏳ **未做**：跨机同 `deviceId` 的 `instanceId` 报警 | 设计里写了、代码里还没接；本机并发的 owner 锁已经实现并测过 |
 | `test/webdav.live.mjs` ✅ **已实现（联网）** | 对着真实的 `bytemark/webdav` 容器跑：`OPTIONS`（打 realm 与 `DAV` 能力）→ `MKCOL` → `PUT` → `GET` 逐字节比对 → `PROPFIND` → `MOVE`（含撞名 412）→ `DELETE`，并在结尾清理自己创建的目录。URL / 账号 / 密码从环境变量取，缺失就跳过并打印怎么起容器 |

package/lib/cache-store.js

@@ -318,10 +318,14 @@ function createJsonStore({ path, log }) {
         if (!record) continue
         const keep = record.rows.filter((row) => !(rowSource(row) === source && String(row.date).startsWith(month)))
         removed += record.rows.length - keep.length
-        if (keep.length === 0) {
-          delete doc.sessions[sessionId]
-          continue
-        }
+        // A session left with **no rows keeps its entry**, empty. The SQLite backend's `sessions` row
+        // survives the same delete (`DELETE FROM days`), and the two backends have to answer this question
+        // the same way: `load()` returning a session with no rows means "this session is now empty", while
+        // dropping the entry means "there was never such a session" — and a reader that merges what it is
+        // given instead of replacing its world with it cannot tell those apart. The host's `loadCache` is
+        // exactly that reader (it must not drop a fold the store could not accept — a read-only store's
+        // `put` returns null, and the fold in memory is then the only copy), so a dropped entry here left
+        // the withdrawn month counted in memory until the host restarted.
         entry.days = keep.map((row) => ({ ...row }))
       }
       if (removed > 0) {

package/lib/client.js

@@ -2151,9 +2151,13 @@ window.__ModuleLoader__.load({
       fill('realm', config.realm)
       fill('deviceId', config.deviceId)
       if (config.windowYears !== undefined && config.windowYears !== null) fill('windowYears', String(config.windowYears))
-      // A checkbox has no "empty" to leave alone: it is on only when the saved configuration says so, and
-      // turning it back on is a deliberate act the person can repeat.
+      // A checkbox has no "empty" to leave alone: it is proposed from the saved configuration, and the
+      // component applies the patch once per configuration. `onStart`/`onExit` default to **on**, so anything
+      // other than an explicit `false` means on — an older `sync.json` has no such field and must not read as
+      // "off".
       if (config.allowInsecureTls) patch.allowInsecureTls = true
+      if (config.onStart !== false) patch.onStart = true
+      if (config.onExit !== false) patch.onExit = true
       return patch
     }
 
@@ -2181,6 +2185,9 @@ window.__ModuleLoader__.load({
       // "fill only what is empty" would then leave a saved 0 or 30 looking like the default forever.
       const [windowYears, setWindowYears] = React.useState(String(initialSync?.config?.windowYears ?? ''))
       const [allowInsecureTls, setAllowInsecureTls] = React.useState(Boolean(initialSync?.config?.allowInsecureTls))
+      // The two automatic triggers. Both default to on, so a configuration that predates them reads as on.
+      const [onStart, setOnStart] = React.useState(initialSync?.config?.onStart !== false)
+      const [onExit, setOnExit] = React.useState(initialSync?.config?.onExit !== false)
       const [state, setState] = React.useState('idle')
       const [note, setNote] = React.useState('')
       const [devices, setDevices] = React.useState(null)
@@ -2238,7 +2245,7 @@ window.__ModuleLoader__.load({
         // The checkbox belongs in the signature too: it is the one field whose saved value can change from
         // `true` to `false`, and without this the signature would look unchanged and the box would keep
         // showing the old answer.
-        const signature = `${saved.url ?? ''}\u0000${saved.username ?? ''}\u0000${saved.realm ?? ''}\u0000${saved.deviceId ?? ''}\u0000${saved.windowYears ?? ''}\u0000${Boolean(saved.allowInsecureTls)}`
+        const signature = `${saved.url ?? ''}\u0000${saved.username ?? ''}\u0000${saved.realm ?? ''}\u0000${saved.deviceId ?? ''}\u0000${saved.windowYears ?? ''}\u0000${Boolean(saved.allowInsecureTls)}\u0000${saved.onStart !== false}\u0000${saved.onExit !== false}`
         if (filledFrom.current === signature) return
         filledFrom.current = signature
         const patch = fillSyncForm(status, { url, username, realm, deviceId, windowYears })
@@ -2248,8 +2255,10 @@ window.__ModuleLoader__.load({
         if (patch.deviceId !== undefined) setDeviceId(patch.deviceId)
         if (patch.windowYears !== undefined) setWindowYears(patch.windowYears)
         // Two-way, unlike the text fields: a checkbox has no empty state to protect, and the saved answer is
-        // the answer. `formDirty` still stops this from fighting someone who has just clicked it.
+        // the answer. `formDirty` still stops this from fighting someone who has just clicked one.
         setAllowInsecureTls(Boolean(saved.allowInsecureTls))
+        setOnStart(saved.onStart !== false)
+        setOnExit(saved.onExit !== false)
       }, [status, url, username, realm, deviceId, windowYears])
 
       // While a run is in flight the panel shows what the host is doing, so it asks again. The condition
@@ -2269,7 +2278,7 @@ window.__ModuleLoader__.load({
         setFailNote('')
         try {
           const sentPassword = password !== ''
-          const payload = { url, username, realm, deviceId, windowYears: Number(windowYears), allowInsecureTls }
+          const payload = { url, username, realm, deviceId, windowYears: Number(windowYears), allowInsecureTls, onStart, onExit }
           if (sentPassword) payload.password = password
           const response = await fetch('/usage-badge/sync', {
             method: 'POST',
@@ -2478,6 +2487,24 @@ window.__ModuleLoader__.load({
                   }),
                   'HTTPS 但证书不受信任时才勾',
                 ),
+                row(
+                  '打开时同步',
+                  h('input', {
+                    type: 'checkbox',
+                    checked: onStart,
+                    onChange: (event) => { formDirty.current = true; setOnStart(event.target.checked) },
+                  }),
+                  'DSH 启动 8 秒后自动同步一次（等冷折叠与首屏先走完）',
+                ),
+                row(
+                  '退出时同步',
+                  h('input', {
+                    type: 'checkbox',
+                    checked: onExit,
+                    onChange: (event) => { formDirty.current = true; setOnExit(event.target.checked) },
+                  }),
+                  '关闭 DSH 前自动同步一次，最多等 3.5 秒（客户端整体只给 5 秒）',
+                ),
                 h(
                   'div',
                   { className: 'dub-form-actions' },

package/lib/fold.js

@@ -302,8 +302,15 @@ export function createAggregator({ sessionsRoot, store, log = () => {} }) {
    * The store has already resolved the copies it may hold for a `(session, date)` down to the
    * fuller log version; what arrives here is the merged view, with the raw `rows` alongside for
    * anything that needs to know where a day came from.
+   *
+   * It is also the only way rows that **arrived from another device** can enter this process: `refresh()`
+   * walks the logs, and a synced row has no log here to be discovered by. That is why the host calls it
+   * again after a sync run touches the store, and why that second call passes `quiet` — a reload is
+   * bookkeeping, not news, and a line per sync would read like the cache was being rebuilt from scratch.
+   *
+   * @param {{quiet?:boolean}} [options] `quiet` suppresses the summary line (the reload after a sync).
    */
-  function loadCache() {
+  function loadCache({ quiet = false } = {}) {
     let loaded
     try {
       loaded = store.load()
@@ -323,7 +330,7 @@ export function createAggregator({ sessionsRoot, store, log = () => {} }) {
       })
     }
     mergeDays()
-    log(`cache loaded: ${records.size} session(s) from ${store.kind}`)
+    if (!quiet) log(`cache loaded: ${records.size} session(s) from ${store.kind}`)
     return records.size > 0
   }
 

package/lib/index.js

@@ -22,7 +22,7 @@ import { join } from 'node:path'
 
 import { createCacheStore } from './cache-store.js'
 import { createAggregator, mergeRecords, resolveDshHome } from './fold.js'
-import { SyncEngine, acquireLock, readSyncDocument, releaseLock, safeDeviceId } from './sync.js'
+import { SyncEngine, acquireLock, lockIsStale, readLock, readSyncDocument, releaseLock, safeDeviceId } from './sync.js'
 import { normalizeWebdavUrl } from './webdav.js'
 import { describeCalendar, loadBundledTable, resolveHolidayRules } from './holidays.js'
 import { OFFICIAL_SOURCES, applyOfficialPricing, fetchOfficialPricing } from './official-pricing.js'
@@ -90,6 +90,16 @@ export const PRICING_PUSH_DELAY_MS = 3000
 /** How long after startup the first automatic sync runs, when sync is enabled. */
 export const STARTUP_SYNC_DELAY_MS = 8000
 
+/**
+ * How long a sync on the way out may take before it is told to stop.
+ *
+ * The application's whole teardown gets 5 s (`PROCESS_SHUTDOWN_TIMEOUT_MS`), and this plugin is one of
+ * several things being disposed — so it takes most of that and leaves the rest alone. Long enough for a
+ * real sync against a reachable server (a few hundred milliseconds for a month of changes), short enough
+ * that quitting never feels stuck.
+ */
+export const EXIT_SYNC_BUDGET_MS = 3500
+
 /**
  * How long the panel waits for a status read before it is told the answer is not ready.
  *
@@ -677,6 +687,10 @@ export function apply(ctx) {
       deviceLabel: String(config.deviceLabel ?? ''),
       windowYears: Number(config.windowYears) || 0,
       instanceId: String(config.instanceId ?? ''),
+      // Defaults are `true`, so an existing `sync.json` that predates these fields reads as "both on" —
+      // which is what the design promises: sync, once switched on, keeps itself current.
+      onStart: config.onStart !== false,
+      onExit: config.onExit !== false,
       hasCredential: Boolean(ha1),
       // Only a real HA1 counts. `password` and `passwordHash` are fields an older build could leave behind,
       // and `connect()` cannot use either — claiming a credential exists would enable 立即同步 and then
@@ -734,27 +748,44 @@ export function apply(ctx) {
   }
 
   async function syncStatus() {
-    // Reading the status must not create anything either, so an untouched install answers with the
-    // sensible defaults rather than acquiring a lock it has no intention of using.
+    // Reading the status must not create anything: someone opening the tab to see what it says has not
+    // decided to use sync yet. So the system (and with it the lock and `sync.json`) is only created by an
+    // action that actually decides something — save, test, run — and this branch answers from the files on
+    // disk plus a **read** of the lock.
     if (!system) {
       const document = readSyncDocument(dataDir, log)
+      const state = document.state ?? {}
+      const pulled = {}
+      for (const context of Object.keys(state.held ?? {})) {
+        const device = context.split('/')[0]
+        pulled[device] = (pulled[device] ?? 0) + 1
+      }
+      // Whose lock is it? Answering "may this instance write" takes no writing: `readLock` looks, and this
+      // mirrors exactly what `acquireLock` would decide — **any** live lock blocks, including one this same
+      // pid holds, because that is the answer `acquireLock` gives and the panel must not promise a write the
+      // engine would then refuse. A stale lock is not a block: it would be taken over.
+      const owner = readLock(dataDir)
+      const blocking = owner && !lockIsStale(owner) ? owner : null
       return {
-        config: safeSyncConfig({ ...document, hasCredential: Boolean(document.ha1 || document.passwordHash || document.password) }),
-        writable: true,
-        lock: null,
+        config: safeSyncConfig(document),
+        writable: !blocking,
+        lock: blocking ? { reason: `this data directory is open by another DSH instance (pid ${blocking.pid} on ${blocking.hostname || 'this host'})`, owner: blocking, pid: process.pid } : null,
         running: false,
         last: {
-          result: document.state?.lastResult || 'never',
-          message: document.state?.message ?? '',
-          at: Number(document.state?.lastSyncAt) || 0,
+          result: state.lastResult || 'never',
+          message: state.message ?? '',
+          at: Number(state.lastSyncAt) || 0,
         },
-        collision: document.state?.collision ?? null,
-        remoteDevices: {},
+        collision: state.collision ?? null,
+        // From the persisted state, so a home that has published before still shows what it published —
+        // none of this needs the lock.
+        remoteDevices: pulled,
         // `null` rather than `{}`: nothing has asked the server yet, and an empty map would read as "there
         // are no other devices".
         remoteKnown: false,
         remoteError: null,
-        published: {},
+        remoteDevicesOnServer: null,
+        published: state.published ?? {},
         conflictFiles: conflictFiles(),
         paths: { sync: join(dataDir, 'sync.json'), pricing: pricingPath },
       }
@@ -821,6 +852,33 @@ export function apply(ctx) {
         if (!attempt.acquired) return { result: 'locked', message: attempt.reason, at: 0 }
         try {
           const result = await instance.engine.run({ lock: attempt })
+          // A run changes the store in two ways that **no log cursor can see**: a pull imports rows another
+          // device published, and a withdrawn month deletes the rows that came from it. `refresh()` walks the
+          // session logs, so neither one would ever reach the in-memory view — the panel would keep showing
+          // what it had until the host process restarted, while the sync page (reading `sync.json`) reported
+          // the successful run. Reloading here is what makes "pulled 1 shard" and the numbers agree, and the
+          // engine's own `storeChanged` is the signal: it is true only when rows were written or deleted.
+          //
+          // Not "whenever the run was not locked": a run that never got past a failed request has nothing to
+          // reload, `storeChanged` is the engine's own answer to "did rows move", and a host that is on its
+          // way out must not touch a cache whose statements are about to be finalized — `syncAbort` is that
+          // flag, set by the disposer just before it closes the store. (A future way to *cancel* a run
+          // without unloading would leave `syncAbort` alone and would get its reload, which is right: this
+          // process keeps living and its view still has to catch up.)
+          if (result?.storeChanged && !instance.syncAbort) {
+            // Losing this must not turn a sync that worked into a reported failure, which is what an
+            // exception here would do on the way out of this `try`: the numbers stay stale (the very thing
+            // 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 })
+            } catch (error) {
+              log(`the folded view could not be reloaded after the sync: ${error?.message ?? error}`)
+            }
+            // Nulled rather than left alone: the next poll would otherwise be allowed to answer from a
+            // snapshot built before these rows existed (it is reused for `SNAPSHOT_TTL_MS`).
+            snapshot = null
+          }
           // A shard may have carried a newer price table; the panel's next poll should see it.
           pricing = readPricing(pricingPaths)
           rules = resolveHolidayRules(pricing.holidays)
@@ -934,6 +992,10 @@ export function apply(ctx) {
   function scheduleStartupSync(delayMs = delayFor('DSH_USAGE_BADGE_STARTUP_SYNC_MS', STARTUP_SYNC_DELAY_MS)) {
     const configured = readSyncDocument(dataDir, log)
     if (!configured.enabled || !configured.url || !configured.ha1) return
+    if (configured.onStart === false) {
+      log('startup sync is switched off')
+      return
+    }
     const timer = setTimeout(() => {
       startupSyncTimer = null
       const instance = syncSystem()
@@ -948,6 +1010,56 @@ export function apply(ctx) {
   }
   let startupSyncTimer = null
 
+  /**
+   * A last sync on the way out, awaited — but only for as long as there is time.
+   *
+   * DSH gives the whole application teardown **5 seconds** (`PROCESS_SHUTDOWN_TIMEOUT_MS` in the runtime)
+   * before it exits the host process outright, and the desktop then waits up to 10 more for the child to go.
+   * So the chain that reaches this function is: desktop asks the host to shut down → the host awaits its own
+   * disposal → cordis disposes this plugin's effects, awaiting what they return. Returning a promise here is
+   * what makes the sync happen at all instead of being cut off mid-request.
+   *
+   * The budget is what keeps that promise from becoming a slow quit: past it the run is told to stop at its
+   * next step boundary (nothing half-written — uploads go through a temporary name and the manifest is
+   * written last) and the disposal returns. A sync that did not finish is reported as such, not pretended.
+   */
+  async function syncOnExit() {
+    // Read the configuration from disk when this session never touched sync: a home configured in an earlier
+    // session, quit without opening the panel, still has to sync. Creating the system here is also what takes
+    // the lock — and the store is still open at this point (the disposer closes it afterwards).
+    const document = system?.engine?.config ?? readSyncDocument(dataDir, log)
+    if (!document.enabled || !document.url || !document.ha1) return
+    if (document.onExit === false) {
+      log('exit sync is switched off')
+      return
+    }
+    const instance = syncSystem()
+    if (!instance.engine.store) return
+    if (!instance.lock?.acquired) {
+      log(`exit sync skipped: ${instance.lock?.reason ?? 'no lock'}`)
+      return
+    }
+    const budget = delayFor('DSH_USAGE_BADGE_EXIT_SYNC_MS', EXIT_SYNC_BUDGET_MS)
+    if (budget <= 0) {
+      // A zero budget means "there is no time for this" — the switch a test or a debugging session uses.
+      log('exit sync skipped: no time budget')
+      return
+    }
+    let timer = null
+    const deadline = new Promise((resolve) => {
+      timer = setTimeout(() => resolve('deadline'), budget)
+      timer.unref?.()
+    })
+    const outcome = await Promise.race([runSync().then((result) => result ?? 'done', () => 'failed'), deadline])
+    clearTimeout(timer)
+    if (outcome === 'deadline') {
+      instance.engine.abort()
+      log(`exit sync did not finish within ${budget}ms; it stops at its next step boundary`)
+      return
+    }
+    log(`exit sync: ${instance.last?.result ?? outcome} — ${instance.last?.message ?? ''}`)
+  }
+
   async function warm() {
     try {
       const status = await refreshOnce()
@@ -1111,14 +1223,15 @@ export function apply(ctx) {
       // plus a `hasCredential` flag, so the state of "is one configured" is visible without the secret
       // leaving the host half.
       if (route === '/sync' && req.method === 'GET') {
-        // Loopback only, like every other sync route. The answer names the server and the account, and
-        // reading it *is* engaging with sync — this is where the system comes into being, and with it the
-        // owner lock. A page that never opens this tab still touches nothing.
+        // Loopback only, like every other sync route: the answer names the server and the account.
+        //
+        // **And it creates nothing.** Opening the tab is looking, not deciding — so this no longer takes the
+        // lock or writes `sync.json`; the system comes into being when something is saved, tested or run.
+        // `writable` is still answered honestly, by reading the lock file rather than writing one.
         if (!isLoopback(req)) {
           sendJson(res, 403, { error: 'the sync status is visible to loopback clients only' })
           return
         }
-        syncSystem()
         let body
         try {
           body = await withTimeout(syncStatus(), STATUS_TIMEOUT_MS, 'reading the sync status')
@@ -1138,9 +1251,14 @@ export function apply(ctx) {
         const instance = syncSystem()
         const patch = await readJsonBody(req)
         const config = {}
-        for (const field of ['enabled', 'url', 'username', 'allowInsecureTls', 'deviceLabel', 'deviceId', 'realm']) {
+        for (const field of ['enabled', 'url', 'username', 'deviceLabel', 'deviceId', 'realm']) {
           if (patch[field] !== undefined) config[field] = patch[field]
         }
+        // The switches, coerced: a panel sends booleans, but a hand-written request may send 0/1, and a
+        // stored `"false"` string would otherwise read as *on* (it is not `false`).
+        for (const field of ['allowInsecureTls', 'onStart', 'onExit']) {
+          if (patch[field] !== undefined) config[field] = patch[field] !== false && patch[field] !== 'false' && patch[field] !== 0
+        }
         if (patch.windowYears !== undefined) config.windowYears = Math.max(0, Math.min(50, Number(patch.windowYears) || 0))
         if (typeof patch.deviceId === 'string' && patch.deviceId !== '') {
           try {
@@ -1259,12 +1377,27 @@ export function apply(ctx) {
       // Fire and forget: this only fills in what the server holds, for the panel's next read.
       void refreshRemoteDevices()
     })
-    return () => {
+    // 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;
+    //   2. sync once, while the store is still open (a sync reads it) and while we still own the lock;
+    //   3. hand the lock back and close the store.
+    //
+    // Returning a promise is what makes step 2 real: DSH awaits the host's teardown, cordis awaits what an
+    // effect's disposer returns, and the runtime force-exits only after 5 s. So this is not "fire and hope";
+    // it is synchronised with the shutdown — and bounded, so a slow server cannot hold up quitting.
+    return async () => {
       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 (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}`)
+      }
       // **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
       // refused by this plugin's own lock, for a pid that is very much alive: its own.
@@ -1278,7 +1411,6 @@ export function apply(ctx) {
         // touch the store do not start.
         system.engine.abort()
         system.engine.release()
-        if (system.running) log('unloading while a sync is in flight; it stops at its next step boundary')
       }
       releaseLock(dataDir)
       aggregator.close()

package/lib/sync.js

@@ -627,6 +627,10 @@ export const defaultSyncConfig = () => ({
   deviceLabel: hostname(),
   instanceId: '',
   windowYears: 5,
+  // The two automatic triggers, both on by default: a backup nobody remembers to run is not a backup. Both
+  // are switchable, because a sync that holds up quitting is worse than one that happens a minute later.
+  onStart: true,
+  onExit: true,
 })
 
 /** Read `sync.json`, or a default document when it is missing or unreadable. */
@@ -823,7 +827,12 @@ export class SyncEngine {
   /**
    * Pull: fetch the shards this device does not already hold, and store their rows.
    *
-   * @returns {{fetched:number, rows:number, failed:Array<{path:string, error:string}>}}
+   * `wrote` is the honest answer to "did the store change", which is not the same as "did rows arrive":
+   * a shard that decodes into fewer rows than its manifest names is still imported (that part is
+   * idempotent) and then reported as a failure, and a tombstone **deletes** rows without any arriving at
+   * all. The host uses it to decide whether its in-memory view is now stale.
+   *
+   * @returns {{fetched:number, rows:number, failed:Array<{path:string, error:string}>, wrote:boolean}}
    */
   async pull(client, manifests) {
     const wanted = planDownload({
@@ -847,6 +856,11 @@ export class SyncEngine {
     })
     let rows = 0
     let fetched = 0
+    // `wrote` comes from the two places that touch the store, and it is the **store's own count** that
+    // decides it: a shard replayed against a store that already holds every one of its rows writes nothing,
+    // and claiming the view is stale then would cost a full reload for nothing (`rows` cannot answer this —
+    // it counts rows the manifest vouched for, which is not the same as rows that changed).
+    let wrote = false
     const failed = []
     for (const item of wanted) {
       // One shard at a time, and a shard is the natural boundary: stopping here leaves the store consistent
@@ -882,7 +896,10 @@ export class SyncEngine {
       // and the honest answer is to keep asking. This build never writes such a shard; an older one or a
       // hand-made file can.
       if (decoded.malformed > 0 || (item.entry.rows > 0 && decoded.rows.length !== item.entry.rows)) {
-        this.store?.intakeRows(decoded.rows)
+        // Imported even though the shard is about to be reported as a failure, so the store's own count is
+        // what says whether the host's view moved. (`rows` stays at zero here: it counts what the manifest
+        // vouched for, and the manifest is exactly what is in question.)
+        if (this.store && this.store.intakeRows(decoded.rows) > 0) wrote = true
         failed.push({
           path: item.entry.path,
           error: `the shard holds ${decoded.rows.length} of the ${item.entry.rows || decoded.rows.length} rows its manifest names` + (decoded.malformed ? ` (${decoded.malformed} unreadable line(s))` : ''),
@@ -900,7 +917,10 @@ export class SyncEngine {
       if (this.store) {
         // `replace`: the month is this device's own statement about it, so rows it no longer lists go.
         // Without that, a publisher that dropped a row keeps every reader counting it forever.
-        this.store.intakeRows(decoded.rows, { replace: { source: item.device, month: item.key } })
+        const imported = this.store.intakeRows(decoded.rows, { replace: { source: item.device, month: item.key } })
+        // In replace mode the count includes the rows it *deleted* as well as the ones it wrote, which is
+        // exactly the question being asked here.
+        if (imported > 0) wrote = true
         // `held` is only advanced once the rows are in the store: if the import throws, the shard
         // must be fetched again rather than remembered as applied.
         this.state.held = { ...(this.state.held ?? {}), [`${item.device}/${item.key}`]: { sha: item.entry.sha256, at: Number(item.entry.at) || 0 } }
@@ -925,6 +945,7 @@ export class SyncEngine {
         // Only what this reader actually imported: a tombstone for a month it never held is nothing.
         if (!this.state.held?.[context]) continue
         const removed = this.store?.dropSourceMonth(device, key) ?? 0
+        if (removed > 0) wrote = true
         const next = { ...(this.state.held ?? {}) }
         delete next[context]
         this.state.held = next
@@ -933,7 +954,7 @@ export class SyncEngine {
         this.log(`dropped ${removed} row(s) from ${context}: the device that published it no longer holds that month (withdrawn ${entry.at ? new Date(entry.at).toISOString().slice(0, 10) : 'at some point'})`)
       }
     }
-    return { fetched, rows, failed, dropped, droppedKeys }
+    return { fetched, rows, failed, dropped, droppedKeys, wrote }
   }
 
   /**
@@ -1314,9 +1335,15 @@ export class SyncEngine {
     // statements are finalized, so continuing is not harmless.
     if (this.aborted) return this.finish('aborted', 'the host unloaded during the sync', { started })
 
+    // Whether this run changed the local store, which is a different question from whether it succeeded:
+    // a pull that imported rows and then failed to publish them has still made the host's in-memory view
+    // stale. Declared outside the `try` so every path out of it — including a failure and an abort — can
+    // report it. The host decides what to do with it: an abort because *it* is unloading is skipped there
+    // (`syncAbort`), while an abort for any other reason still has a live process to catch up.
+    let storeChanged = false
     try {
       const { manifests } = await this.readManifests(client)
-      if (this.aborted) return this.finish('aborted', 'the host unloaded during the sync', { started })
+      if (this.aborted) return this.finish('aborted', 'the host unloaded during the sync', { started, extra: { storeChanged } })
       // **Pull first, refuse only the push.** An installation whose device name is taken still wants the
       // history back, and that is the case the feature exists for (reinstall, another machine): the name
       // is what is in the way, not the data. So the clash is noted here — which is what tells `pull` to
@@ -1330,8 +1357,9 @@ export class SyncEngine {
       // refusing to publish — the one case where the two readings of `collision` differ.
       this.pullOwnDirectory = Boolean(clash)
       const pulled = await this.pull(client, manifests)
+      storeChanged = pulled.wrote
       this.pullOwnDirectory = false
-      if (this.aborted) return this.finish('aborted', `the host unloaded during the sync (${pulled.fetched} shard(s) had arrived)`, { started })
+      if (this.aborted) return this.finish('aborted', `the host unloaded during the sync (${pulled.fetched} shard(s) had arrived)`, { started, extra: { storeChanged } })
       const pushed = await this.push(client)
       if (pushed.manifest) {
         this.state.published = pushed.manifest.chunks
@@ -1341,7 +1369,7 @@ export class SyncEngine {
       }
       // The price table last: it is the only hand-written thing here, and it should not be touched by
       // a run that failed to move the usage it was about to move.
-      if (this.aborted) return this.finish('aborted', 'the host unloaded during the sync', { started })
+      if (this.aborted) return this.finish('aborted', 'the host unloaded during the sync', { started, extra: { storeChanged } })
       const pricing = await this.syncPricing(client)
       const parts = [
         `pulled ${pulled.fetched} shard(s) / ${pulled.rows} row(s)`,
@@ -1377,12 +1405,14 @@ export class SyncEngine {
           refused: pushed.refused ?? null,
           withdrawn: pushed.withdrawn ?? 0,
           dropped: pulled.dropped ?? 0,
+          // Named for the host, not for the panel: it is what tells the host its aggregate is now stale.
+          storeChanged,
         },
       })
     } catch (error) {
       const message = String(error?.message ?? error)
       this.log(`sync failed: ${message}`)
-      return this.finish('failed', message, { started })
+      return this.finish('failed', message, { started, extra: { storeChanged } })
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-usage-badge",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "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",