dsh-any-agent 0.3.6 → 0.3.8

package/CHANGELOG.md

@@ -7,7 +7,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-Post-0.3.6 hardening.
+Post-0.3.8 hardening.
+
+## [0.3.8] — 2026-11-02
+
+### Changed
+
+- `npm test` now works without a local DSH: smoke still checks handshake and
+  the tool table, then skips session-dependent sections instead of failing, so
+  all offline suites run. `npm run test:all` is the explicit full-suite entry.
+- Added the `model-suites` workflow for a self-hosted runner with DSH and
+  provider credentials; hosted runners print an explicit skip.
+- Added an English `USAGE-MIGRATION.en.md` and linked it from the English
+  README and `/en/` install section.
+
+### Testing
+
+- Removed the remaining always-true `check(..., true)` assertions; cleanup
+  checks now assert actual release/forget results or timeout state.
+- `prune` runs with an isolated `DSH_HOME` so it cannot touch real tombstones.
+- Added 8 static accessibility tests for both locales (28 website tests total
+  counting the existing site/release/demo suites).
+- `readHeaderAsync` now uses `StringDecoder` for multi-byte UTF-8 boundaries.
+
+### Website
+
+- `robots.txt` now mirrors the complete Cloudflare Managed crawler list, not
+  just the four most common bots.
+
+## [0.3.7] — 2026-11-02
+
+### Fixed
+
+- **Session-header lookup no longer blocks the event loop.** `Hub.get()`,
+  `Hub.load()` and `pruneStaleTombstones()` now use a streaming
+  `readHeaderAsync()` that stops at the first newline, with a 5 s timeout and
+  1 MiB header cap. Large session logs can no longer stall MCP requests,
+  heartbeat renewal, or approval handling while recovering an unknown
+  conversation. The synchronous reader remains only in the explicit
+  workspace CLI/test-cleanup path.
+- **Website robots policy mirrors Cloudflare Managed content.** The generated
+  `robots.txt` now states `Content-Signal: search=yes, ai-train=no` and
+  disallows GPTBot/ClaudeBot/Google-Extended/CCBot, so non-Cloudflare hosts
+  and the repository agree with the production policy.
+- Website tests now cover the English locale, robots policy, hreflang, CSP
+  hash, and bilingual pages (20 tests).
 
 ## [0.3.6] — 2026-11-02
 
@@ -652,7 +696,9 @@ First public release, published to npm as [`dsh-any-agent`](https://www.npmjs.co
   profiles, sessions and client configs. The product name changed; the on-disk
   contract did not. See the README FAQ.
 
-[Unreleased]: https://github.com/xmtlzzz/dsh-any-agent/compare/v0.3.6...HEAD
+[Unreleased]: https://github.com/xmtlzzz/dsh-any-agent/compare/v0.3.8...HEAD
+[0.3.8]: https://github.com/xmtlzzz/dsh-any-agent/compare/v0.3.7...v0.3.8
+[0.3.7]: https://github.com/xmtlzzz/dsh-any-agent/compare/v0.3.6...v0.3.7
 [0.3.6]: https://github.com/xmtlzzz/dsh-any-agent/compare/v0.3.5...v0.3.6
 [0.3.5]: https://github.com/xmtlzzz/dsh-any-agent/compare/v0.3.4...v0.3.5
 [0.3.4]: https://github.com/xmtlzzz/dsh-any-agent/compare/v0.3.3...v0.3.4

package/DESIGN.md

@@ -2,7 +2,15 @@
 
 > 目标：做一个 MCP Server，让 **Codex / Claude Code** 能调用 **DeepSeek Harness (DSH)** 当"外包工程师"——写代码、搭脚手架、跑任务，并且 DSH 自己还能挂它自己的 MCP。
 >
-> 本文只谈**功能与接口**，不写实现代码；其中 M2/M3 工具（`dsh_rename` 等）是分期计划，不是当前 0.3.6 的缺失功能。技术判断最初基于 DSH 0.1.7-rc.2，当前验证基线是 **DSH 0.2.1-rc.5**（见 §2 证据）。
+> 本文只谈**功能与接口**，不写实现代码；其中 M2/M3 工具（`dsh_rename` 等）是分期计划，不是当前 0.3.8 的缺失功能。技术判断最初基于 DSH 0.1.7-rc.2，当前验证基线是 **DSH 0.2.1-rc.5**（见 §2 证据）。
+
+## 当前实现状态（0.3.8）
+
+当前对外暴露 11 个工具，均已实现并有回归：
+
+`dsh_start`、`dsh_send`、`dsh_list`、`dsh_read`、`dsh_get`、`dsh_interject`、`dsh_interrupt`、`dsh_release`、`dsh_takeover`、`dsh_approval_decide`、`dsh_status`
+
+本文后续出现的 `dsh_resume`、`dsh_rename`、`dsh_delete`、`dsh_transcript`、`dsh_diff`、`dsh_doctor` 等属于 M2/M3 路线图，**不是当前版本的缺失**。当前版本的能力边界以 README 的 Known limitations 与 USAGE-NOTES 为准。
 
 ---
 

package/README.md

@@ -15,7 +15,7 @@
 
 </div>
 
-🧪 815 checks green on 0.3.6 on this machine (851 when all nine client fixtures exist); 519 of them are in the client-registration suites (555 with all fixtures) · 🔌 MCP over stdio · 📦 Zero dependencies · 📜 MIT
+🧪 815 checks green on 0.3.8 on this machine (851 when all nine client fixtures exist); 519 of them are in the client-registration suites (555 with all fixtures) · 🔌 MCP over stdio · 📦 Zero dependencies · 📜 MIT
 
 An MCP server that drives DeepSeek Harness as a **long-lived coding agent**. Hand it a goal, let it write code and run scripts, steer it mid-flight, and collect the result when you are ready.
 
@@ -33,7 +33,7 @@ dsh-any-agent-setup --yes
 
 The second command previews the changes; `--yes` applies them. Reconnect your client's MCP server, then ask your agent to start a DSH conversation in your project, dispatch a task, and collect the result. The [dispatch workflow](#-workflow-dispatch-then-collect-later) shows the tool sequence.
 
-> **Before your first task:** read the [Usage Notes](USAGE-NOTES.en.md), especially the model-config and external-MCP permission boundaries. External MCP tools bypass DSH's sandbox. For a fresh machine, follow the [migration guide](USAGE-MIGRATION.md).
+> **Before your first task:** read the [Usage Notes](USAGE-NOTES.en.md), especially the model-config and external-MCP permission boundaries. External MCP tools bypass DSH's sandbox. For a fresh machine, follow the [migration guide](USAGE-MIGRATION.en.md).
 
 <details>
 <summary>Full contents</summary>
@@ -550,11 +550,15 @@ Silent by default — **not one byte is written**.
 ## 🧪 Tests
 
 ```bash
-node test/run.mjs          # all offline suites (no LLM calls; needs DSH for smoke)
-node test/run.mjs --all    # offline + model-backed suites
+npm test                   # offline suites; smoke skips DSH sections if no DSH
+npm run test:all           # offline + model-backed suites (needs DSH/provider)
 node test/cleanup.mjs      # suite teardown on its own (test-created dirs only; --dry-run to preview)
 ```
 
+Model-backed suites are not part of the hosted CI matrix (they need a real DSH
+install and provider credentials). Run them locally, or dispatch the
+`model-suites` workflow with a self-hosted runner that has DSH configured.
+
 The suite **cleans up after itself**: `run.mjs` always ends with `cleanup.mjs`, which removes sessions and workspace registrations whose cwd is **a test-created directory** (`tmpdir()/dsh-any-agent-*` or `Desktop/dsh-any-agent-test-*`). Real project sessions — including projects under `%TEMP%` — and your live state directory are never touched. To remove `Desktop/dsh-any-agent-test-*` artifacts explicitly, run `node bin/dsh-any-agent-workspaces.mjs --purge-test-sessions`.
 
 | Suite | Checks | Covers |
@@ -595,11 +599,11 @@ The suite **cleans up after itself**: `run.mjs` always ends with `cleanup.mjs`,
 | `list` | 13 | **the cost of `dsh_list`** (measured): a default call with the on-disk probe takes ~1 s (it spawns a DSH process) while **repeated calls hit a cache and drop to single-digit milliseconds**; `only_running=true` and `include_closed=false` **skip the probe** with equivalent semantics (unopened on-disk sessions are simply excluded) |
 | `reasoning-check` | 8 | **reasoning visibility**: `reasoning=hide` returns no thinking body but non-zero stats; `reasoning=full` returns the text and the rendered section |
 
-**`node test/run.mjs` runs 815 checks on a machine with five client fixtures (851 with all nine)** — smoke 29 + 786 offline checks (822 with nine). Every suite exited 0 on 0.3.6; none needs a provider (smoke needs a DSH install for its session-creation section).
+**`node test/run.mjs` runs 815 checks on a machine with five client fixtures (851 with all nine)** — smoke 29 + 786 offline checks (822 with nine). Every suite exited 0 on 0.3.8; none needs a provider (smoke skips its session-creation sections when DSH is absent).
 
 That is **519 assertions in the client-registration suites alone** (`setup` 41, `removal-scope` 24, `config-safety` 406, `real-configs` 48; 555 with all nine fixtures), which is where the 0.3 work actually is.
 
-The model-backed suites (`smoke` 29, `boundary` 46, `integration` 30, `async` 16, `sentinel` 36, `timeout` 38, `lock` 79, `cycle` 36, `concurrency` 31, `capability` 22, `workspace-effect` 24, `acceptance` 36, `multi` 19, `permission` 11, `list` 13, `reasoning-check` 8) total 474 and were last measured in full on 0.3.6 — they need a working provider, so re-run them yourself before trusting a release: `node test/run.mjs --all`. `acceptance` now **skips explicitly** when the DSH profile has no IDA MCP (`mcp__ida__*`).
+The model-backed suites (`smoke` 29, `boundary` 46, `integration` 30, `async` 16, `sentinel` 36, `timeout` 38, `lock` 79, `cycle` 36, `concurrency` 31, `capability` 22, `workspace-effect` 24, `acceptance` 36, `multi` 19, `permission` 11, `list` 13, `reasoning-check` 8) total 474 and were last measured in full on 0.3.8 — they need a working provider, so re-run them yourself before trusting a release: `node test/run.mjs --all`. `acceptance` now **skips explicitly** when the DSH profile has no IDA MCP (`mcp__ida__*`).
 
 > Three different totals are intentional: `node test/run.mjs` (815/851), the CI offline job (786/822, no smoke), and the model-backed set (474 nominal). Counts are the numbers each suite prints itself; don't use one number for a different runner.
 

package/README.zh.md

@@ -15,7 +15,7 @@
 
 </div>
 
-🧪 0.3.6 本机 815 项检查全绿（九种客户端配置齐全时 851 项；其中 519 项属于客户端注册器套件，齐全时 555 项） · 🔌 MCP over stdio · 📦 零依赖 · 📜 MIT
+🧪 0.3.8 本机 815 项检查全绿（九种客户端配置齐全时 851 项；其中 519 项属于客户端注册器套件，齐全时 555 项） · 🔌 MCP over stdio · 📦 零依赖 · 📜 MIT
 
 一个 MCP 服务端，把 DeepSeek Harness 当作**长驻的编码 agent** 来驱动。开个会话、扔个目标，它自己写代码、跑脚本、派子代理；你随时能看、能插话、能回头验收。
 
@@ -565,11 +565,14 @@ node bin/dsh-any-agent-workspaces.mjs --purge-test-sessions   # 删测试会话
 ## 🧪 测试
 
 ```bash
-node test/run.mjs          # 全部离线套件（不消耗 token；smoke 段需要装 DSH）
-node test/run.mjs --all    # 离线 + 需要模型的套件
+npm test                   # 全部离线套件；没有 DSH 时 smoke 自动跳过会话段
+npm run test:all           # 离线 + 需要模型的套件（需要 DSH/provider）
 node test/cleanup.mjs      # 单独跑收尾清理（只清测试自己造的目录；--dry-run 可预演）
 ```
 
+模型套件不在 GitHub 托管 CI 里（需要真实 DSH、provider 与凭据）。在本机跑，
+或用 `model-suites` workflow 指定一台装好 DSH 的 self-hosted runner。
+
 测试套件**会自己收尾**：`run.mjs` 结束时必定执行 `cleanup.mjs`，它只清理 cwd 在**测试自己造的目录**（`tmpdir()/dsh-any-agent-*` 或桌面 `dsh-any-agent-test-*`）里的会话与工作区登记。**用户在 `%TEMP%` 里自己的真实项目、以及你的状态目录都不会被碰**。要连桌面测试目录一起清，可显式跑 `node bin/dsh-any-agent-workspaces.mjs --purge-test-sessions`。
 
 | 套件 | 检查数 | 覆盖 |
@@ -610,11 +613,11 @@ node test/cleanup.mjs      # 单独跑收尾清理（只清测试自己造的目
 | `list` | 13 | **`dsh_list` 的开销**（实测驱动）：含磁盘探测的默认调用约 1 秒（要 spawn 一个 DSH 进程），**连续调用命中缓存降到个位数毫秒**；`only_running=true` 与 `include_closed=false` **跳过探测**且语义等价（不把磁盘上的未打开会话算进来） |
 | `reasoning-check` | 8 | **思考可见性**：`reasoning=hide` 不返回思考正文但统计非零；`reasoning=full` 返回正文且渲染出思考段 |
 
-**`node test/run.mjs` 在本机 5/9 客户端配置时跑 815 项（九种齐全时 851 项）** —— smoke 29 + 离线套件 786 项（九种齐全时 822 项）。0.3.6 上全部退出码 0；都不需要 provider（smoke 的建会话段需要装 DSH）。
+**`node test/run.mjs` 在本机 5/9 客户端配置时跑 815 项（九种齐全时 851 项）** —— smoke 29 + 离线套件 786 项（九种齐全时 822 项）。0.3.8 上全部退出码 0；都不需要 provider（没有 DSH 时 smoke 自动跳过建会话段）。
 
 其中 **519 项属于客户端注册器套件**（`setup` 41、`removal-scope` 24、`config-safety` 406、`real-configs` 48；九种齐全时 555 项）—— 0.3 的活其实都在这里。
 
-需要模型的套件（`smoke` 29、`boundary` 46、`integration` 30、`async` 16、`sentinel` 36、`timeout` 38、`lock` 79、`cycle` 36、`concurrency` 31、`capability` 22、`workspace-effect` 24、`acceptance` 36、`multi` 19、`permission` 11、`list` 13、`reasoning-check` 8）合计 474 项，**最近一次完整实测在 0.3.6** —— 它们要可用 provider，发版前请自己重跑一遍：`node test/run.mjs --all`。`acceptance` 在没有 IDA MCP（`mcp__ida__*`）时会明确 **skip**。
+需要模型的套件（`smoke` 29、`boundary` 46、`integration` 30、`async` 16、`sentinel` 36、`timeout` 38、`lock` 79、`cycle` 36、`concurrency` 31、`capability` 22、`workspace-effect` 24、`acceptance` 36、`multi` 19、`permission` 11、`list` 13、`reasoning-check` 8）合计 474 项，**最近一次完整实测在 0.3.8** —— 它们要可用 provider，发版前请自己重跑一遍：`node test/run.mjs --all`。`acceptance` 在没有 IDA MCP（`mcp__ida__*`）时会明确 **skip**。
 
 > 三个总数是刻意分开的：`node test/run.mjs`（815/851）、CI 离线 job（786/822，不含 smoke）、需要模型的集合（名义 474）。数字取各套件自己打印的汇总，不在这里手抄；不要把一个数字套到另一个 runner 上。
 

package/USAGE-MIGRATION.en.md

@@ -0,0 +1,160 @@
+# Moving to a new machine / first-time setup (English)
+
+This is the short English version of `USAGE-MIGRATION.md`. It covers a fresh
+install, registering the MCP server with your client, and the checks worth
+doing before you trust it with real work.
+
+## 1. Prerequisites
+
+| Item | Requirement |
+|---|---|
+| Node.js | **≥ 22.15** (`zstdDecompressSync` is required) |
+| DSH | DeepSeek Harness installed and able to answer a normal chat turn |
+| Provider | A model route configured in DSH, with credentials available through `~/.dsh/.credentials.yaml` or environment variables |
+
+> The order matters. This server does **not** ship a provider or credentials.
+> On first start it copies the model route from an existing DSH profile. If DSH
+> itself is not configured, the first call fails with a provider error.
+
+## 2. Install and register
+
+```bash
+npm install -g dsh-any-agent
+
+# Preview only: reads configs, writes nothing
+dsh-any-agent-setup
+
+# Apply
+dsh-any-agent-setup --yes
+
+# Limit to some clients, or choose a permission tier
+dsh-any-agent-setup --yes --only cursor,zed
+dsh-any-agent-setup --yes --permission workspace-write
+
+# Remove only this server's entry
+dsh-any-agent-setup --remove --yes
+```
+
+Supported clients: **Claude Code, Claude Desktop, Codex, Cursor, Windsurf,
+Zed, Gemini CLI, opencode, VS Code**. Clients that are not installed are
+reported as skipped, not failed.
+
+The writer is deliberately conservative:
+
+- preview mode never writes and never starts a child process;
+- every changed file is backed up as `<file>.bak-dsh-<stamp>`;
+- JSON/JSONC/TOML edits are text-level and only touch the
+  `dsh-any-agent` entry (indentation, key order, CRLF, BOM and comments are
+  preserved);
+- malformed or read-only configs are refused rather than overwritten;
+- a second `--yes` is a no-op;
+- `setup` does **not** invoke client CLIs such as `claude mcp get` (that can
+  make Claude Code rewrite `~/.claude.json`).
+
+## 3. Manual configuration (optional)
+
+If your client is not covered by setup, add a stdio MCP server. For example:
+
+Codex `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.dsh-any-agent]
+command = "dsh-any-agent"
+args = []
+startup_timeout_sec = 20.0
+tool_timeout_sec = 120.0
+```
+
+Generic JSON client:
+
+```json
+{
+  "mcpServers": {
+    "dsh-any-agent": {
+      "command": "dsh-any-agent",
+      "args": []
+    }
+  }
+}
+```
+
+`setup --yes` writes the absolute node path, the entry file, and
+`DSH_MCP_PERMISSION` / `DSH_MCP_LOG`; the examples above assume
+`dsh-any-agent` is on `PATH`.
+
+## 4. First start and profile bootstrap
+
+On first start the server creates `~/.dsh/profiles/dsh-mcp/` and copies the
+model route from an existing DSH profile (`home` → `desktop` → `web` →
+`headless` → `acp`, first usable one). It uses a built-in zero-dependency YAML
+subset parser, so no extra npm package is needed.
+
+What is copied: `apiKeyEnv`, `baseURL`, `api`, `models`, reasoning metadata.
+What is stripped: literal API keys, nested `headers`, and URL userinfo. The
+generated profile includes the three permission presets but **never**
+`defaultPreset` (that would override the permission tier at session creation).
+
+Credentials remain in DSH's own credential store; this project never owns them.
+Set `DSH_MCP_BOOTSTRAP=0` to disable profile writing entirely, or
+`DSH_MCP_ROUTE_SOURCE=<profile>` / `__home__` to pin the route source.
+
+## 5. Permission tiers
+
+| Tier | Meaning |
+|---|---|
+| `read-only` | DSH's sandbox is read-only; approvals are forced to `auto-deny` |
+| `workspace-write` | Writes are limited to the workspace by DSH's sandbox |
+| `danger-full-access` | No workspace sandbox |
+
+The server's raw default is `danger-full-access` when `DSH_MCP_PERMISSION` is
+not set; `setup` writes `workspace-write` into the client config. Out-of-
+workspace approval requests default to `auto-allow`; pass `on_approval=ask`
+when creating a session if you want `dsh_approval_decide` to adjudicate them.
+
+`read-only` is a hard boundary at this layer: `read-only + auto-allow/ask` is
+rejected, and the server reads back the session's recorded permission tier
+after create/resume. External MCP tools mounted in DSH are outside DSH's
+sandbox; read `USAGE-NOTES.en.md` before using them with untrusted data.
+
+## 6. Verify
+
+```bash
+dsh-any-agent --version
+dsh-any-agent-setup --help
+dsh-any-agent-setup                 # preview should show your clients
+```
+
+In the client, ask the agent to call `dsh_start` with a small project
+directory, then `dsh_send` a short prompt and `dsh_get` the result. If the
+client cannot see the server, restart the client after setup.
+
+## 7. Common problems
+
+- **`DSH CLI entry not found`** — set `DSH_BIN` to
+  `.../node_modules/@deepseek-ai/dsh/lib/bin.js`, or install DSH in a location
+  the server can discover.
+- **`no adapter registered for provider` / no API key** — DSH itself is not
+  configured, or the profile route was not copied. Open DSH once, configure a
+  model, then restart the MCP server.
+- **`session ... is already owned by an active write handle`** — the session
+  is held by another process (often the DSH GUI). Use `dsh_status` to see
+  `lock_holder`; use `dsh_release` on the other instance or `dsh_takeover`
+  when the holder is a stale dsh-any-agent process. Never kill a GUI process.
+- **Nothing happens when waiting for completion** — use the returned
+  `sentinel_file`; a turn that is interrupted by a process exit may not land
+  one. Inspect the workspace and re-dispatch.
+- **Old state after upgrading** — the registry moved from
+  `<repo>/.state/conversations.json` to
+  `$DSH_HOME/.dsh-any-agent/conversations.json`; the first 0.3.x start
+  migrates it automatically. Use `DSH_MCP_STATE` to override.
+
+## 8. Upgrade / rollback
+
+`npm install -g dsh-any-agent@latest` upgrades the server. Client configs are
+not rewritten by an upgrade; run `dsh-any-agent-setup` again only if you want
+to refresh the entry or permission env. `dsh-any-agent-restore` can restore a
+client config from a `.bak-dsh-*` backup.
+
+For the full Chinese guide, environment-variable reference, write-lock
+measurements and website deployment notes, see `USAGE-MIGRATION.md`,
+`README.md` and `USAGE-NOTES.en.md`.

package/bin/dsh-any-agent.mjs

@@ -59,7 +59,7 @@ const { createHandlers } = await import('../src/tools.mjs');
 const log = createLogger();
 
 const hub = new Hub({ log });
-hub.load();
+await hub.load();
 hub.startReaper();
 // 启动时清一次过期哨兵（哨兵内含正文，长期不清理会无声堆积）
 const prunedSentinels = hub.pruneSentinels();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-any-agent",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "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",
@@ -36,6 +36,7 @@
     "USAGE-NOTES.en.md",
     "USAGE-NOTES.md",
     "USAGE-MIGRATION.md",
+    "USAGE-MIGRATION.en.md",
     "CHANGELOG.md",
     "LICENSE",
     "DESIGN.md",
@@ -45,6 +46,7 @@
     "start": "node ./bin/dsh-any-agent.mjs",
     "setup": "node ./bin/setup.mjs",
     "test": "node ./test/run.mjs",
+    "test:all": "node ./test/run.mjs --all",
     "test:smoke": "node ./test/smoke.mjs",
     "test:guards": "node ./test/guards.mjs",
     "test:prune": "node ./test/prune.mjs",

package/src/hub.mjs

@@ -134,14 +134,15 @@ function isForgotten(id) {
  * 留着只会让测试/临时会话在 `$DSH_HOME/.dsh-any-agent-forgotten` 里堆积。
  * 会话文件还在的墓碑必须保留 —— 那正是 forget 的效力所在。
  */
-function pruneStaleTombstones() {
+async function pruneStaleTombstones() {
   let removed = 0;
   try {
     if (!existsSync(FORGOTTEN_DIR)) return 0;
     for (const f of readdirSync(FORGOTTEN_DIR)) {
       if (!f.endsWith('.json')) continue;
       const id = f.slice(0, -5);
-      if (findSessionHeader(id)) continue;
+      // 异步读会话头：启动路径不能被大日志的同步解压卡住。
+      if (await findSessionHeader(id)) continue;
       try {
         rmSync(join(FORGOTTEN_DIR, f), { force: true });
         removed++;
@@ -1209,7 +1210,7 @@ export class Hub {
   /** `dsh_list` 磁盘探测的短缓存（探测要 spawn 一个 DSH 进程，实测约 1 秒）。 */
   #probeCache = null;
 
-  load() {
+  async load() {
     // ★ 启动即确认三个关键目录可写。以前"写失败只记 silent 日志"会让服务
     //   看起来正常，但注册表/哨兵/锁登记全部丢失，异步等待永远醒不过来。
     assertWritableDir(dirname(STATE_FILE), '状态目录');
@@ -1234,7 +1235,7 @@ export class Hub {
       }
     }
 
-    const stale = pruneStaleTombstones();
+    const stale = await pruneStaleTombstones();
     if (stale) this.log.info(`[hub] 清理 ${stale} 个失效的 forget 墓碑`);
     if (!existsSync(STATE_FILE)) return;
     try {
@@ -1373,7 +1374,7 @@ export class Hub {
     }
   }
 
-  get(id) {
+  async get(id) {
     // ★ forget 是终态：墓碑存在时，任何按 id 的查询都必须明确失败，
     //   否则 DSH 会话存储里的记录会让它悄悄复活（"forget 不持久"）。
     if (isForgotten(id)) {
@@ -1392,7 +1393,7 @@ export class Hub {
     if (!c) {
       // 最后一道：注册表里没有，但会话可能就在磁盘上 —— 别的实例建的、注册表被并发写覆盖丢的、
       // 或者根本是别的 profile / GUI 建的。**会话存储才是权威，注册表只是缓存。**
-      const header = findSessionHeader(id);
+      const header = await findSessionHeader(id);
       if (header?.cwd) {
         // ★ 权限档必须取自**会话自己的记录**，不能一律套默认值：
         //   一个当初用 read-only 建的会话，若注册表丢了、被我们以默认档接管，

package/src/tools.mjs

@@ -403,7 +403,7 @@ export function createHandlers(hub, opts = {}) {
       if (typeof args.prompt !== 'string' || args.prompt.trim() === '') {
         throw new Error('prompt 不能为空：至少包含一个非空白字符');
       }
-      const conv = hub.get(args.conversation_id);
+      const conv = await hub.get(args.conversation_id);
       const opts = { reasoning: args.reasoning ?? DEFAULT_REASONING };
       if (args.timeout_ms) opts.timeoutMs = args.timeout_ms;
 
@@ -489,7 +489,7 @@ export function createHandlers(hub, opts = {}) {
     },
 
     async dsh_read(args) {
-      const conv = hub.get(args.conversation_id);
+      const conv = await hub.get(args.conversation_id);
       const r = conv.readOut({
         cursor: args.cursor ?? 0,
         includeReasoning: args.include_reasoning === true,
@@ -515,7 +515,7 @@ export function createHandlers(hub, opts = {}) {
     },
 
     async dsh_get(args) {
-      const conv = hub.get(args.conversation_id);
+      const conv = await hub.get(args.conversation_id);
       const snap = conv.snapshot();
       let run = null;
       const meta = [];
@@ -575,7 +575,7 @@ export function createHandlers(hub, opts = {}) {
       if (typeof args.message !== 'string' || args.message.trim() === '') {
         throw new Error('message 不能为空：至少包含一个非空白字符');
       }
-      const conv = hub.get(args.conversation_id);
+      const conv = await hub.get(args.conversation_id);
       const opts = { mode: args.mode ?? 'interject', reasoning: args.reasoning ?? DEFAULT_REASONING };
       if (args.timeout_ms) opts.timeoutMs = args.timeout_ms;
       const r = await conv.interject(args.message, opts);
@@ -600,7 +600,7 @@ export function createHandlers(hub, opts = {}) {
     },
 
     async dsh_interrupt(args) {
-      const conv = hub.get(args.conversation_id);
+      const conv = await hub.get(args.conversation_id);
       const r = await conv.interrupt();
       return { structured: r, text: r.interrupted ? '已发送中断请求。' : `未中断：${r.reason}` };
     },
@@ -620,7 +620,7 @@ export function createHandlers(hub, opts = {}) {
             `\n会话日志都在磁盘上，之后派活会自动 resume；没有一个可释放时 released=0。`,
         };
       }
-      const conv = hub.get(args.conversation_id);
+      const conv = await hub.get(args.conversation_id);
       const r = await conv.close({ forget: args.forget === true });
       return {
         structured: { conversation_id: args.conversation_id, ...r },
@@ -631,19 +631,19 @@ export function createHandlers(hub, opts = {}) {
     },
 
     async dsh_takeover(args) {
-      const conv = hub.get(args.conversation_id);
+      const conv = await hub.get(args.conversation_id);
       const r = await conv.takeover({ force: args.force === true });
       return { structured: r, text: `${r.ok ? '✅' : '❌'} ${r.message}` };
     },
 
     async dsh_approval_decide(args) {
-      const conv = hub.get(args.conversation_id);
+      const conv = await hub.get(args.conversation_id);
       const r = conv.decideApproval(args.approval_id, args.decision);
       return { structured: r, text: `审批 ${r.approval_id} 已裁决为 ${r.decision}。` };
     },
 
     async dsh_status(args) {
-      const conv = hub.get(args.conversation_id);
+      const conv = await hub.get(args.conversation_id);
       const snap = conv.snapshot();
       const run = conv.getRun();
       const bits = [`状态=${snap.state}`, `轮数=${snap.turns}`];

package/src/workspace.mjs

@@ -15,11 +15,12 @@
  * 或手动执行回填时做一次读-改-写，窗口很小；但仍与 GUI 存在理论上的覆盖可能。
  */
 
-import { copyFileSync, readFileSync, writeFileSync, existsSync, mkdirSync, renameSync, readdirSync, rmSync, realpathSync } from 'node:fs';
+import { copyFileSync, createReadStream, readFileSync, writeFileSync, existsSync, mkdirSync, renameSync, readdirSync, rmSync, realpathSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path';
 import { tmpdir } from 'node:os';
-import { zstdDecompressSync } from 'node:zlib';
+import { StringDecoder } from 'node:string_decoder';
+import { createZstdDecompress, zstdDecompressSync } from 'node:zlib';
 import { DSH_HOME, REGISTER_WORKSPACE } from './config.mjs';
 
 const WORKSPACE_FILE = join(DSH_HOME, 'storages', 'workspace.json');
@@ -220,7 +221,7 @@ export function registerWorkspace(cwd, sessionId) {
   }
 }
 
-/** 读取一个会话头的第一个 zstd 帧（就是头行）。 */
+/** 读取一个会话头的第一个 zstd 帧（就是头行）。仅用于 CLI/测试清理，不用于 MCP 热路径。 */
 function readHeader(file) {
   try {
     const text = zstdDecompressSync(readFileSync(file)).toString('utf8');
@@ -230,6 +231,62 @@ function readHeader(file) {
   }
 }
 
+/**
+ * 异步读取会话头：流式解压，拿到第一行就销毁流。
+ *
+ * 为什么需要它：MCP 服务在 `Hub.get()` 里找回磁盘会话时必须读头；
+ * `readHeader()` 会把整份日志同步解压，超大日志会阻塞事件循环、停掉
+ * 心跳（多实例下可能被误判 stale-mcp）。这里只解到第一个换行，
+ * 不把整份日志读进内存，也不阻塞事件循环。
+ *
+ * 超时/读失败返回 null；调用方按“找不到会话头”处理。
+ */
+export async function readHeaderAsync(file, { timeoutMs = 5000, maxHeaderBytes = 1024 * 1024 } = {}) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let buf = '';
+    let timer = null;
+    const decoder = new StringDecoder('utf8');
+    const rs = createReadStream(file);
+    const zs = createZstdDecompress();
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      try { rs.destroy(); } catch {}
+      try { zs.destroy(); } catch {}
+      resolve(value);
+    };
+    const parseLine = (line) => {
+      try {
+        const value = JSON.parse(String(line).trim());
+        finish(value && typeof value === 'object' ? value : null);
+      } catch {
+        finish(null);
+      }
+    };
+    timer = setTimeout(() => finish(null), timeoutMs);
+    timer.unref?.();
+    rs.on('error', () => finish(null));
+    zs.on('error', () => finish(null));
+    zs.on('data', (chunk) => {
+      // 用 StringDecoder 处理跨 chunk 的多字节 UTF-8（中文/emoji 路径），
+      // 避免 chunk.toString() 把字符截成乱码。
+      buf += decoder.write(chunk);
+      const nl = buf.search(/\r?\n/);
+      if (nl >= 0) parseLine(buf.slice(0, nl));
+      else if (buf.length > maxHeaderBytes) finish(null);
+    });
+    zs.on('end', () => {
+      buf += decoder.end();
+      const line = buf.split(/\r?\n/).find(Boolean);
+      if (line) parseLine(line);
+      else finish(null);
+    });
+    rs.pipe(zs);
+  });
+}
+
 /**
  * 扫描磁盘上所有会话，按 header.cwd 归组。数据源是会话头，不是目录名（目录名有损）。
  *
@@ -272,7 +329,7 @@ export function scanSessions() {
  *
  * 会对 id 做形状校验（只允许 UUID / `session-` 前缀那类字符），避免 `..` 之类逃出会话目录。
  */
-export function findSessionHeader(sessionId) {
+export async function findSessionHeader(sessionId) {
   if (typeof sessionId !== 'string' || !/^[A-Za-z0-9._-]{4,80}$/.test(sessionId)) return null;
   if (!existsSync(SESSIONS_ROOT)) return null;
   let buckets;
@@ -284,7 +341,7 @@ export function findSessionHeader(sessionId) {
   for (const bucket of buckets) {
     const f = join(SESSIONS_ROOT, bucket, sessionId, 'session.v4.jsonl.zstd');
     if (!existsSync(f)) continue;
-    const header = readHeader(f);
+    const header = await readHeaderAsync(f);
     if (header?.id === sessionId) return header;
   }
   return null;