[Lifecycle] Duplicate waiting subagent tool names can roll back late providers

[Lzb-gzist]

Summary

Two live @deepseek-ai/dsh-tool-subagent instances can currently declare the same model-facing toolName while both selected providers are absent. Both plugin fibers activate successfully and retain provider-lifecycle listeners. The conflict is discovered only later, when the second provider arrives and its listener attempts the duplicate tool registration.

That turns a local configuration error into a load-order-dependent provider-registration failure: a provider-added listener is allowed to unwind the provider registration transaction. I reproduced the missing early rejection against official master and prepared a tested fix in a public fork. Since this repository does not expose external pull-request creation, I am sharing the complete patch here according to the repository's contribution workflow.

Reproduction

1. Load dsh-system-prompt, dsh-tools, and dsh-subagent.
2. Load dsh-tool-subagent with { provider: 'later-a', toolName: 'shared_subagent' } while later-a is absent.
3. Load a second instance with { provider: 'later-b', toolName: 'shared_subagent' } while later-b is absent.
4. Require step 3 to fail at its own plugin boundary, before either provider lifecycle is involved.

On official master, both instances activated. The focused regression failed with:

AssertionError: expected 'undefined' to contain
'toolName "shared_subagent" is already reserved by another tool-subagent instance'

undefined is the captured load error: no error was raised. The focused command was:

pnpm exec vitest run packages/subagent/tool-subagent/tests/tool-subagent.spec.ts \
  -t 'reserves a toolName while providers are absent'

Root cause

dsh-tool-subagent registers subagent/provider-added and subagent/provider-removed listeners before checking whether its selected provider exists, which is correct for sibling load-order independence. However, it does not reserve the eventual tool name at apply time. The only duplicate-name check is inside ctx.tools.register() in mount(provider), so two waiting instances remain latent until provider arrival. At that point the error escapes the addition listener and can roll back the provider that triggered it.

Continuable instances happen to reserve a related prompt-section name, but one-shot instances have no equivalent early ownership record. Name validity should not depend on background mode or provider timing.

Proposed fix

The patch adds an app-scoped intent registry for live tool-subagent names:

• a WeakMap<Context, Set<string>> is keyed by ctx.root, so separate applications in one process do not share names;
• each plugin fiber reserves its toolName before observing provider lifecycle events;
• a duplicate fails at the second plugin's apply boundary with an actionable error;
• the fiber's effect disposer releases exactly its reservation, preserving HMR and replacement;
• the ordinary tool registry remains the final backstop for collisions with other tool packages.

This keeps the existing reactive provider design: the model-facing tool still appears only while its selected provider exists, and its wording is still re-derived after provider reload.

Verification

The new regression proves that:

• two absent-provider instances cannot reserve the same toolName;
• the earlier instance still mounts normally when its provider arrives;
• a later provider remains registered after the rejected duplicate instance;
• disposing the owner removes the tool and releases the name;
• a replacement instance can immediately reuse the released name and bind the already-present provider.

Full validation completed successfully:

tool-subagent tests: 2 files, 69 tests passed
lint: passed
typecheck: passed (including pre-push hook)
doc-sync: 28 passed, 0 failed
duplication: 0 clones
git diff --check: passed

Patch

• Compare: master...Lzb-gzist:agent/subagent-toolname-intent-reservation
• Commit: Lzb-gzist@a0128dd
• Branch: Lzb-gzist:agent/subagent-toolname-intent-reservation

[boyin111-1]

源码级根因分析（基于当前仓库源码，未提交修复承诺）

机制：两个 tool-subagent 实例共享同一 provider 名、工具名相同（双方省略 toolName 时都取默认 'subagent'，见 packages/subagent/tool-subagent/src/index.ts:83,277,297），且该 provider 在组合装配时尚未注册（tool-subagent/src/index.ts:448-454 的 "waiting" 分支）。源码里本就有注释记录这一风险（tool-subagent/src/index.ts:435-439）。

触发链是运行时生命周期问题：

1. provider 稍后注册，registerProvider 对 subagent/provider-added 发射一次同步事件（packages/subagent/subagent/src/index.ts:383）。
2. 两个 tool 监听器在同一次发射内先后执行（tool-subagent/src/index.ts:440-442）：第一个挂上工具，第二个在同一名下 tools.register 撞名抛错（packages/core/tools/src/index.ts:1037-1061；报错文案在 packages/core/tools/src/index.ts:726-728）。
3. 该 throw 从发射点冒泡回 provider 注册所用的 Cordis generator-effect，触发其 yield 回滚（packages/subagent/subagent/src/index.ts:377-380 的 providers.delete + provider-removed），后注册的 provider 被整体回滚（回滚有测试背书 packages/subagent/subagent/tests/service.spec.ts:93-98）；那条 provider-removed 又把第一个挂好的工具也卸载（tool-subagent/src/index.ts:443-447）。

这就是 "晚注册的 provider 被滚掉" 的完整路径。

为什么必须是 "waiting"：若 provider 在 apply() 时已在场，两个实例会立刻挂载（tool-subagent/src/index.ts:450），第二个的撞名 throw 只发生在它自己的 fiber 启动里，不会回滚 provider。

离线可探测性：诚实说明——这是纯运行时注册/加载时序缺陷，无离线可判定的 manifest 症状。撞名检查（packages/core/tools/src/index.ts:727）运行时才执行，scripts/verify-cordis-config.ts 也不校验同组合内 toolName 唯一性。静态门禁顶多能在"同一 host 平面 ≥2 个 tool-subagent 行、toolName 相同/省略、指向同一 provider"的配置层面给出疑点，但那是疑点而非必然，我不把它当成已证实的离线检测项。

加固方向（个人看法，非官方承诺）：给同名同 provider 的并发 waiting 实例做共享注册意图协调，或用配置期唯一性校验替代运行期撞名回滚。

（dsh-doctor 未引用——本缺陷无离线可抓的 manifest 指纹。）