dsh-any-agent 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -7,6 +7,194 @@ 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
+
+- **`workspace_changed` no longer misses real edits.** The turn snapshot now
+  fingerprints every `git status` entry (status line + per-path size/mtime,
+  with untracked directories expanded recursively), not just the first 40
+  status lines. A file that was already dirty and changed again, or any change
+  past the 40th entry, is detected; `changed_files` and `entries` keep their
+  old meaning (`entries` is still display-truncated to 40).
+- **`gitStatus` is asynchronous.** Turn start/end snapshots now use `execFile`
+  instead of `spawnSync`, so a large repository's `git status` (up to 8 s) no
+  longer blocks the shared MCP event loop, ACP messages, approvals or other
+  conversations. `busy` is still set before any await; turn finalization keeps
+  releasing `busy`, waking interject waiters and scheduling the drain before
+  waiting for git, and only writes the sentinel after the result (including
+  `workspace_changed` and the review ticket) is complete.
+- `--no-optional-locks` is passed as a **global** git option (before the
+  subcommand); previously `git status ... --no-optional-locks` exited 129, so
+  every real snapshot was `null` and `workspace_changed` stayed false.
+- **`dsh_get(max_chars)` now bounds the whole response.** The budget used to
+  apply only to the rendered text while `structured.run.result` kept every
+  tool's full input, so a 77-tool turn came back as ~75K characters and was
+  rejected by Claude Code's per-call limit even with `max_chars=8000`. With
+  `max_chars > 0`, structured is compacted too: the answer is truncated and
+  `tools_used[]` keeps `id/title/name/status/kind` plus `input_chars`
+  (`run.result_compacted: true`). `max_chars=0` (default) is unchanged; the
+  full result is always in the sentinel file.
+- **`dsh_doctor` flags unverified DSH versions and fragile entry points.** A new
+  `dsh_version` check grades the DSH version against the compatibility matrix
+  (`verified` 0.1.7 ≤ v < 0.2.0 → ok; `partial`, `unsupported`, `unverified`
+  such as 0.2.x, or unreadable → warn). `dsh_bin` warns when DSH resolves from
+  an npx cache (`_npx/<hash>/`), which disappears on cache cleanup.
+
+### Added
+
+- **Auto-approved approvals are visible.** Under `on_approval=auto-allow`, every
+  turn result now carries `auto_approvals_total`, `auto_escalations_total`
+  (requests with `sandbox_permissions`, e.g. `danger-full-access`) and up to 20
+  redacted `auto_approvals` summaries (tool, escalation, justification, command
+  preview). The review ticket's evidence and checklist call them out, so a
+  `workspace-write` session that silently escalated no longer looks like it
+  stayed in bounds. Defaults are unchanged; use `on_approval=ask` to gate each.
+- **PowerShell sentinel waiter.** On Windows the background receipt includes a
+  ready-made, quote-escaped `sentinel_wait_powershell` command (also in the
+  text), and the server instructions document it, for hosts where Git Bash is
+  missing or hangs.
+
+### Website
+
+- Playground: step backward, stateful connection-line status, sentinel receipt
+  pulse, and a "try interject" cross-scenario action on dispatch frames.
+- Code snippets now use one-pass syntax highlighting (quoted keys, values,
+  comments and arrows) without nested spans; the Cursor config tab and copy
+  success icon were added; `/en/` HTML is explicitly revalidated.
+- Navigation now surfaces the FAQ; English and Chinese nav order match.
+
+### Documentation
+
+- Fix the profile-creation command in `USAGE-NOTES.md` / `.en.md`: it needs
+  `dsh --profile dsh-mcp --from-default-profile acp`, and 0.5.0+ normally
+  bootstraps the profile automatically.
+- Correct the team-mode profile default in `docs/zh/limits.md` and the
+  architecture diagrams: `dsh-mcp` is default; `dsh-team` is used only when
+  team mode is on.
+- Clarify the website README's Node.js floor (website build ≥ 22; the MCP
+  server itself requires ≥ 22.15).
+
 ## [0.5.1] — 2026-11-04
 
 ### Security
@@ -948,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/DESIGN.md

@@ -252,7 +252,7 @@ Profile = `~/.dsh/profiles/<name>/`，由 `package.json` 的 `dsh.profile.bundle
 
 **B11 设计要点（调用方审核）**
 - **为什么放进返回载荷**：返回值是"另一个 agent 的自述"。调用方最常见的失败模式是直接转述"已完成/已修好"。审核要求必须和结果出现在同一条消息里（`content.text`、`structuredContent`、哨兵 `result.review`），才可能改变调用方的下一步动作；单独一个"记得审核"的约定会被忽略。
-- **审核单形状**：`{review_id, mode, status, run_id, prompt_preview, checklist, evidence, submit:{tool:"dsh_review", arguments}, instructions}`。清单随回合形状变化（有没有改工作区、有没有错误、用了哪些工具）；`evidence` 只放核对所需的最小事实（stop_reason、error、changed_files、工具名）。
+- **审核单形状**：`{review_id, mode, status, run_id, prompt_preview, checklist, evidence, submit:{tool:"dsh_review", arguments}, instructions}`。清单随回合形状变化（有没有改工作区、有没有错误、用了哪些工具）；`evidence` 只放核对所需的最小事实（stop_reason、error、changed_files、工具名）。`workspace_changed` 必须基于**全量**快照指纹（逐路径 size/mtime，未跟踪目录递归），只比前 40 条状态行会把"同一状态行但内容变了"误报成没落地，审核清单也就失去了证据价值。
 - **默认 advisory，不阻塞**：这是刻意的产品选择。强制门禁会打断"审核失败 → 派修复回合"的自然流程，也会破坏既有调用方；advisory 只把审核请求显性化。`review=off` 可按会话/单次派活关闭；即使 off，`dsh_review` 仍可对旧 run 显式补审核。
 - **裁决落盘与回写**：`reviews/<会话id>/<run_id>.review.json` 原子写入（tmp + rename，唯一 tmp 名），含裁决、理由/findings、清单与证据。`submitReview` 依次从内存 run → 哨兵 → 已有审核记录取事实，所以服务重启、run 被挤出内存后仍可审核。提交后 **原子重写哨兵里的 `result.review`**，避免异步调用方下次读文件看到与事实相反的 `pending`。
 - **隐私**：审核单不含思考正文；理由、findings、任务预览、证据**与每个 checklist 项**在落盘前都走 `redact.sanitizeApprovalContext`（与审批上下文同一套规则）——checklist 会拼接 `result.error`，漏掉它就会成为第二个明文泄漏点。审核记录与哨兵共用 `DSH_MCP_SENTINEL_TTL_MS` 的 7 天清理。
@@ -305,7 +305,7 @@ Profile = `~/.dsh/profiles/<name>/`，由 `package.json` 的 `dsh.profile.bundle
 
 | # | 功能 | 说明 |
 |---|---|---|
-| E1 | **返回变更 diff** | 回合结束后返回工作区变更（`workspace/changes` 事件 + `git diff --stat`）。**让调用方 agent 能审阅 DSH 的产出再决定是否接受**——这是"外包工程师"模式的关键 |
+| E1 | **返回工作区变更** | 回合结束后返回 `workspace_changed`（本回合前后 `git status` 的**全量**快照指纹：状态行 + 逐路径 size/mtime，未跟踪目录递归展开）与 `diff_stat`（当前脏文件摘要）。快照走异步子进程，不阻塞共享 MCP 事件循环。**让调用方 agent 能审阅 DSH 的产出再决定是否接受**——这是"外包工程师"模式的关键 |
 | E2 | 计划模式 | 只出计划不落地（`dsh-plan-mode`），调用方批准后再执行 |
 | E3 | 审查模式 | 对既有改动做对抗式审查 |
 | E4 | 接受/回滚 | 会话级 checkpoint（DSH 有 `dsh-session-checkpoint-policy`）配合 git 做回滚 |

package/README.md

@@ -15,7 +15,7 @@
 
 </div>
 
-🧪 0.5.1 offline suite green, including caller review and input-boundary hardening · 🔌 MCP over stdio · 📦 Zero dependencies · 📜 MIT
+🧪 0.5.2 offline suite green, including the workspace-change detection fix and visible auto-approvals · 🔌 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.
 

package/README.zh.md

@@ -15,7 +15,7 @@
 
 </div>
 
-🧪 0.5.1 本机离线套件全绿，含调用方审核与输入边界加固 · 🔌 MCP over stdio · 📦 零依赖 · 📜 MIT
+🧪 0.5.2 本机离线套件全绿，含工作区变化检测修复、自动放行审批可见 · 🔌 MCP over stdio · 📦 零依赖 · 📜 MIT
 
 一个 MCP 服务端，把 DeepSeek Harness 当作**长驻的编码 agent** 来驱动。开个会话、扔个目标，它自己写代码、跑脚本、派子代理；你随时能看、能插话、能回头验收。
 

package/USAGE-NOTES.en.md

@@ -8,7 +8,7 @@ Practical gotchas and trade-offs you *will* hit when letting Claude / Codex driv
 
 ## 1. Setup
 
-**1.1 The profile must exist first.** Otherwise every turn fails with `no adapter registered for provider "xxx"`. This server ships no provider config; it drives `~/.dsh/profiles/dsh-mcp/`. Create it with `dsh dsh-mcp --from-default-profile acp` and fill in your own provider per [`profile-example/cordis.patch.yml`](profile-example/cordis.patch.yml).
+**1.1 The profile must exist first.** Otherwise every turn fails with `no adapter registered for provider "xxx"`. This server ships no provider config; it drives `~/.dsh/profiles/dsh-mcp/`. Create it with `dsh --profile dsh-mcp --from-default-profile acp` and fill in your own provider per [`profile-example/cordis.patch.yml`](profile-example/cordis.patch.yml). On 0.5.0+ the server bootstraps this profile on first start, so the manual command is normally only needed when `DSH_MCP_BOOTSTRAP=0` or the profile is broken.
 
 **1.2 ★ The most common trap: ACP's model does NOT come from `agent-default-model`.** You configure your provider there, yet turns fail with `no API key for provider route "deepseek-official"`. ACP reads the `dsh-acp` plugin's own `config.provider` / `config.model`, which the `acp` bundle hard-codes. You must override the `acp` row:
 
@@ -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.
@@ -130,7 +132,7 @@ Practical gotchas and trade-offs you *will* hit when letting Claude / Codex driv
 1. **Give goals, not commands.** DSH is an agent: say "add tests for this module and make them pass", not "run pytest". It picks tools, plans steps, and spawns subagents on its own.
 2. **One conversation per task** — mixing unrelated work pollutes history and costs more.
 3. **Split long work into dispatch + collect**: `wait=false` → do something else → `dsh_get(run_id)`.
-4. **Review output via workspace changes** — `workspace_changed` is true when the `git status` entry set changed across the turn; `diff_stat` lists the current dirty files (it is not a per-turn diff).
+4. **Review output via workspace changes** — `workspace_changed` compares a **full** `git status` snapshot fingerprint taken before and after the turn (status line plus each dirty/untracked path's size and mtime; untracked directories are expanded recursively), so an already-dirty file that changes again, or a change past the 40th entry, is still detected. `diff_stat` lists the current dirty files (it is not a per-turn diff).
 5. **Review the result, don't just relay it** — every result carries a `review` ticket. Check at least one claim with your own tools (read the changed file, inspect `git diff`, run the relevant test), then record `pass` / `partial` / `fail` with `dsh_review`. Default `advisory` does not block the next send; `fail`/`partial` need a reason, and a failed review is not fed back to DSH automatically.
 6. **Ask for a plan first** if you want to approve before execution (DSH has plan mode).
 7. **Three cost knobs**: lower `reasoning_effort`, keep `reasoning=hide`, release and start fresh.

package/USAGE-NOTES.md

@@ -11,7 +11,7 @@
 ### 1.1 profile 必须先建，否则连不上模型
 - **现象**：所有回合都失败，报 `no adapter registered for provider "xxx"`。
 - **原因**：本服务不自带任何 provider 配置，它驱动的是 `~/.dsh/profiles/dsh-mcp/` 这个 profile。
-- **对策**：`dsh dsh-mcp --from-default-profile acp`，然后照 [`profile-example/cordis.patch.yml`](profile-example/cordis.patch.yml) 填上你自己的 provider。
+- **对策**：`dsh --profile dsh-mcp --from-default-profile acp`，然后照 [`profile-example/cordis.patch.yml`](profile-example/cordis.patch.yml) 填上你自己的 provider。0.5.0+ 首次启动会自动 bootstrap 这个 profile，通常无需手工执行；只有在 `DSH_MCP_BOOTSTRAP=0` 或 profile 损坏时才需要。
 
 ### 1.2 ★ 最常见的坑：ACP 的模型不走 `agent-default-model`
 - **现象**：明明在 `agent-default-model` 里配了自己的 provider，会话却报 `no API key for provider route "deepseek-official"`。
@@ -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`。
+
 ---
 
 ## 七、隐私与日志
@@ -271,7 +278,7 @@
 1. **给它目标，不要给命令**。DSH 是 agent：说"把这个模块的测试补上并跑通"，别说"执行 pytest"。它自己会选工具、分步骤、必要时派子代理。
 2. **一个会话一件事**。别往一个会话里塞互不相关的任务，历史会互相污染且越来越贵。
 3. **长任务拆成"派活 + 验收"**：`wait=false` → 干别的 → `dsh_get(run_id)`。
-4. **要审查产出就用工作区变更**：`workspace_changed` 表示本回合前后 `git status` 的条目集合发生了变化；`diff_stat` 列出当前仍处于改动状态的文件（不是本回合的精确 diff）。
+4. **要审查产出就用工作区变更**：`workspace_changed` 比较的是本回合前后 `git status` 的**全量**快照指纹（状态行 + 每个脏/未跟踪路径的 size/mtime；未跟踪目录会递归展开），所以"回合前已经脏、回合内又被改内容"或"改动落在第 41 条之后"都能识别。`diff_stat` 列出当前仍处于改动状态的文件（不是本回合的精确 diff）。
 5. **审核结果，别直接转述**：每个结果都带 `review` 审核单。用自己的工具核验至少一项关键声明（读改动的文件、看 `git diff`、跑相关测试），再用 `dsh_review` 记录 `pass` / `partial` / `fail`。默认 `advisory` 不阻塞下一次派活；`fail`/`partial` 必须给理由，且审核不通过不会自动回灌给 DSH。
 6. **要它先想清楚再动手**：让它先给方案、你确认后再执行（DSH 有计划模式）。
 7. **省钱的三个旋钮**：`reasoning_effort` 调低、`reasoning` 保持 `hide`、及时 `dsh_release` 并开新会话。

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/architecture.md

@@ -24,9 +24,9 @@ DSH ships two programmable entry points. The `sdk` profile looks simpler, but it
          │ MCP over stdio              │ newline-delimited JSON-RPC (ACP)
          ▼                             ▼
    ┌─────────────┐            ┌──────────────────────────┐
-   │dsh-any-agent│───────────▶│ dsh --profile dsh-team   │  sessions with the same
-   └─────────────┘            │                          │  (cwd, permission) share
-                              └────────────┬─────────────┘  one process (default since 0.5.0)
+   │dsh-any-agent│───────────▶│ dsh --profile dsh-mcp     │  sessions with the same
+   └─────────────┘            │ (dsh-team when team on)   │  (cwd, permission) share
+                              └────────────┬──────────────┘  one process (default since 0.5.0)
                                            │
                               ┌────────────┴─────────────┐
                               │ DSH's own tools          │ files, shell, search,

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,21 +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;
+- `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.
@@ -48,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/security.md

@@ -10,6 +10,8 @@
 
 `on_approval` can be `auto-allow`, `auto-deny`, or `ask` (which exposes a pending approval for `dsh_approval_decide` to adjudicate).
 
+**Under `auto-allow`, `workspace-write` is a soft boundary.** When DSH's sandbox blocks something (e.g. child-process pipes on Windows), DSH asks for `sandbox_permissions: danger-full-access` and `auto-allow` grants it. The default is unchanged, but the grant is **no longer silent**: every turn result carries `auto_approvals_total`, `auto_escalations_total` and up to 20 redacted `auto_approvals` summaries (tool, escalation tier, justification, command preview), and the review ticket's evidence and checklist call out "N auto-approved this turn, M of them escalations". To gate each one, start a conversation with `on_approval=ask`.
+
 **`read-only` is enforced, not merely a default**: it always runs with `auto-deny`; passing `auto-allow` or `ask` for a read-only conversation is rejected at `dsh_start`, and the approval layer refuses any permission request from a read-only conversation. After create/resume the server reads back the session's recorded tier; for read-only it **fails closed** if the projection cache has no permission record within the DSH flush window, rather than relying on the approval layer alone. Without that, a profile `defaultPreset` plus a permissive approval policy could let a write through (found by the adversarial audit).
 
 ## 🧷 Input boundaries