dsh-any-agent 0.6.1 → 0.6.2

package/CHANGELOG.md

@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.2] — 2026-11-08
+
+### Added
+
+- **Token usage in the live view.** A new `usage` event carries the run's token
+  delta (uncached input, output, cache read, cache write), the session total and
+  the context-window use, read from DSH's own projection cache. It updates during
+  a run (throttled to every 2 s, only when the numbers change; verified against
+  real DSH, which updates its totals after every model step) and once more with
+  the final numbers after the run ends. `watch` shows per-run and session totals;
+  the dashboard adds a token stat, per-run tokens on each turn, and a "Token 消耗"
+  panel (input / output / cache-hit rate, composition, context window, per-turn
+  chart). Counts are metadata only and are written at every level except `off`.
+
+### Changed
+
+- **`watch` redraws in place.** It now runs on the terminal's alternate screen
+  (like `top`) and rewrites only the lines that changed, instead of clearing the
+  screen every tick — which in Windows Terminal piled every frame into the
+  scrollback. Lines are clipped to the terminal width (CJK counted as two
+  columns) and the frame to its height; leaving restores the original screen.
+- **Dashboard: inspector column and scrollable turns.** Wide screens get a right
+  column for the selected conversation: totals, per-tool breakdown, files read /
+  written, approvals. A long turn scrolls inside its card (hidden scrollbar, edge
+  fades, a "↓ N 条" hint), follows the newest tool while you are at the bottom,
+  and keeps your position across live updates when you scroll up. The page no
+  longer caps its width, so ultra-wide screens are filled.
+- Viewers prefer the caller's `title_hint` over DSH's native title, which is only
+  a truncated prefix of the first prompt.
+
+### Fixed
+
+- Dashboard: on narrow screens the token stat's long label widened the header
+  and caused horizontal scrolling; stat labels now truncate and the full token
+  breakdown is in a tooltip.
+
 ## [0.6.1] — 2026-11-08
 
 ### Added

package/docs/en/tests.md

@@ -46,8 +46,8 @@ Why model-backed suites do not point `DSH_HOME` at a throwaway sandbox: DSH keep
 | `line-decoder` | 4 | **UTF-8 line framing**: multi-byte characters split across MCP/ACP stream chunks are preserved (no U+FFFD), including CRLF and EOF-without-newline (no tokens) |
 | `read-cursor` | 26 | **`dsh_read` cursor semantics**: text appended to an already-read entry is delivered again (revision cursor, match by `seq`); **each tool call gets its own entry** and a status update replaces that entry in place (they used to be concatenated into one entry under the first call's id); an empty turn's start/end stay two entries; **message segments separated by tool calls get a blank line between them in `answer`** (they used to run together); and `limit` is clamped to 1..500 so `0`/negative cannot spin or drop the tail (no tokens) |
 | `sentinel-redaction` | 19 | **sentinel disk hygiene**: `result.thinking` is stripped, `thinking_omitted` is always a boolean, and `answer`/`error`/`title`/`tools_used[].input` all pass the same credential redaction as approvals (no tokens) |
-| `live-events` | 33 | **live event stream, write side**: a full run through a fake hub and fake ACP process; event order and fields, tools written only on status change, reasoning never written, redacted previews, `meta`/`off` levels, write failures don't affect runs, ask-approval decisions, failure/queue/cancel/forget (no tokens) |
-| `live-view` | 39 | **live viewers**: byte-level line splitting (no broken CJK), call-chain merge, exited writer shown as interrupted, incremental tail (half lines/rotation/removal), `watch --once` through the bin entry, `dashboard` token / Host / read-only checks and SSE (no tokens) |
+| `live-events` | 39 | **live event stream, write side**: a full run through a fake hub and fake ACP process; event order and fields, tools written only on status change, reasoning never written, redacted previews, `meta`/`off` levels, write failures don't affect runs, ask-approval decisions, failure/queue/cancel/forget (no tokens) |
+| `live-view` | 54 | **live viewers**: byte-level line splitting (no broken CJK), call-chain merge, exited writer shown as interrupted, incremental tail (half lines/rotation/removal), `watch --once` through the bin entry, `dashboard` token / Host / read-only checks and SSE (no tokens) |
 | `review` | 70 | **caller review**: default `advisory` tickets carry a checklist + evidence + `dsh_review` entry; `dsh_review` writes the verdict to disk and back into the run and sentinel; `fail`/`partial` require notes; running/unknown runs are refused; review still works after a restart (sentinel-backed); queue and `client_run_id` replay receipts carry the ticket; review records share the sentinel TTL; notes, previews, evidence **and checklist items** are credential-redacted; **path-traversal ids are rejected before any file I/O** (no tokens) |
 | `forget-tombstone` | 10 | **`forget` is terminal**: `release(forget=true)` writes a tombstone, by-id lookups fail with a recovery path, lists exclude it, and deleting the tombstone restores the normal unknown-session path (no tokens) |
 | `bootstrap-profile` | 24 | **first-start profile works in the published zero-dependency form**: copies routing with the built-in YAML subset parser, strips `apiKey`/`headers`/literal secrets, never writes `defaultPreset`, is idempotent, and leaves a user-maintained profile byte-identical (no tokens) |
@@ -81,13 +81,13 @@ Why model-backed suites do not point `DSH_HOME` at a throwaway sandbox: DSH keep
 > **2026-11-06**: `node test/run.mjs` now runs **every** suite and lists all failures at the end (`--bail` restores stop-at-first-failure) — a single stale assertion in `timeout.mjs` used to hide eleven model-backed suites. Model-backed suites re-run in full against DSH 0.2.2-rc.1 on the desktop app's bundled runtime.
 
 <!-- counts:begin (generated by scripts/sync-test-counts.mjs; do not edit by hand) -->
-**`node test/run.mjs` ran 1489 checks in 33 offline suites on this machine (Windows, DSH installed, 5/9 client config fixtures), all passing.** Parenthesised numbers in the table depend on the environment (DSH present or not, platform, filesystem case sensitivity, how many client configs the machine has), so the total moves with it; this line records the environment of the report used for the last sync.
+**`node test/run.mjs` ran 1510 checks in 33 offline suites on this machine (Windows, DSH installed, 5/9 client config fixtures), all passing.** Parenthesised numbers in the table depend on the environment (DSH present or not, platform, filesystem case sensitivity, how many client configs the machine has), so the total moves with it; this line records the environment of the report used for the last sync.
 
 That is **524 assertions in the client-registration suites alone** (`setup` 45, `removal-scope` 24, `config-safety` 407, `real-configs` 48), which is where the 0.3 work actually is.
 
 The model-backed suites (`boundary` 46, `integration` 30, `async` 21, `sentinel` 36, `timeout` 40, `lock` 79, `multi` 19, `list` 17, `permission` 11, `shared-process` 8, `cycle` 36, `concurrency` 31, `capability` 22, `workspace-effect` 24, `acceptance` 36, `reasoning-check` 8) total **464 checks** nominally; with DSH present `smoke` runs 13 more checks in its session sections. They need a working DSH and provider, so re-run them yourself before trusting a release: `node test/run.mjs --all`. `acceptance` **skips explicitly** when the DSH profile has no IDA MCP (`mcp__ida__*`); `shared-process` also skips without DSH.
 
-> Three different totals are intentional: `node test/run.mjs` on this machine (1489), the CI offline job (nominal 1421 on Linux/macOS, 1427 on Windows; hosted runners have no DSH and no client fixtures, so `smoke` skips its session sections and `real-configs` skips entirely), and the model-backed set (464 nominal). Counts are the numbers each suite prints itself, written back from the report by `npm run docs:counts`; don't copy them by hand and don't use one number for a different runner.
+> Three different totals are intentional: `node test/run.mjs` on this machine (1510), the CI offline job (nominal 1442 on Linux/macOS, 1448 on Windows; hosted runners have no DSH and no client fixtures, so `smoke` skips its session sections and `real-configs` skips entirely), and the model-backed set (464 nominal). Counts are the numbers each suite prints itself, written back from the report by `npm run docs:counts`; don't copy them by hand and don't use one number for a different runner.
 <!-- counts:end -->
 
 ### 🔢 After changing tests: counts are computed

package/docs/en/usage.md

@@ -96,6 +96,7 @@ dsh-any-agent dashboard
 - `dashboard`: a **read-only** local page; prints a URL with a one-time token (binds `127.0.0.1` only, checks the Host header, has no control that changes state).
 - Both are separate processes: they don't start the server, never touch the write lock and never talk to DSH, and they show conversations dispatched from every client (Claude Code, Codex, Cursor, …) together.
 - A run whose writer process has exited without finishing is shown as interrupted.
+- **Token usage**: each run's input / output / cache read-write delta, the session total and context-window use, updated while the run is going (numbers come from DSH's own session record). The dashboard's side column has a "Token 消耗" panel and a per-turn chart.
 - Tune with `DSH_MCP_LIVE`: `detail` (default; redacted command/path/prompt previews), `meta` (tool names, status, timing, approval kinds only), `off`. **Reasoning is never written at any level.** Event files share the sentinels' 7-day TTL; `dsh_release(forget=true)` deletes them too.
 
 ## 🤫 Reasoning: hidden by default

package/docs/zh/live-view-design.md

@@ -2,7 +2,7 @@
 
 # 设计稿：让用户看见 DSH 在做什么（live 事件流 + 查看器）
 
-> 状态：**P1 + P2 已实现**，随 0.6.1 发布（见 CHANGELOG）。实现与本文最初草案的差异已在对应小节标注"实现"。
+> 状态：**P1 + P2 已实现**，随 0.6.1 发布；token 用量与查看端改进随 0.6.2 发布（见 CHANGELOG）。实现与本文最初草案的差异已在对应小节标注"实现"。
 >
 > 代码：`src/live.mjs`（写入）、`src/live-view.mjs`（读取 / 归并 / 终端渲染）、`src/live-cli.mjs`（`watch` / `dashboard` 子命令）、`src/live-dashboard.mjs` + `src/live-dashboard.html`（页面）。测试：`test/live-events.mjs`、`test/live-view.mjs`。
 >
@@ -111,6 +111,7 @@ DSH 的工具活动经 ACP 的 `session/update`（`tool_call` / `tool_call_updat
 - **不写** `text` 事件：正文只在哨兵里。
 - **不写** `writer.hello` / `writer.bye`：每条事件已带 `w`，查看端看最后一个写者的 pid 是否存活即可判断"中断"（§6.5）。
 - 排队被取消、插话等待超时、起不来的回合都补一条 `run.end`，查看端不会留下永远"排队 / 运行中"的回合。
+- 新增 `usage`（0.6.2）：本回合 token 增量 `tokens`、会话累计 `session_tokens`、上下文占用 `context {used, window}`。数据来自 DSH 投影缓存的 `tokenUsage.totals` / `contextPressure`。真机实测 DSH 在回合中每个模型步之后就更新它，所以回合开始记基线，工具状态变化 / `usage_update` 时按 2 秒节流发增量，回合结束（git 快照之后）再发一条 `final: true` 的最终值。只是计数，属于 meta 级字段。
 - 真机验证（DSH ACP）发现：`tool_call` **不带 `name`**，工具名在 `title` 里（`read` / `glob` / `write` / `pwsh`），`kind` 恒为 `other`。所以 `title` 是纯标识符时当作 `name` 写进 meta 级字段；带空格的 `title` 仍只进 detail。查看端把路径显示成相对会话目录的形式，并隐藏 `other`。
 
 `tool` 只在状态变化时落盘，避免 DSH 的快照式重复更新刷屏；`tool_call_id` 让查看器原地替换同一工具的行，语义与 `dsh_read` 的"按 seq 替换"一致。

package/docs/zh/tests.md

@@ -45,8 +45,8 @@ npm run docs:counts:check # 只检查文档与报告是否一致，不一致 exi
 | `read-cursor` | 26 | **`dsh_read` 游标语义**：追加到已读条目里的文本必须再次返回（修订号游标，按 `seq` 替换全文）；**每个工具调用各占一条**、状态更新原地替换（以前会拼成一条、只剩第一个工具的 id）；空回合的开始/结束仍是两条；**`answer` 里被工具调用隔开的正文之间补空行**（以前首尾相接）；`limit` 钳到 1..500，`0`/负数不会空转或丢尾（不花 token） |
 | `line-decoder` | 4 | **UTF-8 行分帧**：MCP/ACP 的 chunk 边界不能把中文/emoji 截成 U+FFFD；覆盖逐字节、任意 chunk、CRLF 与 EOF 残留（不花 token） |
 | `sentinel-redaction` | 19 | **哨兵落盘卫生**：`result.thinking` 被剥掉、`thinking_omitted` 始终是布尔值、`answer`/`error`/`title`/`tools_used[].input` 都走与审批相同的凭据脱敏（不花 token） |
-| `live-events` | 33 | **live 事件流写入侧**：假 hub + 假 ACP 进程跑完整回合；事件序列与字段、工具只在状态变化时写、思考内容不落盘、预览脱敏、`meta`/`off` 级别、写失败不影响派活、ask 审批裁决、失败/排队/取消/forget（不花 token） |
-| `live-view` | 39 | **live 查看端**：按字节切行（不切坏中文）、调用链归并、写者退出显示中断、增量 tail（半行/滚动/删除）、`watch --once` 走 bin 入口、`dashboard` 的 token / Host / 只读校验与 SSE（不花 token） |
+| `live-events` | 39 | **live 事件流写入侧**：假 hub + 假 ACP 进程跑完整回合；事件序列与字段、工具只在状态变化时写、思考内容不落盘、预览脱敏、`meta`/`off` 级别、写失败不影响派活、ask 审批裁决、失败/排队/取消/forget（不花 token） |
+| `live-view` | 54 | **live 查看端**：按字节切行（不切坏中文）、调用链归并、写者退出显示中断、增量 tail（半行/滚动/删除）、`watch --once` 走 bin 入口、`dashboard` 的 token / Host / 只读校验与 SSE（不花 token） |
 | `review` | 70 | **调用方审核**：默认 `advisory` 审核单带清单 + 证据 + `dsh_review` 入口；`dsh_review` 把裁决落盘并回写内存 run 与哨兵；`fail`/`partial` 必须给理由；未完成/未知 run 被拒绝；重启后仍可凭哨兵审核；队列与 `client_run_id` 重放收据也带审核单；审核记录与哨兵共享 TTL；理由、预览、证据**与清单项**都凭据脱敏；**路径穿越 id 在触盘前就被拒绝**（不花 token） |
 | `forget-tombstone` | 10 | **`forget` 是终态**：`release(forget=true)` 写墓碑，按 id 查询明确失败并给出恢复路径，列表不再展示；删除墓碑后回到常规“未知会话”路径（不花 token） |
 | `bootstrap-profile` | 24 | **首启 profile 在零依赖发布形态下可用**：内置 YAML 子集解析器复制路由、剥掉 `apiKey`/`headers`/字面密钥、绝不写 `defaultPreset`、幂等；用户手写文件逐字节不动（不花 token） |
@@ -80,13 +80,13 @@ npm run docs:counts:check # 只检查文档与报告是否一致，不一致 exi
 > **2026-11-06**：`node test/run.mjs` 现在**跑完全部套件**再在末尾列出所有失败项（`--bail` 恢复遇错即停）—— 以前 `timeout.mjs` 一条过时断言就让后面 11 个真机套件全部没跑。需要模型的套件已对桌面版自带运行时上的 DSH 0.2.2-rc.1 全量重跑。
 
 <!-- counts:begin (generated by scripts/sync-test-counts.mjs; do not edit by hand) -->
-**`node test/run.mjs` 在本机（Windows，装了 DSH，5/9 个客户端配置 fixture）跑了 33 个离线套件、1489 项检查，全部通过。**表中带括号的数字随环境变化（有没有 DSH、哪个平台、文件系统是否区分大小写、本机装了几个客户端配置），套件总数也随之变化；这一行记录的是上次同步所用报告的环境。
+**`node test/run.mjs` 在本机（Windows，装了 DSH，5/9 个客户端配置 fixture）跑了 33 个离线套件、1510 项检查，全部通过。**表中带括号的数字随环境变化（有没有 DSH、哪个平台、文件系统是否区分大小写、本机装了几个客户端配置），套件总数也随之变化；这一行记录的是上次同步所用报告的环境。
 
 其中 **524 项属于客户端注册器套件**（`setup` 45、`removal-scope` 24、`config-safety` 407、`real-configs` 48）—— 0.3 的活其实都在这里。
 
 需要模型的套件（`boundary` 46、`integration` 30、`async` 21、`sentinel` 36、`timeout` 40、`lock` 79、`multi` 19、`list` 17、`permission` 11、`shared-process` 8、`cycle` 36、`concurrency` 31、`capability` 22、`workspace-effect` 24、`acceptance` 36、`reasoning-check` 8）名义合计 **464 项**；有 DSH 时 `smoke` 还会多跑 13 项会话段。它们要可用的 DSH 与 provider，发版前请自己重跑一遍：`node test/run.mjs --all`。`acceptance` 在没有 IDA MCP（`mcp__ida__*`）时会明确 **skip**；`shared-process` 没有 DSH 时也会 skip。
 
-> 三个总数是刻意分开的：本机 `node test/run.mjs`（1489）、CI 离线 job（名义 Linux/macOS 1421，Windows 1427；hosted runner 没有 DSH 也没有客户端 fixture，`smoke` 跳过会话段、`real-configs` 整体跳过）、需要模型的集合（名义 464）。数字取各套件自己打印的汇总，由 `npm run docs:counts` 从报告写回，不在这里手抄；不要把一个数字套到另一个 runner 上。
+> 三个总数是刻意分开的：本机 `node test/run.mjs`（1510）、CI 离线 job（名义 Linux/macOS 1442，Windows 1448；hosted runner 没有 DSH 也没有客户端 fixture，`smoke` 跳过会话段、`real-configs` 整体跳过）、需要模型的集合（名义 464）。数字取各套件自己打印的汇总，由 `npm run docs:counts` 从报告写回，不在这里手抄；不要把一个数字套到另一个 runner 上。
 <!-- counts:end -->
 
 ### 🔢 改了测试之后：检查数是算出来的

package/docs/zh/usage.md

@@ -96,6 +96,7 @@ dsh-any-agent dashboard
 - `dashboard`：起一个**只读**本地页面，打印出带一次性 token 的地址（只监听 `127.0.0.1`，校验 Host 头，没有任何能改变状态的按钮）。
 - 两者都是独立进程：不启动服务、不碰写锁、不连 DSH，所有客户端（Claude Code、Codex、Cursor…）派出去的会话都能一起看到。
 - 写者进程已退出而回合没有结束的，显示为"中断"。
+- **token 用量**：每个回合的输入 / 输出 / 缓存读写增量、会话累计和上下文窗口占用，回合进行中就会更新（数字取自 DSH 自己的会话记录）。dashboard 右栏有"Token 消耗"面板和每回合用量图。
 - 级别用 `DSH_MCP_LIVE` 调：`detail`（默认，带脱敏后的命令/路径/prompt 预览）、`meta`（只有工具名、状态、计时、审批类型）、`off`。**思考内容在任何级别都不写**。事件文件和哨兵同一个 7 天 TTL；`dsh_release(forget=true)` 会一并删掉。
 
 ## 🤫 思考内容：默认隐藏

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-any-agent",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "Drive DeepSeek Harness (DSH) as a long-lived coding agent from any MCP client — Claude Code, Claude Desktop, Codex, Cursor, Windsurf, Zed, Gemini CLI, opencode, VS Code. Resume-aware, interruptible, approval-capable, and it only ever touches the one config entry it owns.",
   "type": "module",
   "license": "MIT",

package/src/conversation.mjs

@@ -40,7 +40,7 @@ import { rssMb } from './procstat.mjs';
 import { readConversationMeta } from './titles.mjs';
 import { gitStatus, sameWorkspaceSnapshot } from './git-snapshot.mjs';
 import { writeTombstone } from './hub-store.mjs';
-import { emitLive, livePreview, removeLive, summarizeToolInput } from './live.mjs';
+import { emitLive, livePreview, liveSettings, removeLive, summarizeToolInput } from './live.mjs';
 import {
   classifyHolder,
   describeLeaseConflict,
@@ -158,6 +158,61 @@ export class Conversation {
     emitLive(this.id, type, { run: this.#liveRunId(), turn: this.currentTurn, ...fields }, detail);
   }
 
+  /**
+   * live 事件流的 token 跟踪：`{runId, base, at, last}`。
+   * DSH 在投影缓存里维护**会话累计**的 tokenUsage.totals，并在回合中每个模型步之后更新
+   * （真机实测）；回合开始时记下基线，之后发的是"本回合增量"。
+   */
+  #liveUsage = null;
+
+  /** 读 DSH 投影缓存里的 token 累计与上下文压力；读不到返回 null。 */
+  #readTokenUsage() {
+    try {
+      const meta = readConversationMeta(this.id);
+      const t = meta?.usage?.totals;
+      const p = meta?.pressure;
+      if (!t && !p) return null;
+      const n = (v) => (Number.isFinite(v) && v > 0 ? v : 0);
+      return {
+        totals: t
+          ? { input: n(t.uncachedInputTokens), output: n(t.outputTokens), cache_read: n(t.cacheReadTokens), cache_write: n(t.cacheWriteTokens) }
+          : null,
+        context: p && Number.isFinite(p.contextWindow) ? { used: n(p.pressureTokens ?? p.surfaceTokens), window: p.contextWindow } : null,
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * 发一条 `usage` 事件（本回合 token 增量 + 会话累计 + 上下文占用）。
+   * 回合中节流到 2 秒一次、且只在数字变化时发；回合结束后 force 再发一次最终值。
+   */
+  #liveUsageTick({ force = false } = {}) {
+    const u = this.#liveUsage;
+    if (!u) return;
+    const t = now();
+    if (!force && t - u.at < 2000) return;
+    u.at = t;
+    const cur = this.#readTokenUsage();
+    if (!cur?.totals && !cur?.context) return;
+    const base = u.base ?? { input: 0, output: 0, cache_read: 0, cache_write: 0 };
+    const tokens = cur.totals
+      ? Object.fromEntries(Object.keys(base).map((k) => [k, Math.max(0, cur.totals[k] - base[k])]))
+      : null;
+    const sig = JSON.stringify([tokens, cur.context]);
+    if (!force && sig === u.last) return;
+    u.last = sig;
+    emitLive(this.id, 'usage', {
+      run: u.runId,
+      turn: u.turn,
+      tokens,
+      session_tokens: cur.totals,
+      context: cur.context,
+      final: force || undefined,
+    });
+  }
+
   /** 审批裁决事件（decide / 超时 / 回合结束 / 关闭 统一走这里）。 */
   #liveApprovalDecided(approvalId, by, decision = null, effective = null) {
     this.#live('approval.decided', { approval_id: approvalId, by, decision, effective });
@@ -598,6 +653,7 @@ export class Conversation {
       }
       case 'usage_update':
         c.usage = u;
+        this.#liveUsageTick();
         break;
       case 'plan':
       case 'plan_update':
@@ -635,6 +691,7 @@ export class Conversation {
       },
       { title: livePreview(merged.title, 200), input_preview: summarizeToolInput(merged.input) },
     );
+    this.#liveUsageTick();
   }
 
   async onPermissionRequest(params) {
@@ -789,6 +846,7 @@ export class Conversation {
     runRecord.status = 'error';
     runRecord.error = error?.message ?? String(error);
     runRecord.elapsed_ms = 0;
+    if (this.#liveUsage?.runId === runRecord.run_id) this.#liveUsage = null;
     emitLive(
       this.id,
       'run.end',
@@ -912,6 +970,10 @@ export class Conversation {
     this.pushOut('user', text.length > MAX_PROMPT_ECHO ? `${text.slice(0, MAX_PROMPT_ECHO)}…（已截断）` : text);
     this.pushOut('turn', `第 ${this.currentTurn} 轮开始`, { phase: 'start' });
     this.#liveTools.clear();
+    // live 关闭时不读投影缓存（emitLive 会直接丢弃，读了也白读）。
+    this.#liveUsage = liveSettings().level === 'off'
+      ? null
+      : { runId: runRecord.run_id, turn: this.currentTurn, base: this.#readTokenUsage()?.totals ?? null, at: 0, last: '' };
     this.#live(
       'run.start',
       { via, permission: this.permission, on_approval: this.onApproval, cwd: this.cwd },
@@ -1019,6 +1081,12 @@ export class Conversation {
           this.#scheduleDrain();
           // 到这里才允许被 git 拖慢；结果/审核单/哨兵必须等快照完成后再落。
           const after = await afterPromise;
+          // 回合结束后 DSH 的 token 累计已经落盘（真机实测在哨兵之前）：发一次最终值。
+          // 只发给本回合自己的跟踪器——下一回合可能已经在 git 快照期间开始了。
+          if (this.#liveUsage?.runId === runRecord.run_id) {
+            this.#liveUsageTick({ force: true });
+            this.#liveUsage = null;
+          }
           const result = {
             conversation_id: this.id,
             run_id: runRecord.run_id,

package/src/live-cli.mjs

@@ -6,7 +6,7 @@
  */
 
 import { LIVE_DIR, STATE_FILE } from './config.mjs';
-import { LiveTail, renderText } from './live-view.mjs';
+import { LiveTail, diffFrame, layoutFrame, renderText } from './live-view.mjs';
 import { readConversationMeta } from './titles.mjs';
 
 function parseFlags(args) {
@@ -59,19 +59,43 @@ export async function runWatch(args, { out = process.stdout } = {}) {
     return 0;
   }
   const interval = intFlag(flags.interval, 500, 100, 10_000);
-  const draw = () => {
-    // 清屏 + 光标回到左上角，再整屏重画（树会变长变短，增量刷新不值得）。
-    out.write('\x1b[2J\x1b[H' + renderText(tail.view(), opts) + `\n\n${'\x1b[2m'}live 目录: ${tail.dir} · Ctrl+C 退出${'\x1b[0m'}\n`);
+  const tty = Boolean(out.isTTY);
+  const clock = () => new Date().toTimeString().slice(0, 8);
+  const frameText = () =>
+    renderText(tail.view(), opts) + `\n\n\x1b[2m更新于 ${clock()} · live 目录: ${tail.dir} · Ctrl+C 退出\x1b[0m`;
+
+  // ★ 在 TTY 上用"备用屏幕"原地刷新（同 top / htop）：每帧只重写变化的行。
+  //   旧实现每次 `ESC[2J` 清屏，Windows Terminal 会把被清掉的整屏推进回滚区，
+  //   往上一翻就是一摞重复的帧。备用屏幕没有回滚区，退出时原样恢复用户的终端。
+  let prev = null;
+  let lastText = '';
+  const draw = (force = false) => {
+    const text = frameText();
+    if (!tty) {
+      // 管道 / 重定向：没有光标控制，内容变了才追加一帧（去掉时间行再比较，免得每次都算变化）。
+      const body = text.slice(0, text.lastIndexOf('\n\n'));
+      if (body !== lastText) out.write(text.replace(/\x1b\[[0-9;?]*[A-Za-z]/g, '') + '\n\n');
+      lastText = body;
+      return;
+    }
+    const next = layoutFrame(text, { cols: out.columns ?? 120, rows: out.rows ?? 40 });
+    const seq = diffFrame(force ? null : prev, next);
+    if (seq) out.write(seq);
+    prev = next;
+  };
+  const restore = () => {
+    if (tty) out.write('\x1b[0m\x1b[?25h\x1b[?1049l');
   };
-  draw();
-  let lastDraw = Date.now();
+  if (tty) out.write('\x1b[?1049h\x1b[?25l');
+  process.once('exit', restore);
+  draw(true);
+  const onResize = () => draw(true);
+  if (tty) out.on?.('resize', onResize);
   await new Promise((resolve) => {
     const timer = setInterval(() => {
-      // 有新事件就重画；没有也每 5 秒重画一次（刷新"写者是否还活着"）。
-      if (tail.poll() || Date.now() - lastDraw > 5000) {
-        draw();
-        lastDraw = Date.now();
-      }
+      // 有新事件才重算；时间行每秒在变，所以每次都会写，但 diffFrame 只重写真正变了的那几行。
+      tail.poll();
+      draw();
     }, interval);
     const stop = () => {
       clearInterval(timer);
@@ -80,6 +104,9 @@ export async function runWatch(args, { out = process.stdout } = {}) {
     process.once('SIGINT', stop);
     process.once('SIGTERM', stop);
   });
+  out.off?.('resize', onResize);
+  restore();
+  process.off('exit', restore);
   return 0;
 }
 

package/src/live-dashboard.html

@@ -54,7 +54,8 @@ button { font: inherit; color: inherit; }
 .stats { display: flex; align-items: stretch; height: 100%; margin-left: 4px; }
 .stat { display: flex; flex-direction: column; justify-content: center; padding: 0 16px; border-left: 1px solid var(--line); min-width: 74px; }
 .stat b { font-size: 15px; font-weight: 650; line-height: 1.1; }
-.stat span { font-size: 11px; color: var(--text-3); }
+.stat span { font-size: 11px; color: var(--text-3); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.stat { min-width: 0; }
 .stat.hot b { color: var(--run); }
 .stat.warn b { color: var(--warn); }
 .stat.zero b { color: var(--text-3); font-weight: 500; }
@@ -92,7 +93,66 @@ button { font: inherit; color: inherit; }
 @keyframes pulse { 0%, 100% { opacity: 1 } 50% { opacity: .35 } }
 
 /* ── 主区 ───────────────────────────────── */
-.wrap { max-width: 1080px; padding: 22px 28px 48px; }
+/* 不再限制最大宽度：超宽屏上调用链和右栏一起铺满，右栏随窗口在 300–460px 之间伸缩。 */
+.wrap { padding: 22px 28px 48px; }
+.cols { display: grid; grid-template-columns: minmax(0, 1fr) clamp(300px, 24vw, 460px); gap: 24px; align-items: start; }
+.inspector { position: sticky; top: 22px; display: grid; grid-template-columns: minmax(0, 1fr); gap: 14px; min-width: 0; }
+.panel { min-width: 0; background: var(--surface); border: 1px solid var(--line); border-radius: var(--r); padding: 12px 14px; }
+.panel h3 { margin: 0 0 10px; font-size: 11px; font-weight: 600; text-transform: uppercase; letter-spacing: .6px; color: var(--text-3); }
+.kpis { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 10px 8px; }
+.kpi b { display: block; font-size: 17px; font-weight: 650; line-height: 1.15; }
+.kpi span { font-size: 11px; color: var(--text-3); }
+.kpi.bad b { color: var(--bad); }
+.kpi.warn b { color: var(--warn); }
+.kpi.zero b { color: var(--text-3); font-weight: 500; }
+.dist { display: grid; gap: 7px; }
+.dist-row { display: grid; grid-template-columns: minmax(0, 1fr) auto; gap: 2px 8px; font-size: 12px; }
+.dist-row .n { font-weight: 600; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.dist-row .v { color: var(--text-3); white-space: nowrap; }
+.dist-row .bar { grid-column: 1 / 3; height: 5px; border-radius: 3px; background: var(--sunken); overflow: hidden; }
+.dist-row .bar b { display: block; height: 100%; border-radius: 3px; background: var(--bar-run); opacity: .75; }
+.files { list-style: none; margin: 0; padding: 0; display: grid; gap: 5px; }
+.files li { display: grid; grid-template-columns: 30px minmax(0, 1fr); gap: 6px; align-items: baseline; font-size: 12px; }
+.files .op { font-size: 10.5px; font-weight: 600; text-align: center; border-radius: 4px; padding: 0 3px; background: var(--sunken); color: var(--text-2); }
+.files .op.w { background: var(--ok-soft); color: var(--ok); }
+.files .p { font-family: var(--mono); font-size: 11.5px; color: var(--text-2); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; direction: rtl; text-align: left; }
+.aps, .dist, .files { grid-template-columns: minmax(0, 1fr); }
+.aps { display: grid; gap: 8px; }
+.ap { min-width: 0; font-size: 12px; border-left: 2px solid var(--warn); padding: 2px 0 2px 8px; }
+.ap .m { font-weight: 600; color: var(--warn); }
+.ap .c { font-family: var(--mono); font-size: 11.5px; color: var(--text-2); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.muted { font-size: 12px; color: var(--text-3); }
+/* Token 面板 */
+.tok-big { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 8px; margin-bottom: 12px; }
+.tok-big b { display: block; font-size: 18px; font-weight: 650; line-height: 1.15; }
+.tok-big span { font-size: 11px; color: var(--text-3); }
+.stack { display: flex; height: 8px; border-radius: 4px; overflow: hidden; background: var(--sunken); margin-bottom: 6px; }
+.stack i { display: block; height: 100%; min-width: 2px; }
+.c-unc { background: var(--accent); }
+.c-read { background: var(--ok); opacity: .75; }
+.c-write { background: var(--warn); opacity: .8; }
+.c-out { background: var(--bad); opacity: .7; }
+.legend { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 3px 10px; font-size: 11.5px; color: var(--text-2); margin-bottom: 12px; }
+.legend span { display: flex; align-items: center; gap: 6px; min-width: 0; white-space: nowrap; }
+.legend i { width: 8px; height: 8px; border-radius: 2px; flex: none; }
+.legend em { font-style: normal; margin-left: auto; color: var(--text-3); }
+.ctx-h { display: flex; justify-content: space-between; font-size: 11.5px; color: var(--text-2); margin-bottom: 4px; }
+.ctx-h span:last-child { color: var(--text-3); }
+.ctx { height: 6px; border-radius: 3px; background: var(--sunken); overflow: hidden; margin-bottom: 12px; }
+.ctx b { display: block; height: 100%; border-radius: 3px; background: var(--accent); }
+.ctx.hi b { background: var(--warn); }
+.ctx.crit b { background: var(--bad); }
+.spark-h { font-size: 11.5px; color: var(--text-2); margin-bottom: 6px; display: flex; justify-content: space-between; }
+.spark-h span:last-child { color: var(--text-3); }
+.spark { display: flex; align-items: flex-end; gap: 3px; height: 56px; }
+.spark i { flex: 1; min-width: 4px; max-width: 26px; border-radius: 3px 3px 0 0; background: var(--bar); position: relative; }
+.spark i.cur { background: var(--bar-run); }
+.spark i:hover { background: var(--accent); }
+.tok-run { font-family: var(--mono); font-size: 11.5px; }
+@media (max-width: 1180px) {
+  .cols { grid-template-columns: minmax(0, 1fr); }
+  .inspector { position: static; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); }
+}
 .hd h1 { font-size: 19px; font-weight: 650; margin: 0 0 10px; letter-spacing: -.1px; word-break: break-word; }
 .facts { display: grid; grid-template-columns: repeat(auto-fill, minmax(150px, 1fr)); gap: 10px 24px; padding: 12px 16px; margin: 0 0 24px; border: 1px solid var(--line); border-radius: var(--r); background: var(--surface); }
 .fact { min-width: 0; }
@@ -135,7 +195,17 @@ button { font: inherit; color: inherit; }
 .collapsed .body { display: none; }
 
 /* ── 调用链：工具 / 审批（带时间条） ─────── */
-.spans { border-top: 1px solid var(--line); }
+.spans-box { position: relative; border-top: 1px solid var(--line); }
+/* 工具列表过长时在卡片内部滚动，滚动条隐藏；上下边缘用渐隐提示还有内容。 */
+.spans { max-height: min(60vh, 520px); overflow-y: auto; overscroll-behavior: contain; scrollbar-width: none; -ms-overflow-style: none; }
+.spans::-webkit-scrollbar, .rail::-webkit-scrollbar, .main::-webkit-scrollbar { width: 0; height: 0; display: none; }
+.rail, .main { scrollbar-width: none; -ms-overflow-style: none; }
+.spans-box::before, .spans-box::after { content: ""; position: absolute; left: 0; right: 0; height: 28px; pointer-events: none; opacity: 0; transition: opacity .15s ease; z-index: 1; }
+.spans-box::before { top: 0; background: linear-gradient(var(--surface), transparent); }
+.spans-box::after { bottom: 0; background: linear-gradient(transparent, var(--surface)); border-radius: 0 0 var(--r) var(--r); }
+.spans-box.more-up::before, .spans-box.more-down::after { opacity: 1; }
+.spans-count { position: absolute; right: 12px; bottom: 6px; z-index: 2; font-size: 11px; color: var(--text-3); background: var(--surface); border: 1px solid var(--line); border-radius: 999px; padding: 0 8px; opacity: 0; transition: opacity .15s ease; pointer-events: none; }
+.spans-box.more-down .spans-count { opacity: 1; }
 .span { display: grid; grid-template-columns: 22px 92px minmax(0, 1fr) minmax(120px, 26%) 62px; align-items: center; gap: 10px; padding: 0 12px; height: 32px; border-bottom: 1px solid var(--line); font-size: 12.5px; }
 .span:last-child { border-bottom: 0; }
 .span:hover { background: var(--sunken); }
@@ -175,7 +245,7 @@ button { font: inherit; color: inherit; }
 /* ── 窄屏 ───────────────────────────────── */
 @media (max-width: 820px) {
   .top { height: auto; flex-wrap: wrap; gap: 10px 16px; padding: 10px 16px; position: static; }
-  .stats { height: 40px; margin-left: 0; order: 3; width: 100%; }
+  .stats { height: 40px; margin-left: 0; order: 3; width: 100%; overflow: hidden; }
   .stat { flex: 1; min-width: 0; padding: 0 10px; }
   .stat span { white-space: nowrap; }
   .stat:first-child { border-left: 0; padding-left: 0; }
@@ -249,6 +319,14 @@ button { font: inherit; color: inherit; }
     return Math.round(s / 86400) + ' 天前';
   }
   const t = (ts) => (ts ? Date.parse(ts) : NaN);
+  function ftok(n) {
+    if (!isFinite(n)) return '';
+    if (n < 1000) return String(Math.round(n));
+    if (n < 1e6) return (n / 1000).toFixed(n < 10000 ? 1 : 0) + 'k';
+    return (n / 1e6).toFixed(n < 1e7 ? 2 : 1) + 'M';
+  }
+  const tin = (k) => (k ? k.input + k.cache_read + k.cache_write : 0);
+  const hit = (k) => { const a = tin(k); return a > 0 ? k.cache_read / a : null; };
   const STATE = { running: '运行中', queued: '排队中', idle: '空闲', closed: '已释放' };
   const RUN = { running: '运行中', queued: '排队', done: '完成', error: '出错', cancelled: '已取消', interrupted: '中断' };
   const VIA = { send: '派活', queue: '排队', interject: '插话' };
@@ -276,6 +354,12 @@ button { font: inherit; color: inherit; }
     stat(s.queued, '排队', 'warn');
     stat(s.pending_approvals, '待审批', 'warn');
     stat(s.escalations, '提权', 'warn');
+    if (s.tokens) {
+      const d = h('div', 'stat');
+      d.title = '全部会话 token：输入 ' + tin(s.tokens).toLocaleString() + '（缓存读 ' + s.tokens.cache_read.toLocaleString() + '）· 输出 ' + s.tokens.output.toLocaleString();
+      d.append(h('b', null, ftok(tin(s.tokens) + s.tokens.output)), h('span', null, 'token · 出 ' + ftok(s.tokens.output)));
+      box.append(d);
+    }
   }
 
   function renderRail() {
@@ -447,9 +531,11 @@ button { font: inherit; color: inherit; }
     hd.append(facts);
     wrap.append(hd);
 
+    const cols = h('div', 'cols');
+    const left = h('div');
     const sh = h('div', 'sec-h');
     sh.append(h('h2', null, '调用链'), h('span', null, c.runs.length + ' 个回合 · 最新在上'));
-    wrap.append(sh);
+    left.append(sh);
 
     const turns = h('div', 'turns');
     const runs = [...c.runs].reverse();
@@ -478,6 +564,12 @@ button { font: inherit; color: inherit; }
       const rb = h('span'); rb.append(h('b', null, String(n)), ' 个工具'); right.append(rb);
       const t0 = t(r.started_at);
       const total = r.duration_ms != null ? r.duration_ms : r.status === 'running' && isFinite(t0) ? Date.now() - t0 : null;
+      if (r.tokens) {
+        const tk = h('span', 'tok-run');
+        tk.title = '本回合 token：输入 ' + tin(r.tokens) + '（缓存读 ' + r.tokens.cache_read + '）· 输出 ' + r.tokens.output;
+        tk.append(h('b', null, ftok(tin(r.tokens))), '↑ ', h('b', null, ftok(r.tokens.output)), '↓');
+        right.append(tk);
+      }
       if (total != null) { const d = h('span'); d.append(h('b', null, dur(total))); right.append(d); }
       right.append(h('span', null, ago(r.ended_at || r.started_at || r.queued_at)));
       head.append(right);
@@ -489,19 +581,237 @@ button { font: inherit; color: inherit; }
       if (r.prompt_preview) body.append(h('div', 'prompt', r.prompt_preview));
       if (r.error) body.append(h('div', 'errline', r.error));
       if (r.items.length) {
+        const boxEl = h('div', 'spans-box');
         const spans = h('div', 'spans');
+        spans.dataset.key = key;
+        spans.tabIndex = 0; // 键盘也能滚（方向键 / PageDown）
+        spans.setAttribute('aria-label', '工具调用列表');
         for (const it of r.items) spans.append(spanRow(it, r, t0, total, c.cwd));
-        body.append(spans);
+        boxEl.append(spans, h('span', 'spans-count'));
+        body.append(boxEl);
+        pendingScroll.push({ spans, box: boxEl, key, running: r.status === 'running' });
       }
       card.append(body);
       turn.append(card);
       turns.append(turn);
     }
-    wrap.append(turns);
-    wrap.append(h('div', 'foot', '只读视图 · 数据来自本机 live 事件流 · 思考内容从不写入 · 点击回合标题折叠'));
+    left.append(turns);
+    left.append(h('div', 'foot', '只读视图 · 数据来自本机 live 事件流 · 思考内容从不写入 · 点击回合标题折叠'));
+    cols.append(left, inspector(c));
+    wrap.append(cols);
     main.append(wrap);
   }
 
+  /** Token 面板：会话累计（DSH 记录）、构成、上下文窗口、每回合用量。 */
+  function tokenPanel(c) {
+    const p = h('section', 'panel');
+    p.append(h('h3', null, 'Token 消耗'));
+    const k = c.tokens;
+    if (!k) {
+      p.append(h('div', 'muted', '暂无数据：派一次活之后，这里会实时显示本会话的 token 用量。'));
+      return p;
+    }
+    const big = h('div', 'tok-big');
+    const cell = (v, label) => { const d = h('div'); d.append(h('b', null, v), h('span', null, label)); big.append(d); };
+    cell(ftok(tin(k)), '输入');
+    cell(ftok(k.output), '输出');
+    const hr = hit(k);
+    cell(hr == null ? '—' : Math.round(hr * 100) + '%', '缓存命中');
+    p.append(big);
+
+    // 构成：未命中缓存的输入 / 缓存读 / 缓存写 / 输出
+    const parts = [
+      ['c-unc', '未缓存输入', k.input],
+      ['c-read', '缓存读', k.cache_read],
+      ['c-write', '缓存写', k.cache_write],
+      ['c-out', '输出', k.output],
+    ];
+    const sum = parts.reduce((n, x) => n + x[2], 0) || 1;
+    const stack = h('div', 'stack');
+    stack.setAttribute('role', 'img');
+    stack.setAttribute('aria-label', parts.map((x) => x[1] + ' ' + x[2]).join('，'));
+    for (const [cls, label, v] of parts) {
+      if (!v) continue;
+      const i = h('i', cls);
+      i.style.width = (v / sum) * 100 + '%';
+      i.title = label + ' ' + v.toLocaleString();
+      stack.append(i);
+    }
+    p.append(stack);
+    const lg = h('div', 'legend');
+    for (const [cls, label, v] of parts) {
+      const s = h('span');
+      s.append(h('i', cls), label, h('em', null, ftok(v)));
+      lg.append(s);
+    }
+    p.append(lg);
+
+    if (c.context && c.context.window) {
+      const pct = Math.min(100, (c.context.used / c.context.window) * 100);
+      const hh = h('div', 'ctx-h');
+      hh.append(h('span', null, '上下文窗口'), h('span', null, ftok(c.context.used) + ' / ' + ftok(c.context.window) + '（' + (pct < 1 ? pct.toFixed(1) : Math.round(pct)) + '%）'));
+      p.append(hh);
+      const bar = h('div', 'ctx' + (pct > 85 ? ' crit' : pct > 60 ? ' hi' : ''));
+      const b = h('b'); b.style.width = Math.max(1, pct) + '%'; bar.append(b);
+      p.append(bar);
+    }
+
+    const runs = c.runs.filter((r) => r.tokens).slice(-16);
+    if (runs.length) {
+      const per = runs.map((r) => tin(r.tokens) + r.tokens.output);
+      const max = Math.max(...per) || 1;
+      const sh = h('div', 'spark-h');
+      sh.append(h('span', null, '每回合用量'), h('span', null, '最近 ' + runs.length + ' 轮 · 最高 ' + ftok(max)));
+      p.append(sh);
+      const sp = h('div', 'spark');
+      runs.forEach((r, i) => {
+        const bar = h('i', r.status === 'running' ? 'cur' : '');
+        bar.style.height = Math.max(6, (per[i] / max) * 100) + '%';
+        bar.title = (r.turn ? '第 ' + r.turn + ' 轮 · ' : '') + r.run + '：输入 ' + ftok(tin(r.tokens)) + ' · 输出 ' + ftok(r.tokens.output);
+        sp.append(bar);
+      });
+      p.append(sp);
+    }
+    p.append(h('div', 'foot', '数字来自 DSH 自己的会话记录（累计，含 live 之前的回合）。'));
+    return p;
+  }
+
+  /** 读写类工具：用来从输入预览里认出"涉及的文件"。 */
+  const READ_TOOLS = /^(read|view|cat|open|glob|grep|search|list|ls)/i;
+  const WRITE_TOOLS = /^(write|edit|create|patch|apply|replace|delete|move|rename|mkdir)/i;
+  const looksLikePath = (s) => !!s && !/\s/.test(s) && (/[\\/]/.test(s) || /\.[A-Za-z0-9]{1,8}$/.test(s));
+
+  /** 右侧检查器：这个会话的总量、工具分布、涉及文件、审批。 */
+  function inspector(c) {
+    const box = h('aside', 'inspector');
+    const tools = [];
+    const approvals = [];
+    for (const r of c.runs) for (const it of r.items) {
+      if (it.kind === 'tool') tools.push(it);
+      else if (it.kind === 'approval') approvals.push(it);
+    }
+    const failed = tools.filter((x) => x.status === 'failed').length;
+    const toolMs = tools.reduce((n, x) => n + (x.elapsed_ms || 0), 0);
+    const esc = approvals.filter((x) => x.escalation).length;
+
+    const ov = h('section', 'panel');
+    ov.append(h('h3', null, '概览'));
+    const kpis = h('div', 'kpis');
+    const kpi = (v, label, cls) => {
+      const k = h('div', 'kpi ' + (v && v !== '0' ? cls || '' : 'zero'));
+      k.append(h('b', null, String(v)), h('span', null, label));
+      kpis.append(k);
+    };
+    kpi(c.runs.length, '回合');
+    kpi(tools.length, '工具调用');
+    kpi(failed, '失败', 'bad');
+    kpi(toolMs ? dur(toolMs) : '0', '工具耗时');
+    kpi(approvals.length, '审批', 'warn');
+    kpi(esc, '提权', 'warn');
+    ov.append(kpis);
+    box.append(ov);
+    box.append(tokenPanel(c));
+
+    const byName = new Map();
+    for (const x of tools) {
+      const k = x.name || x.title || 'tool';
+      const e = byName.get(k) || { n: 0, ms: 0, fail: 0 };
+      e.n++; e.ms += x.elapsed_ms || 0; if (x.status === 'failed') e.fail++;
+      byName.set(k, e);
+    }
+    const dist = h('section', 'panel');
+    dist.append(h('h3', null, '工具分布'));
+    if (!byName.size) dist.append(h('div', 'muted', '还没有工具调用'));
+    else {
+      const rows = [...byName.entries()].sort((a, b) => b[1].n - a[1].n || b[1].ms - a[1].ms);
+      const max = rows[0][1].n;
+      const list = h('div', 'dist');
+      for (const [name, e] of rows.slice(0, 8)) {
+        const row = h('div', 'dist-row');
+        row.append(h('span', 'n', name));
+        row.append(h('span', 'v', '×' + e.n + (e.ms ? ' · ' + dur(e.ms) : '') + (e.fail ? ' · ' + e.fail + ' 失败' : '')));
+        const bar = h('span', 'bar'); const b = h('b'); b.style.width = Math.max(4, (e.n / max) * 100) + '%'; bar.append(b); row.append(bar);
+        list.append(row);
+      }
+      dist.append(list);
+    }
+    box.append(dist);
+
+    const files = new Map();
+    for (const x of tools) {
+      const name = x.name || x.title || '';
+      const p = x.input_preview && x.input_preview.split(' · ')[0];
+      if (!looksLikePath(p)) continue;
+      const op = WRITE_TOOLS.test(name) ? 'w' : READ_TOOLS.test(name) ? 'r' : null;
+      if (!op) continue;
+      const key = rel(p, c.cwd) || p;
+      const prev = files.get(key);
+      files.set(key, prev === 'w' || op === 'w' ? 'w' : 'r');
+    }
+    const fp = h('section', 'panel');
+    fp.append(h('h3', null, '涉及文件'));
+    if (!files.size) fp.append(h('div', 'muted', '还没有读写文件'));
+    else {
+      const ul = h('ul', 'files');
+      for (const [p, op] of [...files.entries()].slice(-14).reverse()) {
+        const li = h('li');
+        li.append(h('span', 'op ' + op, op === 'w' ? '写' : '读'));
+        const ps = h('span', 'p'); const bdi = document.createElement('bdi'); bdi.textContent = p; ps.append(bdi); ps.title = p;
+        li.append(ps);
+        ul.append(li);
+      }
+      fp.append(ul);
+    }
+    box.append(fp);
+
+    if (approvals.length) {
+      const ap = h('section', 'panel');
+      ap.append(h('h3', null, '审批'));
+      const list = h('div', 'aps');
+      for (const a of approvals.slice(-6).reverse()) {
+        const d = h('div', 'ap');
+        const m = h('div', 'm', (MODE[a.mode] || a.mode || '') + (a.escalation ? ' · ⚠ ' + a.escalation : ''));
+        d.append(m);
+        const cmd = rel(a.command_preview || a.title || a.tool || '', c.cwd);
+        if (cmd) { const cc = h('div', 'c', cmd); cc.title = cmd; d.append(cc); }
+        if (a.decided) d.append(h('div', 'muted', '→ ' + (a.decided.decision || a.decided.effective || '') + (a.decided.by ? '（' + a.decided.by + '）' : '')));
+        list.append(d);
+      }
+      ap.append(list);
+      box.append(ap);
+    }
+    return box;
+  }
+
+  /**
+   * 每个回合工具列表的滚动状态（按 会话/回合 记）：整块重建 DOM 后恢复位置。
+   * 停在底部的（或从没滚过的运行中回合）跟随最新工具；用户往上翻过就停在原处。
+   */
+  const scrollState = new Map();
+  let pendingScroll = [];
+  function updateEdges(spans, box) {
+    const max = spans.scrollHeight - spans.clientHeight;
+    box.classList.toggle('more-up', spans.scrollTop > 2);
+    box.classList.toggle('more-down', spans.scrollTop < max - 2);
+    const hiddenBelow = Math.max(0, Math.round((max - spans.scrollTop) / 32));
+    box.lastElementChild.textContent = hiddenBelow ? '↓ ' + hiddenBelow + ' 条' : '';
+  }
+  function restoreScroll() {
+    for (const { spans, box, key, running } of pendingScroll) {
+      const st = scrollState.get(key);
+      const max = spans.scrollHeight - spans.clientHeight;
+      if (st && !st.atBottom) spans.scrollTop = Math.min(st.top, max);
+      else if (st || running) spans.scrollTop = max;
+      updateEdges(spans, box);
+      spans.addEventListener('scroll', () => {
+        const m = spans.scrollHeight - spans.clientHeight;
+        scrollState.set(key, { top: spans.scrollTop, atBottom: spans.scrollTop >= m - 4 });
+        updateEdges(spans, box);
+      }, { passive: true });
+    }
+    pendingScroll = [];
+  }
+
   function render() {
     if (!view) return;
     const rt = $('rail').scrollTop, mt = $('main').scrollTop, wt = window.scrollY;
@@ -513,7 +823,9 @@ button { font: inherit; color: inherit; }
     }
     renderStats();
     renderRail();
+    pendingScroll = [];
     renderMain();
+    restoreScroll();
     $('rail').scrollTop = rt; $('main').scrollTop = mt; window.scrollTo(0, wt);
   }
 

package/src/live-view.mjs

@@ -76,6 +76,9 @@ function newConv(id) {
     opened_at: null,
     last_ts: null,
     closed: false,
+    /** DSH 会话累计 token（含不在 live 里的更早回合）。 */
+    session_tokens: null,
+    context: null,
     runs: [],
   };
 }
@@ -98,10 +101,43 @@ function newRun(id) {
     auto_approvals: null,
     auto_escalations: null,
     writer: null,
+    /** 本回合 token 增量 {input, output, cache_read, cache_write}（来自 usage 事件）。 */
+    tokens: null,
+    /** 上下文窗口占用 {used, window}。 */
+    context: null,
     items: [],
   };
 }
 
+const TOKEN_KEYS = ['input', 'output', 'cache_read', 'cache_write'];
+
+/** 规整一组 token 计数；不是对象时返回 null。 */
+function cleanTokens(t) {
+  if (!t || typeof t !== 'object') return null;
+  const out = {};
+  for (const k of TOKEN_KEYS) out[k] = Number.isFinite(t[k]) && t[k] > 0 ? t[k] : 0;
+  return out;
+}
+
+/** 输入总量（未命中缓存 + 缓存读 + 缓存写）。 */
+export function tokenInputTotal(t) {
+  return t ? t.input + t.cache_read + t.cache_write : 0;
+}
+
+/** 缓存命中率（缓存读 / 输入总量），没有输入时为 null。 */
+export function cacheHitRate(t) {
+  const all = tokenInputTotal(t);
+  return all > 0 ? t.cache_read / all : null;
+}
+
+/** 1234 → 1.2k，1500000 → 1.5M。 */
+export function fmtTokens(n) {
+  if (!Number.isFinite(n)) return '';
+  if (n < 1000) return String(Math.round(n));
+  if (n < 1e6) return `${(n / 1000).toFixed(n < 10_000 ? 1 : 0)}k`;
+  return `${(n / 1e6).toFixed(n < 1e7 ? 2 : 1)}M`;
+}
+
 /**
  * 事件归并器。纯内存、与文件无关，方便单测。
  * `apply(ev)` 吃一条事件；`view()` 给出可序列化的调用链快照。
@@ -238,6 +274,18 @@ export class LiveState {
         }
         break;
       }
+      case 'usage': {
+        const r = this.#run(c, ev.run);
+        if (r) {
+          const t = cleanTokens(ev.tokens);
+          if (t) r.tokens = t;
+          if (ev.context && Number.isFinite(ev.context.window)) r.context = { used: ev.context.used ?? 0, window: ev.context.window };
+        }
+        const s = cleanTokens(ev.session_tokens);
+        if (s) c.session_tokens = s;
+        if (ev.context && Number.isFinite(ev.context.window)) c.context = { used: ev.context.used ?? 0, window: ev.context.window };
+        break;
+      }
       case 'interject': {
         const r = this.#run(c, ev.run, { create: false });
         if (r) this.#push(r, { kind: 'interject', at: ev.ts, mode: ev.mode ?? null, text_preview: ev.text_preview ?? null, pending_run: ev.pending_run ?? null });
@@ -307,6 +355,9 @@ export class LiveState {
         opened_at: c.opened_at,
         last_ts: c.last_ts,
         state,
+        /** 会话累计（DSH 自己记的，含更早的回合）；没有就用 live 里各回合之和。 */
+        tokens: c.session_tokens ?? sumTokens(runs.map((r) => r.tokens)),
+        context: c.context,
         runs,
       };
     });
@@ -329,12 +380,25 @@ export class LiveState {
         queued: convs.reduce((n, c) => n + c.runs.filter((r) => r.status === 'queued').length, 0),
         pending_approvals: convs.reduce((n, c) => n + c.runs.reduce((m, r) => m + r.pending_approvals, 0), 0),
         escalations: convs.reduce((n, c) => n + c.runs.reduce((m, r) => m + r.escalations, 0), 0),
+        tokens: sumTokens(convs.map((c) => c.tokens)),
       },
       groups: [...groups.values()],
     };
   }
 }
 
+/** 把若干组 token 计数相加；全是空时返回 null。 */
+export function sumTokens(list) {
+  let any = false;
+  const out = { input: 0, output: 0, cache_read: 0, cache_write: 0 };
+  for (const t of list) {
+    if (!t) continue;
+    any = true;
+    for (const k of TOKEN_KEYS) out[k] += t[k] ?? 0;
+  }
+  return any ? out : null;
+}
+
 function rank(state) {
   return state === 'running' ? 0 : state === 'queued' ? 1 : state === 'idle' ? 2 : 3;
 }
@@ -437,7 +501,11 @@ export class LiveTail {
     return changed;
   }
 
-  /** 标题：DSH 原生标题（投影缓存）> 注册表 titleHint > conv.open 的 title_hint。 */
+  /**
+   * 标题：调用方给的 title_hint（注册表 > conv.open 事件）> DSH 原生标题（投影缓存）。
+   * DSH 原生标题只是首条 prompt 的截断前缀（"在当前目录做一个简易的、可"），
+   * 有显式 title_hint 时它更可读。
+   */
   #refreshTitles() {
     const t = Date.now();
     if (t - this.titlesAt < TITLE_TTL_MS) return false;
@@ -452,16 +520,15 @@ export class LiveTail {
       }
     }
     let changed = false;
-    for (const id of this.state.convs.keys()) {
-      let title = null;
-      if (this.readTitle) {
+    for (const [id, conv] of this.state.convs) {
+      let title = hints.get(id) ?? conv.title_hint ?? null;
+      if (!title && this.readTitle) {
         try {
           title = this.readTitle(id) ?? null;
         } catch {
           title = null;
         }
       }
-      title = title ?? hints.get(id) ?? null;
       if (title && this.titles.get(id) !== title) {
         this.titles.set(id, title);
         changed = true;
@@ -475,6 +542,105 @@ export class LiveTail {
   }
 }
 
+// ── 终端原地刷新（watch） ───────────────────────────────────────
+
+const ANSI_RE = /\x1b\[[0-9;?]*[A-Za-z]/y;
+
+/** 单个码点在终端里占几列：CJK / 全角 / emoji 记 2，其余 1（框线字符在主流终端里是 1）。 */
+export function charWidth(cp) {
+  if (cp < 0x1100) return 1;
+  if (
+    (cp >= 0x1100 && cp <= 0x115f) ||
+    (cp >= 0x2e80 && cp <= 0x303e) ||
+    (cp >= 0x3041 && cp <= 0x33ff) ||
+    (cp >= 0x3400 && cp <= 0x4dbf) ||
+    (cp >= 0x4e00 && cp <= 0x9fff) ||
+    (cp >= 0xa000 && cp <= 0xa4cf) ||
+    (cp >= 0xac00 && cp <= 0xd7a3) ||
+    (cp >= 0xf900 && cp <= 0xfaff) ||
+    (cp >= 0xfe30 && cp <= 0xfe4f) ||
+    (cp >= 0xff00 && cp <= 0xff60) ||
+    (cp >= 0xffe0 && cp <= 0xffe6) ||
+    (cp >= 0x1f300 && cp <= 0x1faff) ||
+    (cp >= 0x20000 && cp <= 0x3fffd)
+  ) {
+    return 2;
+  }
+  return 1;
+}
+
+/** 可见宽度（忽略 ANSI 颜色序列）。 */
+export function displayWidth(s) {
+  let w = 0;
+  for (let i = 0; i < s.length; ) {
+    ANSI_RE.lastIndex = i;
+    const m = ANSI_RE.exec(s);
+    if (m) {
+      i += m[0].length;
+      continue;
+    }
+    const cp = s.codePointAt(i);
+    w += charWidth(cp);
+    i += cp > 0xffff ? 2 : 1;
+  }
+  return w;
+}
+
+/**
+ * 把一行截到 `cols` 列以内（保留颜色序列，超出时末尾放 `…`）。
+ * 不截的话长行会折到下一行，原地刷新时整棵树就错位了。
+ */
+export function clipLine(s, cols) {
+  if (!(cols > 1) || displayWidth(s) <= cols) return s;
+  let w = 0;
+  let out = '';
+  for (let i = 0; i < s.length; ) {
+    ANSI_RE.lastIndex = i;
+    const m = ANSI_RE.exec(s);
+    if (m) {
+      out += m[0];
+      i += m[0].length;
+      continue;
+    }
+    const cp = s.codePointAt(i);
+    const cw = charWidth(cp);
+    if (w + cw > cols - 1) break;
+    out += String.fromCodePoint(cp);
+    w += cw;
+    i += cp > 0xffff ? 2 : 1;
+  }
+  return out + '…\x1b[0m';
+}
+
+/**
+ * 把一帧文本排成"适合这个终端"的行：截宽、截高（超出的行数在最后一行说明）。
+ * 纯函数，方便测试。
+ */
+export function layoutFrame(text, { cols = 120, rows = 40 } = {}) {
+  let lines = String(text).split('\n').map((l) => clipLine(l, cols));
+  if (rows > 2 && lines.length > rows) {
+    const hidden = lines.length - (rows - 1);
+    lines = lines.slice(0, rows - 1);
+    lines.push(clipLine(`\x1b[2m…还有 ${hidden} 行没显示（给会话 id 前缀、或用 --runs / --items 收窄）\x1b[0m`, cols));
+  }
+  return lines;
+}
+
+/**
+ * 计算从上一帧到这一帧要写的终端序列：只重写变化的行，多出来的旧行清掉。
+ * 第一帧（prev 为 null）整屏重画。返回要写出的字符串（无变化时为空串）。
+ */
+export function diffFrame(prev, next) {
+  let out = '';
+  if (!prev) out += '\x1b[H\x1b[2J';
+  for (let i = 0; i < next.length; i++) {
+    if (prev && prev[i] === next[i]) continue;
+    out += `\x1b[${i + 1};1H${next[i]}\x1b[0m\x1b[K`;
+  }
+  if (prev && prev.length > next.length) out += `\x1b[${next.length + 1};1H\x1b[J`;
+  return out;
+}
+
 // ── 终端渲染（watch） ───────────────────────────────────────────
 
 const STATUS_MARK = {
@@ -524,7 +690,8 @@ export function renderText(view, { conv = null, runs = 3, items = 12, color = fa
     `DSH live · ${t.conversations} 会话 · ${t.running} 运行中` +
       (t.queued ? ` · ${t.queued} 排队` : '') +
       (t.pending_approvals ? ` · ${warn(`${t.pending_approvals} 待审批`)}` : '') +
-      (t.escalations ? ` · ${warn(`⚠ ${t.escalations} 次提权`)}` : ''),
+      (t.escalations ? ` · ${warn(`⚠ ${t.escalations} 次提权`)}` : '') +
+      (t.tokens ? ` · token 入 ${fmtTokens(tokenInputTotal(t.tokens))} / 出 ${fmtTokens(t.tokens.output)}` : ''),
   );
   let shown = 0;
   for (const g of view.groups) {
@@ -538,7 +705,9 @@ export function renderText(view, { conv = null, runs = 3, items = 12, color = fa
       const p1 = lastConv ? '└─ ' : '├─ ';
       const p1c = lastConv ? '   ' : '│  ';
       const stateTxt = cv.state === 'running' ? good('运行中') : cv.state === 'queued' ? warn('排队') : dim(cv.state === 'closed' ? '已释放' : '空闲');
-      out.push(`${p1}${shortId(cv.id)}  ${clip(cv.title ?? '(无标题)', 40)}  ${stateTxt}  ${dim(`${cv.permission ?? ''} · ${clip(cv.cwd ?? '', 50)}`)}`);
+      const ctx = cv.context && cv.context.window ? ` · 上下文 ${Math.round((cv.context.used / cv.context.window) * 100)}%` : '';
+      const tok = cv.tokens ? ` · 累计 ${fmtTokens(tokenInputTotal(cv.tokens))}/${fmtTokens(cv.tokens.output)}` : '';
+      out.push(`${p1}${shortId(cv.id)}  ${clip(cv.title ?? '(无标题)', 40)}  ${stateTxt}${dim(tok + ctx)}  ${dim(`${cv.permission ?? ''} · ${clip(cv.cwd ?? '', 50)}`)}`);
       const rs = cv.runs.slice(-runs);
       rs.forEach((r, ri) => {
         const lastRun = ri === rs.length - 1;
@@ -551,6 +720,7 @@ export function renderText(view, { conv = null, runs = 3, items = 12, color = fa
           r.status,
           r.duration_ms != null ? fmtMs(r.duration_ms) : null,
           r.tool_count != null ? `${r.tool_count} 工具` : null,
+          r.tokens ? `${fmtTokens(tokenInputTotal(r.tokens))}↑ ${fmtTokens(r.tokens.output)}↓ tok` : null,
           r.escalations ? warn(`⚠${r.escalations} 提权`) : null,
           r.pending_approvals ? warn(`${r.pending_approvals} 待审批`) : null,
         ].filter(Boolean);