dsh-remote-agent 0.4.3 → 0.6.0

package/lib/node/fs-service.js

@@ -0,0 +1,504 @@
+/**
+ * 远程文件工具集（提案 #25）的副机本地实现 —— 四个只读操作：
+ *   ls / read / grep / tree
+ *
+ * 安全模型（与任务链路同一条底线，缺一不可）：
+ *  - **只读**。整个模块没有任何写路径 —— fs-service 拿不到"写"这个动词。
+ *  - **roots 边界**：每个入口路径先 realpathSync.native（展开 8.3 短名与符号
+ *    链接，与 exec.js resolveWorkspace 同款口径），再与 roots 前缀比对。
+ *  - **denyPaths 生效**：isDenied 与 artifacts.js / task-engine 同一条规则，
+ *    被禁路径在枚举与读取两层都被拦（枚举层拦是为了连名字都不上报）。
+ *  - **符号链接不跟随**：tree/grep 遍历时 withFileTypes 发现的链接只列条目
+ *    本身、绝不深入 —— 否则 roots 内一个指向 C:\Users 的链接就是逃逸口。
+ *
+ * 上限（防御 50GB 级文件夹被一次请求拖死副机）：
+ *  - read：文本模式仅支持 ≤ READABLE_FILE_MAX (8MB) 的文件按行分段；二进制
+ *    只回 sha256/size/头部预览；单次响应文本量 ≤ READ_TEXT_MAX (256KB)。
+ *  - grep：文件数 ≤ GREP_MAX_FILES (2000)、单文件 ≤ GREP_FILE_MAX (2MB)、
+ *    命中 ≤ maxMatches (200)、总时长 ≤ GREP_TIME_MS (10s)。
+ *  - tree：深度 ≤ depth、总条目 ≤ maxEntries (2000)。
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { createHash } from 'node:crypto'
+import { isDenied } from './exec.js'
+import { normalizePath, extname } from '../glob.js'
+import { ERROR_CODE } from '../protocol.js'
+
+/** 文本模式 read 的文件大小上限：超过就拒绝（建议 grep 定位后再读片段）。 */
+export const READABLE_FILE_MAX = 8 * 1024 * 1024
+/** 单次 read 响应携带的文本量上限（字节）。 */
+export const READ_TEXT_MAX = 256 * 1024
+/** grep 递归扫描的文件数上限。 */
+export const GREP_MAX_FILES = 2000
+/** grep 单文件大小上限：更大的文件直接跳过（防止二进制/巨型日志拖死）。 */
+export const GREP_FILE_MAX = 2 * 1024 * 1024
+/** grep 默认总时长上限（ms）：超时停下并如实报告 truncated。 */
+export const GREP_TIME_MS = 10 * 1000
+/** grep 默认命中上限。 */
+export const GREP_MAX_MATCHES = 200
+/** tree 默认最大深度与条目数。 */
+export const TREE_DEFAULT_DEPTH = 3
+export const TREE_MAX_ENTRIES = 2000
+/** ls 单页条目上限。 */
+export const LS_PAGE_MAX = 2000
+/** 二进制嗅探窗口：前 64 字节出现 NUL 即视为二进制。 */
+const SNIFF_BYTES = 64
+
+/** 复用任务链路的错误形态（code 会被 hub 工具层原样透出）。 */
+export class FsError extends Error {
+  constructor(message, code) {
+    super(message)
+    this.name = 'FsError'
+    this.code = code
+  }
+}
+
+/**
+ * 解析"可以是文件也可以是目录"的路径：realpath + roots 前缀 + denyPaths。
+ * 与 resolveWorkspace 的差异只在两点：不要求是目录；不存在时直接拒
+ * （读一个不存在的文件没有"任务会创建它"的借口）。
+ */
+function resolveAny(requested, cfg) {
+  const { roots, caseInsensitive } = cfg
+  if (typeof requested !== 'string' || requested === '') {
+    throw new FsError('path is required', ERROR_CODE.WORKSPACE_DENIED)
+  }
+  if (!path.isAbsolute(requested)) {
+    throw new FsError(`path must be absolute: ${requested}`, ERROR_CODE.WORKSPACE_DENIED)
+  }
+  let resolved
+  try {
+    resolved = fs.realpathSync.native ? fs.realpathSync.native(requested) : fs.realpathSync(requested)
+  } catch {
+    throw new FsError(`path not found: ${requested}`, ERROR_CODE.ARTIFACT_MISSING)
+  }
+  const allowed = (roots ?? []).map((r) => {
+    let base = r
+    try {
+      base = fs.realpathSync.native ? fs.realpathSync.native(r) : fs.realpathSync(r)
+    } catch {
+      // 与 resolveWorkspace 同口径：不可达的根保持原样，后面照样拒一切子路径
+    }
+    return normalizePath(base, { caseInsensitive })
+  })
+  const norm = normalizePath(resolved, { caseInsensitive })
+  const ok = allowed.some((r) => norm === r || norm.startsWith(`${r}/`))
+  if (!ok) {
+    throw new FsError(
+      `path outside allowed roots: ${resolved}`,
+      ERROR_CODE.WORKSPACE_DENIED,
+    )
+  }
+  if (isDenied(resolved, cfg.denyPaths ?? [], { caseInsensitive })) {
+    throw new FsError(`path denied by denyPaths: ${resolved}`, ERROR_CODE.WORKSPACE_DENIED)
+  }
+  return resolved
+}
+
+/** 枚举层拒绝：条目级 denyPaths（连名字都不上报给 hub）。 */
+function entryDenied(absPath, cfg) {
+  return isDenied(absPath, cfg.denyPaths ?? [], { caseInsensitive: cfg.caseInsensitive })
+}
+
+/** 目录条目排序：目录优先，同级按名字（locale 感知，大小写不敏感）。 */
+function sortEntries(list) {
+  return list.sort((a, b) => {
+    if (a.type !== b.type) return a.type === 'dir' ? -1 : 1
+    return a.name.localeCompare(b.name, undefined, { sensitivity: 'base', numeric: true })
+  })
+}
+
+/** 文件是否疑似二进制：前 SNIFF_BYTES 字节出现 NUL。 */
+function looksBinary(fd) {
+  const buf = Buffer.alloc(SNIFF_BYTES)
+  // ⚠ fs.readSync 直接返回 bytesRead 数字（不是 {bytesRead, buffer} 对象 ——
+  // 那是 fs.read 的 promise 版）。解构会得到 undefined，subarray(0, undefined)
+  // 变成整个缓冲，而 alloc 未写区域全零 → **任何文件都被误判二进制**。
+  const bytesRead = fs.readSync(fd, buf, 0, SNIFF_BYTES, 0)
+  return buf.subarray(0, bytesRead).includes(0)
+}
+
+/**
+ * 建一个 fs-service 实例。roots/denyPaths 来自副机配置（与任务链路同源），
+ * caseInsensitive 跟随 Windows 语义。
+ */
+export function createFsService(cfg) {
+  const { roots, caseInsensitive = false } = cfg
+  const conf = { roots, caseInsensitive, denyPaths: cfg.denyPaths ?? [] }
+
+  return {
+    /** 列目录（单层，分页）。 */
+    ls({ path: p, limit = 500, offset = 0 } = {}) {
+      const dir = resolveAny(p, conf)
+      let st
+      try {
+        st = fs.statSync(dir)
+      } catch {
+        throw new FsError(`path not found: ${dir}`, ERROR_CODE.ARTIFACT_MISSING)
+      }
+      if (!st.isDirectory()) {
+        throw new FsError(`not a directory: ${dir}`, ERROR_CODE.WORKSPACE_DENIED)
+      }
+      const limitN = Math.min(Math.max(Number(limit) || 500, 1), LS_PAGE_MAX)
+      const offsetN = Math.max(Number(offset) || 0, 0)
+      const all = []
+      for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+        const abs = path.join(dir, ent.name)
+        if (entryDenied(abs, conf)) continue
+        let type = 'file'
+        let size = 0
+        let mtimeMs = 0
+        if (ent.isSymbolicLink()) {
+          // 链接只报条目本身，不深入也不解引用 —— 防止 roots 内链接逃逸
+          type = 'link'
+        } else if (ent.isDirectory()) {
+          type = 'dir'
+        } else if (ent.isFile()) {
+          try {
+            const s = fs.statSync(abs)
+            size = s.size
+            mtimeMs = s.mtimeMs
+          } catch {
+            // 竞态（文件刚被删）：仍上报名字，大小/时间留空
+          }
+        } else {
+          continue // socket/fifo 等非常规条目不上报
+        }
+        all.push({ name: ent.name, type, size, mtimeMs })
+      }
+      sortEntries(all)
+      return {
+        path: dir,
+        total: all.length,
+        offset: offsetN,
+        truncated: offsetN + limitN < all.length,
+        entries: all.slice(offsetN, offsetN + limitN),
+      }
+    },
+
+    /**
+     * 读文件。文本模式：≤ READABLE_FILE_MAX 的文件按行分段（offset/limit），
+     * 单次文本量 ≤ READ_TEXT_MAX；二进制模式：只回 sha256/size/头部预览。
+     */
+    read({ path: p, offset = 0, limit = 500 } = {}) {
+      const file = resolveAny(p, conf)
+      let st
+      try {
+        st = fs.statSync(file)
+      } catch {
+        throw new FsError(`path not found: ${file}`, ERROR_CODE.ARTIFACT_MISSING)
+      }
+      if (!st.isFile()) {
+        throw new FsError(`not a regular file: ${file}`, ERROR_CODE.WORKSPACE_DENIED)
+      }
+      let fd
+      try {
+        fd = fs.openSync(file, 'r')
+        if (looksBinary(fd)) {
+          // 二进制：hash 全文件 + 头部预览（hex），绝不回原始字节
+          const buf = Buffer.alloc(Math.min(st.size, SNIFF_BYTES))
+          fs.readSync(fd, buf, 0, buf.length, 0)
+          const hash = createHash('sha256')
+          const chunk = Buffer.alloc(1024 * 1024)
+          for (;;) {
+            const n = fs.readSync(fd, chunk, 0, chunk.length, null)
+            if (n <= 0) break
+            hash.update(chunk.subarray(0, n))
+          }
+          return {
+            path: file,
+            binary: true,
+            size: st.size,
+            sha256: hash.digest('hex'),
+            ext: extname(normalizePath(file, { caseInsensitive })),
+            head: buf.toString('hex'),
+          }
+        }
+        if (st.size > READABLE_FILE_MAX) {
+          throw new FsError(
+            `file too large for text read (${st.size} > ${READABLE_FILE_MAX}); use grep to locate then read a narrower path`,
+            ERROR_CODE.ARTIFACT_TOO_LARGE,
+          )
+        }
+        const raw = fs.readFileSync(file)
+        const text = raw.toString('utf8')
+        const lines = text.split('\n')
+        // 尾部空行是 split 的伪影：文件以 \n 结尾时多出一个空串
+        if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop()
+        const offsetN = Math.max(Number(offset) || 0, 0)
+        const limitN = Math.min(Math.max(Number(limit) || 500, 1), 5000)
+        const slice = []
+        let bytes = 0
+        let truncated = false
+        for (let i = offsetN; i < lines.length; i++) {
+          const line = lines[i]
+          // 单行超长截断：一行 1MB 的压缩 JSON 会独自顶爆响应
+          const clipped = line.length > 2000 ? `${line.slice(0, 2000)}…[line truncated]` : line
+          const cost = Buffer.byteLength(clipped, 'utf8') + 1
+          if (bytes + cost > READ_TEXT_MAX) {
+            truncated = true
+            break
+          }
+          slice.push(clipped)
+          bytes += cost
+          if (slice.length >= limitN) {
+            truncated = i < lines.length - 1
+            break
+          }
+        }
+        return {
+          path: file,
+          binary: false,
+          size: st.size,
+          totalLines: lines.length,
+          offset: offsetN,
+          truncated: truncated || offsetN + slice.length < lines.length,
+          lines: slice,
+        }
+      } finally {
+        try {
+          if (fd !== undefined) fs.closeSync(fd)
+        } catch {
+          // 关闭失败不影响结果
+        }
+      }
+    },
+
+    /**
+     * 副机本地全文搜索：递归扫 roots 内目录，文本文件逐行匹配。
+     * 纯 JS（Windows 没有外部 grep 可 spawn）；上限见模块头注释。
+     */
+    grep({ path: p, pattern, regex = false, ignoreCase = true, glob = '', maxMatches = GREP_MAX_MATCHES } = {}) {
+      if (typeof pattern !== 'string' || pattern === '') {
+        throw new FsError('pattern is required', ERROR_CODE.WORKSPACE_DENIED)
+      }
+      let re
+      try {
+        re = regex
+          ? new RegExp(pattern, ignoreCase ? 'i' : '')
+          : new RegExp(pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), ignoreCase ? 'i' : '')
+      } catch (err) {
+        throw new FsError(`invalid pattern: ${err.message}`, ERROR_CODE.WORKSPACE_DENIED)
+      }
+      const dir = resolveAny(p, conf)
+      let st
+      try {
+        st = fs.statSync(dir)
+      } catch {
+        throw new FsError(`path not found: ${dir}`, ERROR_CODE.ARTIFACT_MISSING)
+      }
+      const maxN = Math.min(Math.max(Number(maxMatches) || GREP_MAX_MATCHES, 1), GREP_MAX_MATCHES)
+      const matches = []
+      let filesScanned = 0
+      let filesSkipped = 0
+      let truncatedByTime = false
+      let truncatedByLimit = false
+      const started = Date.now()
+
+      const isGlobMatch = (name) => {
+        if (!glob) return true
+        // 极简 glob：* 任意（不含 /）、? 单字符 —— 覆盖 *.txt / src* 之类
+        const esc = glob.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*').replace(/\?/g, '[^/]')
+        return new RegExp(`^${esc}$`, caseInsensitive ? 'i' : '').test(name)
+      }
+
+      const scan = (dirAbs) => {
+        if (matches.length >= maxN) {
+          truncatedByLimit = true
+          return
+        }
+        if (Date.now() - started > GREP_TIME_MS) {
+          truncatedByTime = true
+          return
+        }
+        let ents
+        try {
+          ents = fs.readdirSync(dirAbs, { withFileTypes: true })
+        } catch {
+          filesSkipped++
+          return
+        }
+        for (const ent of ents) {
+          if (matches.length >= maxN) {
+            truncatedByLimit = true
+            return
+          }
+          if (Date.now() - started > GREP_TIME_MS) {
+            truncatedByTime = true
+            return
+          }
+          const abs = path.join(dirAbs, ent.name)
+          if (entryDenied(abs, conf)) continue
+          if (ent.isDirectory()) {
+            scan(abs)
+            continue
+          }
+          // 链接与非常规文件跳过：不跟随、不读
+          if (!ent.isFile()) {
+            filesSkipped++
+            continue
+          }
+          if (!isGlobMatch(ent.name)) continue
+          let fst
+          try {
+            fst = fs.statSync(abs)
+          } catch {
+            filesSkipped++
+            continue
+          }
+          if (fst.size > GREP_FILE_MAX || fst.size === 0) {
+            filesSkipped++
+            continue
+          }
+          let fd
+          try {
+            fd = fs.openSync(abs, 'r')
+            if (looksBinary(fd)) {
+              filesSkipped++
+              continue
+            }
+            const content = fs.readFileSync(abs)
+            filesScanned++
+            const text = content.toString('utf8')
+            const lines = text.split('\n')
+            for (let i = 0; i < lines.length && matches.length < maxN; i++) {
+              if (re.test(lines[i])) {
+                matches.push({
+                  file: abs,
+                  line: i + 1,
+                  text: lines[i].length > 500 ? `${lines[i].slice(0, 500)}…` : lines[i],
+                })
+                // 达到全局上限即如实报告截断 —— 即使恰好在最后一个文件结束，
+                // 未报出的命中大概率还存在（用户视角"还有更多"才是事实）
+                if (matches.length >= maxN) truncatedByLimit = true
+              }
+            }
+          } catch {
+            filesSkipped++
+          } finally {
+            try {
+              if (fd !== undefined) fs.closeSync(fd)
+            } catch {
+              // 忽略关闭失败
+            }
+          }
+        }
+      }
+
+      if (st.isDirectory()) {
+        scan(dir)
+      } else if (st.isFile()) {
+        // 单文件 grep：直接匹配该文件
+        let fd
+        try {
+          fd = fs.openSync(dir, 'r')
+          if (!looksBinary(fd)) {
+            filesScanned++
+            const lines = fs.readFileSync(dir).toString('utf8').split('\n')
+            for (let i = 0; i < lines.length && matches.length < maxN; i++) {
+              if (re.test(lines[i])) {
+                matches.push({ file: dir, line: i + 1, text: lines[i].slice(0, 500) })
+              }
+            }
+          }
+        } catch {
+          filesSkipped++
+        } finally {
+          try {
+            if (fd !== undefined) fs.closeSync(fd)
+          } catch {
+            // 忽略
+          }
+        }
+      } else {
+        throw new FsError(`not a directory or file: ${dir}`, ERROR_CODE.WORKSPACE_DENIED)
+      }
+
+      return {
+        path: dir,
+        pattern,
+        filesScanned,
+        filesSkipped,
+        matches,
+        matchCount: matches.length,
+        truncated: truncatedByTime || truncatedByLimit,
+        truncatedBy: truncatedByTime ? 'time' : truncatedByLimit ? 'maxMatches' : undefined,
+      }
+    },
+
+    /** 目录树摘要：扫描在副机跑完只回结构（50GB 也不搬家）。 */
+    tree({ path: p, depth = TREE_DEFAULT_DEPTH, maxEntries = TREE_MAX_ENTRIES } = {}) {
+      const rootDir = resolveAny(p, conf)
+      let st
+      try {
+        st = fs.statSync(rootDir)
+      } catch {
+        throw new FsError(`path not found: ${rootDir}`, ERROR_CODE.ARTIFACT_MISSING)
+      }
+      if (!st.isDirectory()) {
+        throw new FsError(`not a directory: ${rootDir}`, ERROR_CODE.WORKSPACE_DENIED)
+      }
+      const depthN = Math.min(Math.max(Number(depth) || TREE_DEFAULT_DEPTH, 1), 6)
+      const maxN = Math.min(Math.max(Number(maxEntries) || TREE_MAX_ENTRIES, 1), TREE_MAX_ENTRIES)
+      let used = 0
+      let truncated = false
+
+      const build = (dirAbs, level) => {
+        if (level > depthN || used >= maxN) {
+          if (used >= maxN) truncated = true
+          return []
+        }
+        let ents
+        try {
+          ents = fs.readdirSync(dirAbs, { withFileTypes: true })
+        } catch {
+          return [{ name: '(unreadable)', type: 'error' }]
+        }
+        const items = []
+        const dirs = []
+        const files = []
+        for (const ent of ents) {
+          const abs = path.join(dirAbs, ent.name)
+          if (entryDenied(abs, conf)) continue
+          if (ent.isDirectory()) dirs.push(ent.name)
+          else if (ent.isFile()) files.push(ent.name)
+          // 链接只报名字标注 link，不深入（与 ls 同口径）
+          else if (ent.isSymbolicLink()) files.push(ent.name)
+        }
+        const collator = (a, b) => a.localeCompare(b, undefined, { sensitivity: 'base', numeric: true })
+        dirs.sort(collator)
+        files.sort(collator)
+        for (const name of dirs) {
+          if (used >= maxN) {
+            truncated = true
+            break
+          }
+          used++
+          const node = { name, type: 'dir', children: build(path.join(dirAbs, name), level + 1) }
+          items.push(node)
+        }
+        for (const name of files) {
+          if (used >= maxN) {
+            truncated = true
+            break
+          }
+          used++
+          items.push({ name, type: 'file' })
+        }
+        return items
+      }
+
+      const items = build(rootDir, 1)
+      return {
+        path: rootDir,
+        depth: depthN,
+        entries: used,
+        maxEntries: maxN,
+        truncated: truncated || used >= maxN,
+        items,
+      }
+    },
+  }
+}

package/lib/node/index.js

@@ -51,6 +51,9 @@ import { friendlyConnectError } from '../setup.js'
 import { scanRepos } from './repos.js'
 import { TaskEngine } from './task-engine.js'
 import { TaskStore } from './task-store.js'
+// 远程文件工具集（提案 #25）：ls/read/grep/tree 只读实现，与任务链路共用
+// roots / denyPaths / caseInsensitive 三个配置（同一个安全边界，两处入口）。
+import { createFsService } from './fs-service.js'
 import { NodeTransport, TRANSPORT_MODE } from './transport.js'
 
 const PLUGIN_NAME = 'dsh-remote-agent'
@@ -452,6 +455,10 @@ function startWorker(ctx, config) {
     stateDir,
   ]
 
+  // 远程文件工具集（提案 #25）：与任务链路同源的 roots/denyPaths —— 同一个
+  // 安全边界，两处入口。只读实现，见 lib/node/fs-service.js 头注释。
+  const fsService = createFsService({ roots, denyPaths, caseInsensitive })
+
   /* 3) 任务仓库 ------------------------------------------------------- */
   let store
   try {
@@ -554,7 +561,11 @@ function startWorker(ctx, config) {
     : RESOURCE_INTERVAL_MS
   const resourceTimer = resourceIntervalMs > 0
     ? setInterval(() => {
-      send(NODE_TO_HUB.RESOURCE, { nodeId, ...sampler.sample() })
+      // 队列健康快照（提案 #26-3）随资源帧搭车：engine 在下方第 7 节才
+      // 装配，但 interval 回调最早也在装配完成后才触发，引用安全。
+      // engine 尚未就绪（极端：interval 在装配中途先触发）时给空快照。
+      const queue = engine ? engine.queueStats() : { queued: 0, running: 0, maxConcurrent: 0, oldestQueuedMs: 0, starved: false }
+      send(NODE_TO_HUB.RESOURCE, { nodeId, ...sampler.sample(), queue })
     }, resourceIntervalMs)
     : undefined
   if (resourceTimer?.unref) resourceTimer.unref()
@@ -601,7 +612,8 @@ function startWorker(ctx, config) {
     caseInsensitive,
     send,
     logger,
-    maxConcurrent: Number.isFinite(cfg.maxConcurrent) ? Math.max(1, cfg.maxConcurrent) : 2,
+    // 默认 4（提案 #26-2）：2 太脆，两条慢任务就能锁死整台机器。
+    maxConcurrent: Number.isFinite(cfg.maxConcurrent) ? Math.max(1, cfg.maxConcurrent) : 4,
   })
 
   // TaskEngine.pump() 用 `void this.execute(taskId)` 起任务 —— 一旦 execute reject，
@@ -782,6 +794,11 @@ function startWorker(ctx, config) {
         // transport 自己已回 pong；这里保留一条兜底，防止上层换实现后 ping 悬空
         send(NODE_TO_HUB.PONG, { echo: frame.id, nodeId, time: Date.now() }, { replyTo: frame.id })
         return
+      case HUB_TO_NODE.FS_REQ:
+        // 远程文件工具集（提案 #25）：异步执行，不挡后续帧；结果回 fs/res，
+        // reqId 就是请求信封 id（hub 按 replyTo 对 pending 表）。
+        handleFsReq(frame, d)
+        return
       case HUB_TO_NODE.ERROR:
         logger.warn('hub reported error', { code: d.code, message: d.message, replyTo: d.replyTo })
         return
@@ -790,6 +807,31 @@ function startWorker(ctx, config) {
     }
   }
 
+  /**
+   * 执行一条远程文件请求（提案 #25）。所有错误——包括被 FsError 表达的
+   * 业务拒绝（越界 / denyPaths / 超限）——都折进 fs/res 的 ok:false 载荷，
+   * 让 hub 工具层拿到结构化的 code 而不是一条 ERROR 帧。
+   */
+  function handleFsReq(frame, d) {
+    const op = typeof d.op === 'string' ? d.op : ''
+    const ops = { ls: 'ls', read: 'read', grep: 'grep', tree: 'tree' }
+    const fn = ops[op]
+    if (!fn) {
+      send(NODE_TO_HUB.FS_RES, { replyTo: frame.id, ok: false, code: ERROR_CODE.WORKSPACE_DENIED, message: `unknown fs op: ${op || '(empty)'}` })
+      return
+    }
+    const started = Date.now()
+    swallow(Promise.resolve().then(() => {
+      const result = fsService[fn](d)
+      logger.debug('fs op done', { op, ms: Date.now() - started, nodeId })
+      send(NODE_TO_HUB.FS_RES, { replyTo: frame.id, ok: true, result })
+    }).catch((err) => {
+      const code = typeof err?.code === 'string' ? err.code : ERROR_CODE.INTERNAL
+      logger.warn('fs op failed', { op, ms: Date.now() - started, code, error: msgOf(err) })
+      send(NODE_TO_HUB.FS_RES, { replyTo: frame.id, ok: false, code, message: msgOf(err) })
+    }))
+  }
+
   /* 9) 事件接线 ------------------------------------------------------- */
   const listenerDisposers = []
   const on = (evt, fn) => {

package/lib/node/task-engine.js

@@ -26,6 +26,23 @@ import { isDenied, resolveWorkspace, runCommand } from './exec.js'
 /** 摘要里最多保留多少条 changed 记录。 */
 const MAX_CHANGED = 500
 
+/**
+ * 默认任务超时（提案 #26-1）：**exec 与 agent 分开**。
+ *
+ * 一条 exec 卡住 = 整台副机 1 小时不可用是 #26 实测的事故形态（两条慢 exec
+ * 占满 maxConcurrent，队列永动不了）。exec 是跑命令，绝大多数 1 分钟内结束；
+ * 10 分钟足够暴露"命令本身有问题"（路径不存在/权限/巨目录）。agent 会话
+ * 可能真的要跑很久，保持 1 小时。
+ *
+ * tools.js 的 remote_task 默认值必须与这里**同源**（直接 import 本常量），
+ * 否则会出现"工具说 10 分钟、副机兜底 1 小时"的分裂。
+ */
+export const EXEC_DEFAULT_TIMEOUT_MS = 10 * 60 * 1000
+export const AGENT_DEFAULT_TIMEOUT_MS = 60 * 60 * 1000
+
+/** 队列饥饿判定阈值（提案 #26-3）：queued>0 且并发占满且最久排队超过此时长。 */
+export const QUEUE_STARVED_AFTER_MS = 2 * 60 * 1000
+
 export class TaskEngine {
   /**
    * @param {object} o
@@ -53,8 +70,10 @@ export class TaskEngine {
     this.logger = o.logger
     /** taskId → { controller, startedAt } */
     this.running = new Map()
-    /** 任务并发上限，防止副机被一次派单压垮 */
-    this.maxConcurrent = o.maxConcurrent ?? 2
+    /** 任务并发上限，防止副机被一次派单压垮。
+     *  默认 4（提案 #26-2）：2 太脆 —— 两条慢任务就能锁死整台机器；
+     *  4 让"两条慢 + 两条快"正常共存。配置项保留，按内存调整。 */
+    this.maxConcurrent = o.maxConcurrent ?? 4
     this.queue = []
     /** 卸载闸门：stop() 置 true 后不再接受/启动新任务（见 stop() 注释）。 */
     this.stopped = false
@@ -319,7 +338,9 @@ export class TaskEngine {
     try {
       res = await runCommand(command, {
         cwd: rec.workspace,
-        timeoutMs: rec.constraints?.timeoutMs ?? 60 * 60 * 1000,
+        // exec 默认 10 分钟（提案 #26-1，与 tools.js 同源常量）；任务显式
+        // 传 timeoutMs 时以任务为准（长遍历大目录等场景仍可显式放宽）。
+        timeoutMs: rec.constraints?.timeoutMs ?? EXEC_DEFAULT_TIMEOUT_MS,
         env: rec.constraints?.extraEnv ?? {},
         signal: controller.signal,
         onData: (chunk, stream) => {
@@ -369,7 +390,7 @@ export class TaskEngine {
       // 落盘为 null 表示未指定 → 传 undefined，让 runner 走"副机默认"路径。
       // in-process 后端会把它叠加到副机默认选择上；headless 后端会明确拒绝。
       model: rec.model ?? undefined,
-      timeoutMs: rec.constraints?.timeoutMs ?? 60 * 60 * 1000,
+      timeoutMs: rec.constraints?.timeoutMs ?? AGENT_DEFAULT_TIMEOUT_MS,
       signal: controller.signal,
       onData: (chunk, stream) => {
         for (const line of chunk.split(/\r?\n/)) {
@@ -491,6 +512,32 @@ export class TaskEngine {
     return map
   }
 
+  /**
+   * 队列健康快照（提案 #26-3）：随资源遥测帧上报 hub。
+   *
+   * 背景（#26 实测事故）：两条慢 exec 占满 maxConcurrent 后，pump() 的
+   * while 条件永假，后续任务全部 queued 且**在面板上不可见**——用户只知道
+   * "卡了"，不知道"卡在哪"。这个快照让 hub/面板能说出一句话：
+   * "队列被 N 条运行中任务阻塞，最久已等 M 分钟"。
+   *
+   * starved 判定：有排队 + 并发占满 + 最久排队超过 QUEUE_STARVED_AFTER_MS。
+   * 纯读操作，绝不影响任务链路（与资源遥测同一条尽力而为不变式）。
+   */
+  queueStats(now = Date.now()) {
+    const queuedAt = this.queue
+      .map((id) => this.store.get(id)?.createdAt)
+      .filter((t) => typeof t === 'number' && t > 0)
+    const oldestQueuedMs = queuedAt.length > 0 ? Math.max(0, now - Math.min(...queuedAt)) : 0
+    const saturated = this.running.size >= this.maxConcurrent
+    return {
+      queued: this.queue.length,
+      running: this.running.size,
+      maxConcurrent: this.maxConcurrent,
+      oldestQueuedMs,
+      starved: this.queue.length > 0 && saturated && oldestQueuedMs > QUEUE_STARVED_AFTER_MS,
+    }
+  }
+
   /** 重连后向 hub 上报全部任务状态。 */
   syncAll() {
     this.send('task/sync', {

package/lib/node/transport.js

@@ -66,6 +66,8 @@ const E2E_REQUIRED_TYPES = new Set([
   HUB_TO_NODE.ARTIFACT_LIST,
   HUB_TO_NODE.ARTIFACT_PULL,
   HUB_TO_NODE.ARTIFACT_CANCEL,
+  // 远程文件请求（提案 #25）：目录结构与文件内容是敏感信息，必须加密。
+  HUB_TO_NODE.FS_REQ,
 ])
 
 /** 副机侧永远明文的帧类型（握手/心跳/交换本身）。 */