dsh-remote 0.8.44 → 0.8.46

package/README.en.md

@@ -133,7 +133,17 @@ A new tab opens showing that remote machine's full DSH interface (chat, tool tre
   no second instance will be started.
 - When the remote `dsh` is not on the SSH login PATH, point `webAttachCommand` at its absolute path; to
   keep an attached instance out of the remote user's own sessions and settings, point `webAttachDshHome`
-  at a scratch directory.
+  at a scratch directory. This is **per machine**: Settings → Remote workspace → the machine card →
+  expand "Advanced" → "Remote dsh command" (e.g.
+  `/home/you/.nvm/versions/node/v22.19.0/bin/node /home/you/.dsh-remote/dsh/node_modules/@deepseek-ai/dsh/lib/bin.js`).
+  Empty falls back to the global `webAttachCommand`. A successful "Deploy & verify" writes this field for you.
+- The tunnel follows the SSH connection: when it drops, the UI shows "Disconnected" and the local DSH
+  process is **not** affected. After the pool reconnects the plugin re-resolves the remote port (restarting
+  the remote process it started, if that one died), so hitting "Reconnect" is enough to carry on.
+- The remote node must be **≥ 20.12** (booting dsh needs `parseEnv` from `node:util`, which only exists
+  from 20.12). An older node is reported as a blocker by the check: npm only warns (EBADENGINE) and
+  installs anyway, and the crash arrives later as
+  `does not provide an export named 'parseEnv'` — so it has to be caught before the install.
 
 ### Cannot connect? Check the environment, then deploy in one click
 
@@ -245,7 +255,7 @@ Deploying to a product profile is a separate, explicit action (`./sync.sh`) for
 | `keyboardInteractive` | bool | `false` | allow keyboard-interactive auth (OTP/MFA) with the configured password |
 | `backend` | string | `native` | SSH transport backend (issue #51). `native` = the built-in ssh2 client (password / private key / agent / OTP); `openssh` = **drive the local `ssh` command**, which is the only way to reach hosts whose sole authentication method is GSSAPI/Kerberos (log in once with `kinit`), and which also honours `ProxyCommand`, `PKCS11Provider`, `Match` blocks and the rest of `~/.ssh/config`. **Settable per machine.** The cost is a fresh connection per command (slower than native); SFTP still reuses one session. The host name is handed to ssh **verbatim** (so `~/.ssh/config` stays the single source of truth) and host keys are checked by ssh against your own `known_hosts` |
 | `sshBinary` | string | `''` | the `ssh` executable the `openssh` backend drives (empty = the `ssh` on PATH) |
-| `proxy` | object | — | jump host: `{ host, port?, username?, password?, privateKeyPath? }` |
+| `proxy` | object | — | jump host: `{ host, port?, username?, password?, privateKeyPath? }`; it means "reach the target host:port from the bastion", which is also what reaches a docker container's sshd on the bastion (see the issue #56 entry in the FAQ) |
 | `autoPush` | bool | `false` | auto-push edited mirror files back to the remote (watcher, debounced) |
 | `auditLog` | bool | `true` | append executed commands to `$DSH_HOME/remote-workspaces/audit.log` |
 | `encoding` | string | `utf-8` | text encoding for remote file reads/writes (e.g. `gbk`) |
@@ -260,7 +270,7 @@ Deploying to a product profile is a separate, explicit action (`./sync.sh`) for
 | `updateCheckIntervalMs` | int | 21600000 (6h) | how often `auto` mode checks npm (floor 60000) |
 | `updateAutoReload` | bool | `true` | hot-swap the host half after an update lands; `false` defers it to the next process start and the panel reports `pendingReload` |
 | `webAttachPortStart` | int | `3088` | first local port for the "Remote DSH Web UI" tunnel (later ports are tried when taken; loopback only) |
-| `webAttachCommand` | string | `dsh` | command used to start `dsh web` on the remote; change it when the remote `dsh` is not on the SSH login PATH |
+| `webAttachCommand` | string | `dsh` | command used to start `dsh web` on the remote; change it when the remote `dsh` is not on the SSH login PATH (also settable per machine under "Advanced" in the settings page, which wins over this default) |
 | `webAttachDshHome` | string | `''` | `DSH_HOME` exported on the remote when attaching; empty reuses the remote user's own harness home |
 | `webAttachWaitSeconds` | int | `45` | how long to wait for a freshly started remote `dsh web` to print its launch token |
 | `webInstallPrefix` | string | `''` | where an automatic deployment installs dsh; empty means `$HOME/.dsh-remote/dsh` (no system directory, no PATH change) |
@@ -273,6 +283,10 @@ Deploying to a product profile is a separate, explicit action (`./sync.sh`) for
 
 **`@` lists remote files but the built-in read tool cannot open them** — the harness's own file tools see the **local mirror**, which stays empty until `rw_sync` downloads it. Read remote files with `rw_read_file` or the sidebar remote tab.
 
+**A file link in a remote Session does not open** (issue #55) — fixed. When a link is clicked the harness turns it into `dsh-resource://file/session/<session>/<path>` and hands it to the built-in text preview, which reads the **local** filesystem; a remote Session's cwd is a **local mirror directory** (empty until `rw_sync`), so the open simply failed. The plugin now registers a higher-priority handler for that address and opens it over SFTP through the same editor as the sidebar "Remote Files" tab. The safety rule is deliberately conservative: it takes over only when the Session's cwd is **provably inside a mirror** and the mirror registry has loaded, so local Sessions — and the instant right after a page load — keep the built-in preview and no local file is ever mistaken for a remote one. The two cases that still cannot be mapped say so instead of showing a blank page: an address with no mirror mapping, and a Session whose workspace is not a remote mirror directory.
+
+**The terminal in a remote Session is still the local one** (issue #55) — that is **by design, and a plugin cannot change it**, but there is an equivalent: DSH's sidebar terminal is core, its PTY comes from the **context-global** `subprocess` service, and its cwd is the Session's own workspace directory (the local mirror for a remote Session). A plugin can neither replace that service nor retarget the core terminal onto SSH. For a **genuine remote terminal** use the "Remote DSH Web UI" (above): it opens the **remote machine's own** DSH in this browser, and that interface's terminal runs on the remote host, with no extra configuration. To run a single remote command instead, use `rw_exec` (add `pty: true` for an interactive PTY).
+
 **Host key changed** — `/remote forget-key` (or Settings → machine → trust again).
 
 **"Authentication failed"** — check the username/password/key path; fill in the passphrase for an encrypted key; enable keyboard-interactive when the host requires OTP.
@@ -281,6 +295,22 @@ Deploying to a product profile is a separate, explicit action (`./sync.sh`) for
 
 **The host only allows GSSAPI/Kerberos (`ssh` works after `kinit`, the plugin does not)** — in Settings → 远程工作区 → Advanced, switch **Backend** to `openssh` (drive the local `ssh`) and tick "use a ~/.ssh/config alias", with Host set to the **alias** in `~/.ssh/config` (not the IP). The login is then performed by your local ssh with your Kerberos ticket, and `ProxyCommand`, `GSSAPIAuthentication` etc. all apply per `~/.ssh/config` — **one source of truth for the configuration** (issues #50/#51). Command-line equivalent: `rw_connect(host="<alias>", useSshConfig=true, backend="openssh")`.
 
+**Can a docker container on the remote host be the workspace?** (issue #56) — Yes, and **no plugin change is needed**. There is no container-specific code anywhere in the plugin, yet the two configurations below already cover the request. Pick by whether the container **publishes a port**:
+
+- **A: the container maps its sshd** (e.g. `docker run -p 127.0.0.1:2222:22 …`) — a plain "jump host" configuration: Host `127.0.0.1`, Port `2222`, the container's user/key, and the **remote host** as the jump host. Why the files really land in the container: `proxy` means "connect to `<host>:<port>` **as resolved by the bastion**" (`lib/pool.js`: `pclient.forwardOut(...this.config.host, this.config.port...)`), and the resulting channel becomes the main connection's own transport (`opts.sock`), so SFTP rides the **container's** sshd — `rw_list_dir`/`rw_read_file`/`rw_write_file`/`rw_sync` all read and write container files. Command-line equivalent: `rw_connect(host="127.0.0.1", port=2222, username="<container user>", privateKeyPath="<key>")`. Requires `AllowTcpForwarding` on the remote sshd (the default).
+- **B: the container publishes nothing** — pure `~/.ssh/config` plus the system-OpenSSH backend, on **your** machine:
+
+```sshconfig
+Host devbox
+    HostName devbox.invalid
+    User dev
+    IdentityFile ~/.ssh/id_ed25519
+    ProxyCommand ssh <remote-host> docker exec -i <container> sh -c 'exec socat - TCP:127.0.0.1:22'
+```
+
+  then `rw_connect(host="devbox", useSshConfig=true, backend="openssh")`. Why **both** commands and file operations reach the container: the `openssh` backend hands the alias to `ssh` verbatim and deliberately never emits its own `ProxyCommand` (`lib/openssh.js` omits it so that `~/.ssh/config` decides), while `ssh -s <dest> sftp` and `ssh -- <dest> <cmd>` travel the same stream. Requires an sshd inside the container plus `socat` (or an `nc` that speaks stdio).
+  ⚠️ **A Windows caveat**: POSIX OpenSSH shell-expands `ProxyCommand`, but **Windows' own OpenSSH 9.5 does not** (measured: it passes the whole string through as literal argv). So on a Windows host either keep the `ProxyCommand` a single command with no shell metacharacters, or point "ssh path" at Git Bash's `ssh.exe`. (Also: whether `docker exec -i` carries binary data byte-for-byte is unverified here — no docker on this machine — so try a small file with B first.)
+
 **`rw_sync`/`rw_push` reports conflicts** — files changed on both sides are skipped and listed (never silently overwritten); merge manually and retry, or pass `force=true`.
 
 **Windows remotes** — everything goes over SFTP, no POSIX shell needed; read Chinese files with `encoding=gbk`.

package/README.md

@@ -120,6 +120,15 @@ dsh plugin add dsh-remote
   `http://127.0.0.1:<端口>/?token=…` 粘进输入框，点「连接已有实例」，插件不会再去启第二个。
 - 远端 `dsh` 不在 SSH 登录 PATH 时，用 `webAttachCommand` 指向它的绝对路径；
   想让它别污染远端用户自己的会话/设置，用 `webAttachDshHome` 指一个临时目录。
+  **按机器设**：设置 → 远程工作区 → 机器卡片 → 展开「高级」→「远端 dsh 命令」，
+  填绝对路径即可（例如
+  `/home/you/.nvm/versions/node/v22.19.0/bin/node /home/you/.dsh-remote/dsh/node_modules/@deepseek-ai/dsh/lib/bin.js`）；
+  留空则用全局的 `webAttachCommand`。「部署并验证」成功后也会自动写进这个字段。
+- 隧道跟着 SSH 连接走：连接断了界面会显示「连接已断开」，**不会**影响本机 DSH 进程；
+  池自动重连后插件会重新解析远端端口（必要时重启它自己启动的那个远端进程），界面点「重连」即可继续用。
+- 远端 node 需要 **≥ 20.12**（dsh 启动要用 `node:util` 的 `parseEnv`，该导出从 20.12 起才有）。
+  node 太旧时体检会直接报 blocker：npm 只会给 EBADENGINE 警告、照样把包装完，
+  直到启动才崩在 `does not provide an export named 'parseEnv'`，所以必须在装之前拦住。
 
 ### 连不上？先体检，再一键部署
 
@@ -227,7 +236,7 @@ scripts/dev-run.sh --status    # 是否在运行
 | `keyboardInteractive` | bool | `false` | 允许 keyboard-interactive 认证（OTP/MFA）并复用配置的密码 |
 | `backend` | string | `native` | SSH 传输后端（issue #51）。`native`=内置 ssh2（密码/私钥/agent/动态码）；`openssh`=**调用本机 `ssh` 命令**，因此支持 GSSAPI/Kerberos（`kinit` 后免密）以及 `ProxyCommand`、`PKCS11Provider`、`Match` 等 OpenSSH 专有特性。**可按机器单独设置**。代价：每条命令新建一次连接（比 native 慢）；SFTP 仍复用单条长连接。主机名会被**原样**交给 ssh（`~/.ssh/config` 是配置唯一来源），主机密钥也由 ssh 用你自己的 `known_hosts` 校验 |
 | `sshBinary` | string | `''` | `openssh` 后端调用的 `ssh` 可执行文件（留空=用 PATH 里的 `ssh`） |
-| `proxy` | object | — | 跳板机：`{ host, port?, username?, password?, privateKeyPath? }` |
+| `proxy` | object | — | 跳板机：`{ host, port?, username?, password?, privateKeyPath? }`；语义是「在跳板机上连目标 host:port」，所以也能用来连跳板机上 docker 容器的 sshd（见「常见问题」里的 issue #56） |
 | `autoPush` | bool | `false` | 镜像内文件被编辑后自动推回远端（watcher，带防抖） |
 | `auditLog` | bool | `true` | 把执行的命令追加到 `$DSH_HOME/remote-workspaces/audit.log` |
 | `encoding` | string | `utf-8` | 远程文件读写的文本编码（如 `gbk`） |
@@ -242,7 +251,7 @@ scripts/dev-run.sh --status    # 是否在运行
 | `updateCheckIntervalMs` | int | 21600000（6h） | `auto` 模式检查 npm 的间隔（下限 60000） |
 | `updateAutoReload` | bool | `true` | 更新落地后自动热切换宿主半；`false` 则留到下次启动，设置页会显示 `pendingReload` |
 | `webAttachPortStart` | int | `3088` | 「远程 DSH 界面」在本机监听的起始端口（占用则顺延，仅监听 127.0.0.1） |
-| `webAttachCommand` | string | `dsh` | 在远端启动 `dsh web` 用的命令；远端 `dsh` 不在 SSH 登录 PATH 时改这里 |
+| `webAttachCommand` | string | `dsh` | 在远端启动 `dsh web` 用的命令；远端 `dsh` 不在 SSH 登录 PATH 时改这里（也可按机器在设置页「高级」里单独设，机器级优先） |
 | `webAttachDshHome` | string | `''` | 远端启动时导出的 `DSH_HOME`；留空则复用远端用户自己的 harness home |
 | `webAttachWaitSeconds` | int | `45` | 等待远端 `dsh web` 打印启动令牌的秒数 |
 | `webInstallPrefix` | string | `''` | 自动部署装到远端的哪个目录；留空用 `$HOME/.dsh-remote/dsh`（不写系统目录、不改 PATH） |
@@ -255,12 +264,59 @@ scripts/dev-run.sh --status    # 是否在运行
 
 **`@` 能列出远程文件，但内置读文件工具打不开** —— harness 自带工具看到的是**本地镜像**，要等 `rw_sync` 下载后才有内容。读远程文件请用 `rw_read_file` 或侧栏远程文件 tab。
 
+**远程会话里的文件链接打不开**（issue #55）—— 已修。链接被点开时 harness 会把它变成
+`dsh-resource://file/session/<会话>/<路径>`，然后交给内置的文本预览去读；而那个预览读的是**本机**
+文件系统，远程会话的 cwd 是**本地镜像目录**（`rw_sync` 之前是空的），所以打开只会失败。
+插件现在注册了一个更高优先级的地址处理器，把这个地址按远程主机解析后用 SFTP 打开（和侧栏「远程文件」同一个编辑器）。
+安全边界是保守的：只有当该会话的 cwd **确实落在某个镜像目录里**、且镜像表已加载时才接管，
+本地会话与页面刚加载的那一瞬间仍然走内置预览 —— 不会把本地文件误当成远程文件。
+两个仍然开不了的情况会给出明确提示而不是空白页：链接指向的是**绝对**远端路径之外无法映射的地址，
+或该会话的工作区不是一个远程镜像目录。
+
+**远程会话里的终端还是本机的**（issue #55）—— 这是**设计如此，插件改不了**，但有等效方案。
+DSH 的侧栏终端是核心功能：它的 PTY 来自**全局唯一**的 `subprocess` 服务，cwd 取会话自己的
+工作区目录（远程会话就是本地镜像），插件既不能替换那个服务、也不能把核心终端重定向到 SSH。
+想要「真正的远程终端」，用**「远程 DSH 界面」**（见上文）：它在本机浏览器里打开**远端机器自己**的
+DSH，那个界面里的终端就跑在远端主机上，零额外配置。只想偶尔跑一条远程命令则用 `rw_exec`
+（要交互式 PTY 就加 `pty: true`）。
+
 **主机指纹变了** —— `/remote forget-key`（或设置页 → 机器 → 重新信任）。
 
 **连接报「认证失败」** —— 检查用户名/密码/私钥路径；加密私钥要填 Passphrase；需要动态码时勾选 keyboard-interactive。
 
 **连不上内网机器** —— 填「跳板机」主机（也可先把跳板机本身配成一台机器）。
 
+**能不能拿远程主机上的 docker 容器当工作空间？**（issue #56）—— 能，**不需要改插件**；
+插件对容器没有任何专门代码，但下面两条既有配置已经完整覆盖这个需求。请按容器**有没有对外暴露端口**二选一：
+
+- **A：容器把 sshd 端口映射出来了**（例如 `docker run -p 127.0.0.1:2222:22 …`）—— 纯「跳板机」配置：
+  Host 填 `127.0.0.1`、Port 填 `2222`、用户/私钥填容器里的，再把「跳板机」主机填**那台远程主机**。
+  为什么这样文件就能落到容器里：`proxy` 的语义是「**在跳板机上**连 `<host>:<port>`」
+  （`lib/pool.js` 的 `pclient.forwardOut(...this.config.host, this.config.port...)`），
+  拿到的通道会被当成主连接自己的 transport（`opts.sock`），于是 SFTP 走的是**容器自己的 sshd** ⇒
+  `rw_list_dir`/`rw_read_file`/`rw_write_file`/`rw_sync` 全部读写的都是容器内的文件。
+  命令行等价写法：`rw_connect(host="127.0.0.1", port=2222, username="<容器用户>", privateKeyPath="<私钥>")`。
+  要求：远程主机的 sshd 允许转发（`AllowTcpForwarding yes`，默认就是）。
+- **B：容器没有暴露端口** —— 纯 `~/.ssh/config` + 系统 OpenSSH 后端，在**本机** `~/.ssh/config` 写：
+
+```sshconfig
+Host devbox
+    HostName devbox.invalid
+    User dev
+    IdentityFile ~/.ssh/id_ed25519
+    ProxyCommand ssh <远程主机> docker exec -i <容器名> sh -c 'exec socat - TCP:127.0.0.1:22'
+```
+
+  然后 `rw_connect(host="devbox", useSshConfig=true, backend="openssh")`。
+  为什么 `exec` 和文件操作**都会**进容器：`openssh` 后端把别名原样交给 `ssh`，
+  自己**从不**生成 `ProxyCommand`（`lib/openssh.js` 明确不传，就是为了让 `~/.ssh/config` 说了算），
+  而 `ssh -s <目标> sftp` 与 `ssh -- <目标> <命令>` 走的是同一条流 ⇒ 两者都穿过这个 ProxyCommand。
+  要求：容器里有 sshd，且有 `socat`（或用支持 stdio 的 `nc`）。
+  ⚠️ **Windows 上有个坑**：POSIX OpenSSH 会把 `ProxyCommand` 交给 shell 展开，**Windows 自带的 OpenSSH 9.5 不会**
+  （实测它把整串按字面当成 argv）。所以在 Windows 跑本插件时，要么把 `ProxyCommand` 写成
+  不含 shell 元字符的单条命令，要么把「ssh 路径」指向 Git Bash 的 `ssh.exe`。
+  （另：`docker exec -i` 传二进制是否逐字节无损，我这边没有 docker 环境验证过，B 方案建议先用小文件试。）
+
 **企业机器只允许 GSSAPI/Kerberos（`kinit` 后 `ssh` 能进，插件进不去）** —— 在设置 → 远程工作区 → 高级配置里把「连接后端」改成 **`openssh`**（调用本机 `ssh`），并勾选「使用 ssh_config 别名」，Host 填 `~/.ssh/config` 里那个**别名**（不是 IP）。这样登录由本机 ssh 用你的 Kerberos 票据完成，且 `ProxyCommand`、`GSSAPIAuthentication` 等全部照 `~/.ssh/config` 生效 —— **配置只有 `~/.ssh/config` 一个来源**（issue #50/#51）。命令行等价写法：`rw_connect(host="<别名>", useSshConfig=true, backend="openssh")`。
 
 **`rw_sync`/`rw_push` 报冲突** —— 两边都改过的文件会被跳过并列出（绝不静默覆盖）；手动合并后重试，或用 `force=true` 以一边为准。

package/lib/client.js

@@ -58,6 +58,13 @@ window.__ModuleLoader__.load({
         'settings.backendOpensshAliasOk': '已勾选「使用 ssh_config 别名」：主机名原样交给 ssh，端口/用户/私钥/跳板机一律由 ~/.ssh/config 的 Host 块决定，对应的输入框在 openssh 后端下填了也不生效（这就是「配置唯一来源」，issue #50）。密码/Passphrase 仍会通过 askpass 交给 ssh，仅当 Host 块里没有可用认证时才用得上。',
         'settings.sshBinary': 'ssh 路径',
         'settings.sshBinaryPlaceholder': '留空 = 用 PATH 里的 ssh',
+        // Issue #54: the README told users to point `webAttachCommand` at a
+        // private-prefix dsh, but the settings UI offered nowhere to type it —
+        // it could only be written by the deploy flow or by hand-editing
+        // machines.json. It is an ordinary per-machine field now.
+        'settings.webAttachCmd': '远端 dsh 命令',
+        'settings.webAttachCmdPlaceholder': '留空 = 用全局 webAttachCommand（默认 dsh）',
+        'settings.webAttachCmdHint': '远端 dsh 不在 SSH 登录 PATH 时（私有前缀 / nvm 装的 node）填它的绝对路径，例如 /home/you/.nvm/versions/node/v22.19.0/bin/node /home/you/.dsh-remote/dsh/node_modules/@deepseek-ai/dsh/lib/bin.js。留空则用全局的 webAttachCommand。',
         'settings.sshImport': '从 ~/.ssh/config 导入',
         'settings.sshCollapse': '收起',
         'settings.sshNoEntries': '~/.ssh/config 里没有可导入的 Host 条目',
@@ -308,6 +315,10 @@ window.__ModuleLoader__.load({
         'file.downloadedAt': ': {path}',
         'file.readFail': '远程读取失败: {msg}',
         'file.listFail': '远程目录读取失败: {msg}',
+        // Issue #55: a file link in a remote Session cannot be mapped onto the
+        // remote host (no mirror for the Session's cwd), so say so instead of
+        // rendering an empty editor.
+        'file.linkUnresolved': '这个文件链接无法对应到远端路径（该会话的工作区不是一个远程镜像目录）。请用侧栏「远程文件」打开，或用 rw_read_file 读取。',
         'common.refresh': '刷新',
         'common.close': '关闭',
         'common.confirm': '确认',
@@ -336,6 +347,11 @@ window.__ModuleLoader__.load({
         'settings.backendOpensshAliasOk': '"Use a ~/.ssh/config alias" is on: the name is handed to ssh verbatim, and Port/User/IdentityFile/ProxyJump come from that Host block — the matching fields below have no effect (this is the "one source of truth" case, issue #50). A password/passphrase is still offered to ssh through askpass, and is only used if the Host block has no usable authentication.',
         'settings.sshBinary': 'ssh path',
         'settings.sshBinaryPlaceholder': 'Empty = the ssh on PATH',
+        // Issue #54: the README documented `webAttachCommand` but the settings
+        // UI had no field for it.
+        'settings.webAttachCmd': 'Remote dsh command',
+        'settings.webAttachCmdPlaceholder': 'Empty = the global webAttachCommand (default: dsh)',
+        'settings.webAttachCmdHint': 'Set the absolute path when the remote dsh is not on the SSH login PATH (a private prefix, or node installed with nvm), e.g. /home/you/.nvm/versions/node/v22.19.0/bin/node /home/you/.dsh-remote/dsh/node_modules/@deepseek-ai/dsh/lib/bin.js. Empty falls back to the global webAttachCommand.',
         'settings.sshImport': 'Import from ~/.ssh/config',
         'settings.sshCollapse': 'Collapse',
         'settings.sshNoEntries': 'No importable Host entries in ~/.ssh/config',
@@ -586,6 +602,7 @@ window.__ModuleLoader__.load({
         'file.downloadedAt': ': {path}',
         'file.readFail': 'Failed to read remote: {msg}',
         'file.listFail': 'Failed to list remote directory: {msg}',
+        'file.linkUnresolved': 'This file link does not map onto a remote path (the Session workspace is not a remote mirror directory). Open it from the sidebar "Remote Files" tab, or read it with rw_read_file.',
         'common.refresh': 'Refresh',
         'common.close': 'Close',
         'common.confirm': 'Confirm',
@@ -1139,15 +1156,17 @@ window.__ModuleLoader__.load({
           proxyUser: (m.proxy && m.proxy.username) || '', proxyPassword: '', proxyKey: (m.proxy && m.proxy.privateKeyPath) || '',
           // Issue #51: the transport backend is per machine.
           backend: m.backend === 'openssh' ? 'openssh' : 'native', sshBinary: m.sshBinary || '',
+          // Issue #54: the per-machine remote-dsh command for Web UI attach.
+          webAttachCommand: m.webAttachCommand || '',
           id: m.id,
           useSshConfig: !!m.useSshConfig,
         })
         // 编辑时若该机器用了高级配置(私钥/agent/跳板/钥匙串/系统 OpenSSH 后端),自动展开折叠区
-        if (m.privateKeyPath || m.useAgent || m.keyboardInteractive || m.workspace || (m.proxy && m.proxy.host) || m.backend === 'openssh' || (m.credentialBackend && m.credentialBackend !== 'plain')) {
+        if (m.privateKeyPath || m.useAgent || m.keyboardInteractive || m.workspace || (m.proxy && m.proxy.host) || m.backend === 'openssh' || m.webAttachCommand || (m.credentialBackend && m.credentialBackend !== 'plain')) {
           setAdvOpen(true)
         }
       }
-      const clearForm = () => setForm({ name: '', host: '', port: '22', username: 'root', password: '', privateKeyPath: '', passphrase: '', workspace: '', hostKeyMode: '', useAgent: false, keyboardInteractive: false, encryptPassword: false, proxyHost: '', proxyPort: '22', proxyUser: '', proxyPassword: '', proxyKey: '', backend: 'native', sshBinary: '', id: '', useSshConfig: false })
+      const clearForm = () => setForm({ name: '', host: '', port: '22', username: 'root', password: '', privateKeyPath: '', passphrase: '', workspace: '', hostKeyMode: '', useAgent: false, keyboardInteractive: false, encryptPassword: false, proxyHost: '', proxyPort: '22', proxyUser: '', proxyPassword: '', proxyKey: '', backend: 'native', sshBinary: '', webAttachCommand: '', id: '', useSshConfig: false })
       const save = (action) => {
         setBusy(true); setErr(''); setMsg('')
         if (action === 'delete') {
@@ -1161,6 +1180,8 @@ window.__ModuleLoader__.load({
           encryptPassword: form.encryptPassword, useSshConfig: !!form.useSshConfig,
           // Issue #51: the transport backend (and, for `openssh`, the executable).
           backend: form.backend || 'native', sshBinary: form.sshBinary || '',
+          // Issue #54: the per-machine remote-dsh command for Web UI attach.
+          webAttachCommand: form.webAttachCommand || '',
           proxy: form.proxyHost ? { host: form.proxyHost, port: Number(form.proxyPort) || 22, username: form.proxyUser || '', password: form.proxyPassword || '', privateKeyPath: form.proxyKey || '' } : undefined,
         }).then((r) => {
           refresh(); clearForm()
@@ -1354,6 +1375,10 @@ window.__ModuleLoader__.load({
               React.createElement('input', { value: form.proxyUser, onChange: setF('proxyUser'), placeholder: 'Jump user', style: { ...inputS, minWidth: 140 } }),
               React.createElement('input', { type: 'password', value: form.proxyPassword, onChange: setF('proxyPassword'), placeholder: 'Jump password', style: { ...inputS, minWidth: 140 } })), 'pu'),
             row(tr('settings.proxyKey'), React.createElement('input', { value: form.proxyKey, onChange: setF('proxyKey'), placeholder: 'Jump private key path (optional)', style: inputS }), 'pk'),
+            // Issue #54: where "远程 DSH 界面" gets its remote dsh. The README
+            // pointed at `webAttachCommand` and there was no field for it.
+            row(tr('settings.webAttachCmd'), React.createElement('input', { value: form.webAttachCommand || '', onChange: setF('webAttachCommand'), placeholder: tr('settings.webAttachCmdPlaceholder'), style: inputS }), 'wac'),
+            React.createElement('div', { style: { paddingLeft: LABEL_W + 8, marginBottom: 8, fontSize: 11, lineHeight: 1.5, opacity: 0.7 } }, tr('settings.webAttachCmdHint')),
           ) : null,
           React.createElement('div', { style: { display: 'flex', gap: 8, justifyContent: 'flex-end', alignItems: 'center', flexWrap: 'wrap', marginTop: 8 } },
             msg ? React.createElement('span', { style: { color: T.ok, fontSize: 12, marginRight: 'auto' } }, msg) : null,
@@ -3324,6 +3349,17 @@ window.__ModuleLoader__.load({
     // paths are local filesystem resources. Each address is session-scoped.
     const NATIVE_EXPLORER = 'dsh-remote/explorer'
     const NATIVE_FILE = 'dsh-remote/file'
+    // Issue #55: the address the CORE emits for a file link, which is NOT the
+    // one this plugin mints for its own explorer. A model-emitted
+    // `[x](src/main.c)` (or a `@src/main.c` chip) is turned into
+    // `dsh-resource://file/session/<sessionId>/<path>` by the chat, and the only
+    // shipped claimant is the built-in text preview, which reads it through the
+    // HOST's ctx.fs. For a remote Session the header cwd is the LOCAL MIRROR, so
+    // the link opens an empty (or stale) local directory and fails. A plugin
+    // cannot re-register protocol `file` (one provider per protocol, and it is
+    // taken), so the supported interception is a tab type that CLAIMS that
+    // address and serves it over SFTP instead.
+    const NATIVE_LINK = 'dsh-remote/remote-link'
     function remoteFileAddress(sessionId, path) {
       return 'dsh-resource://dsh-remote/' + encodeURIComponent(sessionId) + '/' + encodeURIComponent(path)
     }
@@ -3332,6 +3368,88 @@ window.__ModuleLoader__.load({
       if (url.protocol !== 'dsh-resource:' || url.hostname !== 'dsh-remote') throw new Error('Invalid remote resource')
       return decodeURIComponent(url.pathname.split('/').slice(2).join('/'))
     }
+    /**
+     * Parse the core's `dsh-resource://file/session/<id>/<path>` address.
+     *
+     * Mirrors the grammar the core uses (`dsh-util-workspace-path`): the first
+     * segment after the scheme is the scope (`session`), then the id, then the
+     * path. Anything else — including the `absolute/` scope — is not ours: an
+     * absolute remote path cannot be mapped back onto a mirror, so refusing is
+     * correct rather than guessing.
+     *
+     * @param {string} address - the address a link click produced.
+     * @returns {{sessionId: string, path: string}|null} the parts, or null when
+     *   this is not a session-scoped core file address.
+     */
+    function parseCoreFileAddress(address) {
+      let url
+      try { url = new URL(String(address || '')) } catch { return null }
+      if (url.protocol !== 'dsh-resource:' || url.hostname !== 'file') return null
+      const rest = url.pathname.replace(/^\/+/, '')
+      const [scope, ...tail] = rest.split('/')
+      if (scope !== 'session' || tail.length < 2) return null
+      const sessionId = decodeURIComponent(tail[0])
+      if (!sessionId) return null
+      // Dropping the leading empty segment keeps a session-root address ('') a
+      // legitimate empty path instead of turning it into '/'.
+      return { sessionId, path: decodeURIComponent(tail.slice(1).join('/')) }
+    }
+    /**
+     * The ABSOLUTE remote path a core file address refers to, or null.
+     *
+     * A relative link is mirror-rooted and an absolute one is already absolute;
+     * either way what the reader must see is the path on the REMOTE host. The
+     * session's own cwd (a mirror directory) identifies the mirror, whose record
+     * carries the remote root the mirror was taken from — the same invariant
+     * `lib/binding.js` uses host-side.
+     *
+     * Separator-aware on purpose (`mirrorForCwd` handles `/a/mirror` vs
+     * `/a/mirror-2`): showing the WRONG remote file would be worse than the
+     * current failure, so an ambiguous address returns null.
+     *
+     * @param {{sessionId: string, path: string}} parsed - a parsed core address.
+     * @param {string} cwd - the session's local cwd (its mirror directory).
+     * @returns {string} an absolute remote path, or null when it cannot be mapped.
+     */
+    function remotePathForCoreAddress(parsed, cwd) {
+      const mirror = mirrorForCwd(cwd, MIRRORS.list)
+      if (!mirror) return null
+      const remoteRoot = String(mirror.remotePath || '').replace(/[\\/]+$/, '')
+      // The REMOTE host's separator is INDEPENDENT of this machine's, and taking
+      // it from the address was wrong: a Windows client mirroring a Linux host
+      // is the ordinary case here, and reading the separator off the local path
+      // then glued a POSIX root to a Windows join ("/home/u/app" + "\" + "x.c").
+      // Decide from the remote root alone.
+      const remoteIsWin = /^[A-Za-z]:/.test(remoteRoot) || (remoteRoot.includes('\\') && !remoteRoot.includes('/'))
+      const remoteSep = remoteIsWin ? '\\' : '/'
+      const toRemote = (s) => String(s).replace(/[\\/]+/g, remoteSep)
+      // Comparison is separator-INSENSITIVE: `@` completion may insert either
+      // style, and the two sides describe the same directory. The local side
+      // folds case when it looks like a Windows path (Windows paths do).
+      const canon = (s) => String(s).replace(/[\\/]+/g, '/').replace(/\/+$/, '')
+      const localDir = String(mirror.dir || '')
+      const localIsWin = /^[A-Za-z]:/.test(localDir) || localDir.includes('\\')
+      const fold = (s) => (localIsWin ? s.toLowerCase() : s)
+      const rel = canon(parsed.path || '')
+      const mirrorDir = canon(localDir)
+      // The mirror's own directory prefix may be baked into the address when the
+      // link was written against the LOCAL path (that is what `@` completion
+      // inserts); strip it so the result is remote-relative rather than
+      // duplicated under the remote root.
+      const stripped = rel && mirrorDir && (fold(rel) === fold(mirrorDir) || fold(rel).startsWith(fold(mirrorDir) + '/'))
+        ? rel.slice(mirrorDir.length).replace(/^\/+/, '')
+        : rel
+      const relBody = canon(stripped)
+      if (!remoteRoot) return relBody ? toRemote(relBody) : remoteSep
+      if (!relBody) return remoteRoot
+      // A drive-letter absolute path on a POSIX remote is a LOCAL path that fell
+      // outside the mirror: nothing on the remote can name it, so refuse rather
+      // than invent "/home/u/app/D:/x.c".
+      if (!remoteIsWin && /^[A-Za-z]:/.test(relBody)) return null
+      // Genuinely absolute: the reader meant that path on the remote.
+      if (/^[A-Za-z]:/.test(relBody) || /^\//.test(relBody)) return toRemote(relBody)
+      return remoteRoot + remoteSep + toRemote(relBody)
+    }
     function NativeExplorer(props) {
       const info = props.useTabInfo()
       const [expanded, setExpanded] = React.useState([])
@@ -3347,9 +3465,63 @@ window.__ModuleLoader__.load({
       const path = remoteFilePath(info.tab.navigation.address)
       return React.createElement(RemoteFileTab, { key: path, tab: { path }, scope: { sessionId: props.sessionId } })
     }
+    /**
+     * The body for a CORE file link in a remote Session (issue #55).
+     *
+     * It resolves the address to an absolute REMOTE path before rendering the
+     * same editor the plugin's own explorer uses, so a link and the explorer
+     * agree on what a path means. Resolution is attempted synchronously first
+     * (the mirror registry is usually warm) and retried once the registry
+     * arrives, so a click during page load still ends up in the right file.
+     */
+    function NativeRemoteLink(props) {
+      const info = props.useTabInfo()
+      const address = info.tab.navigation.address
+      const parsed = parseCoreFileAddress(address)
+      const sessionId = (parsed && parsed.sessionId) || props.sessionId
+      const [remotePath, setRemotePath] = React.useState(() => {
+        const p = parsed || parseCoreFileAddress(address)
+        return p ? remotePathForCoreAddress(p, sessionCwdFor(sessionId)) : null
+      })
+      React.useEffect(() => {
+        if (remotePath || !parsed) return undefined
+        let cancelled = false
+        ensureMirrors().then(() => {
+          if (cancelled) return
+          const cwd = sessionCwdFor(sessionId)
+          const resolved = remotePathForCoreAddress(parsed, cwd)
+          if (resolved) setRemotePath(resolved)
+        })
+        return () => { cancelled = true }
+      }, [address, remotePath])
+      if (!remotePath) {
+        return React.createElement('div', { style: { padding: 16, fontSize: 12, opacity: 0.7 } },
+          tr('file.linkUnresolved'))
+      }
+      return React.createElement(RemoteFileTab, { key: remotePath, tab: { path: remotePath }, scope: { sessionId } })
+    }
+    /** The local cwd of a session, from the client's own session store. */
+    function sessionCwdFor(sessionId) {
+      try {
+        const list = SESSIONS && SESSIONS.list && typeof SESSIONS.list.getSnapshot === 'function'
+          ? SESSIONS.list.getSnapshot()
+          : null
+        const entry = list && list.byId && list.byId[sessionId]
+        return (entry && entry.cwd) ? String(entry.cwd) : ''
+      } catch { return '' }
+    }
     function registerNativeSidebar(inner) {
       const tabs = inner.get('sidebarRightTabs')
       const slots = inner.get('slots')
+      // Whether this build accepted the remote-link type. A local (not module
+      // level) flag, so two plugin lifetimes cannot see each other's state.
+      let linkTypeAccepted = false
+      // Issue #55: `canOpen` is synchronous and runs on every routing decision,
+      // so the mirror registry has to be warm BEFORE the first link click —
+      // otherwise the very first click of a page load falls through to the
+      // built-in local preview. This is a warm-up, not a dependency: a failure
+      // just leaves the conservative behaviour in place.
+      try { ensureMirrors() } catch { /* the registry is best-effort */ }
       inner.effect(() => tabs.register({
         id: NATIVE_EXPLORER, kind: NATIVE_EXPLORER,
         title: () => tr('explorer.tabTitle'),
@@ -3360,11 +3532,59 @@ window.__ModuleLoader__.load({
         patterns: ['dsh-resource://dsh-remote/**'],
         title: (address) => remoteFilePath(address).split(/[\\/]/).pop() || tr('explorer.tabTitle'),
       }), 'dsh-remote.native-file-type')
+      // Issue #55. No `priority` is declared, so this registers in the
+      // `extension` band, which by contract outranks every viewer the product
+      // ships — including the built-in text preview that currently claims
+      // `dsh-resource://file/**` in the `fallback` band and reads locally.
+      // `canOpen` is the whole safety story: it must return true ONLY for a
+      // session whose cwd is PROVEN to be a remote mirror. Local sessions, and
+      // a page load before the mirror registry has arrived, fall through to the
+      // built-in preview and behave exactly as they did before.
+      //
+      // Registration is wrapped because the address-claiming half of this
+      // contract (`patterns` + `canOpen`) is not something every DSH line
+      // necessarily has. The plugin supports both the 0.1.x and 0.2.x lines, and
+      // on a build whose tab registry cannot express an address claim the right
+      // outcome is "file links keep working the old way" — NOT a throw that
+      // would take the explorer and file types down with it.
+      inner.effect(() => {
+        try {
+          const dispose = tabs.register({
+            id: NATIVE_LINK, kind: NATIVE_LINK,
+            patterns: ['dsh-resource://file/**'],
+            canOpen: (address) => {
+              const parsed = parseCoreFileAddress(address)
+              if (!parsed) return false
+              const cwd = sessionCwdFor(parsed.sessionId)
+              // `MIRRORS.loaded` is checked so a cold start NEVER steals a local
+              // link: an empty registry cannot prove a mirror, and guessing would
+              // break the text preview for every local session.
+              if (!cwd || !MIRRORS.loaded) return false
+              return !!mirrorForCwd(cwd, MIRRORS.list)
+            },
+            title: (address) => {
+              const parsed = parseCoreFileAddress(address)
+              return ((parsed && parsed.path) || '').split(/[\\/]/).pop() || tr('explorer.tabTitle')
+            },
+          })
+          linkTypeAccepted = true
+          return () => { linkTypeAccepted = false; if (typeof dispose === 'function') dispose() }
+        } catch (err) {
+          try { console.warn('dsh-remote: remote file links are unavailable on this DSH build', err) } catch { /* no console */ }
+          return undefined
+        }
+      }, 'dsh-remote.native-link-type')
       inner.effect(() => slots.inject('sidebar.right.pane.tab', () => {
         const disposers = [
           slots.register({ name: 'sidebar.right.pane.tab', key: NATIVE_EXPLORER }, NativeExplorer),
           slots.register({ name: 'sidebar.right.pane.tab', key: NATIVE_FILE }, NativeFile),
         ]
+        // Only register the link body when its type was accepted: a body under a
+        // kind nothing claims would never render, and on a build that rejected
+        // the type the seat may reject the body too.
+        if (linkTypeAccepted) {
+          disposers.push(slots.register({ name: 'sidebar.right.pane.tab', key: NATIVE_LINK }, NativeRemoteLink))
+        }
         return () => disposers.forEach((dispose) => dispose())
       }), 'dsh-remote.native-bodies')
     }

package/lib/forwards.js

@@ -14,11 +14,17 @@
 import net from 'node:net'
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs'
 import path from 'node:path'
+import { forwardOutChannel } from './pool.js'
 
 export class ForwardManager {
-  /** @param {object} pool SshPool (needs .connect() returning the ssh2 client). */
-  constructor(pool, { file } = {}) {
+  /** @param {object} pool SshPool (needs .connect() returning the ssh2 client).
+   *  @param {object} [opts] - `file` (persistence) and `net` (a `node:net`
+   *    compatible module, so the listener's connection handler — the path the
+   *    issue #54 crash travelled — can be driven from a unit test without
+   *    binding a real port). */
+  constructor(pool, { file, net: netModule } = {}) {
     this.pool = pool
+    this.net = netModule || net
     this.file = file || null
     this.defs = this._load()
     this.servers = new Map() // id → { server | remoteListen, sockets:Set, client }
@@ -134,9 +140,17 @@ export class ForwardManager {
 
   _startLocal(d, client) {
     return new Promise((resolve, reject) => {
-      const server = net.createServer((socket) => {
-        client.forwardOut('127.0.0.1', 0, d.targetHost, d.targetPort, (err, channel) => {
-          if (err) { socket.destroy(); return }
+      const server = this.net.createServer((socket) => {
+        // ssh2's forwardOut reports a dead connection by THROWING
+        // (`if (!this._sock || !isWritable(this._sock)) throw new Error('Not
+        // connected')`) and never calls the callback, so a callback-only error
+        // path cannot guard this call. Uncaught, the throw escapes net.Server's
+        // connection handler and kills the whole host process — the exact fatal
+        // stack of issue #54, found in WebAttach and reachable here too for a
+        // user-defined local forward. `attach()` does register a `close`
+        // listener that calls stopAll(), but a request can arrive in the window
+        // between the connection dying and that event.
+        forwardOutChannel(client, { dstHost: d.targetHost, dstPort: d.targetPort }).then((channel) => {
           socket.pipe(channel)
           channel.pipe(socket)
           const kill = () => { try { socket.destroy() } catch {}; try { channel.close() } catch {} }
@@ -144,6 +158,9 @@ export class ForwardManager {
           channel.on('error', kill)
           socket.on('close', kill)
           channel.on('close', kill)
+        }).catch(() => {
+          // A dead tunnel is a UI state, not a reason to exit.
+          try { socket.destroy() } catch { /* already gone */ }
         })
       })
       server.on('error', (e) => reject(new Error(`本地转发 ${d.listenPort} 启动失败: ${e.message}`)))
@@ -192,7 +209,7 @@ export class ForwardManager {
     for (const entry of this.servers.values()) {
       if (entry.kind === 'reverse' && Number(info.destPort) === Number(this._defFor(entry).listenPort)) {
         const channel = accept()
-        const socket = net.connect({ host: this._defFor(entry).targetHost, port: this._defFor(entry).targetPort })
+        const socket = this.net.connect({ host: this._defFor(entry).targetHost, port: this._defFor(entry).targetPort })
         socket.pipe(channel)
         channel.pipe(socket)
         entry.sockets.add(socket)

package/lib/index.js

@@ -1558,6 +1558,10 @@ export async function apply(ctx, config) {
           // handed to ssh verbatim so ~/.ssh/config stays the single source.
           if (args.backend) rec.backend = args.backend === 'openssh' ? 'openssh' : 'native'
           if (args.sshBinary !== undefined) rec.sshBinary = String(args.sshBinary)
+          // Issue #54: the per-machine `dsh web` command is settable by hand too,
+          // not only by the deploy flow (the README told users to set it and the
+          // settings UI offered nowhere to type it).
+          if (args.webAttachCommand !== undefined) rec.webAttachCommand = String(args.webAttachCommand)
           if (useSshConfig) rec.useSshConfig = true
           // An alias connection must dial the RESOLVED identity (~/.ssh/config),
           // while the registry keeps the alias itself — EXCEPT on the
@@ -2977,6 +2981,15 @@ export async function apply(ctx, config) {
                 // the default, so an unknown value is not persisted as-is.
                 backend: body.backend === 'openssh' ? 'openssh' : 'native',
                 sshBinary: String(body.sshBinary || '').trim(),
+                // Issue #54: the per-machine `dsh web` launch command was only
+                // ever writable by the deploy flow or by hand-editing
+                // machines.json — the README told users to set it and the
+                // settings UI offered nowhere to type it. It is an ordinary
+                // machine field now; empty means "fall back to the global
+                // webAttachCommand".
+                webAttachCommand: body.webAttachCommand === undefined
+                  ? String((prev && prev.webAttachCommand) || '')
+                  : String(body.webAttachCommand || '').trim(),
                 proxy: body.proxy && body.proxy.host ? {
                   host: String(body.proxy.host),
                   port: Number(body.proxy.port) || 22,
@@ -3452,12 +3465,17 @@ export async function apply(ctx, config) {
             if (live) { try { await live.close() } catch { /* already torn down */ } }
             const machine = machines.find((m) => m.id === machineId)
             if (!machine) return sendJson(res, 404, { ok: false, error: `机器不存在：${machineId}` })
+            const attachPool = poolForMachine(identityOf(machine))
             const attach = new WebAttach({
               localPortStart: config.webAttachPortStart,
+              // Issue #54: follow the chosen pool's lifecycle so a dropped SSH
+              // connection degrades to "disconnected" and then self-heals,
+              // instead of leaving a dead client that crashes the host process.
+              trackPool: true,
             })
             try {
               await attach.open({
-                pool: poolForMachine(identityOf(machine)),
+                pool: attachPool,
                 machineId,
                 command: String(body.command || '').trim() || webAttachCommandFor(machine),
                 profile: 'web',

package/lib/pool.js

@@ -26,6 +26,42 @@ export function createPool(config, opts) {
     : new SshPool(config, opts)
 }
 
+/**
+ * Run one `forwardOut` and resolve with the resulting channel.
+ *
+ * ssh2 reports a dead connection by THROWING synchronously —
+ * `if (!this._sock || !isWritable(this._sock)) throw new Error('Not connected')`
+ * (ssh2 >= 1.16, `Client.forwardOut`) — and never calls the callback, so a
+ * callback-only error path cannot guard this call (issue #54). Two further
+ * consequences justify a shared helper rather than an inline try/catch:
+ *
+ *   • inside a `new Promise(executor)` a bare throw rejects nothing: it becomes
+ *     an unhandled REJECTION and leaves the promise pending forever;
+ *   • called from a `net.Server` connection handler the throw escapes to the
+ *     process top level and kills the host.
+ *
+ * This guards the CALLER's side of the contract rather than assuming one
+ * backend's behaviour: the system-OpenSSH backend (lib/openssh.js `forwardOut`)
+ * already converts its own spawn failure into a callback error, so for it the
+ * try/catch below is dead code — but a backend is free to throw, and the one
+ * that does must not be able to take the process down.
+ *
+ * @param {object} client - an ssh2 Client or OpenSshConnection.
+ * @param {object} spec - `srcHost`/`srcPort`/`dstHost`/`dstPort`.
+ * @returns {Promise<object>} the forwarded channel / duplex stream.
+ */
+export function forwardOutChannel(client, { srcHost = '127.0.0.1', srcPort = 0, dstHost, dstPort }) {
+  return new Promise((resolve, reject) => {
+    // `reject` is called at most once: a callback that fires after a successful
+    // throw-path rejection would be a no-op, which Promise guarantees.
+    try {
+      client.forwardOut(srcHost, srcPort, dstHost, dstPort, (err, channel) => (err ? reject(err) : resolve(channel)))
+    } catch (err) {
+      reject(err)
+    }
+  })
+}
+
 /**
  * The ACTIVE pool: one long-lived object whose concrete implementation can be
  * swapped when the current machine's transport backend changes.
@@ -262,9 +298,11 @@ export class SshPool {
         }, { knownHostsFile: this._knownHostsFile })
         const pclient = await this.proxyPool.connect()
         if (!isCurrent()) throw new Error('ssh target changed during proxy connect')
-        sock = await new Promise((res, rej) => {
-          pclient.forwardOut('127.0.0.1', 0, this.config.host, this.config.port, (e, ch) => (e ? rej(new Error('proxy forward to target failed: ' + ((e && e.message) || e))) : res(ch)))
-        })
+        try {
+          sock = await forwardOutChannel(pclient, { dstHost: this.config.host, dstPort: this.config.port })
+        } catch (e) {
+          throw new Error('proxy forward to target failed: ' + ((e && e.message) || e))
+        }
       } catch (err) {
         return fail(err)
       }

package/lib/web-attach.js

@@ -222,14 +222,34 @@ export class WebAttach {
    * @param {object} [opts.net] - a `node:net`-compatible module (tests).
    * @param {number} [opts.localPortStart] - first local port to try.
    * @param {number} [opts.localPortMax] - how many ports to try before failing.
+   * @param {boolean} [opts.trackPool] - follow the pool across reconnects so a
+   *   dropped SSH connection degrades to "disconnected" and then SELF-HEALS
+   *   instead of being a permanent dead end (issue #54). `true` in production.
    */
   constructor(opts = {}) {
     this.net = opts.net || net
-    this.localPortStart = opts.localPortStart || 3088
-    this.localPortMax = opts.localPortMax || 50
+    // `??`, not `||`: port 0 is a MEANINGFUL value here (let the OS pick), and
+    // `0 || 3088` silently turned "let the OS choose" into a bind on a fixed
+    // port. An explicit 0 now survives, which is also what lets a test ask for a
+    // port without risking a collision with something really listening.
+    this.localPortStart = opts.localPortStart ?? 3088
+    this.localPortMax = opts.localPortMax ?? 50
+    /** Whether the pool's lifecycle hooks are ours to install. */
+    this.trackPool = opts.trackPool !== false
     /** @type {import('node:net').Server|null} */ this.server = null
     /** @type {Set<import('node:net').Socket>} */ this.sockets = new Set()
     /** @type {object|null} */ this.client = null
+    /** The pool this session borrowed its connection from (may be null). */
+    this.pool = null
+    /** Pool hooks we installed, so close() can hand them back untouched. */
+    this.prevOnReady = null
+    this.prevOnCloseHook = null
+    this.hookedPool = null
+    this._installedOnReady = null
+    this._installedOnClose = null
+    this.attachedClient = null
+    /** Bound listener, kept so it can be removed from the client. */
+    this.onClientClose = null
     this.localPort = 0
     this.remotePort = 0
     this.token = ''
@@ -239,6 +259,28 @@ export class WebAttach {
     this.machineId = ''
     this.command = ''
     this.startedAt = 0
+    /** Launch knobs remembered so a restart after a drop uses the same ones. */
+    this.waitSeconds = 0
+    this.omittedNoOpen = false
+    /** True while a reconnect-triggered re-resolve is in flight. */
+    this._resolving = false
+    /** True once the borrowed connection has been lost (drives recovery). */
+    this.connectionLost = false
+    /** undefined = "not asked yet"; false = the remote process is provably gone. */
+    this._remoteAlive = undefined
+    /** Set by close(): nothing may re-arm the tunnel afterwards. */
+    this.closed = false
+    /** Set once the borrowed connection has gone away (see _clientLost). */
+    this.lastError = ''
+    /**
+     * A listener that throws EARNS an 'error' event on the emitting object, and
+     * an 'error' with no listener is itself fatal — the very crash this module
+     * exists to prevent. Nothing here is expected to throw, but a lifecycle
+     * callback running on someone else's event loop must never be the reason
+     * the host process dies, so both hooks are wrapped.
+     */
+    this._onReady = (client) => { try { this._attach(client) } catch { /* never fatal */ } }
+    this._onPoolClose = () => { try { this._clientLost('ssh connection closed') } catch { /* never fatal */ } }
   }
 
   /** Whether the tunnel is currently listening. */
@@ -268,11 +310,17 @@ export class WebAttach {
     if (!pool) throw new Error('web-attach: a machine pool is required')
     this.machineId = String(machineId || '')
     this.command = command
+    this.waitSeconds = Number(waitSeconds) || 45
 
     const exec = spec.exec || ((cmd, opts) => pool.exec(cmd, opts))
     // Connecting first also surfaces credential/host-key problems BEFORE we
-    // start a remote process we would then have to clean up.
-    this.client = await pool.connect()
+    // start a remote process we would then have to clean up. `_attach` (rather
+    // than a bare assignment) is what subscribes to the connection's 'close',
+    // so the loss is noticed the moment it happens instead of on the next
+    // request — which is when the old code let ssh2 throw 'Not connected' from
+    // inside a socket callback and take the host process with it (issue #54).
+    this._attach(await pool.connect())
+    this._followPool(pool)
 
     if (existingUrl) {
       const parsed = parseWebStart(`dsh web: ${existingUrl}`)
@@ -398,24 +446,334 @@ export class WebAttach {
     })
   }
 
+  /**
+   * Borrow the given connection AND subscribe to its lifecycle.
+   *
+   * Idempotent for the same client (open() calls it once, the pool's `onReady`
+   * calls it again on every reconnect), and it always drops the previous
+   * client's listener first, so one session never accumulates listeners.
+   *
+   * @param {object|null} client - the live ssh2 client / OpenSshConnection.
+   */
+  _attach(client) {
+    if (!client) return
+    if (this.attachedClient && this.attachedClient !== client && this.onClientClose) {
+      // A different client replaced the one we borrowed (pool reconnect). Stop
+      // listening to the old one; its own 'close' has either fired already or
+      // belongs to a connection nobody uses any more.
+      try { this.attachedClient.removeListener('close', this.onClientClose) } catch { /* already gone */ }
+    }
+    this.client = client
+    if (this.attachedClient === client) return
+    this.attachedClient = client
+    this.onClientClose = () => { this._clientLost('ssh connection closed') }
+    // Without this, the object keeps handing out a connection that is already
+    // closed, and `forwardOut` then throws SYNCHRONOUSLY (issue #54).
+    try { client.on('close', this.onClientClose) } catch { /* not an emitter: nothing to watch */ }
+  }
+
+  /** The borrowed connection is gone: keep the session, drop the dead handle. */
+  _clientLost(reason) {
+    this.client = null
+    this.connectionLost = true
+    this.lastError = String(reason || 'ssh connection closed')
+  }
+
+  /**
+   * Register lifecycle hooks on the chosen pool so this tunnel follows it.
+   *
+   * The pool is the one place that both NOTICES a dead connection and later
+   * obtains a fresh one, and it exposes exactly two hooks for that:
+   *   • `onCloseHook` — fires from `close()` and `invalidate()` (the latter is
+   *     the "channel open failed, the pooled connection died server-side"
+   *     self-heal path, which is the likeliest trigger);
+   *   • `onReady` — fires after a successful (re)connect.
+   *
+   * Both are SINGLE-SLOT properties that the plugin already uses for
+   * `ForwardManager` (index.js), so this session CHAINS them rather than
+   * clobbering the forwards manager, and `_detachPool()` restores exactly what
+   * was there — the plugin may legitimately have none, one, or both.
+   *
+   * A real reconnect is the only way the remote port can move, so once the pool
+   * reports a new connection we must re-resolve (token, port) from the remote
+   * log. `onReady` itself cannot await: the pool fires it with the client in
+   * hand, so the re-resolve is kicked off and its failure is recorded rather
+   * than thrown into the pool's callback.
+   *
+   * @param {object} pool - the pool this session attached through.
+   */
+  _followPool(pool) {
+    if (!this.trackPool || this.closed || !pool || this.hookedPool === pool) return
+    this._detachPool()
+    this.pool = pool
+    this.hookedPool = pool
+    const prevReady = typeof pool.onReady === 'function' ? pool.onReady : null
+    const prevClose = typeof pool.onCloseHook === 'function' ? pool.onCloseHook : null
+    this.prevOnReady = prevReady
+    this.prevOnCloseHook = prevClose
+    const installedReady = (client) => {
+      this._attach(client)
+      if (prevReady) { try { prevReady(client) } catch { /* the forwards manager's problem, not ours */ } }
+      // A reconnect lands on a NEW remote process only if the old one died with
+      // the machine; re-read the log to find out which. The re-resolve runs off
+      // the event loop because the pool cannot await it — a hook that throws
+      // would earn an 'error' event on the pool, and an unhandled rejection
+      // would be fatal.
+      if (!this.closed && this.remotePort && !this._resolving) {
+        this._resolving = true
+        Promise.resolve()
+          .then(() => this._refreshRemotePort())
+          .catch((err) => { this.lastError = String((err && err.message) || err) })
+          .then(() => { this._resolving = false })
+      }
+    }
+    const installedClose = () => {
+      this._clientLost('ssh connection closed')
+      if (prevClose) { try { prevClose() } catch { /* never mask our own report */ } }
+    }
+    this._installedOnReady = installedReady
+    this._installedOnClose = installedClose
+    pool.onReady = installedReady
+    pool.onCloseHook = installedClose
+  }
+
+  /**
+   * Hand the pool's hooks back.
+   *
+   * Each slot is restored ONLY when it still holds the wrapper this session
+   * installed. The pool's hooks are single-slot, so if something else has taken
+   * the slot over in the meantime, putting a stale callback back would be worse
+   * than leaving it alone — it would silently disconnect a newer owner.
+   */
+  _detachPool() {
+    const pool = this.hookedPool
+    const mineReady = this._installedOnReady
+    const mineClose = this._installedOnClose
+    this.hookedPool = null
+    this._installedOnReady = null
+    this._installedOnClose = null
+    if (!pool) return
+    if (mineReady && pool.onReady === mineReady) pool.onReady = this.prevOnReady
+    if (mineClose && pool.onCloseHook === mineClose) pool.onCloseHook = this.prevOnCloseHook
+    this.prevOnReady = null
+    this.prevOnCloseHook = null
+  }
+
+  /**
+   * True when the borrowed connection was LOST and this is a session we can
+   * recover: we launched the remote process ourselves (so we hold its PID and
+   * log) and the tunnel is listening (so clients can actually be served).
+   *
+   * The `connectionLost` flag is deliberately separate from `this.client`: the
+   * pool's `onReady` re-attaches the new client BEFORE the re-resolve runs, so a
+   * check on `!this.client` would be false by then and recovery would never
+   * happen.
+   */
+  get _needsReResolve() {
+    return !!(this.connectionLost && !this.closed && this.logPath && this.remotePid && this.localPort)
+  }
+
+  /**
+   * Re-resolve the remote port after a reconnect, restarting the remote `dsh web`
+   * when it did not survive.
+   *
+   * Reaching a remote process needs a live SSH connection, so this reconnects
+   * through the pool first — the pool reports `onReady` for that same client in
+   * production, and in a test double the callback simply never fires.
+   */
+  async _refreshRemotePort() {
+    if (!this._needsReResolve) return
+    const pool = this.pool
+    if (!pool || (typeof pool.connect !== 'function' && typeof pool.exec !== 'function')) return
+    const exec = (cmd, opts) => (typeof pool.exec === 'function'
+      ? pool.exec(cmd, opts)
+      : Promise.reject(new Error('web-attach: the pool cannot run commands')))
+    if (!this.client) await pool.connect()
+    const match = await this._resolveRemotePort(exec)
+    this.remotePort = match.port
+    if (match.token) this.token = match.token
+    this.connectionLost = false
+    this.lastError = ''
+  }
+
+  /**
+   * Read this session's remote log and decide which port is live.
+   *
+   * The startup line is the ONLY source of the port (the launch deliberately
+   * uses `--port 0`), so after the remote process died and was restarted the log
+   * holds BOTH lines — the dead one and the new one — and neither position
+   * identifies the live one. Evidence decides:
+   *   • a process that is still alive on the remote is probed first, and when
+   *     the port it is LISTENING on is one of the logged ports, that is the
+   *     answer (the `dsh web: …` line names its own port, so this is a
+   *     confirmation rather than a second guess);
+   *   • otherwise the newest logged port wins, which is right in every
+   *     single-process case and is the best available answer while the remote is
+   *     still booting (the next reconnect retries).
+   *
+   * @param {(cmd: string, opts?: object) => Promise<{stdout: string}>} exec - remote exec.
+   * @returns {Promise<{port: number, token: string, restarted: boolean}>}
+   */
+  async _resolveRemotePort(exec) {
+    this._remoteAlive = await this._remoteProcessAlive(exec)
+    if (!this._remoteAlive) return this._restartRemote(exec)
+
+    let out = ''
+    try {
+      const res = await exec(`cat "$HOME/${this.logPath}" 2>/dev/null`, { timeoutMs: 15000 })
+      out = String((res && res.stdout) || '')
+    } catch { /* an unreadable log: the listening probe below is the fallback */ }
+    const lines = [...out.matchAll(/dsh web:\s*(http:\/\/[^\s]+)/g)]
+      .map((m) => parseWebStart(`dsh web: ${m[1]}`))
+      .filter(Boolean)
+
+    // What the recorded process actually listens on beats any guess from the
+    // log, because a killed-and-restarted remote leaves BOTH startup lines in
+    // the log and neither position says which one is live.
+    const listening = await this._listeningRemotePort(exec)
+    if (listening) {
+      const match = lines.find((l) => l.port === listening)
+      return { port: listening, token: (match && match.token) || this.token, restarted: false }
+    }
+    if (lines.length) {
+      const newest = lines[lines.length - 1]
+      return { port: newest.port, token: newest.token, restarted: false }
+    }
+    // Alive but silent and not listening yet: the remote is booting. Keep the
+    // last known port and let the next reconnect re-resolve.
+    return { port: this.remotePort, token: this.token, restarted: false }
+  }
+
+  /**
+   * Whether the remote process THIS session started still exists.
+   *
+   * Verified through `/proc`, which is Linux-only; a host that cannot answer (or
+   * a failed probe) is treated as ALIVE on purpose. Restarting a server that was
+   * never dead would spawn a second one and leak a port, whereas assuming life
+   * merely retries a port that turns out to be stale.
+   *
+   * @param {(cmd: string, opts?: object) => Promise<{stdout: string}>} exec - remote exec.
+   * @returns {Promise<boolean>}
+   */
+  async _remoteProcessAlive(exec) {
+    const pid = Number(this.remotePid) || 0
+    if (pid < 1) return true
+    try {
+      const res = await exec(
+        `if [ -d /proc ]; then { [ -d /proc/${pid} ] && echo ALIVE; } || echo GONE; else echo ALIVE; fi`,
+        { timeoutMs: 15000 },
+      )
+      return !/GONE/.test(String((res && res.stdout) || ''))
+    } catch { return true }
+  }
+
+  /**
+   * Ask the remote which loopback port the recorded PID listens on (0 = none).
+   *
+   * Two `/proc` reads are needed because a TCP listener appears in a socket
+   * table (`/proc/net/tcp{,6}`), not in that process's link list: the fd
+   * symlinks give the socket INODE, and the table maps that inode to a port.
+   * Matching on the inode rather than the port is what makes this an
+   * observation instead of a second guess.
+   */
+  async _listeningRemotePort(exec) {
+    const pid = Number(this.remotePid) || 0
+    if (pid < 1) return 0
+    let inodes = ''
+    try {
+      // `ls -l` on a process's own fds needs no privileges for the same uid.
+      const res = await exec(
+        `ls -l /proc/${pid}/fd 2>/dev/null | sed -n 's/.*socket:\\[\\([0-9]*\\)\\].*/\\1/p' | sort -u | tr '\\n' ' '`,
+        { timeoutMs: 15000 },
+      )
+      inodes = String((res && res.stdout) || '').trim()
+    } catch { return 0 }
+    if (!inodes) return 0
+    const want = new Set(inodes.split(/\s+/).filter(Boolean))
+    // `/proc/net/tcp` addresses are little-endian hex, so loopback is
+    // `0100007F` (v4) and `00000000000000000000000001000000` (v6 `::1`).
+    const LOOPBACK = new Set(['0100007F', '00000000000000000000000001000000'])
+    for (const file of ['/proc/net/tcp', '/proc/net/tcp6']) {
+      let text = ''
+      try {
+        const res = await exec(`cat ${file} 2>/dev/null`, { timeoutMs: 15000 })
+        text = String((res && res.stdout) || '')
+      } catch { continue }
+      for (const line of text.split('\n').slice(1)) {
+        const cols = line.trim().split(/\s+/)
+        // sl local_address rem_address st tx:rx tr:tm->when retrnsmt uid timeout inode
+        if (cols.length < 10) continue
+        if (cols[3] !== '0A') continue // TCP_LISTEN
+        if (!want.has(cols[9])) continue
+        const [addr, portHex] = String(cols[1]).split(':')
+        if (!LOOPBACK.has(String(addr).toUpperCase())) continue
+        const port = parseInt(portHex, 16)
+        if (Number.isInteger(port) && port > 0 && port < 65536) return port
+      }
+    }
+    return 0
+  }
+
+  /**
+   * Relaunch the remote `dsh web` because the previous process is gone.
+   *
+   * A restart CANNOT change the listening port locally, and a caller holding a
+   * stale port silently talks to the wrong place at worst and hangs at best, so
+   * the two facts the caller needs are checked: this is a session that launched
+   * its own process (an attach onto someone else's DSH stays hands-off and can
+   * never restart it), and recovery is possible at all (`_refreshRemotePort`
+   * has already returned early when it is not).
+   */
+  async _restartRemote(exec) {
+    const command = this.command || 'dsh'
+    const waitSeconds = this.waitSeconds || 45
+    const timeoutMs = Math.max(30000, (waitSeconds + 20) * 1000)
+    let out = String(await this._launch(exec, { command, profile: 'web', logPath: this.logPath, waitSeconds, timeoutMs }, this.omittedNoOpen === true))
+    if (launchFailed(out) && /unknown option/i.test(out) && /--no-open/.test(out)) {
+      out = String(await this._launch(exec, { command, profile: 'web', logPath: this.logPath, waitSeconds, timeoutMs }, true))
+      this.omittedNoOpen = true
+    }
+    this.remotePid = parseRemotePid(out) || this.remotePid
+    const parsed = parseWebStart(out)
+    if (!parsed) {
+      const tail = out.split(TAIL_MARKER).slice(1).join(TAIL_MARKER).trim()
+      throw new Error('web-attach: the remote DSH could not be restarted after the SSH'
+        + ' connection dropped.' + explainLaunchFailure(tail || out) + (tail ? ` Remote output: ${tail}` : ''))
+    }
+    return { port: parsed.port, token: parsed.token, restarted: true }
+  }
+
   /** Carry one local socket to the remote web port over SSH. */
   _pipe(socket) {
     if (!this.client) { try { socket.destroy() } catch { /* already gone */ } return }
-    this.client.forwardOut('127.0.0.1', 0, '127.0.0.1', this.remotePort, (err, channel) => {
-      if (err) { try { socket.destroy() } catch { /* already gone */ } return }
-      this.sockets.add(socket)
-      socket.pipe(channel)
-      channel.pipe(socket)
-      const kill = () => {
-        try { socket.destroy() } catch { /* already gone */ }
-        try { channel.close() } catch { /* already closed */ }
-        this.sockets.delete(socket)
-      }
-      socket.on('error', kill)
-      channel.on('error', kill)
-      socket.on('close', kill)
-      channel.on('close', kill)
-    })
+    // ssh2's forwardOut does NOT report a dead connection through its callback:
+    // when the socket is gone it THROWS 'Not connected' synchronously
+    // (ssh2/lib/client.js: `if (!this._sock || !isWritable(this._sock)) throw`)
+    // and the callback below is never reached — so `if (err)` cannot guard this
+    // path. Uncaught, that throw travels net.Server → TCP.onconnection and kills
+    // the whole host process (issue #54: every page refresh after the pooled
+    // connection dropped took the session, the browser and the remote orphan
+    // down with it). A dead tunnel is a UI state, not a reason to exit.
+    try {
+      this.client.forwardOut('127.0.0.1', 0, '127.0.0.1', this.remotePort, (err, channel) => {
+        if (err) { try { socket.destroy() } catch { /* already gone */ } return }
+        this.sockets.add(socket)
+        socket.pipe(channel)
+        channel.pipe(socket)
+        const kill = () => {
+          try { socket.destroy() } catch { /* already gone */ }
+          try { channel.close() } catch { /* already closed */ }
+          this.sockets.delete(socket)
+        }
+        socket.on('error', kill)
+        channel.on('error', kill)
+        socket.on('close', kill)
+        channel.on('close', kill)
+      })
+    } catch (err) {
+      this._clientLost(String((err && err.message) || err))
+      try { socket.destroy() } catch { /* already gone */ }
+    }
   }
 
   /**
@@ -462,6 +820,15 @@ export class WebAttach {
    * @param {(cmd: string) => Promise<unknown>} [opts.exec] - remote exec.
    */
   async close({ stopRemote = false, exec } = {}) {
+    // Stop following the pool BEFORE any await: a reconnect landing mid-teardown
+    // must not re-arm the tunnel this call is in the middle of closing.
+    this._detachPool()
+    if (this.attachedClient && this.onClientClose) {
+      try { this.attachedClient.removeListener('close', this.onClientClose) } catch { /* already gone */ }
+    }
+    this.attachedClient = null
+    this.onClientClose = null
+    this.pool = null
     for (const socket of [...this.sockets]) {
       try { socket.destroy() } catch { /* already gone */ }
     }
@@ -475,5 +842,9 @@ export class WebAttach {
       await Promise.resolve(exec(buildStopCommand(this.remotePid, this.logPath))).catch(() => {})
     }
     this.client = null
+    // The recorded PID and log path are FACTS about this session (the UI shows
+    // them, and `stopRemote` addresses them), so they survive; `closed` is what
+    // stops recovery work from being re-armed after teardown.
+    this.closed = true
   }
 }

package/lib/web-deploy.js

@@ -351,6 +351,31 @@ export function versionAtLeast(a, b) {
 /** The first dsh release whose node-pty ships Linux prebuilds (measured). */
 export const PTY_FIXED_VERSION = '0.1.5-rc.2'
 
+/**
+ * Minimum Node the remote must run, and the reason it is exactly this number.
+ *
+ * DSH's boot path imports `parseEnv` from `node:util`, and that export only
+ * exists from **20.12.0** (Node 21.7.0 and later have it too). Measured on a
+ * real host with two nodes installed:
+ *
+ *   /usr/bin/node (v18.19.1)                          → parseEnv: undefined
+ *   ~/.nvm/versions/node/v24.22.0/bin/node (v24.22.0) → parseEnv: function
+ *
+ * The failure mode is what makes this worth a BLOCKER rather than a warning: npm
+ * only prints EBADENGINE (it does not refuse), so all ~535 packages install
+ * cleanly and the crash arrives afterwards as
+ *
+ *   SyntaxError: The requested module 'node:util' does not provide an export
+ *   named 'parseEnv'    at .../@deepseek-ai/dsh-app-boot/lib/index.js:4
+ *
+ * which does not read as "your node is too old". Checking the version BEFORE the
+ * install is the only way to turn that into an actionable message.
+ *
+ * Reference: Node.js 20.12.0 release notes, "Loading and parsing environment
+ * variables" — https://nodejs.org/en/blog/release/v20.12.0
+ */
+export const MIN_NODE_VERSION = '20.12.0'
+
 /**
  * Turn facts into a verdict: what is wrong, why, and what to do.
  *
@@ -394,6 +419,17 @@ export function judgeProbe(facts, opts = {}) {
     add('NO_NODE', 'blocker', '远端没有 node',
       '自动部署需要 node 与 npm。',
       '先在该机器安装 Node.js（nvm 或系统包管理器），再回来重试。')
+  } else if (f.nodeVersion && !versionAtLeast(f.nodeVersion, MIN_NODE_VERSION)) {
+    // The install itself SUCCEEDS on this node — npm only warns (EBADENGINE) —
+    // and the failure surfaces later as a parseEnv import error that does not
+    // read as a version problem. So the check has to happen before the install.
+    add('NODE_TOO_OLD', 'blocker',
+      `远端 node ${f.nodeVersion} 版本过低（需要 ≥ ${MIN_NODE_VERSION}）`,
+      `dsh 启动时要 import node:util 的 parseEnv，该导出从 Node ${MIN_NODE_VERSION} 起才有。`
+      + '在这个版本上 npm 只会给 EBADENGINE 警告、仍然把包装完，'
+      + '直到启动时才崩：SyntaxError: The requested module \'node:util\' does not provide an export named \'parseEnv\'。',
+      `升级该机器的 node 到 ${MIN_NODE_VERSION} 以上（例如 nvm install 22），`
+      + '并把 `webAttachCommand` 指向新 node 的绝对路径（如 ~/.nvm/versions/node/v22.x/bin/node <前缀>/node_modules/@deepseek-ai/dsh/lib/bin.js）。')
   }
   if (!f.npm) {
     add('NO_NPM', 'blocker', '远端没有 npm',
@@ -474,7 +510,13 @@ export function judgeProbe(facts, opts = {}) {
   const blockers = findings.filter((x) => x.severity === 'blocker')
   // A Windows remote with Git Bash can be installed into: pool.exec pipes every
   // command through `bash -s`, so the POSIX plan works there.
-  const canAutoInstall = !!f.node && !!f.npm && (!f.windows || !!f.gitBash)
+  //
+  // A node older than MIN_NODE_VERSION makes an install POINTLESS as well as
+  // failing: the packages land, then the binary cannot boot. Promising
+  // "can auto-install: yes" there is what sent the reporter of issue #54 through
+  // a 535-package install that ended in a parseEnv SyntaxError.
+  const nodeUsable = !!f.node && (!f.nodeVersion || versionAtLeast(f.nodeVersion, MIN_NODE_VERSION))
+  const canAutoInstall = nodeUsable && !!f.npm && (!f.windows || !!f.gitBash)
 
   // Which command should the attach flow use? A verified deployment wins, then a
   // usable dsh already on PATH.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-remote",
-  "version": "0.8.44",
+  "version": "0.8.46",
   "description": "Remote-work assistant for DeepSeek Harness: connect SSH (password/key/agent/keyboard-interactive/proxy jump), pick a remote workspace, operate on it with 22 rw_* tools (incl. rw_edit/rw_stat/rw_mkdir/rw_remove/rw_move/rw_forward), conflict-aware mirror sync, one-click remote dsh deploy + web UI attach, port forwarding, optional side-bar remote file editing, audit log, keychain passwords.",
   "license": "MIT",
   "author": "flymysql <flyphp@outlook.com>",
@@ -84,6 +84,6 @@
     "semver": "^7.8.5"
   },
   "scripts": {
-    "test": "node --import ./test/setup-telemetry-off.mjs --test"
+    "test": "node --import ./test/setup-telemetry-off.mjs --test --test-timeout=20000 --test-force-exit"
   }
 }