dsh-remote-agent 0.9.4 → 0.9.5

package/CHANGELOG.md

@@ -9,6 +9,86 @@
 
 ---
 
+## [0.9.5] - 2026-10-20
+
+> **紧急修复：0.9.4 装上后 DSH 报激活失败，插件显示"异常"。**
+>
+> ```
+> webserver: duplicate upgrade route "/api/remote-agent/node"
+> 1 entry did not activate remote-agent (dsh-remote-agent)
+> ```
+>
+> 0.9.4 在**全新启动**的场景是好的（我验证过单次 apply 注册一次），
+> 但**热重载会撞车** —— 而 DSH 在插件安装/升级后正是靠热重载生效的。
+
+### 🔴 根因：我们的注册不可回收，而宿主不会帮我们回收
+
+`webServer.registerUpgrade(path)` 在 DSH 里是**按 path 查表**的，同路径第二次
+注册直接抛（组合级契约，它这么做是对的）：
+
+```js
+registerUpgrade(route) {
+  if (this.upgrades.has(route.path)) throw new Error(`webserver: duplicate upgrade route "${route.path}"`)
+  this.upgrades.set(route.path, route)
+  return () => { this.upgrades.delete(route.path) }
+}
+```
+
+而本插件的注册全部收集在 `__disposers` 里，通过 `applyHub()` 的返回值
+（`disposeAll`）交给调用方保管 —— **但 DSH 不认识这个返回值**。热重载时它只
+重新 `apply`，不会回头调我们的 disposer。于是第二代的注册压在第一代的残留上：
+
+```
+第一代 apply → 注册 /api/remote-agent/node（表里有了）
+DSH 热重载 → 直接再 apply（不 dispose）
+第二代 apply → registerUpgrade(同一 path) → throw → 整个 entry 激活失败
+```
+
+0.9.3 及以前没暴露，是因为那时改完配置都靠"重启 DSH"（进程重来，表是新的）；
+0.9.4 是在插件管理页里安装/升级，走了热重载路径 —— 这是**场景差异，不是新引入的代码**。
+
+### 修复
+
+1. **apply 变成可重入**（`lib/index.js`）：按**注册宿主**（`ctx.webServer` 服务
+   实例，读不到时退回 ctx）记住"当前这一代"的 dispose；重新 apply 时先自己把
+   上一代摘干净再装。**不指望宿主帮我们清理** —— 这是唯一在各种宿主行为下都
+   成立的修法。
+2. **`disposeAll` 改成逆序**（`lib/hub/index.js`）：此前是正序跑的，会先拆运行时
+   （`registry.dispose()`）再拆工具，工具的 disposer 可能碰到已销毁的 registry。
+   现在与 cordis 的"逆序释放"语义一致。
+3. **独立监听加了 EADDRINUSE 有限重试**：重入时先 `close()` 旧监听、立刻用同一
+   端口重新 `listen`，在 Windows 上经常还拿不到端口（close 是异步的）。重试
+   4 次（200/400/600ms 退避），真被别的进程占用仍会如实报错。
+4. **`handles.dispose`**：apply 的返回值现在带一个顶层 `dispose()`，任何愿意调
+   它的宿主都能正确清理。
+
+### 为什么 CI 没拦住（第三次同类）
+
+仓库里所有测试桩都**比宿主宽松**：`hub-worker-e2e.test.js` 的 `makeCtx()` 里
+`register()` 是 `table.set()`（同名静默覆盖）、`registerUpgrade()` 只是再挂一个
+`server.on('upgrade')`。真宿主会抛，桩不会 —— **桩比宿主宽松 = 假绿灯**。
+
+新增 `test/webserver-contract.test.js`：照宿主源码造一个**重复即抛**的严格 ctx，
+钉住四条契约：
+
+- 单次 apply 只注册一条 upgrade 路由
+- **同一 ctx 重复 apply 不抛**（就是本次的事故回归）
+- apply → dispose → apply 可反复进行，且旧世代的 dispose 不得影响新世代
+- 重入后**独立监听仍能绑回同一端口**（热重载不能把端点变成永久不可用）
+
+### 升级须知
+
+- 装完请在插件页把开关**关一次再打开**（或重启 DSH），让热重载重新加载新代码。
+- 如果你之前点了「生成口令」，副机要用新口令重新配对。
+
+```
+packaging   4 项
+doc-drift   123/123
+diag:inject 11 项
+tests       987（985 pass / 0 fail / 2 skip）
+lint        干净
+```
+
 ## [0.9.4] - 2026-10-20
 
 > **0.9.3 审查的 19 项全部修完。** 0.9.3 把架构换对了（插件自己开 19387），

package/README.en.md

@@ -37,7 +37,7 @@ explicitly pull them.
 | **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** | 982 (980 pass / 2 skip) · 123 doc-drift assertions · eslint strict |
+| **Tests** | 987 (985 pass / 2 skip) · 123 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,

package/README.md

@@ -30,12 +30,12 @@
 
 | | |
 |---|---|
-| **状态** | 0.9.4 —— 主机 + 副机端到端可用；`exec` 与 `agent` 双链路均已在两台真机上验证通过；CI 覆盖 Windows / macOS / Linux |
+| **状态** | 0.9.5 —— 主机 + 副机端到端可用；`exec` 与 `agent` 双链路均已在两台真机上验证通过；CI 覆盖 Windows / macOS / Linux |
 | **DSH** | 桌面版 / CLI，0.2.0-rc.2 验证 |
 | **平台** | Windows（全量验证）· Linux / macOS（CI 覆盖）|
 | **依赖** | **零外部 npm 依赖** —— 只用 `node:` 内置模块 |
 | **Node** | `^22.19.0 \|\| >=24.0.0` |
-| **测试** | 982 项（980 pass / 2 skip）· 123 条文档漂移断言 · eslint 严格档 |
+| **测试** | 987 项（985 pass / 2 skip）· 123 条文档漂移断言 · eslint 严格档 |
 
 **Web 面板**（侧栏「远程同事」）：节点列表（含 CPU/内存徽章）、派发任务、
 任务状态、结果摘要、工作区变更、成品清单、日志尾巴、**环境体检**、

package/lib/hub/index.js

@@ -597,32 +597,65 @@ export function applyHub(ctx, config = {}) {
 
     let disposed = false
 
-    startListenServer({
-      host: picked.host,
-      port,
-      path: cfg.nodePath,
-      healthPath: cfg.healthPath,
-      // 函数形态：按调用者身份分级（匿名只见 `{ ok: true }`）
-      healthBody: (req) => healthPayload(req, 'listen-server'),
-      onUpgrade: (conn, req) => {
-        // 与 webServer 那条路完全相同的鉴权与交接逻辑（一处不能少：
-        // token 校验是这条通道唯一的口令，跳过就是一个无鉴权入口）。
-        if (cfg.nodeToken !== '') {
-          const token = req.headers['x-dsh-token']
-          if (!safeEqual(token, cfg.nodeToken)) {
-            log('warn', 'node upgrade rejected: bad token (listen-server)', { remote: remoteAddress(req) })
-            try {
-              conn.close(1008, 'bad token')
-            } catch {
-              /* 已关 */
+    /**
+     * 起监听，并对 **EADDRINUSE 做有限重试**。
+     *
+     * 为什么需要：0.9.5 起 apply 可重入（同一 ctx 重新 apply 时先摘上一代）。
+     * 摘上一代会 `server.close()`，而**紧接着用同一个端口重新 listen** 在
+     * Windows 上经常还会拿到 EADDRINUSE（close 是异步完成的，端口没这么快
+     * 释放）。没有重试的话，"热重载"就会把端点变成永久不可用 —— 看起来和
+     * "插件坏了"一样，但其实是可自愈的。
+     *
+     * 只重试 4 次（200/400/600ms）：真的被别的进程占了就该报错，不能无限拖。
+     */
+    const startWithRetry = async (attempt = 1) => {
+      try {
+        return await startListenServer({
+          host: picked.host,
+          port,
+          path: cfg.nodePath,
+          healthPath: cfg.healthPath,
+          // 函数形态：按调用者身份分级（匿名只见 `{ ok: true }`）
+          healthBody: (req) => healthPayload(req, 'listen-server'),
+          onUpgrade: (conn, req) => {
+            // 与 webServer 那条路完全相同的鉴权与交接逻辑（一处不能少：
+            // token 校验是这条通道唯一的口令，跳过就是一个无鉴权入口）。
+            if (cfg.nodeToken !== '') {
+              const token = req.headers['x-dsh-token']
+              if (!safeEqual(token, cfg.nodeToken)) {
+                log('warn', 'node upgrade rejected: bad token (listen-server)', { remote: remoteAddress(req) })
+                try {
+                  conn.close(1008, 'bad token')
+                } catch {
+                  /* 已关 */
+                }
+                return
+              }
             }
-            return
-          }
+            registry.attachDirect(conn, { remote: remoteAddress(req) })
+          },
+          log,
+        })
+      } catch (err) {
+        const code = String(err?.code ?? '')
+        const inUse = code === 'EADDRINUSE' || /EADDRINUSE/.test(String(err?.message ?? ''))
+        if (inUse && attempt < 4 && !disposed) {
+          log('warn', 'listen: port still held, retrying (previous generation closing)', {
+            host: picked.host,
+            port,
+            attempt,
+          })
+          await new Promise((r) => {
+            const t = setTimeout(r, 200 * attempt)
+            if (t.unref) t.unref()
+          })
+          return startWithRetry(attempt + 1)
         }
-        registry.attachDirect(conn, { remote: remoteAddress(req) })
-      },
-      log,
-    })
+        throw err
+      }
+    }
+
+    startWithRetry()
       .then((h) => {
         if (disposed) {
           // 竞态：disposer 先跑了（插件卸载/HMR），把刚起来的 server 关掉
@@ -851,8 +884,24 @@ export function applyHub(ctx, config = {}) {
   return {
     registry,
     pulls,
-    // 由调用方保管；DSH 卸载插件时可用它们清理。
-    disposeAll: () => { for (const d of __disposers) { try { d() } catch { /* 已清 */ } } },
+    /**
+     * 由调用方保管；DSH 卸载插件 / 我们自己在重入前清理时用。
+     *
+     * ⚠ **必须逆序**（最后注册的先摘）。`__reg` 的顺序是「运行时 effect 在最先、
+     * 路由/工具/监听在其后」，而运行时那个 disposer 会 `registry.dispose()` /
+     * `pulls.dispose()` —— 先拆它再去拆工具，工具的 disposer 就可能碰到已销毁的
+     * registry（0.9.5 修重入时发现这里原来是正序跑的，与 cordis 的"逆序释放"
+     * 语义和本文件的注释都不一致）。
+     */
+    disposeAll: () => {
+      for (let i = __disposers.length - 1; i >= 0; i -= 1) {
+        try {
+          __disposers[i]()
+        } catch {
+          /* 已清 */
+        }
+      }
+    },
   }
 }
 

package/lib/index.js

@@ -138,6 +138,31 @@ async function applyWorkerBranch(ctx, config, log) {
   }
 }
 
+/**
+ * 每个"注册宿主"上当前这一代的清理函数。
+ *
+ * 键选 **`ctx.webServer` 服务实例**，不是 `ctx`：
+ * 撞车的是**宿主的路由表**（`webServer.upgrades` 这张 Map）。同一个 ctx 当然
+ * 共用同一张表，但 DSH 热重载时也可能给每代一个新的子 ctx —— 那时按 ctx 记
+ * 就会漏掉，照样撞车。按服务实例记才对应"真正会冲突的那个东西"。
+ *
+ * 读不到 `ctx.webServer`（副机 profile 的 `inject: []` 一读就抛）时退回 ctx，
+ * 这条兜底只是让字典有键，不影响正确性。
+ *
+ * 用 WeakMap：既不阻止 GC，也不会把多个 profile / 多个 host 实例串在一起。
+ */
+const GENERATIONS = new WeakMap()
+
+/** 取"注册宿主"作为字典键。读服务可能抛（无 inject），所以必须 try。 */
+function generationKey(ctx) {
+  try {
+    const ws = ctx && ctx.webServer
+    return ws !== undefined && ws !== null ? ws : ctx
+  } catch {
+    return ctx
+  }
+}
+
 /**
  * DSH 插件入口。
  * @param {object} ctx Cordis 上下文
@@ -188,6 +213,64 @@ export function apply(ctx, config = {}) {
   }
   const handles = { role, hub: undefined, worker: undefined, unconfigured: unconfigured === true }
 
+  // ══════════════════════════════════════════════════════════════════════════
+  // 可重入：同一个 ctx 上只允许存在**一代**注册（0.9.5 修 duplicate 激活失败）
+  // ══════════════════════════════════════════════════════════════════════════
+  //
+  // 0.9.4 装上后 DSH 报：
+  //
+  //     webserver: duplicate upgrade route "/api/remote-agent/node"
+  //     1 entry did not activate remote-agent (dsh-remote-agent)
+  //
+  // 根因不是"注册了两次"写错，而是**我们的注册不可回收**：
+  //
+  //   · DSH 的 `webServer.registerUpgrade(path)` 是**按 path 查表**的，
+  //     同路径第二次注册直接抛（这是它的组合级契约，合理）：
+  //       if (this.upgrades.has(route.path)) throw new Error('webserver: duplicate upgrade route ...')
+  //   · 我们的注册全部收集在 `__disposers` 里、由 `applyHub()` 的返回值
+  //     `disposeAll` 交给调用方保管 —— 但 **DSH 不认识这个返回值**，
+  //     热重载/安装后 reload 时它只会重新 `apply`，不会回头调我们的 disposer。
+  //   · 于是第二代在第一代的残留上注册 → 撞车 → 整个 entry 激活失败。
+  //
+  // 为什么以前没暴露：只有"同一个 ctx 上重新 apply"才触发。DSH 在
+  // 插件安装/升级后会热重载，这正是用户装 0.9.4 时踩到的那一步。
+  //
+  // 修法：**不指望宿主帮我们清理**。按 ctx 记住上一代的 dispose，重新
+  // apply 时先自己摘干净再装。这样无论宿主是否调用 disposer，都不会重复注册。
+  const genKey = generationKey(ctx)
+  const prevDispose = GENERATIONS.get(genKey)
+  if (typeof prevDispose === 'function') {
+    try {
+      prevDispose()
+      log('info', 're-apply on the same host: previous generation disposed first')
+    } catch (err) {
+      log('warn', 'previous generation dispose failed (continuing)', {
+        error: String(err?.message ?? err),
+      })
+    }
+  }
+
+  let released = false
+  const dispose = () => {
+    if (released) return
+    released = true
+    // 只摘自己：新一代可能已经顶替了这一格，别把它的注册也拆了
+    if (GENERATIONS.get(genKey) === dispose) GENERATIONS.delete(genKey)
+    // 顺序：hub 的路由/监听 → setup 路由 → worker 拨号。
+    // 每一步独立兜底：一个失败不能让后面的漏摘（否则又变成"摘一半"）。
+    try { handles.hub?.disposeAll?.() } catch (err) {
+      log('warn', 'hub dispose failed', { error: String(err?.message ?? err) })
+    }
+    if (Array.isArray(handles.setup)) {
+      for (const d of handles.setup) {
+        try { if (typeof d === 'function') d() } catch { /* 已摘 */ }
+      }
+    }
+    try { if (typeof handles.worker === 'function') handles.worker() } catch { /* 已摘 */ }
+  }
+  GENERATIONS.set(genKey, dispose)
+  handles.dispose = dispose
+
   // ── 未配置：什么都不注册 ────────────────────────────────────────────────
   //
   // 为什么要有这个分支：首次安装时**插件无法知道这台机器是主机还是副机** ——
@@ -252,6 +335,12 @@ export function apply(ctx, config = {}) {
     // 动态 import 是异步的；不 await —— apply 本身是同步契约。
     // 失败已在 applyWorkerBranch 内部记日志，不让 host 因副机缺件而起不来。
     void applyWorkerBranch(ctx, config, log).then((h) => {
+      // 竞态：这一代已经被 dispose（热重载/卸载）了，把刚挂上的 worker 立刻摘掉。
+      // 否则它会留在后台继续拨号 —— 一份回收不掉的僵尸连接。
+      if (released) {
+        try { if (typeof h === 'function') h() } catch { /* 已摘 */ }
+        return
+      }
       handles.worker = h
     })
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-remote-agent",
-  "version": "0.9.4",
+  "version": "0.9.5",
   "type": "module",
   "description": "把另一台电脑变成你 DSH 的远程 Agent 同事：副机本地持久跑任务、独立 Agent 循环，只回传 handoff 摘要与产物清单，成品按需拉取。",
   "license": "MIT",