dsh-goal-guard

后台子代理还在跑时，别让 goal 自动续跑被烧掉。

DeepSeek Harness（DSH / Cordis）插件。在「派发后台 continuable 子代理 → 结束回合 → 等结算通知」
这种委托纪律下，goal-round-driver 会在母会话每次回到 idle 时注入一轮 `—— 它不知道还有未结算的子代理。本插件在等待窗口内**进程内**解除 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   round=1 注入                      ← ★ 子代理仍在跑，driver 照注入
+859ms  agent/error     QUOTA (子代理)
+943ms  user/message    sourceKind=subagent-settled     ← 结算通知

装上本插件后同一场景：窗口内零注入，且结算后 goal 自动回到 armed（见下方验收记录）。

行为

安全不变量

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 失败 / 窗口卡住」是本功能唯一的人工可见面，不能丢

兼容性

验收记录（2026-10-15，远端测试环境）

被测形态 = 真实部署形态：插件放进 profiles/node_modules/，按包名由 profile 根 roster 挂载；
验收夹具另挂一个探针插件造激励（自建 root agent → 派 continuable 子代理 → arm goal），
不依赖 LLM 成功（远端凭证余额不足，回合以 QUOTA 失败，但生命周期事件齐全）。

对照数字：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/）：

# 远端： 指向测试 home，dsh 用部署树里的 bin
scp -r lib package.json :/node_modules/dsh-goal-guard/
scp test/remote/goal-guard-accept.mjs test/remote/patch.yml :/root/test-env/
ssh  '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 直装不需要构建步骤。

两个踩过的坑（都来自真实部署，别重犯）

1. 不要 import 'schemastery'。部署树里没有顶层 schemastery 包，只有
   @deepseek-ai/schemastery（官方包与已发布第三方插件一律 import 这个 scoped 名）。
   用顶层名会「本地构建通过、真机 failed to import」——本插件第一版就是这样在远端被拒的。
   同理：不要靠 build 时生成的 node_modules/ 软链在运行期解析裸名。
2. 服务句柄必须惰性取。实测 headless profile 在 apply() 时
   goals/agents/subagents/tools 全部尚未就绪（到 agent/created 才齐）；
   装配期抓死句柄会直接坏掉。本插件的 inject 因此留空。

License

BSD-3-Clause