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.
2026-07-12 00:31:46 +08:00
parent e6c7522a75
commit 3529b3c166
43 changed files with 825 additions and 261 deletions
--- a/packages/subagent/subagent/README.md
+++ b/packages/subagent/subagent/README.md
@@ -18,10 +18,10 @@ Unlike the bash seam (one executor per context, second load throws), **multiple

 | Member | Semantics |
 |---|---|
-| `registerProvider(provider)` | Register under `provider.name`. Throws `SubagentError('DUPLICATE_PROVIDER')` on a name clash. Effect-scoped (HMR-safe); returns the disposer. |
-| `getProvider(name)` | Look up a provider (`undefined` if absent). |
+| `registerProvider(provider)` | Register a frozen acceptance snapshot under `provider.name`; later caller mutation cannot change registry behavior or HMR cleanup, while `start` stays bound to the original provider receiver. Throws `SubagentError('DUPLICATE_PROVIDER')` on a name clash. Effect-scoped (HMR-safe); returns the disposer. |
+| `getProvider(name)` | Look up the frozen registry snapshot (`undefined` if absent). |
 | `list()` | Registered provider names (insertion order). |
-| `start(name, request)` | Resolve the provider (`NO_PROVIDER` if absent), validate every requested START-TIME capability (`UNSUPPORTED_CAPABILITY` for the first unmet one — before any child is created), then delegate to `provider.start` and emit `subagent/start` / `subagent/end` around the run. |
+| `start(name, request)` | Resolve the provider (`NO_PROVIDER` if absent), validate every requested START-TIME capability (`UNSUPPORTED_CAPABILITY` for the first unmet one — before any child is created), then delegate to `provider.start`. Emit `subagent/start` only after `run.started` fulfills and the paired `subagent/end` after that started run settles; a pre-publication readiness rejection emits neither. |

 ## Capabilities: two kinds, discovered two ways

@@ -32,9 +32,9 @@ Beside `capabilities` sits one DESCRIPTIVE fact, not validated by the service: `

 ## Run lifecycle

-`provider.start(request)` returns a `SubagentRun`: a handle with a `result` promise, `cancel()`, `dispose()`, and the optional runtime methods. `result` resolves with a `SubagentResult` (`output`, optional `structured`, `stopReason`) — it does **not** reject on a child-level failure (a model/transport failure resolves with `stopReason: 'error'`), so the consumer maps a non-`completed` reason to an `isError` tool result. The consumer MUST `dispose()` on every path (success, error, abort) to reach child quiescence and avoid leaking an idle child / session.
+`provider.start(request)` returns a `SubagentRun`: a handle with `started` (the publication/readiness promise), `result` (the terminal outcome), `cancel()`, `dispose()`, and the optional runtime methods. `started` resolves only after the provider has established a real child and rejects if the attempt fails or is cancelled first. `result` resolves with a `SubagentResult` (`output`, optional `structured`, `stopReason`) — it does **not** reject on a child-level failure (a model/transport failure resolves with `stopReason: 'error'`), so the consumer maps a non-`completed` reason to an `isError` tool result. The consumer MUST `dispose()` on every path (success, error, abort) to reach child quiescence and avoid leaking an idle child / session.

-The service also announces provider lifecycle: `subagent/provider-added` (the live provider) fires after a registration and `subagent/provider-removed` (the name) after an unregistration, so a consumer deriving state from a named provider (the model-facing tool wording) mirrors registry membership instead of assuming load order — the cordis Loader starts sibling plugins concurrently, so "listed earlier" does not mean "registered earlier". The service emits `subagent/start` (payload `SubagentRunInfo`) and `subagent/end` (payload `SubagentRunEndInfo`) around the run — both **observe-only** (plain `emit`s; `subagent/end` fires from a detached `.then` and awaits no listener). `subagent/end` carries `lastAssistantMessage` (a deep clone of the child's final `output`) on the settle path, absent when the run rejected at the infrastructure level. The clone keeps the surface observe-only: the end emit fires from a detached `.then` before the caller's `await run.result` resumes, so a shared reference would let a mutating listener corrupt the caller's result. A `subagent/start` listener can still reach the live child via `ctx.agents.get(info.id)`; a `subagent/end` listener can only observe (the run has settled). Any run-affecting decision (continuation, injection that changes the run) is out of scope for this observe-only surface.
+The service also announces provider lifecycle: `subagent/provider-added` (the frozen registry snapshot) fires after a registration and `subagent/provider-removed` (the accepted name) after an unregistration, so a consumer deriving state from a named provider (the model-facing tool wording) mirrors registry membership instead of assuming load order — the cordis Loader starts sibling plugins concurrently, so "listed earlier" does not mean "registered earlier". Run lifecycle is gated by provider readiness: `subagent/start` (payload `SubagentRunInfo`) fires only after `run.started` fulfills, and `subagent/end` (payload `SubagentRunEndInfo`) fires only for that announced run; readiness rejection emits neither. For spawn/fork, the start listener can resolve the published child via `ctx.agents.get(info.id)`; a remote provider need not have a local registry entry. Both events are **observe-only** plain emits. The service observes `result` immediately even while readiness is pending, clones its output before the caller can mutate it, and buffers that end payload until start has fired; a rejecting result cannot become an unhandled detached promise, start always precedes end, and a listener cannot corrupt the caller's result. `subagent/end` carries the cloned output as `lastAssistantMessage` on the settle path and omits it on infrastructure rejection. Any run-affecting decision is out of scope for this observe-only surface.

 ## Scope (first cut)

--- a/packages/subagent/subagent/src/index.ts
+++ b/packages/subagent/subagent/src/index.ts
@@ -69,7 +69,7 @@ declare module 'cordis' {
     * tool wording in `dsh-tool-subagent`) react HERE instead of assuming load
     * order — the cordis Loader starts sibling plugins concurrently, so
     * "listed earlier in cordis.yml" does not mean "registered earlier".
-     * @param provider - the provider that just registered, live in the registry.
+     * @param provider - the registry's frozen acceptance snapshot of the provider.
     * @mode emit
     */
    'subagent/provider-added'(provider: SubagentProvider): void
@@ -85,8 +85,11 @@ declare module 'cordis' {
     */
    'subagent/provider-removed'(name: string): void
    /**
-     * A subagent run started — emitted after the provider is resolved and its
-     * capabilities validated, as the child run begins. Paired with
+     * A subagent run started — emitted only after {@link SubagentRun.started}
+     * fulfills, when the provider has established a live child. For an
+     * in-process provider, `ctx.agents.get(info.id)` is therefore guaranteed to
+     * resolve during this notification. A readiness rejection emits neither
+     * lifecycle event; every emitted start is paired with
     * {@link Events['subagent/end']}.
     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): the carrier is keyed
     * by the DELEGATING PARENT — a listener registered through the parent's
@@ -97,8 +100,10 @@ declare module 'cordis' {
     */
    'subagent/start'(this: Scoped<SubagentService>, info: SubagentRunInfo): void
    /**
-     * A subagent run settled — emitted when {@link SubagentRun.result}
-     * resolves (any stop reason). Paired with {@link Events['subagent/start']}.
+     * A started subagent run settled — emitted when {@link SubagentRun.result}
+     * resolves (any stop reason) or rejects (reported as `error`). Paired with
+     * {@link Events['subagent/start']}; a run whose readiness rejected emits
+     * neither event.
     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): the carrier is keyed
     * by the DELEGATING PARENT — a listener registered through the parent's
     * `agent.ctx` observes only its own delegations; a plain plugin listener
@@ -161,21 +166,43 @@ export class SubagentService extends Service {

  /**
   * Register a provider under its `provider.name`. Throws {@link SubagentError}
-   * (`DUPLICATE_PROVIDER`) if the name is already taken. Effect-scoped: disposed
-   * with the calling fiber (HMR-safe). Emits `subagent/provider-added` after
-   * the registration and `subagent/provider-removed` on unregistration, so
-   * consumers can mirror provider lifecycle instead of assuming load order.
+   * (`DUPLICATE_PROVIDER`) if the name is already taken. The registry snapshots
+   * the name, static descriptors, and `start` callback identity at acceptance;
+   * later caller mutation cannot change lookup, capability validation, consumer
+   * wording, dispatch, or HMR cleanup. The callback remains bound to the
+   * original provider object, so provider-owned mutable state stays live.
+   * Effect-scoped: disposed with the calling fiber (HMR-safe). Emits
+   * `subagent/provider-added` after the registration and
+   * `subagent/provider-removed` on unregistration, so consumers can mirror
+   * provider lifecycle instead of assuming load order.
   * @param provider - the provider; its `name` is the registry key.
   * @returns the disposer that unregisters the provider. The exact
   *   Cordis effect disposer (single-shot): composite (generator) effects may
   *   yield it directly — exact identity nests the teardown in order.
   */
  registerProvider(provider: SubagentProvider): () => Promise<void> | void {
+    // Snapshot the accepted registration contract before entering the effect.
+    // Cleanup must never re-read caller-owned `provider.name`: an HMR host may
+    // mutate or reuse the provider object before its old fiber unloads. Binding
+    // preserves the provider method's receiver while making replacement of the
+    // public callback field after registration inert.
+    const capabilities: SubagentCapabilities = Object.freeze({
+      outputSchema: provider.capabilities.outputSchema,
+      depthLimit: provider.capabilities.depthLimit,
+      toolFilter: provider.capabilities.toolFilter,
+      persona: provider.capabilities.persona,
+    })
+    const snapshot: SubagentProvider = Object.freeze({
+      name: provider.name,
+      capabilities,
+      inheritsParentContext: provider.inheritsParentContext,
+      start: provider.start.bind(provider),
+    })
    const dispose = this.ctx.effect(function* (this: SubagentService) {
-      if (this.providers.has(provider.name)) {
-        throw new SubagentError(`a subagent provider named "${provider.name}" is already registered`, 'DUPLICATE_PROVIDER')
+      if (this.providers.has(snapshot.name)) {
+        throw new SubagentError(`a subagent provider named "${snapshot.name}" is already registered`, 'DUPLICATE_PROVIDER')
      }
-      this.providers.set(provider.name, provider)
+      this.providers.set(snapshot.name, snapshot)
      // Yield the rollback BEFORE emitting `subagent/provider-added`: a
      // throwing added-listener then unregisters the provider (and announces
      // the removal) instead of leaking it into the registry. The removal
@@ -183,10 +210,10 @@ export class SubagentService extends Service {
      // it runs inside this disposer, where a propagating subscriber would
      // disrupt the backend fiber's teardown and starve later mirrors.
      yield () => {
-        this.providers.delete(provider.name)
-        this.emitLifecycle('subagent/provider-removed', provider.name)
+        this.providers.delete(snapshot.name)
+        this.emitLifecycle('subagent/provider-removed', snapshot.name)
      }
-      this.ctx.emit('subagent/provider-added', provider)
+      this.ctx.emit('subagent/provider-added', snapshot)
    }.bind(this), 'subagents.registerProvider()')
    // The EXACT cordis effect disposer, not a wrapper: a composite (generator)
    // effect that owns a teardown ORDER must be able to yield THIS function —
@@ -198,9 +225,10 @@ export class SubagentService extends Service {
  }

  /**
-   * Look up a registered provider by name (`undefined` if absent).
-   * @param name - the provider name as registered.
-   * @returns the provider, or undefined when the name is unknown.
+   * Look up the registry's frozen provider snapshot by its accepted name
+   * (`undefined` if absent).
+   * @param name - the provider name accepted at registration.
+   * @returns the frozen acceptance snapshot, or undefined when the name is unknown.
   */
  getProvider(name: string): SubagentProvider | undefined {
    return this.providers.get(name)
@@ -219,8 +247,9 @@ export class SubagentService extends Service {
   * `NO_PROVIDER` if absent), validates every requested START-TIME capability
   * against {@link SubagentProvider.capabilities} (throws `UNSUPPORTED_CAPABILITY`
   * for the first unmet one — fail loud, before any child is created), then
-   * delegates to {@link SubagentProvider.start} and emits `subagent/start` /
-   * `subagent/end` around the run.
+   * delegates to {@link SubagentProvider.start}, then emits `subagent/start` /
+   * `subagent/end` only after the run's readiness boundary fulfills. A provider
+   * that fails before establishing a child emits neither event.
   * @param name - the provider to run on.
   * @param request - the child's prompt, capabilities, and options.
   * @returns the live run (its `result` resolves when the child settles).
@@ -252,46 +281,63 @@ export class SubagentService extends Service {
      ...request.persona !== undefined ? { persona: request.persona } : {},
    }
    const run = provider.start(accepted)
-    // Emit `subagent/start` with PER-LISTENER containment (see {@link emitLifecycle}):
-    // the run is already live, so neither a throwing subscriber escaping
-    // `start()` (the caller would never receive the run to dispose it — a leaked
-    // child) NOR one bad subscriber starving the listeners after it is
-    // acceptable. `ctx.emit` halts the dispatch on the first throw, so a single
-    // surrounding try/catch is not enough — each listener is invoked and
-    // contained individually.
-    this.emitLifecycle('subagent/start', { provider: name, id: run.id }, parent)
-    // Emit `subagent/end` when the run settles. The result promise does not
-    // reject on a child-level failure (it resolves with stopReason 'error'),
-    // so a rejection here is an infrastructure fault — surface its stop reason
-    // as 'error' for the telemetry event without swallowing the rejection
-    // (the consumer still observes it via `run.result`). On the resolve path the
-    // child's final output rides on the event (lastAssistantMessage); on the
-    // reject path there is no SubagentResult, so only the stop reason is known.
-    // Per-listener containment also keeps a thrown `subagent/end` listener from
-    // becoming an unhandled rejection on this detached `.then`.
+
+    // Observe result settlement IMMEDIATELY, before waiting on readiness. A
+    // provider may fail both promises in the same turn; deferring the rejection
+    // handler until `started` fulfilled would leave `result` transiently
+    // unhandled. The settled event is buffered until start has been announced,
+    // preserving start → end order even for an already-settled scripted run.
+    let readiness: 'pending' | 'started' | 'failed' = 'pending'
+    let pendingEnd: SubagentRunEndInfo | undefined
+    const deliverEnd = (info: SubagentRunEndInfo): void => {
+      if (readiness === 'started') this.emitLifecycle('subagent/end', info, parent)
+      else if (readiness === 'pending') pendingEnd = info
+      // A pre-publication readiness failure has no lifecycle pair; result
+      // remains observable by the run's consumer, but telemetry must not claim
+      // that a child started.
+    }
    void run.result.then(
      (result) => {
-        // Deep-clone the output onto the event: this detached `.then` runs BEFORE
-        // the caller's own `await run.result` continuation, so handing listeners
-        // the SAME array reference the caller consumes would let a mutating
-        // `subagent/end` listener corrupt the caller's SubagentResult.output —
-        // breaking the observe-only contract. A snapshot makes the event a
-        // read-only view, not a shared handle. The clone is wrapped: it runs
-        // inside `onFulfilled`, OUTSIDE emitLifecycle's per-listener containment,
-        // so an uncloneable value (a future non-serializable content-block type,
-        // or a contract-violating result with no `output`) would otherwise become
-        // an unhandled rejection on this detached `.then`. On clone failure, log
-        // and emit the event WITHOUT lastAssistantMessage rather than dropping the
-        // whole `subagent/end`.
+        // Snapshot before the caller's own `await run.result` continuation. Even
+        // when readiness is still pending, buffering the clone rather than the
+        // caller-owned result keeps the eventual observe-only event immutable
+        // with respect to consumer mutation.
        let lastAssistantMessage: SubagentResult['output'] | undefined
        try {
          lastAssistantMessage = structuredClone(result.output)
        } catch (error: unknown) {
          this.ctx.logger.warn(`subagent: could not clone ${name} output for subagent/end: ${String(error)}`)
        }
-        this.emitLifecycle('subagent/end', { provider: name, id: run.id, stopReason: result.stopReason, ...lastAssistantMessage !== undefined ? { lastAssistantMessage } : {} }, parent)
+        deliverEnd({
+          provider: name,
+          id: run.id,
+          stopReason: result.stopReason,
+          ...lastAssistantMessage !== undefined ? { lastAssistantMessage } : {},
+        })
+      },
+      () => { deliverEnd({ provider: name, id: run.id, stopReason: 'error' }) },
+    )
+
+    // Readiness is the publication boundary owned by the provider. For
+    // in-process runs, fulfillment means the agent registry already contains
+    // `run.id`; for ACP it means the remote session exists. Emit start with
+    // per-listener containment, then flush an outcome that settled unusually
+    // early. A readiness rejection is handled here and deliberately emits no
+    // false start/end pair; the result path above remains independently handled.
+    void run.started.then(
+      () => {
+        readiness = 'started'
+        this.emitLifecycle('subagent/start', { provider: name, id: run.id }, parent)
+        if (pendingEnd !== undefined) {
+          const info = pendingEnd
+          pendingEnd = undefined
+          this.emitLifecycle('subagent/end', info, parent)
+        }
+      },
+      () => {
+        readiness = 'failed'
+        pendingEnd = undefined
      },
-      () => { this.emitLifecycle('subagent/end', { provider: name, id: run.id, stopReason: 'error' }, parent) },
    )
    return run
  }
--- a/packages/subagent/subagent/src/types.ts
+++ b/packages/subagent/subagent/src/types.ts
@@ -142,8 +142,16 @@ export interface SubagentResult {
 * presence of the method IS the capability — narrow before calling.
 */
 export interface SubagentRun {
-  /** The child agent's id (use `ctx.agents.get(id)` to reach the live child). */
+  /** The child agent's id (local in-process runs publish it in `ctx.agents`; remote transports need not). */
  readonly id: AgentId
+  /**
+   * The provider's publication/readiness boundary. Resolves only after a real
+   * child is established: an in-process agent is live in `ctx.agents`, or a
+   * remote transport has created its child session. Rejects when the attempt
+   * fails or is cancelled before that boundary. The service emits the paired
+   * `subagent/start`/`subagent/end` lifecycle only after this fulfills.
+   */
+  readonly started: Promise<void>
  /**
   * Resolves with the child's terminal {@link SubagentResult} when the run
   * settles. Does NOT reject on a child-level failure — a model/transport
@@ -176,7 +184,9 @@ export interface SubagentRun {
 * A subagent backend: one transport for running a child agent (in-process
 * spawn/fork, ACP to another process, …). Implementations register under a
 * unique name via {@link SubagentService.registerProvider}; multiple providers
- * coexist in one context (unlike the single-implementation bash seam).
+ * coexist in one context (unlike the single-implementation bash seam). The
+ * service freezes the public descriptor and callback identity at registration;
+ * the captured `start` remains bound to the original provider receiver.
 */
 export interface SubagentProvider {
  /** Unique registry name (e.g. `spawn`, `fork`, `acp`). */
@@ -194,9 +204,12 @@ export interface SubagentProvider {
   */
  readonly inheritsParentContext: boolean
  /**
-   * Start a child run. The service has already validated that every requested
-   * start-time capability is supported, so an implementation may assume e.g.
-   * `request.maxDepth` is honorable when present.
+   * Start preparing a child run and return its handle synchronously. The
+   * service has already validated that every requested start-time capability
+   * is supported, so an implementation may assume e.g. `request.maxDepth` is
+   * honorable when present. The returned {@link SubagentRun.started} must mark
+   * the real publication/readiness boundary; the result path must observe that
+   * promise immediately so a pre-start rejection cannot become unhandled.
   */
  start(request: SubagentStartRequest): SubagentRun
 }
--- a/packages/subagent/subagent/tests/service.spec.ts
+++ b/packages/subagent/subagent/tests/service.spec.ts
@@ -34,6 +34,7 @@ class StubProvider implements SubagentProvider {
    this.startCount++
    return {
      id: AgentId(`child:${this.name}:${request.parent.id}`),
+      started: Promise.resolve(),
      result: Promise.resolve(this.result),
      cancel() {},
      async dispose() {},
@@ -106,7 +107,7 @@ describe('SubagentService', () => {
    ctx.subagents.registerProvider(provider)

    expect(ctx.subagents.list()).toEqual(['alpha'])
-    expect(ctx.subagents.getProvider('alpha')).toBe(provider)
+    expect(ctx.subagents.getProvider('alpha')).toMatchObject({ name: 'alpha' })

    const run = ctx.subagents.start('alpha', baseRequest())
    expect(provider.startCount).toBe(1)
@@ -162,6 +163,75 @@ describe('SubagentService', () => {
    expect(ctx.subagents.list()).toEqual([])
  })

+  it('snapshots a provider registration so caller mutation cannot corrupt dispatch or HMR cleanup', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SubagentService)
+    const capabilities: SubagentCapabilities = {
+      outputSchema: true,
+      depthLimit: true,
+      toolFilter: true,
+      persona: true,
+    }
+    const provider = new StubProvider('stable', capabilities)
+    const added: SubagentProvider[] = []
+    const removed: string[] = []
+    ctx.on('subagent/provider-added', registered => void added.push(registered))
+    ctx.on('subagent/provider-removed', name => void removed.push(name))
+    const owner = await ctx.plugin({
+      name: 'mutable-provider-owner',
+      inject: ['subagents'],
+      apply(pluginCtx: Context) {
+        pluginCtx.subagents.registerProvider(provider)
+      },
+    })
+    const accepted = ctx.subagents.getProvider('stable')
+
+    const mutable = provider as unknown as {
+      name: string
+      capabilities: SubagentCapabilities
+      inheritsParentContext: boolean
+      start: SubagentProvider['start']
+    }
+    mutable.name = 'mutated'
+    capabilities.outputSchema = false
+    capabilities.depthLimit = false
+    capabilities.toolFilter = false
+    capabilities.persona = false
+    mutable.capabilities = NO_CAPS
+    mutable.inheritsParentContext = true
+    const replacementStart = vi.fn((_request: SubagentStartRequest): SubagentRun => {
+      throw new Error('replacement start must not run')
+    })
+    mutable.start = replacementStart
+
+    expect(added).toEqual([accepted])
+    expect(accepted).not.toBe(provider)
+    expect(Object.isFrozen(accepted)).toBe(true)
+    expect(Object.isFrozen(accepted?.capabilities)).toBe(true)
+    expect(accepted).toMatchObject({
+      name: 'stable',
+      capabilities: { outputSchema: true, depthLimit: true, toolFilter: true, persona: true },
+      inheritsParentContext: false,
+    })
+    expect(ctx.subagents.list()).toEqual(['stable'])
+    expect(ctx.subagents.getProvider('mutated')).toBeUndefined()
+
+    const run = ctx.subagents.start('stable', baseRequest({
+      outputSchema: { type: 'object', properties: { answer: { type: 'string' } } },
+      maxDepth: 2,
+      toolFilter: { deny: ['bash'] },
+      persona: 'reviewer',
+    }))
+    await expect(run.result).resolves.toMatchObject({ stopReason: 'completed' })
+    expect(provider.startCount).toBe(1)
+    expect(replacementStart).not.toHaveBeenCalled()
+
+    await owner.dispose()
+    expect(removed).toEqual(['stable'])
+    expect(ctx.subagents.list()).toEqual([])
+    expect(() => ctx.subagents.registerProvider(new StubProvider('stable'))).not.toThrow()
+  })
+
  it('re-registers a name after its prior registration is disposed (not wedged)', async () => {
    const ctx = new Context()
    await ctx.plugin(SubagentService)
@@ -220,6 +290,7 @@ describe('SubagentService', () => {
    ctx.on('subagent/end', ended)

    const run = ctx.subagents.start('events', baseRequest())
+    await run.started
    expect(started).toHaveBeenCalledWith(expect.objectContaining({ provider: 'events', id: run.id }))

    await run.result
@@ -228,6 +299,67 @@ describe('SubagentService', () => {
    expect(ended).toHaveBeenCalledWith(expect.objectContaining({ provider: 'events', id: run.id, stopReason: 'completed' }))
  })

+  it('waits for provider readiness and observes an early result rejection without reordering lifecycle', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SubagentService)
+    const readiness = Promise.withResolvers<undefined>()
+    ctx.subagents.registerProvider({
+      name: 'delayed-start',
+      capabilities: NO_CAPS,
+      inheritsParentContext: false,
+      start: () => ({
+        id: AgentId('delayed-child'),
+        started: readiness.promise,
+        // Already rejected: SubagentService must attach its result handler in
+        // the same synchronous start() call, before awaiting readiness.
+        result: Promise.reject(new Error('early infrastructure fault')),
+        cancel() {},
+        async dispose() {},
+      }),
+    })
+    const lifecycle: string[] = []
+    ctx.on('subagent/start', () => void lifecycle.push('start'))
+    ctx.on('subagent/end', info => void lifecycle.push(`end:${info.stopReason}`))
+
+    const run = ctx.subagents.start('delayed-start', baseRequest())
+    await expect(run.result).rejects.toThrow('early infrastructure fault')
+    expect(lifecycle).toEqual([])
+
+    readiness.resolve(undefined)
+    await run.started
+    expect(lifecycle).toEqual(['start', 'end:error'])
+  })
+
+  it('emits no lifecycle pair when readiness rejects before a child exists', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SubagentService)
+    const readiness = Promise.withResolvers<undefined>()
+    const result = Promise.withResolvers<SubagentResult>()
+    ctx.subagents.registerProvider({
+      name: 'never-started',
+      capabilities: NO_CAPS,
+      inheritsParentContext: false,
+      start: () => ({
+        id: AgentId('never-started-child'),
+        started: readiness.promise,
+        result: result.promise,
+        cancel() {},
+        async dispose() {},
+      }),
+    })
+    const lifecycle = vi.fn()
+    ctx.on('subagent/start', lifecycle)
+    ctx.on('subagent/end', lifecycle)
+
+    const run = ctx.subagents.start('never-started', baseRequest())
+    readiness.reject(new Error('publication rolled back'))
+    await expect(run.started).rejects.toThrow('publication rolled back')
+    result.resolve({ output: [], stopReason: 'aborted' })
+    await run.result
+    await Promise.resolve()
+    expect(lifecycle).not.toHaveBeenCalled()
+  })
+
  it('pins start and end to the parent accepted at start despite caller mutation', async () => {
    const ctx = new Context()
    await ctx.plugin(SubagentService)
@@ -241,6 +373,7 @@ describe('SubagentService', () => {
        acceptedRequest = accepted
        return {
          id: AgentId('deferred-child'),
+          started: Promise.resolve(),
          result: gate.promise,
          cancel() {},
          async dispose() {},
@@ -282,6 +415,7 @@ describe('SubagentService', () => {
    ctx.on('subagent/end', ended)

    const run = ctx.subagents.start('enriched', baseRequest())
+    await run.started
    expect(started).toHaveBeenCalledWith(expect.objectContaining({ provider: 'enriched', id: run.id }))

    await run.result
@@ -331,6 +465,7 @@ describe('SubagentService', () => {
      inheritsParentContext: false,
      start: () => ({
        id: AgentId('rej-child'),
+        started: Promise.resolve(),
        result: Promise.reject(new Error('infra fault')),
        cancel() {},
        dispose: async () => {},
@@ -365,6 +500,7 @@ describe('SubagentService', () => {
      inheritsParentContext: false,
      start: () => ({
        id: AgentId('unclone-child'),
+        started: Promise.resolve(),
        result: Promise.resolve({ output: uncloneable, stopReason: 'completed' } as SubagentResult),
        cancel() {},
        dispose: async () => {},
@@ -395,6 +531,7 @@ describe('SubagentService', () => {
      inheritsParentContext: false,
      start: () => ({
        id: AgentId('rej-child'),
+        started: Promise.resolve(),
        result: Promise.reject(new Error('infra fault')),
        cancel() {},
        dispose: async () => {},
@@ -424,6 +561,7 @@ describe('SubagentService', () => {

    const run = ctx.subagents.start('contain', baseRequest())
    expect(run.id).toBeDefined()
+    await run.started
    expect(second).toHaveBeenCalledWith(expect.objectContaining({ provider: 'contain', id: run.id }))
    await expect(run.result).resolves.toMatchObject({ stopReason: 'completed' })
  })