dsh-remote-agent 0.8.0 → 0.9.0

package/lib/hub/ui-routes.js

@@ -82,6 +82,9 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { ERROR_CODE, RemoteAgentError, TASK_MODE } from '../protocol.js'
+// 分模式默认超时（提案 #26-1）：与 remote_task 工具同源常量。
+// 面板派单也必须按 mode 取值，否则 exec 会静默吃 1 小时超时（2026-10-17 修）。
+import { AGENT_DEFAULT_TIMEOUT_MS, EXEC_DEFAULT_TIMEOUT_MS } from '../node/task-engine.js'
 import { isInside, normalizePath } from '../glob.js'
 // 副机接入（pair-info）：复用向导的同一份纯逻辑 —— 面板生成的配对码与
 // dsh-remote-setup 生成的一字不差，避免两套实现漂移。
@@ -97,6 +100,10 @@ import {
 // 任务模板库（配方）：模板是"派发表单的预设值"，存 hub 本地 JSON。
 // 校验/原子写/并发串行化都在那个模块里（本文件只做路由与围栏）。
 import { createTemplateStore, defaultTemplatesFile } from './templates.js'
+// 环境体检（2026-10-17）：与命令行 `dsh-remote-setup --doctor` 共用同一份检查逻辑。
+// 存在的理由是那个最贵的静默失败 —— webserver 绑 loopback 时副机永远连不上，
+// 而主机侧毫无异常。面板必须把它渲染出来。
+import { envChecks } from '../env-check.js'
 
 export const UI_API_PREFIX = '/api/remote-agent/ui'
 
@@ -299,6 +306,10 @@ export function registerUiRoutes({
   pullRoot,
   uiTemplatesFile,
   config = {},
+  // 可达性自检结论（2026-10-17）：{ bound, origin, loopback, hint }
+  // 绑 loopback 时副机永远连不上，而这个失败在主机侧完全静默 ——
+  // 面板必须渲染成红色横幅，否则用户只能去猜"地址填错了？token 错了？"
+  reachability = null,
 }) {
   const disposers = []
   const guard = makeGuard(ctx, log)
@@ -424,6 +435,16 @@ export function registerUiRoutes({
         // 面板据此判断"该不该显示落地目录"，空串会渲染成 "落地到 " 这种残缺文案。
         pullRoot: typeof pullRoot === 'string' && pullRoot !== '' ? pullRoot : null,
         dispatch: true,
+        // 可达性自检（2026-10-17）：`loopback === true` 时副机永远连不上，
+        // 面板渲染红色横幅。逐字段投影，不 spread。
+        reachability: reachability
+          ? {
+            bound: typeof reachability.bound === 'string' ? reachability.bound : null,
+            origin: typeof reachability.origin === 'string' ? reachability.origin : null,
+            loopback: reachability.loopback === true,
+            hint: typeof reachability.hint === 'string' ? reachability.hint : '',
+          }
+          : null,
       },
     })
   })
@@ -494,7 +515,17 @@ export function registerUiRoutes({
       model: body.model,
       outputs: Array.isArray(body.outputs) ? body.outputs.filter((s) => typeof s === 'string') : [],
       constraints: {
-        timeoutMs: Number.isFinite(body.timeoutMs) ? body.timeoutMs : (defaults.timeoutMs ?? 3600000),
+        // 提案 #26-1（2026-10-17 修第三处）：面板派单也必须按 mode 分模式取默认。
+        //
+        // 原实现 `defaults.timeoutMs ?? 3600000` 让面板派 exec 任务也吃 1 小时
+        // 超时 —— 与 remote_task 工具同样的缺陷（exec 该是 10 分钟）。
+        // 三处同族失效点：tools.js（TDZ + 兜底遮蔽）、hub/index.js（1h 兜底）、
+        // 这里（1h 兜底）。
+        timeoutMs: Number.isFinite(body.timeoutMs)
+          ? body.timeoutMs
+          : (Number.isFinite(defaults.timeoutMs)
+            ? defaults.timeoutMs
+            : (mode === TASK_MODE.EXEC ? EXEC_DEFAULT_TIMEOUT_MS : AGENT_DEFAULT_TIMEOUT_MS)),
         denyPaths: [],
       },
       origin: 'ui',
@@ -631,6 +662,131 @@ export function registerUiRoutes({
     writeJson(res, 200, { ok: true, config: configView() })
   })
 
+  // ── 环境体检 ──────────────────────────────────────────────────
+  //
+  // 与命令行 `dsh-remote-setup --doctor` 共用 `lib/env-check.js` 的同一份逻辑。
+  //
+  // 为什么面板上必须有这一屏（2026-10-17 实测）：那个最贵的静默失败是
+  // "webserver 绑 127.0.0.1 → 副机永远连不上，而主机侧毫无异常"。日志用户
+  // 不会看，面板会看。所以体检结果要能一键看到，且每条都带修法。
+  //
+  // 探测项里有一部分需要**真实系统信息**（端口占用、防火墙、Tailscale），
+  // 这里只传能拿到的：reachability 来自 applyHub 的自检、nodesOnline 来自
+  // registry。其余留给调用方（命令行）补 —— 拿不到的项 envChecks 会跳过，
+  // 不会误报。
+  route(`${UI_API_PREFIX}/env-check`, (req, res) => {
+    if (req.method !== 'GET') return writeJson(res, 405, { error: 'method' })
+    let result
+    try {
+      const nodes = registry.list()
+      result = envChecks({
+        role: typeof config.role === 'string' ? config.role : 'hub',
+        config,
+        reachability,
+        nodesOnline: nodes.filter((n) => n.online).length,
+      })
+    } catch (err) {
+      // 体检自身出错不能让面板白屏 —— 回一个"体检失败"而不是 500
+      log('warn', 'env-check threw', { error: shortMessage(err) })
+      return writeJson(res, 200, {
+        ok: false,
+        items: [{ ok: false, id: 'internal', label: '体检自身出错', fix: '', detail: shortMessage(err), autoFix: false, severity: 'error' }],
+        failed: 1,
+        autoFixable: 0,
+      })
+    }
+    writeJson(res, 200, result)
+  })
+
+  // ── 工作区 SMB 共享（2026-10-17）──────────────────────────────
+  //
+  // 用户需求：想用本地 IDE 直接打开副机的项目目录 —— 唯一现实路径是把工作区
+  // 通过 SMB 共享出去，主机 `net use X: \\副机\dsh-work` 映射成盘符。
+  //
+  // ⚠ **这是本插件唯一主动放宽安全边界的功能**。开启后：
+  //     · roots / denyPaths 全部失效（Windows 内核直读，插件拦不住）
+  //     · 「清单先于字节」失效（.env / .git 密钥 / 中间产物全部可见）
+  //     · 新增凭证面（主机需要副机 Windows 账号）
+  //
+  // 所以：
+  //   · `POST /share` 必须带 `confirm: 'yes'` —— 二次确认，缺了直接 400
+  //   · `access` 默认 `read`（最小权限），写权限要显式传 `write`
+  //   · **本路由不执行任何共享命令** —— 只返回可复制的命令。执行需要管理员，
+  //     而 DSH 通常以普通用户跑；Node 里提权失败比让用户手动跑一条难排查得多
+  //
+  // 三个 action：
+  //   GET  /share?node=X                 → probe（当前是否管理员 + 已存在的共享）
+  //   POST /share { action:'plan', ... } → 生成共享命令 + 主机映射命令
+  //   POST /share { action:'unshare', ... } → 生成卸载命令
+  route(`${UI_API_PREFIX}/share`, async (req, res) => {
+    // GET = 只读探测（不需要确认）
+    if (req.method === 'GET') {
+      const url = new URL(req.url, 'http://localhost')
+      const nodeId = (url.searchParams.get('node') ?? '').trim()
+      if (nodeId === '') return writeJson(res, 400, { error: 'node-required' })
+      try {
+        const result = await registry.shareRequest(nodeId, 'probe', {})
+        return writeJson(res, 200, { ok: true, ...result })
+      } catch (err) {
+        return writeJson(res, 200, {
+          ok: false,
+          code: err instanceof RemoteAgentError ? err.code : ERROR_CODE.INTERNAL,
+          message: shortMessage(err),
+        })
+      }
+    }
+    if (req.method !== 'POST') return writeJson(res, 405, { error: 'method' })
+
+    const body = await readJson(req)
+    const action = typeof body?.action === 'string' ? body.action : ''
+    const nodeId = typeof body?.node === 'string' ? body.node.trim() : ''
+    if (nodeId === '') return writeJson(res, 400, { error: 'node-required' })
+
+    // ⚠ 二次确认是**硬要求**：这是唯一会放宽安全边界的操作，
+    // 客户端必须显式表达"我知道风险"。缺了就拒，不给默认通过。
+    if (body?.confirm !== 'yes') {
+      return writeJson(res, 400, {
+        error: 'confirm-required',
+        message: '开启工作区共享会让主机绕过本插件的 roots/denyPaths 边界直接读写这些文件。'
+          + '请在请求里带 confirm: "yes" 表示已知情。',
+      })
+    }
+
+    try {
+      if (action === 'plan') {
+        const dir = typeof body.dir === 'string' ? body.dir.trim() : ''
+        const access = body.access === 'write' ? 'write' : 'read'
+        // 主机侧地址：面板把 window.location.hostname 传进来（就是主机自己的地址），
+        // 但副机要连的是**主机**，而映射是主机连**副机** —— 所以这里要的是副机地址。
+        // 由面板从节点信息里取（registry 有），不信任客户端传的值。
+        const node = registry.list().find((n) => n.nodeId === nodeId)
+        const hostForMount = typeof body.host === 'string' && body.host !== ''
+          ? body.host
+          : (node && typeof node.hostname === 'string' ? node.hostname : nodeId)
+        const result = await registry.shareRequest(nodeId, 'plan', {
+          dir,
+          access,
+          host: hostForMount,
+          drive: typeof body.drive === 'string' ? body.drive : 'X:',
+        })
+        return writeJson(res, 200, { ok: true, ...result })
+      }
+      if (action === 'unshare') {
+        const shareName = typeof body.shareName === 'string' ? body.shareName.trim() : ''
+        if (shareName === '') return writeJson(res, 400, { error: 'shareName-required' })
+        const result = await registry.shareRequest(nodeId, 'unshare-plan', { shareName })
+        return writeJson(res, 200, { ok: true, ...result })
+      }
+      return writeJson(res, 400, { error: 'bad-action', message: 'action 必须是 plan / unshare' })
+    } catch (err) {
+      return writeJson(res, 200, {
+        ok: false,
+        code: err instanceof RemoteAgentError ? err.code : ERROR_CODE.INTERNAL,
+        message: shortMessage(err),
+      })
+    }
+  })
+
   // ── 副机接入：生成配对码（面板 GUI 化的落点）──────────────────
   //
   // 端口不查内部状态：面板本身就由 hub 的 webserver 服务，浏览器侧把

package/lib/index.js

@@ -24,7 +24,7 @@ import { applyHub, newNodeToken, normalizeConfig, NODE_UPGRADE_PATH, HEALTH_PATH
 import { registerSetupRoutes } from './setup-routes.js'
 
 /** 角色取值。 */
-export const ROLE = Object.freeze({ HUB: 'hub', WORKER: 'worker', BOTH: 'both' })
+export const ROLE = Object.freeze({ HUB: 'hub', WORKER: 'worker', BOTH: 'both', AUTO: 'auto' })
 
 /**
  * 解析本机角色。
@@ -66,6 +66,26 @@ export function resolveRoleDetail(config) {
   if (typeof raw === 'string') {
     const norm = raw.trim().toLowerCase()
     if (norm === ROLE.HUB || norm === ROLE.WORKER || norm === ROLE.BOTH) return { role: norm }
+    // ── auto：按配置推断（2026-10-17，"开箱即用"的落点）──────────────
+    //
+    // 判据只有一条，但它是**副机与主机最本质的区别**：
+    //   · 配了 `hubUrl` = 这台机器要去连别人 = **副机**
+    //   · 没配 hubUrl = 这台机器不需要连别人 = **主机**
+    //
+    // 为什么这条判据可靠：
+    //   · hubUrl 是副机独有的字段，hub 侧根本不读它（hub 是监听方）
+    //   · 用户配 hubUrl 的唯一目的就是"连主机"
+    //   · 配对码展开后必然产出 hubUrl（见 lib/pairing.js），所以"贴了配对码"
+    //     就等于"有 hubUrl"
+    //
+    // 这样主机装完零操作（默认 hub），副机贴完配对码也零操作（自动 worker）。
+    // 比"两台都要点一下"更接近开箱即用，又不像"写死 hub"那样给副机开一个
+    // 不该开的无鉴权端点。
+    if (norm === 'auto' || norm === ROLE.AUTO) {
+      const hubUrl = typeof config.hubUrl === 'string' ? config.hubUrl.trim() : ''
+      if (hubUrl !== '') return { role: ROLE.WORKER, inferred: 'hubUrl' }
+      return { role: ROLE.HUB, inferred: 'no-hubUrl' }
+    }
   }
   // 无法识别：**不再回退 hub**（那会静默开一个无鉴权入口）。
   // 当成"未配置"，由面板引导用户重新选。
@@ -206,13 +226,42 @@ export function apply(ctx, config = {}) {
 
 export const Config = z.object({
   role: z
-    // ⚠ 空字符串是**合法值**，表示"还没配置" —— 见 resolveRoleDetail 的说明。
-    // 不能用 `.default('hub')`：那会让副机装完以 hub 身份启动（注册一个
-    // nodeToken 为空、不校验凭证的直连端点），且面板不会显示引导。
-    .union([z.const('hub'), z.const('worker'), z.const('both'), z.const('')])
-    .default('')
+    // ⚠ 默认 `'auto'`：**按配置推断角色**，而不是写死一个（2026-10-17）。
+    //
+    // ── 为什么不是写死 hub ──────────────────────────────────────────────
+    //
+    // v0.7.0 之前默认 hub，问题是：**副机装完会以 hub 身份启动** —— 注册一个
+    // nodeToken 为空、不校验凭证的直连端点。这在安全上是实打实的漏洞面。
+    //
+    // ── 为什么不是写死 ''（未配置）──────────────────────────────────────
+    //
+    // v0.7.0~0.8.1 默认 `''`，问题是：**两台机器都要操作一次**，而"开箱即用"
+    // 的目标是主机装完零操作。而且升级时包内默认容易把 profile 里没显式写的
+    // role 冲成空（实测踩过）。
+    //
+    // ── auto 的判据（见 resolveRoleDetail）─────────────────────────────
+    //
+    //   1. 用户显式写了 hub/worker/both  → 用它（最高优先，永不猜错）
+    //   2. 配了 `hubUrl`（副机的特征）    → worker
+    //   3. 都没配                        → hub（默认主机）
+    //
+    // 这样：
+    //   · 主机装完 → 没 hubUrl → 自动 hub → **零操作** ✅
+    //   · 副机填完配对码 → 有 hubUrl → 自动 worker → **零操作** ✅
+    //   · 副机还没填 → 暂时 hub，但面板立刻显示"填配对码成为副机"
+    //
+    // 空字符串仍是**合法值**，表示"用户主动清空了，需要引导"。
+    .union([
+      z.const('hub'),
+      z.const('worker'),
+      z.const('both'),
+      z.const('auto'),
+      z.const(''),
+    ])
+    .default('auto')
     .description(
-      '本机角色：hub=主机（派活方）；worker=副机（干活方）；both=同一台机器自测；'
+      '本机角色：auto=自动推断（默认：配了 hubUrl 就是副机，否则是主机）；'
+      + 'hub=主机（派活方）；worker=副机（干活方）；both=同一台机器自测；'
       + '留空=未配置（打开 Web 面板会显示引导，让你选）',
     ),
 

package/lib/node/fs-service.js

@@ -390,11 +390,29 @@ export function createFsService(cfg) {
       if (st.isDirectory()) {
         scan(dir)
       } else if (st.isFile()) {
-        // 单文件 grep：直接匹配该文件
+        // 单文件 grep：直接匹配该文件。
+        //
+        // ⚠ 必须有大小护栏（2026-10-17 修）。目录扫描路径有 `GREP_FILE_MAX`
+        // （2MB）与 `GREP_TIME_MS`（10s）双护栏，但**这个分支原来什么都没查**：
+        // 直接 `readFileSync` 全文。触发形态是 `remote_grep` 的 path 指向工作区
+        // 内一个巨大文本文件（应用日志 / 数据库转储 / core dump）：
+        //
+        //   · 巨文件整体进内存 → 副机 OOM（副机是常驻进程，OOM 即全部任务中断）
+        //   · `readFileSync` 同步阻塞事件循环 → 期间 ws 帧、心跳、其他任务的
+        //     输出全部停摆
+        //
+        // 而且这条路径是**可达的**：agent 会自主选择 grep 目标。属于 DoS 面。
+        //
+        // 现在与扫描路径同口径：超 `GREP_FILE_MAX` 就跳过并计入 filesSkipped
+        // （而不是静默读爆内存，也不是报错中断整个 grep —— 用户可能只是想
+        // 在目录里搜，其中恰好有个大文件）。
         let fd
         try {
           fd = fs.openSync(dir, 'r')
-          if (!looksBinary(fd)) {
+          if (st.size > GREP_FILE_MAX) {
+            // 跳过超大文件，与目录扫描分支的判定一致（那边也是跳过不报错）
+            filesSkipped++
+          } else if (!looksBinary(fd)) {
             filesScanned++
             const lines = fs.readFileSync(dir).toString('utf8').split('\n')
             for (let i = 0; i < lines.length && matches.length < maxN; i++) {

package/lib/node/index.js

@@ -35,7 +35,7 @@ import {
   validateTaskStart,
 } from '../protocol.js'
 import { ArtifactService } from './artifact-service.js'
-import { defaultRoots } from './exec.js'
+import { defaultRoots, resolveWorkspace } from './exec.js'
 // P2-11：hub 身份验证 —— 指纹归一化 + TOFU 钉住落盘（<stateDir>/hub-pin.json）。
 import { normalizeFingerprint } from '../identity.js'
 import { clearHubPin, loadHubPin, saveHubPin } from './hub-pin.js'
@@ -54,6 +54,15 @@ import { TaskStore } from './task-store.js'
 // 远程文件工具集（提案 #25）：ls/read/grep/tree 只读实现，与任务链路共用
 // roots / denyPaths / caseInsensitive 三个配置（同一个安全边界，两处入口）。
 import { createFsService } from './fs-service.js'
+// 工作区 SMB 共享（2026-10-17）：只探测 + 生成命令，不执行（需管理员）。
+import {
+  SHARE_ACCESS,
+  buildMountCommand,
+  buildShareCommand,
+  buildUnshareCommand,
+  isAdmin,
+  probeShareState,
+} from './share-service.js'
 import { NodeTransport, TRANSPORT_MODE } from './transport.js'
 
 const PLUGIN_NAME = 'dsh-remote-agent'
@@ -958,6 +967,12 @@ function startWorker(ctx, config) {
         // reqId 就是请求信封 id（hub 按 replyTo 对 pending 表）。
         handleFsReq(frame, d)
         return
+      case HUB_TO_NODE.SHARE_REQ:
+        // 工作区 SMB 共享（2026-10-17）：**只探测 + 生成命令**，不执行。
+        // 执行需要管理员，而 DSH 通常以普通用户跑 —— 由用户在提权 PowerShell
+        // 里手动做（面板给可复制命令）。见 lib/node/share-service.js 头注释。
+        handleShareReq(frame, d)
+        return
       case HUB_TO_NODE.ERROR:
         logger.warn('hub reported error', { code: d.code, message: d.message, replyTo: d.replyTo })
         return
@@ -991,6 +1006,76 @@ function startWorker(ctx, config) {
     }))
   }
 
+  /**
+   * 处理工作区共享请求（2026-10-17）。
+   *
+   * 支持三个 op，**全部是只读探测或生成命令**，不执行任何需要管理员的动作：
+   *
+   *   · `probe`        —— 当前是否管理员 + 哪些 dsh-work 共享已存在
+   *   · `plan`         —— 生成共享命令 + 主机侧 net use 命令（只读/读写）
+   *   · `unshare-plan` —— 生成卸载命令
+   *
+   * 为什么不执行：`New-SmbShare` 需要管理员，DSH 通常以普通用户跑。
+   * Node 里提权失败的表现（静默失败 / 被安全软件拦 / 权限半生效）比让用户
+   * 手动跑一条命令难排查得多。所以这里只"生成命令"，执行交给用户。
+   */
+  function handleShareReq(frame, d) {
+    const op = typeof d.op === 'string' ? d.op : ''
+    const reply = (payload) => send(NODE_TO_HUB.SHARE_RES, { replyTo: frame.id, ...payload })
+    try {
+      if (op === 'probe') {
+        // 探测要查的目录：默认用 roots（这是本机的安全边界，共享也只该共享它们）
+        const dirs = Array.isArray(d.dirs) && d.dirs.length > 0
+          ? d.dirs.filter((x) => typeof x === 'string' && x !== '')
+          : roots
+        reply({ ok: true, result: probeShareState({ dirs }) })
+        return
+      }
+      if (op === 'plan') {
+        const dir = typeof d.dir === 'string' ? d.dir.trim() : ''
+        if (dir === '') {
+          reply({ ok: false, code: ERROR_CODE.INTERNAL, message: 'plan 需要 dir（要共享的目录）' })
+          return
+        }
+        // 共享目录必须在 roots 内 —— 与 fs 工具同一条安全边界。
+        // 用户可以在副机共享任意目录，但**通过插件**只能共享已授权的工作区。
+        const resolved = resolveWorkspace(dir, { roots, caseInsensitive, defaultDir: roots[0] })
+        const access = d.access === SHARE_ACCESS.WRITE ? SHARE_ACCESS.WRITE : SHARE_ACCESS.READ
+        const { shareName, command } = buildShareCommand({ dir: resolved, access })
+        reply({
+          ok: true,
+          result: {
+            dir: resolved,
+            access,
+            shareName,
+            shareCommand: command,
+            // 主机侧映射命令：面板直接给用户复制
+            mountCommand: buildMountCommand({ host: d.host || '', shareName, drive: d.drive || 'X:' }),
+            admin: isAdmin(),
+          },
+        })
+        return
+      }
+      if (op === 'unshare-plan') {
+        const shareName = typeof d.shareName === 'string' ? d.shareName.trim() : ''
+        if (shareName === '') {
+          reply({ ok: false, code: ERROR_CODE.INTERNAL, message: 'unshare-plan 需要 shareName' })
+          return
+        }
+        reply({
+          ok: true,
+          result: { shareName, unshareCommand: buildUnshareCommand(shareName), admin: isAdmin() },
+        })
+        return
+      }
+      reply({ ok: false, code: ERROR_CODE.INTERNAL, message: `unknown share op: ${op || '(empty)'}` })
+    } catch (err) {
+      const code = typeof err?.code === 'string' ? err.code : ERROR_CODE.INTERNAL
+      logger.warn('share op failed', { op, code, error: msgOf(err) })
+      reply({ ok: false, code, message: msgOf(err) })
+    }
+  }
+
   /* 9) 事件接线 ------------------------------------------------------- */
   const listenerDisposers = []
   const on = (evt, fn) => {

package/lib/node/runner.js

@@ -641,6 +641,21 @@ export class InProcessRunner {
       )
 
       dlog('before createAgent', { sessionIdFor, cwd, agentOptions })
+
+      // ⚠ **先占位再 await**（2026-10-17 修 L3）。
+      //
+      // 原实现把 `this.active.set(taskId, { handle, controller })` 放在
+      // `await createAgent()` **之后**。于是 createAgent 在途的那几毫秒里，
+      // hub 发 `task/cancel` → `cancel(taskId)` 查不到记录 → 返回 false →
+      // hub 认为"取消失败"，而任务最终会跑完并按 completed 落账 ——
+      // **正是 #26-5 修过的形态在窗口期复现**。
+      //
+      // 窗口窄（createAgent 毫秒级）但取消语义的承诺是"请求即达"。所以先占位
+      // （handle 置 null），createAgent 完成后再补上。`cancel()` 里对
+      // `rec.handle` 的空值已有保护（`rec.handle.agent.cancel` 包在 try 里，
+      // 而 `controller.abort()` 一定生效 —— 后者正是 #26-5 的修复点）。
+      this.active.set(taskId, { handle: null, controller })
+
       handle = await agentLoop.createAgent(this.ctx, {
         sessionId: sessionIdFor,
         meta: { cwd },
@@ -656,6 +671,9 @@ export class InProcessRunner {
         handleKeys: (() => { try { return Object.keys(handle ?? {}).slice(0, 10) } catch { return null } })(),
       })
 
+      // 补齐占位记录里的 handle（cancel 可能已经在 createAgent 期间触发过，
+      // 此时 controller 已被 abort —— 后续 followup 会因 signal 已中止而立刻
+      // 走 abortPromise 分支，符合预期）
       this.active.set(taskId, { handle, controller })
 
       // 观察事件：给 hub 送进度，并在会话日志之外保留一份实时文本（防日志投影差异）
@@ -829,9 +847,13 @@ export class InProcessRunner {
     const rec = this.active.get(taskId)
     if (!rec) return false
     try {
+      // handle 可能还是 null（L3 修复后先占位再 await createAgent）——
+      // 此时 agent 还没建出来，没有 agent.cancel 可调。抛错被吞掉即可，
+      // 真正的取消靠下面的 controller.abort()：createAgent 拿到的 signal
+      // 已经中止，后续 followup 会立刻走 abortPromise 分支。
       rec.handle.agent.cancel({ kind: 'user' })
     } catch {
-      /* agent 可能已停 */
+      /* agent 可能已停，或还没建出来（占位阶段） */
     }
     try {
       rec.controller.abort()