dsh-stall-sentinel：DeepSeek Harness 的轻量级长任务卡死检测插件

DeepSeek Harness (DSH) 理念是“一切皆插件”。在智能体开发中，ctx.subprocess.spawn 生成的长任务（如后台构建、安装依赖）如果卡死，往往难以及时发现。现有监控方案要么依赖复杂的进程表查询，要么容易误杀正在运行的任务。dsh-stall-sentinel 是一个专为 DSH profile-bundle 设计的轻量级看门狗插件，它接管进程生成逻辑，通过探针采样提供卡死预警与取证报告，但不干扰任务执行。

插件简介¶

这是一个纯 JS Cordis 插件，零额外运行时依赖（仅使用 Node 内置模块）。它重写了 longtask-stall-guard 的思路，针对 DSH 场景从零实现，旨在提供进程卡死的自动检测与取证，绝不执行 kill、terminate 或重试操作。

核心能力¶

• 零额外运行时依赖：只依赖 node:* 内置模块，不引入复杂的外部库。
• 自动监控与接线：默认安装后自动拦截 ctx.subprocess.spawn，无需手动调用 guard.watch 即可覆盖 bash 工具、后台 pwsh 及其启动的构建任务。
• 保守的判定模型：基于“进度冻结”与“CPU 状态（空闲或打满）”的双信号聚合取证。只有连续两个采样窗口满足条件才判定卡死。
• 仅提醒与取证：处理动作唯一为“提醒 + 生成取证报告”，绝不执行 kill、terminate 或重试操作。
• 完整日志记录：支持 JSONL 事件日志记录与轮转，便于事后分析。

安装¶

插件以 dsh.bundle.patch 包的形式提供。安装时需确保其排在基础包之后。

dsh plugin --profile <profile> add <path-or-link-to-this-dir>

或者在 profile 的 cordis.patch.yml 中直接引用本地路径：

- insert:
    - id: stall-sentinel
      name: './plugins/dsh-stall-sentinel/lib/index.js'
      config: { enabled: true }

使用方式¶

插件通过 ctx.provide('stall-sentinel', api) 暴露控制接口。你可以手动注册需要监控的目标：

const guard = ctx.get('stall-sentinel');
const { taskId } = guard.watch({
  taskId: 'my-build',
  label: 'pnpm install',
  pid: child.pid,
  logPath: 'C:\\agent\\install.log',
  marker: 'added'
});
guard.getStatus();
guard.list();
guard.unwatch(taskId);

关键点：目标必须提供 logPath（用于进度信号）和 pid。没有 logPath 的目标会永久处于 unknown 状态，无法区分慢与卡死。

适用场景与注意¶

• 适用场景：适用于通过 ctx.subprocess.spawn 启动的长任务（如后台 pwsh、npm install、构建脚本）。这些任务默认被自动监控。
• 边界说明：
• 对于 ctx.jobs 中纯 job 记录（无 pid、无输出暴露），插件仅做存活跟踪，无法判定是否卡死。
• 对于 ctx.shell 层面，插件通过 subprocess seam 覆盖，不直接消费输出。
• 插件在受限沙箱（禁 Node pipe spawn）中通过 stdio: ['ignore', fdOut, fdErr] 仍可工作。
• 可靠性契约：插件绝不杀进程，只读取探针。采样失败会降级为 unknown。日志落盘异常会回退到 console.error。