dsh-desktop-statusbar 2.1.1 → 2.1.2

package/lib/index.js

@@ -40,6 +40,7 @@
 import { z } from 'zod'
 import { adapterFor, adaptersFor, pluginRoutesIn } from './balance-api.js'
 import { holidayHtmlToText, parseHolidayNotice } from './holiday.js'
+import { isUpdating, lastUpdateResult, resolveSelfDir, selfUpdateOnce } from './self-update.js'
 import { appendFileSync, closeSync, copyFileSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, statSync, writeFileSync } from 'node:fs'
 import { basename, dirname, join } from 'node:path'
 import { homedir } from 'node:os'
@@ -404,9 +405,47 @@ const MAX_CALLS = 4000
 const appendCalls = (calls, more) =>
   calls.length + more.length <= MAX_CALLS ? calls.concat(more) : calls.slice(calls.length + more.length - MAX_CALLS).concat(more)
 
+/**
+ * 被 MAX_CALLS 截掉的调用，按「模型 + 峰谷档」累计的 token。
+ *
+ * 为什么需要它：客户端算「总计费用」是**逐条调用**计价（每条按自己发生的时刻定峰谷），
+ * 而 calls 只保留最近 MAX_CALLS 条；超出部分原先直接丢弃，费用就少算了 ——
+ * 实测 5000 次调用少 20%、2 万次少 80%，而「总计用量」用的是官方全量数据，
+ * 于是同一个界面上用量是全量、费用是残缺的，且没有任何提示。
+ *
+ * 这里把丢掉的那些按档累计，客户端用档位价补算即可 —— 档位在 host 侧按北京时间判定，
+ * 与逐条计价同一套规则，所以两段相加与「一条不丢地算」结果一致。
+ */
+const overflowTier = z.object({
+  peak: usageBucket,
+  offPeak: usageBucket,
+}).strict()
+
+/** 往 overflow 里加一笔；返回新的 overflow（不改原对象）。 */
+function addOverflow(overflow, model, parts, peak) {
+  const zero = () => ({ input: 0, cacheRead: 0, cacheWrite: 0, output: 0 })
+  const prev = overflow[model] ?? { peak: zero(), offPeak: zero() }
+  const tierName = peak === true ? 'peak' : 'offPeak'
+  const tier = prev[tierName]
+  return {
+    ...overflow,
+    [model]: {
+      ...prev,
+      [tierName]: {
+        input: tier.input + parts.input,
+        cacheRead: tier.cacheRead + parts.cacheRead,
+        cacheWrite: tier.cacheWrite + parts.cacheWrite,
+        output: tier.output + parts.output,
+      },
+    },
+  }
+}
+
 const sessionUsageSchema = z.object({
   models: z.record(z.string(), usageBucket),
   calls: z.array(usageCall),
+  /* 被 MAX_CALLS 截掉的那部分（见 addOverflow 的说明）。老缓存没有这个键，所以可选。 */
+  overflow: z.record(z.string(), overflowTier).optional(),
     turn: z.number().nullable(),
   current: lastUsage.nullable(),
   last: lastUsage.nullable(),
@@ -419,7 +458,7 @@ const sessionUsageSchema = z.object({
 const sessionUsageProjection = {
   key: 'desktopStatusbarUsage',
   stateSchema: sessionUsageSchema,
-  init: () => ({ models: {}, calls: [], current: null, last: null, turn: null, routeModel: null, routeProvider: null }),
+  init: () => ({ models: {}, calls: [], overflow: {}, current: null, last: null, turn: null, routeModel: null, routeProvider: null }),
   apply: (state, event) => {
     const calls = Array.isArray(state.calls) ? state.calls : []
     const turnOf = (event) => {
@@ -484,10 +523,22 @@ const sessionUsageProjection = {
       output: (prev === null ? 0 : prev.output) + one.output,
     }
     const current = { ...summary, calls: callsForTurn.concat([one]) }
+    /* 追加后若超过 MAX_CALLS，最前面那几条会被丢掉。丢掉的是**真实用过的 token**，
+       必须把它们按档累计进 overflow，否则客户端逐条计价时会少算（见 addOverflow 说明）。
+       用合并前后的长度差算出丢了几条 —— 它们一定是最老的，也就是 calls 队首那几条。 */
+    const merged = appendCalls(calls, [one])
+    const droppedCount = calls.length + 1 - merged.length
+    let overflow = typeof base.overflow === 'object' && base.overflow !== null ? base.overflow : {}
+    for (let i = 0; i < droppedCount; i += 1) {
+      const gone = calls[i]
+      if (gone === undefined) break
+      overflow = addOverflow(overflow, gone.model, gone, isPeakTime(gone.at))
+    }
     return {
       ...base,
       turn: turn === null ? stateTurn : turn,
-      calls: appendCalls(calls, [one]),
+      calls: merged,
+      overflow,
       current,
       // 轮次变化时把上一轮结算进 last
       last: prev === null && base.current !== null ? base.current : base.last,
@@ -503,7 +554,9 @@ const sessionUsageProjection = {
   // 界面上的「本轮」因此与「总计」对不上，提升版本强制从事件日志重放。
   // 4 → 5：旧缓存里缺「会话起标题」那几笔 —— attempt 事件没有 message，取不到型号时
   // 整条投影抛错、该会话的账从此停摆。提升版本强制重放，把这些笔补回账本。
-  stateVersion: 5,
+  // 5 → 6：新增 overflow（被 MAX_CALLS 截掉那段的按档累计）。旧缓存里这个字段不存在，
+  // 长会话的费用会一直少算截掉的部分，必须重放才能补出来。
+  stateVersion: 6,
 }
 
 /* -------------------------------------------------------- sessionTimeRange */
@@ -806,26 +859,82 @@ function sendJson(res, status, body) {
   res.end(text)
 }
 
-/** 读一小段 JSON 请求体（只用于本插件自己的上报接口，超过 4KB 直接断开）。 */
+/* 写请求的来源校验：只拦「带跨站 Origin 的 POST」。
+   插件把 API 挂在 127.0.0.1 的 webServer 上，浏览器里任意网页都能对本机发简单请求
+   （`Content-Type: text/plain` 的 POST 不触发 CORS 预检，页面读不到响应也照样**把请求送达**）。
+   实测：伪造的价格库被完整接受，settleUnpriced 随后按攻击者单价结算进 `days[].cost`，
+   而 cost 一旦记下就不再改动 —— 污染不可逆；同一面还能触发 /api/self-update 真跑 pnpm 安装。
+   按用户确认的最小方案只做这一条判定，**不**引入 CORS 预检、**不**影响 GET：
+     · 没有 Origin（命令行 / curl / 宿主内部）→ 放行；
+     · Origin 的 host 与请求的 host 相同 → 同源，放行；
+     · 带跨站 Origin（含 opaque 的 `null`）的 POST → 由调用方回 403。
+   取不到 Host 头时判不了，保守放行（本机 webServer 一定带 Host，这一支只防意外形状）。 */
+function isCrossSiteWrite(req) {
+  if (req === null || req === undefined || req.method !== 'POST') return false
+  const headers = req.headers
+  if (headers === null || headers === undefined || typeof headers !== 'object') return false
+  const raw = typeof headers.origin === 'string' ? headers.origin.trim() : ''
+  if (raw.length === 0) return false
+  const target = typeof headers.host === 'string' ? headers.host.trim().toLowerCase() : ''
+  if (target.length === 0) return false
+  /* opaque 来源（沙箱 iframe、file:// 页面）与谁都不是同源 */
+  if (raw.toLowerCase() === 'null') return true
+  const schemeAt = raw.indexOf('://')
+  const rest = schemeAt === -1 ? raw : raw.slice(schemeAt + 3)
+  const authority = rest.split('/')[0].split('?')[0].toLowerCase()
+  const at = authority.indexOf('@')
+  const hostOnly = at === -1 ? authority : authority.slice(at + 1)
+  if (hostOnly.length === 0) return true
+  return hostOnly !== target
+}
+
+/* 请求体上限。原先统一 4KB，但**价格库会随模型数增长**：实测一条模型约 186 字节，
+   24 个模型就超过 4096 → 请求被直接断开，客户端 fetch 抛错又被 `.catch(() => {})` 吞掉，
+   于是「设置页改的单价只对底栏生效、活跃总览恒用旧价」而且毫无提示（实测缺陷）。
+   这里的接口只服务本机、只收本插件自己的小 JSON，放宽到 256KB 足够且没有实际风险。 */
+const JSON_BODY_LIMIT = 256 * 1024
+
+/**
+ * 读一小段 JSON 请求体。
+ *
+ * 收的是**原始 Buffer**，最后一次性解码：以前写 `raw += chunk`，每个 chunk 各自跑一次
+ * `toString('utf8')`，一个汉字的 3 个字节被切在两个 chunk 里时两半都变成 U+FFFD ——
+ * 实测中文模型名被污染成 `���定义模型`，接口照样回 `ok:true`，之后查价永远匹配不上。
+ * 上限也按**字节数**判（`raw.length` 是字符数，一个汉字只算 1，拿它当字节数会让
+ * 256KB 的上限实际放到 768KB）。
+ *
+ * @returns {Promise<object|null>} 解析失败或超限返回 null
+ */
 function readJsonBody(req) {
   return new Promise((resolve) => {
-    let raw = ''
+    const chunks = []
+    let size = 0
     let settled = false
+    let overLimit = false
     const finish = (value) => {
       if (settled) return
       settled = true
       resolve(value)
     }
     req.on('data', (chunk) => {
-      raw += chunk
-      if (raw.length > 4096) {
+      if (overLimit === true) return
+      /* 非 Buffer 的 chunk（测试里的字符串）也按同一语义折成字节数 */
+      const buf = Buffer.isBuffer(chunk) === true ? chunk : Buffer.from(String(chunk), 'utf8')
+      size += buf.length
+      if (size > JSON_BODY_LIMIT) {
+        overLimit = true
+        /* 先记下超限，再断开。**不要**在 destroy 之后写响应（socket 已销毁，写不进去）。 */
+        chunks.length = 0
         req.destroy()
         finish(null)
+        return
       }
+      chunks.push(buf)
     })
     req.on('end', () => {
+      if (overLimit === true) return
       try {
-        const parsed = JSON.parse(raw)
+        const parsed = JSON.parse(Buffer.concat(chunks).toString('utf8'))
         finish(parsed !== null && typeof parsed === 'object' ? parsed : null)
       } catch (error) {
         finish(null)
@@ -1363,41 +1472,55 @@ async function queryBalance(ctx, force, provider, model) {
  *
  * 为什么必须落盘：会话一旦被删除，日志就没了，而周总计必须把已经发生的消耗留住。
  * 台账按「事件」去重（同一 turn/step 只算一次、assistant/message 优先），于是重复扫描不会
- * 重复计数，删掉会话也不会让已记下的数字缩水；窗口是自然周（周一 00:00 起）。
+ * 重复计数，删掉会话也不会让已记下的数字缩水；窗口是**滚动的「近 7 天」**
+ * （见 recentStartMs：今天往前推 6 天，不再对齐自然周）。
  * 全程只读 token 数字，不读正文，台账里也只有数字、没有对话内容。
  */
 
 /**
- * 柱状窗口的起点：今天 00:00（北京时间）往前推 6 天，也就是「近 7 天」。
+ * 柱状窗口的起点：**本机时区**今天 00:00 往前推 6 天，也就是「近 7 天」。
  * 这里用的是滚动窗口，不再对齐自然周 —— 用户看到的是最近七天，而不是本周一到现在。
+ *
+ * 日期一律按**装机者所在时区**算（见 localDateKey 的说明），不再固定 UTC+8。
  */
 function recentStartMs(now) {
-  const BEIJING = 8 * 3600 * 1000
-  const shifted = new Date(now + BEIJING)
-  const todayStart = Date.UTC(shifted.getUTCFullYear(), shifted.getUTCMonth(), shifted.getUTCDate()) - BEIJING
-  return todayStart - 6 * 24 * 3600 * 1000
+  const d = new Date(now)
+  /* 按**日历字段**回退 6 天，不要写 `本地今天 00:00 - 6*24h`：
+     有夏令时的时区里，这 6 天中有一天只有 23 小时（春季拨快），
+     减固定毫秒会落到 7 天前的 23:00，被 localDateKey 记成前一天 ——
+     于是窗口变成「7 天前…昨天」，「今天」那根柱子消失、当天用量落在窗口外。
+     实测纽约/伦敦/悉尼/圣地亚哥各错 18 天/3 年（UTC+8 的机器上永远看不到）。 */
+  return new Date(d.getFullYear(), d.getMonth(), d.getDate() - 6).getTime()
 }
 
-/** 本月 1 号 00:00（北京时间）的毫秒时间戳。 */
+/** 本月 1 号 00:00（本机时区）的毫秒时间戳。 */
 function monthStartMs(now) {
-  const BEIJING = 8 * 3600 * 1000
-  const shifted = new Date(now + BEIJING)
-  return Date.UTC(shifted.getUTCFullYear(), shifted.getUTCMonth(), 1) - BEIJING
+  const d = new Date(now)
+  return new Date(d.getFullYear(), d.getMonth(), 1).getTime()
 }
 
 const padTwo = (value) => (value < 10 ? '0' + String(value) : String(value))
 
-/** 当年 1 月 1 日 00:00（北京时间）的毫秒时间戳 —— 12 个月的统计要从这里扫起。 */
+/** 当年 1 月 1 日 00:00（本机时区）的毫秒时间戳 —— 12 个月的统计要从这里扫起。 */
 function yearStartMs(now) {
-  const BEIJING = 8 * 3600 * 1000
-  const shifted = new Date(now + BEIJING)
-  return Date.UTC(shifted.getUTCFullYear(), 0, 1) - BEIJING
+  const d = new Date(now)
+  return new Date(d.getFullYear(), 0, 1).getTime()
 }
 
-/** 北京时间（UTC+8）的日期键 'YYYY-MM-DD' —— DeepSeek 的峰谷与账单都按北京时间。 */
+/**
+ * 日期键 'YYYY-MM-DD' —— 按**装机者所在时区**取，与客户端同一口径。
+ *
+ * 曾经固定用北京时间（UTC+8）：那是 DeepSeek 峰谷计价与账单的口径，但**日期归属**
+ * 不该跟着它走 —— 使用者看的是自己日历上的「今天/昨天」，UTC+8 装机时两地一致，
+ * 非 UTC+8 的机器上活跃总览会整体错一天（今天那格高亮成昨天、未来/过去的灰阶也偏）。
+ *
+ * 注意区分两件事，别把这里改回去：
+ *   · **日期归属**（这条函数）＝ 装机者时区，纯粹是给人看的日历。
+ *   · **峰谷计价**（isPeakTime）＝ 北京时间，那是 DeepSeek 的官方计费规则，与装机位置无关。
+ */
 function localDateKey(ms) {
-  const date = new Date(ms + 8 * 3600 * 1000)
-  return date.getUTCFullYear() + '-' + padTwo(date.getUTCMonth() + 1) + '-' + padTwo(date.getUTCDate())
+  const date = new Date(ms)
+  return date.getFullYear() + '-' + padTwo(date.getMonth() + 1) + '-' + padTwo(date.getDate())
 }
 
 /* 官方参考价（CNY / 每百万 tokens），与客户端价格表同源、与官方定价页一致。
@@ -1607,7 +1730,7 @@ let extraHolidays = null
 /** 落盘过的法定节假日（带缓存）；文件不存在或读不动就当没有这回事。 */
 function extraHolidayDays() {
   if (extraHolidays !== null) return extraHolidays
-  const parsed = readLedgerFile(holidaysPath())
+  const parsed = readJsonObjectFile(holidaysPath())
   extraHolidays = parsed !== null && Array.isArray(parsed.days)
     ? parsed.days.filter((one) => typeof one === 'string')
     : []
@@ -1711,6 +1834,10 @@ function sanitizePriceBook(raw) {
       output: keep(value.output),
     }
     : null)
+  /* 普通对象字面量，但写入一律走 defineBookEntry：键名是 `__proto__` 时
+     `out[name] = {...}` 是**设置原型**而不是建自有属性 —— 那条目会从 Object.keys
+     里消失（静默丢条目）、返回对象的原型还被换掉（把不可信输入挂成原型，是原型污染）。
+     用 defineProperty 建可枚举的自有属性，行为与其它键名一致。 */
   const out = {}
   const names = Object.keys(raw)
   for (let i = 0; i < names.length; i += 1) {
@@ -1724,7 +1851,7 @@ function sanitizePriceBook(raw) {
     /* 保留「是否峰谷计价」：没勾的条目是**全天一个价**，计价时两档都要取 peak，
        否则空闲时段会挑到那个没填的档、把费用算成 0（实测缺陷）。缺省按两档。 */
     const code = entry.currency === 'USD' ? 'USD' : (entry.currency === 'CNY' ? 'CNY' : null)
-    out[names[i]] = {
+    defineBookEntry(out, names[i], {
       peak: peak !== null ? peak : offPeak,
       offPeak: offPeak !== null ? offPeak : peak,
       tiered: entry.tiered !== false,
@@ -1734,7 +1861,7 @@ function sanitizePriceBook(raw) {
          host 不替它决定（否则往返一次多出一个字段，深比较基准会被悄悄改掉）。
          注意：必须保留，不保留就等于清洗时把币种丢了。 */
       ...(code === null ? {} : { currency: code }),
-    }
+    })
   }
   return Object.keys(out).length === 0 ? null : out
 }
@@ -1746,16 +1873,46 @@ function sanitizePriceBook(raw) {
  *
  * 它以前的作用是"不一致就把台账整本丢丢掉重扫"，那会连已经算好的费用一起改掉，
  * 会话日志一旦被删，历史数字就再也算不回来。现在它只读不写、只用来触发补算。
+ *
+ * 格式（v4 起）：`fp4:` + JSON 数组。以前是 `名字:四项:四项|名字:…` 的拼接，两个坑：
+ *   · 键名里带 `:`（Ollama 的 `qwen2.5:14b`）或 `|`（`a|b`）会把分隔符吃掉，
+ *     `parseFingerprint` 要么整条丢、要么还原出**错的键名** → 回扫把"当年已按自建价
+ *     算过钱"的事件误判成"当时缺价"，再补一遍 → 同一笔用量计两次、当天 cost 翻倍；
+ *   · 只序列化四项数字，`tiered`（峰谷计价开关）与 `currency` 改了却算不出变化 →
+ *     用户把「峰谷计价」改成「全天同价」或换币种时 `changed=false`，欠账一直挂着不结算。
+ * JSON 天然带转义，键名不再可能撞上分隔符；`tiered` / `currency` 一起进指纹。
+ *
+ * 币种按**缺省即 CNY** 归一：host 的 `sanitizePriceBook` 不补默认币种、客户端会落成显式
+ * `CNY`，两侧必须算出同一串（见 tests/verify-price-parity.js 的差分断言）。
+ * 两档都空的条目（没定价）不进指纹 —— 它们不参与计价，也不参与"当时有没有价"的判定。
  */
+const FINGERPRINT_MARK = 'fp4:'
+
 function fingerprintOf(book) {
-  const names = Object.keys(book === null || book === undefined ? {} : book).sort()
-  const parts = []
+  const source = book === null || book === undefined ? {} : book
+  const names = Object.keys(source).sort()
+  const rows = []
+  const tierOf = (t) => (t === null || t === undefined
+    ? null
+    : [numOrZero(t.input), numOrZero(t.cacheRead), numOrZero(t.cacheWrite), numOrZero(t.output)])
   for (let i = 0; i < names.length; i += 1) {
-    const one = book[names[i]]
-    const pick = (t) => (t === null || t === undefined ? 'x' : [numOrZero(t.input), numOrZero(t.cacheRead), numOrZero(t.cacheWrite), numOrZero(t.output)].join(','))
-    parts.push(names[i] + ':' + pick(one.peak) + ':' + pick(one.offPeak))
-  }
-  return parts.join('|')
+    const one = source[names[i]]
+    const rawPeak = tierOf(one === null || one === undefined ? null : one.peak)
+    const rawOffPeak = tierOf(one === null || one === undefined ? null : one.offPeak)
+    if (rawPeak === null && rawOffPeak === null) continue
+    /* 两档互相补全，与 `sanitizePriceBook` 同一语义：只给一档的条目（缺省那档为 undefined）
+       在库里、在 parse 回来的库里都表现为"两档同价"。不补全的话 `parseFingerprint`
+       会把缺档还原成有值的那档，`fingerprintOf(parse(fp)) !== fp` —— 往返不成立，
+       而 verify-price-parity 正是靠"指纹往返回到原串"守住格式的。 */
+    rows.push([
+      names[i],
+      rawPeak !== null ? rawPeak : rawOffPeak,
+      rawOffPeak !== null ? rawOffPeak : rawPeak,
+      one !== null && one !== undefined && one.tiered === false ? 0 : 1,
+      one !== null && one !== undefined && one.currency === 'USD' ? 'USD' : 'CNY',
+    ])
+  }
+  return FINGERPRINT_MARK + JSON.stringify(rows)
 }
 
 function priceFingerprint() {
@@ -1764,10 +1921,16 @@ function priceFingerprint() {
 
 /**
  * 指纹 → 价格库（fingerprintOf 的逆运算），迁移回扫用它还原"当时的价格库"。
- * 单条形状对不上（段数不是 3、数字不合法）就跳过那一条；整体为空的返回 null。
+ * 单条形状对不上（不是数组、数字不合法）就跳过那一条；整体为空的返回 null。
+ *
+ * 两种格式都认：
+ *   · `fp4:` 前缀 → 新格式（JSON，可往返）；
+ *   · 别的（老台账里落盘的旧格式）→ 按老的 `:` / `|` 拼接解析，只为让升级前的
+ *     台账还能还原出当年的价目表（解析不出来就返回 null，调用方回退内置表，与旧行为一致）。
  */
 function parseFingerprint(text) {
   if (typeof text !== 'string' || text.length === 0) return null
+  if (text.startsWith(FINGERPRINT_MARK) === true) return parseFingerprintRows(text.slice(FINGERPRINT_MARK.length))
   const out = {}
   const segments = text.split('|')
   const tier = (raw) => {
@@ -1790,11 +1953,56 @@ function parseFingerprint(text) {
     const peak = tier(fields[1])
     const offPeak = tier(fields[2])
     if (peak === null && offPeak === null) continue
-    out[fields[0]] = { peak: peak !== null ? peak : offPeak, offPeak: offPeak !== null ? offPeak : peak }
+    defineBookEntry(out, fields[0], { peak: peak !== null ? peak : offPeak, offPeak: offPeak !== null ? offPeak : peak })
+  }
+  return Object.keys(out).length === 0 ? null : out
+}
+
+/** 把 `fp4:` 后面的 JSON 数组还原成价格库。 */
+function parseFingerprintRows(text) {
+  let rows = null
+  try {
+    rows = JSON.parse(text)
+  } catch (error) {
+    return null
+  }
+  if (Array.isArray(rows) !== true) return null
+  const out = {}
+  for (let i = 0; i < rows.length; i += 1) {
+    const row = rows[i]
+    if (Array.isArray(row) !== true || row.length < 5) continue
+    const name = row[0]
+    if (typeof name !== 'string' || name.length === 0) continue
+    const tier = (raw) => {
+      if (Array.isArray(raw) !== true || raw.length !== 4) return null
+      const one = {
+        input: Number(raw[0]),
+        cacheRead: Number(raw[1]),
+        cacheWrite: Number(raw[2]),
+        output: Number(raw[3]),
+      }
+      if (Number.isFinite(one.input) !== true || Number.isFinite(one.cacheRead) !== true
+        || Number.isFinite(one.cacheWrite) !== true || Number.isFinite(one.output) !== true) return null
+      return one
+    }
+    const peak = tier(row[1])
+    const offPeak = tier(row[2])
+    if (peak === null && offPeak === null) continue
+    defineBookEntry(out, name, {
+      peak: peak !== null ? peak : offPeak,
+      offPeak: offPeak !== null ? offPeak : peak,
+      tiered: row[3] !== 0,
+      currency: row[4] === 'USD' ? 'USD' : 'CNY',
+    })
   }
   return Object.keys(out).length === 0 ? null : out
 }
 
+/** 往价格库里写一条：`__proto__` 这类键名必须建成自有属性（见 sanitizePriceBook 处的说明）。 */
+function defineBookEntry(target, name, value) {
+  Object.defineProperty(target, name, { value: value, enumerable: true, writable: true, configurable: true })
+}
+
 /** 一笔用量按单价折成人民币；模型没有价格表就返回 0（不计入花费）。 */
 function tokenCost(model, at, parts) {
   const entry = priceEntryFor(model)
@@ -2650,9 +2858,13 @@ function emptyLedger() {
 }
 
 /**
- * 读一个台账文件；文件不存在、读不出或不是合法 JSON 对象时返回 null。
+ * 读一个 JSON 对象文件；不存在、读不出或不是合法 JSON 对象时返回 null。
+ *
+ * 名字**刻意不叫** readLedgerFile：它不只读台账，`holidays.json` 也走这里
+ * （两者都是「一个 JSON 对象，坏了就当没有」的语义）。用台账专属的名字会让人
+ * 以为改动只该影响台账。
  */
-function readLedgerFile(file) {
+function readJsonObjectFile(file) {
   try {
     const parsed = JSON.parse(readFileSync(file, 'utf8'))
     return parsed !== null && typeof parsed === 'object' ? parsed : null
@@ -2704,9 +2916,9 @@ function logLedgerNote(message) {
 }
 
 function readLedger() {
-  const parsed = readLedgerFile(ledgerPath())
+  const parsed = readJsonObjectFile(ledgerPath())
   if (parsed !== null) return migrateLedger(parsed)
-  const backup = readLedgerFile(ledgerPath() + '.bak')
+  const backup = readJsonObjectFile(ledgerPath() + '.bak')
   if (backup !== null) {
     logLedgerNote('usage-ledger: 主文件读不出来，已回退到自动备份')
     const recovered = migrateLedger(backup)
@@ -2730,7 +2942,7 @@ function writeLedger(ledger) {
     let kept = false
     /* 只有"上一份是能解析的好数据"才留成备份：主文件损坏时我们刚回退过 .bak，
        若这时把损坏内容复制成新 .bak，备份就只能救命一次（实测缺陷）。 */
-    if (readLedgerFile(target) !== null) {
+    if (readJsonObjectFile(target) !== null) {
       try {
         copyFileSync(target, target + '.bak')
         kept = true
@@ -2759,7 +2971,14 @@ function writeLedger(ledger) {
 function addUnpriced(day, model, parts, peakTime) {
   const name = typeof model === 'string' && model.length > 0 ? model : '(未知模型)'
   const bucket = day.unpriced ?? {}
-  const one = bucket[name] ?? {
+  /* 必须按**自有属性**判断，不能用 `bucket[name] ?? 默认值`：模型名是 JS 原型属性名
+     （`constructor` / `toString` / `valueOf` / `__proto__` …）时，`bucket[name]` 会取到
+     原型上的函数或原型对象，`??` 不触发 —— 于是 `one.peak` 是 undefined，下面
+     `tier.input += …` 抛 TypeError。抛错发生在 collectIntoLedger / backfillUnpriced 里，
+     queueLedgerJob 随之 reject，`/api/daily-usage` 恒返回 ledger-failed，活跃总览整块打不开。
+     凡是"用户/上游给的字符串当对象键"的地方都要走这条判据。 */
+  const hasOwn = Object.prototype.hasOwnProperty.call(bucket, name)
+  const one = hasOwn === true ? bucket[name] : {
     peak: { input: 0, cacheRead: 0, cacheWrite: 0, output: 0 },
     offPeak: { input: 0, cacheRead: 0, cacheWrite: 0, output: 0 },
   }
@@ -2768,7 +2987,8 @@ function addUnpriced(day, model, parts, peakTime) {
   tier.cacheRead += parts.cacheRead
   tier.cacheWrite += parts.cacheWrite
   tier.output += parts.output
-  bucket[name] = one
+  /* 同理：`bucket[name] = one` 在 name 为 `__proto__` 时是设置原型而不是建条目 */
+  defineBookEntry(bucket, name, one)
   day.unpriced = bucket
 }
 
@@ -2989,13 +3209,29 @@ function pruneLedger(ledger) {
 
 /** 把台账里的日桶铺成「近 7 天」固定 7 格（最早一天在最左、今天是最后一格），并算合计；另附当月与全年。 */
 function weekUsagePayload(ledger, rangeStart, monthStart, meta) {
-  const DAY = 24 * 3600 * 1000
   const days = []
   const totals = { input: 0, cacheRead: 0, cacheWrite: 0, output: 0, total: 0, calls: 0, cost: 0 }
+  /* 逐日按**日历**推进，不用 rangeStart + i*24h：后者在夏令时切换日会重复/跳天
+     （同 monthUsagePayload 的说明）。rangeStart 本身已是本地 00:00。 */
+  const startDate = new Date(rangeStart)
   for (let i = 0; i < 7; i += 1) {
-    /* 按北京时间逐日推进，不受机器时区影响 */
-    const key = localDateKey(rangeStart + i * DAY)
-    const bucket = ledger.days[key] ?? { input: 0, cacheRead: 0, cacheWrite: 0, output: 0, calls: 0, cost: 0, peak: { input: 0, cacheRead: 0, cacheWrite: 0, output: 0 } }
+    const at = new Date(startDate.getFullYear(), startDate.getMonth(), startDate.getDate() + i).getTime()
+    const key = localDateKey(at)
+    const raw = ledger.days[key]
+    /* 日桶逐个字段兜底：台账被外部改坏（不是对象、或字段缺失/非数字）时，
+       直接相加会得到 NaN，整个 totals 都变成 NaN、JSON 里还丢键。
+       monthUsagePayload / yearUsagePayload 一直有兜底，只有这里没有。 */
+    const bucket = raw !== null && raw !== undefined && typeof raw === 'object'
+      ? {
+        input: Number(raw.input) || 0,
+        cacheRead: Number(raw.cacheRead) || 0,
+        cacheWrite: Number(raw.cacheWrite) || 0,
+        output: Number(raw.output) || 0,
+        calls: Number(raw.calls) || 0,
+        cost: Number(raw.cost) || 0,
+        peak: raw.peak,
+      }
+      : { input: 0, cacheRead: 0, cacheWrite: 0, output: 0, calls: 0, cost: 0, peak: undefined }
     const total = bucket.input + bucket.cacheRead + bucket.cacheWrite + bucket.output
     const cost = typeof bucket.cost === 'number' && Number.isFinite(bucket.cost) ? bucket.cost : 0
     /* 高峰那一份：老台账没有 peak 字段时按 0 处理 */
@@ -3009,8 +3245,6 @@ function weekUsagePayload(ledger, rangeStart, monthStart, meta) {
     peak.total = peak.input + peak.cacheRead + peak.cacheWrite + peak.output
     days.push({
       date: key,
-      /* 窗口内第几天（0 = 最早那天，6 = 今天）；不再是星期几 */
-      offset: i,
       input: bucket.input,
       cacheRead: bucket.cacheRead,
       cacheWrite: bucket.cacheWrite,
@@ -3048,22 +3282,31 @@ function weekUsagePayload(ledger, rangeStart, monthStart, meta) {
  * 「月内最高的一天」（要标紫的那天）只在当月天里评，避免被上月的量抢走。
  */
 function monthUsagePayload(ledger, monthStart) {
-  const BEIJING = 8 * 3600 * 1000
-  const DAY = 24 * 3600 * 1000
-  const first = new Date(monthStart + BEIJING)
-  const year = first.getUTCFullYear()
-  const month = first.getUTCMonth() + 1
-  const daysInMonth = new Date(Date.UTC(year, month, 0)).getUTCDate()
-  const firstWeekday = (first.getUTCDay() + 6) % 7 /* 周一=0 */
-  const gridStart = monthStart - firstWeekday * DAY
-  const monthEnd = monthStart + (daysInMonth - 1) * DAY
-  const lastWeekday = (new Date(monthEnd + BEIJING).getUTCDay() + 6) % 7
+  /* 一律按本机时区读年月日，与 localDateKey 同口径（别在这里加 8 小时偏移） */
+  const first = new Date(monthStart)
+  const year = first.getFullYear()
+  const month = first.getMonth() + 1
+  const daysInMonth = new Date(year, month, 0).getDate()
+  const firstWeekday = (first.getDay() + 6) % 7 /* 周一=0 */
+  const monthEnd = new Date(year, month - 1, daysInMonth).getTime()
+  const lastWeekday = (new Date(year, month - 1, daysInMonth).getDay() + 6) % 7
   const gridDays = daysInMonth + firstWeekday + (6 - lastWeekday)
+  /* 网格起点：当月 1 号往前退 firstWeekday 天。
+     用**日历逐日构造**而不是 `起点 + i * 24h` —— 后者在有夏令时的时区会错：
+     切换日本地时间整体挪 1 小时，+24h 可能落回同一天（出现两格同一天、另一天缺失），
+     实测纽约 / 伦敦 / 悉尼 / 圣地亚哥都会中（UTC+8 的机器上永远看不到）。
+     逐日构造让每格都稳稳落在本地 00:00。 */
+  const gridStartDate = new Date(year, month - 1, 1 - firstWeekday)
+  const dayAt = (i) => new Date(
+    gridStartDate.getFullYear(),
+    gridStartDate.getMonth(),
+    gridStartDate.getDate() + i
+  ).getTime()
   const days = []
   let max = 0
   let maxDate = null
   for (let i = 0; i < gridDays; i += 1) {
-    const at = gridStart + i * DAY
+    const at = dayAt(i)
     const key = localDateKey(at)
     const inMonth = at >= monthStart && at <= monthEnd
     const bucket = ledger.days[key]
@@ -3100,13 +3343,13 @@ function monthUsagePayload(ledger, monthStart) {
  * 客户端拿它画「活跃总览」标题下面那 12 个方块（配色规则与右侧月历一致）。
  */
 function yearUsagePayload(ledger, now) {
-  const BEIJING = 8 * 3600 * 1000
-  const year = new Date(now + BEIJING).getUTCFullYear()
+  /* 一律按本机时区读年月日，与 localDateKey 同口径 */
+  const year = new Date(now).getFullYear()
   const months = []
   let max = 0
   let maxMonth = null
   for (let m = 1; m <= 12; m += 1) {
-    const daysInMonth = new Date(Date.UTC(year, m, 0)).getUTCDate()
+    const daysInMonth = new Date(year, m, 0).getDate()
     let input = 0
     let cacheRead = 0
     let cacheWrite = 0
@@ -3114,7 +3357,7 @@ function yearUsagePayload(ledger, now) {
     let calls = 0
     let cost = 0
     for (let d = 1; d <= daysInMonth; d += 1) {
-      const bucket = ledger.days[localDateKey(Date.UTC(year, m - 1, d) - BEIJING)]
+      const bucket = ledger.days[localDateKey(new Date(year, m - 1, d).getTime())]
       if (bucket === undefined) continue
       input += bucket.input || 0
       cacheRead += bucket.cacheRead || 0
@@ -3397,203 +3640,282 @@ export function apply(ctx) {
   ctx.effect(() => ctx.webServer.register({
     kind: 'prefix',
     path: '/dsh-desktop-statusbar/api',
+    /* 整体兜底：handler 里任何一处抛错（如 ctx.get('credentials') 在 try 之外被
+       queryBalance 调到、读盘/解压意外抛出）原本会让这个 Promise reject ——
+       webServer 不替我们收尾，于是既不写响应也不关连接，客户端 fetch **永久 pending**
+       （底栏余额永远停在「查询中」）。这里统一写 500 并结束响应；已经写过响应头
+       （headersSent）时不再二次写，只结束连接，避免 ERR_HTTP_HEADERS_SENT。 */
     handler: async (req, res) => {
-      const url = new URL(req.url ?? '/', 'http://127.0.0.1')
-      if (url.pathname === '/dsh-desktop-statusbar/api/prices') {
-        /* POST = 客户端把它的价格库（localStorage 那份，用户可增删改）报上来。
-           活跃总览的 cost 由 host 记账时算出，必须用同一份价格，否则用户在设置页
-           加/改的单价只对底栏生效、活跃总览恒为旧值（实测 2026-10-07）。 */
-        if (req.method === 'POST') {
-          const body = await readJsonBody(req)
-          const book = body === null ? null : sanitizePriceBook(body.models)
-          if (book === null) {
-            sendJson(res, 400, { ok: false, reason: 'bad-models' })
-            return
-          }
-          /* 判断"价格是否变了"用的快照在队列里取（见下）：并排上报不会双双报"已变更" */
-          /* **在队列里换价格库**：换库必须与"读台账→结算→写盘"是同一段原子操作，
-             否则在途扫描会一半用旧价、一半用新价，同一天的数字混两套价（实测缺陷）。 */
-          let settled = { entries: 0, amount: 0 }
-          let changed = false
-          const swapped = await queueLedgerJob(async () => {
-            const before = activePriceFingerprint
-            clientPrices = book
-            const nowFingerprint = priceFingerprint()
-            activePriceFingerprint = nowFingerprint
-            const nowChanged = before !== nowFingerprint
-            /* 价格变了只做一件事：把"当时没有单价、还没算钱"的欠账按新价结算掉。
-               已经算好的费用一律不动，台账也不重建 —— 所以会话日志被删也不影响已有数字。 */
-            if (nowChanged !== true) return { changed: false, settled: { entries: 0, amount: 0 } }
-            const ledger = readLedger()
-            const done = settleUnpriced(ledger)
-            /* 两种情况才落盘：真结算了欠账；或者盘上还是老版本，顺手把迁移结果固化一次
-               （免得每次都重迁一遍）。没有台账时不在这里创建。
-               **绝不改写 priceFingerprint** —— 那个字段记的是"上次记账用的那份价目表"，
-               是回扫判断"当时有没有价"的唯一依据；价格上报抢先改写它，历史缺价明细就永远补不出来。 */
-            const onDisk = readLedgerFile(ledgerPath())
-            const stale = onDisk !== null && onDisk.version !== LEDGER_VERSION
-            if (done.entries > 0 || stale) {
-              ledger.updatedAt = Date.now()
-              writeLedger(ledger)
-            }
-            return { changed: true, settled: done }
-          })
-          changed = swapped.changed
-          settled = swapped.settled
-          if (changed) {
-            /* 面板的数字要重新取一次（payload 缓存在上面） */
-            weekUsageCache = { at: 0, value: null }
-            weekUsageScan = null
-          }
-          logHost(ctx, 'prices: 收到客户端价格库 ' + String(Object.keys(book).length) + ' 条'
-            + (changed
-              ? '（已变更，结算欠账 ' + String(settled.entries) + ' 项 ¥' + String(settled.amount) + '）'
-              : '（与当前一致）'))
-          sendJson(res, 200, { ok: true, changed: changed, count: Object.keys(book).length, settled: settled })
-          return
-        }
-        /* GET = 官方参考价（价格库为空时客户端拿它自愈），与用户价格库无关 */
-        sendJson(res, 200, {
-          models: {
-            'deepseek-flash': TOKEN_PRICES.peak['deepseek-flash'] === undefined ? null : {
-              peak: TOKEN_PRICES.peak['deepseek-flash'],
-              offPeak: TOKEN_PRICES.offPeak['deepseek-flash'],
-            },
-            'deepseek-v4-pro': {
-              peak: TOKEN_PRICES.peak['deepseek-v4-pro'],
-              offPeak: TOKEN_PRICES.offPeak['deepseek-v4-pro'],
-            },
-          },
-          note: 'CNY per 1M tokens, 高峰=北京时间周一至周五 9-12、14-18（法定节假日与周末全天按空闲价）',
-        })
-        return
-      }
-      if (url.pathname === '/dsh-desktop-statusbar/api/holidays') {
-        const raw = url.searchParams.get('year')
-        const year = raw === null ? NaN : Number(raw)
-        if (Number.isInteger(year) !== true || year < 2020 || year > 2100) {
-          sendJson(res, 400, { ok: false, reason: 'bad-year' })
-          return
-        }
+      try {
+        await handleApi(req, res, ctx)
+      } catch (error) {
+        logHost(ctx, 'api: 未捕获异常 ' + probeDetail(error))
         try {
-          const result = await fetchHolidayDays(year)
-          if (result.ok === true) {
-            /* 落盘：host 自己也要用这份假期表判峰谷，否则 2027 年起底栏与活跃总览口径不一致 */
-            const merged = saveHolidayDays(result.days)
-            logHost(ctxRef, 'holidays: ' + String(year) + ' 年 ' + String(result.days.length)
-              + ' 天（累计 ' + String(merged.length) + ' 天，已落盘）')
-          }
-          sendJson(res, 200, result)
-        } catch (error) {
-          const detail = error !== null && error !== undefined && typeof error.message === 'string' ? error.message : 'fetch-failed'
-          logHost(ctxRef, 'holidays: 抓取失败 ' + detail)
-          sendJson(res, 200, { ok: false, reason: 'fetch-failed' })
+          if (res.headersSent === true) res.end()
+          else sendJson(res, 500, { ok: false, reason: 'internal-error' })
+        } catch (nested) {
+          /* 连接已经断了，没什么可做的 */
         }
-        return
       }
-      if (url.pathname === '/dsh-desktop-statusbar/api/version') {
-        /* 启动自检可能还没回来：等这一次在途的查询，别让客户端误判成「没有新版」 */
-        if (latestVersion.checkedAt === 0 && versionCheck !== null) {
-          try {
-            latestVersion = await versionCheck
-          } catch (error) {
-            /* 保持 latest 为 null，下面按「查不到」处理 */
-          }
-        }
-        const raw = url.searchParams.get('current')
-        const current = raw === null ? '' : raw.trim()
-        sendJson(res, 200, {
-          ok: latestVersion.latest !== null,
-          current,
-          latest: latestVersion.latest,
-          /* 只有确实拿到版本号、且它比本地这个新，才算「有更新」 */
-          hasUpdate: latestVersion.latest !== null && current.length > 0
-            && compareVersions(latestVersion.latest, current) > 0,
-          checkedAt: latestVersion.checkedAt,
-          error: latestVersion.error,
-        })
+    },
+  }), 'dsh-desktop-statusbar: balance api')
+}
+
+async function handleApi(req, res, ctx) {
+  /* 带跨站 Origin 的写请求一律拒绝：浏览器里任意网页都能对本机发简单请求，
+     必须在**改任何状态之前**挡住（判定见 isCrossSiteWrite 的说明）。 */
+  if (isCrossSiteWrite(req) === true) {
+    logHost(ctx, 'api: 拒绝跨站写请求 origin=' + String(req.headers.origin))
+    sendJson(res, 403, { ok: false, reason: 'cross-origin' })
+    return
+  }
+  const url = new URL(req.url ?? '/', 'http://127.0.0.1')
+  if (url.pathname === '/dsh-desktop-statusbar/api/prices') {
+    /* POST = 客户端把它的价格库（localStorage 那份，用户可增删改）报上来。
+       活跃总览的 cost 由 host 记账时算出，必须用同一份价格，否则用户在设置页
+       加/改的单价只对底栏生效、活跃总览恒为旧值（实测 2026-10-07）。 */
+    if (req.method === 'POST') {
+      const body = await readJsonBody(req)
+      const book = body === null ? null : sanitizePriceBook(body.models)
+      if (book === null) {
+        sendJson(res, 400, { ok: false, reason: 'bad-models' })
         return
       }
-      if (url.pathname === '/dsh-desktop-statusbar/api/active-model') {
-        if (req.method === 'POST') {
-          const body = await readJsonBody(req)
-          const model = body !== null && typeof body.model === 'string' ? body.model.trim() : ''
-          if (model.length === 0) {
-            sendJson(res, 400, { ok: false, reason: 'model-required' })
-            return
-          }
-          activeModel = {
-            provider: typeof body.provider === 'string' && body.provider.length > 0 ? body.provider : null,
-            model: model,
-            at: Date.now(),
-          }
-          sendJson(res, 200, { ok: true })
-          return
+      /* 判断"价格是否变了"用的快照在队列里取（见下）：并排上报不会双双报"已变更" */
+      /* **在队列里换价格库**：换库必须与"读台账→结算→写盘"是同一段原子操作，
+         否则在途扫描会一半用旧价、一半用新价，同一天的数字混两套价（实测缺陷）。 */
+      let settled = { entries: 0, amount: 0 }
+      let changed = false
+      const swapped = await queueLedgerJob(async () => {
+        const before = activePriceFingerprint
+        clientPrices = book
+        const nowFingerprint = priceFingerprint()
+        activePriceFingerprint = nowFingerprint
+        const nowChanged = before !== nowFingerprint
+        /* 价格变了只做一件事：把"当时没有单价、还没算钱"的欠账按新价结算掉。
+           已经算好的费用一律不动，台账也不重建 —— 所以会话日志被删也不影响已有数字。 */
+        if (nowChanged !== true) return { changed: false, settled: { entries: 0, amount: 0 } }
+        const ledger = readLedger()
+        const done = settleUnpriced(ledger)
+        /* 两种情况才落盘：真结算了欠账；或者盘上还是老版本，顺手把迁移结果固化一次
+           （免得每次都重迁一遍）。没有台账时不在这里创建。
+           **绝不改写 priceFingerprint** —— 那个字段记的是"上次记账用的那份价目表"，
+           是回扫判断"当时有没有价"的唯一依据；价格上报抢先改写它，历史缺价明细就永远补不出来。 */
+        const onDisk = readJsonObjectFile(ledgerPath())
+        const stale = onDisk !== null && onDisk.version !== LEDGER_VERSION
+        if (done.entries > 0 || stale) {
+          ledger.updatedAt = Date.now()
+          writeLedger(ledger)
         }
-        sendJson(res, 200, {
-          ok: true,
-          provider: activeModel.provider,
-          model: activeModel.model,
-          at: activeModel.at,
-        })
-        return
+        return { changed: true, settled: done }
+      })
+      changed = swapped.changed
+      settled = swapped.settled
+      if (changed) {
+        /* 面板的数字要重新取一次（payload 缓存在上面） */
+        weekUsageCache = { at: 0, value: null }
+        weekUsageScan = null
       }
-      if (url.pathname === '/dsh-desktop-statusbar/api/subagent-usage') {
-        /* 底栏「总计」和「本轮」的队友部分：子智能体是独立会话，它的用量只能这样按 parentSession
-           找回来。`since` 是可选的窗口起点（毫秒）：客户端拿"本轮起点"传进来，「本轮」就只算
-           本轮里队友花了多少；不传就是整会话（「总计」用）。
-           参数不对（客户端拿不到会话 id / 传了别的东西）给 400；会话没有队友、或队友日志
-           全都解不出来时给零值而不是 404 —— 客户端按"加上 0"处理，界面不该因此报错。 */
-        const raw = url.searchParams.get('sessionId')
-        const sessionId = raw === null ? '' : raw.trim()
-        if (sessionId.length === 0 || sessionId.length > 200) {
-          sendJson(res, 400, { ok: false, reason: 'bad-session' })
-          return
-        }
-        /* 非法/缺失的 since 一律当"没传"：空串、非有限数、负数、以及**未来时刻**。
-           本轮起点必然在过去，未来时刻只可能是客户端传了坏值；真按它过滤会把队友的
-           数字静默清零（少算钱），所以宁可忽略。留 5 分钟余量容忍时钟抖动。
-           "当没传"的新语义（task-18 起）：由 host 读父会话日志代推起点；连父会话都没有
-           就本轮为空（`sinceSource='none'`），**不**退回整会话 —— 要整会话就显式传 `since=0`。 */
-        const rawSince = url.searchParams.get('since')
-        const sinceText = rawSince === null ? '' : rawSince.trim()
-        const parsedSince = sinceText.length === 0 ? NaN : Number(sinceText)
-        const usableSince = Number.isFinite(parsedSince) === true && parsedSince >= 0
-          && parsedSince <= Date.now() + 5 * 60 * 1000
-        /* 这个接口只读日志、不排队：它不碰台账，没有与扫描抢写盘的问题 */
-        let value
-        try {
-          value = await collectSubagentUsage(sessionId, usableSince === true ? parsedSince : undefined)
-        } catch (error) {
-          logHost(ctx, 'subagent-usage: 汇总失败 ' + probeDetail(error))
-          value = { ok: false, reason: 'scan-failed' }
-        }
-        sendJson(res, 200, value)
-        return
+      logHost(ctx, 'prices: 收到客户端价格库 ' + String(Object.keys(book).length) + ' 条'
+        + (changed
+          ? '（已变更，结算欠账 ' + String(settled.entries) + ' 项 ¥' + String(settled.amount) + '）'
+          : '（与当前一致）'))
+      sendJson(res, 200, { ok: true, changed: changed, count: Object.keys(book).length, settled: settled })
+      return
+    }
+    /* GET = 官方参考价（价格库为空时客户端拿它自愈），与用户价格库无关 */
+    sendJson(res, 200, {
+      models: {
+        'deepseek-flash': TOKEN_PRICES.peak['deepseek-flash'] === undefined ? null : {
+          peak: TOKEN_PRICES.peak['deepseek-flash'],
+          offPeak: TOKEN_PRICES.offPeak['deepseek-flash'],
+        },
+        'deepseek-v4-pro': {
+          peak: TOKEN_PRICES.peak['deepseek-v4-pro'],
+          offPeak: TOKEN_PRICES.offPeak['deepseek-v4-pro'],
+        },
+      },
+      note: 'CNY per 1M tokens, 高峰=北京时间周一至周五 9-12、14-18（法定节假日与周末全天按空闲价）',
+    })
+    return
+  }
+  if (url.pathname === '/dsh-desktop-statusbar/api/holidays') {
+    const raw = url.searchParams.get('year')
+    const year = raw === null ? NaN : Number(raw)
+    if (Number.isInteger(year) !== true || year < 2020 || year > 2100) {
+      sendJson(res, 400, { ok: false, reason: 'bad-year' })
+      return
+    }
+    try {
+      const result = await fetchHolidayDays(year)
+      if (result.ok === true) {
+        /* 落盘：host 自己也要用这份假期表判峰谷，否则 2027 年起底栏与活跃总览口径不一致 */
+        const merged = saveHolidayDays(result.days)
+        logHost(ctxRef, 'holidays: ' + String(year) + ' 年 ' + String(result.days.length)
+          + ' 天（累计 ' + String(merged.length) + ' 天，已落盘）')
       }
-      if (url.pathname === '/dsh-desktop-statusbar/api/daily-usage') {
-        let value
-        try {
-          value = await refreshWeekUsage(url.searchParams.get('force') === '1', ctx)
-        } catch (error) {
-          logHost(ctx, 'usage: 台账刷新失败 ' + probeDetail(error))
-          value = { ok: false, reason: 'ledger-failed' }
-        }
-        sendJson(res, 200, value)
-        return
+      sendJson(res, 200, result)
+    } catch (error) {
+      const detail = error !== null && error !== undefined && typeof error.message === 'string' ? error.message : 'fetch-failed'
+      logHost(ctxRef, 'holidays: 抓取失败 ' + detail)
+      sendJson(res, 200, { ok: false, reason: 'fetch-failed' })
+    }
+    return
+  }
+  if (url.pathname === '/dsh-desktop-statusbar/api/version') {
+    /* 启动自检可能还没回来：等这一次在途的查询，别让客户端误判成「没有新版」 */
+    if (latestVersion.checkedAt === 0 && versionCheck !== null) {
+      try {
+        latestVersion = await versionCheck
+      } catch (error) {
+        /* 保持 latest 为 null，下面按「查不到」处理 */
       }
-      if (url.pathname === '/dsh-desktop-statusbar/api/tip-diag') {
-        if (req.method === 'POST') appendTipDiag(await readJsonBody(req))
-        sendJson(res, 200, { ok: true })
+    }
+    const raw = url.searchParams.get('current')
+    const current = raw === null ? '' : raw.trim()
+    sendJson(res, 200, {
+      ok: latestVersion.latest !== null,
+      current,
+      latest: latestVersion.latest,
+      /* 只有确实拿到版本号、且它比本地这个新，才算「有更新」 */
+      hasUpdate: latestVersion.latest !== null && current.length > 0
+        && compareVersions(latestVersion.latest, current) > 0,
+      checkedAt: latestVersion.checkedAt,
+      error: latestVersion.error,
+    })
+    return
+  }
+  if (url.pathname === '/dsh-desktop-statusbar/api/self-update') {
+    /* 一键更新：由本插件自己完成，不依赖「插件管理器」这个别的插件，也不走
+       pnpm 的 24 小时发布年龄策略（做法见 self-update.js 顶部说明）。
+       GET = 问当前状态（界面挂在更新中途刷新时能接上）；POST = 发起一次更新。 */
+    if (req.method !== 'POST') {
+      const last = lastUpdateResult()
+      sendJson(res, 200, {
+        ok: true,
+        busy: isUpdating(),
+        last: last === null ? null : {
+          ok: last.ok === true,
+          reason: last.reason === undefined ? null : last.reason,
+          from: last.from === undefined ? null : last.from,
+          to: last.to === undefined ? null : last.to,
+        },
+      })
+      return
+    }
+    const body = await readJsonBody(req)
+    const raw = body === null || typeof body.version !== 'string' ? '' : body.version.trim()
+    /* 目标版本必须是明确的三段式版本号：不接受 latest/tag/范围，避免装到别的东西。
+       空则不传 —— host 会自己问 registry 的最新版。 */
+    if (raw.length > 0 && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(raw) !== true) {
+      sendJson(res, 400, { ok: false, reason: 'bad-version' })
+      return
+    }
+    if (isUpdating() === true) {
+      sendJson(res, 409, { ok: false, reason: 'busy' })
+      return
+    }
+    let target = raw
+    if (target.length === 0) {
+      /* 客户端没带版本就自己查一次最新的 */
+      const checked = await checkLatestVersion()
+      latestVersion = checked
+      if (checked.latest === null) {
+        sendJson(res, 200, { ok: false, reason: checked.error === null ? 'no-version' : checked.error })
         return
       }
-      if (url.pathname !== '/dsh-desktop-statusbar/api/balance') {
-        sendJson(res, 404, { ok: false, reason: 'not-found' })
+      target = checked.latest
+    }
+    const selfDir = resolveSelfDir()
+    logHost(ctxRef, 'update: 收到更新请求 → ' + target + '（当前目录 ' + selfDir + '）')
+    const value = await selfUpdateOnce({
+      selfDir,
+      version: target,
+      logger: (message) => logHost(ctxRef, message),
+    })
+    logHost(ctxRef, 'update: 结果 ' + JSON.stringify(value))
+    sendJson(res, 200, value)
+    return
+  }
+  if (url.pathname === '/dsh-desktop-statusbar/api/active-model') {
+    if (req.method === 'POST') {
+      const body = await readJsonBody(req)
+      const model = body !== null && typeof body.model === 'string' ? body.model.trim() : ''
+      if (model.length === 0) {
+        sendJson(res, 400, { ok: false, reason: 'model-required' })
         return
       }
-      const force = url.searchParams.get('force') === '1'
-      const value = await queryBalance(ctx, force, url.searchParams.get('provider'), url.searchParams.get('model'))
-      sendJson(res, 200, Object.assign({}, value, { probe: accountProbeNote }))
-    },
-  }), 'dsh-desktop-statusbar: balance api')
+      activeModel = {
+        provider: typeof body.provider === 'string' && body.provider.length > 0 ? body.provider : null,
+        model: model,
+        at: Date.now(),
+      }
+      sendJson(res, 200, { ok: true })
+      return
+    }
+    sendJson(res, 200, {
+      ok: true,
+      provider: activeModel.provider,
+      model: activeModel.model,
+      at: activeModel.at,
+    })
+    return
+  }
+  if (url.pathname === '/dsh-desktop-statusbar/api/subagent-usage') {
+    /* 底栏「总计」和「本轮」的队友部分：子智能体是独立会话，它的用量只能这样按 parentSession
+       找回来。`since` 是可选的窗口起点（毫秒）：客户端拿"本轮起点"传进来，「本轮」就只算
+       本轮里队友花了多少；不传就是整会话（「总计」用）。
+       参数不对（客户端拿不到会话 id / 传了别的东西）给 400；会话没有队友、或队友日志
+       全都解不出来时给零值而不是 404 —— 客户端按"加上 0"处理，界面不该因此报错。 */
+    const raw = url.searchParams.get('sessionId')
+    const sessionId = raw === null ? '' : raw.trim()
+    if (sessionId.length === 0 || sessionId.length > 200) {
+      sendJson(res, 400, { ok: false, reason: 'bad-session' })
+      return
+    }
+    /* 非法/缺失的 since 一律当"没传"：空串、非有限数、负数、以及**未来时刻**。
+       本轮起点必然在过去，未来时刻只可能是客户端传了坏值；真按它过滤会把队友的
+       数字静默清零（少算钱），所以宁可忽略。留 5 分钟余量容忍时钟抖动。
+       "当没传"的新语义（task-18 起）：由 host 读父会话日志代推起点；连父会话都没有
+       就本轮为空（`sinceSource='none'`），**不**退回整会话 —— 要整会话就显式传 `since=0`。 */
+    const rawSince = url.searchParams.get('since')
+    const sinceText = rawSince === null ? '' : rawSince.trim()
+    const parsedSince = sinceText.length === 0 ? NaN : Number(sinceText)
+    const usableSince = Number.isFinite(parsedSince) === true && parsedSince >= 0
+      && parsedSince <= Date.now() + 5 * 60 * 1000
+     /* 这个接口会排队（collectSubagentUsage 内部走 queueLedgerJob）——
+        别按「只读、不排队」去理解它的时序。此处原先的注释与实现矛盾，已改正。 */
+    let value
+    try {
+      value = await collectSubagentUsage(sessionId, usableSince === true ? parsedSince : undefined)
+    } catch (error) {
+      logHost(ctx, 'subagent-usage: 汇总失败 ' + probeDetail(error))
+      value = { ok: false, reason: 'scan-failed' }
+    }
+    sendJson(res, 200, value)
+    return
+  }
+  if (url.pathname === '/dsh-desktop-statusbar/api/daily-usage') {
+    let value
+    try {
+      value = await refreshWeekUsage(url.searchParams.get('force') === '1', ctx)
+    } catch (error) {
+      logHost(ctx, 'usage: 台账刷新失败 ' + probeDetail(error))
+      value = { ok: false, reason: 'ledger-failed' }
+    }
+    sendJson(res, 200, value)
+    return
+  }
+  if (url.pathname === '/dsh-desktop-statusbar/api/tip-diag') {
+    if (req.method === 'POST') appendTipDiag(await readJsonBody(req))
+    sendJson(res, 200, { ok: true })
+    return
+  }
+  if (url.pathname !== '/dsh-desktop-statusbar/api/balance') {
+    sendJson(res, 404, { ok: false, reason: 'not-found' })
+    return
+  }
+  const force = url.searchParams.get('force') === '1'
+  const value = await queryBalance(ctx, force, url.searchParams.get('provider'), url.searchParams.get('model'))
+  sendJson(res, 200, Object.assign({}, value, { probe: accountProbeNote }))
 }