dsh-any-agent 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.1] — 2026-11-08
+
+### Added
+
+- **Live call-chain view of dispatched work.** The server now appends each
+  conversation's activity — run start/end (with how it was dispatched: send,
+  queue or interject, and which MCP client sent it), tool calls on status change,
+  approvals and their decisions — to `<state dir>/live/<conversation_id>/events.jsonl`.
+  Two new read-only subcommands show it without going through the calling agent:
+  `dsh-any-agent watch` (terminal tree) and `dsh-any-agent dashboard` (local page on
+  `127.0.0.1` with a one-time token and Host check, no controls). Both run as
+  separate processes, never touch the write lock, and merge conversations from
+  every client. `DSH_MCP_LIVE=detail|meta|off` (default `detail`: redacted
+  previews, the same exposure as sentinels) and `DSH_MCP_LIVE_DIR`. Reasoning is
+  never written; write failures never affect a run; files follow the sentinel
+  TTL and are deleted on `forget`. Design: `docs/zh/live-view-design.md`.
+
 ## [0.6.0] — 2026-11-07
 
 ### Added

package/bin/dsh-any-agent.mjs

@@ -39,6 +39,8 @@ if (argv.includes('--help') || argv.includes('-h')) {
     '  dsh-any-agent                 run the MCP server on stdio\n' +
     '  dsh-any-agent team on|off     enable/disable Agent Teams (writes settings.json)\n' +
     '  dsh-any-agent team status     show the effective team mode\n' +
+    '  dsh-any-agent watch [conv]    live call chain of dispatched runs in this terminal\n' +
+    '  dsh-any-agent dashboard       same, as a read-only local web page (127.0.0.1 + token)\n' +
     '  dsh-any-agent --version       print the version and exit\n' +
     '  dsh-any-agent --help          this text\n\n' +
     'Register it with your client:\n' +
@@ -52,12 +54,23 @@ if (argv.includes('--help') || argv.includes('-h')) {
     '  DSH_MCP_PERMISSION       danger-full-access | workspace-write | read-only\n' +
     '  DSH_MCP_APPROVAL         auto-allow | auto-deny | ask\n' +
     '  DSH_MCP_REVIEW           advisory (default) | off — caller review ticket on results\n' +
-    '  DSH_MCP_LOG              silent (default) | info | debug\n\n' +
+    '  DSH_MCP_LOG              silent (default) | info | debug\n' +
+    '  DSH_MCP_LIVE             detail (default) | meta | off — live event stream for watch/dashboard\n\n' +
     'Docs: https://github.com/xmtlzzz/dsh-any-agent\n',
   );
   process.exit(0);
 }
 
+/**
+ * `dsh-any-agent watch` / `dsh-any-agent dashboard`：只读查看 live 事件流（调用链）。
+ * 独立进程，不启动 Hub、不碰写锁、不连 DSH —— 必须在启动 Hub 之前分派。
+ */
+if (argv[0] === 'watch' || argv[0] === 'dashboard') {
+  const cli = await import('../src/live-cli.mjs');
+  const code = argv[0] === 'watch' ? await cli.runWatch(argv.slice(1)) : await cli.runDashboard(argv.slice(1));
+  process.exit(code);
+}
+
 /**
  * `dsh-any-agent team on|off|status`
  *
@@ -128,6 +141,15 @@ await hub.load();
 hub.startReaper();
 // 启动时清一次过期哨兵（哨兵内含正文，长期不清理会无声堆积）
 const prunedSentinels = hub.pruneSentinels();
+// live 事件流与哨兵同一 TTL（单独调用，不改 pruneSentinels 的返回形状）
+try {
+  const { pruneLive } = await import('../src/live.mjs');
+  const { SENTINEL_TTL_MS } = await import('../src/config.mjs');
+  const prunedLive = pruneLive(SENTINEL_TTL_MS);
+  if (prunedLive.pruned) log.info(`[dsh-any-agent] 启动清理：删除 ${prunedLive.pruned} 个过期 live 事件文件`);
+} catch {
+  /* 清理失败不影响启动 */
+}
 if (prunedSentinels.pruned || prunedSentinels.reviews_pruned) {
   log.info(
     `[dsh-any-agent] 启动清理：删除 ${prunedSentinels.pruned} 个过期哨兵、` +

package/docs/en/reference.md

@@ -30,6 +30,8 @@
 | `DSH_MCP_SENTINEL_INCLUDE_REASONING` | unset | `1` writes `result.thinking` into the sentinel (**breaks the never-on-disk guarantee**); answer/error/title/tool inputs are still credential-redacted |
 | `DSH_MCP_REVIEW` | `advisory` | Caller-review policy. `advisory` (default) attaches a review ticket (checklist + evidence + `dsh_review` entry) to every result and sentinel **without blocking later sends**; `off` disables automatic tickets. Per-conversation/per-send overrides use the `review` argument |
 | `DSH_MCP_REVIEWS_DIR` | `<state file dir>/reviews` | Where review verdicts are written (`<this>/<conversation_id>/<run_id>.review.json`). Must be writable, or startup fails loudly |
+| `DSH_MCP_LIVE` | `detail` | Live event stream level (the data behind `watch` / `dashboard`). `detail` adds redacted prompt / command / path previews; `meta` keeps tool names, status, timing and approval kinds only; `off` writes nothing. Reasoning is never written at any level |
+| `DSH_MCP_LIVE_DIR` | `<state file dir>/live` | Live event stream directory (`<this>/<conversation_id>/events.jsonl`, rolled to `.1` at 5 MB). Write failures are skipped silently and never affect a run; pruned by `DSH_MCP_SENTINEL_TTL_MS` |
 | `DSH_MCP_PERMISSION` | `workspace-write` | Default tier for `dsh_start`. `danger-full-access` additionally requires `DSH_MCP_ALLOW_FULL_ACCESS=1` |
 | `DSH_MCP_ALLOW_FULL_ACCESS` | `0` | Whether `permission=danger-full-access` is allowed. Denied by default: it hands the caller whole-machine write access |
 | `DSH_MCP_REASONING_EFFORT` | `max` | Default reasoning effort |

package/docs/en/security.md

@@ -64,5 +64,6 @@ Silent by default — **not one byte is written**.
 - **The async completion sentinel persists the answer, usage and tool inputs** (it must, so a caller can collect offline) but **strips `result.thinking`** and always reports `thinking_omitted` (true when reasoning was removed, false when there was none). Tool inputs are passed through the same credential redaction as approvals, but the sentinel still contains commands and file contents — treat it as sensitive. A test asserts that even when `reasoning=full` is requested, no reasoning text appears in the sentinel — while `dsh_get(run_id)` still returns it from memory. Set `DSH_MCP_SENTINEL_INCLUDE_REASONING=1` to break this on purpose.
 - **Review records are the second intentional on-disk artifact.** `<state dir>/reviews/<conversation_id>/<run_id>.review.json` holds the verdict, the reviewer's `notes`/`findings`, the checklist and an evidence summary. `notes`/`findings`, the task preview, the evidence **and each checklist item** pass through the same credential redaction (the checklist can interpolate `result.error`); reasoning is never included. Treat review records as sensitive too (they can quote code or paths).
 - Sentinels **and review records** are pruned after 7 days by default (`DSH_MCP_SENTINEL_TTL_MS`; `0` keeps them forever).
+- The live event stream (`<state dir>/live/`, read by `watch` / `dashboard`) carries **redacted** command, path and prompt previews by default — no more than the sentinels already hold — never reasoning, and is pruned on the same 7-day TTL. Set `DSH_MCP_LIVE=meta` to drop the previews or `off` to write nothing. `dashboard` binds `127.0.0.1` only, requires a one-time token, checks the Host header, and is read-only.
 
 > ⚠️ **DSH writes its own session log under `~/.dsh/sessions` and that log contains the full reasoning text** (even with `reasoning=hide`). It is what makes resume possible and is outside this server's control. The absolute "reasoning never reaches disk" claim applies to *this server's* artifacts only.

package/docs/en/tests.md

@@ -46,6 +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) |
 | `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) |
@@ -79,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 1417 checks in 31 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 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.
 
 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 (1417), the CI offline job (nominal 1349 on Linux/macOS, 1355 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 (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.
 <!-- counts:end -->
 
 ### 🔢 After changing tests: counts are computed

package/docs/en/usage.md

@@ -76,6 +76,28 @@ Design notes (especially under **concurrent multi-session** use):
 4. dsh_read(id,  cursor=<prev>) # switch back; entries that grew since <prev> reappear (match by seq)
 ```
 
+## 👀 Side view: what the dispatched work is doing
+
+The calling agent can `dsh_read`, but you, sitting in front of the client, usually only see one `dsh_send`. The server writes each conversation's activity to a live event stream (`<state dir>/live/<conversation_id>/events.jsonl`), so you can watch the call chain **without going through the agent**:
+
+```text
+client (who dispatched) → conversation → run (send / queue / interject) → tool calls · approvals
+```
+
+```bash
+dsh-any-agent watch
+```
+
+```bash
+dsh-any-agent dashboard
+```
+
+- `watch [conversation id prefix]`: live call chain in the terminal (`--once` prints once and exits, `--runs N` shows the last N runs per conversation).
+- `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.
+- 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
 
 DSH separates reasoning from answer text at the model layer, and ACP exposes them as **two independent streams**. This server hides reasoning by default and returns only **statistics** (characters, duration, chunk count) — so the caller knows thinking happened without paying for it in context.

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

@@ -0,0 +1,192 @@
+> 返回 [README](../../README.zh.md)
+
+# 设计稿：让用户看见 DSH 在做什么（live 事件流 + 查看器）
+
+> 状态：**P1 + P2 已实现**，随 0.6.1 发布（见 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`。
+>
+> 范围：定位为**轻量功能**，只做 §12 的 P1（事件流 + `watch`）和 P2（只读 `dashboard` 页面）。状态栏、宿主内嵌、控制面都不在本次范围内。
+
+## 1. 问题
+
+本服务把 DSH 当成外包工程师来派活。对**调用方 agent** 来说，过程是透明的：它可以 `dsh_read` 增量拉取、等哨兵、`dsh_get` 取结果。对**坐在 Claude Code / Codex / Cursor 前面的用户**来说，过程基本是黑盒：
+
+- 屏幕上只有一次 `dsh_send` 调用和一张收据（run_id、哨兵路径），然后就是等待。
+- DSH 在这期间读了哪些文件、跑了哪些命令、是否借审批把沙箱提升到了 `danger-full-access`，用户看不到——除非 agent 主动去 `dsh_read` 并转述，而这既花 token，也取决于 agent 愿不愿意做。
+- 撞到问题（卡在某个工具上、反复失败、一直在等审批）时，用户无从判断是该等还是该打断。
+
+目标是给用户一个**不经过 agent 的旁路视图**。
+
+## 2. 目标与非目标
+
+**目标**
+
+1. 用户能实时看到每个会话：是否在跑、当前在哪个工具上、本轮已调用了哪些工具及其状态。
+2. 审批（尤其自动放行和沙箱提权）在视图里显眼。
+3. 同时看到所有客户端、所有服务实例派出去的会话。
+4. 不破坏现有隐私红线：**思考内容绝不落到这条通路上**。
+5. 写入失败绝不影响派活主流程。
+
+**非目标**
+
+- 不做控制面：查看器里不能批准、插话、中断（理由见 §9 第 4 条）。
+- 不做状态栏一行输出，也不做宿主内嵌视图（Claude Code 侧边面板、MCP Apps）。将来真要做，也只是读同一份事件流，不需要改服务端。
+- 不替代 `dsh_read`、哨兵、审计日志，它们的语义一律不变。
+- 不读取 DSH 自己的 `~/.dsh/sessions`。
+
+## 3. 现状：数据在哪
+
+DSH 的工具活动经 ACP 的 `session/update`（`tool_call` / `tool_call_update`）到达本服务，此后的去向：
+
+| 位置 | 内容 | 实时 | 谁能看 |
+|---|---|---|---|
+| `Conversation.out` 环形缓冲（`src/conversation.mjs` 的 `onSessionUpdate` → `pushOut`） | 工具名 + 状态快照、正文、轮次起止 | 是 | 仅 `dsh_read`，即只有 agent |
+| 回合收集器 `collector.tools` / `autoApprovals` | 工具输入、自动放行摘要 | 是 | 回合结束后进哨兵 / `dsh_get` |
+| 哨兵 `<RUNS_DIR>/<conv>/<run>.json` | 正文、工具输入（已脱敏） | 否，回合结束才写 | 文件，7 天 TTL |
+| 审计 `DSH_MCP_AUDIT_FILE` | 谁对哪个会话做了什么（不含工具） | 是 | 默认关闭 |
+| DSH 的 `~/.dsh/sessions` | 全量，含思考内容 | DSH 自己写 | 内部格式 |
+
+结论：实时的数据只存在于服务进程的内存里，唯一的出口是 agent 调用的 MCP 工具。
+
+## 4. 约束
+
+1. **服务是 stdio 子进程。** 每个 MCP 客户端各起一个 `dsh-any-agent`，没有端口，HTML 页面无处可连。
+2. **多实例。** Claude Code、Codex、Cursor 同时在用时就有多个服务进程，各自的内存缓冲互不相通。视图必须跨实例聚合。
+3. **共享 ACP 进程。** 同一 `(cwd, permission)` 的会话共用一个 DSH 进程（`src/host.mjs`），但事件是按 `sessionId` 分发到各 `Conversation` 的，按会话组织数据不受影响。
+4. **写锁。** 同一会话同一时刻只有一个写者（见 [写锁](locking.md)），这让"按会话一个文件、单写者追加"天然成立。takeover 的交接窗口需要单独考虑（§6.5）。
+5. **不发 MCP 通知。** 现有设计不依赖客户端处理推送，新方案也不应依赖。
+6. **隐私红线。** 日志、哨兵、注册表不写思考正文；新增的任何落盘都要守同一条线，并沿用 `src/redact.mjs` 的脱敏。
+7. **测试隔离。** `test/cleanup.mjs` 会清理全部测试会话，真实运行与测试运行不能写同一目录。
+
+## 5. 方案对比
+
+| 方案 | 做法 | 优点 | 主要问题 | 结论 |
+|---|---|---|---|---|
+| A. 服务进程内嵌 HTTP/SSE | `pushOut` 时推给本进程开的本地端口 | 实时、改动小 | 多实例抢端口要做发现；生命周期绑客户端；本地端口有 CSRF / DNS rebinding 面，要 token；Windows 防火墙弹窗 | 否 |
+| B. 查看器直接读 `~/.dsh/sessions` | 服务端零改动 | 改动最小 | 耦合 DSH 内部格式（仍在 rc）；含思考内容，越过隐私红线 | 否 |
+| C. 服务端写事件流文件，查看器只读 | 服务端追加 JSONL，任意查看器 tail | 跨实例、跨重启；与哨兵"文件即 IPC"一致；视图可独立迭代 | 要定一份稳定 schema；需处理轮转与清理 | **采用** |
+| D. MCP progress 通知 / MCP Apps | 走宿主原生 UI | 体验好 | `dsh_send` 默认立即返回，没有长期挂着的调用承载进度；宿主支持参差 | 不做（超出轻量定位） |
+
+## 6. 数据契约：live 事件流
+
+### 6.1 位置与开关
+
+- 目录：`DSH_MCP_LIVE_DIR`，默认 `<dirname(STATE_FILE)>/live/`，与 `runs/`、`reviews/` 并列。
+- 文件：`<live>/<conversation_id>/events.jsonl`，一行一个事件，UTF-8，`\n` 结尾。
+  - 实现：按会话分**子目录**而不是扁平文件，因为现有的 `pruneDirTree` 只清理会话子目录；滚动出的 `events.jsonl.1` 也放在同一目录。
+- 级别：`DSH_MCP_LIVE=off | meta | detail`。
+  - `meta`（建议默认）：工具名、kind、状态、时间、计数、审批类型与是否提权。**不含**任何工具输入、命令、路径、正文。
+  - `detail`：在 `meta` 之上加脱敏后的输入预览（命令、路径）、prompt 预览、正文增量摘要。与哨兵已有的暴露面同级。
+  - `off`：不写。
+
+> 实现：**默认改为 `detail`**。用途是看调用链，只有工具名看不出"读了哪个文件、跑了什么命令"；而哨兵默认已经落了完整正文和未截断的工具输入，`detail` 的脱敏短预览暴露面不超过它。`meta` 只写 `name` / `kind`，`title` 归 `detail`（§11 第 2 条已按此定）。
+
+### 6.2 公共字段
+
+```json
+{"v":1,"ts":"2026-11-08T09:12:03.120Z","conv":"conv-…","run":"run-…","turn":3,"w":"<pid>:<hub-instance>","n":42,"type":"tool"}
+```
+
+- `v`：schema 版本，查看器遇到未知版本只展示公共字段。
+- `w`：写者标识（服务进程 pid + 本次启动的随机实例 id），用于 takeover 交接与"写者是否还活着"的判定。
+- `n`：写者内单调递增序号；跨写者排序以 `ts` 为准、`n` 只用于同写者去重。
+
+### 6.3 事件类型
+
+| type | 何时写 | `meta` 字段 | `detail` 追加 |
+|---|---|---|---|
+| `run.start` | 派活开始（`第 N 轮开始` 处） | `prompt_chars`、`permission`、`on_approval` | `prompt_preview`（≤200 字，脱敏） |
+| `tool` | `tool_call` / `tool_call_update` 且**状态变化**时 | `tool_call_id`、`name`、`kind`、`status`、`elapsed_ms` | `title`、`input_preview`（≤300 字，脱敏） |
+| `text` | 正文增量，节流（如每 2 秒或每 2KB 一条） | `chars_total` | `tail_preview`（最后 ≤200 字） |
+| `approval` | 收到 `request_permission` | `mode`（auto-allow / auto-deny / ask / read-only-deny）、`escalation`（如 `danger-full-access`）、`approval_id`（ask 时） | `command_preview`、`reason` |
+| `approval.decided` | `dsh_approval_decide` 或超时 | `approval_id`、`decision`、`by`（caller / timeout） | — |
+| `interject` / `interrupt` | 插话、排队、中断 | `mode` | `text_preview` |
+| `run.end` | 回合终止（成功 / 失败 / 取消） | `status`、`stop_reason`、`duration_ms`、`tool_count`、`auto_approvals`、`auto_escalations`、`usage` | — |
+| `writer.hello` / `writer.bye` | 写者首次写某会话 / 释放或 takeover 交出 | `reason` | — |
+
+实现与上表的差异（轻量化）：
+
+- 新增 `conv.open`（`dsh_start` 建会话，带 cwd / 权限 / 模型）、`conv.close`（非 forget 的释放）、`run.queued`（`dsh_send(queue=true)` 入队，带位置）。`run.start` 带 `via`（send / queue / interject）与 `cwd`；`conv.open` / `run.queued` / `run.start` 带 `client`（MCP `initialize` 的 `clientInfo.name`），查看端据此把会话挂到"谁派的"下面。
+- **不写** `text` 事件：正文只在哨兵里。
+- **不写** `writer.hello` / `writer.bye`：每条事件已带 `w`，查看端看最后一个写者的 pid 是否存活即可判断"中断"（§6.5）。
+- 排队被取消、插话等待超时、起不来的回合都补一条 `run.end`，查看端不会留下永远"排队 / 运行中"的回合。
+- 真机验证（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 替换"一致。
+
+### 6.4 写入方式
+
+- 与 `src/audit.mjs` 同一纪律：同步追加一行、所有异常吞掉、绝不抛到主流程。
+- 单行上限（如 4KB），超出截断并标 `truncated: true`。
+- 写入点集中到一个 `live.emit(conv, type, fields)`，由 `Conversation` 在现有钩子处调用：`onSessionUpdate`（工具、正文）、`onPermissionRequest` / `#recordAutoApproval` / `decideApproval`（审批）、回合起止、插话与中断。不在 `pushOut` 里泛化地写，以免把内部条目格式变成对外契约。
+- 思考内容（`agent_thought_chunk`）**没有对应事件类型**，从结构上杜绝落盘；`DSH_MCP_SENTINEL_INCLUDE_REASONING` 不影响这里。
+
+### 6.5 一致性与边界情况
+
+- **takeover**：（实现）不写交接事件；查看器以每个回合 / 会话最后一条事件的 `w` 为准。旧写者被抢占后不会再有事件，迟到事件的窗口可以忽略。
+- **崩溃**：没有 `run.end` 的 run 视为"可能仍在跑"。查看器用 `w` 里的 pid 判断写者是否存活，已死则显示为"中断（写者已退出）"，不靠心跳。
+- **半行**：查看器必须容忍文件末尾的不完整行（写到一半被读）。
+- **轮转**：单文件超过上限（如 5MB）滚动成 `.1`，只留一份。
+- **清理**：启动时按 `SENTINEL_TTL_MS` 清理 `live/`（实现：在 `bin/` 里单独调用 `pruneLive`，不改 `Hub.pruneSentinels` 的返回形状）；会话被 forget（tombstone）时同步删除其 live 目录；测试残留清理（`src/residue.mjs`）也一并清 `live/<id>/`。
+
+## 7. 查看端
+
+两个查看端都只读 `live/` 与 `conversations.json`（取标题、cwd），彼此独立。CLI 沿用 `bin/dsh-any-agent.mjs` 已有的子命令分派（同 `team`），不新增依赖。
+
+### 7.1 终端：`dsh-any-agent watch [conversation_id]`
+
+tail 一个或全部会话，按会话分组、工具行原地刷新、审批高亮。适合在宿主旁开一个终端标签。
+
+### 7.2 页面：`dsh-any-agent dashboard`
+
+- **独立进程**，与 MCP 服务进程无关，所以 §5 方案 A 的端口、生命周期问题都不存在。
+- 只绑定 `127.0.0.1`、随机端口；启动时生成一次性 token，放在打印出来的 URL 里；校验 `Host` 头防 DNS rebinding；只提供 GET。
+- 单个内联静态 HTML，不依赖 CDN；数据走 SSE。
+- 文件变更检测用 `fs.watch` + 定时轮询兜底（Windows 上 `fs.watch` 不可靠）。
+- 视图：左侧会话列表（状态、cwd、标题、最近活动），右侧当前会话的时间线（轮次 → 工具 → 审批 → 结束摘要）。
+
+## 8. 与现有机制的关系
+
+| 机制 | 关系 |
+|---|---|
+| `dsh_read` | 不变。它服务 agent，live 服务用户；两者数据来源相同、出口不同。 |
+| 哨兵 | 不变。哨兵是"回合完成"的闩锁和结果载体，live 是过程流；`run.end` 不替代哨兵。 |
+| 审计日志 | 不变。审计回答"谁对会话做了什么"，live 回答"会话自己在做什么"。 |
+| 写锁 | live 不持锁；查看器永远不触碰锁，也不会因为"在看"而影响 GUI 或 takeover。 |
+
+## 9. 隐私与安全
+
+1. 思考内容在 schema 里没有位置（§6.4）。
+2. 所有字符串字段过 `sanitizeApprovalContext`，再按字段截断。
+3. 默认 `meta` 级别不含工具输入；`detail` 需显式开启，文档里说明其暴露面与哨兵同级。
+4. **为什么不做控制面**：待决审批、插话、中断的状态都在某个服务进程的内存里（`pendingApprovals` 等）。独立的 dashboard 进程要操作它们，只能再开一条反向通道（例如服务进程监视一个命令目录），这等于给"能写本地文件的任何东西"开了一个批准提权的口子，需要单独的鉴权设计，和"轻量"的定位不符。
+5. dashboard 只监听回环地址，token 只在启动时打印，不落盘。
+
+## 10. 测试
+
+- 离线（`test/fake-acp.mjs` 驱动）：发 `tool_call` / `tool_call_update` / `request_permission`，断言 live 文件的行、级别过滤、脱敏、状态去重、单行截断。
+- 思考内容回归：fake ACP 发 `agent_thought_chunk`，断言 live 文件里不出现其文本（任何级别）。
+- 写入失败：live 目录不可写时派活仍成功。
+- takeover / 崩溃：`writer.hello` / `writer.bye` 顺序；无 `run.end` 时查看器的判定。
+- 轮转与 TTL 清理、forget 时删除。
+- 查看器解析：半行、未知 `v`、未知 `type`。
+- 所有测试设置 `DSH_MCP_LIVE_DIR` 到各自临时目录；live 用例不并发跑真实 DSH（与现有 live 测试同一规则）。
+
+## 11. 开放问题
+
+1. **DSH 子代理的工具调用会不会经 ACP 上报？** 未验证。若不上报，用户只能看到子代理这一层的"一个工具"，需要先拿真实会话测，再决定是否在视图里标注"子代理内部不可见"。
+2. ~~`meta` 级别要不要写 `title`？~~ 已定：`meta` 只写 `name` / `kind`，`title` 归 `detail`。
+3. ~~默认级别~~ 已定：默认 `detail`（理由见 §6.1）。
+4. ~~正文要不要进 live~~ 已定：不进，正文只在哨兵里。
+5. **多机 / 远程**：live 目录在本机；远程或云端会话的可见性不在本文范围。
+6. 英文版文档待方案定稿后补。
+
+## 12. 分期
+
+| 阶段 | 内容 | 交付判定 |
+|---|---|---|
+| P1 | `live.emit` + 事件 schema v1 + 清理 + 测试；`dsh-any-agent watch` | 真实派活时另开终端能实时看到工具与审批 |
+| P2 | `dsh-any-agent dashboard`（只读页面） | 浏览器里能同时看到两个客户端派出的会话 |
+
+到 P2 为止。状态栏、宿主内嵌、控制面不排期（见 §2 非目标）。

package/docs/zh/reference.md

@@ -30,6 +30,8 @@
 | `DSH_MCP_SENTINEL_INCLUDE_REASONING` | 未设置 | `1` 会把 `result.thinking` 一并写进哨兵（**打破"思考不落盘"的保证**）；answer/error/title/工具输入仍会脱敏 |
 | `DSH_MCP_REVIEW` | `advisory` | 调用方审核策略。`advisory`（默认）给每个结果/哨兵附审核单（清单 + 证据 + `dsh_review` 入口），**但不阻塞**后续派活；`off` 关闭自动审核单。单会话/单次派活可用 `review` 参数覆盖 |
 | `DSH_MCP_REVIEWS_DIR` | `<状态文件同目录>/reviews` | 审核裁决的落盘目录（`<此目录>/<会话id>/<run_id>.review.json`）。不可写会让服务启动时明确失败 |
+| `DSH_MCP_LIVE` | `detail` | live 事件流级别（`watch` / `dashboard` 的数据源）。`detail` 带脱敏后的 prompt / 命令 / 路径预览；`meta` 只有工具名、状态、计时、审批类型；`off` 不写。思考内容任何级别都不写 |
+| `DSH_MCP_LIVE_DIR` | `<状态文件同目录>/live` | live 事件流目录（`<此目录>/<会话id>/events.jsonl`，5MB 滚动到 `.1`）。写不进去只会静默跳过，不影响派活；按 `DSH_MCP_SENTINEL_TTL_MS` 清理 |
 | `DSH_MCP_PERMISSION` | `workspace-write` | `dsh_start` 未指定时的权限档。设为 `danger-full-access` 还需要 `DSH_MCP_ALLOW_FULL_ACCESS=1` |
 | `DSH_MCP_ALLOW_FULL_ACCESS` | `0` | 是否允许 `permission=danger-full-access`。默认拒绝：该档把整机写权限交给调用方 |
 | `DSH_MCP_REASONING_EFFORT` | `max` | 默认思考深度 |

package/docs/zh/security.md

@@ -64,5 +64,6 @@ node bin/dsh-any-agent-workspaces.mjs --purge-test-sessions   # 删测试会话
 - **异步完成哨兵需要把正文写进文件**（否则调用方无法离线收活），载荷还包含用量与（已按审批规则脱敏的）工具输入，但 `result.thinking` 会被**剥掉**，并始终给出布尔 `thinking_omitted`。测试里专门验证了：即使请求 `reasoning=full`，哨兵里也不出现任何思考文本——而同一 run 在内存（`dsh_get`）里仍能看到。设 `DSH_MCP_SENTINEL_INCLUDE_REASONING=1` 可刻意打破这条。
 - **审核记录是第二个刻意落盘的产物**：`<状态目录>/reviews/<会话id>/<run_id>.review.json` 保存裁决、理由/findings、清单与证据摘要。理由、findings、任务预览、证据**以及每个清单项**都走同一套凭证脱敏（清单会拼接 `result.error`），且**不含思考正文**；但它可能引用代码或路径，同样按敏感数据对待。
 - 哨兵**与审核记录**默认 7 天后由启动清理删除（`DSH_MCP_SENTINEL_TTL_MS`，`0` 表示永久保留）。
+- live 事件流（`<状态目录>/live/`，供 `watch` / `dashboard` 查看）默认带**脱敏后的**命令、路径与 prompt 预览，暴露面不超过哨兵；不含思考内容，同样按 7 天清理。不想落这些预览就设 `DSH_MCP_LIVE=meta`，完全不要就设 `off`。`dashboard` 只监听 `127.0.0.1`，要求一次性 token 并校验 Host 头，且是只读的。
 
 > ⚠️ **DSH 自己会在 `~/.dsh/sessions` 写会话日志，而且其中包含完整 reasoning 文本**（即使 `reasoning=hide` 也照存）。那是 resume 的依据，不在本服务控制范围内；“思考不落盘”的绝对表述只适用于**本服务自己的**日志/哨兵/注册表。

package/docs/zh/tests.md

@@ -45,6 +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） |
 | `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） |
@@ -78,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）跑了 31 个离线套件、1417 项检查，全部通过。**表中带括号的数字随环境变化（有没有 DSH、哪个平台、文件系统是否区分大小写、本机装了几个客户端配置），套件总数也随之变化；这一行记录的是上次同步所用报告的环境。
+**`node test/run.mjs` 在本机（Windows，装了 DSH，5/9 个客户端配置 fixture）跑了 33 个离线套件、1489 项检查，全部通过。**表中带括号的数字随环境变化（有没有 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`（1417）、CI 离线 job（名义 Linux/macOS 1349，Windows 1355；hosted runner 没有 DSH 也没有客户端 fixture，`smoke` 跳过会话段、`real-configs` 整体跳过）、需要模型的集合（名义 464）。数字取各套件自己打印的汇总，由 `npm run docs:counts` 从报告写回，不在这里手抄；不要把一个数字套到另一个 runner 上。
+> 三个总数是刻意分开的：本机 `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 上。
 <!-- counts:end -->
 
 ### 🔢 改了测试之后：检查数是算出来的

package/docs/zh/usage.md

@@ -76,6 +76,28 @@ while(-not (Test-Path -LiteralPath $f)){ if((Get-Date) -gt $dl){ 'TIMEOUT'; exit
 4. dsh_read(id,  cursor=<上次>) # 切回来；上次之后被追加过的条目会再次出现（按 seq 替换全文）
 ```
 
+## 👀 旁路查看：派出去的活在干什么
+
+调用方 agent 能 `dsh_read`，但坐在客户端前的你通常只看到一次 `dsh_send`。服务会把每个会话的活动写成 live 事件流（`<状态目录>/live/<会话id>/events.jsonl`），你可以**不经过 agent**直接看调用链：
+
+```text
+客户端（谁派的） → 会话 → 回合（派活 / 排队 / 插话） → 工具调用 · 审批
+```
+
+```bash
+dsh-any-agent watch
+```
+
+```bash
+dsh-any-agent dashboard
+```
+
+- `watch [会话id前缀]`：在终端里实时显示调用链（`--once` 打印一次就退出，`--runs N` 每个会话显示最近几轮）。
+- `dashboard`：起一个**只读**本地页面，打印出带一次性 token 的地址（只监听 `127.0.0.1`，校验 Host 头，没有任何能改变状态的按钮）。
+- 两者都是独立进程：不启动服务、不碰写锁、不连 DSH，所有客户端（Claude Code、Codex、Cursor…）派出去的会话都能一起看到。
+- 写者进程已退出而回合没有结束的，显示为"中断"。
+- 级别用 `DSH_MCP_LIVE` 调：`detail`（默认，带脱敏后的命令/路径/prompt 预览）、`meta`（只有工具名、状态、计时、审批类型）、`off`。**思考内容在任何级别都不写**。事件文件和哨兵同一个 7 天 TTL；`dsh_release(forget=true)` 会一并删掉。
+
 ## 🤫 思考内容：默认隐藏
 
 DSH 在模型层就把思考与正文分开，ACP 又把它们做成**两条独立流**。本服务默认隐藏思考内容，只返回**统计**（字数、耗时、段数）——调用方知道它想过，但不必为思考内容付上下文成本。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-any-agent",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "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/config.mjs

@@ -231,6 +231,31 @@ export const RUNS_DIR = process.env.DSH_MCP_RUNS_DIR ?? join(dirname(STATE_FILE)
  */
 export const REVIEWS_DIR = process.env.DSH_MCP_REVIEWS_DIR ?? join(dirname(STATE_FILE), 'reviews');
 
+/**
+ * live 事件流目录（默认与状态文件同目录下的 live/）。
+ *
+ * 每个会话一份 `<LIVE_DIR>/<conversation_id>/events.jsonl`：派活、工具调用、审批、回合结束，
+ * 给用户用 `dsh-any-agent watch` / `dashboard` 旁路查看（不经过调用方 agent）。
+ * 详见 docs/zh/live-view-design.md。**思考内容在事件格式里没有位置，任何级别都不落盘。**
+ */
+export const LIVE_DIR = process.env.DSH_MCP_LIVE_DIR ?? join(dirname(STATE_FILE), 'live');
+
+/**
+ * live 事件流级别：
+ *   detail（默认）—— 在 meta 之上带脱敏后的预览：prompt、工具 title / 输入、审批命令。
+ *                    暴露面与哨兵相同（哨兵默认就落完整正文与工具输入）。
+ *   meta         —— 只有工具名 / kind / 状态 / 计时 / 计数 / 审批类型，不含任何输入或正文。
+ *   off          —— 不写。
+ */
+export const LIVE_LEVELS = ['off', 'meta', 'detail'];
+export const LIVE_LEVEL = (() => {
+  const raw = String(process.env.DSH_MCP_LIVE ?? '').trim().toLowerCase();
+  if (raw === '') return 'detail';
+  if (raw === '0' || raw === 'false' || raw === 'no') return 'off';
+  if (raw === '1' || raw === 'true' || raw === 'on' || raw === 'yes') return 'detail';
+  return LIVE_LEVELS.includes(raw) ? raw : 'detail';
+})();
+
 /**
  * 调用方审核策略：
  *   advisory（默认）—— 每个回合结果都附审核单（清单 + dsh_review 入口 + 证据），