fix(scope): close final ownership races

Drain idle injection flushes before agent teardown, snapshot approval and subagent provider inputs, and gate subagent lifecycle events on real child readiness. Align the RFCs and generated contracts with the hardened behavior.

packages/core/agent-loop/README.md

@@ -8,7 +8,7 @@ This is the only package in the harness that contains concrete loop logic. Every
 
 ### Public API
 
-Lifecycle (scoped): programmatic creation and resume snapshot caller-owned identity/configuration data, reserve both IDs, mint `agent.ctx`, and install the ordered teardown skeleton before awaiting optional `setup`. Resume installs an owner-liveness sentinel before persistence load, then hands ownership directly to the full lifecycle. After setup resolves, the factory checks its lifecycle flag, owner-fiber state, and owning agent status around one microtask checkpoint so a same-turn Cordis unload wins before publication. Successful setup inserts both session and agent before announcing either, enables driving immediately before `agent/session-start`, then starts the loop. Setup calls to `send`/`steer`/`inject`/`cancel` reject structurally; load/setup rejection or owner unload publishes nothing. Teardown runs stop/drain → unregister → detach session → unwind scope. All `agent/*` dispatches go through `agentEvents(ctx, agent)`; per-step assembly through `assembleContextFor(agent)`; the turn-end durability checkpoint through `ctx.sessions.flush(session)`.
+Lifecycle (scoped): programmatic creation and resume snapshot caller-owned identity/configuration data, reserve both IDs, mint `agent.ctx`, and install the ordered teardown skeleton before awaiting optional `setup`. Resume installs an owner-liveness sentinel before persistence load, then hands ownership directly to the full lifecycle. After setup resolves, the factory checks its lifecycle flag, owner-fiber state, and owning agent status around one microtask checkpoint so a same-turn Cordis unload wins before publication. Successful setup inserts both session and agent before announcing either, enables driving immediately before `agent/session-start`, then starts the loop. Setup calls to `send`/`steer`/`inject`/`cancel` reject structurally; load/setup rejection or owner unload publishes nothing. Teardown runs stop/drain (including outstanding idle-injection flushes) → unregister → detach session → unwind scope. All `agent/*` dispatches go through `agentEvents(ctx, agent)`; per-step assembly through `assembleContextFor(agent)`; the turn-end durability checkpoint through `ctx.sessions.flush(session)`.
 
 - `ctx.agentLoop.create(id: string, options?: AgentOptions, meta?: { cwd?: string }): ReactLoopAgent` — config-driven create: an agent on a fresh per-run session id `${id}-session-<uuid>` with optional session metadata. Used for `cordis.yml`-configured agents. The per-run uuid avoids colliding with the on-disk log a prior run materialized once a durable persistence backend is loaded; each run is a new session (a deliberate demo simplification — a real resume-or-create policy is a TODO). Disposed with the calling fiber.
 

packages/core/agent-loop/src/agent.ts

@@ -31,8 +31,12 @@ export interface PreparedReactLoopAgent {
   agent: ReactLoopAgent
   /** Open its driving verbs at the rollback-covered publication boundary. */
   enableDrive(): void
-  /** Start its driver after publication and session-start notification. */
-  startDriver(): () => void
+  /**
+   * Start its driver after publication and session-start notification.
+   * The returned disposer reaches quiescence for both the loop and every
+   * fire-and-forget idle-injection flush the agent started.
+   */
+  startDriver(): () => Promise<void>
 }
 
 /**
@@ -126,6 +130,12 @@ export class ReactLoopAgent implements Agent {
    * the `disposed` transition fires and leave the promise hanging.
    */
   private idleWaiters: (() => void)[] = []
+  /**
+   * Durability checkpoints started by idle {@link inject} calls. `inject()` is
+   * synchronous, so it cannot await them itself; the driver disposer drains
+   * this set before the lifecycle unregisters the agent or detaches its session.
+   */
+  private pendingIdleFlushes = new Set<Promise<void>>()
 
   constructor(
     private loopCtx: Context,
@@ -249,14 +259,16 @@ export class ReactLoopAgent implements Agent {
       // will flush this turn. Fire-and-forget with error containment: inject()
       // is synchronous, and a persistence backend failing must not throw into
       // the caller (e.g. a tool-bash task-done callback). Disposal still drains
-      // independently, so a slow flush is safe. A flush failure is reported via
-      // agent/error (step 0 — the idle-injection convention, there is no real
-      // step) AND the logger, mirroring the loop's post-turn/end flush path so
-      // plugins monitoring agent/error see idle-injection persistence failures
-      // too. A throwing agent/error listener is contained.
+      // independently, so a slow flush is safe. The task is tracked until it
+      // settles: driver disposal awaits every pending idle-injection checkpoint
+      // before unregistering the agent or detaching the session. A flush failure
+      // is reported via agent/error (step 0 — the idle-injection convention,
+      // there is no real step) AND the logger, mirroring the loop's post-turn/end
+      // flush path so plugins monitoring agent/error see idle-injection
+      // persistence failures too. A throwing agent/error listener is contained.
       if (turnRecorded) {
         // Through the store's flush (the carrier owner), never a raw parallel.
-        void this.loopCtx.sessions.flush(this.session).catch((error: unknown) => {
+        const flush = this.loopCtx.sessions.flush(this.session).catch((error: unknown) => {
           const err = error instanceof Error ? error : new Error(String(error))
           this.loopCtx.logger.warn(`agent "${this.id}": flush after idle injection failed: ${err.message}`)
           try {
@@ -266,6 +278,13 @@ export class ReactLoopAgent implements Agent {
             // listener must not escape this fire-and-forget catch.
           }
         })
+        this.pendingIdleFlushes.add(flush)
+        // Attach the same retirement callback to both settlement arms so even a
+        // logger failure in the catch above cannot become an unhandled rejection.
+        // Teardown uses allSettled for the same reason: a reporting failure must
+        // not strand ownership.
+        const retire = (): void => { this.pendingIdleFlushes.delete(flush) }
+        void flush.then(retire, retire)
       }
     }
   }
@@ -310,8 +329,8 @@ export class ReactLoopAgent implements Agent {
    * fully ended) or chaining {@link done} on `disposed` (wait for the loop to
    * actually exit). Implements the {@link Agent.whenIdle} contract: a non-owner
    * quiescence-observation hook, distinct from teardown (a lifecycle owner stops
-   * and unregisters via `AgentHandle.dispose()`, which awaits {@link done}
-   * directly, not through this).
+   * and unregisters via `AgentHandle.dispose()`, whose driver boundary awaits
+   * both {@link done} and outstanding idle-injection flushes, not through this).
    */
   whenIdle(): Promise<void> {
     if (this._status === 'disposed') return this.done
@@ -334,12 +353,14 @@ export class ReactLoopAgent implements Agent {
    * Start the driver loop. Returns a disposer: calling it sets status to
    * `disposed`, emits `agent/status('disposed')`, resolves the disposed
    * promise (unblocking the idle wait), releases any `whenIdle` waiters, and
-   * aborts the current request if any. The returned `agent.done` promise
-   * resolves once the loop exits.
-   * @returns the disposer — idempotent and infallible (it runs inside the
-   *   fiber's LIFO disposal chain, where a throw would skip later disposers).
+   * aborts the current request if any. Its returned promise resolves only after
+   * the loop exits and every idle-injection flush started by this agent settles.
+   * @returns the disposer — idempotent, synchronously marks the agent disposed,
+   *   and asynchronously reaches loop + flush quiescence without rejecting (it
+   *   runs inside the fiber's LIFO disposal chain, where a rejection would skip
+   *   later disposers).
    */
-  [startDriver](): () => void {
+  [startDriver](): () => Promise<void> {
     this.done = runLoop(this.loopCtx, this, {
       inbox: this.#inbox,
       setStatus: (status) => { this.setStatus(status) },
@@ -360,22 +381,35 @@ export class ReactLoopAgent implements Agent {
     // The disposer must be infallible: it runs inside the fiber's LIFO
     // disposal chain, where a throw would skip later disposers (e.g. the
     // registry unregistration) and leave `done` pending forever.
-    return () => {
-      if (this._status === 'disposed') return
-      this._status = 'disposed'
-      this.resolveDisposed()
-      // Release whenIdle waiters BEFORE the (guarded) event emit — they are
-      // internal state that must settle even if a listener throws below. Each
-      // waiter chains `done`, so it resolves only once the loop actually exits.
-      this.settleIdleWaiters()
-      this.currentAbort?.abort('disposed')
-      // setStatus refuses transitions out of 'disposed', so emit directly —
-      // 'disposed' is part of the agent/status contract. Guarded: a throwing
-      // listener must not break the disposal chain.
-      try {
-        this.loopCtx.emit(this.carrier, 'agent/status', this, 'disposed')
-      } catch {
-        // listener error during disposal — nothing safe left to do with it
+    return async () => {
+      if (this._status !== 'disposed') {
+        this._status = 'disposed'
+        this.resolveDisposed()
+        // Release whenIdle waiters BEFORE the (guarded) event emit — they are
+        // internal state that must settle even if a listener throws below. Each
+        // waiter chains `done`, so it resolves only once the loop actually exits.
+        this.settleIdleWaiters()
+        this.currentAbort?.abort('disposed')
+        // setStatus refuses transitions out of 'disposed', so emit directly —
+        // 'disposed' is part of the agent/status contract. Guarded: a throwing
+        // listener must not break the disposal chain.
+        try {
+          this.loopCtx.emit(this.carrier, 'agent/status', this, 'disposed')
+        } catch {
+          // listener error during disposal — nothing safe left to do with it
+        }
+      }
+      // An unexpected driver rejection must not skip registry/session/scope
+      // cleanup. The normal loop contains turn failures itself; allSettled is the
+      // final lifecycle backstop for anything outside those boundaries.
+      await Promise.allSettled([this.done])
+      // No new inject() can start after the synchronous disposed transition.
+      // Loop because settled tasks retire themselves in promise reactions that
+      // may run beside this continuation; either the set is empty or this waits
+      // the exact remaining quiescence boundary. allSettled keeps a failure in
+      // error reporting from skipping the registry/session/scope disposers.
+      while (this.pendingIdleFlushes.size > 0) {
+        await Promise.allSettled([...this.pendingIdleFlushes])
       }
     }
   }

packages/core/agent-loop/src/index.ts

@@ -375,7 +375,7 @@ export class AgentLoop extends Service implements AgentFactory {
     let active = true
     let detachSession: (() => void) | undefined
     let detachAgent: (() => void) | undefined
-    let stop: (() => void) | undefined
+    let stop: (() => Promise<void>) | undefined
     const { promise: deactivated, resolve: markDeactivated } = Promise.withResolvers<void>()
     const { promise: torndown, resolve: markTorndown } = Promise.withResolvers<void>()
 
@@ -401,8 +401,7 @@ export class AgentLoop extends Service implements AgentFactory {
         active = false
         markDeactivated()
         if (stop === undefined) return
-        stop()
-        return agent.done
+        return stop()
       }
     }, 'agentLoop.lifecycle()')
 
@@ -461,8 +460,9 @@ export class AgentLoop extends Service implements AgentFactory {
   /**
    * Build an {@link AgentHandle} for a PREPARED session + a fresh agent. The
    * handle's `dispose()` runs the composite effect's disposer (see
-   * {@link start}) — which stops the loop, awaits its exit (final flush
-   * captured), unregisters the agent, and detaches the session, in that order.
+   * {@link start}) — which stops the loop, awaits its exit and outstanding
+   * idle-injection flushes, unregisters the agent, and detaches the session, in
+   * that order.
    * The same composite effect is what a fiber unload disposes, so both teardown
    * triggers honor the ordering identically.
    *
@@ -470,8 +470,8 @@ export class AgentLoop extends Service implements AgentFactory {
    * single-shot (a second call returns immediately because the effect's epoch is
    * already cleared, NOT awaiting the in-flight teardown), so concurrent/repeated
    * `dispose()` calls would otherwise resolve before the first call's
-   * `await agent.done` + final flush completed. Memoizing the promise makes every
-   * caller observe the SAME quiescence boundary, honoring the
+   * loop + flush quiescence boundary completed. Memoizing the promise makes
+   * every caller observe that SAME boundary, honoring the
    * `AgentHandle.dispose(): Promise<void>` contract (mirrors the ACP `quiesce()`
    * helper).
    */

packages/core/agent-loop/src/loop.ts

@@ -489,7 +489,7 @@ async function runTurn(
       // against the system prompt (it counts toward the budget). runStep reuses
       // this same assembly for the request, so the prompt is assembled once per
       // step. renderPrompt IS the full prompt — the persona is the order-0
-      // section (registered by the AgentLoop plugin) and `{{variable}}`
+      // section (owned by dsh-system-prompt) and `{{variable}}`
       // interpolation happens in the render, so there is no separate join.
       const assembly = await ctx.systemPrompt.assemble(assembleContextFor(agent))
       const fullSystemPrompt = renderPrompt(assembly)

packages/core/agent-loop/tests/agent.spec.ts

@@ -242,11 +242,12 @@ describe('ReactLoopAgent', () => {
     const dispose = prepared.startDriver()
 
     // First dispose
-    dispose()
+    const firstDisposal = dispose()
     expect(agent.status).toBe('disposed')
+    await firstDisposal
 
     // Second dispose — idempotent, no throw
-    expect(() => { dispose() }).not.toThrow()
+    await expect(dispose()).resolves.toBeUndefined()
     expect(agent.status).toBe('disposed')
   })
 
@@ -347,10 +348,10 @@ describe('ReactLoopAgent', () => {
     expect(agent.status).toBe('running')
 
     const idle = agent.whenIdle() // queues an internal waiter (running)
-    dispose() // settles the waiter synchronously; whenIdle chains done
+    const disposal = dispose() // settles the waiter synchronously; whenIdle chains done
     await idle
     expect(agent.status).toBe('disposed')
-    await agent.done
+    await disposal
   })
 
   it('whenIdle() subscribed while running survives a FIBER dispose (no hung promise)', async () => {

packages/core/agent-loop/tests/scope-lifecycle.spec.ts

@@ -440,4 +440,35 @@ describe('agent scope lifecycle', () => {
     expect(ctx.sessions.get(SessionId('h1-s'))).toBeUndefined()
     await unload
   })
+
+  it('handle.dispose() awaits an idle-injection flush before unregistering or detaching', async () => {
+    const ctx = await harness()
+    const handle = await ctx.agents.create({
+      agentId: AgentId('idle-flush'),
+      sessionId: SessionId('idle-flush-s'),
+      agentOptions: { model: 'mock' },
+    })
+    const gate = Promise.withResolvers<undefined>()
+    let flushStarted = false
+    ctx.on('session/flush', (session) => {
+      if (session !== handle.agent.session) return
+      flushStarted = true
+      return gate.promise
+    })
+
+    handle.agent.inject(text('durable idle context'), { source: { kind: 'plugin', plugin: 'test' } })
+    expect(flushStarted).toBe(true)
+
+    let disposed = false
+    const disposal = handle.dispose().then(() => { disposed = true })
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(disposed).toBe(false)
+    expect(ctx.agents.get(AgentId('idle-flush'))).toBe(handle.agent)
+    expect(ctx.sessions.get(SessionId('idle-flush-s'))).toBe(handle.agent.session)
+
+    gate.resolve(undefined)
+    await disposal
+    expect(ctx.agents.get(AgentId('idle-flush'))).toBeUndefined()
+    expect(ctx.sessions.get(SessionId('idle-flush-s'))).toBeUndefined()
+  })
 })