@menghuan1918/dsh-apollo 0.0.0-stage → 0.4.0

package/package.json

@@ -1,6 +1,78 @@
 {
   "name": "@menghuan1918/dsh-apollo",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.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",
+    "prompts": "node scripts/render-prompts.mjs"
+  },
+  "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-ptc.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,3 @@
+presets/eng.patch.yml 与 presets/eng-ptc.patch.yml 的 config.plugins 块改编自
+DeepSeek Harness 内置 Standard / PTC 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('subagent', child.id, child.label ?? child.meta?.label))
+  }
+  for (const job of jobs) {
+    lines.push(lineOf('background job', job.id, job.label === undefined ? job.kind : `${job.label}, ${job.kind}`))
+  }
+  const text = [
+    'This background work is still running, so the turn cannot end yet:',
+    ...lines,
+    '',
+    'Wait for running subagents with wait_subagent (use send_message to continue one), '
+      + 'collect background command results with job_output, and stop work you no longer need with job_kill. Finish only after all of it is handled.',
+  ].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,124 @@
+/**
+ * `eng-mode-instructions` — preset-scoped prompt section for 工程模式
+ * (`eng`) and 工程(PTC)模式 (`eng-ptc`).
+ *
+ * Carries what no other surface states: the general engineering discipline
+ * (moved out of the user-global ~/.dsh/AGENTS.md, which keeps only
+ * machine-local conventions), the delegation policy, the subagent model tiers
+ * rendered from Apollo settings (`tiers.*`), and the exit guard contract while
+ * that switch is on. Tool mechanics, background-job etiquette and run_code
+ * syntax live in the harness prompt and tool descriptions and are NOT
+ * repeated here.
+ *
+ * The text is a function re-rendered per request from the live Apollo config,
+ * so settings edits apply without remounting; an edit costs the prefix cache
+ * once, which is acceptable for rarely changed settings. The row config
+ * `ptc: true` (set by eng-ptc) adds a rule for fanning out subagents inside
+ * one run_code program (workflow usage is left to the harness tool guidance); run_code mechanics themselves
+ * come from the harness `tools:sdk` / `tools:ptc-only` sections.
+ */
+
+import z from '@deepseek-ai/schemastery'
+import { currentConfig } from '../../../../src/config.js'
+
+export const name = 'eng-mode-instructions'
+
+export const inject = ['systemPrompt']
+
+export const Config = z.object({
+  /** Render the PTC variant (eng-ptc). */
+  ptc: z.boolean().default(false),
+})
+
+const PRINCIPLES = `# Engineering mode
+
+For coding and infrastructure work. These are defaults; explicit user instructions take precedence.
+
+## Principles
+- KISS / YAGNI: use the simplest approach that works. Do not add abstractions, indirection, or options the task does not need.
+- Inspect first: read the actual files, run the actual commands, check the actual state, then judge. When evidence and judgment disagree, evidence wins. Look up unfamiliar library/API behavior instead of relying on memory.
+- Fix the root cause: trace a bad value back to the violated assumption; no workarounds that only hide the symptom.
+- One coherent change at a time, each with an observable result and a pass/fail check; do not bundle unrelated edits.
+- Follow existing conventions: match surrounding naming, style, error handling, and patterns; use the project's own build/test/lint commands; read the repo's coding-standards files (if any) before writing code.
+- Think about requirements, approach, and verification; do not draft whole implementations in your reasoning. If your reasoning starts repeating, stop, change angle, or go gather evidence.
+
+## Avoid over-engineering and over-defending
+- Do not add complexity for speculative needs or vanishingly unlikely race/security edge cases. If one seems necessary, first explain the concrete failure mode, its likelihood, and the complexity cost to the user and get agreement; never silently expand scope for theoretical robustness.
+- Validate unknown input once, at the boundary that owns it, and pass settled values inward; do not re-check what a schema, constructor, or type already guarantees.
+- Put try/catch only where the error can actually be handled; never use it to swallow errors or hide failures.
+- Do not extract single-use helpers unless they name a real concept or isolate a genuinely complex boundary.
+- Comment non-obvious constraints and surprising behavior, not what the code already says.
+- Test the real implementation; minimize mocks; do not copy implementation logic into tests.
+
+## Verification and reporting
+- Claim success only with fresh evidence from the changed state. Passing lint does not prove runtime behavior; unit tests do not prove deployment integration.
+- In reports, separate verified, executed-but-unverified, and not executed. Never fake progress.
+
+## Boundaries
+- Changing shared branches such as main or dev needs explicit authorization. Within the task, commits and merges on isolated branches are fine; create worktrees for isolation when useful.
+- Preserve unrelated changes and keep the main worktree clean; recurring local files can go in .git/info/exclude.
+- Commit with the configured global Git identity, never placeholder identities such as bot or agent.
+- Tell the user when you install system packages or download dependencies outside the package manager; ask where to install missing unmanaged dependencies; prefer prebuilt packages over compiling.
+- No filesystem-wide or whole-home-directory searches without asking first.
+- Deviating from these rules needs the user's consent. Before asking, explore the code, tests, and prior decisions yourself; ask only questions whose answers change what you do, each with a recommended answer and why.
+
+## Commands and processes
+- One background job per goal: check job_list first; do not run near-duplicate commands in parallel.
+- Work on data where it already is (including remote mounts) instead of downloading or copying large files.
+- Before killing a process, confirm its full command line and PID with \`pgrep -af <keyword>\`, then \`kill <PID>\`; never pkill / killall.
+- Never sleep longer than 60s at once; for longer waits use stepped probes, sentinel files, or completion notices.
+- Run services that must outlive the turn (dev servers, watchers) under pm2/nohup outside the job registry, and say which ones are still running when you finish.`
+
+const DELEGATION_HEAD = `## Delegation
+- Subagents cannot see this conversation: state the goal, write scope, deliverable, and verification, and give real file paths for prior outputs.
+- Opening reconnaissance: when starting non-trivial work in an unfamiliar or large codebase, immediately dispatch fast-tier scouts in parallel (structure, relevant modules, conventions, test entry points), all in one message; the main agent reads only the instruction files that define the task. A scout prompt needs only goal, boundaries, and deliverable.
+- Delegate read-only, parallelizable, stateless investigation by default instead of trying it in the main thread first; when a new unknown appears mid-task and 1–2 rounds of digging do not converge, delegate it.
+- Implementation chunks with non-overlapping write scopes can run in parallel; keep linear work, tightly coupled changes, and debugging that needs live state in the main thread.`
+
+const FANOUT_PTC = '- For repeated same-shaped work, dispatch all subagents inside one run_code program, then collect them with wait_subagent.'
+
+const DELEGATION_TAIL = `- When you need a subagent's result, wait patiently with wait_subagent. Do not poll or prod it with send_message; send a message only to give it genuinely new information or a correction.
+- The main agent owns integration, review, and final verification. Subagent reports are leads, not evidence: check the actual changes yourself.
+- When a subagent ends in an error or empty result, read why, fix the cause, and re-dispatch once; take over in the main thread only if it fails again without an external blocker, and say why.`
+
+const EXIT_GUARD = `## Exit guard
+- If subagents or background commands are still running when the turn would end, the system injects a reminder and the turn continues. Collect them with wait_subagent / job_output, stop unneeded ones with job_kill, then finish.`
+
+/** One tier as model-facing argument text; an unset tier inherits the parent route. */
+export function renderTier(tier) {
+  if (!tier?.provider || !tier?.model) return 'omit provider / model / reasoning_effort to inherit the parent route'
+  const parts = [`provider: \`${tier.provider}\``, `model: \`${tier.model}\``]
+  if (tier.reasoningEffort) parts.push(`reasoning_effort: \`${tier.reasoningEffort}\``)
+  return parts.join(' · ')
+}
+
+/**
+ * Render the full section text.
+ * @param config - normalized Apollo config (`exitGuard`, `tiers`).
+ * @param options - `{ ptc }` from this row's config.
+ * @returns the section markdown.
+ */
+export function renderInstructions(config, options = {}) {
+  const tiers = `## Subagent model tiers
+- Fast tier (exploration, reconnaissance, mechanical analysis, batch triage): ${renderTier(config.tiers?.fast)}
+- Quality tier (complex implementation, debugging, review, design): ${renderTier(config.tiers?.quality)}
+- Start exploration on the fast tier; when coverage falls short or key questions remain, re-dispatch the unresolved part on the quality tier. Escalating means re-dispatching, not modifying an existing subagent.
+- subagent_fork takes no model choice: it keeps the parent route to reuse the prefix cache.`
+  const blocks = [
+    PRINCIPLES,
+    [DELEGATION_HEAD, ...(options.ptc ? [FANOUT_PTC] : []), DELEGATION_TAIL].join('\n'),
+    tiers,
+  ]
+  if (config.exitGuard) blocks.push(EXIT_GUARD)
+  return blocks.join('\n\n')
+}
+
+export function apply(ctx, config) {
+  const options = { ptc: config?.ptc === true }
+  ctx.effect(() => ctx.systemPrompt.section({
+    name: 'eng:mode-instructions',
+    order: 1,
+    interpolate: false,
+    text: () => renderInstructions(currentConfig(ctx), options),
+  }), '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,233 @@
+/**
+ * `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.
+ * Values below MIN_TIMEOUT_MS (15 minutes) are raised to it: short polling
+ * waits only burned turns, since a finishing child notifies the parent anyway.
+ * 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
+
+/** Floor for a caller-supplied timeout_ms (15 minutes). */
+const MIN_TIMEOUT_MS = 15 * 60_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 direct subagents (from subagent or subagent_fork) to finish their current turn. Pass every id in subagent_id; all are awaited together and each gets one done line, while its closing message arrives as the settlement notice right after. Use it when your next step needs the results, instead of messaging the child to check on it. Not for bash jobs (use job_output).',
+    parameters: {
+      type: 'object',
+      properties: {
+        subagent_id: {
+          type: 'array',
+          items: { type: 'string' },
+          minItems: 1,
+          description: 'Durable ids returned by subagent or subagent_fork.',
+        },
+        timeout_ms: {
+          type: 'integer',
+          description: 'Optional shared wait window in ms; values below 900000 (15 minutes) are raised to 900000. Omit to wait until every child settles.',
+        },
+      },
+      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 ? Math.max(args.timeout_ms, MIN_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"
+}