fix(docs): address Codex review — document the subagent_fork alias, harden dispose

Round-1 Codex review findings on the tool-schema catalog:

(A) The shipped coding-agent / acp-agent configs load dsh-tool-subagent twice —
as `subagent` (spawn backend) and `subagent_fork` (fork backend) — so the model
sees a `subagent_fork` tool the catalog never mentioned, while the intro claimed
to list "the exact name the model receives". The registered name is the plugin's
load-time `toolName` config, not a package fact, so rather than bake an
example-app config into a packages-scoped generator, add a per-package deployment
`note`: the subagent entry now records the `subagent_fork` alias and points at the
leaf configs. Intro and RFC scope reworded to state the unit is the package (at
its default config), with aliases noted — no longer overclaiming. A test asserts
the note names `subagent_fork`, covering the config-driven-name path.

(B) collectToolCatalog only disposed the context on the success path; a throw from
mount/schemas() after earlier plugins mounted would leak the fiber. Move
`ctx.fiber.dispose()` into a `finally` per the repo's dispose-to-quiescence rule.

scripts/gen-tool-catalog.ts

@@ -72,6 +72,14 @@ interface ToolPackage {
   /** Plug the injected seams + the tool plugin onto a context that already
    * carries `systemPrompt` + `tools`. */
   mount: (ctx: Context) => Promise<void>
+  /**
+   * A deployment note rendered after the package's tools, for a fact that
+   * booting the package alone cannot show. The registered tool NAME can be a
+   * load-time config (`tool-subagent`'s `toolName`), so one package may surface
+   * under several names across deployments — the boot yields the package
+   * DEFAULT, and this note records the shipped alternatives the model sees.
+   */
+  note?: string
 }
 
 /**
@@ -99,6 +107,8 @@ const TOOL_PACKAGES: ToolPackage[] = [
       await ctx.plugin(SubagentMock, { name: 'mock' })
       await ctx.plugin(ToolSubagent, { provider: 'mock' })
     },
+    note:
+      'The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `examples/coding-agent/cordis.yml` and `examples/acp-agent/cordis.yml`.',
   },
   {
     pkg: '@deepseek-ai/dsh-tool-todo',
@@ -115,6 +125,8 @@ interface CatalogPackage {
   pkg: string
   source: string
   schemas: ToolSchema[]
+  /** A deployment note (see {@link ToolPackage.note}), rendered after the tools. */
+  note?: string
 }
 
 /** The whole catalog: one entry per booted tool package, in manifest order. */
@@ -153,13 +165,18 @@ export async function collectToolCatalog(packages: ToolPackage[] = TOOL_PACKAGES
   const catalog: ToolCatalog = []
   for (const entry of packages) {
     const ctx = new Context()
-    await ctx.plugin(SystemPrompt)
-    await ctx.plugin(ToolRegistry)
-    await entry.mount(ctx)
-    // Copy the schemas out before the context is torn down.
-    const schemas = ctx.tools.schemas().sort((a, b) => a.name.localeCompare(b.name))
-    await ctx.fiber.dispose()
-    catalog.push({ pkg: entry.pkg, source: entry.source, schemas })
+    // Dispose in `finally` so a throw from `mount`/`schemas()` after earlier
+    // plugins mounted still tears the context down (no leaked executor/provider
+    // fiber) — the repo's "dispose must reach quiescence" rule.
+    try {
+      await ctx.plugin(SystemPrompt)
+      await ctx.plugin(ToolRegistry)
+      await entry.mount(ctx)
+      const schemas = ctx.tools.schemas().sort((a, b) => a.name.localeCompare(b.name))
+      catalog.push({ pkg: entry.pkg, source: entry.source, schemas, ...entry.note !== undefined ? { note: entry.note } : {} })
+    } finally {
+      await ctx.fiber.dispose()
+    }
   }
   return catalog
 }
@@ -182,16 +199,17 @@ export function render(catalog: ToolCatalog): string {
     '',
     '# Tool Schema Catalog',
     '',
-    'Every model-facing tool a shipped plugin contributes to `ctx.tools`: the exact `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the [cordis events & services catalog](../cordis-catalog/events-and-services.md) (the wiring a plugin listens to and calls) and [core-data-structures/](../core-data-structures/core.md) (the types those signatures move) — this page is the *tools* the agent is offered.',
+    'Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the [cordis events & services catalog](../cordis-catalog/events-and-services.md) (the wiring a plugin listens to and calls) and [core-data-structures/](../core-data-structures/core.md) (the types those signatures move) — this page is the *tools* the agent is offered.',
     '',
     'This file is GENERATED and verified fresh by `pnpm run verify-tool-catalog` (part of `doc-sync`) — do not edit it by hand. Unlike the cordis catalog (a pure source-AST pass), this generator BOOTS each tool plugin on a real context and reads `ctx.tools.schemas()`, because a tool schema is not statically knowable (runtime-spread enums, concatenated descriptions, config-driven names, raw-JSON-Schema MCP tools). A completeness guard globs `packages/*/tool-*` and fails if any package is missing from the generator\'s boot manifest, so a new tool cannot be silently undocumented. See [the tool-schema-catalog RFC](../rfc/implemented/process/2026-07-02-tool-schema-catalog.md).',
     '',
-    'Scope: shipped product tools under `packages/*/tool-*`. The `examples/` demo tools (e.g. `echo`) are excluded, matching the cordis catalog\'s packages-only scope.',
+    'Scope: shipped product tools under `packages/*/tool-*`, each booted with its DEFAULT config. The registered tool NAME can be a load-time config (e.g. `tool-subagent`\'s `toolName`), so a deployment may surface a package under a different or additional name — a per-package note records those shipped aliases where they exist. The `examples/` demo tools (e.g. `echo`) are excluded, matching the cordis catalog\'s packages-only scope.',
     '',
   ]
   for (const entry of catalog) {
     lines.push(`## \`${entry.pkg}\``, '')
     for (const schema of entry.schemas) lines.push(...renderTool(schema, entry.source))
+    if (entry.note) lines.push(entry.note, '')
   }
   return lines.join('\n')
 }