@menghuan1918/dsh-apollo 0.0.0-stage → 0.3.0

package/package.json

@@ -1,6 +1,77 @@
 {
   "name": "@menghuan1918/dsh-apollo",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "DSH plugin: 流程技能、工程模式、Codex/Claude 可续接子代理与统一设置。纯 ESM，无构建步骤。",
+  "license": "GPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Menghuan1918/dsh-apollo.git"
+  },
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./client": "./src/client.js",
+    "./presets/*": "./presets/*",
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0",
+    "dsh": ">=0.2.1-rc.2 <0.3.0"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "files": [
+    "src",
+    "docs",
+    "skills",
+    "presets",
+    "third-party",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "deepseek-harness-plugin",
+    "workflow",
+    "orchestration",
+    "agent-preset"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "devDependencies": {
+    "js-yaml": "^4.2.0",
+    "react": "18.3.1",
+    "react-test-renderer": "18.3.1"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "~3.18.4",
+    "dsh-better-goal": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": [
+        "./cordis.patch.yml",
+        "./presets/eng.patch.yml",
+        "./presets/eng-noask.patch.yml"
+      ]
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-client-ui-settings"
+      ],
+      "platform": "web"
+    }
+  }
+}

package/presets/eng/NOTICE

@@ -0,0 +1,2 @@
+presets/eng.patch.yml 的 config.plugins 块改编自 DeepSeek Harness 内置
+Standard preset（MIT）。原始 DeepSeek 版权和 MIT 许可声明见开源仓库。

package/presets/eng/plugins/exit-guard/index.js

@@ -0,0 +1,111 @@
+/**
+ * `eng-exit-guard` — 工程模式退出守卫（预设本地插件）。
+ *
+ * pi-atlas task guard 的 DSH 等价物：回合即将结束时（`agent/turn-stopping`，
+ * serial 事件——监听器跑完后 agent-loop 会重查 inbox，`agent.steer()` 加入的
+ * next-step 消息使回合不关闭），若本代理仍有运行中的直接子代理或后台任务，
+ * 注入一条提醒强制回合继续，直到 wait_subagent / job_output 等待收取、
+ * job_kill 停止，或用户中断（被中断的回合在 dispatch 前即 throwIfAborted，
+ * 天然不触发本守卫——Esc 始终是逃生口）。
+ *
+ * 无豁免机制（曾有 exitGuardIgnore 子串清单，因会被用来静默绕过守卫而移除
+ * ——实测有会话中 agent 被拦一次后自行写入豁免，后续回合全部静默放行）：
+ * 任何存活的后台 job 都必须被收取或停止，回合才能收尾。需要跨回合常驻的
+ * 服务（dev server、watcher）用 pm2/systemd/裸 nohup 等脱离 DSH job 注册表
+ * 的方式管理——守卫只看本地 job 注册表与直接子代理。
+ *
+ * 每次事件读取当前 profile 的 Apollo Config.exitGuard（默认关闭）。
+ * 设置保存后即时生效；旧配置只由宿主执行一次性导入。
+ * 查询失败（listChildren / jobs.list 抛错）按 fail-open 处理：告警并放行本次
+ * 回合结束，避免查询故障把回合卡死。
+ *
+ * 零 bare import（同 wait-subagent 约束）；消息构造参照 goal-round-driver /
+ * repeat-tool-reminder 的 plain-object 模式。
+ */
+
+import { currentConfig } from '../../../../src/config.js'
+
+export const name = 'eng-exit-guard'
+
+export const inject = ['subagents', 'agents']
+
+/** 后台任务终态（dsh-jobs-local isTerminal 同款）。 */
+const JOB_TERMINAL = new Set(['completed', 'killed', 'failed'])
+
+/** 渲染一条运行项清单行。 */
+function lineOf(prefix, id, detail) {
+  return `  - ${prefix} ${id}${detail === undefined || detail === '' ? '' : `（${detail}）`}`
+}
+
+/**
+ * 构造 steer 提醒消息（模型可见，进入会话日志）。
+ * @param children - 运行中的直接子代理 listChildren 条目。
+ * @param jobs - 运行中的后台任务快照。
+ * @returns 一条 user 角色的 plugin notice 消息。
+ */
+function buildMessage(children, jobs) {
+  const lines = []
+  for (const child of children) {
+    // 0.1.1-rc.2 的条目是 meta:{mode,label}，0.1.2 起 mode/label 升为顶级；
+    // 兼容回退只影响展示措辞，绝不抛错。
+    lines.push(lineOf('子代理', child.id, child.label ?? child.meta?.label))
+  }
+  for (const job of jobs) {
+    lines.push(lineOf('后台任务', job.id, job.label === undefined ? job.kind : `${job.label}，${job.kind}`))
+  }
+  const text = [
+    '⚠️ 以下后台工作仍在运行，回合不能结束：',
+    ...lines,
+    '',
+    '请先用 wait_subagent 等待运行中的子代理（需要续用其对话用 send_message）、'
+      + '用 job_output 收取后台命令的结果；确属不需要的用 job_kill 停止，全部处理完毕后再收尾。',
+  ].join('\n')
+  return {
+    role: 'user',
+    content: [{ type: 'text', text }],
+    source: {
+      kind: 'plugin',
+      plugin: 'eng-exit-guard',
+      form: 'notice',
+      summary: `运行中的后台工作阻止回合结束（子代理 ${children.length}，后台任务 ${jobs.length}）`,
+    },
+    id: crypto.randomUUID(),
+  }
+}
+
+/**
+ * 收集本代理仍在运行的后台工作。
+ * @param ctx - 预设插件上下文（subagents / agents 注入，jobs 可选）。
+ * @param agent - 回合即将结束的代理。
+ * @returns `{ children, jobs }`；查询失败抛出由调用方按 fail-open 处理。
+ */
+async function collectRunning(ctx, agent) {
+  const children = []
+  for (const entry of await ctx.subagents.listChildren(agent.id)) {
+    if (ctx.agents.get(entry.id)?.status === 'running') children.push(entry)
+  }
+  const jobs = ctx.get('jobs')
+  const runningJobs = jobs === undefined
+    ? []
+    // 0.1.7 起 JobRegistry.list 的参数是 SessionId（0.1.6 及以前是 Agent 对象）：
+    // 传 Agent 对象不报错但恒不匹配，守卫会静默看不见任何 owned 后台任务。
+    : jobs.list(agent.id).filter((job) => !JOB_TERMINAL.has(job.status))
+  return { children, jobs: runningJobs }
+}
+
+export function apply(ctx) {
+  ctx.on('agent/turn-stopping', async (payload) => {
+    const agent = payload?.agent
+    if (agent === undefined || payload?.signal?.aborted) return
+    try {
+      if (!currentConfig(ctx).exitGuard) return
+      const { children, jobs } = await collectRunning(ctx, agent)
+      if (children.length === 0 && jobs.length === 0) return
+      if (payload.signal?.aborted) return
+      agent.steer(buildMessage(children, jobs))
+    } catch (error) {
+      // fail-open：查询或注入失败时放行本次回合结束，守卫不应卡死会话。
+      ctx.logger?.warn?.(`eng-exit-guard: guard skipped: ${error instanceof Error ? error.message : String(error)}`)
+    }
+  })
+}

package/presets/eng/plugins/exit-guard/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "dsh-preset-eng-exit-guard",
+  "private": true,
+  "type": "module",
+  "main": "index.js",
+  "version": "0.1.0"
+}

package/presets/eng/plugins/mode-instructions/index.js

@@ -0,0 +1,48 @@
+/**
+ * `eng-mode-instructions` — preset-scoped prompt section for the eng preset
+ * (工程模式). Carries the two eng-only behaviors no other surface states:
+ *  - the exit guard contract;
+ *  - the delegation/orchestration policy (when to delegate, write scopes,
+ *    verification, failure handling), moved out of the user-global
+ *    ~/.dsh/AGENTS.md on 2026-09-11.
+ * Model tiers stay in ~/.dsh/AGENTS.md: they mirror this host's
+ * `subagent-model-selection.allowedModels` route list, which is local config.
+ * Everything else — tool mechanics, background-job etiquette, sleep caps —
+ * lives in the harness system prompt or the tool descriptions, and is
+ * deliberately NOT repeated here. Dedupe first, inject only the delta.
+ *
+ * Zero imports on purpose (same constraint as the sibling wait-subagent
+ * plugin): this module loads from the preset directory, where Node's upward
+ * node_modules walk never reaches the harness install.
+ */
+
+export const name = 'eng-mode-instructions'
+
+export const inject = ['systemPrompt']
+
+const TEXT = [
+  '# 工程模式专属',
+  '',
+  '工程模式（eng）面向编码与基础设施任务。',
+  '',
+  '- 退出守卫：回合结束前仍有运行中的子代理或后台命令时，回合不会关闭——系统注入运行清单提醒，先用 wait_subagent / job_output 等待收取、job_kill 停掉不需要的，处理完毕再收尾。',
+  '',
+  '## 委派与编排',
+  '',
+  '- 开局侦察：非琐碎任务在陌生或大型代码库上开始时，情况了解（仓库结构、相关模块定位、约定与测试入口）默认立即并行派发快速档侦察子代理，同批在一条消息里一起派；主线程只保留定义任务必需的指令类文件阅读（AGENTS.md、PRD、任务说明）。不要为「写好委派 prompt」而先单线程探索——侦察 prompt 只需目标、边界、交付物，缺的上下文正是侦察要产出的东西。',
+  '- 默认委派：只读、可并行、无状态的调查一律派出去（含大型/陌生仓库、前端代码、批量排查），同一批独立任务在一条消息里一起派，不在主线程先试一遍。',
+  '- 转委派阈值：实现/调试中途冒出的新未知，主线程深挖 1–2 轮未收敛立即派出去；开局侦察不适用此阈值。',
+  '- 实现分层：写入范围互不重叠的独立实现块派子代理并行推进；线性推进、强耦合改动、需要持续控制活状态的调试（活进程、串行打补丁）留主线程。',
+  '- 扇出用 workflow：同一形状的工作重复多份（审计、迁移、多角度验证、批量修复）即属大型多代理编排，直接写 workflow 脚本一次编排；一两次委派仍用 subagent。',
+  '- 派发写明目标、写入范围、交付物与验证方式；引用的前置产出给实际文件路径——子代理看不到父对话。',
+  '- 并行实现子代理的写入范围不得重叠；最终集成、审查、验证由主代理负责；子代理报告是线索不是证据，亲自核对实际变更状态。',
+  '- 子代理以 error / 空返回收场：先读失败原因，修正路由或重派一次；仍失败且无外部阻塞才主线程接管，并在当轮说明为何接管。',
+].join('\n')
+
+export function apply(ctx) {
+  ctx.effect(() => ctx.systemPrompt.section({
+    name: 'eng:mode-instructions',
+    order: 1,
+    text: TEXT,
+  }), 'eng-mode-instructions.section()')
+}

package/presets/eng/plugins/mode-instructions/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "dsh-preset-eng-mode-instructions",
+  "private": true,
+  "type": "module",
+  "main": "index.js",
+  "version": "0.1.0"
+}

package/presets/eng/plugins/wait-subagent/index.js

@@ -0,0 +1,228 @@
+/**
+ * `wait_subagent` tool — explicit wait for continuable children to settle.
+ *
+ * Preset-local plugin for the eng preset (resolved relative to this preset's
+ * directory). Continuable subagents live in the `subagents` registry, not the
+ * `jobs` registry, so the only settlement signal is the scoped `subagent/end`
+ * event. The tool takes an ARRAY of durable child ids (`subagent_id`), awaits
+ * them all concurrently (duplicates deduped, order preserved), and returns one
+ * SHORT line per id (done + stopReason).
+ *
+ * The children's content is none of this tool's business: the subagent manager
+ * unconditionally delivers a settlement notice to the parent BEFORE
+ * `subagent/end` fires (dispose order: notifySettlement() →
+ * observer.settle()), carrying the one-line account and the closing message.
+ * A busy parent is steered, so the notice sits in the pending next-step queue
+ * and reaches the model right after this tool result — exactly once, per
+ * child, by the framework. Earlier designs returned the child's final message
+ * here AND spliced the duplicate notice (and any mid-run `report`) out of the
+ * parent inbox; that coupled this plugin to `agent.inbox` internals and to
+ * the `subagent-report` source kind, which upstream removed in
+ * 0.1.2-alpha.4 (bidirectional `send_message` replaced `report`). Returning
+ * "done" lines and leaving delivery to the framework has no such coupling.
+ * Mid-run messages the child sends (`send_message`, source kind
+ * `agent-message`) likewise stay in place.
+ *
+ * `timeout_ms` is ONE shared window over the whole batch (all timers start at
+ * the same instant), matching the semantics same-message parallel calls had.
+ * An id that is not a direct child fails the whole call fast — nobody is
+ * waited for — keeping the contract the single-id version had. A child
+ * dispatched moments ago may not have started its first turn yet: its status
+ * is not `running` and no settlement exists. Returning early with a "not
+ * running" note there (the pre-grace behavior) ended the turn before the
+ * child even started and forced a re-wait on the next turn — session audit
+ * 2f5dd618. Instead, a not-yet-started child gets a startup grace window
+ * (START_GRACE_MS): the tool keeps waiting while the child spins up,
+ * settles, the optional timeout elapses, or the grace expires without the
+ * child ever starting (only then a retryable informational line).
+ *
+ * Zero imports on purpose: the module loads from the preset directory, where
+ * Node's upward node_modules walk never reaches the harness install, so bare
+ * package imports would fail. Everything needed comes from the context.
+ */
+
+export const name = 'tool-wait-subagent'
+
+export const inject = ['tools', 'subagents', 'agents']
+
+/** Grace window for a just-dispatched child that has not started running yet. */
+const START_GRACE_MS = 30_000
+
+/** Status polling interval while waiting for a not-yet-started child. */
+const POLL_MS = 250
+
+export function apply(ctx) {
+  /** childId -> { time, info } — latest settlement observed since mount. */
+  const settled = new Map()
+  /** childId -> finish(info) callbacks awaiting settlement. */
+  const waiters = new Map()
+
+  ctx.on('subagent/end', (info) => {
+    const id = info && info.id
+    if (typeof id !== 'string') return
+    settled.set(id, { time: Date.now(), info })
+    const list = waiters.get(id)
+    if (list !== undefined) {
+      waiters.delete(id)
+      for (const finish of [...list]) finish({ kind: 'settled', info })
+    }
+  })
+
+  ctx.tools.register({
+    name: 'wait_subagent',
+    description: 'Wait for one or more background continuable subagents (spawned by subagent or subagent_fork) to finish their current turn. Pass their durable ids as an array in subagent_id — all are awaited concurrently and the result carries one short line per id (done + stop reason); a child\'s closing message arrives as the framework settlement notice immediately after this result; do not expect it here. Blocks until every listed child settles, the optional timeout_ms elapses (one shared window over all ids), or the user interrupts — without timeout_ms, until completion. A just-dispatched child that has not started yet is awaited through a brief startup grace rather than reported as not running. Use it when your next step depends on those results; with independent work remaining, prefer background plus completion notices. Do not pass bash job ids — those use job_output.',
+    parameters: {
+      type: 'object',
+      properties: {
+        subagent_id: {
+          type: 'array',
+          items: { type: 'string' },
+          minItems: 1,
+          description: 'One or more durable subagent ids returned by the subagent or subagent_fork tool call; every id is awaited concurrently.',
+        },
+        timeout_ms: {
+          type: 'integer',
+          description: 'Optional maximum wait in milliseconds applied as one shared window over all ids; omit to wait until every child settles. On expiry the tool returns while some children are still running.',
+        },
+      },
+      required: ['subagent_id'],
+    },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
+    isConcurrencySafe: () => true,
+    async execute(args, exec) {
+      // Dedupe preserving input order; the schema already enforces a
+      // non-empty array, the guard below only covers malformed direct calls.
+      const ids = [...new Set(Array.isArray(args.subagent_id) ? args.subagent_id : [])]
+      if (ids.length === 0) return 'subagent_id must be a non-empty array of subagent ids.'
+      const parent = exec.agent
+      if (parent === undefined) throw new Error('wait_subagent requires a calling agent (exec.agent was undefined)')
+
+      // Verify every id is one of this agent's direct children — fail fast,
+      // waiting for nobody (the contract the single-id version had).
+      let entries
+      try {
+        entries = await ctx.subagents.listChildren(parent.id, exec.signal)
+      } catch (error) {
+        return 'listChildren failed: ' + (error && error.message ? error.message : String(error))
+      }
+      const known = new Set(entries.map((entry) => entry.id))
+      const unknown = ids.filter((id) => !known.has(id))
+      if (unknown.length > 0) {
+        return `unknown subagent ${unknown.map((id) => `"${id}"`).join(', ')}: not a direct child of this agent (list_agents shows your children; only depth-1 children can be awaited).`
+      }
+
+      const statusOf = (id) => {
+        const agent = ctx.agents.get(id)
+        return agent === undefined ? 'ready' : agent.status === 'running' ? 'running' : 'idle'
+      }
+
+      /** Settlement line: short done line; content belongs to the framework notice. */
+      const doneLine = (id, info) => `subagent ${id} done (${info && info.stopReason ? info.stopReason : 'completed'}); its closing message follows as the settlement notice.`
+
+      const startedAt = Date.now()
+      const capMs = typeof args.timeout_ms === 'number' && args.timeout_ms > 0 ? args.timeout_ms : undefined
+
+      /**
+       * Wait for one child. Resolves with {kind:'settled',info} |
+       * {kind:'timedOut'} | {kind:'aborted'} | {kind:'notStarted'}. The
+       * per-id machinery (settled fast path, waiter registration, timeout
+       * timer, startup-grace poller) is the single-id logic of old,
+       * unchanged; Promise.all over ids gives the concurrent batch.
+       */
+      const waitOne = (id) => {
+        // Fast path: the child is not running and a settlement is already on
+        // record — resolve immediately (the notice was already delivered when
+        // the child settled, so it is in the conversation history).
+        if (statusOf(id) !== 'running') {
+          const hit = settled.get(id)
+          if (hit !== undefined) return Promise.resolve({ kind: 'settled', info: hit.info })
+        }
+
+        return new Promise((resolve) => {
+          let done = false
+          let timer
+          let poller
+          const finish = (value) => {
+            if (done) return
+            done = true
+            if (poller !== undefined) clearInterval(poller)
+            const list = waiters.get(id)
+            if (list !== undefined) {
+              const index = list.indexOf(finish)
+              if (index >= 0) list.splice(index, 1)
+              if (list.length === 0) waiters.delete(id)
+            }
+            if (timer !== undefined) clearTimeout(timer)
+            if (exec.signal !== undefined) exec.signal.removeEventListener('abort', onAbort)
+            resolve(value)
+          }
+          const onAbort = () => finish({ kind: 'aborted' })
+
+          const list = waiters.get(id) ?? []
+          list.push(finish)
+          waiters.set(id, list)
+          // All ids share startedAt, so one capMs value is one shared window.
+          if (capMs !== undefined) timer = setTimeout(() => finish({ kind: 'timedOut' }), capMs)
+          if (exec.signal !== undefined) {
+            if (exec.signal.aborted) {
+              finish({ kind: 'aborted' })
+              return
+            }
+            exec.signal.addEventListener('abort', onAbort, { once: true })
+          }
+
+          // Startup grace: a freshly dispatched child sits between spawn and
+          // its first turn (status not `running`, no settlement yet). Keep the
+          // wait alive while it spins up; once `running`, only `subagent/end`
+          // (the listener above) resolves us. If the grace expires without the
+          // child ever starting or settling, fall back to a retryable note
+          // instead of the old misleading "is not running" early return.
+          poller = setInterval(() => {
+            if (done) return
+            const hit = settled.get(id)
+            if (hit !== undefined) {
+              finish({ kind: 'settled', info: hit.info })
+              return
+            }
+            if (statusOf(id) !== 'running' && Date.now() - startedAt >= START_GRACE_MS) {
+              finish({ kind: 'notStarted' })
+            }
+          }, POLL_MS)
+
+          // Re-check: the child may have settled between the fast path above
+          // and waiter registration. Only a settlement AFTER this wait started
+          // counts as a live result.
+          const hit = settled.get(id)
+          if (hit !== undefined && hit.time >= startedAt) finish({ kind: 'settled', info: hit.info })
+        })
+      }
+
+      const outcomes = await Promise.all(ids.map((id) => waitOne(id)))
+
+      // Every waiter shares one abort signal, so an interruption either
+      // aborts the whole batch or lands after some children already settled.
+      // Collapse the all-aborted case into one line; mixed cases keep
+      // per-id lines so the settled ones are not lost.
+      if (outcomes.length > 0 && outcomes.every((outcome) => outcome.kind === 'aborted')) {
+        return `wait for ${ids.length} subagent${ids.length === 1 ? '' : 's'} was aborted by user interruption; the children may still be running.`
+      }
+
+      const lines = outcomes.map((outcome, index) => {
+        const id = ids[index]
+        if (outcome.kind === 'aborted') return `wait for subagent ${id} was aborted by user interruption; the child may still be running.`
+        if (outcome.kind === 'timedOut') return `timed out waiting for subagent ${id}; it is still running. You will be notified when it finishes — you can wait_subagent it again or continue with other work.`
+        if (outcome.kind === 'notStarted') {
+          return `subagent ${id} has not started after ${Math.round(START_GRACE_MS / 1000)}s (status: ${statusOf(id)}). It may still be spinning up — call wait_subagent again, or continue with other work; you will be notified when it finishes.`
+        }
+        // Real settlement: short done line; the framework's settlement notice
+        // (already delivered to the parent inbox before `subagent/end`)
+        // carries the closing message — nothing to consume or deduplicate.
+        return doneLine(id, outcome.info)
+      })
+      return lines.join('\n')
+    },
+  })
+}

package/presets/eng/plugins/wait-subagent/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "dsh-preset-eng-wait-subagent",
+  "private": true,
+  "type": "module",
+  "main": "index.js",
+  "version": "0.1.0"
+}

package/presets/eng-noask/NOTICE

@@ -0,0 +1,2 @@
+presets/eng-noask.patch.yml 的 config.plugins 块改编自 DeepSeek Harness 内置
+Standard preset（MIT）。原始 DeepSeek 版权和 MIT 许可声明见开源仓库。

package/presets/eng-noask/plugins/exit-guard/index.js

@@ -0,0 +1,111 @@
+/**
+ * `eng-exit-guard` — 工程模式退出守卫（预设本地插件）。
+ *
+ * pi-atlas task guard 的 DSH 等价物：回合即将结束时（`agent/turn-stopping`，
+ * serial 事件——监听器跑完后 agent-loop 会重查 inbox，`agent.steer()` 加入的
+ * next-step 消息使回合不关闭），若本代理仍有运行中的直接子代理或后台任务，
+ * 注入一条提醒强制回合继续，直到 wait_subagent / job_output 等待收取、
+ * job_kill 停止，或用户中断（被中断的回合在 dispatch 前即 throwIfAborted，
+ * 天然不触发本守卫——Esc 始终是逃生口）。
+ *
+ * 无豁免机制（曾有 exitGuardIgnore 子串清单，因会被用来静默绕过守卫而移除
+ * ——实测有会话中 agent 被拦一次后自行写入豁免，后续回合全部静默放行）：
+ * 任何存活的后台 job 都必须被收取或停止，回合才能收尾。需要跨回合常驻的
+ * 服务（dev server、watcher）用 pm2/systemd/裸 nohup 等脱离 DSH job 注册表
+ * 的方式管理——守卫只看本地 job 注册表与直接子代理。
+ *
+ * 每次事件读取当前 profile 的 Apollo Config.exitGuard（默认关闭）。
+ * 设置保存后即时生效；旧配置只由宿主执行一次性导入。
+ * 查询失败（listChildren / jobs.list 抛错）按 fail-open 处理：告警并放行本次
+ * 回合结束，避免查询故障把回合卡死。
+ *
+ * 零 bare import（同 wait-subagent 约束）；消息构造参照 goal-round-driver /
+ * repeat-tool-reminder 的 plain-object 模式。
+ */
+
+import { currentConfig } from '../../../../src/config.js'
+
+export const name = 'eng-exit-guard'
+
+export const inject = ['subagents', 'agents']
+
+/** 后台任务终态（dsh-jobs-local isTerminal 同款）。 */
+const JOB_TERMINAL = new Set(['completed', 'killed', 'failed'])
+
+/** 渲染一条运行项清单行。 */
+function lineOf(prefix, id, detail) {
+  return `  - ${prefix} ${id}${detail === undefined || detail === '' ? '' : `（${detail}）`}`
+}
+
+/**
+ * 构造 steer 提醒消息（模型可见，进入会话日志）。
+ * @param children - 运行中的直接子代理 listChildren 条目。
+ * @param jobs - 运行中的后台任务快照。
+ * @returns 一条 user 角色的 plugin notice 消息。
+ */
+function buildMessage(children, jobs) {
+  const lines = []
+  for (const child of children) {
+    // 0.1.1-rc.2 的条目是 meta:{mode,label}，0.1.2 起 mode/label 升为顶级；
+    // 兼容回退只影响展示措辞，绝不抛错。
+    lines.push(lineOf('子代理', child.id, child.label ?? child.meta?.label))
+  }
+  for (const job of jobs) {
+    lines.push(lineOf('后台任务', job.id, job.label === undefined ? job.kind : `${job.label}，${job.kind}`))
+  }
+  const text = [
+    '⚠️ 以下后台工作仍在运行，回合不能结束：',
+    ...lines,
+    '',
+    '请先用 wait_subagent 等待运行中的子代理（需要续用其对话用 send_message）、'
+      + '用 job_output 收取后台命令的结果；确属不需要的用 job_kill 停止，全部处理完毕后再收尾。',
+  ].join('\n')
+  return {
+    role: 'user',
+    content: [{ type: 'text', text }],
+    source: {
+      kind: 'plugin',
+      plugin: 'eng-exit-guard',
+      form: 'notice',
+      summary: `运行中的后台工作阻止回合结束（子代理 ${children.length}，后台任务 ${jobs.length}）`,
+    },
+    id: crypto.randomUUID(),
+  }
+}
+
+/**
+ * 收集本代理仍在运行的后台工作。
+ * @param ctx - 预设插件上下文（subagents / agents 注入，jobs 可选）。
+ * @param agent - 回合即将结束的代理。
+ * @returns `{ children, jobs }`；查询失败抛出由调用方按 fail-open 处理。
+ */
+async function collectRunning(ctx, agent) {
+  const children = []
+  for (const entry of await ctx.subagents.listChildren(agent.id)) {
+    if (ctx.agents.get(entry.id)?.status === 'running') children.push(entry)
+  }
+  const jobs = ctx.get('jobs')
+  const runningJobs = jobs === undefined
+    ? []
+    // 0.1.7 起 JobRegistry.list 的参数是 SessionId（0.1.6 及以前是 Agent 对象）：
+    // 传 Agent 对象不报错但恒不匹配，守卫会静默看不见任何 owned 后台任务。
+    : jobs.list(agent.id).filter((job) => !JOB_TERMINAL.has(job.status))
+  return { children, jobs: runningJobs }
+}
+
+export function apply(ctx) {
+  ctx.on('agent/turn-stopping', async (payload) => {
+    const agent = payload?.agent
+    if (agent === undefined || payload?.signal?.aborted) return
+    try {
+      if (!currentConfig(ctx).exitGuard) return
+      const { children, jobs } = await collectRunning(ctx, agent)
+      if (children.length === 0 && jobs.length === 0) return
+      if (payload.signal?.aborted) return
+      agent.steer(buildMessage(children, jobs))
+    } catch (error) {
+      // fail-open：查询或注入失败时放行本次回合结束，守卫不应卡死会话。
+      ctx.logger?.warn?.(`eng-exit-guard: guard skipped: ${error instanceof Error ? error.message : String(error)}`)
+    }
+  })
+}

package/presets/eng-noask/plugins/exit-guard/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "dsh-preset-eng-exit-guard",
+  "private": true,
+  "type": "module",
+  "main": "index.js",
+  "version": "0.1.0"
+}