dsh-tokenlens 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -4,6 +4,19 @@
 
 **版本记录约定**：同一发布日只保留一个章节，标题取当日**最后一个**已发布版本号；当日多次发布的改动合并到该章节，并在标题下注明当日实际发布过的版本号（npm 上仍可安装这些独立版本）。若当日已有发布，后续小改动不再单独增加版本号，而是并入下一篇日志。这样日志按天规整、不出现同日多个小版本。
 
+## 1.5.0 — 2026-11-02
+
+（当日已发布版本：v1.3.5 / v1.3.6 / v1.3.7 / v1.3.8 / v1.3.9 / v1.4.0 / v1.5.0）
+
+- **feat(open-design): 本机累加 Design Plan 周期用量估算**——Open Design 只提供滚动的 5 小时 / 7 天窗口，**没有「本账期已用」接口**（控制台的 `/billing/usage`、`/billing/coding-plan-usage` 都是 cookie 会话鉴权，Control Key 一律 401）。插件改为累加它观测到的 7 天窗口：每个窗口实例记录历史最大 `usedCredits`，把同一账期内已完成 + 当前的窗口相加，再按 `creditsPerUsd` 折算成美元
+- feat(open-design): **只统计 7 天窗口**——5 小时窗口测量的是同一笔消耗（实测两者 `usedCredits` 完全相同），相加会双重计数
+- feat(open-design): 估算带**覆盖率标注**——`complete: true` 仅当最早观测到的窗口起点等于账期起点；否则显示「仅统计已观测的 N 个窗口」，绝不把下限当完整值
+- feat(wire): snapshot 升到 v4，新增可选 `designPlan: {periodStart, periodEnd, usedCredits, estimatedUsd, windows, complete, since, limitPerWindow}`（仅 open-design）；原始上游窗口行不下发
+- feat(storage): 新增 `$DSH_HOME/dsh-tokenlens/design-plan-ledger.json`（原子写、0600、仅数字与时间戳、保留 6 个账期）；写入失败只降级为内存折叠，绝不影响用量读取
+- feat(ui): 容量卡片新增一行「本期 Design Plan 累计 $X（≈ N 个周额度 · 已覆盖本账期全部窗口 / 仅统计已观测的 N 个窗口）」，悬浮说明「Open Design 没有月度用量接口，此值由本机累加观测得出，仅供参考」
+- feat(config): `designPlanLedgerFile` 可配置（空 = 默认路径）
+- 测试：292 → 307（ledger 单测 10 个：只记周窗口不双计、同窗口取最大值、跨窗口累加、完整性判定、账期切换清零、磁盘往返与历史上限；Host 端到端：三次读累积与瞬时回落不降值、原始行不下发、写入失败仍出估算；客户端：完整/部分两种覆盖率渲染、其它供应商不渲染该行）
+
 ## 1.4.0 — 2026-11-02
 
 （当日已发布版本：v1.3.5 / v1.3.6 / v1.3.7 / v1.3.8 / v1.3.9 / v1.4.0）

package/PROTOCOL.md

@@ -138,6 +138,48 @@ HTTP 401 there (the console UI itself authenticates with a session cookie), so i
 is only a fallback. The wallet is therefore always read first; the plan endpoint
 must not turn a readable balance into a hard error.
 
+### Design Plan period estimate (v1.5.0, open-design only)
+
+Open Design publishes a **monthly** cap (Go: $120/month = 4 × the $30 weekly
+window) but serves no "used this period" endpoint — not even cookie-free reads
+(`/billing/usage` and `/billing/coding-plan-usage` both answer 401 to a Control
+Key). So `snapshot.designPlan` (v4 wire) is a **local estimate** the Host derives
+by observing the weekly windows it sees:
+
+```jsonc
+"designPlan": {
+  "periodStart": "2026-11-02T09:53:18.000Z",   // billing period (billing/summary)
+  "periodEnd":   "2026-12-02T09:53:18.000Z",
+  "usedCredits": 50025,                         // Σ final+current weekly windows
+  "estimatedUsd": 5.0025,                       // usedCredits / creditsPerUsd
+  "windows": 1,                                 // weekly windows observed
+  "complete": true,                             // earliest window starts at periodStart
+  "since": "2026-11-02T09:53:18.000Z",          // first window actually observed
+  "limitPerWindow": 150000                      // the account's real weekly cap
+}
+```
+
+Rules the Host guarantees:
+
+- **Only the 7-day window is counted.** The 5-hour window measures the same spend
+  (live: both report identical `usedCredits`), so summing them double-counts.
+- Within one window instance (`windowStart`) the stored `usedCredits` only ever
+  grows to the **maximum** observed; a transient smaller read never lowers it.
+- A window that disappears from the upstream payload keeps its last (final) value.
+- `complete` is true only when the earliest observed window starts at
+  `periodStart`. Otherwise earlier windows of the period were never seen and the
+  number is a **lower bound** — the UI must say so.
+- Persisted in `$DSH_HOME/dsh-tokenlens/design-plan-ledger.json` (atomic, 0600,
+  numbers/timestamps only, 6 periods retained). A write failure degrades to an
+  in-memory fold and never fails the usage read.
+- The raw upstream window rows never cross the wire; only the summary above does.
+- `designPlan` is absent on every other provider and on an older Host.
+
+Note the account's real caps may differ from the public pricing table (this
+machine reports 50,000 credits per 5h / 150,000 per 7d = $5 / $15 at
+`creditsPerUsd: 10000`, half of the advertised $10 / $30), so the summary reports
+`limitPerWindow` as returned rather than assuming a published number.
+
 Rules:
 
 - `percent` is clamped to `0..100`; an unknown percentage is `null` (render "—"), never a fake 0.

package/README.md

@@ -258,6 +258,7 @@ Control Key 是 **Open Design 桌面端/CLI 登录时写入本机的会话凭据
     pollIntervalMs: 120000              # 后台轮询间隔（毫秒）；0 = 关闭轮询
     statusFile: ''                      # 诊断状态 JSON 路径；空 = 不写文件
     providerStoreFile: ''               # 空 = $DSH_HOME/dsh-tokenlens/providers.json
+    designPlanLedgerFile: ''            # 空 = $DSH_HOME/dsh-tokenlens/design-plan-ledger.json
     stats:
       enabled: true
       ttlMs: 30000                      # 统计结果复用时长；fresh:true 强制重扫
@@ -326,6 +327,7 @@ Control Key 是 **Open Design 桌面端/CLI 登录时写入本机的会话凭据
 - OpenCode 的额度定义见[官方文档](https://opencode.ai/docs/go/#usage-limits)（5h = 月度额度的 20%、周 = 50%、月 = 100%）；接口只返回百分比，插件也只画百分比。
 - Command Code 的 `/alpha/*` 是官方 CLI 自用的私有计费路由；免费 / 无方案账户返回空窗口（显示 `—`），插件不会用方案目录猜额度。
 - Open Design 的窗口按账户实际返回的时长渲染：Go 同时有 5 小时和 7 天窗口，Plus / Pro / Max 只有 7 天窗口；钱包余额是独立于窗口的 USD 额度，用尽后继续扣钱包。查询要求工作区权限，鉴权失败会明确显示错误而不是 0；工作区 ID 与 Control Key 缺任一项时，弹窗会指出缺哪一项并给出「去配置」入口（v1.3.5）。窗口、余额、套餐档位是**三层独立读取**（v1.4.0）：任一接口不可用时只少那一块数据，不会整套报错。
+- **「本期 Design Plan 累计」是插件本机算的估算值**（v1.5.0）。Open Design 有月度额度（Go 为每月 $120 = 4 × 每周 $30），但**没有「本账期已用」接口**——控制台的 `/billing/usage`、`/billing/coding-plan-usage` 都靠浏览器 Cookie 鉴权，Control Key 一律 401。于是插件累加它观测到的 **7 天窗口**（只记 7 天，因为 5 小时窗口测量的是同一笔消耗，相加会重复计数），按 `creditsPerUsd` 折算成美元；弹窗会标注覆盖情况（「已覆盖本账期全部窗口」或「仅统计已观测的 N 个窗口」），插件没运行期间错过的窗口无法计入。
 - 未配置凭据的供应商 chip 静默隐藏；`zai`、`minimax`、`deepinfra` 属 best-effort 适配（未公开接口，失败时按可重试错误优雅降级）。
 - 各供应商的元数据（`kind` / `label` / `shortLabel` / `baseURL` / `apiKeyRef` / `consoleUrl`）集中在 `lib/providers.mjs` 的 `PROVIDER_DEFAULTS` 与 `ADAPTERS` 中，新增适配器只需在该文件登记并补测试。
 
@@ -437,7 +439,7 @@ Host 半注册 `tokenlens_usage`，参数 `action`（默认 `snapshot`）与可
 
 ## 验证
 
-- `node --test`：**292 个自动化用例**，覆盖 Host 数据层、供应商适配器、统计折叠、各 harness 读取、插件集成与浏览器端渲染 / 交互。
+- `node --test`：**307 个自动化用例**，覆盖 Host 数据层、供应商适配器、统计折叠、各 harness 读取、Design Plan 周期账本、插件集成与浏览器端渲染 / 交互。
 - 在真实环境中验证过 **5 个 harness** 的数据源；本机统计与独立的 SQLite 查询、独立的日志解析逐项对账（差额为 0），跨 harness 合并与供应商映射算术自洽。
 - 供应商接口按各官方文档与参考客户端行为验证；未配置凭据时 chip 静默隐藏，接口异常时按可重试错误降级。
 

package/client.js

@@ -339,6 +339,12 @@ window.__ModuleLoader__.load({
       providerControlKeySaved: '已保存；要替换请重新粘贴',
       configureProvider: '去配置',
       errorOpenDesignConfig: 'Open Design 额度查询需要工作区 ID 与 Control Key（不是推理 Key）',
+      designPlanLabel: '本期 Design Plan 累计',
+      designPlanHint:
+        'Open Design 没有月度用量接口，此值由插件在本机累加观测到的 7 天窗口得出，仅供参考；未观测到的窗口不会计入',
+      designPlanWindowsOf: '≈ {count} 个周额度',
+      designPlanComplete: '已覆盖本账期全部窗口',
+      designPlanPartial: '仅统计已观测的 {count} 个窗口',
       providerSave: '保存',
       providerSaving: '保存中…',
       providerTest: '测试连接',
@@ -594,6 +600,12 @@ window.__ModuleLoader__.load({
       providerControlKeySaved: 'Saved; paste again to replace it',
       configureProvider: 'Configure',
       errorOpenDesignConfig: 'Open Design quota needs a workspace ID and a Control Key (not an inference key)',
+      designPlanLabel: 'Period Design Plan (estimate)',
+      designPlanHint:
+        'Open Design serves no period-usage endpoint: this value accumulates the 7-day windows observed on this machine. Windows observed while the plugin was not running are not counted.',
+      designPlanWindowsOf: '≈ {count} weekly allowances',
+      designPlanComplete: 'covers every window of this period',
+      designPlanPartial: 'only {count} observed window(s)',
       providerConsoleURLPlaceholder: 'Leave empty for the built-in default',
       providerSave: 'Save',
       providerSaving: 'Saving…',
@@ -1059,6 +1071,32 @@ window.__ModuleLoader__.load({
       return { console: url }
     }
 
+    /**
+     * The open-design period estimate (v1.5.0), or null.
+     *
+     * Open Design serves no period-usage endpoint, so the Host accumulates the
+     * weekly windows it observes. Everything here is optional: an older Host
+     * omits the field entirely and renders no line.
+     */
+    function normalizeDesignPlan(raw) {
+      if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null
+      const usedCredits = numberOrNull(raw.usedCredits)
+      if (usedCredits === null || usedCredits <= 0) return null
+      const windows = Number.isFinite(raw.windows) && raw.windows > 0 ? Math.round(raw.windows) : 0
+      const estimatedUsd = numberOrNull(raw.estimatedUsd)
+      const limitPerWindow = numberOrNull(raw.limitPerWindow)
+      return {
+        periodStart: stringOrEmpty(raw.periodStart),
+        periodEnd: stringOrEmpty(raw.periodEnd),
+        usedCredits,
+        estimatedUsd,
+        windows,
+        complete: raw.complete === true,
+        since: stringOrEmpty(raw.since),
+        limitPerWindow: limitPerWindow !== null && limitPerWindow > 0 ? limitPerWindow : null,
+      }
+    }
+
     /** The whole wire snapshot, or null. */
     function normalizeSnapshot(raw) {
       if (raw === null || typeof raw !== 'object') return null
@@ -1080,6 +1118,8 @@ window.__ModuleLoader__.load({
         credits: normalizeCredits(raw.credits),
         account: normalizeAccount(raw.account),
         links: normalizeLinks(raw.links),
+        // v1.5.0: open-design only; absent everywhere else.
+        designPlan: normalizeDesignPlan(raw.designPlan),
         fetchedAt: stringOrEmpty(raw.fetchedAt),
         ageMs: Number.isFinite(raw.ageMs) ? raw.ageMs : null,
         stale: raw.stale === true,
@@ -3911,6 +3951,66 @@ window.__ModuleLoader__.load({
       )
     }
 
+    /**
+     * The open-design period estimate row (v1.5.0).
+     *
+     * Open Design has no period-usage endpoint, so this is the Host's local
+     * accumulation of the weekly windows it observed. It is labelled as an
+     * estimate and carries a coverage note: when the first observed window does
+     * not start at the billing period start, earlier windows were never seen and
+     * the value is a lower bound.
+     */
+    function buildDesignPlanRow(designPlan, t) {
+      if (designPlan === null) return null
+      const parts = []
+      if (designPlan.estimatedUsd !== null) {
+        parts.push(
+          h(
+            'span',
+            { key: 'usd', className: 'dsh-tokenlens-percent dsh-tokenlens-capacity-money' },
+            formatMoney(designPlan.estimatedUsd, 'USD'),
+          ),
+        )
+      } else {
+        parts.push(
+          h(
+            'span',
+            { key: 'credits', className: 'dsh-tokenlens-percent dsh-tokenlens-capacity-money' },
+            formatTokensPrecise(designPlan.usedCredits),
+          ),
+        )
+      }
+      const notes = []
+      if (designPlan.limitPerWindow !== null && designPlan.usedCredits > 0) {
+        const ratio = designPlan.usedCredits / designPlan.limitPerWindow
+        notes.push(t('designPlanWindowsOf', { count: ratio.toFixed(1) }))
+      }
+      if (designPlan.complete === true) notes.push(t('designPlanComplete'))
+      else if (designPlan.windows > 0) notes.push(t('designPlanPartial', { count: designPlan.windows }))
+      return h(
+        'div',
+        {
+          key: 'design-plan',
+          className: 'dsh-tokenlens-row',
+          'data-capacity-designplan': 'true',
+          title: t('designPlanHint'),
+        },
+        h(
+          'div',
+          { className: 'dsh-tokenlens-row-head' },
+          h('span', { className: 'dsh-tokenlens-row-label' }, t('designPlanLabel')),
+          parts,
+        ),
+        notes.length > 0
+          ? h(
+              'div',
+              { className: 'dsh-tokenlens-capacity-tokens', 'data-kind': designPlan.complete === true ? 'complete' : 'partial' },
+              notes.join(' · '),
+            )
+          : null,
+      )
+    }
+
     /** The provider/plan/account header line, or null when there is nothing to say. */
     function buildProviderHeader(snapshot, t) {
       if (snapshot === null) return null
@@ -5267,15 +5367,19 @@ window.__ModuleLoader__.load({
         } else if (snapshot.provider.kind === 'windows') {
           // A windows provider may ALSO report an independent wallet balance
           // (OpenDesign): show it as one extra row of the same capacity card,
-          // after the allowance windows (or after the "no usage" hint).
+          // after the allowance windows (or after the "no usage" hint). The same
+          // applies to the local period estimate (v1.5.0).
           const balanceRow = buildCapacityBalanceRow(snapshot.balance, t)
+          const designPlanRow = buildDesignPlanRow(snapshot.designPlan, t)
           if (snapshot.windows !== null) {
             const rows = WINDOW_ORDER.map((id) => buildWindowRow(id, snapshot.windows[id], state, now, t, statsRow))
             if (balanceRow !== null) rows.push(balanceRow)
+            if (designPlanRow !== null) rows.push(designPlanRow)
             section.push(h('div', { key: 'rows', className: 'dsh-tokenlens-rows' }, rows))
           } else {
             section.push(h('div', { key: 'no-windows', className: 'dsh-tokenlens-hint' }, t('chipNoUsage')))
             if (balanceRow !== null) section.push(balanceRow)
+            if (designPlanRow !== null) section.push(designPlanRow)
           }
         } else {
           section.push(h('div', { key: 'no-kind', className: 'dsh-tokenlens-hint' }, t('chipNoUsage')))

package/index.js

@@ -38,6 +38,13 @@ import {
   saveProviderStore,
 } from './lib/provider-store.mjs'
 import { makeCustomAdapter, sanitizeUsageBaseURL, validateCustomProvider } from './lib/custom-provider.mjs'
+import {
+  defaultDesignPlanLedgerFile,
+  loadLedger,
+  observeDesignPlan,
+  saveLedger,
+  summarizeDesignPlan,
+} from './lib/design-plan-ledger.mjs'
 import { redactEndpoint, redactPaths, redactTextPaths } from './lib/redact.mjs'
 import { UPDATE_CHECK_URL, UPDATE_PACKAGE_URL, buildUpdateInfo, parseLatestVersion } from './lib/update-check.mjs'
 
@@ -76,7 +83,7 @@ export const inject = []
 export const PLUGIN_NAME = 'dsh-tokenlens'
 
 /** Plugin version; mirrors package.json (kept here so diagnostics need no fs read). */
-export const PLUGIN_VERSION = '1.4.0'
+export const PLUGIN_VERSION = '1.5.0'
 
 /** Documented defaults; every field of the raw row config is optional. */
 const DEFAULTS = {
@@ -88,6 +95,8 @@ const DEFAULTS = {
   statusFile: '',
   // Empty selects $DSH_HOME/dsh-tokenlens/providers.json.
   providerStoreFile: '',
+  // Empty selects $DSH_HOME/dsh-tokenlens/design-plan-ledger.json.
+  designPlanLedgerFile: '',
   stats: {
     enabled: true,
     ttlMs: 30_000,
@@ -175,6 +184,10 @@ export function normalize(raw) {
     statusFile: typeof value.statusFile === 'string' ? value.statusFile : DEFAULTS.statusFile,
     providerStoreFile:
       typeof value.providerStoreFile === 'string' ? value.providerStoreFile : DEFAULTS.providerStoreFile,
+    designPlanLedgerFile:
+      typeof value.designPlanLedgerFile === 'string'
+        ? value.designPlanLedgerFile
+        : DEFAULTS.designPlanLedgerFile,
     stats: {
       enabled: statsRaw.enabled !== false,
       ttlMs: nonNegative(statsRaw.ttlMs, DEFAULTS.stats.ttlMs),
@@ -383,6 +396,49 @@ export function apply(ctx, rawConfig) {
     config.providerStoreFile !== '' ? config.providerStoreFile : defaultProviderStoreFile(dshHomeOf(process.env))
   let providerStore = loadProviderStore(providerStoreFile)
 
+  // Design Plan period ledger (v1.5.0): OpenDesign serves rolling 5h/7d windows
+  // but no period-usage endpoint, so the Host accumulates what it observes.
+  const designPlanLedgerFile =
+    config.designPlanLedgerFile !== ''
+      ? config.designPlanLedgerFile
+      : defaultDesignPlanLedgerFile(dshHomeOf(process.env))
+  let designPlanLedger = loadLedger(designPlanLedgerFile)
+
+  /**
+   * Fold one OpenDesign observation into the period ledger.
+   *
+   * `designPlan` is the provider read's extra context (period bounds + credits
+   * rate + the upstream window rows); it is absent for every other provider and
+   * whenever the quota route was unreadable, in which case nothing is recorded.
+   */
+  function recordDesignPlan(designPlan, now) {
+    if (designPlan === null || typeof designPlan !== 'object') return
+    const folded = observeDesignPlan(designPlanLedger, {
+      periodStart: designPlan.periodStart,
+      periodEnd: designPlan.periodEnd,
+      creditsPerUsd: designPlan.creditsPerUsd,
+      windows: designPlan.windows,
+      now,
+    })
+    if (!folded.changed) return
+    try {
+      designPlanLedger = saveLedger(designPlanLedgerFile, folded.ledger)
+      noteStatus('design-plan-ledger', { designPlanLedgerFile })
+    } catch (error) {
+      // A ledger write must never break a usage read: keep the in-memory fold.
+      designPlanLedger = folded.ledger
+      warn(`design plan ledger write failed: ${String(error?.message ?? error)}`)
+    }
+  }
+
+  /** The period estimate for the open-design snapshot, or null. */
+  function designPlanSummaryFor(providerId, designPlan) {
+    if (canonicalProviderId(providerId) !== 'open-design') return null
+    const periodStart = designPlan?.periodStart
+    if (typeof periodStart !== 'string' || periodStart === '') return null
+    return summarizeDesignPlan(designPlanLedger, periodStart)
+  }
+
   /** Built-in defaults + profile config + management-page overrides. */
   function effectiveProviderConfig(providerId) {
     const id = canonicalProviderId(providerId)
@@ -1110,6 +1166,11 @@ export function apply(ctx, rawConfig) {
   }
 
   function snapshotFromResult(providerId, read, now) {
+    // v1.5.0: the Design Plan period estimate. The ledger observes every read
+    // (refreshes and background polls), then the current period is summarized
+    // into the snapshot so the dialog can show it without a second round-trip.
+    recordDesignPlan(read.result.designPlan ?? null, now)
+    const designPlan = designPlanSummaryFor(providerId, read.result.designPlan)
     return buildSnapshot({
       provider: providerInfo(providerId),
       plan: read.result.plan ?? null,
@@ -1118,6 +1179,8 @@ export function apply(ctx, rawConfig) {
       credits: read.result.credits ?? null,
       account: read.result.account ?? null,
       links: consoleLinks(providerId, read.result),
+      // Only open-design reports a period estimate (see design-plan-ledger.mjs).
+      ...(designPlan === null ? {} : { designPlan }),
       fetchedAtMs: read.fetchedAtMs,
       now,
       latencyMs: read.latencyMs,

package/lib/design-plan-ledger.mjs

@@ -0,0 +1,266 @@
+/**
+ * The Open Design "Design Plan" ledger: a local, honest reverse-derivation of
+ * how much of a billing period's allowance has been used.
+ *
+ * WHY THIS EXISTS
+ *
+ * Open Design exposes the Design Plan allowance only as *rolling windows*
+ * (5 hours and 7 days). There is no "current period usage" endpoint: the
+ * console's own `/billing/usage` and `/billing/coding-plan-usage` routes are
+ * cookie-authenticated, and a Control Key gets HTTP 401. The monthly cap itself
+ * is real (`Go` is advertised as $120/month, 4 × the $30 weekly window) but the
+ * "used so far this period" number is never served.
+ *
+ * So the Host remembers what it has *observed*. Every successful open-design
+ * read reports the current window instances; this ledger keeps, per instance,
+ * the HIGHEST `usedCredits` ever seen (a window's usage only grows until it
+ * resets), and sums the finished + current weekly windows that belong to one
+ * billing period.
+ *
+ * WHY THE 7-DAY WINDOW IS THE UNIT
+ *
+ * The 5-hour and 7-day windows are simultaneous, overlapping limits over the
+ * same spend — a moment can show `usedCredits` identical in both (verified
+ * live: 48,195 in the 5h window and 48,195 in the 7d window). Summing both
+ * would double-count every credit. The 7-day window is the longest Design Plan
+ * window, so it alone tiles the period without overlap.
+ *
+ * WHAT IT CANNOT DO
+ *
+ * Observation starts when the plugin first runs. Earlier windows of the same
+ * period are unknowable, so the summary reports `complete` (true only when the
+ * earliest observed window starts at the period start) and `since`, and the UI
+ * must present the number as an estimate rather than an official figure.
+ *
+ * Storage: `$DSH_HOME/dsh-tokenlens/design-plan-ledger.json`, atomic, owner-only,
+ * numbers and timestamps only — no credentials, no prompts.
+ */
+import { chmodSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+/** Ledger schema version; a mismatch discards the file (regenerate by observing). */
+export const LEDGER_VERSION = 1
+
+/** The weekly window length; it is the accounting unit (see the module doc). */
+export const WEEKLY_SECONDS = 604800
+
+/** How many periods to retain (older ones only cost a little disk). */
+const MAX_PERIODS = 6
+
+/** How many window observations one period may hold (guards a runaway file). */
+const MAX_WINDOWS = 64
+
+/** Credits are decimal strings in the upstream document; accept a safe integer. */
+function creditsOf(value) {
+  if (typeof value === 'string' && /^\d{1,40}$/.test(value)) return Number(value)
+  if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0) return value
+  return null
+}
+
+/** An ISO string, or '' when the value is not one. */
+function isoOf(value) {
+  if (typeof value !== 'string' || value.trim() === '') return ''
+  const ms = Date.parse(value)
+  return Number.isFinite(ms) ? new Date(ms).toISOString() : ''
+}
+
+/** The empty ledger document. */
+export function emptyLedger() {
+  return { version: LEDGER_VERSION, periods: {} }
+}
+
+/** Read the ledger; a missing or unusable file is an empty ledger (never throws). */
+export function loadLedger(file) {
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8'))
+    if (parsed === null || typeof parsed !== 'object' || parsed.version !== LEDGER_VERSION) return emptyLedger()
+    const periods = {}
+    for (const [start, period] of Object.entries(parsed.periods ?? {})) {
+      if (!isoOf(start)) continue
+      if (period === null || typeof period !== 'object') continue
+      const windows = {}
+      for (const [key, window] of Object.entries(period.windows ?? {})) {
+        if (!isoOf(key) || window === null || typeof window !== 'object') continue
+        const used = creditsOf(window.usedCredits)
+        if (used === null) continue
+        windows[key] = {
+          usedCredits: used,
+          limitCredits: creditsOf(window.limitCredits) ?? 0,
+          durationSeconds: Number.isSafeInteger(window.durationSeconds) ? window.durationSeconds : WEEKLY_SECONDS,
+          resetsAt: isoOf(window.resetsAt),
+          lastSeenAt: isoOf(window.lastSeenAt),
+        }
+      }
+      periods[start] = {
+        periodEnd: isoOf(period.periodEnd),
+        creditsPerUsd: Number.isSafeInteger(period.creditsPerUsd) && period.creditsPerUsd > 0
+          ? period.creditsPerUsd
+          : null,
+        windows,
+      }
+    }
+    return { version: LEDGER_VERSION, periods }
+  } catch {
+    return emptyLedger()
+  }
+}
+
+/** Persist the ledger atomically (tmp + rename, mode 0600). Returns the document written. */
+export function saveLedger(file, ledger) {
+  const periods = {}
+  // Newest periods first, then keep a bounded history.
+  for (const [start, period] of Object.entries(ledger.periods ?? {})
+    .sort(([left], [right]) => right.localeCompare(left))
+    .slice(0, MAX_PERIODS)) {
+    periods[start] = {
+      periodEnd: period.periodEnd ?? '',
+      creditsPerUsd: period.creditsPerUsd ?? null,
+      windows: Object.fromEntries(Object.entries(period.windows ?? {}).slice(0, MAX_WINDOWS)),
+    }
+  }
+  const document = { version: LEDGER_VERSION, periods }
+  mkdirSync(dirname(file), { recursive: true })
+  const temp = `${file}.${process.pid}.${Date.now().toString(36)}.tmp`
+  writeFileSync(temp, `${JSON.stringify(document, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 })
+  try {
+    chmodSync(temp, 0o600)
+  } catch {
+    /* POSIX-only nicety; Windows ACLs are inherited */
+  }
+  try {
+    renameSync(temp, file)
+  } catch (error) {
+    try {
+      unlinkSync(temp)
+    } catch {
+      /* best-effort cleanup */
+    }
+    throw error
+  }
+  return document
+}
+
+/**
+ * Fold one observation into the ledger (pure: returns a new document).
+ *
+ * @param ledger - the current document (`loadLedger` or `emptyLedger`).
+ * @param input.periodStart - the billing period start (ISO); the period key.
+ * @param input.periodEnd - the billing period end (ISO), optional.
+ * @param input.creditsPerUsd - credits per US dollar, optional.
+ * @param input.windows - the upstream window rows (`durationSeconds`, `usedCredits`,
+ *   `limitCredits`, `windowStart`/`resetsAt`).
+ * @param input.now - epoch ms of the observation.
+ * @returns `{ ledger, changed }` where `changed` is false when nothing grew.
+ *
+ * Only the weekly window is recorded: the 5-hour window measures the same
+ * spending over a shorter span, so keeping both would double-count the period.
+ * Within one window instance the stored value only ever grows, and an instance
+ * that disappears from the upstream payload keeps its last (final) value.
+ */
+export function observeDesignPlan(ledger, input) {
+  const periodStart = isoOf(input?.periodStart)
+  if (periodStart === '') return { ledger, changed: false }
+  const now = Number.isFinite(input?.now) ? input.now : Date.now()
+  const period = ledger?.periods?.[periodStart] ?? { periodEnd: '', creditsPerUsd: null, windows: {} }
+  const windows = { ...(period.windows ?? {}) }
+  let changed = false
+  for (const row of Array.isArray(input?.windows) ? input.windows : []) {
+    if (row === null || typeof row !== 'object') continue
+    if (row.durationSeconds !== WEEKLY_SECONDS) continue
+    const used = creditsOf(row.usedCredits)
+    if (used === null) continue
+    const start = isoOf(row.windowStart) || isoOf(row.resetsAt)
+    if (start === '') continue
+    const previous = windows[start]
+    const nextLimit = creditsOf(row.limitCredits) ?? 0
+    const resetsAt = isoOf(row.resetsAt)
+    if (previous === undefined) {
+      windows[start] = {
+        usedCredits: used,
+        limitCredits: nextLimit,
+        durationSeconds: WEEKLY_SECONDS,
+        resetsAt,
+        lastSeenAt: new Date(now).toISOString(),
+      }
+      changed = true
+      continue
+    }
+    // A window's usage only grows until it resets; keep the maximum so a
+    // transient smaller read (or a retried request) never lowers the record.
+    const grew = used > previous.usedCredits
+    const limitGrew = nextLimit > previous.limitCredits
+    if (!grew && !limitGrew && resetsAt === previous.resetsAt) continue
+    windows[start] = {
+      ...previous,
+      usedCredits: grew ? used : previous.usedCredits,
+      limitCredits: limitGrew ? nextLimit : previous.limitCredits,
+      resetsAt: resetsAt || previous.resetsAt,
+      lastSeenAt: new Date(now).toISOString(),
+    }
+    changed = true
+  }
+  if (!changed && period.periodEnd === isoOf(input?.periodEnd) && period.creditsPerUsd === (input?.creditsPerUsd ?? null)) {
+    return { ledger, changed: false }
+  }
+  return {
+    ledger: {
+      version: LEDGER_VERSION,
+      periods: {
+        ...(ledger?.periods ?? {}),
+        [periodStart]: {
+          periodEnd: isoOf(input?.periodEnd) || period.periodEnd,
+          creditsPerUsd:
+            Number.isSafeInteger(input?.creditsPerUsd) && input.creditsPerUsd > 0
+              ? input.creditsPerUsd
+              : period.creditsPerUsd,
+          windows,
+        },
+      },
+    },
+    changed,
+  }
+}
+
+/**
+ * Summarize one period: the estimated Design Plan usage the Host has observed.
+ *
+ * @returns `null` when the period has no observations at all, else
+ *   `{ usedCredits, estimatedUsd, windows, complete, since, periodStart, periodEnd, limitPerWindow }`.
+ *   `complete` is true only when the earliest observed window starts at the
+ *   period start — otherwise earlier windows of this period were never seen and
+ *   the number is a lower bound.
+ */
+export function summarizeDesignPlan(ledger, periodStart) {
+  const key = isoOf(periodStart)
+  if (key === '') return null
+  const period = ledger?.periods?.[key]
+  if (period === undefined) return null
+  const entries = Object.entries(period.windows ?? {}).sort(([left], [right]) => left.localeCompare(right))
+  if (entries.length === 0) return null
+  let usedCredits = 0
+  let windows = 0
+  for (const [, window] of entries) {
+    usedCredits += window.usedCredits
+    windows += 1
+  }
+  const creditsPerUsd = period.creditsPerUsd
+  const estimatedUsd =
+    Number.isSafeInteger(creditsPerUsd) && creditsPerUsd > 0 ? usedCredits / creditsPerUsd : null
+  const since = entries[0][0]
+  const limitPerWindow = entries[entries.length - 1][1].limitCredits
+  return {
+    periodStart: key,
+    periodEnd: period.periodEnd || '',
+    usedCredits,
+    estimatedUsd,
+    windows,
+    complete: since === key,
+    since,
+    limitPerWindow: Number.isSafeInteger(limitPerWindow) && limitPerWindow > 0 ? limitPerWindow : null,
+  }
+}
+
+/** The default ledger file: `$DSH_HOME/dsh-tokenlens/design-plan-ledger.json`. */
+export function defaultDesignPlanLedgerFile(dshHome) {
+  return join(dshHome, 'dsh-tokenlens', 'design-plan-ledger.json')
+}

package/lib/go-usage.mjs

@@ -19,7 +19,7 @@
 export const WINDOW_IDS = ['rolling', 'weekly', 'monthly']
 
 /** Version of the wire snapshot shape (see PROTOCOL.md). */
-export const SNAPSHOT_VERSION = 3
+export const SNAPSHOT_VERSION = 4
 
 /** A typed failure the plugin can classify, serialize and test. */
 export class UsageError extends Error {
@@ -141,6 +141,9 @@ export function buildSnapshot(input) {
     balance: input.balance ?? null,
     credits: input.credits ?? null,
     account: input.account ?? null,
+    // v1.5.0 (open-design only): the locally accumulated Design Plan period
+    // estimate. `null` on every other provider and until the first observation.
+    ...(input.designPlan === undefined || input.designPlan === null ? {} : { designPlan: input.designPlan }),
     // Provider-owned web pages the dialog links to (they follow the selection).
     links: input.links ?? null,
     fetchedAt: new Date(input.fetchedAtMs).toISOString(),

package/lib/providers.mjs

@@ -897,10 +897,22 @@ export function parseOpenDesignWallet(payload, workspaceId) {
  */
 export function parseOpenDesignSummary(payload) {
   const document = payload !== null && typeof payload === 'object' && !Array.isArray(payload) ? payload : null
-  if (document === null) return { plan: null }
+  if (document === null) {
+    return { plan: null, periodStart: '', periodEnd: '', creditsPerUsd: null }
+  }
   const tier = typeof document.membershipTier === 'string' ? document.membershipTier.trim() : ''
   const plan = tier === '' ? null : { id: tier, label: tier.toUpperCase() }
-  return { plan }
+  // v1.5.0: the billing period bounds and the credits→USD rate, which the Host
+  // needs to turn observed window usage into a period estimate.
+  const iso = (value) =>
+    typeof value === 'string' && Number.isFinite(Date.parse(value)) ? new Date(value).toISOString() : ''
+  const rate = document.creditsPerUsd
+  return {
+    plan,
+    periodStart: iso(document.subscriptionCurrentPeriodStart),
+    periodEnd: iso(document.subscriptionCurrentPeriodEnd),
+    creditsPerUsd: Number.isSafeInteger(rate) && rate > 0 ? rate : null,
+  }
 }
 
 /**
@@ -1008,11 +1020,25 @@ export const ADAPTERS = {
         () => undefined,
       )
       const parsedSummary = parseOpenDesignSummary(summary)
+      // v1.5.0: hand the period context + the raw weekly window rows to the Host
+      // so it can accumulate a period estimate (OpenDesign serves no period-usage
+      // endpoint). `designPlan` is not a wire field: the Host converts it into a
+      // summary and never forwards the raw document.
+      const designPlan =
+        funding !== undefined && Array.isArray(funding?.codingPlan?.windows)
+          ? {
+              periodStart: parsedSummary.periodStart,
+              periodEnd: parsedSummary.periodEnd,
+              creditsPerUsd: parsedSummary.creditsPerUsd,
+              windows: funding.codingPlan.windows,
+            }
+          : null
       return {
         kind: 'windows',
         windows: parsed.windows,
         plan: parsed.plan ?? parsedSummary.plan,
         balance: walletParsed.balance,
+        designPlan,
       }
     },
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-tokenlens",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "type": "module",
   "description": "dsh-TokenLens (词元透镜) — provider-aware plan capacity plus local token statistics (today/7d/30d/all-time, by harness/provider/model/workspace) for DSH.",
   "license": "MIT",