dsh-remote-agent 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -9,6 +9,43 @@
 
 ---
 
+## [0.6.0] - 2026-10-17
+
+### 修复：单条慢命令锁死整台副机（提案 #26，实测事故防线）
+
+实测事故：两条慢 exec 占满 `maxConcurrent=2` 后，后续任务**全部 queued 且一条
+都不执行**；重启副机后重派同样命令再次锁死。根因是 `maxConcurrent=2` 与
+exec 默认超时 1 小时的组合 —— 一条卡住的命令 = 整台副机一小时不可用。
+
+**行为变更（默认值）**：
+
+- **exec / agent 默认超时分开**：exec 10 分钟（绝大多数命令 1 分钟内结束，
+  10 分钟足够暴露"命令本身有问题"）、agent 保持 1 小时。工具层与副机兜底
+  **同源常量**（`task-engine.js` 导出，`tools.js` 直接 import），显式
+  `timeoutMs` 仍然优先。
+- **maxConcurrent 默认 2 → 4**：2 太脆 —— 两条慢任务就能锁死整台机器；
+  4 让"两条慢 + 两条快"正常共存。配置项保留，按内存调整。
+
+**可见性：队列健康遥测（#26-3）**：
+
+- 副机 `TaskEngine.queueStats()` 每 30s 随资源遥测帧搭车上报：
+  `{queued, running, maxConcurrent, oldestQueuedMs, starved}`。
+  `starved` = 有排队 + 并发占满 + 最久排队超 2 分钟。
+- `remote_nodes` 透出 `queue` 字段；starved 节点渲染 ⚠ 堵死告警并给出
+  下一步动作（remote_status 逐条查 / remote_cancel 释放并发槽）——
+  用户不再只知道"卡了"，还知道"卡在哪、等多久、怎么办"。
+- 旧副机不上报 queue（向后兼容），remote_nodes 相应行缺席。
+
+**如实说明**：exec 的取消链路核查结论是**真杀进程树**（Windows
+`taskkill /T /F`、POSIX `kill(-pgid)`，abort → killTree 已实装）——
+"remote_cancel 无效"的残余风险在 agent 会话卡在不检查 signal 的 await
+与快照同步扫描（`snapshotWorkspace`），留待 #26 后续批次。
+
+测试：引擎侧 3 条（常量同源文本断言 / maxConcurrent 默认 / queueStats 判定
+矩阵）+ e2e 资源遥测用例扩展（queue 贯通 + starved 渲染）。全量 825 tests。
+
+---
+
 ## [0.5.0] - 2026-10-17
 
 ### 功能：远程文件工具集（提案 #25）

package/README.en.md

@@ -244,6 +244,16 @@ There is also a Web panel (sidebar → "远程同事"): node list (with CPU / me
 / load badges), task dispatch, task states, result summaries, workspace
 changes, change diffs, final artifacts, log tail.
 
+> **Queue starvation has an alarm** (defense added after a real incident on
+> 2026-10-17): every 30s the worker reports queue health along with resource
+> telemetry (queued / running / longest wait). When "tasks are queued AND all
+> concurrency slots are busy AND the oldest has waited over 2 minutes",
+> `remote_nodes` shows a ⚠ starvation warning on that node with the suggested
+> next step (remote_status to inspect, remote_cancel to free a slot). The
+> default concurrency is raised 2 → 4 and the default exec timeout tightened
+> from 1 hour to 10 minutes — a single slow command can no longer easily lock
+> up the whole worker.
+
 ### Tool reference
 
 <details>
@@ -260,7 +270,7 @@ changes, change diffs, final artifacts, log tail.
 | `mode` | `agent` (worker starts an independent agent session, default) / `exec` (run a command directly) |
 | `model` | Optional. Model the worker should use (`mode=agent` only): `{model:"deepseek-chat"}` or `{provider:"openai",model:"gpt-4o"}`. Selection only, no credentials —— the worker runs it with its own provider config; unsupported on headless backends |
 | `outputs` | Glob of expected outputs (relative to the workspace), used to filter the artifact manifest |
-| `timeoutMs` | Worker-side timeout, 1 hour by default |
+| `timeoutMs` | Worker-side timeout. Defaults by mode: **exec 10 minutes, agent 1 hour** (one slow exec should not pin the worker for an hour) |
 | `denyPaths` | Extra absolute paths to deny |
 | `artifactRules` | Override built-in artifact role classification, e.g. `{ intermediate: ["build/**"] }` |
 

package/README.md

@@ -217,6 +217,13 @@ ack 自动按明文兼容旧中继继续），安全边界与已知局限见
 派发任务、**待审批卡**（exec 任务默认挂起，批准才下发）、任务状态、结果摘要、
 工作区变更、**变更 diff**（文本文件改动的 unified diff）、成品清单、日志尾巴。
 
+> **队列堵死有告警**（2026-10-17 实测事故的防线）：副机每 30s 随资源遥测上报
+> 队列健康（排队数 / 并发占用 / 最久等待）。当"有排队且并发占满且最久已等
+> 超 2 分钟"时，`remote_nodes` 会在该节点行打 ⚠ 堵死告警并给出下一步动作
+> （remote_status 逐条查、remote_cancel 释放并发槽）。默认并发已从 2 提到 4，
+> 一条慢 exec 的默认超时也从 1 小时收紧到 10 分钟 —— 单条慢命令锁死整台
+> 副机的概率大幅降低。
+
 ### 工具速查
 
 <details>
@@ -233,7 +240,7 @@ ack 自动按明文兼容旧中继继续），安全边界与已知局限见
 | `mode` | `agent`（副机起独立 agent 会话，默认）/ `exec`（直接跑命令）|
 | `model` | 可选。副机用的模型（仅 `mode=agent` 生效）：`{model:"deepseek-chat"}` 或 `{provider:"openai",model:"gpt-4o"}`。只传选择不传凭证 —— 副机用自己的 provider 配置跑；headless 后端不支持 |
 | `outputs` | 期望产出物的 glob（相对工作区），用于产物清单筛选 |
-| `timeoutMs` | 副机侧超时，默认 1 小时 |
+| `timeoutMs` | 副机侧超时。缺省按模式：**exec 10 分钟、agent 1 小时**（一条慢 exec 不该锁死副机一小时） |
 | `denyPaths` | 额外禁止访问的绝对路径 |
 | `artifactRules` | 覆盖内置产物角色判定，例如 `{ intermediate: ["build/**"] }` |
 

package/lib/hub/node-registry.js

@@ -862,6 +862,9 @@ class NodeRegistryCore {
       // 资源遥测（最近一次 node/resource；null = 尚未上报）。离线节点保留
       // 最后一份 —— 带 at 时间戳，消费方自行判断新鲜度。
       resource: r.resource ?? null,
+      // 队列健康快照（提案 #26-3）：null = 副机未上报（旧版本）。starved=true
+      // 表示"有排队且并发占满且最久排队超 2 分钟"——派发前值得先看一眼。
+      queue: r.queue ?? null,
       // 仓库清单（提案 #13）：路由提示。remote_nodes 给名字列表供选型，
       // repo 路由细节在 pickNodeByRepo。
       repos: Array.isArray(r.repos) ? r.repos.map((x) => x.name) : [],

package/lib/hub/registry-ingest.js

@@ -163,6 +163,18 @@ export function withIngest(Base) {
             memTotalMb: num(d.memTotalMb),
             at: Date.now(),
           }
+          // 队列健康快照（提案 #26-3，新副机随帧搭车）。旧副机不发 queue ——
+          // 保留 rec.queue 原值（可能是 undefined），remote_nodes 按 null 展示。
+          const q = d.queue && typeof d.queue === 'object' && !Array.isArray(d.queue) ? d.queue : null
+          if (q) {
+            rec.queue = {
+              queued: num(q.queued) ?? 0,
+              running: num(q.running) ?? 0,
+              maxConcurrent: num(q.maxConcurrent) ?? 0,
+              oldestQueuedMs: num(q.oldestQueuedMs) ?? 0,
+              starved: q.starved === true,
+            }
+          }
           return
         }
 

package/lib/hub/tools.js

@@ -34,6 +34,9 @@ import {
   newTaskId,
   validateTaskStart,
 } from '../protocol.js'
+// exec/agent 分开的默认超时（提案 #26-1）——与副机兜底**同源**，
+// 避免"工具说 10 分钟、副机兜底 1 小时"的分裂。
+import { AGENT_DEFAULT_TIMEOUT_MS, EXEC_DEFAULT_TIMEOUT_MS } from '../node/task-engine.js'
 // 视图投影共享层：与 UI 路由用**同一份**白名单（见 lib/hub/views.js 的说明）。
 import { handoffView } from './views.js'
 
@@ -348,7 +351,7 @@ export function handoffSummaryText(task) {
  */
 export function registerRemoteTools({ ctx, registry, pulls, log: _log, defaults = {} }) {
   const disposers = []
-  const defaultTimeoutMs = num(defaults.timeoutMs) ?? 60 * 60 * 1000
+  const explicitTimeoutMs = num(defaults.timeoutMs)
 
   /**
    * 注册一个工具，并给它的 `execute` **统一套上返回值净化**。
@@ -419,6 +422,18 @@ export function registerRemoteTools({ ctx, registry, pulls, log: _log, defaults
                     at: { type: 'number' },
                   },
                 },
+                // 队列健康快照（提案 #26-3）：副机未上报（旧版本）时为 null，
+                // 由 dropNullForSchema 剥掉。字段全部有值（0/false 兜底）。
+                queue: {
+                  type: 'object',
+                  properties: {
+                    queued: { type: 'number' },
+                    running: { type: 'number' },
+                    maxConcurrent: { type: 'number' },
+                    oldestQueuedMs: { type: 'number' },
+                    starved: { type: 'boolean' },
+                  },
+                },
               },
               required: ['nodeId', 'online'],
             },
@@ -441,6 +456,15 @@ export function registerRemoteTools({ ctx, registry, pulls, log: _log, defaults
           if (n.resource) {
             lines.push(`  资源: CPU ${n.resource.cpuPct ?? '—'}% · 内存 ${n.resource.memUsedMb ?? '—'}/${n.resource.memTotalMb ?? '—'}MB · load1 ${n.resource.load1 ?? '—'}`)
           }
+          // 队列健康（提案 #26-3）：starved 是"该去副机看看卡在哪"的强信号
+          if (n.queue) {
+            if (n.queue.starved === true) {
+              const waited = Math.round((n.queue.oldestQueuedMs ?? 0) / 60000)
+              lines.push(`  ⚠ 队列疑似堵死：${n.queue.running}/${n.queue.maxConcurrent} 并发占满，${n.queue.queued} 条排队，最久已等 ${waited >= 1 ? `${waited} 分钟` : `${n.queue.oldestQueuedMs}ms`}。用 remote_status 逐条查 running 任务，必要时 remote_cancel。`)
+            } else if ((n.queue.queued ?? 0) > 0) {
+              lines.push(`  队列: ${n.queue.running}/${n.queue.maxConcurrent} 在跑，${n.queue.queued} 条排队`)
+            }
+          }
         }
         return lines.join('\n')
       }),
@@ -479,7 +503,7 @@ export function registerRemoteTools({ ctx, registry, pulls, log: _log, defaults
           additionalProperties: false,
         },
         outputs: { type: 'array', items: { type: 'string' }, description: '期望产出物的 glob（相对工作区），用于产物清单筛选。' },
-        timeoutMs: { type: 'number', description: `副机侧任务超时（毫秒），默认 ${defaultTimeoutMs}。` },
+        timeoutMs: { type: 'number', description: `副机侧任务超时（毫秒）。缺省按模式：exec ${EXEC_DEFAULT_TIMEOUT_MS / 60000} 分钟、agent ${AGENT_DEFAULT_TIMEOUT_MS / 60000} 分钟。` },
         denyPaths: { type: 'array', items: { type: 'string' }, description: '副机侧额外禁止访问的路径（绝对路径）。' },
         artifactRules: {
           type: 'object',
@@ -589,7 +613,10 @@ export function registerRemoteTools({ ctx, registry, pulls, log: _log, defaults
         // 只有消费者没有生产者，用户无法覆盖内置的产物角色判定）
         artifactRules: args?.artifactRules,
         constraints: {
-          timeoutMs: num(args?.timeoutMs) ?? defaultTimeoutMs,
+          // 提案 #26-1：缺省按模式分开（exec 10min / agent 1h），与副机兜底
+          // 同源常量；defaults.timeoutMs（配置显式指定）优先于一切缺省。
+          timeoutMs: num(args?.timeoutMs) ?? explicitTimeoutMs
+            ?? (v.spec.mode === TASK_MODE.EXEC ? EXEC_DEFAULT_TIMEOUT_MS : AGENT_DEFAULT_TIMEOUT_MS),
           denyPaths: Array.isArray(args?.denyPaths) ? args.denyPaths : [],
         },
         origin: 'hub',

package/lib/node/index.js

@@ -561,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()
@@ -608,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，

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/package.json

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