dsh-remote-agent 0.8.1 → 0.9.0

package/lib/env-check.js

@@ -0,0 +1,244 @@
+/**
+ * 环境体检（`env-check`）—— 命令行与 Web 面板共用的同一份检查逻辑。
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * 为什么需要它（2026-10-17 的真实教训）
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * 用户装好插件、配好配对码，副机**永远连不上**，而主机侧**没有任何异常**：
+ * hub 自己 healthz 200、面板能开、工具都在，只有副机连不上。
+ *
+ * 根因是 DSH 的 `webserver` 默认绑 `127.0.0.1`（它面向"本机浏览器访问自己"），
+ * 而本插件是跨机用法。这个失败**完全静默** —— 用户只能猜"地址错了？token 错了？
+ * 防火墙？"
+ *
+ * 所以本模块把这些"静默失败的前置条件"逐条查出来，每条都给**人话原因**和
+ * **具体修法**，能自动修的给 `autoFix` 标记。
+ *
+ * ── 三档处置（产品决策，2026-10-17 用户确认）────────────────────────────
+ *
+ *   A. **自动修**（只改我们自己的配置，不下载任何东西）
+ *      webserver 绑 loopback、role/inject 缺失、roots 不存在
+ *   B. **提示 + 复制命令**（需要用户装东西）
+ *      Tailscale 未安装 —— 只给官方链接和命令，**不代下载**
+ *   C. **只诊断**（需要人判断）
+ *      端口被占、防火墙、模型凭证失效
+ *
+ * ── 为什么不代下载（重要）──────────────────────────────────────────────
+ *
+ * 本插件的核心卖点是**零 npm 依赖、零构建**（README 明确写着）。代用户下载
+ * 第三方二进制会让它变成软件分发方：装哪个版本、从哪下、校验和怎么保证、
+ * 装失败算谁的、供应链攻击面 —— 全都落在我们头上。所以档位 B 只给提示。
+ *
+ * ── 设计约束 ────────────────────────────────────────────────────────────
+ *
+ *   · **纯函数 + 注入探测**：本模块不自己 spawn 命令、不自己读 env，
+ *     所有外部探测由调用方传入（便于单测、也便于命令行走真进程而面板走缓存）
+ *   · **绝不抛**：任何一项探测失败都落成"该项 ok=false + 说明"，不影响其它项
+ *   · **逐项独立**：一项失败不能让整份体检失败
+ */
+
+/** 检查结果。`autoFix` 为真表示"我们能自动改配置修好它"。 */
+function item(ok, id, label, { fix = '', detail = '', autoFix = false, severity = 'error' } = {}) {
+  return { ok: Boolean(ok), id, label, fix: ok ? '' : fix, detail, autoFix: ok ? false : autoFix, severity }
+}
+
+/**
+ * 判定一个 origin/URL 是否只对本机可见。
+ * @param {string} origin 形如 `http://127.0.0.1:19387`
+ * @returns {boolean|null} null = 无法判定
+ */
+export function isLoopbackOrigin(origin) {
+  if (typeof origin !== 'string' || origin.trim() === '') return null
+  let host
+  try {
+    host = new URL(origin).hostname
+  } catch {
+    return null
+  }
+  const h = host.toLowerCase()
+  // IPv6 在 URL.hostname 里带方括号
+  return h === '127.0.0.1' || h === 'localhost' || h === '[::1]' || h === '::1'
+}
+
+/**
+ * 环境体检。
+ *
+ * @param {object} o
+ * @param {'hub'|'worker'} o.role
+ * @param {object} [o.config] 本行生效配置（只读快照）
+ * @param {object|null} [o.reachability] hub 的可达性自检结论（applyHub 产出）
+ * @param {number|null} [o.webPort] 实际监听的端口（探测结果）
+ * @param {boolean|null} [o.portFree] 目标端口是否空闲（探测结果）
+ * @param {boolean|null} [o.firewallOk] 防火墙是否放行（探测结果；null=未探测）
+ * @param {string[]} [o.missingRoots] roots 里不存在的路径（探测结果）
+ * @param {boolean|null} [o.tailscaleUp] Tailscale 是否可用（探测结果）
+ * @param {number} [o.nodesOnline] 已在线副机数
+ * @returns {{ok:boolean, items:Array, failed:number, autoFixable:number}}
+ */
+export function envChecks({
+  role,
+  config = {},
+  reachability = null,
+  webPort = null,
+  portFree = null,
+  firewallOk = null,
+  missingRoots = [],
+  tailscaleUp = null,
+  nodesOnline = null,
+} = {}) {
+  const out = []
+  const isHub = role === 'hub' || role === 'both'
+  // `config` 可能显式传 null（调用方拿不到配置快照时）—— 归一成空对象，
+  // 否则下面每一处 `config.role` 都会 TypeError，整份体检直接抛。
+  const cfg = config && typeof config === 'object' && !Array.isArray(config) ? config : {}
+
+  /* ── 1. 角色已配置（未配置时面板显示引导页，用户会以为装坏了）── */
+  const roleRaw = typeof cfg.role === 'string' ? cfg.role.trim().toLowerCase() : ''
+  out.push(item(
+    roleRaw === 'hub' || roleRaw === 'worker' || roleRaw === 'both',
+    'role',
+    '本机角色已配置（hub / worker / both）',
+    {
+      fix: "打开 Web 面板「远程同事」，点「我是主机」或「我是副机」选一次角色",
+      detail: roleRaw === '' ? '当前 role 为空 = 未配置' : `当前 role = ${roleRaw}`,
+      autoFix: true,
+    },
+  ))
+
+  /* ── 2. inject 含必需服务（缺了 hub 半死 / agent 无工具）── */
+  const inject = Array.isArray(cfg.inject) ? cfg.inject : null
+  // inject 通常在 loader 行上，config 快照里可能没有 —— 拿不到就跳过（不误报）
+  if (inject !== null) {
+    const need = isHub ? ['webServer', 'tools', 'systemPrompt'] : ['tools', 'agentLoop', 'sessions']
+    const missing = need.filter((s) => !inject.includes(s))
+    out.push(item(
+      missing.length === 0,
+      'inject',
+      `inject 含本角色必需的服务（${need.join(' / ')}）`,
+      {
+        fix: `在 profile 的 cordis.patch.yml 里把本插件的 inject 改成 [${need.map((s) => `'${s}'`).join(', ')}]`,
+        detail: missing.length ? `缺少：${missing.join(', ')}` : '',
+        autoFix: true,
+      },
+    ))
+  }
+
+  /* ── 3. hub 可达性（**最贵的一条**：绑 loopback 时副机永远连不上）── */
+  if (isHub) {
+    const loop = reachability && typeof reachability.loopback === 'boolean'
+      ? reachability.loopback
+      : (reachability && typeof reachability.origin === 'string' ? isLoopbackOrigin(reachability.origin) : null)
+    if (loop === null) {
+      out.push(item(true, 'reachability', 'Web 服务可达性（无法判定，已跳过）', {
+        detail: reachability && reachability.hint ? reachability.hint : '未拿到 webServer.getOrigin()',
+        severity: 'info',
+      }))
+    } else {
+      out.push(item(
+        loop === false,
+        'reachability',
+        'Web 服务绑在可达地址（副机才能连上）',
+        {
+          fix: "在 profile 的 cordis.patch.yml 里给 webserver 行加 host: '0.0.0.0'（保留 port），然后重启 DSH",
+          detail: loop
+            ? `当前只监听 ${reachability.bound || '127.0.0.1'}（${reachability.origin || ''}）—— 副机用任何地址都连不上`
+            : `当前监听 ${reachability.origin || ''}`,
+          autoFix: true,
+        },
+      ))
+    }
+  }
+
+  /* ── 4. 端口占用（hub 需要能绑上目标端口）── */
+  if (isHub && portFree !== null) {
+    out.push(item(portFree === true, 'port', 'hub 端口可用', {
+      fix: '换一个端口（改 webserver 的 port），或先关掉占用它的程序',
+      detail: portFree === false ? `端口 ${webPort ?? '?'} 已被占用` : '',
+    }))
+  }
+
+  /* ── 5. 防火墙（局域网/公网场景；Tailscale 不受影响）── */
+  if (isHub && firewallOk !== null) {
+    out.push(item(firewallOk === true, 'firewall', '防火墙已放行 hub 端口', {
+      fix: `以管理员运行：netsh advfirewall firewall add rule name="dsh-remote-agent" dir=in action=allow protocol=TCP localport=${webPort ?? 19387}`,
+      detail: firewallOk === false
+        ? '局域网/公网的副机会被挡住（走 Tailscale 的不受影响）'
+        : '',
+      autoFix: true,
+    }))
+  }
+
+  /* ── 6. roots 存在（worker：任务全报 workspace-denied）── */
+  const roots = Array.isArray(cfg.roots) ? cfg.roots.filter((r) => typeof r === 'string' && r.trim() !== '') : []
+  if (roleRaw === 'worker' || roleRaw === 'both') {
+    if (roots.length === 0) {
+      out.push(item(false, 'roots', 'roots 已配置且路径存在', {
+        fix: '在 profile 的 cordis.patch.yml 里给本插件加 roots: [\'D:\\\\work\']（绝对路径，必须真实存在）',
+        detail: 'roots 为空 —— 任务会被全部拒绝（workspace-denied）',
+        autoFix: true,
+      }))
+    } else if (Array.isArray(missingRoots) && missingRoots.length > 0) {
+      out.push(item(false, 'roots', 'roots 已配置且路径存在', {
+        fix: `创建这些目录，或把 roots 改成真实存在的路径：${missingRoots.join(', ')}`,
+        detail: `不存在的路径：${missingRoots.join(', ')}`,
+        autoFix: true,
+      }))
+    } else {
+      out.push(item(true, 'roots', 'roots 已配置且路径存在', { detail: roots.join(', ') }))
+    }
+  }
+
+  /* ── 7. Tailscale（跨网场景的推荐路径；**只提示不代下载**）── */
+  if (isHub && tailscaleUp !== null) {
+    out.push(item(tailscaleUp === true, 'tailscale', 'Tailscale 可用（跨网推荐）', {
+      // ⚠ 边界（产品决策，2026-10-17 用户确认）：本插件**不代用户下载任何第三方软件**。
+      // 理由：零 npm 依赖 / 零构建是核心卖点；代下载会让我们变成软件分发方
+      // （装哪个版本、从哪下、校验和怎么保证、装失败算谁的、供应链攻击面）。
+      // 所以这里只给官方链接 + 说明，动作留给用户。
+      fix: '装 Tailscale 并登录同一账号：https://tailscale.com/download —— 装好后两台机器自动互通，'
+        + '再用 tailscale ip -4 拿主机 IP 填到副机。'
+        + '（本插件不会代你下载第三方软件，只做检测与提示。）',
+      detail: tailscaleUp === false
+        ? '没装 / 没登录。同一局域网可以直接用主机局域网 IP；跨网建议装 Tailscale'
+        : '',
+      severity: 'warn',
+    }))
+  }
+
+  /* ── 8. 副机是否连上过（最能说明"到底通不通"的一条）── */
+  if (isHub && nodesOnline !== null) {
+    out.push(item(nodesOnline > 0, 'nodes', '至少有一台副机在线', {
+      fix: '检查：① 副机的 hubUrl 是否含 :19387 端口 ② 副机 DSH 是否在跑 '
+        + '③ 上面那条「Web 服务绑在可达地址」是否通过 ④ 防火墙',
+      detail: nodesOnline > 0 ? `${nodesOnline} 台在线` : '还没有副机连上过',
+      severity: 'warn',
+    }))
+  }
+
+  const failed = out.filter((x) => !x.ok && x.severity === 'error').length
+  const autoFixable = out.filter((x) => !x.ok && x.autoFix).length
+  return { ok: failed === 0, items: out, failed, autoFixable }
+}
+
+/**
+ * 把体检结果渲染成人读文本（命令行用；面板自己渲染，不走这里）。
+ * @param {ReturnType<typeof envChecks>} result
+ */
+export function renderEnvChecks(result, { title = '环境体检' } = {}) {
+  const lines = [title, '']
+  for (const it of result.items) {
+    const mark = it.ok ? '✓' : (it.severity === 'warn' ? '⚠' : '✗')
+    lines.push(`${mark} ${it.label}`)
+    if (it.detail) lines.push(`    ${it.detail}`)
+    if (!it.ok && it.fix) lines.push(`    ↳ 怎么修：${it.fix}`)
+    if (!it.ok && it.autoFix) lines.push('    ↳ 可以自动修（面板上点「修复」，或命令行加 --fix）')
+  }
+  lines.push('')
+  if (result.ok && result.failed === 0) {
+    lines.push('核心项全部通过。')
+  } else {
+    lines.push(`共 ${result.failed} 项需要处理${result.autoFixable > 0 ? `（其中 ${result.autoFixable} 项可自动修）` : ''}。`)
+  }
+  return { text: lines.join('\n'), failed: result.failed, autoFixable: result.autoFixable }
+}

package/lib/hub/index.js

@@ -81,7 +81,22 @@ export function normalizeConfig(config = {}) {
       helloTimeoutMs: numOr(limits.helloTimeoutMs, 10_000),
     },
     defaults: {
-      timeoutMs: numOr(defaults.timeoutMs, 60 * 60 * 1000),
+      // ⚠ **不要在这里兜底 1h**（2026-10-17 修，行为变更）。
+      //
+      // 原实现 `numOr(defaults.timeoutMs, 60 * 60 * 1000)` 让 explicitTimeoutMs
+      // 恒为 3600000，于是 tools.js 里 #26-1 的优先级
+      //
+      //     args > 显式配置 > 分模式默认（exec 10min / agent 1h）
+      //
+      // 被压扁成「恒 1h」——**exec 的 10 分钟默认成了死代码**，一条失控命令
+      // 比文档承诺的多跑 50 分钟才被杀。而且那个兜底还掩盖了 tools.js 里的
+      // 一个 TDZ 引用 bug（`v.spec.mode` 自引用），让它在生产环境永不触发。
+      //
+      // 现在保持 undefined：不配置就是"没有显式指定"，让 tools.js 按 mode
+      // 分模式取默认值。用户显式配 `defaults.timeoutMs` 时仍然优先。
+      timeoutMs: typeof defaults.timeoutMs === 'number' && Number.isFinite(defaults.timeoutMs)
+        ? defaults.timeoutMs
+        : undefined,
     },
   }
 }
@@ -241,6 +256,76 @@ export function applyHub(ctx, config = {}) {
     log('warn', 'audit log unavailable; running without audit', { error: String(err?.message ?? err) })
     audit = null
   }
+
+  // ── 可达性自检：webServer 绑在 loopback 时副机永远连不上 ────────────────
+  //
+  // ═══════════════════════════════════════════════════════════════════════════
+  // 这是一个**静默失败**，2026-10-17 实测踩到
+  // ═══════════════════════════════════════════════════════════════════════════
+  //
+  // DSH 的 `@deepseek-ai/dsh-host-webserver` 的 `host` 是**必填项、无默认值**，
+  // 而它面向的默认场景是"本机浏览器访问自己"，所以多数 profile 里绑的是
+  // `127.0.0.1`。`webServer.getOrigin()` 的文档也明说它返回的是
+  // "the root URL **local clients** use to reach the bound listener"。
+  //
+  // 但本插件的整个用法是**跨机**：副机拿 `ws://<主机IP>:19387/...` 拨入。
+  // 绑 loopback 时：
+  //   · hub 自己一切正常（healthz 200、面板能开、工具都在）
+  //   · 副机**永远连不上**，报 `ECONNREFUSED` / `connect timeout`
+  //   · 主机侧**没有任何异常**，用户只能去猜"地址填错了？token 错了？防火墙？"
+  //
+  // 三种用户会踩：
+  //   A. 全新安装，没动过 webserver 配置（**绝大多数**）
+  //   B. 装过某个改 lanBind 的插件又卸载，托管块残留但插件没了
+  //   C. 自己改过 webserver，绑错了
+  //
+  // 所以这里做两件事：
+  //   1. **启动时 log 一条明确的 warn**（带修法，不是只说"不可达"）
+  //   2. 把结论存进 `reachability`，由面板渲染成**红色横幅** ——
+  //      日志用户不会看，面板会看
+  //
+  // ⚠ 自检本身**绝不能**让 hub 起不来：`getOrigin()` 在 listen 之前会抛，
+  // 服务缺失时也不存在。整段包 try/catch，拿不到就记 `unknown`。
+  let reachability = { bound: null, origin: null, loopback: null, hint: '' }
+  try {
+    const ws = ctx.webServer
+    const origin = typeof ws?.getOrigin === 'function' ? ws.getOrigin() : null
+    if (typeof origin === 'string' && origin !== '') {
+      let hostname = null
+      try {
+        hostname = new URL(origin).hostname
+      } catch {
+        /* 非 URL 形态：保持 null */
+      }
+      const h = typeof hostname === 'string' ? hostname.toLowerCase() : ''
+      // IPv6 在 URL.hostname 里带方括号
+      const loopback = h === '127.0.0.1' || h === 'localhost' || h === '[::1]' || h === '::1'
+      reachability = {
+        bound: hostname,
+        origin,
+        loopback,
+        hint: loopback
+          ? "webServer 绑在 loopback，副机无法接入。在 profile 的 cordis.patch.yml 里给 webserver 行加 host: '0.0.0.0'（保留 port），然后重启 DSH。"
+          : '',
+      }
+      if (loopback) {
+        log('warn', 'hub 绑在 loopback：副机将无法接入', {
+          origin,
+          bound: hostname,
+          fix: "给 webserver 加 host: '0.0.0.0'",
+        })
+      } else {
+        log('info', 'hub reachable from other hosts', { origin, bound: hostname })
+      }
+    } else {
+      reachability = { bound: null, origin: null, loopback: null, hint: 'webServer.getOrigin() 不可用，无法判断可达性' }
+    }
+  } catch (err) {
+    // getOrigin() 在 listen 完成前会抛（文档明说）；服务缺失也会抛。
+    reachability = { bound: null, origin: null, loopback: null, hint: `可达性自检失败：${String(err?.message ?? err)}` }
+    log('info', 'reachability self-check unavailable', { error: String(err?.message ?? err) })
+  }
+
   const registry = new NodeRegistry({ log, limits: cfg.limits, identity: hubIdentity, audit })
   const pulls = new PullManager({ registry, log, limits: cfg.limits, audit })
   registry.bindPulls(pulls)
@@ -391,6 +476,9 @@ export function applyHub(ctx, config = {}) {
           // 本行生效配置的只读快照，供面板「主机设置」区展示。
           // 传**原始** config（而非归一化后的 cfg），因为面板要如实反映用户写了什么。
           config,
+          // 可达性自检结论（2026-10-17）：绑 loopback 时副机永远连不上，
+          // 面板要渲染成红色横幅 —— 这个失败在主机侧是完全静默的。
+          reachability,
         }).map(once)
       } catch (err) {
         log('error', 'ui route registration threw', { error: String(err?.message ?? err) })

package/lib/hub/node-registry.js

@@ -86,6 +86,14 @@ class NodeRegistryCore {
     this.tasks = new Map()
     /** reqId → { resolve, timer }（提案 #25：远程文件请求的等待者表） */
     this.fsPending = new Map()
+    /**
+     * reqId → { resolve, timer }（2026-10-17：工作区共享请求的等待者表）。
+     *
+     * 与 fsPending **刻意分开**：fs 是"读文件内容"、share 是"探测共享状态并
+     * 生成命令"，两者语义不同。混用一张表会让超时归因变模糊（一条 share 超时
+     * 被记成 fs-timeout，排查方向直接跑偏）。
+     */
+    this.sharePending = new Map()
     /** @type {import('./pull-manager.js').PullManager | undefined} */
     this.pulls = undefined
     /** @type {import('./relay-link.js').RelayLink | undefined} */
@@ -563,11 +571,28 @@ class NodeRegistryCore {
     const rec = this.nodes.get(t.nodeId)
     const sent = rec?.online ? this.send(t.nodeId, HUB_TO_NODE.TASK_START, { ...t.spec }) : false
     if (!sent) {
-      // 批准时节点已掉线：任务转 failed 终态，绝不静默退回挂起
+      // 批准时节点已掉线：任务转 **failed 终态**，绝不静默退回挂起
       // （退回挂起会让"批了但没跑"变成无头案）。
-      this.tasks.delete(taskId)
+      //
+      // ⚠ 2026-10-17 修：原实现是 `this.tasks.delete(taskId)` —— 那让任务从
+      // hub 视图**彻底消失**（不是失败、不是挂起，是不存在），与这段注释
+      // 自称的"转 failed 终态"直接矛盾。后果：
+      //   · `remote_status` / 面板都查不到该任务，用户以为批准成功
+      //   · subagent provider 的 `awaitTerminal` 等不到终态，只能靠超时兜底
+      //     （最长可挂 1 小时+）
+      //   · 与 ui-routes 的 502 分支文案（"任务已转 failed"）不符
+      //
+      // 改成**保留记录并置终态**：状态可见、可查、可重试。
+      t.status = TASK_STATUS.FAILED
+      t.endedAt = Date.now()
+      t.error = {
+        code: 'node-unreachable',
+        message: `approval could not be delivered: node ${t.nodeId} is unreachable`,
+      }
       rec?.tasks.delete(taskId)
       this.auditRecord('approval.granted', { taskId, nodeId: t.nodeId, by, delivered: false })
+      // 唤醒 awaitTerminal 等待者（不唤醒会让它们挂到超时）
+      this.resolveWaiters(t)
       throw new RemoteAgentError(`node unreachable: ${t.nodeId}`, ERROR_CODE.INTERNAL)
     }
     t.status = TASK_STATUS.QUEUED
@@ -778,6 +803,73 @@ class NodeRegistryCore {
     }
   }
 
+  /**
+   * 工作区共享请求（2026-10-17）。
+   *
+   * 与 `fsRequest` 同款 RPC 模式（发帧 + 等 replyTo），但走独立的 SHARE 帧与
+   * 独立的 pending 表 —— 两者语义不同（fs 是"读文件"，share 是"探测共享状态
+   * 并生成命令"），混用一张表会让超时归因变模糊。
+   *
+   * @param {string} nodeId
+   * @param {'probe'|'plan'|'unshare-plan'} op
+   * @param {object} [params]
+   * @returns {Promise<object>}
+   */
+  shareRequest(nodeId, op, params = {}, { timeoutMs = 15_000 } = {}) {
+    return new Promise((resolve, reject) => {
+      const rec = this.nodes.get(nodeId)
+      if (!rec?.online) {
+        reject(Object.assign(new Error(`node not online: ${nodeId}`), { code: ERROR_CODE.TASK_UNKNOWN }))
+        return
+      }
+      const env = envelope(HUB_TO_NODE.SHARE_REQ, { op, ...params })
+      const reqId = env.id
+      const timer = setTimeout(() => {
+        this.sharePending.delete(reqId)
+        this.log('warn', 'share request timeout', { nodeId, op, reqId, timeoutMs })
+        reject(Object.assign(new Error(`share ${op} timed out after ${timeoutMs}ms`), { code: ERROR_CODE.FS_TIMEOUT }))
+      }, timeoutMs)
+      if (typeof timer.unref === 'function') timer.unref()
+      this.sharePending.set(reqId, { resolve, reject, timer, op, nodeId })
+      const sent = this.send(nodeId, HUB_TO_NODE.SHARE_REQ, { op, ...params }, { id: reqId })
+      if (!sent) {
+        clearTimeout(timer)
+        this.sharePending.delete(reqId)
+        reject(Object.assign(new Error(`failed to send share request to ${nodeId}`), { code: ERROR_CODE.TASK_UNKNOWN }))
+      }
+    })
+  }
+
+  /** share/res 到达：按 replyTo 唤醒等待者。 */
+  handleShareRes(nodeId, d) {
+    const reqId = typeof d.replyTo === 'string' ? d.replyTo : ''
+    const waiter = reqId !== '' ? this.sharePending.get(reqId) : undefined
+    if (!waiter) {
+      this.log('info', 'late share response dropped', { nodeId, reqId })
+      return
+    }
+    clearTimeout(waiter.timer)
+    this.sharePending.delete(reqId)
+    if (d.ok === true) {
+      waiter.resolve(d.result ?? {})
+    } else {
+      waiter.reject(Object.assign(
+        new Error(typeof d.message === 'string' ? d.message : 'share request failed'),
+        { code: typeof d.code === 'string' ? d.code : ERROR_CODE.INTERNAL },
+      ))
+    }
+  }
+
+  /** 节点断连：清掉它名下还没等到 share/res 的等待者。 */
+  shareCancelForNode(nodeId) {
+    for (const [reqId, w] of this.sharePending) {
+      if (w.nodeId !== nodeId) continue
+      clearTimeout(w.timer)
+      w.reject(Object.assign(new Error('node disconnected during share request'), { code: ERROR_CODE.FS_TIMEOUT }))
+      this.sharePending.delete(reqId)
+    }
+  }
+
   /**
    * 发一个二进制帧给节点（header.to 由中继用来路由）。
    * E2E 会话存在时整体封密：外层只留 t/seq/iv + to。
@@ -894,6 +986,8 @@ class NodeRegistryCore {
     this.pulls?.onNodeOffline?.(nodeId)
     // 在途的远程文件请求同样 fail-fast（提案 #25）：等不到 fs/res 就别挂调用方
     this.fsCancelForNode(nodeId)
+    // 在途的工作区共享请求同样 fail-fast（2026-10-17）
+    this.shareCancelForNode(nodeId)
   }
 
   startHeartbeat() {

package/lib/hub/registry-ingest.js

@@ -164,6 +164,15 @@ export function withIngest(Base) {
           // 资源遥测（~30s 一次）：只更新 rec.resource，绝不影响任务链路。
           // 尽力而为的字段级校验：缺/类型不对就落 null —— 一个畸形遥测帧
           // 不能让节点记录缺胳膊少腿，更不能抛（单帧故障隔离不变式）。
+          //
+          // ⚠ `rec` 必须判空（2026-10-17 修）。未知节点（hub 重启后副机还没
+          // 重连的"影子节点"竞态）发来 resource 帧 —— 30s 一次，**必然发生**：
+          // `rec.resource = {...}` 对 undefined 抛 TypeError。外层 try/catch
+          // 能兜住（不崩溃、不断连），但会打一条误导性 error 日志并丢一帧遥测。
+          //
+          // 同文件 REPOS 分支有 `if (rec)` 护栏 —— 同一份单帧隔离不变式，
+          // 两个分支一个做一个漏。
+          if (!rec) return
           const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null)
           rec.resource = {
             cpuPct: num(d.cpuPct),
@@ -268,6 +277,12 @@ export function withIngest(Base) {
           this.handleFsRes(nodeId, d)
           return
 
+        case NODE_TO_HUB.SHARE_RES:
+          // 工作区共享响应（2026-10-17）：按 replyTo 唤醒 shareRequest 等待者。
+          // 与 FS_RES 分开 —— 两张 pending 表不能混（混了会让超时归因变模糊）。
+          this.handleShareRes(nodeId, d)
+          return
+
         case NODE_TO_HUB.ERROR:
           this.log('warn', 'node reported error', { nodeId, code: d.code, taskId: d.taskId })
           if (d.code === ERROR_CODE.E2E_REQUIRED) {

package/lib/hub/tools.js

@@ -658,8 +658,33 @@ export function registerRemoteTools({ ctx, registry, pulls, log: _log, defaults
         constraints: {
           // 提案 #26-1：缺省按模式分开（exec 10min / agent 1h），与副机兜底
           // 同源常量；defaults.timeoutMs（配置显式指定）优先于一切缺省。
+          //
+          // ⚠ 这里**必须用 `routeMode`，不能用 `v.spec.mode`**（2026-10-17 修）。
+          //
+          // 原实现写的是 `v.spec.mode`，而 `v` 正是这一行所属的
+          // `const v = validateTaskStart({...})` 的初始化目标 —— 参数对象字面量
+          // 在 `v` 初始化期间引用 `v` 自身，进入 TDZ（临时死区）：
+          //
+          //     const v = validateTaskStart({ constraints: {
+          //       timeoutMs: ... ?? (v.spec.mode === 'exec' ? ... : ...)
+          //                              ^ Cannot access 'v' before initialization
+          //
+          // 当 `??` 链左侧全空（args.timeoutMs 未传 且 explicitTimeoutMs 为
+          // undefined）时抛 ReferenceError。
+          //
+          // 为什么 829 个测试全绿仍带此 bug：e2e helper 恒传 timeoutMs（`??`
+          // 第一项短路）、单测构造时 defaults 也总有值 —— TDZ 分支从未被测到。
+          //
+          // 为什么生产没炸但更糟：`normalizeConfig` 用
+          // `numOr(defaults.timeoutMs, 60*60*1000)` 兜底，使 explicitTimeoutMs
+          // 恒为 3600000 → TDZ 永不触发，但 #26-1 的「args > 显式配置 >
+          // 分模式默认」被压扁成「恒 1h」：exec 的 10min 默认成为死代码，
+          // 一条失控命令比承诺的多跑 50 分钟才被杀。
+          //
+          // `routeMode`（L614）与 `v.spec.mode` 同义（都是 'exec' | 'agent'），
+          // 且已在 `v` 之前求值 —— 用它彻底消除自引用。
           timeoutMs: num(args?.timeoutMs) ?? explicitTimeoutMs
-            ?? (v.spec.mode === TASK_MODE.EXEC ? EXEC_DEFAULT_TIMEOUT_MS : AGENT_DEFAULT_TIMEOUT_MS),
+            ?? (routeMode === TASK_MODE.EXEC ? EXEC_DEFAULT_TIMEOUT_MS : AGENT_DEFAULT_TIMEOUT_MS),
           denyPaths: Array.isArray(args?.denyPaths) ? args.denyPaths : [],
         },
         origin: 'hub',