refactor(core): every registry register-method returns the exact effect disposer

The exact-disposer fix (5fbac8be B1) repaired agents.register but left the
same wrapper (return () => void dispose()) at seven sibling sites:
tools.register, tools.restrict, systemPrompt.section/tools/variable,
agents.setFactory, and subagents.registerProvider. A wrapper makes correct
composite usage unrepresentable — the exact disposer cannot be recovered, so
a generator effect yielding it leaves the inner effect disposing as a
CONCURRENT SIBLING on owner unload, silently reproducing B1's ordering
corruption. The exact disposer serves both usages (composite-nestable AND
fire-and-forget callable); all seven now return it, typed
() => Promise<void> | void, with the convention pinned by a discriminating
test: an async-link composite probe that passes with the exact disposer and
observes the sibling unregistration firing mid-drain with a wrapper.

Re-auditing also surfaced that B1 itself SHIPPED a full-lint failure: it
changed register()'s return type without updating cross-file consumers
(agent.spec.ts dispose() statements, tool-bash's disposer list), which the
staged-scoped pre-commit lint never saw — pnpm run lint was red at HEAD.
Those three sites and this change's own fallout are fixed together: tests
now await disposers (stronger — they observe the full unwind), sync
paths void them, and the two annotation sites carry the honest union type.
agents.register's README line had drifted the same way (B1 updated the
JSDoc, not the README) — all seven README signatures now match; services
catalog regenerated.

packages/core/tools/README.md

@@ -6,8 +6,8 @@ Tool registry and execution pipeline. Tool plugins register their schemas and ex
 
 ### Public API
 
-- `ctx.tools.register(definition: ToolDefinition): () => void` Register a tool. The layer is the CALLING context's scope (`dsh-scope`): a plain plugin context registers globally; an agent's `agent.ctx` registers for that agent alone, SHADOWING a same-named global tool there (per-agent tool variants). Duplicate names within one layer throw. Disposed with the calling fiber (= the agent, for scoped registrations).
-- `ctx.tools.restrict(filter: ToolRestriction): () => void` Scoped-only (throws on a plain context): mask the GLOBAL tool surface for the calling agent — `allow` keeps only the listed tools, `deny` removes them; multiple restrictions intersect; scoped registrations bypass restriction as explicit grants. Snapshot-at-registration, loud unknown-name validation, `restrict({})` rejects (the materialized-empty-config trap).
+- `ctx.tools.register(definition: ToolDefinition): () => Promise<void> | void` Register a tool. The layer is the CALLING context's scope (`dsh-scope`): a plain plugin context registers globally; an agent's `agent.ctx` registers for that agent alone, SHADOWING a same-named global tool there (per-agent tool variants). Duplicate names within one layer throw. Disposed with the calling fiber (= the agent, for scoped registrations).
+- `ctx.tools.restrict(filter: ToolRestriction): () => Promise<void> | void` Scoped-only (throws on a plain context): mask the GLOBAL tool surface for the calling agent — `allow` keeps only the listed tools, `deny` removes them; multiple restrictions intersect; scoped registrations bypass restriction as explicit grants. Snapshot-at-registration, loud unknown-name validation, `restrict({})` rejects (the materialized-empty-config trap).
 - `ctx.tools.get(name: string, scope?: ScopeKey): ToolDefinition | undefined` Resolution as one scope sees it (shadowing applied; a restricted-away global reads as absent) — presenters pass the calling agent so the card matches what executed.
 - `ctx.tools.visible(scope?: ScopeKey): ToolDefinition[]` THE visibility function — restricted global layer ∪ the scope's own layer — feeding prompt assembly, `get`, and `execute`, so what the model sees and what dispatches can never disagree.
 - `ctx.tools.knownNames(scope?: ScopeKey): string[]` The PRE-restriction name universe configuration (`toolOrder`, `restrict`) validates against: a typo fails loud while a restricted-away tool stays a normal absence.

packages/core/tools/src/index.ts

@@ -344,9 +344,11 @@ export class ToolRegistry extends Service {
    * Emits `tools/change` on register/unregister.
    * @param definition - the tool's schema plus its execute (and optional
    *   presentation) functions.
-   * @returns the disposer that unregisters the tool.
+   * @returns the disposer that unregisters the tool. The exact
+   *   Cordis effect disposer (single-shot): composite (generator) effects may
+   *   yield it directly — exact identity nests the teardown in order.
    */
-  register(definition: ToolDefinition): () => void {
+  register(definition: ToolDefinition): () => Promise<void> | void {
     const scope = scopeOf(this.ctx)
     const dispose = this.ctx.effect(function* (this: ToolRegistry) {
       const layer = scope === undefined ? this.global : this.layerFor(scope)
@@ -370,9 +372,13 @@ export class ToolRegistry extends Service {
       }
       this.ctx.emit('tools/change')
     }.bind(this), 'tools.register()')
-    // ctx.effect's disposer returns Promise<void>; our disposer API is
-    // synchronous fire-and-forget — discard the (always-resolved) promise.
-    return () => void dispose()
+    // The EXACT cordis effect disposer, not a wrapper: a composite (generator)
+    // effect that owns a teardown ORDER must be able to yield THIS function —
+    // cordis nests a disposer out of the fiber's concurrent sibling list by
+    // exact function identity, so a wrapper would silently break the nesting
+    // (the agents.register() lesson). Fire-and-forget callers may still
+    // discard the (always-resolved) promise.
+    return dispose
   }
 
   /**
@@ -389,9 +395,11 @@ export class ToolRegistry extends Service {
    * Scoped registrations bypass restrictions (explicit grants win). Disposed
    * with the calling fiber (revocable independently); emits `tools/change`.
    * @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).
-   * @returns the disposer that lifts this restriction.
+   * @returns the disposer that lifts this restriction. The exact
+   *   Cordis effect disposer (single-shot): composite (generator) effects may
+   *   yield it directly — exact identity nests the teardown in order.
    */
-  restrict(filter: ToolRestriction): () => void {
+  restrict(filter: ToolRestriction): () => Promise<void> | void {
     const scope = scopeOf(this.ctx)
     if (scope === undefined) {
       throw new Error('tools.restrict() requires a scoped context (agent.ctx): a context-global restriction would mask every agent — deny the tool for the intended agent instead')
@@ -422,9 +430,13 @@ export class ToolRegistry extends Service {
       }
       this.ctx.emit('tools/change')
     }.bind(this), 'tools.restrict()')
-    // ctx.effect's disposer returns Promise<void>; our disposer API is
-    // synchronous fire-and-forget — discard the (always-resolved) promise.
-    return () => void dispose()
+    // The EXACT cordis effect disposer, not a wrapper: a composite (generator)
+    // effect that owns a teardown ORDER must be able to yield THIS function —
+    // cordis nests a disposer out of the fiber's concurrent sibling list by
+    // exact function identity, so a wrapper would silently break the nesting
+    // (the agents.register() lesson). Fire-and-forget callers may still
+    // discard the (always-resolved) promise.
+    return dispose
   }
 
   /** The (created-on-demand) scoped layer for `scope`. */

packages/core/tools/tests/scoped.spec.ts

@@ -125,7 +125,7 @@ describe('restrict()', () => {
     const liftAllow = scope.ctx.tools.restrict({ allow: ['a', 'b'] })
     scope.ctx.tools.restrict({ deny: ['b'] })
     expect(ctx.tools.schemas(key).map(t => t.name)).toEqual(['a'])
-    liftAllow()
+    await liftAllow()
     // The deny remains after the allow-list is lifted.
     expect(ctx.tools.schemas(key).map(t => t.name).sort()).toEqual(['a', 'c'])
   })

packages/core/tools/tests/tools.spec.ts

@@ -358,7 +358,7 @@ describe('ToolRegistry', () => {
     const dispose = ctx.tools.register({ ...echoTool, name: 'disposable' })
     expect(ctx.tools.schemas().map(t => t.name)).toEqual(['echo', 'disposable'])
 
-    dispose()
+    await dispose()
     expect(ctx.tools.schemas().map(t => t.name)).toEqual(['echo'])
   })
 
@@ -379,9 +379,38 @@ describe('ToolRegistry', () => {
     // exposed exactly once (the duplicate-name check is not wedged).
     const dispose = ctx.tools.register(echoTool)
     expect(ctx.tools.schemas().map(t => t.name)).toEqual(['echo'])
-    dispose()
+    await dispose()
     expect(ctx.tools.get('echo')).toBeUndefined()
   })
+
+  it('register() returns the EXACT effect disposer: a composite yield nests the teardown in order', async () => {
+    // The registry-disposer convention (set by agents.register): the returned
+    // function IS the cordis effect disposer, so a composite (generator)
+    // effect that yields it has the unregistration run at that yield's LIFO
+    // position on owner unload. A wrapper would leave the inner effect
+    // disposing as a CONCURRENT SIBLING of the composite; the async probe
+    // below (disposed first, LIFO) yields the event loop exactly like the
+    // agent factory's stop-and-drain link, and a sibling unregistration fires
+    // in that window — the probe would observe the tool already gone. Pins
+    // the convention for the whole register-method family (system-prompt
+    // registrars, registerProvider, setFactory share the same return).
+    const ctx = await setup()
+    const order: string[] = []
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      inner.effect(function* () {
+        yield () => { order.push('disposed-last') }
+        yield inner.tools.register({ ...echoTool, name: 'nested' })
+        order.push('registered')
+        yield async () => {
+          await new Promise(resolve => setTimeout(resolve, 0))
+          order.push(inner.tools.get('nested') ? 'first: still registered' : 'first: already gone')
+        }
+      })
+    }, { inject: ['tools'] }))
+    await fiber.dispose()
+    expect(order).toEqual(['registered', 'first: still registered', 'disposed-last'])
+    expect(ctx.tools.get('nested')).toBeUndefined()
+  })
 })
 
 describe('defineTool / schema DSL', () => {