dsh-any-agent 0.3.7 → 0.3.9

package/USAGE-MIGRATION.en.md

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

package/src/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;