dsh-any-agent 0.5.2 → 0.6.0

package/CHANGELOG.md

@@ -7,6 +7,126 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] — 2026-11-07
+
+### Added
+
+- **Zero-config DSH discovery, including the desktop app.** The server now finds
+  the DeepSeek Harness desktop app on its own (Windows uninstall registry via
+  `reg export`, plus default install paths on every platform), reads the CLI's
+  version and `engines` straight out of `resources/app.asar` with plain Node,
+  and launches it on the app's bundled Electron runtime in Node mode
+  (`ELECTRON_RUN_AS_NODE=1`). Previously only npx caches and npm global installs
+  were searched, so with the desktop app on 0.2.2-rc.1 the server silently ran a
+  stale 0.2.1-rc.5 from an npx cache. Candidates are ranked runnable-first →
+  newest → desktop > npm global > npx. `DSH_BIN` stays as an explicit override
+  (it may point inside an `.asar`); new `DSH_RUNTIME` overrides the launcher,
+  both with `DSH_BIN` and on its own for auto-discovered npm/npx installs (whose
+  `engines.node` is then re-checked against it); the desktop app always keeps its
+  bundled runtime.
+- `dsh_doctor`: `dsh_bin` shows the source and runtime; new `dsh_runtime`
+  (launcher's Node vs DSH's `engines.node` — 0.2.2 needs Node ≥ 24.9),
+  `dsh_desktop` (warns when the GUI and this server run different DSH versions
+  over the shared `~/.dsh`), and `dsh_candidates`.
+- Background receipts on Windows carry `sentinel_read_powershell`, a reader that
+  passes `-Encoding UTF8` (Windows PowerShell 5.1 otherwise misreads the BOM-less
+  sentinel and `ConvertFrom-Json` fails on CJK text).
+- `npm run lint` (`scripts/lint.mjs`, no npm dependencies): `node --check` on every
+  `.mjs`, relative import paths that resolve with exact case, named imports that
+  are real exports (including `await import()` destructuring and `node:`
+  builtins), and unused named imports. Runs first in every CI offline cell and at
+  the Node 22.15 floor; `test/lint.mjs` is its regression suite. Its first run
+  removed nine unused imports.
+- **Test counts in the docs are generated, not hand-edited.** `test/run.mjs`
+  writes a machine-readable report (`.state/test-report.json` by default,
+  `--report <path>`; per suite: passed/failed/skipped/duration, plus platform,
+  Node, DSH and client-fixture context), every suite prints a standard summary
+  line, and `npm run docs:counts` rewrites the per-suite counts, totals and the
+  CI scope comment from it; `npm run docs:counts:check` fails on any mismatch.
+  The CI offline job runs the check on the platform-independent suites, and the
+  release checklist includes it. Several hand-maintained numbers were wrong and
+  are corrected (e.g. failure-terminal 10, not 11).
+
+### Changed
+
+- **Internal: `src/hub.mjs` and `src/tools.mjs` are split into cohesive modules**
+  with no behaviour change. From `hub.mjs`: `conversation.mjs` (the `Conversation`
+  class), `git-snapshot.mjs`, `hub-store.mjs` (meta sidecar and forget
+  tombstones), `sentinel.mjs`, `workspace-guard.mjs`, `acp-session.mjs`. From
+  `tools.mjs`: `tool-defs.mjs`, `tool-render.mjs`, `doctor.mjs`. Both files
+  re-export every name they exported before, so existing import paths still work.
+- `model-suites` workflow finds DSH through the project's own `resolveDsh()`
+  (`scripts/detect-dsh.mjs`) instead of `command -v dsh`, so a self-hosted runner
+  with only the desktop app installed works without secrets; `DSH_BIN` stays an
+  optional override.
+- **`dsh-any-agent-workspaces --purge-test-sessions --ids …` now refuses
+  sessions whose cwd is not a test directory**, even when named explicitly, and
+  reports them as skipped. The purge also removes every artifact of a test
+  session (projection cache, registry entry, sentinels, reviews, locks), not
+  just its session directory.
+- Compatibility matrix: DSH 0.2.1-rc.5 and 0.2.2-rc.1 are **verified** (full
+  suites, 2026-11-06); 0.2.3+ is unverified.
+- Server `instructions` cut from ~4.4k to ~1.5k characters with the hard rules
+  first. Clients truncate long instructions (Claude Code dropped the old tail,
+  including the "don't" rules); `smoke` now enforces a 2400-character cap.
+- `node test/run.mjs` runs **every** suite and lists all failures at the end;
+  `--bail` restores stop-at-first-failure. One stale assertion used to hide the
+  eleven model-backed suites after it.
+
+### Fixed
+
+- **Test runs left residue in the real `~/.dsh`.** Purging a test session removed
+  only its session directory; the DSH projection cache
+  (`storages/session_projcache/sessions/<id>.json`) was never removed, so about
+  400 orphan files piled up, and the project's own `runs/`, `reviews/`, `meta/`,
+  `locks/` and registry entries leaked too (eight suites kept their state loose
+  under `%TEMP%`, where nothing cleaned it). Every model-backed suite now purges
+  exactly the sessions it created (plus DSH-spawned subagent sessions) with every
+  artifact in its own `finally`; `test/cleanup.mjs` is only the backstop and also
+  sweeps old orphans. The purge refuses any session whose cwd is not a test
+  directory, even when named by id, and no longer re-registers every temp session
+  on disk into the GUI workspace list as a side effect. New offline suite
+  `residue-purge` proves both halves in a sandboxed `DSH_HOME`. With
+  `DSH_MCP_KEEP_EVIDENCE=1`, `cleanup.mjs` now skips the whole sweep, so the
+  sessions and state directories that `acceptance` / `workspace-effect` keep for
+  inspection survive the end-of-run cleanup.
+- **`dsh_read` merged different tool calls into one entry.** Consecutive tool
+  updates in a turn were concatenated (`read [in_progress]read [completed]pwsh …`)
+  under the first call's `tool_call_id`. Each tool call now has its own entry and
+  a status update replaces it in place; only streamed text is still merged, so an
+  empty turn's start/end markers also stay separate. Because an in-place update
+  can give an earlier entry a higher revision, `dsh_read` now pages in revision
+  order (entries in a page are still returned in time order) so a small `limit`
+  can never skip an unread entry, and `gap` is computed from entries actually
+  evicted from the ring buffer instead of assuming revisions grow along it.
+- **`answer` ran message segments together.** Text DSH sends before and after a
+  tool call is two messages, but the collected answer joined them with no
+  separator (`…where possible.1) package.json…`). A blank line now separates a
+  segment that follows a tool call (none is added when the previous segment
+  already ends with a newline, or before the first text); `dsh_read` entries are
+  unchanged.
+- **A clean repository is a 0-change snapshot, not `null`.** `null` now only means
+  "no snapshot" (not a git repo, git unavailable, disabled). A turn that removed
+  the last change used to report `workspace_changed=true` with `diff_stat=null`.
+- **A cold `session/resume` that DSH never answers is retried once.** A live
+  `test/multi.mjs` run once hit `ACP request timed out: session/resume` (60 s of
+  silence from a freshly spawned DSH); a rerun passed and it did not reproduce in
+  ~70 controlled resume cycles, 40 of them under concurrent load. The write lock is
+  ruled out (DSH takes it with a zero-timeout wait and refuses instantly), so it
+  looks like a rare stall inside the DSH process. `resume` is idempotent and the
+  failure path already kills the process and waits for it to exit, so `ensureAlive`
+  now rebuilds the process and retries exactly once — only for a timeout, never for
+  a write-lock refusal or invalid params, and not on a shared host that still carries
+  other conversations. `AcpProcess` timeout errors now carry `code=ACP_TIMEOUT` and
+  `method`, and the DSH stderr tail at the moment of a timeout goes to the opt-in
+  `DSH_MCP_LOG_STDERR` log. New offline suite `resume-retry` (fake ACP server).
+- Tests: `timeout` asserts that a negative `timeout_ms` is rejected (the 0.4.0
+  behaviour) instead of the old "wait forever" semantics, and no longer passes on
+  an error result; `list` asserts caching via `probe_cached` instead of a 500 ms
+  wall-clock threshold; `integration`'s queue check uses a code token instead of
+  requiring the model to echo a phrase verbatim; `capability` prints the tool
+  error text when a call fails instead of an empty `err=`.
+
 ## [0.5.2] — 2026-11-05
 
 ### Fixed
@@ -1016,7 +1136,12 @@ 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.9...HEAD
+[Unreleased]: https://github.com/xmtlzzz/dsh-any-agent/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/xmtlzzz/dsh-any-agent/compare/v0.5.2...v0.6.0
+[0.5.2]: https://github.com/xmtlzzz/dsh-any-agent/compare/v0.5.1...v0.5.2
+[0.5.1]: https://github.com/xmtlzzz/dsh-any-agent/compare/v0.5.0...v0.5.1
+[0.5.0]: https://github.com/xmtlzzz/dsh-any-agent/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/xmtlzzz/dsh-any-agent/compare/v0.3.9...v0.4.0
 [0.3.9]: https://github.com/xmtlzzz/dsh-any-agent/compare/v0.3.8...v0.3.9
 [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

package/USAGE-NOTES.en.md

@@ -24,7 +24,7 @@ Practical gotchas and trade-offs you *will* hit when letting Claude / Codex driv
 
 **1.4 Never register dsh-any-agent into DSH's own MCP list.** DSH is an MCP client, this server is an MCP server; pointing one at the other recurses forever.
 
-**1.5 `DSH CLI entry not found`.** Set `DSH_BIN` explicitly (auto-detection scans the npx cache, npm global, and common paths).
+**1.5 `DSH CLI entry not found`.** Auto-detection finds the DeepSeek Harness desktop app (Windows uninstall registry plus default install paths on every platform; the CLI inside `app.asar` runs on the app's bundled runtime), npm global installs and the npx cache. Check `dsh_candidates` in `dsh_doctor`; for portable or custom locations set `DSH_BIN` explicitly (it may point inside `app.asar`).
 
 ## 2. Cost and budget
 
@@ -94,6 +94,8 @@ Practical gotchas and trade-offs you *will* hit when letting Claude / Codex driv
 
 **6.3 Temp directories are skipped by default** (`DSH_MCP_REGISTER_WORKSPACE=project`) so test runs don't flood your GUI. Use `all` to include them.
 
+**6.4 Running the tests must not leave anything in `~/.dsh`.** Symptom: the session count under `~/.dsh` keeps growing, and `storages/session_projcache/sessions/` holds many orphan files whose session directories are long gone. Cause: model-backed tests use your real `~/.dsh` (the credentials live there, so it cannot be isolated), and the old cleanup removed the session directory but neither the projection cache nor this project's own `runs/reviews/meta/locks`. Now: every model-backed suite removes the sessions it created, with every artifact, in its own `finally`, and `node test/cleanup.mjs` is the global backstop. **Only sessions whose cwd is a test directory are ever deleted** — naming an id does not bypass that. See `docs/en/tests.md`.
+
 ## 7. Privacy
 
 **7.1 Silent by default** — not one byte. MCP's stdout is the protocol channel, and stderr lands in Claude/Codex's logs.

package/USAGE-NOTES.md

@@ -37,8 +37,10 @@
 
 ### 1.5 `DSH_BIN` 探测失败
 - **现象**：启动即报 `DSH CLI 入口未找到`。
-- **原因**：DSH 装在非常规位置（本服务按 npx 缓存 → npm 全局 → 常见路径的顺序通配搜索）。
-- **对策**：显式设置 `DSH_BIN=/path/to/node_modules/@deepseek-ai/dsh/lib/bin.js`。
+- **原因**：DSH 装在非常规位置。本服务自动识别 DeepSeek Harness 桌面版（Windows 卸载注册表 +
+  各平台默认安装位置，用桌面版自带运行时跑 asar 里的 CLI）、npm 全局安装和 npx 缓存。
+- **对策**：先跑 `dsh_doctor` 看 `dsh_candidates`；便携版/自定义位置再显式设置
+  `DSH_BIN=/path/to/node_modules/@deepseek-ai/dsh/lib/bin.js`（可指进 `app.asar` 内部）。
 
 ---
 
@@ -226,6 +228,11 @@
 - **原因**：跑测试会在 `%TEMP%` 下建一堆工作区，全登记会把你 GUI 灌满。
 - **对策**：默认模式 `project` 会跳过临时目录。要连临时目录一起登记就设 `DSH_MCP_REGISTER_WORKSPACE=all`。
 
+### 6.4 跑测试不该在 `~/.dsh` 里留东西
+- **现象**：`~/.dsh` 里会话数越攒越多；`storages/session_projcache/sessions/` 里有大量会话目录早已不在的孤儿文件。
+- **原因**：真机测试用的是你真实的 `~/.dsh`（凭据在那里，没法隔离）；旧版清理只删会话目录，不删投影缓存，也不清本项目自己的 `runs/reviews/meta/locks`。
+- **现状**：每个真机套件在 `finally` 里清掉自己造的会话及全部产物，全局 `node test/cleanup.mjs` 兜底；**只有 cwd 是测试目录的会话才会被删**，点名 id 也绕不过。详见 `docs/zh/tests.md`。
+
 ---
 
 ## 七、隐私与日志

package/bin/dsh-any-agent-workspaces.mjs

@@ -15,8 +15,11 @@
  *   node bin/dsh-any-agent-workspaces.mjs --purge-test-sessions [--dry-run] [--ids=a,b]
  *
  * 只有 --purge-test-sessions 会动磁盘上的会话文件，且规则很死：只删
- * "cwd 在 tmpdir()/dsh-any-agent-* 下" 或 "cwd 在 Desktop\dsh-any-agent-test-*" 的会话，
- * 外加 --ids 显式指定的。**不会**删除用户在 %TEMP% 里自己的真实项目会话。
+ * "cwd 在 tmpdir()/dsh-any-agent-* 下"、"cwd 在 Desktop\dsh-any-agent-test-A|B" 或本仓库
+ * ".state/ws-probe-*" 的会话。**不会**删除用户在 %TEMP% 里自己的真实项目会话。
+ * --ids=a,b 只清点名的那几个，但**点名也绕不过护栏**：cwd 不是测试目录的会被拒绝并列出。
+ * 每个被删会话的全部产物一并清掉（日志、投影缓存、工作区登记、墓碑，以及本项目的
+ * 注册表/元数据/哨兵/审核/锁登记）；另外清掉投影缓存里的测试孤儿。
  */
 
 import {
@@ -24,10 +27,10 @@ import {
   listWorkspaces,
   pruneEmptyWorkspaces,
   pruneTempWorkspaces,
-  purgeTestSessions,
   WORKSPACE_FILE,
   SESSIONS_ROOT,
 } from '../src/workspace.mjs';
+import { purgeTestResidue, sweepTestResidue } from '../src/residue.mjs';
 
 const argv = process.argv.slice(2);
 const has = (f) => argv.includes(f);
@@ -46,14 +49,18 @@ const ids = (val('--ids') ?? '').split(',').map((s) => s.trim()).filter(Boolean)
 
 // ── 清理测试会话（唯一会删文件的动作） ──────────────────────
 if (has('--purge-test-sessions')) {
-  const res = purgeTestSessions({ dryRun, ids, testOnly: true });
+  // 点名（--ids）= 只清这几个；否则全盘扫荡。两条路都会连带清本项目侧的 per-run 数据。
+  const full = ids.length ? purgeTestResidue({ ids, dryRun }) : sweepTestResidue({ dryRun });
+  const res = full.sessions;
   console.log(`${flag}清理测试会话：${res.count} 个`);
   for (const v of res.victims) {
     console.log(`  - ${v.id}  [${v.reason}]${v.origin ? ` origin=${v.origin}` : ''}  cwd=${v.cwd}`);
     if (v.error) console.log(`      ⚠️ 删除失败: ${v.error}`);
   }
+  for (const s of res.skipped ?? []) console.log(`  ✗ 拒绝 ${s.id}：${s.reason}  cwd=${s.cwd}`);
   if (!res.count) console.log('  （没有命中任何会话）');
-  if (!dryRun) console.log('  已同步从工作区注册表摘除这些会话 id');
+  if (!dryRun) console.log('  已同步清掉这些会话的投影缓存、工作区登记、墓碑与本项目 per-run 数据');
+  if (full.orphans) console.log(`${flag}  投影缓存测试孤儿：${full.orphans.count} 个`);
   console.log('');
 }
 

package/bin/dsh-any-agent.mjs

@@ -3,7 +3,8 @@
  * dsh-any-agent 入口：以 MCP stdio 服务端方式运行，用 DSH (ACP) 作为后端。
  *
  * 环境变量：
- *   DSH_BIN                     DSH CLI 入口（默认探测 npx 缓存位置）
+ *   DSH_BIN                     DSH CLI 入口（默认自动识别：桌面版 → npm 全局 → npx 缓存）
+ *   DSH_RUNTIME                 拉起 DSH 的可执行文件（默认：桌面版用其自带运行时，其余用本进程 node）
  *   DSH_MCP_PROFILE             驱动用的 DSH profile（默认 dsh-mcp）
  *   DSH_MCP_STATE               会话注册表路径（默认 $DSH_HOME/.dsh-any-agent/conversations.json）
  *   DSH_MCP_PERMISSION          新建会话的默认权限档（默认 danger-full-access）
@@ -45,6 +46,8 @@ if (argv.includes('--help') || argv.includes('-h')) {
     '  dsh-any-agent-setup --yes     apply\n\n' +
     'Key environment variables (all optional):\n' +
     '  DSH_BIN                  path to @deepseek-ai/dsh/lib/bin.js; auto-detected\n' +
+    '                           (desktop app -> npm global -> npx cache)\n' +
+    '  DSH_RUNTIME              executable that launches DSH; auto (desktop app\'s own runtime)\n' +
     '  DSH_MCP_PROFILE          DSH profile to drive (default dsh-mcp)\n' +
     '  DSH_MCP_PERMISSION       danger-full-access | workspace-write | read-only\n' +
     '  DSH_MCP_APPROVAL         auto-allow | auto-deny | ask\n' +

package/bin/restore.mjs

@@ -19,7 +19,7 @@
 import { chmodSync, existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
 
-import { atomicWrite, backupFile, clientList, resolveDirs, ENTRY_NAME } from '../src/clients.mjs';
+import { atomicWrite, backupFile, clientList, resolveDirs } from '../src/clients.mjs';
 
 const argv = process.argv.slice(2);
 const has = (f) => argv.includes(f);

package/docs/en/compatibility.md

@@ -12,7 +12,8 @@ upgrading DSH, and run `dsh_doctor` afterwards.
 |---|---|---|---|
 | 0.5.x | `0.1.7-rc.1` or newer | ✅ Verified | ACP and the experimental Agent Teams packages are available; team mode is opt-in via `dsh-any-agent team on` |
 | 0.5.x | `0.1.5-rc.1` | ⚠️ Partial | ACP basics work; no team packages, so team mode stays off |
-| 0.5.x | `0.2.x` | ⚠️ Unverified | The ACP `session/*` surface may change; team packages must match the DSH version. Run `dsh_doctor` and the offline suite before upgrading |
+| 0.5.x | `0.2.1-rc.5` – `0.2.2-rc.1` | ✅ Verified | Full suites run on 2026-11-06 (0.2.1-rc.5 from npm, 0.2.2-rc.1 on the desktop app's bundled runtime); from 0.2.2 DSH requires Node ≥ 24.9 |
+| 0.5.x | `0.2.3` or newer | ⚠️ Unverified | The ACP `session/*` surface may change; team packages must match the DSH version. Run `dsh_doctor` and the offline suite before upgrading |
 | 0.4.x | `0.1.7-rc.1` | ✅ Verified | Team mode was on by default at that time |
 | 0.4.x | `0.1.5-rc.1` | ⚠️ Partial | No team packages |
 
@@ -22,22 +23,41 @@ upgrading DSH, and run `dsh_doctor` afterwards.
 
 ## Runtime requirements
 
-- **Node.js ≥ 22.15** (uses `zstdDecompressSync` from `node:zlib` to read DSH session headers);
+- **Node.js ≥ 22.15** for this server (uses `zstdDecompressSync` from `node:zlib` to read DSH session headers);
 - DSH installed and `~/.dsh` already has a working provider and credentials (the GUI can chat);
+- **DSH's own Node requirement** (`engines.node`, ≥ 24.9 from 0.2.2) is met by whatever runtime launches DSH:
+  the desktop app's bundled runtime when DSH comes from the desktop app (no local Node 24 needed), or this server's node for npm/npx installs;
 - Team mode also requires DSH `>= 0.1.7-0` and a profile that actually mounts both team packages.
 
+## Where DSH comes from (auto-detected, no configuration)
+
+The server finds DSH on its own, in this order — **no need to set `DSH_BIN`**:
+
+1. **DeepSeek Harness desktop app**: on Windows the install directory comes from the uninstall
+   registry (HKCU/HKLM); default install locations are checked on every platform. The CLI lives
+   inside `resources/app.asar`, so the server runs it with the app's bundled Electron in Node mode
+   (`ELECTRON_RUN_AS_NODE=1`) — the same DSH and the same runtime the GUI uses;
+2. **npm global install** (`npm i -g @deepseek-ai/dsh`);
+3. **npx cache** (can vanish at any time; lowest priority when otherwise equal).
+
+When several exist: candidates whose runtime satisfies `engines.node` first → higher version →
+desktop > global > npx. `DSH_BIN` (may point inside an `.asar`) and `DSH_RUNTIME` (the executable
+that launches DSH) are explicit overrides only.
+
 ## How to check
 
 ```bash
 dsh-any-agent --version          # this server
-node <DSH_BIN> --version         # DSH version (set DSH_BIN to pin it)
 dsh-any-agent team status        # team switch and profile
 ```
 
 In an MCP client, call `dsh_doctor` and look at:
 
-- `dsh_bin`: DSH entry point and version; **warn** when it resolves from an npx cache (`_npx/<hash>/`), which disappears on cache cleanup — install DSH globally or pin `DSH_BIN`;
-- `dsh_version`: the version graded against the table above — `verified` is ok; `partial` / `unsupported` / `unverified` (e.g. 0.2.x) / unreadable are **warn**;
+- `dsh_bin`: DSH entry point, version, source (desktop / npm global / npx cache / DSH_BIN) and runtime; **warn** when it resolves from an npx cache (`_npx/<hash>/`), which disappears on cache cleanup;
+- `dsh_runtime`: whether the launching runtime's Node satisfies DSH's `engines.node`; **warn** if not;
+- `dsh_desktop`: the desktop app's version; **warn** when it differs from the DSH this server uses (both share the `~/.dsh` session store);
+- `dsh_candidates`: every DSH found and which one was picked;
+- `dsh_version`: the version graded against the table above — `verified` is ok; `partial` / `unsupported` / `unverified` (e.g. 0.2.3+) / unreadable are **warn**;
 - `profile`: exists, drift, route source;
 - `team`: `on` / `off` / `requested but unavailable` (version or profile lacks the team package);
 - `config`: effective permission, idle reaping, shared process, and so on.
@@ -49,4 +69,5 @@ In an MCP client, call `dsh_doctor` and look at:
 3. If team mode will not turn on, check `dsh-any-agent team status` and `dsh_doctor`'s
    `team` check, then verify `~/.dsh/profiles/dsh-team/cordis.patch.yml` contains
    `@deepseek-ai/dsh-experimental-agent-team`;
-4. To pin a DSH version, set `DSH_BIN` explicitly instead of letting the npx cache pick one.
+4. By default the server follows the desktop app: after the app updates, the next DSH launch picks
+   up the new version (discovery is cached for 60 s). Set `DSH_BIN` only to pin a specific version.

package/docs/en/reference.md

@@ -4,7 +4,8 @@
 
 | Variable | Default | Purpose |
 |---|---|---|
-| `DSH_BIN` | auto-detected | Path to `@deepseek-ai/dsh/lib/bin.js` |
+| `DSH_BIN` | auto-detected (desktop app → npm global → npx cache) | Explicit path to `@deepseek-ai/dsh/lib/bin.js` (may point inside the desktop app's `app.asar`) |
+| `DSH_RUNTIME` | auto | Explicit executable that launches DSH (e.g. a Node 24). Used with `DSH_BIN`, or on its own for auto-discovered npm global / npx installs (their `engines.node` is re-checked against it); the desktop app always keeps its bundled runtime (only it can read the asar). Unset: the desktop app's bundled runtime, otherwise this server's node |
 | `DSH_HOME` | `~/.dsh` | DSH home shared with the GUI (credentials, sessions, workspace registry). Point it elsewhere only for isolation/multi-account |
 | `DSH_MCP_PROFILE` | `dsh-mcp` (`dsh-team` when team is on) | DSH profile to drive; an explicit value wins |
 | `DSH_MCP_TEAM` | `0` (off) | Team mode, opt-in. `dsh-any-agent team on` writes the settings file; this env var overrides it. When on, uses the `dsh-team` profile and injects a "form a team when needed" line before `dsh_send`; per call use `dsh_send(team=false)` |

package/docs/en/release.md

@@ -13,6 +13,10 @@ npm version patch --no-git-tag-version
 node test/run.mjs
 node test/package-check.mjs
 npm run check:release   # version / CHANGELOG / doc links / package contents agree
+npm run docs:counts:check   # check counts in tests.md and the CI comment = the report node test/run.mjs just wrote
+#    A mismatch means tests changed without the numbers being refreshed:
+#    node test/run.mjs --all --report .state/test-report.json && npm run docs:counts
+#    (model-suite numbers only move with a report made using --all; see "After changing tests" in docs/en/tests.md)
 
 # 3. Verify the tarball itself: builds, installs, starts.
 npm pack --dry-run

package/docs/en/tests.md

@@ -6,17 +6,30 @@
 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)
+npm run lint               # zero-dependency static checks: syntax, imports, named exports, unused imports
+node test/run.mjs --all --report .state/test-report.json   # same, writing the JSON report to a chosen path (every run writes .state/test-report.json by default)
+npm run docs:counts       # write the report's check counts back into this page and the CI comment (see "After changing tests")
+npm run docs:counts:check # check that the docs agree with the report; exit 1 and print the diff if not
 ```
 
+`npm run lint` (`scripts/lint.mjs`) runs `node --check` on every `.mjs` under `src/ bin/ scripts/ test/ demo/`, and verifies that every relative `import` / `export … from` points at an existing file with **exactly matching case**, that every named import is a real export of the target module, and that no named import is unused. It adds no npm dependency (`package-check` still enforces zero dependencies) and is a token-level scan rather than a full parser: it prefers a missed report to a false one. Run it after splitting modules or moving functions — a forgotten export tends to blow up only on some cold path, which CI without a real DSH never reaches. The offline CI job runs it first in every matrix cell.
+
 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`.
+The suite **cleans up after itself and leaves no residue**. Each model-backed suite calls `cleanupSuite` (`test/residue.mjs`) in its own `finally` and removes exactly the sessions it created (`McpClient` records every `dsh_start` id automatically; the suite's own temp root additionally catches sessions whose id was lost and the subagent sessions DSH spawns itself), together with **every artifact** they produced:
+- DSH side: the session log, the projection cache `storages/session_projcache/sessions/<id>.json` (deleting the session directory does **not** remove it — older runs piled up hundreds of orphans), the `workspace.json` registration, and the forget tombstone;
+- this project's side: the registry entry, `meta/`, sentinels `runs/`, reviews `reviews/`, and lock markers `locks/` (the state directory now lives inside the suite's own temp root instead of loose under `%TEMP%`).
+
+`run.mjs` still ends with a global `cleanup.mjs` as the backstop (killed processes, leftovers from older versions, test orphans in the projection cache). **Guard rail**: a session is only ever deleted when its recorded cwd is **a test-created directory** (this process's `tmpdir()/dsh-any-agent-*`, `Desktop/dsh-any-agent-test-A|B`, or this repo's `.state/ws-probe-*`) — naming an id does not bypass it. Real project sessions (including projects under `%TEMP%`), the temp roots of parallel agents (TMP pointed elsewhere) 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`.
+
+Why model-backed suites do not point `DSH_HOME` at a throwaway sandbox: DSH keeps its credentials in `$DSH_HOME/.credentials.yaml`, so a sandbox has no model access, and copying keys or routes into a temp directory would just open another leak surface. They keep using the real `~/.dsh` and rely on the precise cleanup above (offline suites already use a sandbox `DSH_HOME`, see `test/sandbox-home.mjs`).
 
 | Suite | Checks | Covers |
 |---|---|---|
-| `smoke` | 31 | handshake, tool table (15 tools), conversation creation, config, registry purity, prototype-name tool rejection |
+| `smoke` | 33 (20 without DSH) | handshake, **instructions length cap** (clients truncate long instructions) with the core rules up front, tool table (15 tools), conversation creation, config, registry purity, prototype-name tool rejection |
+| `dsh-locate` | 21 | **DSH auto-discovery**: a synthetic `app.asar` is read with plain Node (version, `engines.node`, entry existence), a desktop install dir maps to its bundled Electron runtime with `ELECTRON_RUN_AS_NODE=1`, candidate ranking (runnable first → newer → desktop > global > npx), `DSH_BIN` pointing inside an asar picks the desktop runtime, `DSH_RUNTIME` override, `engines.node` range evaluation, and parsing of `reg export` output (no tokens, no registry access) |
 | `boundary` | 46 | protocol edges (double initialize, malformed lines, unknown method), argument validation (including read-only + permissive approval rejection, unknown provider/model, and no stale write-lock marker on a failed create), unknown ids, cursor edges, lifecycle idempotence, unicode |
 | `integration` | 30 | resume-with-memory across processes, interrupt, both interject modes |
 | `async` | 21 | fire-and-forget + later collection, including the review ticket in the receipt/result/sentinel and a real `dsh_review` round trip |
@@ -25,46 +38,75 @@ The suite **cleans up after itself**: `run.mjs` always ends with `cleanup.mjs`,
 | `guards` | 40 | **environment-variable guards**: odd numbers always land on the safe side — `IDLE_TTL_MS=-1` means "never reap", garbage/empty falls back to the 10-minute default, a too-small reap interval falls back to the default (no busy loop), and the **lost-holder threshold is floored at 30 s** (so another instance cannot "legitimately" preempt and kill our turn); plus the team-mode default and precedence (`DSH_MCP_TEAM` > `settings.json` > off) (no tokens, runs every time) |
 | `sandbox-guard` | 21 | **the test sandbox itself**: a "throwaway HOME" that resolves to the real user profile, to the filesystem root, or to anywhere outside the OS temp dir is refused with an error instead of being written to and deleted. Every other suite builds its HOME through `test/sandbox-home.mjs` and can only destroy what it created there (no tokens, runs every time) |
 | `approval-details` | 37 | **approval review context**: the pending-approval snapshot carries the command, reason, cwd and original approval ID — not just a bare ID — so a caller can actually adjudicate; missing `rawInput` is correlated from the earlier `tool_call` update by ID; credential-shaped fields and common inline literals are redacted; closing a conversation cancels pending approvals. Verified end-to-end over real stdio MCP |
-| `failure-terminal` | 11 | **terminal state on failure**: an `ensureAlive` failure wakes `dsh_interject` waiters, writes an `error` sentinel, and attaches `runId` to the error; an approval with no matching option reports `effective=cancelled` instead of a fake allow; `dsh_get` reads a run back from its sentinel (no tokens) |
+| `failure-terminal` | 10 | **terminal state on failure**: an `ensureAlive` failure wakes `dsh_interject` waiters, writes an `error` sentinel, and attaches `runId` to the error; an approval with no matching option reports `effective=cancelled` instead of a fake allow; `dsh_get` reads a run back from its sentinel (no tokens) |
 | `shared-host` | 25 | **shared process host**: notifications and permission requests route by `sessionId`, unknown-session approvals are cancelled, a process exit fans out to every attached conversation, the child stops only when the last conversation detaches; **on by default and switchable off with `=0`** (an empty value counts as unset); the pre-takeover collision check for a shared process; RSS helper (no tokens) |
 | `shared-process` | 8 (skips without DSH) | **real-DSH shared process**: two conversations with the same `(cwd, permission)` share one PID, closing one leaves the other alive, closing both clears the host and exits the PID (needs a local DSH; runs with `--all`) |
-| `dispatch-tools` | 55 (53 off Windows) | **dispatch surface**: `dsh_inbox` aggregates pending approvals across conversations, `client_run_id` idempotency hits and evicts with its run, queue list/update/promote/remove (remove writes a cancelled sentinel), `dsh_get(max_chars)` compacts both text and structured (answer truncated, tool inputs reduced to `input_chars`; `max_chars=0` still returns everything), `dsh_doctor` DSH-version grading and npx-cache detection, PowerShell sentinel-waiter escaping plus a real run (Windows only), audit records metadata only, `dsh_doctor` essential checks (no tokens) |
+| `resume-retry` | 63 | **cold-resume timeout retry** (uses `test/fake-acp.mjs` as DSH, run once shared and once with `DSH_MCP_SHARED_PROCESS=0`): a silent first `session/resume` is retried once on a fresh process (old child exited, lock marker points at the new one); a permanently silent one fails after exactly one retry with no zombie child or marker; a write-lock refusal or invalid params is *not* retried; `AcpProcess` timeout errors carry `code=ACP_TIMEOUT`/`method`; a shared host that still carries another conversation is not retried (no tokens) |
+| `dispatch-tools` | 59 (55 off Windows) | **dispatch surface**: `dsh_inbox` aggregates pending approvals across conversations, `client_run_id` idempotency hits and evicts with its run, queue list/update/promote/remove (remove writes a cancelled sentinel), `dsh_get(max_chars)` compacts both text and structured (answer truncated, tool inputs reduced to `input_chars`; `max_chars=0` still returns everything), `dsh_doctor` DSH-version grading (0.2.1-rc.5 / 0.2.2-rc.1 verified, 0.2.3+ unverified) and npx-cache detection, PowerShell sentinel-waiter escaping plus a real run, and the sentinel **reader** command (`-Encoding UTF8`, parses CJK content under Windows PowerShell 5.1; real run on Windows only), audit records metadata only, `dsh_doctor` essential checks (no tokens) |
 | `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` | 10 | **`dsh_read` cursor semantics**: text appended to an already-read entry is delivered again (revision cursor, match by `seq`), and `limit` is clamped to 1..500 so `0`/negative cannot spin or drop the tail (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) |
 | `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) |
 | `workspace-safety` | 23 | **data-loss boundaries**: `isTempPath` is segment-aware (`tmpdir()+'Suffix'` and `/tmpfoo` are *not* temp), a corrupt `workspace.json` is never overwritten, an unreadable session root never wipes `sessionIds`, and automatic cleanup deletes only test-created sessions (no tokens) |
+| `residue-purge` | 149 | **test-residue cleanup** (sandboxed `DSH_HOME`, no tokens): every artifact kind of a test session (session log, projection cache, workspace registration/archived/pinned, tombstone, registry entry, meta, sentinels, reviews, lock markers) is removed; **non-test sessions stay byte-identical** (naming them does not delete them); subagent cascade, `roots` scoping, zero-write dry run, corrupt files fail closed, path traversal, legacy flat directories need evidence, every model-backed suite is wired to the teardown |
 | `permission-adopt` | 17 | **no silent privilege escalation**: adopting an external session with no permission record fails closed to `read-only`; a recorded `read-only` cannot be promoted by the sidecar; the runtime read-back rejects a recorded/requested mismatch (no tokens) |
 | `state-safety` | 26 | **state/sentinel/lock storage**: defaults live under `$DSH_HOME/.dsh-any-agent`, an unwritable directory fails startup loudly, sentinel write failures return `null` + `sentinel_error`, and bad numeric env values land on the safe side (no tokens) |
+| `workspace-snapshot` | 21 | **workspace snapshot**: `workspace_changed` must see full file contents (same status line with different content, changes past the 41st entry, inside untracked directories) and `gitStatus` runs asynchronously so it never blocks the shared MCP event loop (filesystem + a temp git repo, no tokens) |
 | `setup` | 45 | **the registration CLI**: preview writes nothing, `--remove` takes out only its own entry, an absent client is skipped rather than failed, the Codex TOML block round-trips, and the command recorded in a config is actually spawned and must answer `initialize` (no tokens). It never invokes `claude mcp get` — that CLI rewrites `~/.claude.json` |
 | `removal-scope` | 24 | **unregistering touches only its own entry**: configs holding unrelated MCP servers, top-level Codex settings and sibling Zed settings are registered and then removed, asserting every other value is byte-identical; removing something never written is a no-op with no write (no tokens) |
-| `config-safety` | 407 | **the property the 0.3 line is about**, per client: preview leaves files byte-identical with no `.bak`; register-then-remove restores every other entry byte-for-byte, keeps key order and drops no top-level key; 4-space / 2-space indentation, single-line JSON, missing trailing newline, CRLF and a UTF-8 BOM all survive a write; malformed JSON and read-only files are refused without damage; the second `--yes` is a no-op with no new backup; every `.bak-dsh-<stamp>` appears once and equals the pre-write bytes; a `claude` on PATH is never invoked (no tokens) |
-| `real-configs` | 84 (66 with 7/9, 48 with 5/9 fixtures) | **round-trip on the real thing**: copies this machine's actual client configs (an 182693-byte `~/.claude.json` holding hundreds of `projects` entries and case-colliding keys, a 238-line Codex TOML, Zed's full `settings.json`) into a temp dir, registers, then removes, and requires every file back **byte for byte**; entry-presence is checked by key (not a bare substring), and missing fixtures are reported as skipped rather than green (no tokens) |
+| `config-safety` | 407 (406 without client configs) | **the property the 0.3 line is about**, per client: preview leaves files byte-identical with no `.bak`; register-then-remove restores every other entry byte-for-byte, keeps key order and drops no top-level key; 4-space / 2-space indentation, single-line JSON, missing trailing newline, CRLF and a UTF-8 BOM all survive a write; malformed JSON and read-only files are refused without damage; the second `--yes` is a no-op with no new backup; every `.bak-dsh-<stamp>` appears once and equals the pre-write bytes; a `claude` on PATH is never invoked (no tokens) |
+| `real-configs` | 84 (66 with 7/9 fixtures, 48 with 5/9 fixtures) | **round-trip on the real thing**: copies this machine's actual client configs (an 182693-byte `~/.claude.json` holding hundreds of `projects` entries and case-colliding keys, a 238-line Codex TOML, Zed's full `settings.json`) into a temp dir, registers, then removes, and requires every file back **byte for byte**; entry-presence is checked by key (not a bare substring), and missing fixtures are reported as skipped rather than green (no tokens) |
 | `commit-script` | 26 | commit messages go through stdin, never a temp file that `git add -A` could capture (no tokens) |
+| `test-counts` | 92 | **check-count sync**: parsing suite output (Chinese/English summary lines, whole-suite skip, `✓`/`✗` fallback, `[report]` environment tags), report assembly, round-trips of the "main number (other environments)" cell, rewriting the Chinese and English docs and `tests.yml`, `--check` diffs and `--portable`, model-suite numbers left alone, failing reports refused (no tokens) |
 | `roots` | 12 | `dsh_start` without `cwd` asks the client for MCP roots; a client without roots gets an actionable error (no tokens) |
-| `workspace-titles` | 18 | home-as-workspace **and filesystem-root cwd** are rejected before DSH starts; `title_hint` is returned separately from DSH's automatic title (no tokens) |
+| `workspace-titles` | 18 (17 with TEMP outside the home directory, 16 case-sensitive with TEMP outside home) | home-as-workspace **and filesystem-root cwd** are rejected before DSH starts; `title_hint` is returned separately from DSH's automatic title (no tokens) |
 | `package-check` | 14 | `files` whitelist, zero runtime dependencies, Node floor, and bin shebangs (no tokens) |
-| `timeout` | 38 | **timeout semantics**: `wait=false` is unaffected by `timeout_ms`; a `wait=true` expiry merely downgrades to background (turn not cancelled, result not lost, `busy` never lies); `timeout_ms<=0` waits forever; a failed resume invalidates the process instead of wedging the conversation; an empty prompt yields a clear error |
+| `lint` | 22 | **Regression for the `npm run lint` static check itself**: throwaway trees prove that a syntax error, a missing or wrongly-cased import path, a missing named export (including `export { x } from`, `await import()` destructuring and `node:` builtins) and an unused import are each reported; a tree of tricky-but-valid syntax (uses inside template literals, quotes inside regex literals, `export *`) produces zero false positives; and this repo itself is lint-clean (no tokens) |
+| `timeout` | 40 | **timeout semantics**: `wait=false` is unaffected by `timeout_ms`; a `wait=true` expiry merely downgrades to background (turn not cancelled, result not lost, `busy` never lies); `timeout_ms=0` waits forever and a **negative `timeout_ms` is rejected with a clear error** (no run dispatched, conversation still usable); a failed resume invalidates the process instead of wedging the conversation; an empty prompt yields a clear error |
 | `lock` | 79 | **write lock and preemption**: four holder classifications, `writeMarker` never overwriting a live holder, malformed/missing registration edge cases; **end-to-end** with two real MCP instances fighting over one conversation → clear error → refusal → `force` takeover; **a crash releases the lock automatically**, **a wedged holder is preempted without `force`**; plus the "one turn, one sentinel" invariant (inline turns and idle interjects included) |
 | `cycle` | 36 | **the async dispatch lifecycle**: dispatch → collect the sentinel → idle reap → dispatch again, three rounds with no lock error; re-dispatch right on the reap boundary (widening the race); an immediate re-dispatch after `dsh_release`; and an assertion that reaping leaves no unattributable lock (this suite caught the reaper collecting a freshly spawned process as if it were idle) |
 | `concurrency` | 31 | three simultaneous conversations + live incremental reads |
 | `capability` | 22 | writing code, running scripts, **spawning its own subagents** (verified on disk via child session headers) |
 | `workspace-effect` | 24 | workspace actually effective when no path is given |
-| `acceptance` | 36 | two folders × two conversations doing a read-only IDA Pro analysis |
+| `acceptance` | 36 (skips without IDA MCP) | two folders × two conversations doing a read-only IDA Pro analysis |
 | `multi` | 19 | **several instances and non-ASCII paths**: reproduces "two instances share the registry and the later save drops the earlier instance's conversation", then proves **that conversation is recoverable by id alone from the session store and actually usable** (registry loss, not an explicit `forget` — forget is a terminal tombstone); **recovery never silently escalates privileges** (a read-only conversation stays read-only); no `.tmp` residue; and **CJK / emoji workspace paths** create sessions, do real work, and place files in the right directory |
 | `permission` | 11 | ★ **whether the permission tiers actually take effect** (a safety property): it ignores our own return values (the very thing that used to lie) and reads **the session's own record** (`permissions.preset` / `sandboxMode` in the projection cache), checking all three tiers and that their recorded values differ. **This suite caught a silent privilege escalation**: a `defaultPreset` in the profile overrides `DSH_PERMISSION_MODE` at session creation |
-| `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) |
+| `list` | 17 | **the cost of `dsh_list`**: a default call runs the on-disk probe (it spawns a DSH process — seconds with many sessions) while **repeated calls hit the cache** (asserted via `probe_cached`, not wall-clock: Windows occasionally adds ~700 ms to one cached call); `only_running=true` and `include_closed=false` **skip the probe** (`probe_ok=null`) 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 1012 checks on a machine with seven client fixtures (1030 with all nine)** — smoke 31 + 981 offline checks (999 with nine). Every suite exited 0 on the 0.5.0 tree plus caller review (2026-11-04, Windows / Node 22.19.0; the local five-fixture run reports 994); none needs a provider (smoke skips its session-creation sections when DSH is absent).
+> **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.
+
+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.
 
-That is **542 assertions in the client-registration suites alone** (`setup` 45, `removal-scope` 24, `config-safety` 407, `real-configs` 66; 560 with all nine fixtures), which is where the 0.3 work actually is.
+> 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.
+<!-- counts:end -->
+
+### 🔢 After changing tests: counts are computed
+
+The check counts in this page are not typed by hand. Every `node test/run.mjs` run collects each suite's output and parses it into a JSON report (default `.state/test-report.json`, which is gitignored; `--report <path>` picks another location, `--no-report` skips it): per suite `passed` / `failed` / `skipped` / `exitCode` / `durationMs`, plus the platform, Node and DSH versions and how many client-config fixtures the machine had. The numbers come from each suite's own summary line (`===== ...: passed N, failed M =====`); an older suite without one falls back to counting its `✓`/`✗` lines; a new suite should print the standard summary line.
+
+**After changing tests:**
+
+```bash
+node test/run.mjs --all --report .state/test-report.json   # needs DSH/provider; drop --all to refresh only the offline numbers
+npm run docs:counts                                        # rewrite this table, the totals above (both languages) and the scope comment in .github/workflows/tests.yml
+git diff docs .github                                      # review what changed, then commit
+```
 
-The model-backed suites (`smoke` 31, `boundary` 46, `integration` 30, `async` 21, `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, `shared-process` 8) total 489. Most were last measured in full on 0.3.9; the suites touched by caller review (`smoke`, `integration`, `async`, `sentinel`, `boundary`) were re-run on this tree. 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__*`); `shared-process` also skips without DSH.
+- **Without `--all`** the report has no model-backed suites, so their numbers are left untouched (the script says so).
+- **Environment-dependent suites** are written as "main number (other environments)": `smoke` (DSH present or not), `dispatch-tools` (Windows also runs the real PowerShell sentinel checks), `config-safety` and `real-configs` (how many client configs the machine has), `workspace-titles` (filesystem case sensitivity, whether `TEMP` is inside the home directory). **Only the cell this run measured is updated**; the others stay as they were. To refresh another cell, run in that environment and pass the reports in order with several `--report` flags.
+- **Suites that skip as a whole** (`shared-process` without DSH, `acceptance` without IDA MCP, `real-configs` without client configs) keep their numbers.
+- **A report with a failing suite is refused** (exit 2): a failing suite's count is not trustworthy.
+- **A new suite**: add it to `OFFLINE`/`MODEL` in `test/run.mjs`, then add a table row (the script does not write the "covers" text; a missing row exits 1 and names the suite).
 
-> Three different totals are intentional: `node test/run.mjs` (1012/1030), the CI offline job (nominal 981/999, no smoke; hosted runners without client fixtures skip `real-configs` entirely), and the model-backed set (489 nominal). Counts are the numbers each suite prints itself; don't use one number for a different runner.
+**Keeping it from drifting:** `npm run docs:counts:check` writes nothing; if the docs disagree with the report it prints the diff and exits 1. The CI offline job runs `node test/run.mjs --report` and then `docs:counts:check --portable`, which only checks environment-independent suites plus `smoke` / `config-safety` in the cell hosted runners land in (no DSH, no client configs); platform-dependent suites are left to the full local check (a step in the release checklist). The `test-counts` suite covers the parser and the rewriting itself.
 
 ### 🧯 Why `sandbox-guard` exists
 

package/docs/zh/compatibility.md

@@ -11,7 +11,8 @@
 |---|---|---|---|
 | 0.5.x | `0.1.7-rc.1` 及以上 | ✅ 已验证 | ACP + 实验性 Agent Teams 包均可用；团队模式需 `dsh-any-agent team on` |
 | 0.5.x | `0.1.5-rc.1` | ⚠️ 部分可用 | ACP 基本路径可用；缺 team 包，团队模式会自动保持关闭 |
-| 0.5.x | `0.2.x` | ⚠️ 未验证 | ACP 的 `session/*` 面可能变化；team 包必须与 DSH 版本匹配。升级前先跑 `dsh_doctor` 和离线套件 |
+| 0.5.x | `0.2.1-rc.5` ~ `0.2.2-rc.1` | ✅ 已验证 | 2026-11-06 全量套件实测（0.2.1-rc.5 走 npm，0.2.2-rc.1 走桌面版自带运行时）；0.2.2 起 DSH 要求 Node ≥ 24.9 |
+| 0.5.x | `0.2.3` 及以上 | ⚠️ 未验证 | ACP 的 `session/*` 面可能变化；team 包必须与 DSH 版本匹配。升级前先跑 `dsh_doctor` 和离线套件 |
 | 0.4.x | `0.1.7-rc.1` | ✅ 已验证 | 团队模式当时默认开启 |
 | 0.4.x | `0.1.5-rc.1` | ⚠️ 部分可用 | 无 team 包 |
 
@@ -20,22 +21,39 @@
 
 ## 运行时要求
 
-- **Node.js ≥ 22.15**（用到 `node:zlib` 的 `zstdDecompressSync` 读 DSH 会话头）；
+- **Node.js ≥ 22.15**（本服务自身；用到 `node:zlib` 的 `zstdDecompressSync` 读 DSH 会话头）；
 - DSH 已安装，且 `~/.dsh` 下已有可用的 provider 与凭据（GUI 能正常聊天即可）；
+- **DSH 自己的 Node 要求**（`engines.node`，0.2.2 起是 ≥ 24.9）由拉起 DSH 的运行时满足：
+  用桌面版时是桌面版自带的运行时（无需本机 Node 24）；用 npm/npx 安装时是本服务所在的 node；
+
+## DSH 从哪里来（自动识别，无需配置）
+
+服务按下面的顺序自动找 DSH，**不需要手填 `DSH_BIN`**：
+
+1. **DeepSeek Harness 桌面版**：Windows 读卸载注册表（HKCU/HKLM）里的安装目录，
+   各平台再查默认安装位置。CLI 在 `resources/app.asar` 里，服务用桌面版自带的 Electron
+   以 Node 模式（`ELECTRON_RUN_AS_NODE=1`）运行它 —— 与 GUI 用的是同一份 DSH、同一个运行时；
+2. **npm 全局安装**（`npm i -g @deepseek-ai/dsh`）；
+3. **npx 缓存**（随时可能被清掉，同等条件下最低优先）。
+
+多个来源同时存在时：当前运行时能满足 `engines.node` 的优先 → 版本高的优先 → 桌面版 > 全局 > npx。
+`DSH_BIN`（可指进 `.asar` 内部）与 `DSH_RUNTIME`（指定拉起 DSH 的可执行文件）只作显式覆盖。
 - 团队模式额外要求 DSH `>= 0.1.7-0`，并且 profile 里真的挂上了两个 team 包。
 
 ## 怎么确认
 
 ```bash
 dsh-any-agent --version          # 本服务版本
-node <DSH_BIN> --version         # DSH 版本（DSH_BIN 可用环境变量指定）
 dsh-any-agent team status        # 团队开关与 profile
 ```
 
 在 MCP 客户端里调用 `dsh_doctor`，重点看：
 
-- `dsh_bin`：DSH 入口与版本；入口落在 npx 缓存（`_npx/<hash>/`）时 **warn** —— 清缓存就会失效，建议全局安装 DSH 或固定 `DSH_BIN`；
-- `dsh_version`：按上表给版本定档 —— `verified` 为 ok；`partial` / `unsupported` / `unverified`（如 0.2.x）/ 读不到版本为 **warn**；
+- `dsh_bin`：DSH 入口、版本、来源（桌面版 / npm 全局 / npx 缓存 / DSH_BIN）与运行时；入口落在 npx 缓存（`_npx/<hash>/`）时 **warn** —— 清缓存就会失效；
+- `dsh_runtime`：拉起 DSH 的运行时的 Node 版本是否满足 DSH 的 `engines.node`，不满足时 **warn**；
+- `dsh_desktop`：桌面版版本，与本服务所用 DSH 不一致时 **warn**（两边共用 `~/.dsh` 会话存储）；
+- `dsh_candidates`：发现的全部 DSH 来源，以及自动选中了哪一个；
+- `dsh_version`：按上表给版本定档 —— `verified` 为 ok；`partial` / `unsupported` / `unverified`（如 0.2.3+）/ 读不到版本为 **warn**；
 - `profile`：是否存在、是否漂移、路由来源；
 - `team`：`on` / `off` / `requested but unavailable`（版本或 profile 不含 team 包）；
 - `config`：当前 permission、空闲回收、共享进程等生效值。
@@ -47,4 +65,5 @@ dsh-any-agent team status        # 团队开关与 profile
 3. 如果团队模式打不开，先看 `dsh-any-agent team status` 和 `dsh_doctor` 的 `team` 检查，
    再确认 `~/.dsh/profiles/dsh-team/cordis.patch.yml` 是否包含
    `@deepseek-ai/dsh-experimental-agent-team`；
-4. 需要固定 DSH 版本时，显式设置 `DSH_BIN`，不要让 npx 缓存自动挑版本。
+4. 默认跟随桌面版：桌面版升级后服务会在下次拉起 DSH 时自动用上新版本（发现结果缓存 60 秒）。
+   确实需要固定某个版本时才显式设置 `DSH_BIN`。

package/docs/zh/reference.md

@@ -4,7 +4,8 @@
 
 | 变量 | 默认 | 说明 |
 |---|---|---|
-| `DSH_BIN` | 自动探测 | `@deepseek-ai/dsh/lib/bin.js` 路径 |
+| `DSH_BIN` | 自动探测（桌面版 → npm 全局 → npx 缓存） | 显式指定 `@deepseek-ai/dsh/lib/bin.js` 路径（可指进桌面版 `app.asar` 内部） |
+| `DSH_RUNTIME` | 自动 | 显式指定拉起 DSH 的可执行文件（如一个 Node 24）。配合 `DSH_BIN` 使用，或单独设置时作用于自动发现的 npm 全局 / npx 版 DSH（并按它的 Node 版本重新判定 `engines.node`）；桌面版始终用其自带运行时（asar 只有它读得了）。不设时：桌面版用自带运行时，其余用本服务的 node |
 | `DSH_MCP_PROFILE` | `dsh-mcp`（团队开启时 `dsh-team`） | 驱动用的 DSH profile；显式设置优先 |
 | `DSH_MCP_TEAM` | `0`（关闭） | 团队模式，按需开启。`dsh-any-agent team on` 写设置文件；这里设 `1`/`0` 可覆盖它。开启后使用 `dsh-team` profile，并在 `dsh_send` 前注入"需要时先建团队"的提示；单次关闭用 `dsh_send(team=false)` |
 | `DSH_MCP_SETTINGS` | `$DSH_HOME/.dsh-any-agent/settings.json` | 团队开关的设置文件（`dsh-any-agent team on/off` 写它） |