dsh-goal-guard
后台子代理还在跑时，别让 goal 自动续跑被烧掉。
DeepSeek Harness（DSH / Cordis）插件。在「派发后台 continuable 子代理 → 结束回合 → 等结算通知」
这种委托纪律下，goal-round-driver 会在母会话每次回到 idle 时注入一轮 <goal_round>——
它不知道还有未结算的子代理。本插件在等待窗口内进程内解除 goal 的自动续跑
（goals.disarm，不产生耐久事件、不改 phase/revision），全部子代理结算后自动恢复
（goals.resume）。
为什么需要它（这是核心缺口，不是某个插件的私有 workaround）
@deepseek-ai/dsh-goal-round-driver 的 readyToDrive 只检查
return ctx.fiber.state === 2 && !state.stopping
&& ctx.agents.get(state.agent.id) === state.agent
&& state.agent.status === "idle"
&& !state.competingQueued
——没有子代理维度：该包不注入 subagents，Config 也只有 defaultMaxGoalRounds，
没有任何原生开关。而模型工具层的 update_goal(pause/resume) 要求「直接人类回合」，
模型自救不了。
远端实测（web profile，子代理运行期间）复现：
+ 66ms agent/created origin=subagent depth=1 ← 子代理诞生
+ 72ms agent/status running (子代理)
+209ms <goal_round> round=1 注入 ← ★ 子代理仍在跑，driver 照注入
+859ms agent/error QUOTA (子代理)
+943ms user/message sourceKind=subagent-settled ← 结算通知
装上本插件后同一场景：窗口内零注入，且结算后 goal 自动回到 armed（见下方验收记录）。
行为
| 时机 | 动作 |
|---|
子代理诞生（agent/created 带 origin='subagent' + parentSession） | 母会话 goal 若 active + armed → 抢先 disarm（母会话仍在 running，零竞态；覆盖 subagent / subagent_fork / workflow 等所有派发路径） |
goal 被 arm 但已有子代理在跑（goal/changed 采纳） | 立即 disarm（堵住「先派子代理、后 arm goal」的窗口） |
idle / 结算通知（agent/status idle、subagent-settled、turn/end） | 有 running 子代理 → 保持 disarm；无 running 子代理 → 自动 resume |
agent/error、回合 max-tokens / aborted | 毒化：不再自动 resume（不覆盖 harness 的熔断决定，交人类） |
agent/disposed、agent/session-start | 整段窗口状态作废（新 epoch 不继承） |
安全不变量
goals.resume 在服务层没有人类门（人类门在 dsh-tool-goal），所以本插件只重新武装
自己刚 disarm 过的、id + revision 完全一致、且仍为 active + disarmed 的 goal。
goal 被清 / 被编辑 / complete / blocked / paused / 被第三方重新武装 → 一律清 mark 交人类，
绝不猜。「还有子代理在跑」用 subagents.listDescendants(...) 的 activity === 'running'
判定；查询失败按「未知」处理，未知不构成 disarm 或 resume 的理由。
安装
# 方式一：DSH 插件管理器（写入 profile 依赖 + bundle 装配）
dsh plugin --profile web add /path/to/dsh-goal-guard
# 方式二：dsh-super-injector（运行时注入，免重启）
dev_inject_plugin /path/to/dsh-goal-guard
# 方式三：作为 profile patch overlay 挂载
dsh web --patch ./cordis.patch.yml
cordis.patch.yml 把本插件插到 profile 根 roster。挂载位置很重要：dsh-scope 的准入规则是
const tag = scopeOf(ctx);
if (tag === void 0) return true; // 未打标的监听器 → 全局准入
只有未打标的监听器才能收到根会话的 agent/status；被打标的 ctx 只收其作用域链后代的事件。
配置
# profile patch / 插件 config
- id: dsh-goal-guard
config:
enabled: true # 总开关；关闭即退回原生行为
statusRoute: true # 注册 /dsh-goal-guard/api/status
tool: true # 注册 goal_guard 工具
watchdogIntervalMs: 30000 # 看门狗周期；0 = 关闭
maxWindowMs: 1800000 # 窗口超时告警阈值
观测
GET /dsh-goal-guard/api/status → { ok, loggerPresent, guarded, tracked, states, diag }- 工具
goal_guard：action=status 看守卫状态；action=resume 立即重新评估并尝试恢复
（模型自查「为什么 goal 没继续」用）
- 告警走
ctx.logger.warn 并额外落 console.warn：某些宿主不把插件 logger 输出落到
可见位置，而「resume 失败 / 窗口卡住」是本功能唯一的人工可见面，不能丢
兼容性
| 项 | 值 |
|---|
dsh.engines.dsh | >=0.1.7-rc.1 <0.2 |
| peer | @deepseek-ai/cordis、@deepseek-ai/dsh-tools、@deepseek-ai/schemastery |
| 必需服务 | 无（goals / agents / subagents / tools / webServer 全部可选且惰性解析） |
验收记录（2026-10-15，远端测试环境）
被测形态 = 真实部署形态：插件放进 profiles/node_modules/，按包名由 profile 根 roster 挂载；
验收夹具另挂一个探针插件造激励（自建 root agent → 派 continuable 子代理 → arm goal），
不依赖 LLM 成功（远端凭证余额不足，回合以 QUOTA 失败，但生命周期事件齐全）。
| 场景 | 窗口内 <goal_round> 注入 | disarm 时点 | 结算后 resume | 判定 |
|---|
| 基线（无插件，探针实测） | 1 | — | — | 病根复现 |
adopt（先派子代理 → 再 arm goal） | 0 | arm 后 +15ms | ✅ armed | PASS |
proactive（先 arm goal → 立刻派子代理） | 0 | 子代理 agent/created 时（早于 spawn 时间戳） | ✅ armed | PASS |
对照数字：driver 从 goal/changed 到排队轮次约 178ms（内部有 await sessions.flush() 检查点），
守卫 disarm 在 15ms 内完成 → 赢约 160ms。/api/status 实测 HTTP 200，
diag spawned:1 / windowDisarms:1 / resumes:1 / resumeFails:0 / watchdogTicks:2。
复现（夹具在 test/remote/）：
# 远端：<DSH_HOME> 指向测试 home，dsh 用部署树里的 bin
scp -r lib package.json <remote>:<profile>/node_modules/dsh-goal-guard/
scp test/remote/goal-guard-accept.mjs test/remote/patch.yml <remote>:/root/test-env/
ssh <remote> 'cd /root/test-env && GG_ACCEPT_MODE=adopt dsh web --patch /root/test-env/patch.yml --port 3099 --no-open'
# 报告：/root/test-env/accept-out/report.json（看 verdict.pass）
开发
bash scripts/build.sh # src/ → lib/（从部署树链类型依赖，用全局 tsc）
npx tsc -p tsconfig.json --noEmit
npm test # node --test（先 build 再 test，测的是 lib/ 产物）
本仓库不 npm install：scripts/build.sh 从 ~/.dsh/profiles/node_modules 或
/usr/lib/node_modules/@deepseek-ai/dsh/node_modules 探测一份 DSH 依赖树，把
@deepseek-ai/* 软链进本地 node_modules 后用系统 tsc 编译。lib/ 是产物但入库
（files 含 lib），这样 dsh plugin add / git 直装不需要构建步骤。
两个踩过的坑（都来自真实部署，别重犯）
- 不要
import 'schemastery'。部署树里没有顶层 schemastery 包，只有
@deepseek-ai/schemastery（官方包与已发布第三方插件一律 import 这个 scoped 名）。
用顶层名会「本地构建通过、真机 failed to import」——本插件第一版就是这样在远端被拒的。
同理：不要靠 build 时生成的 node_modules/<name> 软链在运行期解析裸名。
- 服务句柄必须惰性取。实测 headless profile 在
apply() 时
goals/agents/subagents/tools 全部尚未就绪（到 agent/created 才齐）；
装配期抓死句柄会直接坏掉。本插件的 inject 因此留空。
License
BSD-3-Clause
