dsh-remote-agent 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -9,6 +9,376 @@
 
 ---
 
+## [0.9.0] - 2026-10-17
+
+### ⚠ 行为变更：exec 任务默认超时 1 小时 → 10 分钟
+
+**升级前请读这一段。**
+
+此前 `exec` 任务实际拿到的超时是 **60 分钟**（不论文档说什么）。
+原因是三处缺陷叠加（详见下方「代码审查修复」的 H1）：
+
+1. `tools.js` 里有个 TDZ 自引用 bug，让分模式默认值那条分支永远走不到
+2. `hub/index.js` 用 `numOr(defaults.timeoutMs, 1h)` 兜底，把 `explicitTimeoutMs`
+   压成恒 3600000 → 优先级 `args > 显式配置 > 分模式默认` 被压扁成「恒 1h」
+3. 面板 dispatch 同样写死 `?? 3600000`
+
+三处都修了，所以现在：
+
+| 模式 | 默认超时 | 意味着 |
+|---|---|---|
+| `exec` | **10 分钟**（`EXEC_DEFAULT_TIMEOUT_MS`） | 失控命令最多跑 10 分钟就被杀，不再占机一小时 |
+| `agent` | 1 小时（不变） | agent 任务本来就需要长窗口 |
+
+**如果你有 exec 任务本来就要跑 10 分钟以上**，显式传 `timeoutMs`：
+
+- 工具：`remote_task({ ..., timeoutMs: 1800000 })`（30 分钟）
+- 面板：派发表单的「超时毫秒」字段
+- 配置：`defaults.timeoutMs`（作用于所有任务，优先于分模式默认）
+
+### 修复：代码审查（1 High + 3 Medium + 6 Low）
+
+WorkBuddy 2026-10-17 对 `lib/` 全部 26 个源文件（约 19,900 行）做全量审查，
+发现的缺陷逐条核实为真后修复。
+
+#### H1（High）tools.js TDZ 自引用
+
+```js
+const v = validateTaskStart({ constraints: {
+  timeoutMs: ... ?? (v.spec.mode === 'exec' ? ... : ...)
+                         ^ v 正在初始化，进入 TDZ
+```
+
+`??` 链左侧全空时抛 `ReferenceError`。
+
+**为什么 829 个测试全绿仍带此 bug**：e2e helper 恒传 `timeoutMs`（`??` 第一项
+短路）、单测构造时 defaults 也总有值 —— 该分支**从未被求值**。这是典型的
+「测试环境与生产装配层差异造成的盲区」。
+
+生产没炸但更糟：`normalizeConfig` 的 1h 兜底让 TDZ 永不触发，却把分模式
+默认压成死代码（见上方行为变更）。
+
+修复：改用已在 `v` 之前求值的 `routeMode`。
+
+#### M1（Medium）relay 第三条 hub 写路径漏背压
+
+C1-1 的背压修复只加在 `broadcastHubs` / `broadcastHubsBinary` 两条路径上，
+**node 上行帧 → 全 hub 广播是第三条**，漏网。而 `ws.js` 的 `overBudget` 只是
+查询属性、不自动断连，所以这条路径的写缓冲**没有任何上限检查**。
+
+实测过的后果形态：单个停滞对端把 relay `writableLength` 推到 339.8 MiB、
+RSS 419 MiB。中继是 NAT 场景唯一会合点、单进程常驻，OOM 即全体断连。
+
+#### M2（Medium）grep 单文件分支无大小护栏
+
+目录扫描路径有 `GREP_FILE_MAX`（2MB）与 `GREP_TIME_MS`（10s）双护栏，
+但 `st.isFile()` 分支**直接 `readFileSync` 全文**。触发形态：`remote_grep` 的
+path 指向工作区内巨大文本文件（应用日志 / 数据库转储 / core dump）→
+副机 OOM + 同步阻塞事件循环。**这是一条可达的 DoS 面**（agent 自主选择 grep 目标）。
+
+#### M3（Medium）approveTask 节点不可达时删除任务
+
+原实现 `this.tasks.delete(taskId)` —— 任务从 hub 视图**彻底消失**（不是失败、
+不是挂起，是不存在），与该方法注释自称的「转 failed 终态」**直接矛盾**。
+
+后果：`remote_status` / 面板都查不到；`awaitTerminal` 等不到终态只能靠超时
+兜底（最长 1 小时+）；与 ui-routes 的 502 文案不符。
+
+修复：保留记录 + 置 FAILED + `error.code='node-unreachable'` + 唤醒等待者。
+
+#### Low 系列（修 6 条）
+
+- **L1** 副机 transport 缺 RelayLink 的两条并发不变式：
+  `connecting` 闸门（`start()` 被调两次会开两条 TCP 连接）、close 必须校验
+  `this.conn === conn`（否则陈旧连接的 close 把活着的新连接引用清掉 → 副机永久失联）
+- **L2** RESOURCE 分支 `rec` 未判空（影子节点竞态必抛 TypeError）
+- **L3** runner 的 active 注册晚于 `await createAgent`（窗口期内 cancel 返回
+  false，正是 #26-5 修过的形态复现）→ 改为先占位再 await
+- **L4** `E2E_REOFFER_DEBOUNCE_MS` 死常量 → 真正按 250ms 时间窗去抖
+  （⚠ 它是**实例字段**不是 static，必须经 `this.` 读）
+- **L5/L6/L7 未修**（记录在案）：relay 模式 hub 去重被中继层兜住、WS 版本校验
+  双方恒发 13、hub 空闲淘汰被副机 15s 心跳掩盖 —— 属一致性改进而非缺陷
+
+#### 测试
+
+新增 `test/code-review-regressions.test.js` **11 条**，覆盖 H1/M1/M2/M3/L1/L2/L4。
+**H1 的测试刻意不走 e2e helper**（那正是盲区成因）。
+
+### 文档：README 补「功能」章节
+
+用户指出「README 好像没有功能相关的介绍」—— 核实后发现**比这更严重**：
+
+- **版本号落后 4 个版本**（写 0.4.0，实际 0.8.x）
+- **工具数量写错**（写「7 个」，实际 **12 个**：8 个 `remote_*` + 4 个 fs 工具），
+  出现在架构图、目录表、工具速查三处
+- 确实没有功能总览章节
+
+新增「功能」六组：派任务 / 拿结果 / 翻文件 / 本地 IDE 打开（SMB）/ 自我诊断 /
+断连跨网安全。英文版同步。
+
+新增断言 83：**README 声明的工具数量必须等于代码里 `reg(` + `fsOp(` 的注册数**，
+两边任一变化立刻失败（做过负向验证）。
+
+### 关于 0.8.0 与 0.8.1（记录）
+
+0.8.0 的 publish 第一次报「假成功」（tarball 未落地），当时判断它卡在 staging
+并跳过发布了 0.8.1。事后查 registry 发现 **0.8.0 最终也发布成功了**
+（07:43:45，比 0.8.1 晚 3 分钟）—— 那次 `unpublish` 同样假成功。
+
+两个版本内容基本相同（都是 #26-4/#26-5 + EPERM 修复 + #27 完整版），
+不影响使用。教训：**npm publish 的成功/失败判定必须用 `Cache-Control: no-cache`
+读 registry 核实**，不能只看 exit code 或缓存副本。
+
+### 文档：README 补「功能」章节 + 修正 4 个版本号的漂移
+
+用户指出「README 好像没有功能相关的介绍」—— 核实后发现**比这更严重**：
+
+#### 1. 版本号落后 4 个版本
+
+```
+README L33:  | **状态** | 0.4.0 —— 主机侧端到端可用 ... |
+实际:        npm latest = 0.8.1
+```
+
+#### 2. 工具数量写错（7 → 12）
+
+README 写「7 个 remote_* 工具」，实际是 **12 个**（8 个 `remote_*` +
+4 个 fs 工具）。这个数字在 3 处出现（架构图、目录表、工具速查）。
+
+#### 3. 确实没有「功能」章节
+
+原结构是「五分钟上手 → 核心不变式 → 安装 → 用法」——「用法」里只有工具速查，
+**没有一个"这个插件能干什么"的总览**。读者只能从零散段落里拼。
+
+#### 修复
+
+新增「功能」章节，分六组：
+
+1. **把任务派给副机** —— 两种模式 / 两阶段审批 / dry-run / 仓库感知 /
+   负载感知 / 模型下拉 / 分模式超时 / 并发上限
+2. **拿结果但不搬整个工作区** —— handoff 卡 / 三分类 / 显式拉取 /
+   断点续传 / 变更 diff
+3. **直接翻副机的文件** —— 四个只读工具（不进任务队列）
+4. **用本地 IDE 打开副机文件** —— SMB 共享（含安全警示）
+5. **出问题能自己诊断** —— 环境体检 / 可达性自检 / 队列健康 /
+   运行中分组 / 取消真打断 / 审计日志
+6. **断连、跨网、安全** —— 断连不终止 / 两种传输 / E2E / 主机身份 /
+   凭证不出副机 / 零依赖
+
+另修：架构图工具数、状态行（0.4.0 → 0.8.1）、测试数表、
+`lib/` 目录表（补 `env-check.js`、`role: auto`）。
+
+英文版 `README.en.md` 同步（同样的 4 处漂移 + 完整 Features 章节）。
+
+#### 加了一条断言防复发（83）
+
+工具数量这种「数字漂移」是最容易积累的文档债务 —— 每次加工具都忘了改
+README，而读者会拿它当事实。所以新增断言：**数代码里 `reg(` + `fsOp(`
+的注册调用数，与 README 里的声明比对**，两边任一变化都会立刻失败。
+
+做了负向验证：临时把 README 的 12 改成 7，断言正确报错并给出
+「实际 12 个（reg=8 + fsOp=4）vs 声明 7 个」。
+
+```
+packaging   4 项
+doc-drift   118/118（+1）
+diag:inject 11 项
+tests       938（937 pass / 0 fail / 1 skip）
+lint        干净
+```
+
+### 功能：工作区共享（SMB）—— 用本地 IDE 打开副机的文件
+
+用户需求：想用本地 IDE 直接打开副机的项目目录。
+
+实现方式：把副机的工作区通过 Windows SMB 共享出去，主机
+`net use X: \\副机\dsh-work-...` 映射成盘符。
+
+#### ⚠ 这是本插件**唯一主动放宽安全边界**的功能
+
+开启后：
+- `roots` / `denyPaths` 全部失效（Windows 内核直读，插件拦不住）
+- 「清单先于字节」失效（中间产物、日志、`.env`、`.git` 密钥全部可见）
+- 新增凭证面（主机需要副机的 Windows 账号）
+
+所以按用户要求做了三重防护：
+
+1. **二次确认**（硬要求）—— `POST /share` 缺 `confirm: 'yes'` 直接 400，
+   没有默认通过的分支；面板上必须勾选「我知道风险」按钮才可点
+2. **只读 / 读写两选项**，默认**只读**（最小权限）；读写用 `-ChangeAccess`
+   而非 `-FullAccess`（后者会把共享 ACL 也交出去，主机能改权限）
+3. **不代执行** —— 只生成可复制的命令，执行由用户在管理员 PowerShell 里做
+
+#### 为什么不代执行（重要设计决策）
+
+`New-SmbShare` 需要管理员，而 DSH 通常以普通用户运行。Node 里提权的
+失败表现（静默失败 / 被安全软件拦 / 权限半生效）比让用户手动跑一条命令
+难排查得多。所以 `handleShareReq` 只做三件事：`probe`（探测管理员状态
+与已有共享）、`plan`（生成共享 + 映射命令）、`unshare-plan`（生成卸载命令）。
+
+#### 实现要点
+
+- **协议**：新增 `SHARE_REQ` / `SHARE_RES` 帧，与 `fs/req` 同款 RPC 模式
+- **E2E 强制**：`SHARE_REQ` 进 `E2E_REQUIRED_TYPES` —— 帧里含工作区
+  **绝对路径**（暴露副机目录结构），不许明文过中继
+- **独立 pending 表**：`sharePending` 与 `fsPending` 刻意分开 —— 混用会让
+  超时归因变模糊（一条 share 超时被记成 fs-timeout，排查方向直接跑偏）
+- **共享名稳定哈希**：同一目录反复开关共享名不变（不留孤儿共享），固定
+  `dsh-work-` 前缀便于识别与清理（不会误删用户的其它共享）
+- **共享目录过 roots 边界**：`plan` 的目录必须经 `resolveWorkspace`
+  （realpath + roots 前缀 + denyPaths），与 fs 工具同一条规则
+
+#### 文档
+
+新增 [docs/workspace-share.md](docs/workspace-share.md)：完整风险披露、
+三步用法（面板开启 → 副机管理员执行 → 主机映射）、关闭方法、常见问题
+（连不上怎么查、为什么共享名是怪名字、能不能共享整个盘、与 relay 的关系）。
+
+#### 测试
+
+- `test/share-service.test.js` **17 条**：共享名稳定性、只读/读写映射
+  （含"不得用 FullAccess"）、单引号转义防注入、探测不抛、跨平台安全
+- `test/share-integration.test.js` **12 条**：帧已声明、E2E 强制、
+  pending 表独立、断连 fail-fast、**二次确认是硬要求**、只读默认、
+  面板勾选框、不代执行、目录过 roots 边界
+
+doc-drift 新增 81（接线完整）、82（安全约束）。
+
+```
+packaging   4 项
+doc-drift   117/117
+diag:inject 11 项
+tests       926（925 pass / 0 fail / 1 skip）
+lint        干净
+```
+
+### 开箱即用：装完就能用，不用读文档
+
+用户标准（2026-10-17）："我希望是小白可用的，是开箱即用的"。
+
+此前有三道门槛，每一道都能让小白卡死：
+
+1. **`role` 默认 `''`** → 两台机器都要操作一次，不是开箱即用
+2. **`webserver` 没绑 `0.0.0.0`** → 副机永远连不上，且**完全静默**
+3. **副机表单 4 个字段** → 不知道节点 ID / 工作区填什么
+
+#### 核心设计：`role` 默认 `auto`，按 `hubUrl` 推断
+
+- 默认 `hub`：副机装完会以 hub 身份启动 —— 注册一个 nodeToken 为空、
+  不校验凭证的直连端点。**这是实打实的攻击面**（v0.7.0 之前的老问题）。
+- 默认 `''`：两台机器都要操作一次，不是开箱即用。
+- **默认 `auto`**：没配 `hubUrl` 就是主机（零操作），配了 `hubUrl` 就是副机
+  （贴完配对码零操作）。**两者都开箱即用，且不给副机开不该开的端点。**
+
+判据只有一条，但它是副机与主机最本质的区别：`hubUrl` 是副机独有字段，
+hub 侧根本不读它。配对码展开后必然产出 `hubUrl`，所以"贴码 = 自动变副机"。
+
+推断结果带 `inferred` 标记（`no-hubUrl` / `hubUrl`），面板可显示依据。
+显式写 `hub`/`worker`/`both` 永远优先于推断 —— 用户写的不该被猜掉。
+
+#### 包内 patch 让 hub 真能被访问
+
+```yaml
+- id: webserver
+  config:
+    host: '0.0.0.0'
+    port: 19387
+```
+
+不覆盖这一行，hub 只监听 loopback → 副机永远连不上。这是"能不能用"的决定性一条。
+
+**安全披露**（写进 patch 注释 + README + 面板 + 体检）：绑 `0.0.0.0` 意味着
+**DSH 的整个 Web GUI 也能被局域网访问**，不只是本插件的节点端点。DSH 自带
+Host/Origin 围栏 + cookie 鉴权，但暴露面确实变大了。用户可在 profile 里覆盖
+回 `127.0.0.1`（此时请改用 relay 模式）。
+
+优先级安全：`cordis.yml` 头注释说明应用顺序是 bundles → profile patch →
+--patch overlays，所以**用户 profile 里的同名行会覆盖包内默认**。
+
+#### 副机表单简化
+
+- **工作区预填**（Windows `D:\work`，其他 `~/work`）—— 此前是空，小白不知道
+  填什么：填相对路径被拒、填 `C:\` 太宽（安全边界）、填不存在的目录任务全报
+  `workspace-denied`
+- **节点 ID 折叠为高级选项** —— 默认取主机名，90% 用户不用改
+- **目录自动创建** —— 写入配置时 `mkdirSync(recursive)` 建不存在的 roots
+  （只建不改；相对路径跳过交给 resolveRoots 去拒；失败不阻塞写配置，
+  结果进 `warnings` 随响应回给面板）
+
+#### 首次自动体检
+
+面板加载时**自动跑一次**体检（`autoChecked` ref 保证只跑一次，不进 4 秒轮询）。
+此前要用户主动点「体检」按钮 —— 但小白不知道要点。
+
+#### 文档修正
+
+README 安装段重写。顺带修正一个**长期错误建议**：旧文档教用户写
+`inject: []`，那是错的 —— 副机 agent 的 ctx 继承插件的依赖声明，
+`inject: []` 会让 agent 没有任何 shell/文件工具，任务"跑完了但什么都没干"。
+正确写法是 `['tools', 'agentLoop', 'sessions']`。doc-drift 断言 30 也跟着改。
+
+#### 测试
+
+`test/out-of-box.test.js` **15 条**：auto 推断的四种情形（没 hubUrl / 有 hubUrl /
+空白 hubUrl / 显式 role 优先）、空 role 仍走引导、非法 role 不回退 hub、
+包内 patch 绑 0.0.0.0 + 安全披露、表单预填/折叠、自动建目录、首次自动体检。
+
+doc-drift 新增 79（auto + webserver 绑定）、80（表单简化 + 自动建目录 + 自动体检）。
+
+```
+packaging   4 项
+doc-drift   115/115
+diag:inject 11 项
+tests       897（896 pass / 0 fail / 1 skip）
+lint        干净
+```
+
+### 功能：环境体检（命令行为准，面板可见）
+
+这个插件最贵的失败**全是静默的**：
+
+- **webserver 绑 loopback** → 副机永远连不上，而主机侧毫无异常
+  （hub healthz 200、面板能开、工具都在）
+- **inject 缺服务** → hub 半死（路由活着但 8 个工具全丢）
+- **roots 不存在** → 任务全被 `workspace-denied` 拒绝
+
+用户只能猜"地址错了？token 错了？防火墙？"。
+
+本版新增 `lib/env-check.js`，命令行与面板**共用同一份逻辑**：
+
+- `envChecks()` 逐项检查：角色已配置 / inject 含必需服务 / **Web 服务绑在
+  可达地址** / 端口可用 / 防火墙 / roots 存在 / Tailscale / 副机在线
+- 每项都带 **detail（为什么）** 与 **fix（怎么修）** —— 不是干巴巴一个 ✗
+- `autoFix` 标记"我们能自动改配置修好它"
+
+三档处置（产品决策）：
+
+| 档位 | 做法 | 例子 |
+|---|---|---|
+| A 自动修 | 只改我们自己的配置，不下载任何东西 | webserver 绑 0.0.0.0、role/inject/roots |
+| B 提示 + 命令 | 给官方链接与命令，**不代下载** | Tailscale 未安装 |
+| C 只诊断 | 报清楚，让人判断 | 端口占用、防火墙、模型凭证 |
+
+**为什么不代下载**（边界）：零 npm 依赖 / 零构建是核心卖点。代用户下载第三方
+软件会让本插件变成软件分发方 —— 装哪个版本、从哪下、校验和怎么保证、装失败
+算谁的、供应链攻击面，全落在我们头上。所以档位 B 只给链接与命令。
+
+配套：
+
+- `applyHub` 新增**可达性自检**：调 `webServer.getOrigin()` 判定是否绑在
+  loopback，是则 `log('warn')` 带修法。自检本身包 try/catch ——
+  `getOrigin()` 在 listen 前会抛，**绝不能因为自检让 hub 起不来**
+- 面板新增**红色横幅**（绑 loopback 时）+「体检」按钮 + 体检结果区
+- 新增 `GET /api/remote-agent/ui/env-check` 路由
+
+测试：`test/env-check.test.js` **24 条**（loopback 识别的 8 种写法 +
+各检查项的通过与失败 + 修法必须具体 + warn 不计入 failed +
+config 传 null 不抛 + 渲染每条 ✗ 都带修法）。
+doc-drift 新增 77（三处齐备）、78（覆盖静默失败项 + 不代下载边界）。
+
+写测试时抓到 3 个真问题：`config: null` 会 TypeError、Tailscale 文案漏了
+"不代下载"说明、以及一个断言的正则转义层数写错。
+
 ## [0.8.0] - 2026-10-17
 
 ### 功能：#27 完整版 —— 模型清单自述 + 面板下拉

package/README.en.md

@@ -18,7 +18,7 @@ explicitly pull them.
 ┌──────────── main machine (hub) ────────────┐
 │  DSH · model · session logs · all credentials │
 │  ┌─ dsh-remote-agent ─────────────────────┐ │
-│  │ 7 remote_* tools + Web panel            │ │
+│  │ 12 remote_* tools + Web panel           │ │
 │  └────────────────────────────────────────┘ │
 └──────────────────▲──────────────────────────┘
                    │ node dials in (direct / relay)
@@ -32,15 +32,21 @@ explicitly pull them.
 
 | | |
 |---|---|
-| **Status** | 0.4.0 —— hub side end-to-end usable; real-runtime dial-in verified (standalone worker process → running DSH desktop hub, see [KNOWN-ISSUES §8](KNOWN-ISSUES.md)); both `exec` and `agent` paths verified on two real machines |
+| **Status** | 0.8.1 —— hub + worker end-to-end usable; both `exec` and `agent` paths verified on two real machines; CI covers Windows / macOS / Linux |
 | **DSH** | Desktop / CLI, verified on 0.2.0-rc.2 |
 | **Platforms** | Windows (fully verified) · Linux / macOS (CI covered) |
 | **Dependencies** | **Zero external npm dependencies** —— `node:` built-ins only |
 | **Node** | `^22.19.0 \|\| >=24.0.0` |
+| **Tests** | 938 (937 pass / 1 skip) · 117 doc-drift assertions · eslint strict |
 
 **Web panel**（sidebar → "远程同事" / Remote co-worker）：node list with CPU /
 memory badges, task dispatch, task states, result summaries, workspace changes,
-change diffs (unified diffs of text-file edits), final artifacts, log tail.
+change diffs (unified diffs of text-file edits), final artifacts, log tail,
+**environment health-check**, **workspace sharing (SMB)**, model dropdown.
+
+> **Works out of the box**: restart DSH after install and it just works. The
+> bundled patch defaults `role: auto` (no `hubUrl` ⇒ hub) and binds `webserver`
+> to `0.0.0.0:19387` (otherwise workers can never connect). See *Install* below.
 
 <p align="center">
   <img src="docs/screenshots/panel-main.png" width="720" alt="Web panel: nodes, dispatch form, task list">
@@ -106,6 +112,91 @@ Not interactive? One command does it all: `--role worker --hub-url
 
 ---
 
+## Features
+
+### 1. Dispatch tasks to the worker
+
+| Feature | What it does |
+|---|---|
+| **Two task modes** | `exec` runs a command directly (`npm run build`, `git pull`, bulk renames in `D:\work`); `agent` spins up an **independent agent session** on the worker that plans, calls tools and writes files itself |
+| **Two-phase approval** | `exec` is held for confirmation by default (`approval: 'manual'`) — nothing runs until a human approves. Guards against an AI dispatching a destructive command |
+| **Dry-run preview** | See which node it routes to, which model, which directory, what artifacts to expect — without dispatching |
+| **Repo-aware routing** | Workers report git repos under their `roots`; `remote_task({repo: 'my-project'})` finds the worker that has it |
+| **Load-aware routing** | Workers report CPU/memory/load every 30s; omitting `node` picks the least loaded |
+| **Model selection** | Panel offers a dropdown of the worker's **self-reported model list** (no guessing provider/model names); headless backends that can't take a model are **rejected before dispatch** |
+| **Per-mode timeouts** | `exec` defaults to 10 minutes (a runaway command shouldn't hold a machine for an hour); `agent` defaults to 1 hour |
+| **Concurrency cap** | Worker `maxConcurrent` (default 4); excess tasks queue, `remote_status` shows queue depth and oldest wait |
+
+### 2. Get results without moving the whole workspace
+
+| Feature | What it does |
+|---|---|
+| **Handoff card** | A task returns one card: summary + workspace changes + artifact manifest + exit code. **Not** the whole directory |
+| **Three-way artifact classification** | Files are `final` / `intermediate` / `other`; **only `final` can be pulled**. Logs, caches, `node_modules` stay on the worker |
+| **Explicit pull** | Pull individual files with `remote_pull`, glob filters supported |
+| **Resume on interruption** | A pull that drops mid-way doesn't restart: received bytes are kept and the retry continues from `startOffset` with `prefixSha256` verification |
+| **Change diff view** | Compares the workspace before/after, showing exactly which files changed and by how many bytes |
+
+### 3. Browse the worker's files directly (without touching the task queue)
+
+Four **read-only** tools over a separate `fs/req`↔`fs/res` frame — **they bypass the
+task queue and don't consume a concurrency slot**. Even when the worker is saturated
+with a long task, these answer instantly:
+
+| Tool | Purpose |
+|---|---|
+| `remote_ls` | List a directory (single level, paginated) |
+| `remote_read` | Read a file (text by line range; binaries return metadata only) |
+| `remote_grep` | Full-text search **locally** on the worker (pure JS, no process spawn) |
+| `remote_tree` | Directory tree summary (scanning happens on the worker; only structure returns) |
+
+Safety: paths must be inside the node's `roots`, `denyPaths` applies, symlinks are
+listed but never dereferenced.
+
+### 4. Open the worker's files in your local IDE (SMB share)
+
+The panel's *Workspace sharing* section publishes a worker directory over SMB; the
+hub maps it with `net use X: \\worker\dsh-work-...` and you can open it in local VS Code.
+
+> **⚠ This bypasses the plugin's security boundary** (`roots` / `denyPaths` stop
+> applying, intermediates and secrets become visible to the hub, and a new
+> credential surface appears). Requires **explicit second confirmation**; **read-only
+> by default**. Full risk notes: [docs/workspace-share.md](docs/workspace-share.md).
+
+### 5. Diagnose problems yourself
+
+| Feature | What it does |
+|---|---|
+| **Environment health-check** | One click in the panel checks 8 items: role config, `inject` dependencies, **whether the web server is bound to a reachable address**, port, firewall, `roots` existence, Tailscale, workers online. **Every item comes with a concrete fix**; auto-fixable ones are flagged |
+| **Reachability self-check** | At startup, verifies `webServer` isn't bound to loopback — if it is, workers can never connect while the hub side looks perfectly healthy. Logs a clear warning and shows a red banner |
+| **Queue health snapshot** | Workers report `queued` / `running` / `maxConcurrent` / oldest wait with each resource frame; both the panel and `remote_nodes` warn when the queue is jammed |
+| **"Running" grouping** | Running tasks are pinned on top with **elapsed time** (the only clue for "is it stuck?") |
+| **Cancel really aborts** | `remote_cancel` actually terminates the agent loop (not just setting a flag and letting it finish) |
+| **Audit log** | Dispatch / cancel / pull / approval all recorded (`~/.dsh-remote-agent/audit.jsonl`, rotated) |
+
+### 6. Disconnects, NAT traversal, security
+
+| Feature | What it does |
+|---|---|
+| **Disconnects don't kill tasks** | Relay down or hub restarted, the worker keeps running; `task/sync` reconciles on reconnect and **never re-runs completed work** |
+| **Two transports** | `direct` (same LAN / Tailscale); `relay` (both behind NAT, needs a VPS) |
+| **End-to-end encryption** | In relay mode, business frames use X25519 + AES-256-GCM; the relay only sees routing envelopes |
+| **Hub authentication** | Workers verify the hub: persistent ed25519 identity + fingerprint carried in the pairing code, TOFU-pinned on first connect |
+| **Credentials never leave the worker** | The protocol carries no model keys; the worker runs its own loop with its own model config |
+| **Zero npm dependencies** | `node:` built-ins only, no build step, `lib/` is the artifact |
+
+### Tool reference (12 tools)
+
+| Category | Tools |
+|---|---|
+| **Nodes** | `remote_nodes` (list + load + queue + model list) |
+| **Tasks** | `remote_task` (dispatch) · `remote_status` (progress) · `remote_cancel` (abort) |
+| **Approval** | `approval: 'manual'` holds the task → approve/reject from the panel or tools |
+| **Results** | `remote_handoff` (result card) · `remote_manifest` (artifact list) · `remote_pull` (fetch finals) · `remote_purge` (cleanup) |
+| **Files** | `remote_ls` · `remote_read` · `remote_grep` · `remote_tree` |
+
+---
+
 ## Core invariants
 
 These are the design premises of this package — read them before changing it:
@@ -335,7 +426,7 @@ computer.** Read **[SECURITY.md](SECURITY.md)** before deploying — especially:
 | Path | Purpose |
 |---|---|
 | `lib/index.js` | Plugin entry (role dispatcher: `role: hub` / `worker` / `both`) |
-| `lib/hub/**` | Hub side: node registry, 7 tools, subagent provider, UI routes |
+| `lib/hub/**` | Hub side: node registry, **12 tools**, subagent provider, UI routes, environment health-check |
 | `lib/hub/views.js` | **Shared projection layer** —— tools and the UI use the same field whitelist |
 | `lib/node/**` | Worker side: dial-in, task engine, artifact service, exec/agent backends |
 | `lib/client.js` | Browser half (Web panel) |