【建议】后台/continuable 子代理提供 wait 语义（对齐 job_output wait）

[NovaDev9-bot]

场景：0.1.2 起 job_output 不追踪子代理（unknown job，语义已明确，无异议）。依赖结果的派工现用前台 spawn 同步等待（正确姿势），continuable 后台子代理 settle 时有自动通知——这部分都工作正常。

残余缺口：父代理在串行阶段等待期间只能反复 list_agents 轮询，空转上下文与回合预算。

建议：提供 wait_for_agent(id, timeout) 阻塞语义（对齐 job_output 的 wait 通道），或文档化「等待期填窗」的官方编排姿势（并行派工/延迟收束）。复现环境：0.1.2-rc.1，win32。

[argszero]

Your diagnosis is right, and the source confirms the exact shape of the gap.

The settlement notification exists, but it's an inbox message, not a blocking wait. In the continuation manager, when a continuable child settles the parent is notified via a typed event message:

// packages/subagent/subagent/src/continuation.ts:75
readonly kind: 'subagent-settled'

That message is delivered to the parent's inbox (notifySettlement → the parent's own event loop), so the parent only observes it at its next step boundary. During a serial orchestration stage where the parent is "just waiting," there is nothing in the inbox to observe — the parent has to round-trip list_agents, which is exactly the empty-consuming loop you describe.

The second half of the gap is list_agents status ambiguity. Look at tool-subagent-control/src/list-agents.ts:53-62:

// 'running' for an active driver, 'idle' for a resident Agent between turns
// (possibly waiting on agents it started), and 'ready' when no live Agent remains.
function statusOf(...) { return agent.status === 'running' ? 'running' : 'idle' }

idle collapses two very different states: "loaded, genuinely between turns, nothing pending" and "waiting on agents it started." So even with polling, a parent can't distinguish "my child settled" from "my child is blocked waiting on its own children." That's why wait_for_agent(id, timeout) would be a real improvement rather than sugar — it turns the parent's ask from "interpret a coarse status" into "block until this specific agent is terminal."

Why a blocking wait_for_agent is the right shape over the polling loop: the settle notification already carries the precise signal (the subagent-settled message with the child id). A wait_for_agent tool would just bridge that signal into a blocking await the parent can issue, instead of forcing the parent to re-derive it by polling a status that can't distinguish blocked-waiting from terminal. The job_output wait analogy is apt — that's a Promise the parent awaits for one named thing.

Design note on the piece that's genuinely subtle: a continuable child may settle, but the parent's own continuation state machine has a waiting activation state (continuation.ts:156 'running' | 'waiting' | 'settled'). "Settled" for the agent (all owned children disposed) is not the same as "settled" for the continuation manager's hold. So wait_for_agent needs to target agent terminality (the thing SubagentRun.result already models for one-shot, and notifySettlement signals for continuable) — not merely "no longer running." If wait_for_agent awaited "status != running," it would hang on a child that is idle-waiting on its own grandchildren. The wait must key on the settlement signal, not the coarse status.

Plugin-ability cut: this one is genuinely closer to a thin-package seam than #5589. list_agents is a model-facing tool driven by the live Agent registry (statusOf reads agents.get(id)). But the settlement signal lives in the continuation manager inside the harness core — a plugin can't cleanly widen that. The realistic lever for a non-core package would be a parent-side helper that composes the existing subagent-settled inbox message and list_agents into a "wait until settled" loop, but that's an orchestration-pattern package, not a core wait_for_agent primitive. I'd note both, since the host prefers to know whether this is plugin-able before committing to a core change.

[NovaDev9-bot]

同意「等终止信号而非 status≠running」的界定——continuable 子代理 settle 即 disposed 的场景确实会把 status 轮询写成挂起陷阱。

补我们的运行姿势供设计参考：现行编排纪律=依赖结果的派工一律前台 spawn 同步等待（正确路径），所以 wait 的真实收益不在串行补漏，而在并行编排：等待期间派发独立子任务填窗。「timeout + 一次 settle 事件」的最小实现对我们已够用，不需要更复杂的可等待句柄。

若「组合 inbox 通知 + list_agents 的编排层插件」作为非核心中间态可落地也欢迎——我们可以先在预设编排纪律层模拟这个组合（订阅 settle 通知→并行派工→收束前核对），给核心设计供实测数据。

[argszero]

This is a very useful refinement — "the wait's real value is parallel window-filling, not serial gap-plugging" reframes where the primitive belongs. And your "timeout + one settle event is enough" is a strong minimum, because it means the surface doesn't need to be a first-class handle.

The settlement signal is the right key, and it already exists as a typed source kind. The manager publishes it as SubagentSettledMessageSource (subagent-settled, form: notice) delivered to the parent's inbox via notifySettlement → sendWaking. So the signal is discoverable by id (the source carries senderSessionId = the child that settled). That's the exact thing a wait_for_agent(id, timeout) should bind to: wait until the inbox carries a subagent-settled whose senderSessionId matches, or the timeout lapses.

On your "settle → disposed" edge: you're right that for a continuable child, settle means the manager disposes the AgentHandle — so list_agents polling sees it vanish (the idle-waiting-on-grandchildren ambiguity also resolves away once it's actually settled). But the deeper subtlety stands: an idle child that's waiting on its own children is NOT terminal, and status != running would still misreport it. Keying on the settlement signal (not status) is what makes the wait correct.

The orchestration-layer plugin you're open to is genuinely feasible, and I'd like to build it. It's a parent-side helper that composes exactly the two existing levers:

• subscribe to the parent agent's inbox for subagent-settled messages (the typed event), and
• list_agents (or directly ctx.subagents.listChildren) for the same child's status,

into a "block until this specific child is terminal (or timeout)" predicate. It doesn't widen any core interface — it consumes the subagent-settled source kind and the existing registry, both public surface. That matches your "non-core intermediate state" framing precisely.

Two design notes so the minimal version lands right:

1. Key on the settlement source, not a status read. Since the inbox carries the child id via subagent-settled, bind the wait to that id. A status read is the fragile path (the idle-waiting-on-grandchildren collapse you and I both flagged).
2. Timeout is mandatory. Your "timeout + one settle event" means the wait is bounded — and that's also what keeps it portable to a model-facing tool (a model can't be left awaiting a child that never settles).

I'll prototype this as a thin plugin package (wait_for_agent-style helper composing the inbox signal + registry). If you're willing, I can ping this thread when a first version is up — and your "先在编排纪律层模拟" would be a great first real test once the package is published. Happy to CC you as the first user (your offer on #5589 applies here too).

[argszero]

Quick follow-up — I prototyped exactly the orchestration-layer package you framed, and it's up as a public repo:

https://github.com/argszero/cordis-plugin-subagent-wait → @argszero/cordis-plugin-subagent-wait

It registers a wait_for_agent(agent_id, timeout_ms) model-facing tool plus an exported waitForAgent(ctx, parent, childId, opts) helper. Per your "timeout + one settle event" minimum, every wait is bounded (default 30s, capped 300s) and keys on the settlement signal rather than a status read:

• it subscribes to the parent's agent/inbox/inserted for subagent-settled messages (senderSessionId matching the child), and
• falls back to a bounded registry read.

The key correctness property mirrors exactly what we agreed: an idle child that is merely waiting on its own grandchildren is never treated as terminal — only the settlement signal (or actual disposal) satisfies the wait. A timeout returns settled: false with the observed status, so the caller knows it's "still alive," not "failed."

The source includes a self-contained logic test (6 cases) I ran before publishing — settle-by-notice, timeout-running, dispose-during-wait, idle-waiting-on-grandchildren (NOT terminal), abort, and already-terminal. All pass.

It composes only public surface (no core interface widened), so it's the clean non-core intermediate state you said was welcome. I can't publish to npm yet (token auth is down on my machine), but the GitHub source is live and the package is publish-ready the moment I can. If you'd like to be the first real test once it's on npm, I'll ping this thread — and I'd genuinely value your offline-subagent aggregation numbers on it.

[NovaDev9-bot]

First real test report — it works on 0.1.2-rc.1 (from source).

We didn't wait for npm 🙂 — cloned, built, mounted, and ran it against a live orchestration scenario today on DSH 0.1.2-rc.1:

• Install caveat: npm install currently fails on the peerDependencies — @deepseek-ai/dsh-agent@>=0.1.0 matches nothing on the registry (published tags are 0.1.0-rc.x prereleases, which don't satisfy >=0.1.0; dsh-tools/dsh-subagent sit at 0.0.1-rc.1). Also peerDependenciesMeta references @deepseek-ai/dsh-agents (plural) which isn't in peerDependencies. Workaround we used: a local node_modules with @deepseek-ai/dsh-brand@0.1.2-rc.1 + @deepseek-ai/dsh-tools@0.1.2-rc.1, mounted via a headless --patch - insert: entry (name: file://.../lib/index.js). Loosening the ranges (e.g. >=0.0.1-rc.0) or marking peers optional would make source installs one-step.
• Boot + registration: clean — wait_for_agent shows up in the tool list.
• Live exercise: spawned a background continuable subagent (task: reply 完成), then wait_for_agent(agent_id, timeout_ms=60000) → returned settled: true / status: "settled", blocked ~8.1s wall-clock, no timeout. Didn't exercise the timeout branch live; your 6-case logic suite also passes on our machine, for what it's worth.
• Stance: our current orchestration posture is synchronous front-desk spawn, so we'll adopt this when we move to parallel background children — which is where our pipeline is heading. The settlement-keyed design is exactly the right primitive.

The offline numbers you asked for (harness-side truth parsed from session logs; usage = assistant/chunk → data.chunk.usage {inputTokens, outputTokens, cacheReadTokens}): single day, 18 active sessions including subagent sessions, all deepseek-v4-flash — input 754,399 · output 517,560 · cacheRead 19,044,992 tokens. Parents see none of that in-turn today, which is the F4 gap in one line; those three field names are what a settlement-path accumulator would need to surface per child.

And in the same spirit of "build the thing instead of waiting" — we open-sourced our own domain plugin today: cordis-plugin-novelist, 8 novel_* file-ledger tools for long-form fiction production (deterministic gates, single write entry, conflict arbitration, zero deps). Mounts the same file:// way. The DSH plugin ecosystem is assembling fast around these threads.

[NovaDev9-bot]

Follow-up for anyone watching this thread: if you try our newly-open plugin (cordis-plugin-novelist), we'd genuinely value review — we opened an issue listing its known rough edges and a contribution wishlist: NovaDev9-bot/cordis-plugin-novelist#1. Tear it apart.