dsh-any-agent 0.3.8 → 0.3.9

package/CHANGELOG.md

@@ -7,7 +7,66 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-Post-0.3.8 hardening.
+Post-0.3.9 hardening.
+
+## [0.3.9] — 2026-11-02
+
+### Security / robustness
+
+- **UTF-8 stream framing is lossless.** MCP and ACP now use a shared
+  `LineDecoder` backed by `StringDecoder`, so a multi-byte Chinese/emoji
+  character split across stream chunks is no longer silently replaced by
+  U+FFFD. Covers both input prompts and DSH output.
+- **Concurrent adoption of the same disk session is deduplicated.** `Hub.get`
+  now shares one in-flight `findSessionHeader`/adoption promise per id and
+  rechecks the registry, preventing two Conversation objects (and the
+  unreachable child/write-lock leak that followed).
+- **`read-only` runtime verification fails closed.** It waits up to ~10s
+  (covering DSH's projection-cache flush window); if no recorded permission is
+  available, the call is refused instead of relying on an approval layer that
+  a danger sandbox may never invoke.
+- **`spawned_at` is reset when the child PID changes.** PID-reuse protection no
+  longer rejects takeover of a legitimate restarted child.
+- **`forget` tombstones survive unreadable session headers.** Header read is
+  three-state (found / missing / error); only a genuinely missing session file
+  prunes a tombstone.
+- **`DSH_MCP_SENTINEL_INCLUDE_REASONING=1` no longer disables redaction.**
+  Thinking is kept, but answer/error/title/tool inputs are still sanitized.
+- **`close`/`releaseAll`/`shutdown` keep lock registrations until the child is
+  confirmed dead.** If stop times out, the registration is retained so
+  takeover can still attribute the orphan; `forget` is refused while the child
+  is alive.
+- setup preserves the target file's mode (e.g. 0600) and rejects an invalid
+  `--permission` with exit code 2.
+- `restore --latest` excludes its own `pre-restore-*` safety copies, so running
+  it twice no longer undoes the first restore.
+
+### Behavior
+
+- `workspace_changed` compares git-status entry snapshots instead of object
+  identity; output now says "workspace state changed" rather than claiming a
+  per-turn file count.
+- `dsh_takeover` prefers a live `known_child_pid` when the marker points at a
+  dead child.
+
+### Website
+
+- Mobile navigation keeps the language switch visible; the footer also carries
+  a language link.
+- `hero.jpg` and `favicon.svg` are content-hashed; all `/assets/*` can stay
+  immutable.
+- Light-theme muted/faint/accent colors were darkened to meet WCAG AA on the
+  surfaces they are used on.
+
+### Docs / tests
+
+- README/Chinese README/USAGE-MIGRATION: workspace-write approval semantics,
+  setup's `workspace-write` default, Zed `context_servers`, English npm publish
+  step, current route/limit links.
+- New `line-decoder` suite (4), expanded sentinel redaction (19), tombstone
+  pruning (10), permission adoption (17), state/lock safety (26), sandbox guard
+  (21), setup (45), config-safety (407). Offline total 843 / 879 with nine
+  client fixtures; website 29.
 
 ## [0.3.8] — 2026-11-02
 
@@ -696,7 +755,8 @@ 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.8...HEAD
+[Unreleased]: https://github.com/xmtlzzz/dsh-any-agent/compare/v0.3.9...HEAD
+[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
 [0.3.6]: https://github.com/xmtlzzz/dsh-any-agent/compare/v0.3.5...v0.3.6

package/DESIGN.md

@@ -2,9 +2,9 @@
 
 > 目标：做一个 MCP Server，让 **Codex / Claude Code** 能调用 **DeepSeek Harness (DSH)** 当"外包工程师"——写代码、搭脚手架、跑任务，并且 DSH 自己还能挂它自己的 MCP。
 >
-> 本文只谈**功能与接口**，不写实现代码；其中 M2/M3 工具（`dsh_rename` 等）是分期计划，不是当前 0.3.8 的缺失功能。技术判断最初基于 DSH 0.1.7-rc.2，当前验证基线是 **DSH 0.2.1-rc.5**（见 §2 证据）。
+> 本文只谈**功能与接口**，不写实现代码；其中 M2/M3 工具（`dsh_rename` 等）是分期计划，不是当前 0.3.9 的缺失功能。技术判断最初基于 DSH 0.1.7-rc.2，当前验证基线是 **DSH 0.2.1-rc.5**（见 §2 证据）。
 
-## 当前实现状态（0.3.8）
+## 当前实现状态（0.3.9）
 
 当前对外暴露 11 个工具，均已实现并有回归：
 
@@ -439,7 +439,7 @@ Profile = `~/.dsh/profiles/<name>/`，由 `package.json` 的 `dsh.profile.bundle
 `dsh_start` / `dsh_send` / `dsh_list` / `dsh_get` / `dsh_release` + 专用 profile 脚手架（provider/model/权限/标题 LLM）+ 思考默认隐藏 + Windows 拉起方式 + 进程池与空闲回收。
 
 **M2（把它变成好用的"外包工程师"）**
-`dsh_diff`、计划模式、`dsh_read` 游标增量、progress/log 通知、审批**报告**（G3，注意不可应答）、脱敏、`dsh_search`（需先开 `session-query-sqlite` 的 `openAt`，默认 `never` 时全文搜索直接报 `SESSION_QUERY_SEARCH_DISABLED`）、resources/prompts。
+`dsh_diff`、计划模式、`dsh_read` 游标增量、progress/log 通知、审批**可应答**（G3 已由 `dsh_approval_decide` 实现）、脱敏、`dsh_search`（需先开 `session-query-sqlite` 的 `openAt`，默认 `never` 时全文搜索直接报 `SESSION_QUERY_SEARCH_DISABLED`）、resources/prompts。
 
 **M3（能力面与体验）**
 MCP 服务器增删查（F2）、插件与技能管理、`dsh_doctor`、分叉/回滚、可选 TUI 伴生进程。
@@ -451,9 +451,9 @@ MCP 服务器增删查（F2）、插件与技能管理、`dsh_doctor`、分叉/
 | # | 问题 | 我的建议 |
 |---|---|---|
 | Q1 | 会话空间：与用户 GUI 共用 `~/.dsh`（历史统一、但会抢写锁）还是独立 `DSH_HOME`（隔离、但要另配凭据）？ | 默认共用，提供 `--dsh-home` 覆盖；MCP 起的会话打标记便于过滤 |
-| Q2 | 空闲回收 TTL 默认值？（太长会占锁让用户打不开，太短会反复重启丢上下文） | 5 分钟，且 `dsh_release` 可显式交还 |
+| Q2 | 空闲回收 TTL 默认值？（太长会占锁让用户打不开，太短会反复重启丢上下文） | ✅ **已定：默认 `0` = 永不回收**（`dsh_release` 可显式交还；显式设非零值才回收） |
 | Q3 | **中断怎么做？** SDK 协议没有 cancel，且杀进程 = 永久失去该会话（约束 6） | 强烈倾向 ②：写个极小 DSH 插件补 `session/interrupt`。① 已排除——headless 无法接管 web 建的会话 |
-| Q4 | 默认权限档给哪一档？ | ✅ **已定：默认 `danger-full-access`，其余可选。** 成因几经变化：SDK 协议没有审批通道时中间档等于废档（越界操作静默失败）；**改用 ACP 后 `session/request_permission` 让中间档复活**，所以现在是"默认最省事 + 需要时可收窄"，而不是被迫只留一档。`read-only` 留给分析不信任样本的场景。注意 `approval.policy: never` 的语义是"每次询问都确定性拒绝"（不是自动放行），它只在 `danger-full-access` 下无副作用——因为沙箱根本不产生询问 |
+| Q4 | 默认权限档给哪一档？ | ✅ **已定：服务端裸默认 `danger-full-access`；`setup` 写入 `workspace-write`；其余可选。** 成因几经变化：SDK 协议没有审批通道时中间档等于废档（越界操作静默失败）；**改用 ACP 后 `session/request_permission` 让中间档复活**，所以现在是"默认最省事 + 需要时可收窄"，而不是被迫只留一档。`read-only` 留给分析不信任样本的场景。注意 `approval.policy: never` 的语义是"每次询问都确定性拒绝"（不是自动放行），它只在 `danger-full-access` 下无副作用——因为沙箱根本不产生询问 |
 | Q5 | 会话 id 是否直接采用 DSH 原生 `session-<uuid>`？ | ✅ 已定：采用。实测语义 = 全新 id 落成磁盘会话 id（磁盘/标题/GUI 全对齐）；已存在的 id 直接报错。故**每个会话只在首次 prompt 生成一次 id，之后仅在本进程内复用** |
 | Q6 | 首版面向 Codex 还是 Claude Code？（两者 MCP 能力不同：progress/log 通知、resources、prompts 支持度有差异） | 先保 Codex 的保守子集（tools 即可），Claude 的增强能力渐进加 |
 | Q7 | 要不要把 `session-title-llm` 打开（每个会话多一次小 LLM 调用换更好的标题）？ | 打开，标题质量对"列表里找对话"影响很大 |
@@ -468,7 +468,7 @@ MCP 服务器增删查（F2）、插件与技能管理、`dsh_doctor`、分叉/
 | 位置 | 内容 |
 |---|---|
 | [`src/`](src) | 实现：ACP 客户端、会话池与注册表、工具层、MCP 服务端、工作区登记 |
-| [`test/`](test) | 可复跑的测试套件（冒烟 / 边界 / 集成 / 异步 / 并发 / 能力 / 工作区有效性 / 验收），合计 229 项检查 |
+| [`test/`](test) | 可复跑的测试套件；当前基线见 README（0.3.9：离线 843 项、官网 29 项，模型套件另计）。本文件是历史设计稿，不再重复抄写计数 |
 | [`README.md`](README.md) / [`README.zh.md`](README.zh.md) | 使用文档（英文 / 中文） |
 | [`profile-example/cordis.patch.yml`](profile-example/cordis.patch.yml) | DSH profile 补丁层模板（含两个必踩的坑的说明） |
 

package/README.md

@@ -15,7 +15,7 @@
 
 </div>
 
-🧪 815 checks green on 0.3.8 on this machine (851 when all nine client fixtures exist); 519 of them are in the client-registration suites (555 with all fixtures) · 🔌 MCP over stdio · 📦 Zero dependencies · 📜 MIT
+🧪 843 checks green on 0.3.9 on this machine (879 when all nine client fixtures exist); 524 of them are in the client-registration suites (560 with all fixtures) · 🔌 MCP over stdio · 📦 Zero dependencies · 📜 MIT
 
 An MCP server that drives DeepSeek Harness as a **long-lived coding agent**. Hand it a goal, let it write code and run scripts, steer it mid-flight, and collect the result when you are ready.
 
@@ -214,7 +214,7 @@ What changed since 0.1.x: JSON configs used to be **re-serialised whole** (value
 
 Codex's `config.toml` gets the same treatment line-wise: your other `[tables]` and their comments, the top-level keys (`model`, `approval_policy`, `sandbox_mode`, …) and CRLF endings come back exactly as they were — `--remove` deletes only the two `[mcp_servers.dsh-any-agent]` sections and leaves the rest intact.
 
-The coverage for each of those claims is in [`test/`](test/) (`test/config-safety.mjs` asserts them one by one, 406 checks).
+The coverage for each of those claims is in [`test/`](test/) (`test/config-safety.mjs` asserts them one by one, 407 checks).
 
 **Checked against a real home, read-only.** Running `setup --json` (plan mode) against an actual developer profile reported all nine clients and left every existing config untouched — identical size, mtime and SHA-256, no `.bak-dsh-*` created, no new file created:
 
@@ -359,7 +359,7 @@ tool_timeout_sec = 120.0
 
 For a local checkout, use `"command": "node"` and `"args": ["/absolute/path/to/server/bin/dsh-any-agent.mjs"]`.
 
-> Cursor, Windsurf, Zed, Cline, Continue and most other clients use this same `mcpServers` shape — if it can launch a stdio MCP server, it works.
+> Cursor, Windsurf, Cline, Continue and most other clients use this same `mcpServers` shape — if it can launch a stdio MCP server, it works. Zed is the exception: it uses `context_servers` (shown above).
 
 </details>
 
@@ -432,7 +432,7 @@ Design notes (especially under **concurrent multi-session** use):
 - **Latch semantics**: the file is written once and kept. Even if the run finishes *before* you arm the waiter, `[ -f ]` is immediately true — you never miss it.
 - **Atomic write**: `tmp` + `rename`; if the file exists its contents are complete. Each run uses its own tmp, so concurrent writes never clobber.
 - **No server push**: the service only answers requests over MCP (it sends no notifications). "Completion notification" is entirely the sentinel file plus your background waiter.
-- **★ No reasoning in the sentinel**: the payload carries the answer, thinking *statistics*, usage and (credential-redacted) tool inputs, but never reasoning text — `result.thinking` is stripped and replaced by a boolean `thinking_omitted` (`true` when reasoning was removed, `false` when there was none), because this server's rule is that reasoning never reaches its own disk artifacts. `dsh_get(run_id)` still returns it from memory while the record lives. `DSH_MCP_SENTINEL_INCLUDE_REASONING=1` breaks that guarantee deliberately. Note that **DSH's own session log does contain reasoning** — see [Logging and privacy](#️-logging-and-privacy).
+- **★ No reasoning in the sentinel**: the payload carries the answer, thinking *statistics*, usage and (credential-redacted) tool inputs, but never reasoning text — `result.thinking` is stripped and replaced by a boolean `thinking_omitted` (`true` when reasoning was removed, `false` when there was none), because this server's rule is that reasoning never reaches its own disk artifacts. `dsh_get(run_id)` still returns it from memory while the record lives. `DSH_MCP_SENTINEL_INCLUDE_REASONING=1` breaks that guarantee deliberately. Note that **DSH's own session log does contain reasoning** — see [Logging and privacy](#-logging-and-privacy).
 
 > Cleanup: sentinels contain full answers, so the service **prunes sentinels older than 7 days at startup** (tune with `DSH_MCP_SENTINEL_TTL_MS`; `0` disables). Your waiter should still `rm` the file after consuming it.
 
@@ -461,13 +461,13 @@ DSH separates reasoning from answer text at the model layer, and ACP exposes the
 
 | Tier | Approval default | Use for |
 |---|---|---|
-| `danger-full-access` (default) | `auto-allow` | Zero friction |
-| `workspace-write` | `auto-allow` | Out-of-workspace operations surface as pending approvals |
+| `danger-full-access` (raw server default) | `auto-allow` | Zero friction; `setup` writes `workspace-write` by default |
+| `workspace-write` | `auto-allow` | Writes are limited to the workspace by DSH's sandbox; out-of-workspace requests are auto-allowed unless you pass `on_approval=ask` |
 | `read-only` | `auto-deny` | Analyzing untrusted samples (malware, unknown dumps) |
 
 `on_approval` can be `auto-allow`, `auto-deny`, or `ask` (which exposes a pending approval for `dsh_approval_decide` to adjudicate).
 
-**`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. Without that, DSH can ask for a `sandbox_permissions` escalation and a permissive approval policy would let the write through (found by the adversarial audit).
+**`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).
 
 ## 🪟 Workspace visibility in the DSH GUI
 
@@ -530,12 +530,12 @@ Silent by default — **not one byte is written**.
 | `DSH_MCP_FORGOTTEN_DIR` | `$DSH_HOME/.dsh-any-agent-forgotten` | Tombstones written by `dsh_release(forget=true)` |
 | `DSH_MCP_RUNS_DIR` | `<state file dir>/runs` | Root for async completion sentinels (`<this>/<conversation_id>/<run_id>.json`) |
 | `DSH_MCP_LOCKS_DIR` | `<state file dir>/locks` | Holder registrations for the write lock. ⚠️ **All instances must agree on this value**, or they cannot see each other's registrations and will misread each other as an unidentifiable holder (a GUI) and refuse to preempt |
-| `DSH_MCP_LOCK_STALE_MS` | `90000` | How long without a heartbeat before a holder counts as lost (and becomes auto-preemptible by `dsh_takeover`) |
+| `DSH_MCP_LOCK_STALE_MS` | `90000` (3× `REAP_INTERVAL_MS`, floor 30 s) | How long without a heartbeat before a holder counts as lost (and becomes auto-preemptible by `dsh_takeover`); changing the reap interval changes the derived default |
 | `DSH_MCP_IDLE_TTL_MS` | `0` (never reap) | How long a conversation may sit idle before its DSH process is reaped. ★★ **`0` means never reap (the default)**: the server keeps holding the write lock, so **the GUI cannot take it** — opening the conversation there is read-only and still works. Cost: one resident DSH process per conversation (**measured 300 MB and 476 MB in two cold starts**). Set a millisecond value (e.g. `300000`) to save memory and accept that the lock can be taken |
 | `DSH_MCP_MAX_LIVE` | `8` (≈2.5–4 GB worst case; see note 8) | ★ **How many conversation processes to keep alive at once** (`0` = unlimited). Going over the cap reaps the **least recently used** one (a running turn is never reaped) — "**bounded memory, locks kept where it matters**". Use `4` when memory is tight, `0` on a big machine. To free idle conversations at once: `dsh_release(all=true)` (busy turns are skipped unless `force=true`) |
 | `DSH_MCP_LIST_PROBE_TTL_MS` | `10000` | Cache lifetime for `dsh_list`'s on-disk probe (the probe spawns a DSH process and takes ~1 s) |
 | `DSH_MCP_SENTINEL_TTL_MS` | `604800000` (7 days) | Startup pruning age for sentinels; `0` disables pruning |
-| `DSH_MCP_SENTINEL_INCLUDE_REASONING` | unset | `1` writes `result.thinking` into the sentinel (**breaks the never-on-disk guarantee**) |
+| `DSH_MCP_SENTINEL_INCLUDE_REASONING` | unset | `1` writes `result.thinking` into the sentinel (**breaks the never-on-disk guarantee**); answer/error/title/tool inputs are still credential-redacted |
 | `DSH_MCP_PERMISSION` | `danger-full-access` | Default tier for `dsh_start` |
 | `DSH_MCP_REASONING_EFFORT` | `max` | Default reasoning effort |
 | `DSH_MCP_PROMPT_TIMEOUT_MS` | `0` (no timeout) | Wait bound for **`wait=true` only**; on expiry the turn merely moves to the background |
@@ -570,18 +570,19 @@ The suite **cleans up after itself**: `run.mjs` always ends with `cleanup.mjs`,
 | `sentinel` | 36 | completion sentinel: atomicity, latch semantics, per-conversation namespacing under concurrency, cancelled runs still land it, and **reasoning never reaching the file** |
 | `prune` | 11 | **sentinel retention**: prunes over-age and crash-leftover files, keeps fresh ones, removes empty shells, `TTL=0` disables pruning, and never touches the conversation registry beside it (no tokens, runs every time) |
 | `guards` | 31 | **environment-variable guards**: odd numbers always land on the safe side — `IDLE_TTL_MS` values like `-1` or garbage mean "never reap" (never give the write lock away), 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) (no tokens, runs every time) |
-| `sandbox-guard` | 18 | **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) |
+| `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` | 27 | **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 |
+| `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) |
-| `sentinel-redaction` | 15 | **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) |
-| `forget-tombstone` | 7 | **`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) |
+| `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) |
+| `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) |
-| `permission-adopt` | 13 | **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` | 21 | **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) |
-| `setup` | 41 | **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` |
+| `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) |
+| `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` | 406 | **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) |
+| `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) |
 | `commit-script` | 26 | commit messages go through stdin, never a temp file that `git add -A` could capture (no tokens) |
 | `roots` | 12 | `dsh_start` without `cwd` asks the client for MCP roots; a client without roots gets an actionable error (no tokens) |
@@ -599,13 +600,13 @@ The suite **cleans up after itself**: `run.mjs` always ends with `cleanup.mjs`,
 | `list` | 13 | **the cost of `dsh_list`** (measured): a default call with the on-disk probe takes ~1 s (it spawns a DSH process) while **repeated calls hit a cache and drop to single-digit milliseconds**; `only_running=true` and `include_closed=false` **skip the probe** with equivalent semantics (unopened on-disk sessions are simply excluded) |
 | `reasoning-check` | 8 | **reasoning visibility**: `reasoning=hide` returns no thinking body but non-zero stats; `reasoning=full` returns the text and the rendered section |
 
-**`node test/run.mjs` runs 815 checks on a machine with five client fixtures (851 with all nine)** — smoke 29 + 786 offline checks (822 with nine). Every suite exited 0 on 0.3.8; none needs a provider (smoke skips its session-creation sections when DSH is absent).
+**`node test/run.mjs` runs 843 checks on a machine with five client fixtures (879 with all nine)** — smoke 29 + 814 offline checks (850 with nine). Every suite exited 0 on 0.3.9; none needs a provider (smoke skips its session-creation sections when DSH is absent).
 
-That is **519 assertions in the client-registration suites alone** (`setup` 41, `removal-scope` 24, `config-safety` 406, `real-configs` 48; 555 with all nine fixtures), which is where the 0.3 work actually is.
+That is **524 assertions in the client-registration suites alone** (`setup` 45, `removal-scope` 24, `config-safety` 407, `real-configs` 48; 560 with all nine fixtures), which is where the 0.3 work actually is.
 
-The model-backed suites (`smoke` 29, `boundary` 46, `integration` 30, `async` 16, `sentinel` 36, `timeout` 38, `lock` 79, `cycle` 36, `concurrency` 31, `capability` 22, `workspace-effect` 24, `acceptance` 36, `multi` 19, `permission` 11, `list` 13, `reasoning-check` 8) total 474 and were last measured in full on 0.3.8 — they need a working provider, so re-run them yourself before trusting a release: `node test/run.mjs --all`. `acceptance` now **skips explicitly** when the DSH profile has no IDA MCP (`mcp__ida__*`).
+The model-backed suites (`smoke` 29, `boundary` 46, `integration` 30, `async` 16, `sentinel` 36, `timeout` 38, `lock` 79, `cycle` 36, `concurrency` 31, `capability` 22, `workspace-effect` 24, `acceptance` 36, `multi` 19, `permission` 11, `list` 13, `reasoning-check` 8) total 474 and were last measured in full on 0.3.9 — they need a working provider, so re-run them yourself before trusting a release: `node test/run.mjs --all`. `acceptance` now **skips explicitly** when the DSH profile has no IDA MCP (`mcp__ida__*`).
 
-> Three different totals are intentional: `node test/run.mjs` (815/851), the CI offline job (786/822, no smoke), and the model-backed set (474 nominal). Counts are the numbers each suite prints itself; don't use one number for a different runner.
+> Three different totals are intentional: `node test/run.mjs` (843/879), the CI offline job (nominal 814/850, no smoke; hosted runners without client fixtures skip real-configs' 48 checks), and the model-backed set (474 nominal). Counts are the numbers each suite prints itself; don't use one number for a different runner.
 
 ### 🧯 Why `sandbox-guard` exists
 
@@ -669,7 +670,7 @@ DSH conversations carry a **cross-process write lock**: **it never expires while
 5. **A conversation that dies before its first successful turn may never have materialized on disk** — resume then fails with a clear error. Safe after the first message.
 6. **No renaming** — DSH's title subsystem has no external rename API (`SessionTitleService.rename` requires a live in-process session). Titles are auto-generated from the first message.
 7. **`session/list` returns only `{sessionId, cwd}` and excludes already-open sessions** — titles are filled in by this server from DSH's projection cache.
-8. **"Never reap" costs memory (measured 300–480 MB per conversation)** — that is what buys "the GUI can never take the write lock". Two fresh-start measurements of one active conversation gave 476 MB and 295 MB of added resident memory (the DSH child plus this server); expect the higher figures on a cold process. Two ways to spend less: ① **`DSH_MCP_MAX_LIVE` (default 8** — over the cap, the least recently used process is reaped → bounded memory, locks still held where it matters); ② set `DSH_MCP_IDLE_TTL_MS` to a millisecond value (at the cost of the lock being takeable). To drop to zero right after a batch of work: **`dsh_release(all=true)`** ✓ (releases idle conversations; busy turns are skipped and keep running — pass `force=true` to interrupt them too. Everything resumes on demand).
+8. **"Never reap" costs memory (measured 300–480 MB per conversation)** — within the `MAX_LIVE` window that is what buys "the GUI cannot take the write lock". Two fresh-start measurements of one active conversation gave 476 MB and 295 MB of added resident memory (the DSH child plus this server); expect the higher figures on a cold process. Two ways to spend less: ① **`DSH_MCP_MAX_LIVE` (default 8** — over the cap, the least recently used process is reaped → bounded memory, locks still held where it matters); ② set `DSH_MCP_IDLE_TTL_MS` to a millisecond value (at the cost of the lock being takeable). To drop to zero right after a batch of work: **`dsh_release(all=true)`** ✓ (releases idle conversations; busy turns are skipped and keep running — pass `force=true` to interrupt them too. Everything resumes on demand).
 
 ## ❓ Why is the profile still called `dsh-mcp`?
 
@@ -705,6 +706,13 @@ npm pack --dry-run
 # 4. Tag and push (wait for CI before publishing).
 git add -A && git commit -m "chore: release x.y.z"
 git tag vx.y.z && git push origin main --tags
+
+# 5. Publish to npm and verify.
+npm publish --access public
+npm view dsh-any-agent version
+# A 404 right after publish is usually propagation, not failure: npm returns
+# 202 and the registry can lag briefly. Confirm the local npm log shows the
+# version before retrying.
 ```
 
 ## Star History

package/README.zh.md

@@ -15,7 +15,7 @@
 
 </div>
 
-🧪 0.3.8 本机 815 项检查全绿（九种客户端配置齐全时 851 项；其中 519 项属于客户端注册器套件，齐全时 555 项） · 🔌 MCP over stdio · 📦 零依赖 · 📜 MIT
+🧪 0.3.9 本机 843 项检查全绿（九种客户端配置齐全时 879 项；其中 524 项属于客户端注册器套件，齐全时 560 项） · 🔌 MCP over stdio · 📦 零依赖 · 📜 MIT
 
 一个 MCP 服务端，把 DeepSeek Harness 当作**长驻的编码 agent** 来驱动。开个会话、扔个目标，它自己写代码、跑脚本、派子代理；你随时能看、能插话、能回头验收。
 
@@ -227,7 +227,7 @@ Zed          33 -> 33 个键   只有 context_servers 多了个子项
 
 Codex 的 `config.toml` 同理，是按行处理的：其它 `[表]` 及其注释、顶层键（`model`、`approval_policy`、`sandbox_mode` 等）、CRLF 行尾都原样保留 —— `--remove` 只删 `[mcp_servers.dsh-any-agent]` 那两段，其余一律不动。
 
-这些断言的详细覆盖见 [`test/`](test/)（`test/config-safety.mjs` 共 406 项，逐条断言上面每一条）。
+这些断言的详细覆盖见 [`test/`](test/)（`test/config-safety.mjs` 共 407 项，逐条断言上面每一条）。
 
 **在真实 home 上做过只读验证。** 用 `setup --json`（纯计划模式）跑一遍开发机上的真实配置：9 个客户端全部报出，而现存的每份配置都**原封未动** —— size、mtime、SHA-256 全同，没有新增任何 `.bak-dsh-*`，也没有新建任何文件：
 
@@ -376,7 +376,7 @@ tool_timeout_sec = 120.0
 
 本地目录安装时改用 `"command": "node"` 和 `"args": ["/绝对路径/server/bin/dsh-any-agent.mjs"]`。
 
-> Cursor、Windsurf、Zed、Cline、Continue 等大部分客户端都吃同一套 `mcpServers` 结构——只要能拉起 stdio MCP 服务，就能用。
+> Cursor、Windsurf、Cline、Continue 等大部分客户端都吃同一套 `mcpServers` 结构——只要能拉起 stdio MCP 服务，就能用。Zed 是例外：它用 `context_servers`（见上方示例）。
 
 </details>
 
@@ -476,13 +476,13 @@ DSH 在模型层就把思考与正文分开，ACP 又把它们做成**两条独
 
 | 档位 | 审批默认 | 用途 |
 |---|---|---|
-| `danger-full-access`（默认） | `auto-allow` | 零摩擦 |
-| `workspace-write` | `auto-allow` | 越界操作会冒泡为待决审批 |
+| `danger-full-access`（服务端裸默认） | `auto-allow` | 零摩擦；`setup` 默认写入 `workspace-write` |
+| `workspace-write` | `auto-allow` | DSH 沙箱限制可写范围；越界请求默认放行，传 `on_approval=ask` 才挂起审批 |
 | `read-only` | `auto-deny` | 分析不信任样本（恶意软件、来路不明 dump） |
 
 `on_approval` 可选 `auto-allow` / `auto-deny` / `ask`（`ask` 会把审批挂起，交给 `dsh_approval_decide` 裁决）。
 
-**`read-only` 是强制边界，不只是默认值**：它固定使用 `auto-deny`；给只读会话传 `auto-allow` / `ask` 会在 `dsh_start` 被直接拒绝，审批层也会拒绝来自只读会话的任何权限请求。否则 DSH 可以请求 `sandbox_permissions` 提权，而宽松的审批策略会把写操作放行（对抗审计实测过）。
+**`read-only` 是强制边界，不只是默认值**：它固定使用 `auto-deny`；给只读会话传 `auto-allow` / `ask` 会在 `dsh_start` 被直接拒绝，审批层也会拒绝来自只读会话的任何权限请求。建会话/resume 后还会回读会话自己记录的权限档；只读档如果在 DSH 投影缓存刷盘窗口内仍读不到记录，会 **fail-closed 拒绝继续**，而不是只依赖审批层兜底。否则 profile 的 `defaultPreset` 加宽松审批策略可能放行写操作（对抗审计实测过）。
 
 ## 🪟 会话在 DSH GUI 里的可见性
 
@@ -545,12 +545,12 @@ node bin/dsh-any-agent-workspaces.mjs --purge-test-sessions   # 删测试会话
 | `DSH_MCP_APPROVAL` | `auto-allow`（非只读档） | 默认审批策略。设成 `ask` 才能让越界请求挂起给 `dsh_approval_decide`，而不是自动放行 |
 | `DSH_MCP_APPROVAL_TIMEOUT_MS` | `300000` | 待决 `ask` 审批的等待上限；超时按拒绝处理 |
 | `DSH_MCP_FORGOTTEN_DIR` | `$DSH_HOME/.dsh-any-agent-forgotten` | `dsh_release(forget=true)` 写的墓碑目录 |
-| `DSH_MCP_LOCK_STALE_MS` | `90000` | 持锁登记多久没续心跳就算"持有者失联"（此时可被 `dsh_takeover` 自动抢占） |
+| `DSH_MCP_LOCK_STALE_MS` | `90000`（3× `REAP_INTERVAL_MS`，下限 30 秒） | 持锁登记多久没续心跳就算"持有者失联"（此时可被 `dsh_takeover` 自动抢占）；改回收间隔会改变推导出的默认值 |
 | `DSH_MCP_IDLE_TTL_MS` | `0`（永不回收） | 会话空闲多久回收其 DSH 进程。★★ **`0` = 永不回收（默认）**：本服务一直握着写锁，**GUI 抢不走**（你在 GUI 里点开是**只读**，照样能看 ✓）。代价：每会话常驻一个 DSH 进程（**两次冷启动实测 476MB / 295MB**）。设成毫秒数（如 `300000`）可省内存，但要接受"锁可能被 GUI 抢走" |
 | `DSH_MCP_MAX_LIVE` | `8`（最坏约 2.5–4GB，见第 8 条） | ★ **最多同时保活几个会话进程**（`0` = 不限）。超标时回收**最久没用过**的（**在跑的回合绝不回收**）—— "**内存有界，锁尽量在手**"。内存紧用 `4`，机器大可以 `0`。用完想立刻放掉空闲会话：`dsh_release(all=true)`（busy 回合默认跳过，`force=true` 才中断） |
 | `DSH_MCP_LIST_PROBE_TTL_MS` | `10000` | `dsh_list` 磁盘探测结果的缓存时长（探测要 spawn 一个 DSH 进程，实测约 1 秒） |
 | `DSH_MCP_SENTINEL_TTL_MS` | `604800000`（7 天） | 启动时清理超过此时长的哨兵；`0` 关闭清理 |
-| `DSH_MCP_SENTINEL_INCLUDE_REASONING` | 未设置 | `1` 会把 `result.thinking` 一并写进哨兵（**打破"思考不落盘"的保证**） |
+| `DSH_MCP_SENTINEL_INCLUDE_REASONING` | 未设置 | `1` 会把 `result.thinking` 一并写进哨兵（**打破"思考不落盘"的保证**）；answer/error/title/工具输入仍会脱敏 |
 | `DSH_MCP_PERMISSION` | `danger-full-access` | `dsh_start` 未指定时的权限档 |
 | `DSH_MCP_REASONING_EFFORT` | `max` | 默认思考深度 |
 | `DSH_MCP_PROMPT_TIMEOUT_MS` | `0`（不设超时） | **仅 `wait=true` 时**的等待上限；到期只转后台，不取消回合 |
@@ -584,18 +584,19 @@ node test/cleanup.mjs      # 单独跑收尾清理（只清测试自己造的目
 | `sentinel` | 36 | 完成哨兵：原子性、闩锁语义、多会话并发不串台、被取消也落地、**思考不进文件** |
 | `prune` | 11 | **哨兵留存**：清超期与崩溃残留、留新、清空壳目录、`TTL=0` 关闭清理、且绝不碰同目录的会话注册表（不花 token，每次必跑） |
 | `guards` | 31 | **环境变量守卫**：奇怪的数值一律压到安全侧 —— `IDLE_TTL_MS` 的 `-1`/非法值都当"永不回收"（绝不主动让出写锁）、回收间隔过小压回默认（防空转紧循环）、**失联阈值下限 30 秒**（防别的实例"合法地"抢占并杀掉我们的回合）（不花 token，每次必跑） |
-| `sandbox-guard` | 18 | **测试沙箱自身**：「临时 HOME」如果落到真实用户目录、它的子目录、盘符根目录，或 OS 临时目录之外，一律报错拒绝，绝不被写入和删除。其余套件都通过 `test/sandbox-home.mjs` 拿目录、只销毁自己建的那个（不花 token，每次必跑） |
+| `sandbox-guard` | 21 | **测试沙箱自身**：「临时 HOME」如果落到真实用户目录、它的子目录、盘符根目录，或 OS 临时目录之外，一律报错拒绝，绝不被写入和删除。其余套件都通过 `test/sandbox-home.mjs` 拿目录、只销毁自己建的那个（不花 token，每次必跑） |
 | `approval-details` | 27 | **审批审查上下文**：待决审批的快照带命令、理由、cwd 与原始审批 ID —— 不只是一个裸 ID，调用方才能真正裁决；缺失的 `rawInput` 会按 ID 从先前的 `tool_call` 更新关联回来；凭据形状的字段与常见内联字面量在结构化上下文和展示标题里都会脱敏；关闭会话会取消待决审批。经真实 stdio MCP 端到端验证 |
 | `read-cursor` | 10 | **`dsh_read` 游标语义**：追加到已读条目里的文本必须再次返回（修订号游标，按 `seq` 替换全文）；`limit` 钳到 1..500，`0`/负数不会空转或丢尾（不花 token） |
-| `sentinel-redaction` | 15 | **哨兵落盘卫生**：`result.thinking` 被剥掉、`thinking_omitted` 始终是布尔值、`answer`/`error`/`title`/`tools_used[].input` 都走与审批相同的凭据脱敏（不花 token） |
-| `forget-tombstone` | 7 | **`forget` 是终态**：`release(forget=true)` 写墓碑，按 id 查询明确失败并给出恢复路径，列表不再展示；删除墓碑后回到常规“未知会话”路径（不花 token） |
+| `line-decoder` | 4 | **UTF-8 行分帧**：MCP/ACP 的 chunk 边界不能把中文/emoji 截成 U+FFFD；覆盖逐字节、任意 chunk、CRLF 与 EOF 残留（不花 token） |
+| `sentinel-redaction` | 19 | **哨兵落盘卫生**：`result.thinking` 被剥掉、`thinking_omitted` 始终是布尔值、`answer`/`error`/`title`/`tools_used[].input` 都走与审批相同的凭据脱敏（不花 token） |
+| `forget-tombstone` | 10 | **`forget` 是终态**：`release(forget=true)` 写墓碑，按 id 查询明确失败并给出恢复路径，列表不再展示；删除墓碑后回到常规“未知会话”路径（不花 token） |
 | `bootstrap-profile` | 24 | **首启 profile 在零依赖发布形态下可用**：内置 YAML 子集解析器复制路由、剥掉 `apiKey`/`headers`/字面密钥、绝不写 `defaultPreset`、幂等；用户手写文件逐字节不动（不花 token） |
 | `workspace-safety` | 23 | **数据丢失边界**：`isTempPath` 按路径分段（`tmpdir()+'Suffix'`、`/tmpfoo` 都不算临时目录）、坏 `workspace.json` 绝不覆盖、会话根不可读时绝不清空 `sessionIds`、自动清理只删测试造的会话（不花 token） |
-| `permission-adopt` | 13 | **不无声提权**：接管没有权限记录的外部会话时 fail-closed 到 `read-only`；记录为 `read-only` 的会话不能被侧车提升；运行期回读记录与请求不一致会失败（不花 token） |
-| `state-safety` | 21 | **状态/哨兵/锁目录**：默认在 `$DSH_HOME/.dsh-any-agent`、不可写时启动明确失败、哨兵写失败返回 `null` + `sentinel_error`、非法数值落安全侧（不花 token） |
-| `setup` | 41 | **注册 CLI**：预览不写盘、`--remove` 只摘自己那条、没装客户端算跳过不算失败、Codex TOML 段往返、以及把写进配置里的命令真的拉起一次并要求应答 `initialize`（不花 token）。**不会调用 `claude mcp get`** —— 那个 CLI 会整体回写 `~/.claude.json` |
+| `permission-adopt` | 17 | **不无声提权**：接管没有权限记录的外部会话时 fail-closed 到 `read-only`；记录为 `read-only` 的会话不能被侧车提升；运行期回读记录与请求不一致会失败（不花 token） |
+| `state-safety` | 26 | **状态/哨兵/锁目录**：默认在 `$DSH_HOME/.dsh-any-agent`、不可写时启动明确失败、哨兵写失败返回 `null` + `sentinel_error`、非法数值落安全侧（不花 token） |
+| `setup` | 45 | **注册 CLI**：预览不写盘、`--remove` 只摘自己那条、没装客户端算跳过不算失败、Codex TOML 段往返、以及把写进配置里的命令真的拉起一次并要求应答 `initialize`（不花 token）。**不会调用 `claude mcp get`** —— 那个 CLI 会整体回写 `~/.claude.json` |
 | `removal-scope` | 24 | **注销只动自己那条**：给一份装着别的 MCP 服务器、顶层 Codex 设置和 Zed 兄弟设置的配置，注册再注销，断言其余每个值逐字节不变；删一个从没写过的东西 = 无写入、无报错（不花 token） |
-| `config-safety` | 406 | **0.3 这条线的核心性质**，逐客户端验证：预览后文件逐字节不变且不产生 `.bak`；注册再注销后其余条目逐字节还原、键顺序不变、顶层键不丢；4 空格 / 2 空格缩进、单行 JSON、无末尾换行、CRLF、UTF-8 BOM 都能在写入后保留；坏 JSON 与只读文件被拒绝且原文件无损；第二次 `--yes` 空跑不新增备份；每个 `.bak-dsh-<时间戳>` 只出现一次且内容等于写入前字节；PATH 上有 `claude` 也绝不调用（不花 token） |
+| `config-safety` | 407 | **0.3 这条线的核心性质**，逐客户端验证：预览后文件逐字节不变且不产生 `.bak`；注册再注销后其余条目逐字节还原、键顺序不变、顶层键不丢；4 空格 / 2 空格缩进、单行 JSON、无末尾换行、CRLF、UTF-8 BOM 都能在写入后保留；坏 JSON 与只读文件被拒绝且原文件无损；第二次 `--yes` 空跑不新增备份；每个 `.bak-dsh-<时间戳>` 只出现一次且内容等于写入前字节；PATH 上有 `claude` 也绝不调用（不花 token） |
 | `real-configs` | 84（7/9 配置时 66，本机 5/9 时 48） | **拿真家伙做往返**：把本机**真实**的客户端配置复制进临时目录（18 万字节、含几百个 `projects` 条目与大小写重复键的 `~/.claude.json`，238 行的 Codex TOML，Zed 的完整 `settings.json`），注册再撤销，要求每个文件**逐字节**还原；条目是否存在按**键**判断而不是裸子串；缺少 fixture 时明确打印 `skipped`，绝不假绿（不花 token） |
 | `commit-script` | 26 | 提交信息走 stdin，绝不落临时文件让 `git add -A` 卷进发布提交（不花 token） |
 | `roots` | 12 | 不传 `cwd` 时通过 MCP roots 取客户端当前项目；不支持 roots 的客户端得到可操作的报错（不花 token） |
@@ -613,13 +614,13 @@ node test/cleanup.mjs      # 单独跑收尾清理（只清测试自己造的目
 | `list` | 13 | **`dsh_list` 的开销**（实测驱动）：含磁盘探测的默认调用约 1 秒（要 spawn 一个 DSH 进程），**连续调用命中缓存降到个位数毫秒**；`only_running=true` 与 `include_closed=false` **跳过探测**且语义等价（不把磁盘上的未打开会话算进来） |
 | `reasoning-check` | 8 | **思考可见性**：`reasoning=hide` 不返回思考正文但统计非零；`reasoning=full` 返回正文且渲染出思考段 |
 
-**`node test/run.mjs` 在本机 5/9 客户端配置时跑 815 项（九种齐全时 851 项）** —— smoke 29 + 离线套件 786 项（九种齐全时 822 项）。0.3.8 上全部退出码 0；都不需要 provider（没有 DSH 时 smoke 自动跳过建会话段）。
+**`node test/run.mjs` 在本机 5/9 客户端配置时跑 843 项（九种齐全时 879 项）** —— smoke 29 + 离线套件 814 项（九种齐全时 850 项）。0.3.9 上全部退出码 0；都不需要 provider（没有 DSH 时 smoke 自动跳过建会话段）。
 
-其中 **519 项属于客户端注册器套件**（`setup` 41、`removal-scope` 24、`config-safety` 406、`real-configs` 48；九种齐全时 555 项）—— 0.3 的活其实都在这里。
+其中 **524 项属于客户端注册器套件**（`setup` 45、`removal-scope` 24、`config-safety` 407、`real-configs` 48；九种齐全时 560 项）—— 0.3 的活其实都在这里。
 
-需要模型的套件（`smoke` 29、`boundary` 46、`integration` 30、`async` 16、`sentinel` 36、`timeout` 38、`lock` 79、`cycle` 36、`concurrency` 31、`capability` 22、`workspace-effect` 24、`acceptance` 36、`multi` 19、`permission` 11、`list` 13、`reasoning-check` 8）合计 474 项，**最近一次完整实测在 0.3.8** —— 它们要可用 provider，发版前请自己重跑一遍：`node test/run.mjs --all`。`acceptance` 在没有 IDA MCP（`mcp__ida__*`）时会明确 **skip**。
+需要模型的套件（`smoke` 29、`boundary` 46、`integration` 30、`async` 16、`sentinel` 36、`timeout` 38、`lock` 79、`cycle` 36、`concurrency` 31、`capability` 22、`workspace-effect` 24、`acceptance` 36、`multi` 19、`permission` 11、`list` 13、`reasoning-check` 8）合计 474 项，**最近一次完整实测在 0.3.9** —— 它们要可用 provider，发版前请自己重跑一遍：`node test/run.mjs --all`。`acceptance` 在没有 IDA MCP（`mcp__ida__*`）时会明确 **skip**。
 
-> 三个总数是刻意分开的：`node test/run.mjs`（815/851）、CI 离线 job（786/822，不含 smoke）、需要模型的集合（名义 474）。数字取各套件自己打印的汇总，不在这里手抄；不要把一个数字套到另一个 runner 上。
+> 三个总数是刻意分开的：`node test/run.mjs`（843/879）、CI 离线 job（名义 814/850，不含 smoke；hosted runner 没有客户端 fixture 时 real-configs 的 48 项会跳过）、需要模型的集合（名义 474）。数字取各套件自己打印的汇总，不在这里手抄；不要把一个数字套到另一个 runner 上。
 
 ### 🧯 为什么会有 `sandbox-guard`
 
@@ -684,7 +685,7 @@ DSH 的会话有**跨进程写锁**：**持有者活着就永不过期，也没
 5. **首次成功回合之前就死掉的会话可能尚未落盘** —— 此时 resume 会报清晰错误。发出第一条消息后就安全了。
 6. **不能改名** —— DSH 的标题子系统没有对外改名接口（`SessionTitleService.rename` 需要进程内的活会话）。标题一律由首条消息自动生成。
 7. **`session/list` 只返回 `{sessionId, cwd}`，且排除已打开的会话** —— 对话名由本服务从 DSH 投影缓存补全。
-8. **默认"永不回收"要花内存（实测 300–480MB/会话）** —— 换来的是"GUI 抢不走写锁"。两次冷启动实测单个活跃会话新增常驻内存分别为 476MB 和 295MB（含 DSH 子进程与本服务），冷进程首次偏高。两种省内存办法：① **`DSH_MCP_MAX_LIVE`（默认 8**，超标就回收最久没用过的 → 内存有界 ✓ 锁仍尽量在手 ✓）；② 把 `DSH_MCP_IDLE_TTL_MS` 设成毫秒数（代价是锁可能被 GUI 拿走）。一批活干完想立刻归零：**`dsh_release(all=true)`** ✓（默认只释放空闲会话，**正在跑的回合会跳过、继续跑**；要连它们一起停掉传 `force=true`。之后照样 resume）。
+8. **默认"永不回收"要花内存（实测 300–480MB/会话）** —— 在 `MAX_LIVE` 窗口内，换来的是"GUI 抢不走写锁"。两次冷启动实测单个活跃会话新增常驻内存分别为 476MB 和 295MB（含 DSH 子进程与本服务），冷进程首次偏高。两种省内存办法：① **`DSH_MCP_MAX_LIVE`（默认 8**，超标就回收最久没用过的 → 内存有界 ✓ 锁仍尽量在手 ✓）；② 把 `DSH_MCP_IDLE_TTL_MS` 设成毫秒数（代价是锁可能被 GUI 拿走）。一批活干完想立刻归零：**`dsh_release(all=true)`** ✓（默认只释放空闲会话，**正在跑的回合会跳过、继续跑**；要连它们一起停掉传 `force=true`。之后照样 resume）。
 
 ## ❓ 为什么 profile 还叫 `dsh-mcp`？
 

package/USAGE-MIGRATION.en.md

@@ -113,8 +113,10 @@ when creating a session if you want `dsh_approval_decide` to adjudicate them.
 
 `read-only` is a hard boundary at this layer: `read-only + auto-allow/ask` is
 rejected, and the server reads back the session's recorded permission tier
-after create/resume. External MCP tools mounted in DSH are outside DSH's
-sandbox; read `USAGE-NOTES.en.md` before using them with untrusted data.
+after create/resume. If the projection cache has no record within the DSH
+flush window, read-only **fails closed** instead of relying on approvals.
+External MCP tools mounted in DSH are outside DSH's sandbox; read
+`USAGE-NOTES.en.md` before using them with untrusted data.
 
 ## 6. Verify
 
@@ -155,6 +157,6 @@ not rewritten by an upgrade; run `dsh-any-agent-setup` again only if you want
 to refresh the entry or permission env. `dsh-any-agent-restore` can restore a
 client config from a `.bak-dsh-*` backup.
 
-For the full Chinese guide, environment-variable reference, write-lock
-measurements and website deployment notes, see `USAGE-MIGRATION.md`,
-`README.md` and `USAGE-NOTES.en.md`.
+For the full Chinese guide, environment-variable reference and write-lock
+measurements, see `USAGE-MIGRATION.md`, `README.md` and `USAGE-NOTES.en.md`.
+Website build/deploy notes live in `website/README.md`.

package/USAGE-MIGRATION.md

@@ -294,13 +294,13 @@ codex mcp list      # 应看到 dsh-any-agent ... enabled
 
 ### 权限档怎么选
 
-`DSH_MCP_PERMISSION` 默认 `danger-full-access`（零摩擦）。建议按用途改：
+服务端未设置 `DSH_MCP_PERMISSION` 时默认 `danger-full-access`；`setup --yes` 默认写入 **`workspace-write`**。建议按用途改：
 
 | 档位 | 适用于 |
 |---|---|
 | `danger-full-access` | 自己的项目，追求速度 |
-| `workspace-write` | **推荐默认**，越界操作会变成待批审批 |
-| `read-only` | 分析不信任的样本（配合 `DSH_MCP_APPROVAL=auto-deny`） |
+| `workspace-write` | **setup 默认**；DSH 沙箱限制可写范围，越界请求默认 auto-allow，传 `on_approval=ask` 才挂起审批 |
+| `read-only` | 分析不信任的样本（强制 `on_approval=auto-deny`） |
 
 `DSH_MCP_APPROVAL` 三选一：`auto-allow` / `auto-deny` / `ask`。
 `ask` 时待决审批会出现在 `dsh_status` 里，用 `dsh_approval_decide` 裁决。

package/USAGE-NOTES.en.md

@@ -52,7 +52,7 @@ Practical gotchas and trade-offs you *will* hit when letting Claude / Codex driv
 
 **3.5 ★ The write lock: one writer per conversation at a time.** A session suddenly stops responding with a vague error (`Internal error`, or "this session is in use") and re-dispatching doesn't help. Cause: a DSH session directory carries a **cross-process write lock** whose semantics are "**the holder keeps it while it lives**", with **no API to take it from a live holder**. This server keeps a DSH process alive per conversation, so the two sides are **mutually exclusive**: while we hold a conversation your own DSH GUI cannot open it, and while your GUI has it open our `session/resume` cannot acquire it. The error is opaque because `SessionAlreadyOwnedError` is not a standard JSON-RPC error — ACP wraps it as a generic `-32603 "Internal error"` and hides the real cause in `error.data` (this server now surfaces and translates it). Fix: read `lock_holder` from `dsh_status` — `stale-mcp` (alive but wedged: its heartbeat expired; a real crash releases the lock automatically) → `dsh_takeover` takes it without `force` and kills that process; `live-mcp` (another live dsh-any-agent instance) → `dsh_release` on that side, or `dsh_takeover(force=true)`; `none` (most likely your GUI has it open) → **never killed by us** — close it in that window and retry.
 
-**3.6 ★ "Taking the lock" means killing the holder, so we must know who that is.** The lock is a Windows named kernel semaphore, released by the kernel when the holder process dies — killing is the *only* way to take it. So this server registers a conversation **only once it actually holds it** (`<state dir>/locks/<conversation id>.json`, with pid + heartbeat). Holders it cannot identify are **never killed**. Why the GUI is untouchable: GUI conversations run inside the single **`dsh web` process** (not one process per conversation), so killing the lock holder would take down your entire UI *and every GUI conversation in that process, including the one you're reading*. Sessions on disk survive resumption, but in-flight turns are lost. **Operational rule: never open a conversation this server drives in your DSH GUI.** To view it there, `dsh_release` first and dispatch again afterwards (it resumes automatically).
+**3.6 ★ "Taking the lock" means killing the holder, so we must know who that is.** The lock is a Windows named kernel semaphore (or POSIX `flock`), released by the OS when the holder process dies — killing is the *only* way to take it. So this server registers a conversation **only once it actually holds it** (`<state dir>/locks/<conversation id>.json`, with pid + heartbeat). Holders it cannot identify are **never killed**. Why the GUI is untouchable: GUI conversations run inside the single **`dsh web` process** (not one process per conversation), so killing the lock holder would take down your entire UI *and every GUI conversation in that process, including the one you're reading*. Sessions on disk survive resumption, but in-flight turns are lost. **Operational rule: never open a conversation this server drives in your DSH GUI.** To view it there, `dsh_release` first and dispatch again afterwards (it resumes automatically).
 
 **3.7 ★ Crash vs. wedge — measured, don't guess.** A **crash** (the MCP is killed or restarted): the DSH children it spawned **exit with it** — their stdio is a pipe to the parent, so closing it gives them EOF and they shut down. **The lock is therefore released automatically; no orphan keeps holding it**, so a restart always gets it back. The cost: **in-flight turns are interrupted and no sentinel lands** (the process is gone) — don't wait for that file, inspect the workspace (`git status`, files) and decide whether to re-dispatch. A **wedge** (the MCP is alive but stalled; no heartbeat for 90 s) is what `stale-mcp` really means, and `dsh_takeover` handles it **without `force`**. Judge with `dsh_status`'s `lock_holder` — and note that `none` does not mean "the lock is free"; it can also mean "a process we don't manage holds it" (usually the GUI).
 
@@ -68,9 +68,9 @@ Practical gotchas and trade-offs you *will* hit when letting Claude / Codex driv
 
 ## 4. Permissions and safety
 
-**4.1 The default is full access.** DSH can touch anything your account can. That default exists because, unattended, ACP's approval channel tends to degrade into silent failures. For untrusted material (malware, unknown dumps, unfamiliar repos) use `permission: "read-only"`.
+**4.1 The raw server default is full access; `setup` writes `workspace-write`.** With no `DSH_MCP_PERMISSION`, DSH can touch anything your account can. That default exists because, unattended, ACP's approval channel tends to degrade into silent failures. `dsh-any-agent-setup --yes` writes `workspace-write` into the client config unless you pass `--permission`. For untrusted material (malware, unknown dumps, unfamiliar repos) use `permission: "read-only"`.
 
-**4.2 `approval: never` means "deterministically reject", not "auto-allow".** It has no downside under `danger-full-access` only because the sandbox stops producing asks. To let the caller adjudicate escalation, use `workspace-write` + `on_approval: "ask"` + `dsh_approval_decide`.
+**4.2 The public approval policy is `on_approval` (`auto-allow` / `auto-deny` / `ask`).** DSH's internal `approval: never` corresponds to `auto-deny`: it deterministically rejects prompts, it does not auto-allow. Under `danger-full-access` the sandbox produces no asks, so the distinction is invisible. To let the caller adjudicate escalation, use `workspace-write` + `on_approval: "ask"` + `dsh_approval_decide`.
 
 **4.3 ★ Side effects of *external MCP tools* are NOT covered by DSH's sandbox.** DSH's permission tiers govern DSH's own file and shell tools. Tools from an MCP server mounted into DSH (e.g. IDA Pro's `patch` / `rename` / `set_comments`) execute **inside that MCP server**, where DSH's tier has no effect. For read-only work, forbid write-class tools **in the prompt** and verify afterwards that `tools_used` contains none. Do not rely on `permission` alone.
 
@@ -130,7 +130,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` / `diff_stat` tell you which files it touched.
+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).
 5. **Ask for a plan first** if you want to approve before execution (DSH has plan mode).
 6. **Three cost knobs**: lower `reasoning_effort`, keep `reasoning=hide`, release and start fresh.
 7. **Don't paste large code blocks into the prompt** — tell it which file to read instead; DSH has its own file tools.

package/USAGE-NOTES.md

@@ -70,7 +70,7 @@
 - **对策**：用 `wait=false` 时**直接靠完成哨兵文件收活**（它自带结果、不受内存窗口限制、还扛服务重启）；否则当场落盘，或用 `dsh_read` 把输出缓冲拉干（同样是内存、有界 500 条）。
 
 ### 2.6 哨兵文件会占磁盘
-- **现象**：`.state/runs/<会话id>/` 下文件越攒越多，每个都含完整正文。
+- **现象**：`$DSH_HOME/.dsh-any-agent/runs/<conversation_id>/` 下文件越攒越多，每个都含完整正文。
 - **原因**：哨兵是**闩锁**——写一次并保留，晚到的等待方才能不漏，所以它不会自己消失。
 - **对策**：服务**启动时会清掉超过 7 天的**（`DSH_MCP_SENTINEL_TTL_MS` 调，`0` 关闭）。等待任务消费后顺手 `rm` 更干净。哨兵**不含思考内容**（`result.thinking` 被剥掉，并始终给出布尔 `thinking_omitted`）；它还会包含用量与**已按审批规则脱敏的工具输入**，仍应按敏感文件对待。
 
@@ -86,7 +86,7 @@
 ### 3.2 默认**不回收**空闲进程；显式设置 TTL 才回收
 - **现象**：`dsh_status` 显示 `detached`（没有附着进程）。
 - **原因**：默认 `DSH_MCP_IDLE_TTL_MS=0` = 永不回收，本服务一直握着写锁。显式设成毫秒数（如 `300000`）才会按 TTL 回收。**`detached` 不是错误** —— 会话本体在磁盘上，下次派活会自动 `session/resume` 复活，历史完整。
-- **对策**：不用管。想让它一直热着就调大 `DSH_MCP_IDLE_TTL_MS`，或者定期 `dsh_status`（会刷新 `lastUsedAt` 吗？不会——只有派活算使用。所以真要常驻就调 TTL）。
+- **对策**：默认 `0` 已经就是“一直热着、永不回收”；只有你显式把 `DSH_MCP_IDLE_TTL_MS` 设成非零，才会按 TTL 回收。
 
 ### 3.3 同一个会话别在两处同时打开
 - **现象**：你自己的 DSH GUI 打不开某个会话，或者对方报被占用。
@@ -112,7 +112,7 @@
   - `none`（多半是你自己的 GUI 开着它）→ **本服务绝不杀**，请在那个窗口里关掉该会话后重试。
 
 ### 3.6 ★ "抢锁" = 杀掉持有者，所以必须先知道那是谁
-- **原因**：锁是 Windows 命名内核信号量，持有者进程一死内核就释放 —— 这是**唯一**的夺锁手段。
+- **原因**：Windows 上是命名内核信号量，POSIX 上是 `flock`；持有者进程一死，系统就释放 —— 这是**唯一**的夺锁手段。
 - **所以**本服务只登记**自己的子进程在真正拿到锁之后**的持有状态（`<状态目录>/locks/<会话id>.json`，含 pid + 心跳）。判定不了的持有者**一律不杀**。
 - **为什么对 GUI 绝不杀**：GUI 的会话跑在 **`dsh web` 那一个进程里**（不是一会话一进程）。杀掉占锁的它 = 整个界面 + **该进程里所有 GUI 会话（含你正在看的那个）一起断**。磁盘上的会话能 resume，但进行中的回合会丢。
 - **操作铁律**：本服务驱动的会话**不要在 GUI 里打开**。要用 GUI 看，先 `dsh_release` 交还；看完再重派（会自动 resume）。
@@ -177,14 +177,14 @@
 
 ## 四、权限与安全（认真看）
 
-### 4.1 默认是"完全权限"
-- **现象**：DSH 能碰你账户能碰的任何东西。
-- **原因**：默认 `danger-full-access` —— 这是为了零摩擦，因为**ACP 的审批通道在无人值守时很容易变成"静默失败"**。
+### 4.1 服务端裸默认是"完全权限"；setup 写入 `workspace-write`
+- **现象**：未设置 `DSH_MCP_PERMISSION` 时，DSH 能碰你账户能碰的任何东西。
+- **原因**：服务端裸默认 `danger-full-access` —— 这是为了零摩擦，因为**ACP 的审批通道在无人值守时很容易变成"静默失败"**。`dsh-any-agent-setup --yes` 默认会把 `workspace-write` 写进客户端配置（除非显式传 `--permission`）。
 - **对策**：分析不信任的东西（恶意软件、来路不明的 dump、陌生仓库）时，用 `permission: "read-only"`（沙箱只读 + 审批一律拒绝）。
 
-### 4.2 `approval: never` 的语义是"确定性拒绝"，不是"自动放行"
+### 4.2 公开审批参数是 `on_approval`；DSH 内部 `approval: never` 对应 `auto-deny`
 - **现象**：以为关掉审批就万事大吉，结果某些操作还是失败。
-- **原因**：`never` = 每次询问都返回拒绝。它之所以在 `danger-full-access` 下没副作用，是因为沙箱根本不产生询问。
+- **原因**：DSH 内部的 `approval: never` = 每次询问都返回拒绝（确定性拒绝），不是自动放行；公开参数应写 `on_approval: "auto-deny"`。它在 `danger-full-access` 下没有副作用，是因为沙箱根本不产生询问。
 - **对策**：需要"越界操作由调用方裁决"时，用 `permission: "workspace-write"` + `on_approval: "ask"`，再用 `dsh_approval_decide` 裁决。
 
 ### 4.3 ★ MCP 工具的副作用**不受** DSH 沙箱约束
@@ -271,7 +271,7 @@
 1. **给它目标，不要给命令**。DSH 是 agent：说"把这个模块的测试补上并跑通"，别说"执行 pytest"。它自己会选工具、分步骤、必要时派子代理。
 2. **一个会话一件事**。别往一个会话里塞互不相关的任务，历史会互相污染且越来越贵。
 3. **长任务拆成"派活 + 验收"**：`wait=false` → 干别的 → `dsh_get(run_id)`。
-4. **要审查产出就用工作区变更**：返回值里的 `workspace_changed` / `diff_stat` 告诉你它动了哪些文件。
+4. **要审查产出就用工作区变更**：`workspace_changed` 表示本回合前后 `git status` 的条目集合发生了变化；`diff_stat` 列出当前仍处于改动状态的文件（不是本回合的精确 diff）。
 5. **要它先想清楚再动手**：让它先给方案、你确认后再执行（DSH 有计划模式）。
 6. **省钱的三个旋钮**：`reasoning_effort` 调低、`reasoning` 保持 `hide`、及时 `dsh_release` 并开新会话。
 7. **别在提示词里重复贴大段代码**——告诉它去看哪个文件更划算（DSH 自己有文件工具）。

package/bin/restore.mjs

@@ -108,9 +108,13 @@ if (wantFile) {
     process.exit(1);
   }
 } else {
-  // 每个文件只取最新的一份。
+  // 每个文件只取最新的一份；但排除本工具自己写的 pre-restore 安全副本，
+  // 否则连续两次 --latest 会把上一次还原再撤回去。
   const byTarget = new Map();
-  for (const b of all) if (!byTarget.has(b.target)) byTarget.set(b.target, b);
+  for (const b of all) {
+    if (b.stamp.startsWith('pre-restore-')) continue;
+    if (!byTarget.has(b.target)) byTarget.set(b.target, b);
+  }
   chosen = [...byTarget.values()];
 }
 

package/bin/setup.mjs

@@ -38,6 +38,7 @@ import {
   planClient,
   resolveDirs,
 } from '../src/clients.mjs';
+import { PERMISSION_TIERS } from '../src/config.mjs';
 
 /** 版本号以 package.json 为准，避免 npm version 之后这里变旧。 */
 const VERSION = (() => {
@@ -115,6 +116,11 @@ const tick = (s) => log('  OK   ' + s);
 const dash = (s) => log('  ---  ' + s);
 const bang = (s) => log('  FAIL ' + s);
 
+if (!PERMISSION_TIERS.includes(PERMISSION)) {
+  log(`--permission 必须是 ${PERMISSION_TIERS.join(' | ')} 之一；收到: ${JSON.stringify(PERMISSION)}`);
+  process.exit(2);
+}
+
 // ── 主流程 ─────────────────────────────────────────────────────────
 
 const dirs = resolveDirs(HOME_OVERRIDE);

package/package.json

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

package/src/acp.mjs

@@ -12,6 +12,7 @@
 import { spawn } from 'node:child_process';
 import { ensureProfile } from './bootstrap.mjs';
 import { DSH_PROFILE, PKG_VERSION, REQUEST_TIMEOUT_MS, resolveDshBin } from './config.mjs';
+import { LineDecoder } from './line-decoder.mjs';
 
 /** ACP 协议版本（@agentclientprotocol/sdk 的 v1）。 */
 const PROTOCOL_VERSION = 1;
@@ -25,7 +26,8 @@ export class AcpProcess {
   #child = null;
   #nextId = 1;
   #pending = new Map();
-  #buf = '';
+  #lineDecoder = new LineDecoder();
+  #errDecoder = new LineDecoder();
   #stderrTail = [];
   #stopping = false;
   #log = NOOP_LOG;
@@ -100,7 +102,7 @@ export class AcpProcess {
     this.#child.stdout.on('error', streamError);
     this.#child.stderr.on('error', streamError);
     this.#child.stderr.on('data', (d) => {
-      for (const line of d.toString('utf8').split(/\r?\n/)) {
+      for (const line of this.#errDecoder.push(d)) {
         if (!line.trim()) continue;
         this.#stderrTail.push(line.trim());
         if (this.#stderrTail.length > STDERR_TAIL_LINES) this.#stderrTail.shift();
@@ -124,11 +126,7 @@ export class AcpProcess {
   }
 
   #onData(chunk) {
-    this.#buf += chunk.toString('utf8');
-    let idx;
-    while ((idx = this.#buf.indexOf('\n')) !== -1) {
-      const line = this.#buf.slice(0, idx);
-      this.#buf = this.#buf.slice(idx + 1);
+    for (const line of this.#lineDecoder.push(chunk)) {
       if (!line.trim()) continue;
       let msg;
       try {
@@ -258,7 +256,7 @@ export class AcpProcess {
   /** 优雅收尾：close 由调用方负责，这里只关 stdin（DSH 绑定 stdin EOF → 有界退出）。 */
   async stop({ graceMs = 3000, killWaitMs = 5000 } = {}) {
     const child = this.#child;
-    if (!child) return;
+    if (!child) return true;
     this.#stopping = true;
     try {
       child.stdin.end();
@@ -273,7 +271,7 @@ export class AcpProcess {
         });
       });
     // 1) 先给它体面退出的机会（stdin EOF → DSH 有界退出）
-    if (await waitExit(graceMs)) return;
+    if (await waitExit(graceMs)) return true;
     // 2) 超时则强杀，**并且等它真的退出**。
     //    ★ 旧实现 kill() 之后立刻 resolve —— 于是调用方会在"子进程还活着、还握着写锁"
     //      的时候继续往下走：删掉登记、再 spawn 新进程去 resume，就会撞上一个**无法归因的锁**
@@ -282,6 +280,6 @@ export class AcpProcess {
     try {
       child.kill();
     } catch {}
-    await waitExit(killWaitMs);
+    return await waitExit(killWaitMs);
   }
 }

package/src/clients.mjs

@@ -89,11 +89,22 @@ export function pruneBackups(file) {
  * 任何一步失败都必须删掉临时文件 —— 曾经有版本在 rename 失败后
  * 把 mcp.json.tmp-dsh-<pid> 留在了客户端目录里。
  */
-export function atomicWrite(file, text) {
+export function atomicWrite(file, text, { mode } = {}) {
+  // 尽量保留原文件权限：POSIX 上 0600 的客户端配置不能因为一次 setup 变成 0644。
+  let originalMode = mode;
+  if (originalMode === undefined) {
+    try { originalMode = statSync(file).mode; } catch { originalMode = null; }
+  }
   const tmp = file + '.tmp-dsh-' + process.pid + '-' + Math.random().toString(36).slice(2, 8);
   try {
-    writeFileSync(tmp, text, 'utf8');
+    writeFileSync(tmp, text, {
+      encoding: 'utf8',
+      ...(originalMode === null ? {} : { mode: originalMode & 0o7777 }),
+    });
     renameSync(tmp, file);
+    if (originalMode !== null) {
+      try { chmodSync(file, originalMode & 0o7777); } catch { /* 尽力而为 */ }
+    }
   } catch (e) {
     try { if (existsSync(tmp)) unlinkSync(tmp); } catch { /* 尽力而为 */ }
     throw e;

package/src/hub.mjs

@@ -51,7 +51,7 @@ import {
 } from './config.mjs';
 import { AcpProcess } from './acp.mjs';
 import { readConversationMeta } from './titles.mjs';
-import { registerWorkspace, findSessionHeader } from './workspace.mjs';
+import { registerWorkspace, findSessionHeaderStatus } from './workspace.mjs';
 import {
   LOCKS_DIR,
   classifyHolder,
@@ -134,7 +134,7 @@ function isForgotten(id) {
  * 留着只会让测试/临时会话在 `$DSH_HOME/.dsh-any-agent-forgotten` 里堆积。
  * 会话文件还在的墓碑必须保留 —— 那正是 forget 的效力所在。
  */
-async function pruneStaleTombstones() {
+async function pruneStaleTombstones(log = NOOP_LOG) {
   let removed = 0;
   try {
     if (!existsSync(FORGOTTEN_DIR)) return 0;
@@ -142,7 +142,13 @@ async function pruneStaleTombstones() {
       if (!f.endsWith('.json')) continue;
       const id = f.slice(0, -5);
       // 异步读会话头：启动路径不能被大日志的同步解压卡住。
-      if (await findSessionHeader(id)) continue;
+      // ★ 只有确认会话文件不存在时才删墓碑；读超时/损坏时保留，
+      //   否则一次慢盘/挂载异常就会让 forget 失效。
+      const found = await findSessionHeaderStatus(id);
+      if (found.status === 'found' || found.status === 'error') {
+        if (found.status === 'error') log.info(`[hub] 墓碑 ${id} 暂不清理：${found.reason}`);
+        continue;
+      }
       try {
         rmSync(join(FORGOTTEN_DIR, f), { force: true });
         removed++;
@@ -247,8 +253,9 @@ async function applySessionConfig(proc, sessionId, cfg) {
  */
 export function sanitizeResultForSentinel(result) {
   if (!result || typeof result !== 'object') return result ?? null;
-  if (SENTINEL_INCLUDE_REASONING) return result;
   const { thinking, ...rest } = result;
+  // ★ 即使 DSH_MCP_SENTINEL_INCLUDE_REASONING=1，也只额外保留 thinking；
+  //   answer/error/title/tools_used 仍然必须脱敏（以前这个开关会跳过整段清洗）。
   // 正文/错误/标题同样可能夹带密钥；哨兵是落盘副本，统一套脱敏。
   for (const key of ['answer', 'error', 'title']) {
     if (typeof rest[key] === 'string') rest[key] = sanitizeApprovalContext(rest[key], key);
@@ -264,7 +271,9 @@ export function sanitizeResultForSentinel(result) {
     });
   }
   // 始终给出布尔值：调用方才能区分“思考被剥离”与“本来没有思考”。
-  return { ...rest, thinking_omitted: Boolean(thinking) };
+  const out = { ...rest, thinking_omitted: Boolean(thinking) && !SENTINEL_INCLUDE_REASONING };
+  if (SENTINEL_INCLUDE_REASONING && thinking !== undefined) out.thinking = thinking;
+  return out;
 }
 
 export class Conversation {
@@ -462,9 +471,10 @@ export class Conversation {
       //   当成持锁者（表现为"上一代子进程还活着并握着锁"），于是每次失败都误报锁冲突 ——
       //   更糟的是旧代码没有 lastChildPid 兜底，会把这种自伤报成"多半是你自己的 GUI"，
       //   而 dsh_takeover 对 none 又拒绝接管，会话就卡住了（test/cycle.mjs 实测抓到）。
-      await proc.stop().catch(() => {});
-      // 只删**自己的**登记（removeMarker 会校验 token）；别人的登记必须留着当线索
-      removeMarker(this.id);
+      const stopped = await proc.stop().catch(() => false);
+      // 只删**自己的**登记（removeMarker 会校验 token）；进程没确认退出时保留登记，
+      // 让 classifyHolder/takeover 仍能归因。
+      if (stopped) removeMarker(this.id);
       // 写锁冲突是最常见也最需要"说人话"的失败：DSH 的 SessionAlreadyOwnedError 会被
       // ACP 包成 -32603 "Internal error"，只说这句调用方根本不知道该怎么办。
       if (isLeaseError(e.message)) {
@@ -500,11 +510,14 @@ export class Conversation {
    *
    * 为什么不能只信入参：DSH profile 里的 `permission.defaultPreset` 会在
    * session/new 时覆盖 `DSH_PERMISSION_MODE`（test/permission.mjs 实测抓到过
-   * read-only 被静默提升）。投影缓存可能稍后才刷盘，所以短轮询；读不到时
-   * 不阻断（read-only 仍有审批层的硬拒绝兜底），但读到不一致就立刻失败。
+   * read-only 被静默提升）。投影缓存可能稍后才刷盘；read-only 必须 fail-closed：
+   * 等待至少一个刷盘周期，仍读不到就拒绝继续，不能依赖“审批层兜底”
+   * （danger sandbox 下根本不会产生审批请求）。
    */
-  async verifyPermissionRecorded({ attempts = 6, delayMs = 250 } = {}) {
-    for (let i = 0; i < attempts; i++) {
+  async verifyPermissionRecorded({ attempts, delayMs = 250 } = {}) {
+    // read-only 需要覆盖 DSH 约 5 秒的投影缓存刷新周期；其它档位保持较短等待。
+    const tries = Number.isFinite(attempts) ? attempts : this.permission === 'read-only' ? 40 : 6;
+    for (let i = 0; i < tries; i++) {
       const meta = readConversationMeta(this.id);
       const recorded = meta?.permissions?.preset;
       if (recorded) {
@@ -519,11 +532,18 @@ export class Conversation {
         this.permissionVerified = true;
         return recorded;
       }
-      if (i < attempts - 1) await new Promise((r) => setTimeout(r, delayMs));
+      if (i < tries - 1) await new Promise((r) => setTimeout(r, delayMs));
     }
     this.permissionVerified = false;
+    if (this.permission === 'read-only') {
+      throw new Error(
+        `无法在 ${(tries * delayMs) / 1000}s 内确认会话实际为 read-only（投影缓存无权限记录）。\n` +
+          '  为避免 profile 的 defaultPreset 把只读会话静默提升为完全访问，本次调用已拒绝。\n' +
+          '  请确认 DSH 会话存储可读，或稍后重试；非只读档位不受此限制。',
+      );
+    }
     this.#hub.log.info(
-      `[conv ${this.id}] 投影缓存里暂时没有权限记录，跳过运行期核对（read-only 仍由审批层强制拒绝）`,
+      `[conv ${this.id}] 投影缓存里暂时没有权限记录，跳过运行期核对（非只读档）`,
     );
     return null;
   }
@@ -565,7 +585,8 @@ export class Conversation {
     report.holder_kind = holder.kind;
     report.holder = holder.marker;
     // 登记可能已随回收被删，但"我们自己的残留子进程"仍可归因（见 locks.classifyHolder）
-    const killTarget = holder.marker?.child_pid ?? holder.known_child_pid ?? null;
+    const markerChild = holder.marker?.child_pid ?? null;
+    const killTarget = isPidAlive(markerChild) ? markerChild : (holder.known_child_pid ?? markerChild);
 
     if (holder.kind === 'none' || !holder.childAlive) {
       report.message =
@@ -857,7 +878,7 @@ export class Conversation {
           },
           tools_used: [...c.tools.values()],
           usage: c.usage,
-          workspace_changed: before !== after,
+          workspace_changed: !sameWorkspaceSnapshot(before, after),
           diff_stat: after,
           elapsed_ms: now() - t0,
         };
@@ -1092,11 +1113,12 @@ export class Conversation {
   async close({ forget = false } = {}) {
     const proc = this.proc;
     this.proc = null;
+    let stopped = true;
     if (proc?.alive) {
       try {
         await proc.request('session/close', { sessionId: this.id }, 10_000);
       } catch {}
-      await proc.stop();
+      stopped = await proc.stop().catch(() => false);
     }
     // 回合已经结束/进程正在关闭，任何仍挂着的审批都不再可裁决。
     for (const [, p] of this.pendingApprovals) {
@@ -1105,18 +1127,32 @@ export class Conversation {
       } catch {}
     }
     this.pendingApprovals.clear();
-    // 进程没了 → 写锁也释放了，登记必须跟着删（否则会把"孤儿持有者"误报给抢占逻辑）
-    removeMarker(this.id);
+    // 只有确认进程退出后才删登记；否则把登记留着，让 takeover/classifyHolder
+    // 还能把这个仍握着写锁的孤儿归因出来。
+    if (stopped) removeMarker(this.id);
+    else {
+      this.#hub.log.info(`[conv ${this.id}] 进程未能确认退出，保留写锁登记以便后续归因`);
+      // 进程还活着时不能 forget：墓碑会让按 id 查询直接失败，而活着的进程
+      // 仍握着写锁，之后连 takeover 都无法归因/接管。
+      if (forget) return { closed: false, forgotten: false, error: '进程未能确认退出，拒绝 forget' };
+    }
     if (forget) {
       // 先写墓碑再从注册表移除：之后按 id 查询会明确报"已 forget"，
       // 而不是从 DSH 会话存储把它重建回来（否则 forget 形同虚设）。
       writeTombstone(this.id);
       this.#hub.remove(this.id);
     } else this.#hub.save();
-    return { closed: true, forgotten: forget };
+    return { closed: stopped, forgotten: forget, ...(stopped ? {} : { error: '进程未能确认退出，登记已保留' }) };
   }
 }
 
+/** 两次 git status 快照是否表示同一组工作区变更。 */
+export function sameWorkspaceSnapshot(a, b) {
+  if (!a && !b) return true;
+  if (!a || !b) return false;
+  return JSON.stringify(a.entries ?? []) === JSON.stringify(b.entries ?? []);
+}
+
 /** 收集当前工作区的 git 变更摘要（非 git 目录返回 null）。 */
 export function gitStatus(cwd) {
   if (process.env.DSH_MCP_GIT_STATUS === '0') return null;
@@ -1207,6 +1243,8 @@ export class Hub {
   }
 
   #reaper;
+  /** 同一 id 的磁盘接管 in-flight Promise，防止并发请求各自构造一个 Conversation。 */
+  #adopting = new Map();
   /** `dsh_list` 磁盘探测的短缓存（探测要 spawn 一个 DSH 进程，实测约 1 秒）。 */
   #probeCache = null;
 
@@ -1235,7 +1273,7 @@ export class Hub {
       }
     }
 
-    const stale = await pruneStaleTombstones();
+    const stale = await pruneStaleTombstones(this.log);
     if (stale) this.log.info(`[hub] 清理 ${stale} 个失效的 forget 墓碑`);
     if (!existsSync(STATE_FILE)) return;
     try {
@@ -1390,10 +1428,26 @@ export class Hub {
       this.adoptNewFromDisk();
       c = this.conversations.get(id);
     }
+    if (!c) {
+      // 同一个磁盘态会话的并发查询共用一次 adopt，避免各自构造 Conversation。
+      const inflight = this.#adopting.get(id);
+      if (inflight) {
+        await inflight;
+        c = this.conversations.get(id);
+      }
+    }
     if (!c) {
       // 最后一道：注册表里没有，但会话可能就在磁盘上 —— 别的实例建的、注册表被并发写覆盖丢的、
       // 或者根本是别的 profile / GUI 建的。**会话存储才是权威，注册表只是缓存。**
-      const header = await findSessionHeader(id);
+      let release;
+      const gate = new Promise((resolve) => { release = resolve; });
+      this.#adopting.set(id, gate);
+      try {
+      const found = await findSessionHeaderStatus(id);
+      if (found.status === 'error') {
+        throw new Error(`无法读取会话 ${id} 的会话头：${found.reason}`);
+      }
+      const header = found.header;
       if (header?.cwd) {
         // ★ 权限档必须取自**会话自己的记录**，不能一律套默认值：
         //   一个当初用 read-only 建的会话，若注册表丢了、被我们以默认档接管，
@@ -1442,6 +1496,10 @@ export class Hub {
         this.save();
         this.log.info(`[hub] 从会话存储吸收了 ${id}（注册表里没有，但磁盘上有；权限档沿用 ${permission}）`);
       }
+      } finally {
+        this.#adopting.delete(id);
+        release();
+      }
     }
     if (!c) {
       throw new Error(
@@ -1593,8 +1651,8 @@ export class Hub {
       // 失败路径也要清掉写锁登记：session/new 可能已经成功、登记已写入，
       // 但会话最终没有注册（例如无效 provider/model 被 fail-fast）。留下 marker
       // 会被 dsh_list/dsh_takeover 误报成“孤儿持有者”，也会在 locks 目录里积垃圾。
-      if (createdSessionId) removeMarker(createdSessionId);
-      await proc.stop().catch(() => {});
+      const stopped = await proc.stop().catch(() => false);
+      if (createdSessionId && stopped) removeMarker(createdSessionId);
       throw e;
     }
   }
@@ -1732,8 +1790,8 @@ export class Hub {
           // ★ 顺序要紧：**先确认子进程真的退出（写锁真的释放），再删登记**。
           //   反过来的话，一旦它没死透，锁的持有者就变成"无登记的未知进程" ——
           //   既报不清是谁，连 dsh_takeover 都会拒绝（判成 none）。
-          await proc.stop().catch(() => {});
-          removeMarker(c.id);
+          const stopped = await proc.stop().catch(() => false);
+          if (stopped) removeMarker(c.id);
         }
       } catch (e) {
         this.log.info(`[hub] 回收周期异常（已忽略，下个周期继续）: ${e.message}`);
@@ -1751,6 +1809,7 @@ export class Hub {
   async releaseAll({ force = false } = {}) {
     const released = [];
     const skippedBusy = [];
+    const failed = [];
     for (const c of this.conversations.values()) {
       if (!c.proc?.alive) continue;
       // ★ 默认不打断正在跑的回合：all=true 是"腾内存"，不是"取消任务"。
@@ -1761,12 +1820,18 @@ export class Hub {
       }
       const proc = c.proc;
       c.proc = null;
-      await proc.stop().catch(() => {});
-      removeMarker(c.id);
-      released.push(c.id);
+      const stopped = await proc.stop().catch(() => false);
+      if (stopped) {
+        removeMarker(c.id);
+        released.push(c.id);
+      } else {
+        // 进程没确认退出：保留登记，让 takeover 还能归因这个孤儿。
+        failed.push(c.id);
+        this.log.info(`[hub] 释放 ${c.id} 时进程未确认退出，保留写锁登记`);
+      }
     }
     this.save();
-    return { released: released.length, conversations: released, skipped_busy: skippedBusy };
+    return { released: released.length, conversations: released, skipped_busy: skippedBusy, failed };
   }
 
   async shutdown() {
@@ -1775,9 +1840,10 @@ export class Hub {
     for (const c of this.conversations.values()) {
       const proc = c.proc;
       c.proc = null;
-      await proc?.stop().catch(() => {});
-      // 子进程停了，锁就释放了；登记也要删，否则下个实例会把我们看成"孤儿持有者"
-      removeMarker(c.id);
+      const stopped = await proc?.stop().catch(() => false);
+      // 只有确认子进程退出、锁真的释放后才删登记；否则留给下个实例归因。
+      if (stopped) removeMarker(c.id);
+      else this.log.info(`[hub] 关闭 ${c.id} 时进程未确认退出，保留写锁登记`);
     }
     this.save();
   }

package/src/line-decoder.mjs

@@ -0,0 +1,41 @@
+/**
+ * 行式 UTF-8 解码器。
+ *
+ * Node 的 stream 回调给的是 Buffer；直接对每个 chunk 调 `toString('utf8')`
+ * 会在 chunk 边界把一个多字节字符（中文/emoji）截成 U+FFFD，JSON 仍然合法，
+ * 但内容被静默改写。StringDecoder 会跨 chunk 保留未完成的多字节序列。
+ *
+ * 同时负责按 `\n` 切行；行内保留 `\r`，由调用方按需 trim。
+ */
+import { StringDecoder } from 'node:string_decoder';
+
+export class LineDecoder {
+  #decoder = new StringDecoder('utf8');
+  #buf = '';
+
+  /** 喂一个 Buffer；返回本轮切出的完整行（不含换行符）。 */
+  push(chunk) {
+    this.#buf += this.#decoder.write(chunk);
+    return this.#drain(false);
+  }
+
+  /** EOF：把 decoder 里残留的半个字符和最后一行一起吐出来。 */
+  end() {
+    this.#buf += this.#decoder.end();
+    return this.#drain(true);
+  }
+
+  #drain(flush) {
+    const lines = [];
+    let i;
+    while ((i = this.#buf.indexOf('\n')) !== -1) {
+      lines.push(this.#buf.slice(0, i));
+      this.#buf = this.#buf.slice(i + 1);
+    }
+    if (flush && this.#buf) {
+      lines.push(this.#buf);
+      this.#buf = '';
+    }
+    return lines;
+  }
+}

package/src/locks.mjs

@@ -106,7 +106,12 @@ export function writeMarker(conversationId, { childPid, cwd }) {
     mcp_token: MCP_TOKEN,
     child_pid: childPid ?? null,
     cwd: cwd ?? null,
-    spawned_at: prev?.spawned_at ?? now,
+    // 只有同一个子进程才沿用旧启动时间；子进程换了（PID 变化）必须重置，
+    // 否则 PID 复用保护会把新进程误判成“复用旧 PID”而拒绝 takeover。
+    spawned_at:
+      prev && prev.child_pid === childPid && Number.isFinite(prev.spawned_at)
+        ? prev.spawned_at
+        : now,
     heartbeat_at: now,
   });
   return true;

package/src/mcp.mjs

@@ -10,6 +10,7 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createHandlers, TOOL_DEFS } from './tools.mjs';
 import { DEFAULT_PERMISSION } from './config.mjs';
+import { LineDecoder } from './line-decoder.mjs';
 
 const SERVER_NAME = 'dsh-any-agent';
 /**
@@ -117,7 +118,7 @@ function fileURLToPathSafe(uri) {
 
 export function createMcpServer({ hub, toolDefs = TOOL_DEFS, handlers = createHandlers(hub), log }) {
   const write = (obj) => process.stdout.write(JSON.stringify(obj) + '\n');
-  let buffer = '';
+  const lineDecoder = new LineDecoder();
   let initialized = false;
   let clientCapabilities = {};
   let rootsSeq = 0;
@@ -251,11 +252,7 @@ export function createMcpServer({ hub, toolDefs = TOOL_DEFS, handlers = createHa
   }
 
   function onData(chunk) {
-    buffer += chunk.toString('utf8');
-    let idx;
-    while ((idx = buffer.indexOf('\n')) !== -1) {
-      const line = buffer.slice(0, idx);
-      buffer = buffer.slice(idx + 1);
+    for (const line of lineDecoder.push(chunk)) {
       if (!line.trim()) continue;
       let msg;
       try {

package/src/tools.mjs

@@ -292,7 +292,7 @@ function renderSendResult(r) {
   }
   const tools = (r.tools_used ?? []).map((t) => t.name ?? t.title).filter(Boolean);
   if (tools.length) meta.push(`工具=[${[...new Set(tools)].join(', ')}]`);
-  if (r.workspace_changed) meta.push(`工作区有改动(${r.diff_stat?.changed_files ?? '?'} 个文件)`);
+  if (r.workspace_changed) meta.push(`本轮工作区状态发生变化(当前共 ${r.diff_stat?.changed_files ?? '?'} 个文件有改动)`);
   lines.push('');
   lines.push(`[${meta.join(' · ')}]`);
 
@@ -611,12 +611,15 @@ export function createHandlers(hub, opts = {}) {
       if (args.all === true) {
         const r = await hub.releaseAll({ force: args.force === true });
         return {
-          structured: { released: r.released, conversations: r.conversations, skipped_busy: r.skipped_busy },
+          structured: { released: r.released, conversations: r.conversations, skipped_busy: r.skipped_busy, failed: r.failed },
           text:
             `已释放 ${r.released} 个空闲会话进程（写锁让出，内存回收）。` +
             (r.skipped_busy.length
               ? `\n跳过 ${r.skipped_busy.length} 个正在跑回合的会话；要连它们一起停掉请传 force=true。`
               : '') +
+            (r.failed.length
+              ? `\n⚠️ ${r.failed.length} 个会话的进程未确认退出，写锁登记已保留；可稍后用 dsh_status/dsh_takeover 处理。`
+              : '') +
             `\n会话日志都在磁盘上，之后派活会自动 resume；没有一个可释放时 released=0。`,
         };
       }

package/src/workspace.mjs

@@ -329,22 +329,33 @@ export function scanSessions() {
  *
  * 会对 id 做形状校验（只允许 UUID / `session-` 前缀那类字符），避免 `..` 之类逃出会话目录。
  */
-export async function findSessionHeader(sessionId) {
-  if (typeof sessionId !== 'string' || !/^[A-Za-z0-9._-]{4,80}$/.test(sessionId)) return null;
-  if (!existsSync(SESSIONS_ROOT)) return null;
+export async function findSessionHeaderStatus(sessionId) {
+  if (typeof sessionId !== 'string' || !/^[A-Za-z0-9._-]{4,80}$/.test(sessionId)) {
+    return { status: 'missing', header: null, reason: 'id 形状非法' };
+  }
+  if (!existsSync(SESSIONS_ROOT)) return { status: 'missing', header: null, reason: '会话目录不存在' };
   let buckets;
   try {
     buckets = readdirSync(SESSIONS_ROOT);
-  } catch {
-    return null;
+  } catch (e) {
+    return { status: 'error', header: null, reason: `会话目录不可读: ${e.message}` };
   }
   for (const bucket of buckets) {
     const f = join(SESSIONS_ROOT, bucket, sessionId, 'session.v4.jsonl.zstd');
     if (!existsSync(f)) continue;
     const header = await readHeaderAsync(f);
-    if (header?.id === sessionId) return header;
+    if (header?.id === sessionId) return { status: 'found', header, file: f };
+    if (header === null) {
+      // 文件存在但头读不出来（超时/损坏/IO）：不能当成“会话不存在”，
+      // 否则 forget 墓碑会被误删、按 id 查询也会误报未知会话。
+      return { status: 'error', header: null, reason: `无法读取会话头: ${f}`, file: f };
+    }
   }
-  return null;
+  return { status: 'missing', header: null, reason: '会话文件不存在' };
+}
+
+export async function findSessionHeader(sessionId) {
+  return (await findSessionHeaderStatus(sessionId)).header;
 }
 
 /**